Built-in placeholders

expression%server.version%since 1.5.4

Minecraft version, e.g. 1.20.4 · text

send "&7Server %server.version% | TPS %server.tps% | Online %server.online_players%"

Try it

expression%server.tps%since 1.5.4

Recent ticks per second, 2 decimals, max 20 · number

send "TPS is %server.tps% and your ping is %player.ping% ms"

Try it

expression%server.online_players%since 1.5.4

Players online · number

set {_players} to server.online_players

Try it

expression%server.max_players%since 1.5.4

Player slot limit · number

send "&7%server.online_players% of %server.max_players% players online"

Try it

expression%server.players%since 1.5.4

Names of the players online · list

set {_online} to server.players

Try it

expression%server.time%since 1.5.4

The current time as seconds since 1970, for timestamps · number

set {%player%.last_seen} to server.time

Try it

expression%server.worlds%since 1.7.0

The names of the loaded worlds · list

for each {_world} in server.worlds:
    send "&7 - &f%{_world}%"

Try it

expression%server.operators%, %server.banned%, %server.whitelist%since 1.7.0

Names of operators, banned and whitelisted players · list

send "&7Operators: &f%server.operators%"

Try it

expression%server.plugins%since 1.7.0

The names of the installed plugins · list

send "&7Plugins: &f%server.plugins%"

Try it

expression%server.uptime%since 1.7.0

How long the server has been running · duration

send "&7The server has been up for &f%server.uptime%"

Try it

expression%server.memory_used%, %server.memory_max%since 1.7.0

Memory in megabytes · number

send "&7Memory: &f%server.memory_used% &7of &f%server.memory_max% &7MB"

Try it

expression%server.date%since 1.5.9

Today's date, e.g. 2026-10-11 · text

log "Backup finished on %server.date% at %server.clock%"

Try it

expression%server.clock%since 1.5.9

The time of day, e.g. 18:30 · text

send "&7Server time: &f%server.clock%"

Try it

expression%server.weekday%since 1.5.9

The day of the week in lower case, e.g. sunday · text

if server.weekday is "saturday":
    send "&6Double coins today!"

Try it

expression%server.hour%, %server.minute%since 1.5.9

The hour (0 to 23) and the minute, as numbers · number

if server.hour >= 22:
    send "&7It is late. Good night!"

Try it

expression%player.name%since 1.5.4

Player name · text

log "%player.name% left"

Try it

expression%player.uuid%since 1.5.4

Player UUID · text

set {_path} to "plugins/HyperScript/notes/%player.uuid%.txt"

Try it

expression%player.ping%since 1.5.4

Latency in ms (-1 if unavailable) · number

send "TPS is %server.tps% and your ping is %player.ping% ms"

Try it

expression%player.health%since 1.5.4

Health, 1 decimal (20 = full by default) · number

if player.health < 6:
    send "&cYou are badly hurt!"

Try it

expression%player.world%since 1.5.4

Name of the world the player is in · text

set time in world "%player.world%" to 1000

Try it

expression%player.gamemode%since 1.5.4

survival, creative, adventure or spectator · text

send "&bWorld &f%player.world% &7| &bMode &f%player.gamemode% &7| &bHealth &f%player.health%"

Try it

expression%player.x%, %player.y%, %player.z%since 1.5.4

Position, 2 decimals · number

set {%player%.home.x} to player.x

Try it

expression%arg.1%, %arg.2%, ...since 1.5.4

Command argument by position · text

freeze arg.1

Try it

expression%args%since 1.5.4

All command arguments joined by spaces · text

send "&7You typed: %args%"

Try it

expression%args.count%since 1.5.4

Number of command arguments · number

if args.count > 0:
    set file at {_path} to args
    send "&aNote saved."

Try it

expression%event.message%since 1.5.4

Chat message (on player chat) · text

set chat format to "&7%player.name% &8>> &f%event.message%"

Try it

expression%event.block%since 1.5.4

Block type, e.g. diamond_ore (on block break, on right click) · text

if event.block contains "ore":
    set {_reward} to {_reward} * 5

Try it

expression%event.power%since 1.7.63

The redstone power a block has now, 0 to 15 (on redstone) · number

if event.power > 0:
    log "A lamp was lit at %event's location%"

Try it

expression%event.item%since 1.5.4

Held item type, e.g. compass (on right click) · text

add 1 to {smelted.%event.item%}

Try it

expression%event.entity%since 1.5.4

Entity type, e.g. zombie (on entity death) · text

send "&aYou tamed a %event.entity%!"

Try it

expression%event.killer%since 1.5.4

Name of the killing player (on entity death) · text

