Value types

type<amount> in frontsince 1.3.0

How many; the default is 1

give 16 bread to player

Try it

typenamed <text>

Custom display name; & colour codes work

set {%player%.backpack.item} to diamond sword named "Storage"

Try it

typefireworksince 1.7.65

Short for firework rocket, wherever an item is named: give 3 firework to player

command /party:
    trigger:
        give 3 firework to player
        send "&dLight them up!"

Try it

typeowned by <name>since 1.7.3

For a player head: whose head it is, so it shows their skin

open gui with title "&8Online" with 1 rows for player:
    slot 1 is "player_head" owned by player.name named "&f%player.name%"

Try it

typetextured <value>since 1.7.64

For a player head: a skin of its own, for heads that are decoration and nobody's face. The value is what such heads are passed around as: the address of the skin on textures.minecraft.net, the code at its end, or the long text websites with heads give. Needs Minecraft 1.18.1 or newer; on an older server the head stays plain

command /globe:
    trigger:
        give 1 player head textured "b1dd4fe4a429abd665dfdb3e21321d6efa6a6b5e7b956db9c5d59c9efab25" named "&bGlobe" to player

Try it

typewith potion <kind>since 1.7.3

For a potion, splash potion, lingering potion or tipped arrow: what it holds. Kinds are the game's own: strength, long_swiftness, strong_healing and so on

give 1 splash potion with potion strong_healing to player

Try it

typewith lore <text>, <text>, ...since 1.3.0

Description lines, one per text

give player 1 diamond sword named "&6Excalibur" with lore "&7A fine blade", "&7Handle with care"

Try it

typeenchanted with <enchantment> <level>, ...since 1.7.27

Enchantments, the game's or your own: enchanted with sharpness 5, unbreaking 3

set {reward} to 1 bow enchanted with power 3

Try it

typeunbreakablesince 1.7.27

It never wears out

set nbt of tool of player to "{Unbreakable:1b}"

Try it

typeglowingsince 1.7.27

It shimmers as an enchanted item does, without being enchanted

give player 1 stick glowing

Try it

typetagged <text>since 1.7.27

A hidden mark scripts can tell it by

give 1 blaze rod named "&dMagic wand" tagged "wand" to player

Try it

typemodel <number>since 1.7.27

The custom model number a resource pack draws it with

give 1 paper named "&6Ticket" model 12 to player

Try it

typetype of <item>since 1.7.1

An item's material, e.g. diamond_sword; an entity's kind · type of tool of player

set {_held} to tool of player
if type of {_held} is "diamond_sword":
    send "&bA fine blade."

Try it

typeamount of <item>since 1.7.1

How many are in the stack · amount of tool of player

set {_held} to tool of player
send "&7You are holding " + amount of {_held} + " item(s)."

Try it

typeamount of <item> in inventory of <who>since 1.7.58

How many of them the player carries, all stacks together; 0 for none · amount of diamond in inventory of player

command /diamonds:
    trigger:
        set {_n} to amount of diamond in inventory of player
        send "&bYou carry &f%{_n}% &bdiamonds."

Try it

typex of <location>, y of <location>, z of <location>since 1.5.4

One coordinate, as a number · y of player's location

set {_height} to y of player's location

Try it

typeworld of <location>since 1.5.4

The world's name · world of {spawn}

send "Your home is in " + world of {%player%.home}

Try it

typeset y of <variable> to <number>since 1.5.4

Change one part; add and subtract work too · add 5 to y of {_spot}

set {_loc} to player's location
add 10 to y of {_loc}
teleport player to {_loc}

Try it

Guide and examples

A variable holds whatever you put in it. Besides numbers, text, booleans and lists there are richer kinds of value: durations, locations and items, described here, and dates, which have a part of their own, Dates and times. All of them are saved with the rest of the variable data.

Type	Written as	Prints as
Item	`diamond sword`, `3 golden apple`, `diamond sword named "&6Excalibur" with lore "line 1", "line 2"`	`3 golden apple`, `diamond sword named &6Excalibur`
Duration	`30 minutes`, `2 hours`, `1 hour 30 minutes`, `5 ticks`	`30 minutes`, `1 hour 30 minutes`
Location	`player's location`	`world 10.5, 64, -3.25`

