HyperScript
Docs

← All of the Docs Players

Players

effectheal <who> / feed <who>since 1.5.8

Full health (and no longer burning) / a full hunger bar

heal player
feed player
Try it
expressionhealth of <who>since 1.5.8

Health in half hearts; 20 is ten hearts. Setting it to 0 kills

if health of player < 6:
    send "&cYou are badly hurt!"
Try it
expressionmax health of <who>since 1.5.8

The most health they can have

set max health of player to 40
Try it
expressionfood of <who>since 1.5.8

Hunger, 0 to 20

set food of player to 20
Try it
expressionlevel of <who>since 1.5.8

Experience level

add 5 to level of player
Try it
expressiongamemode of <who>since 1.5.8

survival, creative, adventure or spectator

set gamemode of player to creative
Try it
expressionflight of <who>since 1.5.8

Whether they may fly: true or false

set flight of player to true
Try it
effectapply <effect> [<level>] to <who> [for <duration>]since 1.5.8

Give a potion effect; level 1 and 30 seconds unless said otherwise

apply speed 2 to player for 30 seconds
Try it
effectclear effects of <who> / clear <effect> effect of <who>since 1.5.8

Take every effect away, or one

clear effects of player
clear speed effect of player
Try it
effectignite <who> [for <duration>] / extinguish <who>since 1.5.8

Set on fire (5 seconds unless said otherwise), or put out

ignite arg.1 for 3 seconds
extinguish player
Try it
effectfreeze <who> / unfreeze <who>since 1.5.8

Hold a player in place; they can still look around

freeze arg.1
send "&cYou have been frozen." to arg.1
Try it
expressionrespawn <who>since 1.7.1

Bring a dead player back at once, skipping the death screen

on player death:
    wait 1 tick
    respawn player
Try it
expressionshow <who> a book titled <text> with pages <text>, <text>since 1.7.1

Open a book on their screen; nothing is put in their inventory

show player a book titled "Rules" with pages "&lRules\n\n1. Be kind.", "2. No griefing."
Try it
effecthide <who> from tab list of <who>since 1.7.42

Take a player off the list another player sees when they hold Tab. They are still seen in the world; only the list changes. Needs a Paper server, 1.20 or newer

hide player from tab list of arg.1
Try it
expressionshow <who> in tab list of <who>since 1.7.42

Put them back on it. show <who> from tab list of <who> means the same

show player in tab list of arg.1
Try it
effectset <who>'s yaw to <number>since 1.7.42

Turn them left or right: the same as set yaw of <who> to. 0 is south, 90 west, 180 north, -90 east

set player's yaw to -90
Try it
effectset <who>'s pitch to <number>since 1.7.42

Make them look up or down: the same as set pitch of <who> to. -90 is straight up, 90 straight down

set player's pitch to 0
Try it
effecthide <who> from <who> / show <who> to <who>since 1.7.1

Make one player invisible to another, or visible again

hide player from arg.1
send "&7%arg.1% can no longer see you."
Try it
effectclear title of <who>since 1.7.1

Remove a title from the screen

clear title of player
Try it
expressiontab name of <who>since 1.7.1

Their name in the tab list; settable

set tab name of player to "&6[VIP] &f%player.name%"
Try it
expressionfree slots of <who>since 1.7.1

How many of their inventory slots are empty

if free slots of player < 3:
    send "&eYour inventory is nearly full."
Try it
expressionping of <who>since 1.7.1

Their connection delay in milliseconds. Unset on servers older than 1.17, where %player.ping% still works

send "&7Ping of %arg.1%: &f" + ping of arg.1
Try it
effectsend toast <text> [with icon <item>] [as goal] [to <who>]since 1.7.2

The pop-up in the top corner that advancements use. as task (the default), as goal or as challenge picks the frame and sound

send toast "&aQuest complete!" with icon diamond as challenge to player
Try it
effectgive head of <name> to <who>since 1.7.2