set death message to "&c%player.name% &7was defeated by &c%event.killer%"

Try it

expression%event.world%, %event.x%, %event.y%, %event.z%since 1.5.4

The block the event is about (on block break, on right click); as one value: event's location · text / number

on block break:
    log "%player.name% broke a block at %event.x%, %event.y%, %event.z% in %event.world%"

Try it

expression%discord.user%since 1.5.4

Discord user name (on discord command) · text

on discord command "/hello":
    reply "Hello, %discord.user%!"

Try it

expression%discord.user_id%since 1.5.4

Discord user ID (on discord command) · text

set {link.discord.%{_player}%} to discord.user_id

Try it

expression%discord.channel%since 1.5.4

Discord channel name (on discord command) · text

on discord command "/where":
    reply "You are in #%discord.channel%"

Try it

Guide and examples

Placeholders are read-only live values that HyperScript provides, such as the player's name or the server's TPS. They are written in two ways, depending on where they stand:

Where	Written	Example
In code	The plain name	`if player.health < 6:`
Inside text	The name between percent signs	`send "Hello %player.name%!"`

Braces are never used for placeholders. {...} always means a variable of your own; see Variables.

Placeholder	Value	Type
`%server.version%`	Minecraft version, e.g. `1.20.4`	text
`%server.tps%`	Recent ticks per second, 2 decimals, max 20	number
`%server.online_players%`	Players online	number
`%server.max_players%`	Player slot limit	number
`%server.players%`	Names of the players online	list
`%server.time%`	The current time as seconds since 1970, for timestamps	number
`%server.worlds%`	The names of the loaded worlds	list
`%server.operators%`, `%server.banned%`, `%server.whitelist%`	Names of operators, banned and whitelisted players	list
`%server.plugins%`	The names of the installed plugins	list
`%server.uptime%`	How long the server has been running	duration
`%server.memory_used%`, `%server.memory_max%`	Memory in megabytes	number
`%server.date%`	Today's date, e.g. `2026-10-11`	text
`%server.clock%`	The time of day, e.g. `18:30`	text
`%server.weekday%`	The day of the week in lower case, e.g. `sunday`	text
`%server.hour%`, `%server.minute%`	The hour (0 to 23) and the minute, as numbers	number
`%player.name%`	Player name	text
`%player.uuid%`	Player UUID	text
`%player.ping%`	Latency in ms (`-1` if unavailable)	number
`%player.health%`	Health, 1 decimal (20 = full by default)	number
`%player.world%`	Name of the world the player is in	text
`%player.gamemode%`	`survival`, `creative`, `adventure` or `spectator`	text
`%player.x%`, `%player.y%`, `%player.z%`	Position, 2 decimals	number
`%arg.1%`, `%arg.2%`, ...	Command argument by position	text
`%args%`	All command arguments joined by spaces	text
`%args.count%`	Number of command arguments	number
`%event.message%`	Chat message (`on player chat`)	text
`%event.block%`	Block type, e.g. `diamond_ore` (`on block break`, `on right click`)	text
`%event.power%`	The redstone power a block has now, 0 to 15 (`on redstone`)	number
`%event.item%`	Held item type, e.g. `compass` (`on right click`)	text
`%event.entity%`	Entity type, e.g. `zombie` (`on entity death`)	text
`%event.killer%`	Name of the killing player (`on entity death`)	text
`%event.world%`, `%event.x%`, `%event.y%`, `%event.z%`	The block the event is about (`on block break`, `on right click`); as one value: `event's location`	text / number
`%discord.user%`	Discord user name (`on discord command`)	text
`%discord.user_id%`	Discord user ID (`on discord command`)	text
`%discord.channel%`	Discord channel name (`on discord command`)	text

The table lists each placeholder as it is written inside text. In code, leave the percent signs off: server.tps, arg.1, event.block. (The percent form is accepted in code as well, so %arg.1% == "on" still works.)

Two more describe the player as a whole: player is the player, for use wherever a player is expected (send "hi" to player), and inside text %player% is their name. player.location is where they stand, as a location.

Writing a placeholder in braces, as in {player.name} or %{player.name}%, is an error that says how to write it instead. That was the syntax before version 1.5.4, so scripts from older versions need those places changed.

"The player" is whoever caused the trigger: the player who joined, broke the block, ran the command, clicked the GUI slot, or, for on entity death, the killer. A placeholder with nothing to report (for example %player.name% when the console runs a command) is unset and prints as <none>.

send "TPS is %server.tps% and your ping is %player.ping% ms"
if player.health < 6:
    send "&cYou are badly hurt!"