set {%player%.backpack.item} to diamond sword named "Storage"
set {event.start_time} to 30 minutes
set {%player%.home} to player's location
give {%player%.backpack.item} to player
teleport player to {%player%.home}

Items are Minecraft material names written as plain words, with spaces instead of underscores. The name is checked when the script loads, so a misspelt item is reported straight away.

Part	Meaning
`<amount>` in front	How many; the default is 1
`named <text>`	Custom display name; `&` colour codes work
`firework`	Short for `firework rocket`, wherever an item is named: `give 3 firework to player`
`owned by <name>`	For a `player head`: whose head it is, so it shows their skin
`textured <value>`	For a `player head`: a skin of its own, for heads that are decoration and nobody's face. The value is what such heads are passed around as: the address of the skin on `textures.minecraft.net`, the code at its end, or the long text websites with heads give. Needs Minecraft 1.18.1 or newer; on an older server the head stays plain
`with potion <kind>`	For a `potion`, `splash potion`, `lingering potion` or `tipped arrow`: what it holds. Kinds are the game's own: `strength`, `long_swiftness`, `strong_healing` and so on
`with lore <text>, <text>, ...`	Description lines, one per text
`enchanted with <enchantment> <level>, ...`	Enchantments, the game's or your own: `enchanted with sharpness 5, unbreaking 3`
`unbreakable`	It never wears out
`glowing`	It shimmers as an enchanted item does, without being enchanted
`tagged <text>`	A hidden mark scripts can tell it by
`model <number>`	The custom model number a resource pack draws it with

An item value can be given with give, shown in a GUI slot (slot 5 is {%player%.backpack.item}), kept in a list, or adjusted when used: give player 5 {%player%.backpack.item} gives five of it. Items carry a material, amount, name, lore, enchantments, the unbreakable and glowing marks, a hidden tag, a custom model number, a head's owner and a potion's kind. How worn an item is, is not kept.

Durations are a number followed by ticks, seconds, minutes, hours or days (the unit must be written out in full inside a script line), and may be chained: 1 hour 30 minutes.

In math and comparisons a duration counts as its number of seconds: 30 minutes > 60 is true and server.time + 30 minutes is the moment half an hour from now.
Adding or subtracting two durations gives a duration; any other arithmetic gives a number of seconds.
Wherever a statement takes a time, any duration works: for 10 seconds, for 2 minutes.

Locations remember a world and a position. player's location is where the player stands. A location can be used anywhere a position is expected: teleport player to {%player%.home}, spawn particle "flame" at {%player%.home}.

The parts of a location can be read and changed one at a time:

set {_loc} to player's location
add 1 to y of {_loc}
set x of {_loc} to 0
send "Going to %{_loc}%"
teleport player to {_loc}

Syntax	Meaning	Example
`type of <item>`	An item's material, e.g. `diamond_sword`; an entity's kind	`type of tool of player`
`amount of <item>`	How many are in the stack	`amount of tool of player`
`amount of <item> in inventory of <who>`	How many of them the player carries, all stacks together; 0 for none	`amount of diamond in inventory of player`
`x of <location>`, `y of <location>`, `z of <location>`	One coordinate, as a number	`y of player's location`
`world of <location>`	The world's name	`world of {spawn}`
`set y of <variable> to <number>`	Change one part; `add` and `subtract` work too	`add 5 to y of {_spot}`

Mixing types up. Each kind of value can only do what makes sense for it. Adding a number to a whole location, or doing math on an item, stops the trigger and writes a warning to the log that names the script, the line and both kinds of value:

[HyperScript] kits.hs:14 Cannot add a number to a location (world 10.5, 64, -3.25). To change one coordinate, name it: add 1 to y of <variable>

These warnings are on by default. log-script-errors: false in config.yml hides them; the trigger still stops at the mistake, so leave them on unless the log is being flooded.