A player head wearing that player's skin

on player kill:
    give head of victim to player
Try it
effectset item cooldown of <item> for <who> to <duration>since 1.7.2

Grey out an item so it cannot be used for a while, as ender pearls are. item cooldown of <item> for <who> reads what is left

on right click:
    if event.item is "blaze_rod":
        if item cooldown of blaze rod for player > 0 seconds:
            stop
        set item cooldown of blaze rod for player to 5 seconds
        strike lightning at target block of player
Try it
effectstop sound <name> [for <who>] / stop all sounds [for <who>]since 1.7.2

Cut a sound short. stop all sounds needs Minecraft 1.17 or newer

stop sound "music_disc.cat" for player
Try it
expressionlocation of <who>since 1.7.3

Where another player is, as a location; for the player of the trigger, player's location

if distance between player's location and location of arg.1 > 10:
    send "&c%arg.1% is too far away."
Try it
expressionyaw from <location> to <location>since 1.7.55

Which way to turn at the first place to face the second, as the game counts it: 0 is south, 90 west

set {_way} to yaw from player's location to {spawn}
set player's yaw to {_way}
Try it
expressionpitch from <location> to <location>since 1.7.55

How far to look up or down: below nothing is up

set {_tilt} to pitch from player's location to {spawn}
set player's pitch to {_tilt}
Try it
expression<location> moved <n> blocks towards <location>since 1.7.55

The place that far along the way from one to the other; never beyond it

set {_step} to player's location moved 3 blocks towards {spawn}
teleport player to {_step}
Try it
expression<who>'s locationsince 1.7.7

The same, written after the player: loop-player's location, arg.1's location, {_name}'s location

loop all players:
    draw particle circle with radius 2 using particle "flame" at loop-player's location
Try it
expressionabsorption of <who>since 1.7.2

Their golden extra hearts, in half hearts; settable

set absorption of player to 8
Try it
expressionprotocol version of <who>since 1.7.2

The number of the game version their client speaks, e.g. 754 for 1.16.5. Asked from ViaVersion if it is installed, otherwise from Paper; unset on plain Spigot

if protocol version of player < 765:
    send "&eYou are on an old version; some things may look different."
Try it
expressionclient brand of <who>since 1.7.2

What their game calls itself: vanilla, fabric, forge. Paper only

log "%player.name% plays with " + client brand of player
Try it
expressionask <who> <text> into <variable>since 1.7.3

Ask a question and wait for the answer. The next thing the player says in chat is the answer and nobody else sees it. Add for at most 30 seconds to change how long to wait (a minute by default); with no answer the variable is unset

command /clan <action>:
    trigger:
        ask player "&eWhat should your clan be called?" into {_name} for at most 30 seconds
        if {_name} is not set:
            send "&cToo slow."
            stop
        send "&aClan %{_name}% created."
Try it
expressionask <who> <text> as number into <variable>since 1.7.60

The same, for an amount: an answer that is no number is said to be none and the question asked again. 1.5k counts

command /deposit:
    trigger:
        ask player "&eHow much?" as number into {_amount}
        if {_amount} is set:
            add {_amount} to {%player%.bank}
Try it
expressionask <who> <text> with options <text>, <text> into <variable>since 1.7.3

The same, with answers to click on. Typing one in chat works too

ask player "&ePick a team:" with options "Red", "Blue" into {_team}
if {_team} is set:
    add player to team lowercase {_team}
Try it
expressionask <who> <text> with anvil into <variable>since 1.7.23

The question opens as an anvil with a box to type in; what the player types and takes out is the answer. Good inside menus, where chat is out of the way. The question stands on top of the window and the box starts empty, so the answer is simply typed; on an older server, where the question has to stand in the box, it is taken off the answer if it was left there. Needs a Paper server; elsewhere the question is asked in chat. Closing the anvil gives an empty answer

