HyperScript
Docs

← All of the Docs The basics

Conditions

condition==

Equal · player.world == "world_nether"

if size of {_names} == 0:
    send "&7There are no notes."
    stop
Try it
condition!=

Not equal · arg.1 != "off"

if args.count != 1:
    send "&cUsage: /lookup <player>"
    reset cooldown
    stop
Try it
condition> < >= <=

Numeric comparison · player.health <= 5

if {%player%.coins} >= 100:
    send "&aYou can afford it."
Try it
conditioncontains

Left text includes right text, or left list includes right value; does not contain is the opposite · message contains "help"

if {winners} contains player.name:
    send "You already won."
Try it
conditionis between <a> and <b>since 1.7.0

A number is in that range, ends included · player.y is between 0 and 64

if player.y is between 0 and 16:
    send "&bDiamond level!"
Try it
conditionis in <list>since 1.7.0

The list contains the value · arg.1 is in ["on", "off"]

if arg.1 is in ["on", "off"]:
    send "&aOK."
Try it
conditionis emptysince 1.7.0

Unset, empty text or an empty list · {queue} is empty

if {queue} is empty:
    send "&7Nobody is waiting."
Try it
conditionis a list / a location / an item / a date / an entity / a table / textsince 1.7.0

What kind of value it is · {home} is a location

if {%player%.home} is a location:
    teleport player to {%player%.home}
Try it
conditionis a playersince 1.7.0

The name of someone who is online · arg.1 is a player

if arg.1 is not a player:
    send "&c%arg.1% is not online."
Try it
conditionis alphanumericsince 1.7.0

Only letters and digits · arg.1 is alphanumeric

if arg.1 is not alphanumeric:
    send "&cUse letters and digits only."
Try it
conditionis sneaking / sprinting / swimming / blocking / sleeping / on ground / in watersince 1.7.0

What a player is doing · player is sneaking

on right click:
    if player is sneaking:
        send "&7A sneaky click."
Try it
condition<who> is [not] ridingsince 1.7.45

They sit on or in something: a horse, a boat, a minecart. vehicle of <who> is what · player is riding

if player is riding:
    set {_mount} to vehicle of player
    send "&7You are riding something."
Try it
condition<who> is [not] looking at <target>since 1.7.45

Their crosshair is on it, give or take a few degrees. The target is a location or somebody; up to 100 blocks away · player is looking at arg.1

if player is looking at arg.1:
    send "&aYou have %arg.1% in your sights."
Try it
condition<who> is [not] in biome <name>since 1.7.45

Where they stand is that biome; a location works in place of a player · player is in biome "desert"

if player is in biome "desert":
    send "&eIt is hot here."
Try it
condition<number> is [not] (even/odd)since 1.7.45

A whole number that two goes into, or does not · level of player is even

if level of player is even:
    send "&7An even level."
Try it
condition<number> is [not] divisible by <n>since 1.7.45

It can be divided by that with nothing left over · level of player is divisible by 5

if level of player is divisible by 5:
    give 1 diamond to player or drop
Try it
conditionis op / is onlinesince 1.7.0

Also true or false for someone offline · arg.1 is online

if arg.1 is online:
    send "&a%arg.1% is here."
Try it
conditionhas played beforesince 1.7.0

They have joined at least once before; has not played before is the opposite · arg.1 has played before

if arg.1 has played before:
    send "&7%arg.1% has been here."
Try it
conditionhas saved inventory <name> / does not have saved inventory <name>since 1.7.15

An inventory was put away for them with save inventory · player has saved inventory "before-arena"

on player quit:
    if player has saved inventory "before-arena":
        log "%player% left in the middle of a round"
Try it
conditionis holding <item> / is wearing <item>since 1.7.0

In either hand, or in an armour slot · player is holding diamond sword

if player is holding diamond sword:
    send "&bNice sword."
Try it
conditionis in region <name> / is not in region <name>since 1.7.14

The player is inside a region made with create region · player is in region "spawn"

on block break:
    if player is in region "spawn":
        cancel event
        send "&cNot here."
Try it
conditionis on cooldown <name> / is not on cooldown <name>since 1.7.14

A cooldown started with start cooldown is still running for them · player is on cooldown "kit"

command /kit:
    trigger:
        if player is on cooldown "kit":
            set {_left} to cooldown "kit"
            send "&cWait %{_left}%."
            stop
        start cooldown "kit" of 1 hour
        give player 16 bread