command /pet:
    players only: true
    trigger:
        ask player "Name your pet" with anvil into {_name}
        if {_name} is "":
            send "&7Maybe later."
            stop
        set {%player%.pet} to {_name}
        send "&aYour pet is called %{_name}%."
Try it
structureconfirm <text>:since 1.7.3

Ask yes or no; the block runs only if the player answers yes. confirm <text> for <who>: asks someone else

command /delhome:
    trigger:
        confirm "&cDelete your home? This cannot be undone.":
            delete {%player%.home}
            send "&eHome deleted."
Try it
expressionitems in ender chest of <who>since 1.7.3

A list of the items in their ender chest

send "&7Your ender chest holds " + size of (items in ender chest of player) + " stack(s)."
Try it
expressionitems in inventory of <who>since 1.7.57

A list of the items they carry, without the armour and the other hand

command /carrying:
    trigger:
        loop items in inventory of player:
            send "&7%loop-index%. &f%loop-value%"
        else:
            send "&7You carry nothing."
Try it
effectadd <item> to ender chest of <who> / clear ender chest of <who>since 1.7.3

Put items in an ender chest, or empty it

add 3 diamond to ender chest of player
send "&bA gift is waiting in your ender chest."
Try it
effectmake <who> say <text>since 1.7.0

Send a chat message, or run a command if it starts with /, as that player

make player say "I love this server!"
Try it
effectopen workbench for <who> / open enderchest for <who>since 1.7.0

Show a crafting grid or their ender chest

open workbench for player
Try it
expressionfly speed of <who> / walk speed of <who>since 1.7.0

From -1 to 1; the usual values are 0.1 for flying and 0.2 for walking

set walk speed of player to 0.4
Try it
expressiontool durability of <who>since 1.7.70

How many uses the thing in their hand has left; unset for what does not wear out. set tool durability of player to 50 sets it

set {_left} to tool durability of player
if {_left} is set and {_left} < 20:
    send "&cYour tool is about to break."
Try it
effectset time of <who> to <ticks>since 1.7.70

The time of day that player sees, standing still, whatever the world's clock says: 1000 day, 6000 noon, 13000 night, 18000 midnight. Nobody else sees it. reset time of <who> gives them the world's own again

command /midnight:
    trigger:
        set time of player to 18000

command /daylight:
    trigger:
        reset time of player
Try it
effectset weather of <who> to rainsince 1.7.70

The weather that player sees: rain or clear. reset weather of <who> gives them the world's own again

set weather of player to rain
wait 30 seconds
reset weather of player
Try it
expressionsaturation of <who> / air of <who>since 1.7.0

Hidden hunger reserve; seconds of breath left (15 is full)

if air of player < 3:
    send "&cYou are running out of breath!"
Try it
expressionheld slot of <who>since 1.7.0

The selected hotbar slot, 1 to 9

set held slot of player to 1
Try it
expressioncompass target of <who>since 1.7.27

Where their compass points

set compass target of player to {spawn}
Try it
expressionbed location of <who>since 1.7.27

Where they respawn; unset without a bed. Change it with set bed spawn of <who> to <location>

command /bed:
    players only: true
    trigger:
        if bed location of player is not set:
            send "&7You have not slept in a bed yet."
            stop
        teleport player to bed location of player
Try it
expressionyaw of <who> / pitch of <who> / direction of <who>since 1.7.0

Which way they face; direction is north, east, south or west

send "&7You are facing &f" + direction of player
Try it
expressiongame version of <who>since 1.7.20

What their game calls its version, e.g. 1.21.4, for servers that let several versions in. From the number in protocol version of; one the list does not know yet comes as protocol <n>

on player join:
    if game version of player is not "1.21.4":
        send "&eYou are on %game version of player%. Some things look best on 1.21.4."
Try it
expressionip of <who> / locale of <who>since 1.7.0

Their address and game language, e.g. en_us

log "%player.name% uses the language " + locale of player
Try it
expressiontime played of <who>since 1.7.0