Try it
conditioncan see <player>since 1.7.0

The other player is not hidden from them · player can see arg.1

if player can see arg.1:
    send "&7You can see %arg.1%."
Try it
condition<world> is raining / is day / is nightsince 1.7.0

About a world, by name · player.world is night

if player.world is night:
    send "&7It is dark. Watch out."
Try it
condition<block> is solidsince 1.7.0

The block type can be stood on · block at {_loc} is solid

if block at (location below player's location) is solid:
    send "&7You are on firm ground."
Try it
condition<block> is liquidsince 1.7.67

It is water or lava · block at {_loc} is liquid

if block at player's location is liquid:
    send "&bYou are swimming."
Try it
condition<block> is passablesince 1.7.67

It can be walked through: air, water, grass, flowers, torches · block at {_loc} is passable

if block at (location below player's location) is passable:
    send "&7There is nothing under your feet."
Try it
condition<block> is airsince 1.7.67

Nothing is there · block at {_loc} is air

if block at (location above player's location) is air:
    send "&7Nothing above you."
Try it
conditionhas space for <item>since 1.7.1

The items would fit in the inventory · player has space for 5 diamond

if player has space for 5 diamond:
    give 5 diamond to player
else:
    send "&cYour inventory is full."
Try it
conditionis bedrock / is deadsince 1.7.1

On the Bedrock edition (through Floodgate) / dead and not yet respawned · player is bedrock

if player is bedrock:
    send "&7Bedrock players: use /menu instead of the book."
Try it
condition<a> if <condition> else <b>since 1.7.1

Not a test but a choice: one value or the other · "on" if {flag} else "off"

set {_state} to "&aon" if {%player%.pvp_on} else "&coff"
send "&7PvP is %{_state}%"
Try it
conditionstarts with / ends withsince 1.5.9

The text begins or ends with the other, ignoring case · message starts with "!"

on player chat:
    if message starts with "!":
        cancel event
        send "&7Commands start with / here."
Try it
conditionmatchessince 1.5.9

The whole text fits a regular expression · arg.1 matches "[a-z0-9_]{3,16}"

if not (arg.1 matches "[a-zA-Z0-9_]{3,16}"):
    send "&cThat is not a valid name."
Try it
conditionchance of <n>%since 1.5.9

True about that often, at random · if chance of 25%:

on block break:
    if chance of 5%:
        give 1 diamond to player
        send "&bLucky find!"
Try it
conditionchance of <n>%:since 1.7.45

The same as a block of its own: its lines run about that often. An if chance of <n>%: without the if; use the if when there is an else · chance of 10%:

on block break:
    chance of 10%:
        give player 1 emerald
        send "&aLucky!"
Try it
conditionhas <item>since 1.5.6

The player's inventory holds at least that many · player has 5 diamond

if player has 5 diamond:
    send "&aYou can afford the upgrade."
Try it
conditiondoes not have <item>since 1.5.6

It holds fewer · player does not have 1 "%{_material}%"

if player does not have 1 iron pickaxe:
    send "&cBring a pickaxe."
Try it
conditionhas permission

The player holds the permission · player has permission "shop.vip"

unless player has permission "fly.use":
    send "&cYou cannot fly here."
    stop
Try it
conditiondoes not have permissionsince 1.4.0

The player lacks the permission · player does not have permission "shop.vip"

if player does not have permission "fly.use":
    cancel event
Try it
conditionhas effect / does not have effectsince 1.5.8

The player has that potion effect · player has effect speed

if player does not have effect night vision:
    apply night vision to player for 5 minutes
Try it
conditionis frozen / is vanished / is flyingsince 1.5.8

See Players · arg.1 is frozen

if player is flying:
    send "&7Enjoy the view."
Try it
conditionis tagged / is not taggedsince 1.5.8

The item carries that hidden tag · tool of player is tagged "wand"

if tool of player is tagged "wand":
    send "&dThe wand hums."
Try it
conditionis banned / is not bannedsince 1.5.7

The player is on the server's ban list · arg.1 is banned

if arg.1 is banned:
    send "&c%arg.1% is banned."
Try it
conditionis set / is not set

The value exists / does not · {%player%.coins} is not set

if {_spot} is set:
    teleport player to {_spot}
Try it
conditionis a number / is not a number

The value is numeric · arg.1 is a number

if arg.1 is not a number:
    send "&cUsage: /pay <amount>"
    stop
Try it
conditionis / is notsince 1.5.0

The same as == / != · event.cause is "FALL", {%player%.frozen} is true

if event.cause is "FALL":
    cancel event
Try it
conditionbigger than / smaller thansince 1.7.42

The same as > / <. Also greater than, more than, larger than, higher than, and less than, lower than, fewer than. With or without is in front · {_players} bigger than 50, {%player%.coins} is less than 10

if {_players} bigger than 50:
    send "&aBusy today."
Try it
conditionat least / at mostsince 1.7.42

The same as >= / <=. Also greater than or equal to and less than or equal to · level of player is at least 30

if level of player is at least 30:
    send "&6You may enter."
Try it
conditionis equal to / is not equal tosince 1.7.42

The same as == / != · arg.1 is equal to "red"

if arg.1 is equal to "red":
    send "&cRed it is."
Try it
conditionis above / is belowsince 1.7.42

The same as > / < · y of player's location is below 0

if y of player's location is above 200:
    send "&bHigh up."
Try it
conditionis between <a> and <b>since 1.7.0

Not less than the one and not more than the other; both ends count. is not between is the opposite · level of player is between 10 and 20

if player.y is between 0 and 16:
    send "&bDiamond level!"
Try it
conditionany of <list> <condition>since 1.7.58

The condition holds for at least one element of the list. What follows the list is any condition about one value; are and have may be written for is and has · any of {_scores} is above 100

command /anyrich:
    trigger:
        set {_coins} to [5, 250, 40]
        if any of {_coins} is above 100:
            send "&6Somebody is rich."
Try it
conditionall of <list> <condition>since 1.7.58

It holds for every element; for an empty list that is true · all of {team} are online

command /ready:
    trigger:
        set {_marks} to [3, 4, 5]
        if all of {_marks} are above 2:
            send "&aEverybody passed."
Try it
conditionand, or, not

Combine conditions · {_a} > 1 and not {locked}

if {%player%.coins} >= 50 and not {shop_closed}:
    send "&aThe shop is open."
Try it
Guide and examples
if {%player%.coins} >= 100:
    send "&aYou can afford it."
else if {%player%.coins} >= 50:
    send "&eAlmost there."
else:
    send "&cNot enough coins."
OperatorTrue whenExample
==Equalplayer.world == "world_nether"
!=Not equalarg.1 != "off"
> < >= <=Numeric comparisonplayer.health <= 5
containsLeft text includes right text, or left list includes right value; does not contain is the oppositemessage contains "help"
is between <a> and <b>A number is in that range, ends includedplayer.y is between 0 and 64
is in <list>The list contains the valuearg.1 is in ["on", "off"]
is emptyUnset, empty text or an empty list{queue} is empty
is a list / a location / an item / a date / an entity / a table / textWhat kind of value it is{home} is a location
is a playerThe name of someone who is onlinearg.1 is a player
is alphanumericOnly letters and digitsarg.1 is alphanumeric
is sneaking / sprinting / swimming / blocking / sleeping / on ground / in waterWhat a player is doingplayer is sneaking
<who> is [not] ridingThey sit on or in something: a horse, a boat, a minecart. vehicle of <who> is whatplayer is riding
<who> is [not] looking at <target>Their crosshair is on it, give or take a few degrees. The target is a location or somebody; up to 100 blocks awayplayer is looking at arg.1
<who> is [not] in biome <name>Where they stand is that biome; a location works in place of a playerplayer is in biome "desert"
<number> is [not] (even/odd)A whole number that two goes into, or does notlevel of player is even
<number> is [not] divisible by <n>It can be divided by that with nothing left overlevel of player is divisible by 5
is op / is onlineAlso true or false for someone offlinearg.1 is online
has played beforeThey have joined at least once before; has not played before is the oppositearg.1 has played before
has saved inventory <name> / does not have saved inventory <name>An inventory was put away for them with save inventoryplayer has saved inventory "before-arena"
is holding <item> / is wearing <item>In either hand, or in an armour slotplayer is holding diamond sword
is in region <name> / is not in region <name>The player is inside a region made with create regionplayer is in region "spawn"
is on cooldown <name> / is not on cooldown <name>A cooldown started with start cooldown is still running for themplayer is on cooldown "kit"
can see <player>The other player is not hidden from themplayer can see arg.1
<world> is raining / is day / is nightAbout a world, by nameplayer.world is night
<block> is solidThe block type can be stood onblock at {_loc} is solid
<block> is liquidIt is water or lavablock at {_loc} is liquid
<block> is passableIt can be walked through: air, water, grass, flowers, torchesblock at {_loc} is passable
<block> is airNothing is thereblock at {_loc} is air
has space for <item>The items would fit in the inventoryplayer has space for 5 diamond
is bedrock / is deadOn the Bedrock edition (through Floodgate) / dead and not yet respawnedplayer is bedrock
<a> if <condition> else <b>Not a test but a choice: one value or the other"on" if {flag} else "off"
starts with / ends withThe text begins or ends with the other, ignoring casemessage starts with "!"
matchesThe whole text fits a regular expressionarg.1 matches "[a-z0-9_]{3,16}"
chance of <n>%True about that often, at randomif chance of 25%:
chance of <n>%:The same as a block of its own: its lines run about that often. An if chance of <n>%: without the if; use the if when there is an elsechance of 10%:
has <item>The player's inventory holds at least that manyplayer has 5 diamond
does not have <item>It holds fewerplayer does not have 1 "%{_material}%"
has permissionThe player holds the permissionplayer has permission "shop.vip"
does not have permissionThe player lacks the permissionplayer does not have permission "shop.vip"
has effect / does not have effectThe player has that potion effectplayer has effect speed
is frozen / is vanished / is flyingSee Playersarg.1 is frozen
is tagged / is not taggedThe item carries that hidden tagtool of player is tagged "wand"
is banned / is not bannedThe player is on the server's ban listarg.1 is banned
is set / is not setThe value exists / does not{%player%.coins} is not set
is a number / is not a numberThe value is numericarg.1 is a number
is / is notThe same as == / !=event.cause is "FALL", {%player%.frozen} is true
bigger than / smaller thanThe same as > / <. Also greater than, more than, larger than, higher than, and less than, lower than, fewer than. With or without is in front{_players} bigger than 50, {%player%.coins} is less than 10
at least / at mostThe same as >= / <=. Also greater than or equal to and less than or equal tolevel of player is at least 30
is equal to / is not equal toThe same as == / !=arg.1 is equal to "red"
is above / is belowThe same as > / <y of player's location is below 0
is between <a> and <b>Not less than the one and not more than the other; both ends count. is not between is the oppositelevel of player is between 10 and 20
any of <list> <condition>The condition holds for at least one element of the list. What follows the list is any condition about one value; are and have may be written for is and hasany of {_scores} is above 100
all of <list> <condition>It holds for every element; for an empty list that is trueall of {team} are online
and, or, notCombine conditions{_a} > 1 and not {locked}

A comparison can be written with its sign or in words; both mean the same:

command /check:
    trigger:
        set {_players} to server.online_players
        if {_players} bigger than 50:
            send "&aBusy today."
        if {_players} smaller than 5:
            send "&7Quiet today."
        if level of player is at least 30:
            send "&6You may enter."
        if level of player at most 5:
            send "&7You are new here."
        if arg.1 is equal to "red":
            send "&cRed it is."
        if arg.1 is not equal to "red":
            send "&7Not red."
        if y of player's location is below 0:
            send "&8Deep down."
        if y of player's location is above 200:
            send "&bHigh up."
        if level of player is between 10 and 20:
            send "&eIn the middle."
        if {_players} is greater than or equal to 1 and {_players} is not more than 100:
            send "&7Somebody is here."
  • On one line: a short if can have its statement on the same line, after the colon: if arg.1 is not set: stop. It takes one statement and has no else.
  • else unless <condition>: joins the chain alongside else if.
  • Every is test has an is not form: player is not sneaking, arg.1 is not in {allowed}.
  • unless <condition>: is if the other way round; it runs its block when the condition is false:
unless player has permission "fly.use":
    send "&cYou cannot fly here."
    stop
  • A bare value is a condition too: if {event_active}: is true for true, any non-zero number, any non-empty list, and any text other than false or empty.
  • ==, != and contains ignore case for text, and == compares numerically when both sides are numeric ("5" == 5 is true).
  • not binds tighter than and, which binds tighter than or. Use parentheses when in doubt.
  • player has permission "x" checks whoever triggered the script, so it is true for the console. To check someone else, put a name on the left: arg.1 has permission "x".
  • has <item> counts across the whole inventory, armour and off hand included. A plain item such as 5 diamond matches any diamonds; an item written with a name or lore only matches stacks that carry them. A player who is offline has nothing. Take items away with remove 5 diamond from player; see Actions.