Total time on the server, as a duration

send "&7Played: &f" + time played of player
Try it
expressionfall distance of <who>since 1.7.0

How far they have fallen so far

if fall distance of player > 20:
    send "&cBrace yourself!"
Try it
effectvanish <who> / unvanish <who>since 1.5.8

Hide a player from everyone else, or show them again

vanish player
send "&7Nobody can see you now."
Try it
condition<who> has effect <effect> / does not have effect <effect>since 1.5.8

They have that potion effect

if player has effect speed:
    send "&bYou are fast."
Try it
condition<who> is frozen / is vanished / is flyingsince 1.5.8

As it says; is not works too

if arg.1 is frozen:
    send "&7%arg.1% is frozen."
Try it
condition<who> is falling / is glidingsince 1.7.70

Coming down through the air, or flying with an elytra

if player is falling:
    send action bar "&7Mind the landing." to player
Try it
Guide and examples

What a player is like right now can be read and changed.

command /heal:
    permission: "staff.heal"
    trigger:
        heal player
        feed player
        send "&aYou feel much better."

on player join:
    if level of player < 5:
        apply speed 1 to player for 2 minutes
        send "&7A little speed boost for a new player."
SyntaxMeaning
heal <who> / feed <who>Full health (and no longer burning) / a full hunger bar
health of <who>Health in half hearts; 20 is ten hearts. Setting it to 0 kills
max health of <who>The most health they can have
food of <who>Hunger, 0 to 20
level of <who>Experience level
gamemode of <who>survival, creative, adventure or spectator
flight of <who>Whether they may fly: true or false
apply <effect> [<level>] to <who> [for <duration>]Give a potion effect; level 1 and 30 seconds unless said otherwise
clear effects of <who> / clear <effect> effect of <who>Take every effect away, or one
ignite <who> [for <duration>] / extinguish <who>Set on fire (5 seconds unless said otherwise), or put out
freeze <who> / unfreeze <who>Hold a player in place; they can still look around
respawn <who>Bring a dead player back at once, skipping the death screen
show <who> a book titled <text> with pages <text>, <text>Open a book on their screen; nothing is put in their inventory
hide <who> from tab list of <who>Take a player off the list another player sees when they hold Tab. They are still seen in the world; only the list changes. Needs a Paper server, 1.20 or newer
show <who> in tab list of <who>Put them back on it. show <who> from tab list of <who> means the same
set <who>'s yaw to <number>Turn them left or right: the same as set yaw of <who> to. 0 is south, 90 west, 180 north, -90 east
set <who>'s pitch to <number>Make them look up or down: the same as set pitch of <who> to. -90 is straight up, 90 straight down
hide <who> from <who> / show <who> to <who>Make one player invisible to another, or visible again
clear title of <who>Remove a title from the screen
tab name of <who>Their name in the tab list; settable
free slots of <who>How many of their inventory slots are empty
ping of <who>Their connection delay in milliseconds. Unset on servers older than 1.17, where %player.ping% still works
send toast <text> [with icon <item>] [as goal] [to <who>]The pop-up in the top corner that advancements use. as task (the default), as goal or as challenge picks the frame and sound
give head of <name> to <who>A player head wearing that player's skin
set item cooldown of <item> for <who> to <duration>Grey out an item so it cannot be used for a while, as ender pearls are. item cooldown of <item> for <who> reads what is left
stop sound <name> [for <who>] / stop all sounds [for <who>]Cut a sound short. stop all sounds needs Minecraft 1.17 or newer
location of <who>Where another player is, as a location; for the player of the trigger, player's location
yaw from <location> to <location>Which way to turn at the first place to face the second, as the game counts it: 0 is south, 90 west
pitch from <location> to <location>How far to look up or down: below nothing is up
<location> moved <n> blocks towards <location>The place that far along the way from one to the other; never beyond it
<who>'s locationThe same, written after the player: loop-player's location, arg.1's location, {_name}'s location
absorption of <who>Their golden extra hearts, in half hearts; settable
protocol version of <who>The number of the game version their client speaks, e.g. 754 for 1.16.5. Asked from ViaVersion if it is installed, otherwise from Paper; unset on plain Spigot
client brand of <who>What their game calls itself: vanilla, fabric, forge. Paper only
ask <who> <text> into <variable>Ask a question and wait for the answer. The next thing the player says in chat is the answer and nobody else sees it. Add for at most 30 seconds to change how long to wait (a minute by default); with no answer the variable is unset
ask <who> <text> as number into <variable>The same, for an amount: an answer that is no number is said to be none and the question asked again. 1.5k counts
ask <who> <text> with options <text>, <text> into <variable>The same, with answers to click on. Typing one in chat works too
ask <who> <text> with anvil into <variable>The question opens as an anvil with a box to type in; what the player types and takes out is the answer. Good inside menus, where chat is out of the way. The question stands on top of the window and the box starts empty, so the answer is simply typed; on an older server, where the question has to stand in the box, it is taken off the answer if it was left there. Needs a Paper server; elsewhere the question is asked in chat. Closing the anvil gives an empty answer
confirm <text>:Ask yes or no; the block runs only if the player answers yes. confirm <text> for <who>: asks someone else
items in ender chest of <who>A list of the items in their ender chest
items in inventory of <who>A list of the items they carry, without the armour and the other hand
add <item> to ender chest of <who> / clear ender chest of <who>Put items in an ender chest, or empty it
make <who> say <text>Send a chat message, or run a command if it starts with /, as that player
open workbench for <who> / open enderchest for <who>Show a crafting grid or their ender chest
fly speed of <who> / walk speed of <who>From -1 to 1; the usual values are 0.1 for flying and 0.2 for walking
tool durability of <who>How many uses the thing in their hand has left; unset for what does not wear out. set tool durability of player to 50 sets it
set time of <who> to <ticks>The time of day that player sees, standing still, whatever the world's clock says: 1000 day, 6000 noon, 13000 night, 18000 midnight. Nobody else sees it. reset time of <who> gives them the world's own again
set weather of <who> to rainThe weather that player sees: rain or clear. reset weather of <who> gives them the world's own again
saturation of <who> / air of <who>Hidden hunger reserve; seconds of breath left (15 is full)
held slot of <who>The selected hotbar slot, 1 to 9
compass target of <who>Where their compass points
bed location of <who>Where they respawn; unset without a bed. Change it with set bed spawn of <who> to <location>
yaw of <who> / pitch of <who> / direction of <who>Which way they face; direction is north, east, south or west
game version of <who>What their game calls its version, e.g. 1.21.4, for servers that let several versions in. From the number in protocol version of; one the list does not know yet comes as protocol <n>
ip of <who> / locale of <who>Their address and game language, e.g. en_us
time played of <who>Total time on the server, as a duration
fall distance of <who>How far they have fallen so far
vanish <who> / unvanish <who>Hide a player from everyone else, or show them again

The ones written <something> of <who> are values: read them, set them, and add to or subtract from the numeric ones.

set gamemode of player to creative
set flight of arg.1 to true
add 5 to level of player
subtract 4 from health of player
if health of player < 6:
    send "&cYou are badly hurt!"
ConditionTrue when
<who> has effect <effect> / does not have effect <effect>They have that potion effect
<who> is frozen / is vanished / is flyingAs it says; is not works too
<who> is falling / is glidingComing down through the air, or flying with an elytra
  • Effects are Minecraft's own names written as words: speed, jump boost, night vision, regeneration, slowness, invisibility and so on. They are checked when the script loads.
  • Giving an effect a player already has replaces it, so a shorter one really is shorter.
  • freeze and vanish last until they are undone or the player logs out. Someone who joins while a player is vanished does not see them.
  • All of these need the player to be online. For an offline player the values are unset and the statements do nothing.