Expressions

Absorbed blocks

🔗

Expression

Patterns:
  • [the] absorbed blocks
Since: 2.5
Usable in events: sponge absorb
Return Type: block
The blocks absorbed by a sponge block.

Examples:

the absorbed blocks

Affected Entities

🔗

Expression

Patterns:
  • [the] affected entities
Since: 2.4
Return Type: livingentity
The affected entities in the area cloud effect event.

Examples:

on area cloud effect:
    loop affected entities:
        if loop-value is a player:
            send "WARNING: you've step on an area effect cloud!" to loop-value

Age of Block/Entity

🔗

Expression

Patterns:
Since: 2.7
Return Type:
Returns the age or maximum age of blocks and age for entities (there in no maximum age for entities). For blocks, 'Age' represents the different growth stages that a crop-like block can go through. A value of 0 indicates that the crop was freshly planted, whilst a value equal to 'maximum age' indicates that the crop is ripe and ready to be harvested. For entities, 'Age' represents the time left for them to become adults and it's in minus increasing to be 0 which means they're adults, e.g. A baby cow needs 20 minutes to become an adult which equals to 24,000 ticks so their age will be -24000 once spawned.

Examples:

# Set targeted crop to fully grown crop
set age of targeted block to maximum age of targeted block

# Spawn a baby cow that will only need 1 minute to become an adult
spawn a baby cow at player
set age of last spawned entity to -1200 # in ticks = 60 seconds

All Banned Players/IPs

🔗

Expression

Patterns:
  • [all [[of] the]|the] banned (players|(ips|ip addresses))
Since: 2.7
Return Type: object
Obtains the list of all banned players or IP addresses.

Examples:

command /banlist:
    trigger:
        send all the banned players

All Groups

🔗

Expression

Patterns:
  • all groups
Since: 2.2-dev35
Requirements: Vault, a permission plugin that supports Vault
Return Type: string
All the groups a player can have. This expression requires Vault and a compatible permissions plugin to be installed.

Examples:

command /group <text>:
    trigger:
        if argument is "list":
            send "%all groups%"

All Operators

🔗

Expression

Patterns:
  • [all [[of] the]|the] [server] [non(-| )]op[erator]s
Since: 2.7
Return Type: offlineplayer
The list of operators on the server.

Examples:

set {_ops::*} to all operators

All Permissions

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] permissions (from|of) %players%
  • [(all [[of] the]|the)] %players%'[s] permissions
Since: 2.2-dev33
Return Type: string
Returns all permissions of the defined player(s). Note that the modifications to resulting list do not actually change permissions.

Examples:

set {_permissions::*} to all permissions of the player

All Scripts

🔗

Expression

Patterns:
  • [all [of the]] scripts [(without ([subdirectory] paths|parents))]
  • [all [of the]] (enabled|loaded) scripts [(without ([subdirectory] paths|parents))]
  • [all [of the]] (disabled|unloaded) scripts [(without ([subdirectory] paths|parents))]
Since: 2.5
Return Type: string
Returns all of the scripts, or just the enabled or disabled ones.

Examples:

command /scripts:
    trigger:
        send "All Scripts: %scripts%" to player
        send "Loaded Scripts: %enabled scripts%" to player
        send "Unloaded Scripts: %disabled scripts%" to player

All commands

🔗

Expression

Patterns:
  • [(all|the|all [of] the)] [registered] [script] commands
Since: 2.6
Return Type: string
Returns all registered commands or all script commands.

Examples:

send "Number of all commands: %size of all commands%"
send "Number of all script commands: %size of all script commands%"

Alphabetical Sort

🔗

Expression

Patterns:
  • alphabetically sorted %texts%
Since: 2.2-dev18b
Return Type: string
Sorts given strings in alphabetical order.

Examples:

set {_list::*} to alphabetically sorted {_strings::*}

Altitude

🔗

Expression

Patterns:
Since: 1.4.3
Return Type: number
Effectively an alias of 'y-coordinate of …', it represents the height of some object above bedrock.

Examples:

on damage:
    altitude of the attacker is higher than the altitude of the victim
    set damage to damage * 1.2

Amount

🔗

Expression

Patterns:
  • [the] (amount|number|size) of %objects%
  • [the] recursive (amount|number|size) of %objects%
Since: 1.0
Return Type:
The amount of something. Please note that amount of %items% will not return the number of items, but the number of stacks, e.g. 1 for a stack of 64 torches. To get the amount of items in a stack, see the item amount expression.

Also, you can get the recursive size of a list, which will return the recursive size of the list with sublists included, e.g.

 {list::*} Structure
├──── {list::1}: 1
├──── {list::2}: 2
│ ├──── {list::2::1}: 3
│ │ └──── {list::2::1::1}: 4
│ └──── {list::2::2}: 5
└──── {list::3}: 6

Where using %size of {list::*}% will only return 3 (the first layer of indices only), while %recursive size of {list::*}% will return 6 (the entire list) Please note that getting a list's recursive size can cause lag if the list is large, so only use this expression if you need to!

Examples:

message "There are %number of all players% players online!"

Amount of Items

🔗

Expression

Patterns:
Since: 2.0
Return Type:
Counts how many of a particular item type are in a given inventory.

Examples:

message "You have %number of ores in the player's inventory% ores in your inventory."

Anvil Text Input

🔗

Expression

Patterns:
  • [the] anvil [inventory] (rename|text) input of %inventories%
  • %inventories%'[s] anvil [inventory] (rename|text) input
Since: 2.7
Return Type: string
An expression to get the name to be applied to an item in an anvil inventory.

Examples:

on inventory click:
    type of event-inventory is anvil inventory
    if the anvil input text of the event-inventory is "FREE OP":
        ban player

Applied Enchantments

🔗

Expression

Patterns:
  • [the] applied enchant[ment]s
Since: 2.5
Usable in events: enchant
Return Type: enchantmenttype
The applied enchantments in an enchant event. Deleting or removing the applied enchantments will prevent the item's enchantment.

Examples:

on enchant:
    set the applied enchantments to sharpness 10 and fire aspect 5

Argument

🔗

Expression

Patterns:
  • [the] last arg[ument]
  • [the] arg[ument](-| )<(\d+)>
  • [the] <(\d*1)st|(\d*2)nd|(\d*3)rd|(\d*[4-90])th> arg[ument][s]
  • [(all [[of] the]|the)] arg[ument][s]
  • [the] %*type%( |-)arg[ument][( |-)<\d+>]
  • [the] arg[ument]( |-)%*type%[( |-)<\d+>]
Since: 1.0, 2.7 (support for command events)
Return Type: object
Usable in script commands and command events. Holds the value of an argument given to the command, e.g. if the command "/tell <player> <text>" is used like "/tell Njol Hello Njol!" argument 1 is the player named "Njol" and argument 2 is "Hello Njol!". One can also use the type of the argument instead of its index to address the argument, e.g. in the above example 'player-argument' is the same as 'argument 1'. Please note that specifying the argument type is only supported in script commands.

Examples:

give the item-argument to the player-argument
damage the player-argument by the number-argument
give a diamond pickaxe to the argument
add argument 1 to argument 2
heal the last argument

Arithmetic

🔗

Expression

Patterns:
Since: 1.4.2
Return Type: number
Arithmetic expressions, e.g. 1 + 2, (health of player - 2) / 3, etc.

Examples:

set the player's health to 10 - the player's health
loop (argument + 2) / 5 times:
    message "Two useless numbers: %loop-num * 2 - 5%, %2^loop-num - 1%"
message "You have %health of player * 2% half hearts of HP!"

Armour Slot

🔗

Expression

Patterns:
  • [the] (boot[s]|shoe[s]|leg[ging][s]|chestplate[s]|helm[et][s]) [(item|slot)] of %living entities%
  • %living entities%'[s] (boot[s]|shoe[s]|leg[ging][s]|chestplate[s]|helm[et][s]) [(item|slot)]
Since: 1.0
Return Type: slot
A part of a player's armour, i.e. the boots, leggings, chestplate or helmet.

Examples:

set chestplate of the player to a diamond chestplate
helmet of player is neither a helmet nor air # player is wearing a block, e.g. from another plugin

Arrow Knockback Strength

🔗

Expression

Patterns:
Since: 2.5.1
Return Type:
An arrow's knockback strength.

Examples:

on shoot:
    event-projectile is an arrow
    set arrow knockback strength of event-projectile to 10

Arrows Stuck

🔗

Expression

Patterns:
Since: 2.5
Return Type:
The number of arrows stuck in a living entity.

Examples:

set arrows stuck in player to 5

Attack Cooldown

🔗

Expression

Patterns:
Since: 2.6.1
Requirements: Minecraft 1.15+
Return Type:
Returns the current cooldown for a player's attack. This is used to calculate damage, with 1.0 representing a fully charged attack and 0.0 representing a non-charged attack. NOTE: Currently this can not be set to anything.

Examples:

on damage:
    if attack cooldown of attacker < 1:
        set damage to 0
        send "Your hit was too weak! wait until your weapon is fully charged next time." to attacker

Attacked

🔗

Expression

Patterns:
  • [the] (attacked|damaged|victim) [<(.+)>]
Since: 1.3, 2.6.1 (projectile hit event)
Usable in events: damage, death, projectile hit
Return Type: entity
The victim of a damage event, e.g. when a player attacks a zombie this expression represents the zombie. When using Minecraft 1.11+, this also covers the hit entity in a projectile hit event.

Examples:

on damage:
    victim is a creeper
    damage the attacked by 1 heart

Attacker

🔗

Expression

Patterns:
  • [the] (attacker|damager)
Since: 1.3
Usable in events: damage, death, destroy
Return Type: entity
The attacker of a damage event, e.g. when a player attacks a zombie this expression represents the player. Please note that the attacker can also be a block, e.g. a cactus or lava, but this expression will not be set in these cases.

Examples:

on damage:
    attacker is a player
    health of attacker is less than or equal to 2
    damage victim by 1 heart

Bed

🔗

Expression

Patterns:
  • [the] [((safe|valid)|(unsafe|invalid))] bed[s] [location[s]] of %offline players%
  • %offline players%'[s] [((safe|valid)|(unsafe|invalid))] bed[s] [location[s]]
Since: 2.0, 2.7 (offlineplayers, safe bed)
Return Type: location
Returns the bed location of a player, i.e. the spawn point of a player if they ever slept in a bed and the bed still exists and is unobstructed however, you can set the unsafe bed location of players and they will respawn there even if it has been obstructed or doesn't exist anymore and that's the default behavior of this expression otherwise you will need to be specific i.e. safe bed location.

NOTE: Offline players can not have their bed location changed, only online players.

Examples:

if bed of player exists:
    teleport player the the player's bed
else:
    teleport the player to the world's spawn point

set the bed location of player to spawn location of world("world") # unsafe/invalid bed location
set the safe bed location of player to spawn location of world("world") # safe/valid bed location

Biome

🔗

Expression

Patterns:
Since: 1.4.4, 2.6.1 (3D biomes)
Return Type: biome
The biome at a certain location. Please note that biomes are only defined for x/z-columns (i.e. the altitude (y-coordinate) doesn't matter), up until Minecraft 1.15.x. As of Minecraft 1.16, biomes are now 3D (per block vs column).

Examples:

# damage player in deserts constantly
every real minute:
    loop all players:
        biome at loop-player is desert
        damage the loop-player by 1

Block

🔗

Expression

Patterns:
  • [the] [event-]block
Since: 1.0
Return Type: block
The block involved in the event, e.g. the clicked block or the placed block. Can optionally include a direction as well, e.g. 'block above' or 'block in front of the player'.

Examples:

block is ore
set block below to air
spawn a creeper above the block
loop blocks in radius 4:
    loop-block is obsidian
    set loop-block to water
block is a chest:
    clear the inventory of the block

Block

🔗

Expression

Patterns:
Since: 1.0
Return Type: block
The block involved in the event, e.g. the clicked block or the placed block. Can optionally include a direction as well, e.g. 'block above' or 'block in front of the player'.

Examples:

block is ore
set block below to air
spawn a creeper above the block
loop blocks in radius 4:
    loop-block is obsidian
    set loop-block to water
block is a chest:
    clear the inventory of the block

Block Break Speed

🔗

Expression

Patterns:
Since: 2.7
Requirements: 1.17+
Return Type:
Gets the speed at which the given player would break this block, taking into account tools, potion effects, whether or not the player is in water, enchantments, etc. The returned value is the amount of progress made in breaking the block each tick. When the total breaking progress reaches 1.0, the block is broken. Note that the break speed can change in the course of breaking a block, e.g. if a potion effect is applied or expires, or the player jumps/enters water.

Examples:

on left click using diamond pickaxe:
    event-block is set
    send "Break Speed: %break speed for player%" to player

Block Data

🔗

Expression

Patterns:
Since: 2.5, 2.5.2 (set)
Requirements: Minecraft 1.13+
Return Type: blockdata
Get the block data associated with a block. This data can also be used to set blocks.

Examples:

set {data} to block data of target block
set block at player to {data}
set block data of target block to oak_stairs[facing=south;waterlogged=true]

Block Hardness

🔗

Expression

Patterns:
Since: 2.6
Requirements: Minecraft 1.13+
Return Type: number
Obtains the block's hardness level (also known as "strength"). This number is used to calculate the time required to break each block.

Examples:

set {_hard} to block hardness of target block
if block hardness of target block > 5:

Block Sphere

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] blocks in radius %number% [(of|around) %location%]
  • [(all [[of] the]|the)] blocks around %location% in radius %number%
Since: 1.0
Return Type: block
All blocks in a sphere around a center, mostly useful for looping.

Examples:

loop blocks in radius 5 around the player:
    set loop-block to air

Blocks

🔗

Expression

Patterns:
Since: 1.0, 2.5.1 (within/cuboid/chunk)
Return Type: block
Blocks relative to other blocks or between other blocks. Can be used to get blocks relative to other blocks or for looping. Blocks from/to and between will return a straight line whereas blocks within will return a cuboid.

Examples:

loop blocks above the player:
loop blocks between the block below the player and the targeted block:
set the blocks below the player, the victim and the targeted block to air
set all blocks within {loc1} and {loc2} to stone
set all blocks within chunk at player to air

Blocks in Region

🔗

Expression

Patterns:
  • [(all|the)] blocks (in|of) [[the] region[s]] %regions%
Since: 2.1
Requirements: Supported regions plugin
Return Type: block
All blocks in a region. This expression requires a supported regions plugin to be installed.

Examples:

loop all blocks in the region {arena.%{faction.%player%}%}:
    clear the loop-block

Book Author

🔗

Expression

Patterns:
  • [the] [book] (author|writer|publisher) of %item types%
  • %item types%'[s] [book] (author|writer|publisher)
Since: 2.2-dev31
Return Type: string
The author of a book.

Examples:

on book sign:
    message "Book Title: %author of event-item%"

Book Pages

🔗

Expression

Patterns:
Since: 2.2-dev31, 2.7 (changers)
Return Type: string
The pages of a book.

Examples:

on book sign:
    message "Book Pages: %pages of event-item%"
    message "Book Page 1: %page 1 of event-item%"
set page 1 of player's held item to "Book writing"

Book Title

🔗

Expression

Patterns:
Since: 2.2-dev31
Return Type: string
The title of a book.

Examples:

on book sign:
    message "Book Title: %title of event-item%"

Burn/Cook Time

🔗

Expression

Patterns:
  • [the] burn[ing] time
  • [the] (burn|cook)[ing] time of %blocks%
  • %blocks%'[s] (burn|cook)[ing] time
Since: 2.3
Return Type: timespan
The time a furnace takes to burn an item in a fuel burn event. Can also be used to change the burn/cook time of a placed furnace.

Examples:

on fuel burn:
    if fuel slot is coal:
        set burning time to 1 tick

Case Text

🔗

Expression

Patterns:
  • %texts% in (upper|lower)[ ]case
  • (upper|lower)[ ]case %texts%
  • capitali(s|z)ed %texts%
  • %texts% in [(lenient|strict) ](proper|title)[ ]case
  • [(lenient|strict) ](proper|title)[ ]case %texts%
  • %texts% in [(lenient|strict) ]camel[ ]case
  • [(lenient|strict) ]camel[ ]case %texts%
  • %texts% in [(lenient|strict) ]pascal[ ]case
  • [(lenient|strict) ]pascal[ ]case %texts%
  • %texts% in [(lower|upper|capital|screaming)[ ]]snake[ ]case
  • [(lower|upper|capital|screaming)[ ]]snake[ ]case %texts%
  • %texts% in [(lower|upper|capital)[ ]]kebab[ ]case
  • [(lower|upper|capital)[ ]]kebab[ ]case %texts%
Since: 2.2-dev16 (lowercase and uppercase), 2.5 (advanced cases)
Return Type: string
Copy of given text in Lowercase, Uppercase, Proper Case, camelCase, PascalCase, Snake_Case, and Kebab-Case

Examples:

"Oops!" in lowercase # oops!
"oops!" in uppercase # OOPS!
"hellO i'm steve!" in proper case # HellO I'm Steve!
"hellO i'm steve!" in strict proper case # Hello I'm Steve!
"spAwn neW boSs ()" in camel case # spAwnNeWBoSs()
"spAwn neW boSs ()" in strict camel case # spawnNewBoss()
"geneRate ranDom numBer ()" in pascal case # GeneRateRanDomNumBer()
"geneRate ranDom numBer ()" in strict pascal case # GenerateRandomNumber()
"Hello Player!" in snake case # Hello_Player!
"Hello Player!" in lower snake case # hello_player!
"Hello Player!" in upper snake case # HELLO_PLAYER!
"What is your name?" in kebab case # What-is-your-name?
"What is your name?" in lower kebab case # what-is-your-name?
"What is your name?" in upper kebab case # WHAT-IS-YOUR-NAME?

Chat Format

🔗

Expression

Patterns:
  • [the] (message|chat) format[ting]
Since: 2.2-dev31
Return Type: string
Can be used to get/retrieve the chat format. The sender of a message is represented by [player] or [sender], and the message by [message] or [msg].

Examples:

set the chat format to "<yellow>[player]<light gray>: <green>[message]"

Chat Recipients

🔗

Expression

Patterns:
  • [chat][( |-)]recipients
Since: 2.2-Fixes-v7, 2.2-dev35 (clearing recipients)
Return Type: player
Recipients of chat events where this is called.

Examples:

chat recipients

Chunk

🔗

Expression

Patterns:
Since: 2.0
Return Type: chunk
The chunk a block, location or entity is in.

Examples:

add the chunk at the player to {protected chunks::*}

Clicked Block/Entity/Inventory/Slot

🔗

Expression

Patterns:
  • [the] (clicked [enchant[ment]] (button|option)|clicked (block|%*item type/entity type%)|clicked slot|clicked inventory|click (type|action)|inventory action)
Since: 1.0, 2.2-dev35 (more clickable things)
Usable in events: click, inventory click
Return Type: object
The clicked block, entity, inventory, inventory slot, inventory click type or inventory action.

Examples:

message "You clicked on a %type of clicked entity%!"
if the clicked block is a chest:
    show the inventory of the clicked block to the player

Color of

🔗

Expression

Patterns:
Since: 1.2
Return Type: color
The color of an item, can also be used to color chat messages with "<%color of ...%>this text is colored!".

Examples:

on click on wool:
    message "This wool block is <%color of block%>%color of block%!"
    set the color of the block to black

Colored / Uncolored

🔗

Expression

Patterns:
  • (colo[u]r-|colo[u]red )%texts%
  • (format-|formatted )%texts%
  • (un|non)[-](colo[u]r-|colo[u]red |format-|formatted )%texts%
Since: 2.0
Return Type: string
Parses <color>s and, optionally, chat styles in a message or removes any colors and chat styles from the message. Parsing all chat styles requires this expression to be used in same line with the send effect.

Examples:

on chat:
    set message to colored message # Safe; only colors get parsed
command /fade <player>:
    trigger:
        set display name of the player-argument to uncolored display name of the player-argument
command /format <text>:
    trigger:
        message formatted text-argument # Safe, because we're sending to whoever used this command

Command

🔗

Expression

Patterns:
  • [the] (full|complete|whole) command
  • [the] command [(label|alias)]
Since: 2.0, 2.7 (support for script commands)
Usable in events: command
Return Type: string
The command that caused an 'on command' event (excluding the leading slash and all arguments)

Examples:

# prevent any commands except for the /exit command during some game
on command:
    if {game::%player%::playing} is true:
        if the command is not "exit":
            message "You're not allowed to use commands during the game"
            cancel the event

Command Info

🔗

Expression

Patterns:
  • [the] main command [label] of command %texts%
  • command %texts%'[s] main command [name]
  • [the] description of command %texts%
  • command %texts%'[s] description
  • [the] label of command %texts%
  • command %texts%'[s] label
  • [the] usage of command %texts%
  • command %texts%'[s] usage
  • [(all|the|all [of] the)] aliases of command %texts%
  • command %texts%'[s] aliases
  • [the] permission of command %texts%
  • command %texts%'[s] permission
  • [the] permission message of command %texts%
  • command %texts%'[s] permission message
  • [the] plugin [owner] of command %texts%
  • command %texts%'[s] plugin [owner]
Since: 2.6
Return Type: string
Get information about a command.

Examples:

main name of command "skript"
description of command "help"
label of command "pl"
usage of command "help"
aliases of command "bukkit:help"
permission of command "/op"
command "op"'s permission message
command "sk"'s plugin owner

Command Sender

🔗

Expression

Patterns:
  • [the] [command['s]] (sender|executor)
Since: 2.0
Usable in events: command
Return Type: commandsender
The player or the console who sent a command. Mostly useful in commands and command events. If the command sender is a command block, its location can be retrieved by using %block's location%

Examples:

make the command sender execute "/say hi!"
on command:
    log "%executor% used command /%command% %arguments%" to "commands.log"

Compass Target

🔗

Expression

Patterns:
Since: 2.0
Return Type: location
The location a player's compass is pointing at.

Examples:

# make all player's compasses target a player stored in {compass::target::%player%}
every 5 seconds:
    loop all players:
        set the loop-player's compass target to location of {compass::target::%%loop-player%}

Console

🔗

Expression

Patterns:
  • [the] (console|server)
Since: 1.3.1
Return Type: commandsender
Represents the server's console which can receive messages and execute commands

Examples:

execute console command "/stop"
send "message to console" to the console

Cooldown Time/Remaining Time/Elapsed Time/Last Usage/Bypass Permission

🔗

Expression

Patterns:
  • [the] remaining [time] [of [the] (cooldown|wait) [(of|for) [the] [current] command]]
  • [the] elapsed [time] [of [the] (cooldown|wait) [(of|for) [the] [current] command]]
  • [the] ((cooldown|wait) time|[wait] time of [the] (cooldown|wait) [(of|for) [the] [current] command])
  • [the] last usage [date] [of [the] (cooldown|wait) [(of|for) [the] [current] command]]
  • [the] [cooldown] bypass perm[ission] [of [the] (cooldown|wait) [(of|for) [the] [current] command]]
Since: 2.2-dev33
Return Type: object
Only usable in command events. Represents the cooldown time, the remaining time, the elapsed time, the last usage date, or the cooldown bypass permission.

Examples:

command /home:
    cooldown: 10 seconds
    cooldown message: You last teleported home %elapsed time% ago, you may teleport home again in %remaining time%.
    trigger:
        teleport player to {home::%player%}

Coordinate

🔗

Expression

Patterns:
  • [the] (x|y|z)(-| )(coord[inate]|pos[ition]|loc[ation])[s] of %locations%
  • %locations%'[s] (x|y|z)(-| )(coord[inate]|pos[ition]|loc[ation])[s]
Since: 1.4.3
Return Type: number
Represents a given coordinate of a location.

Examples:

player's y-coordinate is smaller than 40:
    message "Watch out for lava!"

Creature/Entity/Player/Projectile/Villager/Powered Creeper/etc.

🔗

Expression

Patterns:
  • [the] [event-]<.+>
Since: 1.0
Return Type: entity
The entity involved in an event (an entity is a player, a creature or an inanimate object like ignited TNT, a dropped item or an arrow). You can use the specific type of the entity that's involved in the event, e.g. in a 'death of a creeper' event you can use 'the creeper' instead of 'the entity'.

Examples:

give a diamond sword of sharpness 3 to the player
kill the creeper
kill all powered creepers in the wolf's world
projectile is an arrow

Cursor Slot

🔗

Expression

Patterns:
Since: 2.2-dev17
Return Type: slot
The item which the player has on their cursor. This slot is always empty if player has no inventories open.

Examples:

cursor slot of player is dirt
set cursor slot of player to 64 diamonds

Custom Chest Inventory

🔗

Expression

Patterns:
  • [a [new]] chest inventory (named|with name) %text% [with %number% row[s]]
  • [a [new]] chest inventory with %number% row[s] [(named|with name) %text%]
Since: 2.2-dev34
Return Type: inventory
Returns a chest inventory with the given amount of rows and the name. Use the open inventory effect to open it.

Examples:

open chest inventory with 1 row named "test" to player
set {_inventory} to chest inventory with 1 row

Custom Model Data

🔗

Expression

Patterns:
Since: 2.5
Requirements: 1.14+
Return Type:
Get/set the CustomModelData tag for an item. (Value is an integer between 0 and 99999999)

Examples:

set custom model data of player's tool to 3
set {_model} to custom model data of player's tool

Damage

🔗

Expression

Patterns:
  • [the] damage
Since: 1.3.5
Usable in events: damage
Return Type: number
How much damage is done in a damage event, possibly ignoring armour, criticals and/or enchantments. Can be changed (remember that in Skript '1' is one full heart, not half a heart).

Examples:

increase the damage by 2

Damage Cause

🔗

Expression

Patterns:
  • [the] damage (cause|type)
Since: 2.0
Return Type: damagecause
The damage cause of a damage event. Please click on the link for more information.

Examples:

damage cause is lava, fire or burning

Damaged Item

🔗

Expression

Patterns:
Since: 2.4
Return Type: itemtype
Directly damages an item. In MC versions 1.12.2 and lower, this can be used to apply data values to items/blocks

Examples:

give player diamond sword with damage value 100
set player's tool to diamond hoe damaged by 250
give player diamond sword with damage 700 named "BROKEN SWORD"
set {_item} to diamond hoe with damage value 50 named "SAD HOE"
set target block of player to wool with data value 1
set target block of player to potato plant with data value 7

Data/Damage Value

🔗

Expression

Patterns:
Since: 1.2
Return Type:
The data/damage value of an item/block. Data values of blocks are only supported on 1.12.2 and below. You usually don't need this expression as you can check and set items with aliases easily, but this expression can e.g. be used to "add 1 to data of <item>", e.g. for cycling through all wool colors.

Examples:

set damage value of player's tool to 10
set data value of target block of player to 3
add 1 to the data value of the clicked block
reset data value of block at player

Date Ago/Later

🔗

Expression

Patterns:
Since: 2.2-dev33
Return Type: date
A date the specified timespan before/after another date.

Examples:

set {_yesterday} to 1 day ago
set {_hourAfter} to 1 hour after {someOtherDate}
set {_hoursBefore} to 5 hours before {someOtherDate}

Default Value

🔗

Expression

Patterns:
Since: 2.2-dev36
Return Type: object
A shorthand expression for giving things a default value. If the first thing isn't set, the second thing will be returned.

Examples:

broadcast {score::%player's uuid%} otherwise "%player% has no score!"

Difference

🔗

Expression

Patterns:
Since: 1.4
Return Type: object
The difference between two values, e.g. numbers, dates or times.

Examples:

if difference between {command::%player%::lastuse} and now is smaller than a minute:
    message "You have to wait a minute before using this command again!"

Difficulty

🔗

Expression

Patterns:
  • [the] difficult(y|ies) of %worlds%
  • %worlds%'[s] difficult(y|ies)
Since: 2.3
Return Type: difficulty
The difficulty of a world.

Examples:

set the difficulty of "world" to hard

Direction

🔗

Expression

Patterns:
  • [%number% [(block|met(er|re))[s]] [to the]] (north[[(-| )](east|west)][(ward[(s|ly)]|er[(n|ly)])] [of]|south[[(-| )](east|west)][(ward[(s|ly)]|er[(n|ly)])] [of]|(east|west)[(ward[(s|ly)]|er[(n|ly)])] [of]|above|over|(up|down)[ward[(s|ly)]]|below|under[neath]|beneath) [%direction%]
  • [%number% [(block|met(er|re))[s]]] in [the] (direction|horizontal direction|facing|horizontal facing) of %entity/block% [(of|from)]
  • [%number% [(block|met(er|re))[s]]] in %entity/block%'[s] (direction|horizontal direction|facing|horizontal facing) [(of|from)]
  • [%number% [(block|met(er|re))[s]]] (in[ ]front [of]|forward[s]|behind|backwards|[to the] (right|left) [of])
  • [%number% [(block|met(er|re))[s]]] horizontal[ly] (in[ ]front [of]|forward[s]|behind|backwards|to the (right|left) [of])
Since: 1.0 (basic), 2.0 (extended)
Return Type: direction
A helper expression for the direction type.

Examples:

thrust the player upwards
set the block behind the player to water
loop blocks above the player:
    set {_rand} to a random integer between 1 and 10
    set the block {_rand} meters south east of the loop-block to stone
block in horizontal facing of the clicked entity from the player is air
spawn a creeper 1.5 meters horizontally behind the player
spawn a TNT 5 meters above and 2 meters horizontally behind the player
thrust the last spawned TNT in the horizontal direction of the player with speed 0.2
push the player upwards and horizontally forward at speed 0.5
push the clicked entity in in the direction of the player at speed -0.5
open the inventory of the block 2 blocks below the player to the player
teleport the clicked entity behind the player
grow a regular tree 2 meters horizontally behind the player

Distance

🔗

Expression

Patterns:
Since: 1.0
Return Type: number
The distance between two points.

Examples:

if the distance between the player and {home::%uuid of player%} is smaller than 20:
    message "You're very close to your home!"

Drops

🔗

Expression

Patterns:
  • [the] drops
Since: 1.0
Usable in events: death
Return Type: itemtype
Only works in death events. Holds the drops of the dying creature. Drops can be prevented by removing them with "remove ... from drops", e.g. "remove all pickaxes from the drops", or "clear drops" if you don't want any drops at all.

Examples:

clear drops
remove 4 planks from the drops

Drops Of Block

🔗

Expression

Patterns:
Since: 2.5.1
Requirements: Minecraft 1.15+ ('as %entity%')
Return Type: itemtype
A list of the items that will drop when a block is broken.

Examples:

on break of block:
    give drops of block using player's tool to player

Element of

🔗

Expression

Patterns:
  • ([the] first|[the] last|[a] random|[the] %number%(st|nd|rd|th)|[the] %number%(st|nd|rd|th) [to] last) element [out] of %objects%
Since: 2.0, 2.7 (relative to last element)
Return Type: object
The first, last or a random element of a set, e.g. a list variable. See also: random

Examples:

give a random element out of {free items::*} to the player

Enchant Item

🔗

Expression

Patterns:
  • [the] enchant[ed] item
Since: 2.5
Usable in events: enchant prepare, enchant
Return Type: itemtype
The enchant item in an enchant prepare event or enchant event. It can be modified, but enchantments will still be applied in the enchant event.

Examples:

on enchant:
    set the enchanted item to a diamond chestplate
on enchant prepare:
    set the enchant item to a wooden sword

Enchanting Experience Cost

🔗

Expression

Patterns:
  • [the] [displayed] ([e]xp[erience]|enchanting) cost
Since: 2.5
Usable in events: enchant
Return Type:
The cost of enchanting in an enchant event. This is number that was displayed in the enchantment table, not the actual number of levels removed.

Examples:

on enchant:
    send "Cost: %the displayed enchanting cost%" to player

Enchantment Bonus

🔗

Expression

Patterns:
  • [the] enchantment bonus
Since: 2.5
Usable in events: enchant prepare
Return Type:
The enchantment bonus in an enchant prepare event. This represents the number of bookshelves affecting/surrounding the enchantment table.

Examples:

on enchant:
    send "There are %enchantment bonus% bookshelves surrounding this enchantment table!" to player

Enchantment Level

🔗

Expression

Patterns:
Since: 2.0
Return Type:
The level of a particular enchantment on an item.

Examples:

player's tool is a sword of sharpness:
    message "You have a sword of sharpness %level of sharpness of the player's tool% equipped"

Enchantment Offer

🔗

Expression

Patterns:
  • [all [of]] [the] enchant[ment] offers
  • enchant[ment] offer[s] %numbers%
  • [the] %number%(st|nd|rd|th) enchant[ment] offer
Since: 2.5
Usable in events: enchant prepare
Requirements: 1.11 or newer
Return Type: enchantmentoffer
The enchantment offer in enchant prepare events.

Examples:

on enchant prepare:
    send "Your enchantment offers are: %the enchantment offers%" to player

Enchantment Offer Cost

🔗

Expression

Patterns:
Since: 2.5
Requirements: 1.11 or newer
Return Type:
The cost of an enchantment offer. This is displayed to the right of an enchantment offer. If the cost is changed, it will always be at least 1. This changes how many levels are required to enchant, but does not change the number of levels removed. To change the number of levels removed, use the enchant event.

Examples:

set cost of enchantment offer 1 to 50

Ender Chest

🔗

Expression

Patterns:
Since: 2.0
Return Type: inventory
The ender chest of a player.

Examples:

open the player's ender chest to the player

Entities

🔗

Expression

Patterns:
Since: 1.2.1, 2.5 (chunks)
Return Type: entity
All entities in all worlds, in a specific world, in a chunk or in a radius around a certain location, e.g. all players, all creepers in the player's world, or players in radius 100 of the player.

Examples:

kill all creepers in the player's world
send "Psst!" to all players within 100 meters of the player
give a diamond to all ops
heal all tamed wolves in radius 2000 around {town center}
delete all monsters in chunk at player

Entity AI

🔗

Expression

Patterns:
Since: 2.5
Return Type: boolean
Returns whether an entity has AI.

Examples:

set artificial intelligence of target entity to false

Entity Attribute

🔗

Expression

Patterns:
Since: 2.5, 2.6.1 (final attribute value)
Return Type: number
The numerical value of an entity's particular attribute. Note that the movement speed attribute cannot be reliably used for players. For that purpose, use the speed expression instead. Resetting an entity's attribute is only available in Minecraft 1.11 and above.

Examples:

on damage of player:
    send "You are wounded!"
    set victim's attack speed attribute to 2

Entity Fire Burn Duration

🔗

Expression

Patterns:
  • [the] (burn[ing]|fire) (time|duration) of %entities%
  • %entities%'[s] (burn[ing]|fire) (time|duration)
Since: 2.7
Return Type: timespan
How much time an entity will be burning for.

Examples:

send "You will stop burning in %fire time of player%"

Entity Owner

🔗

Expression

Patterns:
Since: 2.5
Return Type: offlineplayer
The owner of a tameable entity, such as a horse or wolf.

Examples:

set owner of target entity to player
delete owner of target entity
set {_t} to uuid of tamer of target entity

Exhaustion

🔗

Expression

Patterns:
Since: 2.2-dev35
Return Type: number
The exhaustion of a player. This is mainly used to determine the rate of hunger depletion.

Examples:

set exhaustion of all players to 1

Experience

🔗

Expression

Patterns:
  • [the] [(spawned|dropped)] [e]xp[erience] [orb[s]]
Since: 2.1, 2.5.3 (block break event), 2.7 (experience change event)
Usable in events: experience spawn, break / mine, experience change
Return Type: experience
How much experience was spawned in an experience spawn or block break event. Can be changed.

Examples:

on experience spawn:
    add 5 to the spawned experience
on break of coal ore:
    clear dropped experience
on break of diamond ore:
    if tool of player = diamond pickaxe:
        add 100 to dropped experience

Exploded Blocks

🔗

Expression

Patterns:
  • [the] exploded blocks
Since: 2.5
Usable in events: explode
Return Type: block
Get all the blocks that were destroyed in an explode event

Examples:

on explode:
    loop exploded blocks:
        add loop-block to {exploded::blocks::*}

Explosion Block Yield

🔗

Expression

Patterns:
  • [the] [explosion['s]] block (yield|amount)
  • [the] percentage of blocks dropped
Since: 2.5
Usable in events: explosion
Return Type: number
The percentage of exploded blocks dropped in an explosion event. When changing the yield, a value greater than 1 will function the same as using 1. Attempting to change the yield to a value less than 0 will have no effect.

Examples:

on explode:
set the explosion's block yield to 10%

Explosion Yield

🔗

Expression

Patterns:
  • [the] explosion (yield|radius|size)
  • [the] (yield|radius|size) of [the] explosion
Since: 2.5
Usable in events: explosion prime
Return Type: number
The yield of the explosion in an explosion prime event. This is how big the explosion is. When changing the yield, values less than 0 will be ignored. Read this wiki page for more information

Examples:

on explosion prime:
    set the yield of the explosion to 10

Explosive Yield

🔗

Expression

Patterns:
  • [the] explosive (yield|radius|size) of %entities%
  • %entities%'[s] explosive (yield|radius|size)
Since: 2.5
Requirements: Minecraft 1.12 or newer for creepers
Return Type: number
The yield of an explosive (creeper, primed tnt, fireball, etc.). This is how big of an explosion is caused by the entity. Read this wiki page for more information

Examples:

on spawn of a creeper:
    set the explosive yield of the event-entity to 10

Facing

🔗

Expression

Patterns:
Since: 1.4
Return Type: direction
The facing of an entity or block, i.e. exactly north, south, east, west, up or down (unlike direction which is the exact direction, e.g. '0.5 south and 0.7 east')

Examples:

# makes a bridge
loop blocks from the block below the player in the horizontal facing of the player:
    set loop-block to cobblestone

Fall Distance

🔗

Expression

Patterns:
  • [the] fall[en] (distance|height) of %entities%
  • %entities%'[s] fall[en] (distance|height)
Since: 2.5
Return Type: number
The distance an entity has fallen for.

Examples:

set all entities' fall distance to 10
on damage:
    send "%victim's fall distance%" to victim

Fertilized Blocks

🔗

Expression

Patterns:
  • [all] [the] fertilized blocks
Since: 2.5
Usable in events: block fertilize
Requirements: Minecraft 1.13 or newer
Return Type: block
The blocks fertilized in block fertilize events.

Examples:

the fertilized blocks

Filter

🔗

Expression

Patterns:
  • %objects% (where|that match) \[<.+>\]
Since: 2.2-dev36
Return Type: object
Filters a list based on a condition. For example, if you ran 'broadcast "something" and "something else" where [string input is "something"]', only "something" would be broadcast as it is the only string that matched the condition.

Examples:

send "congrats on being staff!" to all players where [player input has permission "staff"]

Filter Input

🔗

Expression

Patterns:
  • input
  • %*type% input
Since: 2.2-dev36
Return Type: object
Represents the input in a filter expression. For example, if you ran 'broadcast "something" and "something else" where [input is "something"]the condition would be checked twice, using "something" and "something else" as the inputs.

Examples:

send "congrats on being staff!" to all players where [input has permission "staff"]

Final Damage

🔗

Expression

Patterns:
  • [the] final damage
Since: 2.2-dev19
Usable in events: damage
Return Type: number
How much damage is done in a damage event, considering all types of damage reduction. Can NOT be changed.

Examples:

send "%final damage%" to victim

Firework Effect

🔗

Expression

Patterns:
  • [(flickering|trailing|flickering trailing|trailing flickering)] %firework type% [firework [effect]] colo[u]red %colors%
  • [(flickering|trailing|flickering trailing|trailing flickering)] %firework type% [firework [effect]] colo[u]red %colors% fad(e|ing) [to] %colors%
Since: 2.4
Return Type: fireworkeffect
Represents a 'firework effect' which can be used in the launch firework effect.

Examples:

launch flickering trailing burst firework colored blue and green at player
launch trailing flickering star colored purple, yellow, blue, green and red fading to pink at target entity
launch ball large colored red, purple and white fading to light green and black at player's location with duration 1

Flight Mode

🔗

Expression

Patterns:
  • [the] fl(y[ing]|ight) (mode|state) of %players%
  • %players%'[s] fl(y[ing]|ight) (mode|state)
Since: 2.2-dev34
Return Type: boolean
Whether the player(s) are allowed to fly. Use Make Fly effect to force player(s) to fly.

Examples:

set flight mode of player to true
send "%flying state of all players%"

Food Level

🔗

Expression

Patterns:
  • [the] (food|hunger)[[ ](level|met(er|re)|bar)] [of %players%]
  • %players%'[s] (food|hunger)[[ ](level|met(er|re)|bar)]
Since: 1.0
Return Type: number
The food level of a player from 0 to 10. Has several aliases: food/hunger level/meter/bar.

Examples:

set the player's food level to 10

Formatted Date

🔗

Expression

Patterns:
  • %dates% formatted [human-readable] [(with|as) %text%]
  • [human-readable] formatted %dates% [(with|as) %text%]
Since: 2.2-dev31, 2.7 (support variables in format)
Return Type: string
Converts date to human-readable text format. By default, 'yyyy-MM-dd HH:mm:ss z' (e.g. '2018-03-30 16:03:12 +01') will be used. For reference, see this Wikipedia article.

Examples:

command /date:
    trigger:
        send "Full date: %now formatted human-readable%" to sender
        send "Short date: %now formatted as "yyyy-MM-dd"%" to sender

Former/Future State

🔗

Expression

Patterns:
  • [the] (former|past|old) [state] [of] %~object%
  • %~object% before [the event]
  • [the] (future|to-be|new) [state] [of] %~object%
  • %~object%(-to-be| after[(wards| the event)])
Since: 1.1
Return Type: object
Represents the value of an expression before an event happened or the value it will have directly after the event, e.g. the old or new level respectively in a level change event. Note: The past, future and present states of an expression are sometimes called 'time states' of an expression. Note 2: If you don't specify whether to use the past or future state of an expression that has different values, its default value will be used which is usually the value after the event.

Examples:

on teleport:
    former world was "world_nether" # or 'world was'
    world will be "world" # or 'world after the event is'
on tool change:
    past tool is an axe
    the tool after the event will be air
on weather change:
    set {weather::%world%::old} to past weather
    set {weather::%world%::current} to the new weather

Freeze Time

🔗

Expression

Patterns:
Since: 2.7
Return Type: timespan
How much time an entity has been in powdered snow for.

Examples:

player's freeze time is less than 3 seconds:
    send "you're about to freeze!" to the player

Furnace Slot

🔗

Expression

Patterns:
  • (fuel|result) [slot]
  • (ore|fuel|result)[s] [slot[s]] of %blocks%
  • %blocks%'[s] (ore|fuel|result)[s] [slot[s]]
Since: 1.0
Usable in events: smelt, fuel burn
Return Type: slot
A slot of a furnace, i.e. either the ore, fuel or result slot. Remember to use 'block' and not 'furnace', as 'furnace' is not an existing expression.

Examples:

set the fuel slot of the clicked block to a lava bucket
set the block's ore slot to 64 iron ore
give the result of the block to the player
clear the result slot of the block

Game Mode

🔗

Expression

Patterns:
Since: 1.0
Return Type: gamemode
The gamemode of a player. (Gamemodes)

Examples:

player's gamemode is survival
set the player's gamemode to creative

Gamerule Value

🔗

Expression

Patterns:
Since: 2.5
Requirements: Minecraft 1.13+
Return Type: gamerulevalue
The gamerule value of a world.

Examples:

set the gamerule commandBlockOutput of world "world" to false

Gliding State

🔗

Expression

Patterns:
Since: 2.2-dev21
Return Type: boolean
Sets of gets gliding state of player. It allows you to set gliding state of entity even if they do not have an Elytra equipped.

Examples:

set gliding of player to off

Glowing

🔗

Expression

Patterns:
Since: 2.2-dev18
Return Type: boolean
Indicates if targeted entity is glowing (new 1.9 effect) or not. Glowing entities can be seen through walls.

Examples:

set glowing of player to true

Gravity

🔗

Expression

Patterns:
Since: 2.2-dev21
Return Type: boolean
If entity is affected by gravity or not, i.e. if it has Minecraft 1.10+ NoGravity flag.

Examples:

set gravity of player off

Group

🔗

Expression

Patterns:
Since: 2.2-dev35
Requirements: Vault, a permission plugin that supports Vault
Return Type: string
The primary group or all groups of a player. This expression requires Vault and a compatible permissions plugin to be installed.

Examples:

on join:
    broadcast "%group of player%" # this is the player's primary group
    broadcast "%groups of player%" # this is all of the player's groups

Hanging Entity/Remover

🔗

Expression

Patterns:
  • [the] hanging (entity|remover)
Since: 2.6.2
Return Type: entity
Returns the hanging entity or remover in hanging break and place events.

Examples:

on break of item frame:
    if item of hanging entity is diamond pickaxe:
        cancel event
        if hanging remover is a player:
            send "You can't break that item frame!" to hanging remover

Hash

🔗

Expression

Patterns:
  • %texts% hash[ed] with (MD5|SHA-256)
Since: 2.0, 2.2-dev32 (SHA-256 algorithm)
Return Type: string
Hashes the given text using the MD5 or SHA-256 algorithms. Each algorithm is suitable for different use cases.

MD5 is provided mostly for backwards compatibility, as it is outdated and not secure. SHA-256 is more secure, and can used to hash somewhat confidental data like IP addresses and even passwords. It is not that secure out of the box, so please consider using salt when dealing with passwords! When hashing data, you must specify algorithms that will be used for security reasons!

Please note that a hash cannot be reversed under normal circumstanses. You will not be able to get original value from a hash with Skript.

Examples:

command /setpass <text>:
    trigger:
        set {password::%uuid of player%} to text-argument hashed with SHA-256
command /login <text>:
    trigger:
        if text-argument hashed with SHA-256 is {password::%uuid of player%}:
            message "Login successful."
        else:
            message "Wrong password!"

Hatching Entity Type

🔗

Expression

Patterns:
  • [the] hatching entity [type]
Since: 2.7
Usable in events: Egg Throw
Return Type: entitydata
The type of the entity that will be hatched in a Player Egg Throw event.

Examples:

on player egg throw:
    set the hatching entity type to a primed tnt

Hatching Number

🔗

Expression

Patterns:
  • [the] hatching number
Since: 2.7
Usable in events: Egg Throw
Return Type:
The number of entities that will be hatched in a Player Egg Throw event. Please note that no more than 127 entities can be hatched at once.

Examples:

on player egg throw:
    set the hatching number to 10

Head location

🔗

Expression

Patterns:
Since: 2.0
Return Type: location
The location of an entity's head, mostly useful for players and e.g. looping blocks in the player's line of sight. Please note that this location is only accurate for entities whose head is exactly above their center, i.e. players, endermen, zombies, skeletons, etc., but not sheep, pigs or cows.

Examples:

set the block at the player's head to air
set the block in front of the player's eyes to glass
loop blocks in front of the player's head:

Heal Amount

🔗

Expression

Patterns:
  • [the] heal amount
Since: 2.5.1
Usable in events: heal
Return Type: number
The amount of health healed in a healing event.

Examples:

increase heal amount by 2
remove 0.5 from heal amount

Heal Reason

🔗

Expression

Patterns:
  • (regen|health regain|heal) (reason|cause)
Since: 2.5
Return Type: healreason
The heal reason of a heal event. Please click on the link for more information.

Examples:

on heal:
    if heal reason = satiated:
        send "You ate enough food and gained health back!" to player

Health

🔗

Expression

Patterns:
Since: 1.0
Usable in events: damage
Return Type: number
The health of a creature, e.g. a player, mob, villager, etc. The minimum value is 0, and the maximum is the creature's max health (e.g. 10 for players).

Examples:

message "You have %health% HP left."

Hidden Players

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] hidden players (of|for) %players%
  • [(all [[of] the]|the)] players hidden (from|for|by) %players%
Since: 2.3
Return Type: player
The players hidden from a player that were hidden using the player visibility effect.

Examples:

message "<light red>You are currently hiding: <light gray>%hidden players of the player%"

Highest Solid Block

🔗

Expression

Patterns:
  • highest [(solid|non-air)] block at %locations%
Since: 2.2-dev34
Return Type: block
Returns the highest solid block at the x and z coordinates of the world of a given location.

Examples:

highest block at location of arg-player

Hostname

🔗

Expression

Patterns:
  • [the] (host|domain)[ ][name]
Since: 2.6.1
Return Type: string
The hostname used by the connecting player to connect to the server in a connect event.

Examples:

on connect:
    hostname is "testers.example.com"
    send "Welcome back tester!"

Hotbar Button

🔗

Expression

Patterns:
  • [the] hotbar button
Since: 2.5
Return Type:
The hotbar button clicked in an inventory click event.

Examples:

on inventory click:
    send "You clicked the hotbar button %hotbar button%!"

Hotbar Slot

🔗

Expression

Patterns:
  • [the] [([currently] selected|current)] hotbar slot of %players%
  • %players%'[s] [([currently] selected|current)] hotbar slot
Since: 2.2-dev36
Return Type: slot
The currently selected hotbar slot. To retrieve its number use Slot Index expression.

Examples:

message "%player's current hotbar slot%"
set player's selected hotbar slot to slot 4 of player
send "index of player's current hotbar slot = 1" # second slot from the left

Hover List

🔗

Expression

Patterns:
  • [the] [custom] [(player|server)] (hover|sample) ([message] list|message)
  • [the] [custom] player [(hover|sample)] list
Since: 2.3
Usable in events: server list ping
Requirements: Paper 1.12.2 or newer
Return Type: string
The list when you hover on the player counts of the server in the server list. This can be changed using texts or players in a server list ping event only. Adding players to the list means adding the name of the players. And note that, for example if there are 5 online players (includes fake online count) in the server and the hover list is set to 3 values, Minecraft will show "... and 2 more ..." at end of the list.

Examples:

on server list ping:
    clear the hover list
    add "&aWelcome to the &6Minecraft &aserver!" to the hover list
    add "" to the hover list # A blank line
    add "&cThere are &6%online players count% &conline players!" to the hover list

Humidity

🔗

Expression

Patterns:
  • [the] humidit(y|ies) of %blocks%
  • %blocks%'[s] humidit(y|ies)
Since: 2.2-dev35
Return Type: number
Humidity of given blocks.

Examples:

set {_humidity} to event-block's humidity

IP

🔗

Expression

Patterns:
  • IP[s][( |-)address[es]] of %players%
  • %players%'[s] IP[s][( |-)address[es]]
  • IP[( |-)address]
Since: 1.4, 2.2-dev26 (when used in connect event), 2.3 (when used in server list ping event)
Return Type: string
The IP address of a player, or the connected player in a connect event, or the pinger in a server list ping event.

Examples:

ban the IP address of the player
broadcast "Banned the IP %IP of player%"

on connect:
    log "[%now%] %player% (%ip%) is connected to the server."

on server list ping:
    send "%IP-address%" to the console

Id

🔗

Expression

Patterns:
Since: 1.0
Return Type:
The id of a specific item. You usually don't need this expression as you can likely do everything with aliases.

Examples:

message "the ID of %type of the clicked block% is %id of the clicked block%."

Index Of

🔗

Expression

Patterns:
  • [the] [(first|last)] index of %text% in %text%
Since: 2.1
Return Type:
The first or last index of a character (or text) in a text, or -1 if it doesn't occur in the text. Indices range from 1 to the length of the text.

Examples:

set {_first} to the first index of "@" in the text argument
if {_s} contains "abc":
    set {_s} to the first (index of "abc" in {_s} + 3) characters of {_s} # removes everything after the first "abc" from {_s}

Indices of List

🔗

Expression

Patterns:
  • [(the|all [[of] the])] (indexes|indices) of %~objects%
  • %~objects%'[s] (indexes|indices)
  • [sorted] (indices|indexes) of %~objects% in (ascending|descending) order
  • [sorted] %~objects%'[s] (indices|indexes) in (ascending|descending) order
Since: 2.4 (indices), 2.6.1 (sorting)
Return Type: string
Returns all the indices of a list variable, optionally sorted by their values. To sort the indices, all objects in the list must be comparable; Otherwise, this expression will just return the unsorted indices.

Examples:

set {l::*} to "some", "cool" and "values"
broadcast "%indices of {l::*}%" # result is 1, 2 and 3

set {_leader-board::first} to 17
set {_leader-board::third} to 30
set {_leader-board::second} to 25
set {_leader-board::fourth} to 42
set {_ascending-indices::*} to sorted indices of {_leader-board::*} in ascending order
broadcast "%{_ascending-indices::*}%" #result is first, second, third, fourth
set {_descending-indices::*} to sorted indices of {_leader-board::*} in descending order
broadcast "%{_descending-indices::*}%" #result is fourth, third, second, first

Inventory

🔗

Expression

Patterns:
  • [the] inventor(y|ies) of %inventoryholders%
  • %inventoryholders%'[s] inventor(y|ies)
Since: 1.0
Return Type: object
The inventory of a block or player. You can usually omit this expression and can directly add or remove items to/from blocks or players.

Examples:

add a plank to the player's inventory
clear the player's inventory
remove 5 wool from the inventory of the clicked block

Inventory Action

🔗

Expression

Patterns:
  • [the] inventory action
Since: 2.2-dev16
Return Type: inventoryaction
The inventory action of an inventory event. Please click on the link for more information.

Examples:

inventory action is pickup all

Inventory Holder/Viewers/Rows/Slots

🔗

Expression

Patterns:
  • (holder[s]|viewers|[amount of] rows|[amount of] slots) of %inventories%
  • %inventories%'[s] (holder[s]|viewers|[amount of] rows|[amount of] slots)
Since: 2.2-dev34, 2.5 (slots)
Return Type: object
Gets the amount of rows/slots, viewers and holder of an inventory.

NOTE: 'Viewers' expression returns a list of players viewing the inventory. Note that a player is considered to be viewing their own inventory and internal crafting screen even when said inventory is not open.

Examples:

event-inventory's amount of rows
holder of player's top inventory
{_inventory}'s viewers

Inventory Slot

🔗

Expression

Patterns:
Since: 2.2-dev24
Return Type: slot
Represents a slot in an inventory. It can be used to change the item in an inventory too.

Examples:

if slot 0 of player is air:
    set slot 0 of player to 2 stones
    remove 1 stone from slot 0 of player
    add 2 stones to slot 0 of player
    clear slot 1 of player

Item

🔗

Expression

Patterns:
  • [the] item
Since: unknown (before 2.1)
Return Type: itemstack
The item involved in an event, e.g. in a drop, dispense, pickup or craft event.

Examples:

on dispense:
    item is a clock
    set the time to 6:00

Item Amount

🔗

Expression

Patterns:
Since: 2.2-dev24
Return Type:
The amount of an item stack.

Examples:

send "You have got %item amount of player's tool% %player's tool% in your hand!" to player

Item Enchantments

🔗

Expression

Patterns:
Since: 2.2-dev36
Return Type: enchantmenttype
All the enchantments an item type has.

Examples:

clear enchantments of event-item

Item of an Entity

🔗

Expression

Patterns:
Since: 2.2-dev35, 2.2-dev36 (improved), 2.5.2 (throwable projectiles)
Requirements: Minecraft 1.15.2+ (throwable projectiles)
Return Type: slot
An item associated with an entity. For dropped item entities, it gets, obviously, the item that was dropped. For item frames, the item inside the frame is returned. For throwable projectiles (snowballs, enderpearls etc.),it gets the displayed item. Other entities do not have items associated with them.

Examples:

Missing examples.

Item with CustomModelData

🔗

Expression

Patterns:
Since: 2.5
Requirements: 1.14+
Return Type: itemtype
Get an item with a CustomModelData tag. (Value is an integer between 0 and 99999999)

Examples:

give player a diamond sword with custom model data 2
set slot 1 of inventory of player to wooden hoe with custom model data 357

Item with Lore

🔗

Expression

Patterns:
Since: 2.3
Return Type: itemtype
Returns the given item type with the specified lore added to it. If multiple strings are passed, each of them will be a separate line in the lore.

Examples:

set {_test} to stone with lore "line 1" and "line 2"
give {_test} to player

Items

🔗

Expression

Patterns:
  • [all [[of] the]|the] block[[ ]type]s
  • every block[[ ]type]
  • [all [[of] the]|the|every] block[s] of type[s] %item types%
  • [all [[of] the]|the|every] item[s] of type[s] %item types%
Since: 1.0 pre-5
Return Type: itemtype
Items or blocks of a specific type, useful for looping.

Examples:

loop items of type ore and log:
    block contains loop-item
    message "Theres at least one %loop-item% in this block"
drop all blocks at the player # drops one of every block at the player

Items In

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] items ([with]in|of|contained in|out of) [inventor(y|ies)] %inventories%
Since: 2.0
Return Type: slot
All items in an inventory. Useful for looping or storing in a list variable. Please note that the positions of the items in the inventory are not saved, only their order is preserved.

Examples:

loop all items in the player's inventory:
    loop-item is enchanted
    remove loop-item from the player
set {inventory::%uuid of player%::*} to items in the player's inventory

Join & Split

🔗

Expression

Patterns:
  • (concat[enate]|join) %texts% [(with|using|by) [[the] delimiter] %text%]
  • split %text% (at|using|by) [[the] delimiter] %text% [with case sensitivity]
  • %text% split (at|using|by) [[the] delimiter] %text% [with case sensitivity]
  • regex split %text% (at|using|by) [[the] delimiter] %text%
  • regex %text% split (at|using|by) [[the] delimiter] %text%
Since: 2.1, 2.5.2 (regex support), 2.7 (case sensitivity)
Return Type: string
Joins several texts with a common delimiter (e.g. ", "), or splits a text into multiple texts at a given delimiter.

Examples:

message "Online players: %join all players with "" | ""%" # %all players% would use the default "x, y, and z"
set {_s::*} to the string argument split at ","

Language

🔗

Expression

Patterns:
  • [the] [([currently] selected|current)] [game] (language|locale) [setting] of %players%
  • %players%'[s] [([currently] selected|current)] [game] (language|locale) [setting]
Since: 2.3
Return Type: string
Currently selected game language of a player. The value of the language is not defined properly. The vanilla Minecraft client will use lowercase language / country pairs separated by an underscore, but custom resource packs may use any format they wish.

Examples:

message player's current language

Last Attacker

🔗

Expression

Patterns:
  • [the] last attacker of %entity%
  • %entity%'[s] last attacker
Since: 2.5.1
Return Type: object
The last block or entity that attacked an entity.

Examples:

send "%last attacker of event-entity%"

Last Color

🔗

Expression

Patterns:
  • [the] last color[s] of %texts%
  • %texts%'[s] last color[s]
Since: 2.6
Return Type: string
The colors used at the end of a string. The colors of the returned string will be formatted with their symbols.

Examples:

set {_color} to the last colors of "heyyo"

Last Damage

🔗

Expression

Patterns:
Since: 2.5.1
Return Type: number
The last damage that was done to an entity. Note that changing it doesn't deal more/less damage.

Examples:

set last damage of event-entity to 2

Last Damage Cause

🔗

Expression

Patterns:
Since: 2.2-Fixes-V10
Return Type: damagecause
Cause of last damage done to an entity

Examples:

set last damage cause of event-entity to fire tick

Last Loaded Server Icon

🔗

Expression

Patterns:
  • [the] [last[ly]] loaded server icon
Since: 2.3
Requirements: Paper 1.12.2 or newer
Return Type: cachedservericon
Returns the last loaded server icon with the load server icon effect.

Examples:

set {server-icon} to the last loaded server icon

Last Resource Pack Response

🔗

Expression

Patterns:
  • [the] [last] resource pack response[s] of %players%
  • %players%'[s] [last] resource pack response[s]
Since: 2.4
Requirements: Paper 1.9 or newer
Return Type: resourcepackstate
Returns the last resource pack response received from a player.

Examples:

if player's last resource pack response is deny or download fail:

Last Spawned Entity

🔗

Expression

Patterns:
  • [the] [last[ly]] (spawned|shot) %*entity type%
  • [the] [last[ly]] dropped (item)
  • [the] [last[ly]] (created|struck) (lightning)
  • [the] [last[ly]] (launched|deployed) (firework)
Since: 1.3 (spawned entity), 2.0 (shot entity), 2.2-dev26 (dropped item), 2.7 (struck lightning, firework)
Return Type: entity
Holds the entity that was spawned most recently with the spawn effect (section), dropped with the drop effect, shot with the shoot effect or created with the lightning effect. Please note that even though you can spawn multiple mobs simultaneously (e.g. with 'spawn 5 creepers'), only the last spawned mob is saved and can be used. If you spawn an entity, shoot a projectile and drop an item you can however access all them together.

Examples:

spawn a priest
set {healer::%spawned priest%} to true
shoot an arrow from the last spawned entity
ignite the shot projectile
drop a diamond sword
push last dropped item upwards
teleport player to last struck lightning
delete last launched firework

Last/First Login Time

🔗

Expression

Patterns:
Since: 2.5
Return Type: date
When a player last/first logged in the server. 'last login' requires paper to get the last login, otherwise it will get the last time they were seen on the server.

Examples:

command /onlinefor:
    trigger:
        send "You have been online for %difference between player's last login and now%."
        send "You first joined the server %difference between player's first login and now% ago."

Leash Holder

🔗

Expression

Patterns:
Since: 2.3
Return Type: entity
The leash holder of a living entity.

Examples:

set {_example} to the leash holder of the target mob

Length

🔗

Expression

Patterns:
Since: 2.1
Return Type:
The length of a text, in number of characters.

Examples:

set {_l} to length of the string argument

Level

🔗

Expression

Patterns:
Since: unknown (before 2.1)
Usable in events: level change
Return Type:
The level of a player.

Examples:

reduce the victim's level by 1
set the player's level to 0

Level Progress

🔗

Expression

Patterns:
Since: 2.0
Usable in events: level change
Return Type: number
The player's progress in reaching the next level, this represents the experience bar in the game. Please note that this value is between 0 and 1 (e.g. 0.5 = half experience bar). Changing this value can cause the player's level to change if the resulting level progess is negative or larger than 1, e.g. increase the player's level progress by 0.5 will make the player gain a level if their progress was more than 50%.

Examples:

# use the exp bar as mana
on rightclick with a blaze rod:
    player's level progress is larger than 0.2
    shoot a fireball from the player
    reduce the player's level progress by 0.2
every 2 seconds:
    loop all players:
        level progress of loop-player is smaller than 0.9:
            increase level progress of the loop-player by 0.1
        else:
            set level progress of the loop-player to 0.99
on xp spawn:
    cancel event

Light Level

🔗

Expression

Patterns:
Since: 1.3.4
Return Type:
Gets the light level at a certain location which ranges from 0 to 15. It can be separated into sunlight (15 = direct sunlight, 1-14 = indirect) and block light (torches, glowstone, etc.). The total light level of a block is the maximum of the two different light types.

Examples:

# set vampire players standing in bright sunlight on fire
every 5 seconds:
    loop all players:
        {vampire::%uuid of loop-player%} is true
        sunlight level at the loop-player is greater than 10
        ignite the loop-player for 5 seconds

Loaded Plugins

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] [loaded] plugins
Since: 2.7
Return Type: string
An expression to obtain a list of the names of the server's loaded plugins.

Examples:

if the loaded plugins contains "Vault":
    broadcast "This server uses Vault plugin!"

send "Plugins (%size of loaded plugins%): %plugins%" to player

Location

🔗

Expression

Patterns:
  • [the] [event-](location|position)
Since: 2.0
Return Type: location
The location where an event happened (e.g. at an entity or block), or a location relative to another (e.g. 1 meter above another location).

Examples:

drop 5 apples at the event-location # exactly the same as writing 'drop 5 apples'
set {_loc} to the location 1 meter above the player

Location

🔗

Expression

Patterns:
Since: 2.0
Return Type: location
The location where an event happened (e.g. at an entity or block), or a location relative to another (e.g. 1 meter above another location).

Examples:

drop 5 apples at the event-location # exactly the same as writing 'drop 5 apples'
set {_loc} to the location 1 meter above the player

Location

🔗

Expression

Patterns:
Since: Unknown
Return Type: location
The location of a block or entity. This not only represents the x, y and z coordinates of the location but also includes the world and the direction an entity is looking (e.g. teleporting to a saved location will make the teleported entity face the same saved direction every time). Please note that the location of an entity is at it's feet, use head location to get the location of the head.

Examples:

set {home::%uuid of player%} to the location of the player
message "You home was set to %player's location% in %player's world%."

Location At

🔗

Expression

Patterns:
  • [the] (location|position) [at] [\(][x[ ][=[ ]]]%number%, [y[ ][=[ ]]]%number%, [and] [z[ ][=[ ]]]%number%[\)] [[(in|of) [[the] world]] %world%]
Since: 2.0
Return Type: location
Allows to create a location from three coordinates and a world.

Examples:

set {_loc} to the location at arg-1, arg-2, arg-3 of the world arg-4
distance between the player and the location (0, 0, 0) is less than 200

Loop value

🔗

Expression

Patterns:
  • [the] loop-<.+>
Since: 1.0
Return Type: object
The currently looped value.

Examples:

# countdown:
loop 10 times:
    message "%11 - loop-number%"
    wait a second
# generate a 10x10 floor made of randomly colored wool below the player:
loop blocks from the block below the player to the block 10 east of the block below the player:
    loop blocks from the loop-block to the block 10 north of the loop-block:
        set loop-block-2 to any wool

Loot

🔗

Expression

Patterns:
  • [the] loot
Since: 2.7
Requirements: MC 1.16+
Return Type: itemstack
The loot that will be generated in a 'loot generate' event.

Examples:

on loot generate:
    chance of %10
    add 64 diamonds
    send "You hit the jackpot!!"

Lore

🔗

Expression

Patterns:
Since: 2.1
Return Type: string
An item's lore.

Examples:

set the 1st line of the item's lore to "<orange>Excalibur 2.0"

MOTD

🔗

Expression

Patterns:
  • [the] [(default)|(shown|displayed)] (MOTD|message of [the] day)
Since: 2.3
Return Type: string
The message of the day in the server list. This can be changed in a server list ping event only. 'default MOTD' returns the default MOTD always and can't be changed.

Examples:

on server list ping:
    set the motd to "Join now!"

Max Durability

🔗

Expression

Patterns:
Since: 2.5
Return Type:
The maximum durability of an item.

Examples:

maximum durability of diamond sword
if max durability of player's tool is not 0: # Item is damageable

Max Health

🔗

Expression

Patterns:
Since: 2.0
Usable in events: damage, death
Return Type: number
The maximum health of an entity, e.g. 10 for a player.

Examples:

on join:
    set the maximum health of the player to 100
spawn a giant
set the last spawned entity's max health to 1000

Max Minecart Speed

🔗

Expression

Patterns:
  • [the] max[imum] minecart (speed|velocity) of %entities%
  • %entities%'[s] max[imum] minecart (speed|velocity)
Since: 2.5.1
Return Type: number
The maximum speed of a minecart.

Examples:

on right click on minecart:
    set max minecart speed of event-entity to 1

Max Players

🔗

Expression

Patterns:
  • [the] [(real|default)|(fake|shown|displayed)] max[imum] player[s] [count|amount|number|size]
  • [the] [(real|default)|(fake|shown|displayed)] max[imum] (count|amount|number|size) of players
Since: 2.3, 2.7 (modify max real players)
Requirements: Paper 1.16+ (modify max real players)
Return Type:
The count of max players. This can be changed in a server list ping event only. 'real max players' returns the real count of max players of the server and can be modified on Paper 1.16 or later.

Examples:

on server list ping:
    set the max players count to (online players count + 1)

Maximum Freeze Time

🔗

Expression

Patterns:
  • [the] max[imum] freeze time of %entities%
  • %entities%'[s] max[imum] freeze time
Since: 2.7
Return Type: timespan
The maximum amount of time an entity can spend in powdered snow before taking damage.

Examples:

difference between player's freeze time and player's max freeze time is less than 1 second:
    send "you're about to freeze!" to the player

Maximum Stack Size

🔗

Expression

Patterns:
Since: 2.1
Return Type:
The maximum stack size of the specified material, e.g. 64 for torches, 16 for buckets, and 1 for swords.

Examples:

send "You can only pick up %max stack size of player's tool% of %type of (player's tool)%" to player

Me

🔗

Expression

Patterns:
  • me
  • my[self]
Since: 2.1.1
Return Type: player
A 'me' expression that can be used in players' effect commands only.

Examples:

!heal me
!kick myself
!give a diamond axe to me

Mending Repair Amount

🔗

Expression

Patterns:
  • [the] [mending] repair amount
Since: 2.5.1
Return Type:
The number of durability points an item is to be repaired in a mending event. Modifying the repair amount will affect how much experience is given to the player after mending.

Examples:

on item mend:
    set the mending repair amount to 100

Message

🔗

Expression

Patterns:
  • [the] [chat( |-)]message
  • [the] (join|log[ ]in)( |-)message
  • [the] (quit|leave|log[ ]out|kick)( |-)message
  • [the] death( |-)message
Since: 1.4.6 (chat message), 1.4.9 (join & quit messages), 2.0 (death message)
Usable in events: chat, join, quit, death
Return Type: string
The (chat) message of a chat event, the join message of a join event, the quit message of a quit event, or the death message on a death event. This expression is mostly useful for being changed.

Examples:

on chat:
    player has permission "admin"
    set message to "&c%message%"

on first join:
    set join message to "Welcome %player% to our awesome server!"

on join:
    player has played before
    set join message to "Welcome back, %player%!"

on quit:
    set quit message to "%player% left this awesome server!"

on death:
    set the death message to "%player% died!"

Metadata

🔗

Expression

Patterns:
Since: 2.2-dev36
Return Type: object
Metadata is a way to store temporary data on entities, blocks and more that disappears after a server restart.

Examples:

set metadata value "healer" of player to true
broadcast "%metadata value ""healer"" of player%"
clear metadata value "healer" of player

Middle of Location

🔗

Expression

Patterns:
  • [the] (middle|center) [point] of %location%
  • %location%'[s] (middle|center) [point]
Since: 2.6.1
Return Type: location
Returns the middle/center of a location. In other words, returns the middle of the X, Z coordinates and the floor value of the Y coordinate of a location.

Examples:

command /stuck:
    executable by: players
    trigger:
        teleport player to the center of player's location
        send "You're no longer stuck."

Minecart Derailed / Flying Velocity

🔗

Expression

Patterns:
  • [the] [minecart] (derailed|flying) velocity of %entities%
  • %entities%'[s] [minecart] (derailed|flying) velocity
Since: 2.5.1
Return Type: vector
The velocity of a minecart as soon as it has been derailed or as soon as it starts flying.

Examples:

on right click on minecart:
    set derailed velocity of event-entity to vector 2, 10, 2

Money

🔗

Expression

Patterns:
Since: 2.0, 2.5 (offline players)
Requirements: Vault, an economy plugin that supports Vault
Return Type: money
How much virtual money a player has (can be changed).

Examples:

message "You have %player's money%" # the currency name will be added automatically
remove 20$ from the player's balance # replace '$' by whatever currency you use
add 200 to the player's account # or omit the currency altogether

Moon Phase

🔗

Expression

Patterns:
  • [the] (lunar|moon) phase[s] of %worlds%
  • %worlds%'[s] (lunar|moon) phase[s]
Since: 2.7
Requirements: Paper 1.16+
Return Type: moonphase
The current moon phase of a world.

Examples:

if moon phase of player's world is full moon:
    send "Watch for the wolves!"

Moved blocks

🔗

Expression

Patterns:
  • [the] moved blocks
Since: 2.2-dev27
Return Type: block
Blocks which are moved in a piston event. Cannot be used outside of piston events.

Examples:

the moved blocks

Name / Display Name / Tab List Name

🔗

Expression

Patterns:
Since: before 2.1, 2.2-dev20 (inventory name), 2.4 (non-living entity support, changeable inventory name), 2.7 (worlds)
Return Type: string
Represents the Minecraft account, display or tab list name of a player, or the custom name of an item, entity, block, inventory, gamerule or world.

        
  • Players         
                  
    • Name: The Minecraft account name of the player. Can't be changed, but 'display name' can be changed.
    •             
    • Display Name: The name of the player that is displayed in messages. This name can be changed freely and can include color codes, and is shared among all plugins (e.g. chat plugins will use the display name).
    •         
        
  •     
  • Entities         
                  
    • Name: The custom name of the entity. Can be changed. But for living entities, the players will have to target the entity to see its name tag. For non-living entities, the name will not be visible at all. To prevent this, use 'display name'.
    •             
    • Display Name: The custom name of the entity. Can be changed, which will also enable custom name visibility of the entity so name tag of the entity will be visible always.
    •         
        
  •     
  • Items         
                  
    • Name and Display Name: The custom name of the item (not the Minecraft locale name). Can be changed.
    •         
        
  •     
  • Inventories         
                  
    • Name and Display Name: The name/title of the inventory. Changing name of an inventory means opening the same inventory with the same contents but with a different name to its current viewers.
    •         
        
  •     
  • Gamerules (1.13+)         
                  
    • Name: The name of the gamerule. Cannot be changed.
    •         
        
  •     
  • Worlds         
                  
    • Name: The name of the world. Cannot be changed.
    •         
        

Examples:

on join:
    player has permission "name.red"
    set the player's display name to "<red>[admin] <gold>%name of player%"
    set the player's tab list name to "<green>%player's name%"
set the name of the player's tool to "Legendary Sword of Awesomeness"

Name / Display Name / Tab List Name

🔗

Expression

Patterns:
  • [the] ((player|tab)[ ]list name[s]) of %players%
  • %players%'[s] ((player|tab)[ ]list name[s])
Since: before 2.1, 2.2-dev20 (inventory name), 2.4 (non-living entity support, changeable inventory name), 2.7 (worlds)
Return Type: string
Represents the Minecraft account, display or tab list name of a player, or the custom name of an item, entity, block, inventory, gamerule or world.

        
  • Players         
                  
    • Name: The Minecraft account name of the player. Can't be changed, but 'display name' can be changed.
    •             
    • Display Name: The name of the player that is displayed in messages. This name can be changed freely and can include color codes, and is shared among all plugins (e.g. chat plugins will use the display name).
    •         
        
  •     
  • Entities         
                  
    • Name: The custom name of the entity. Can be changed. But for living entities, the players will have to target the entity to see its name tag. For non-living entities, the name will not be visible at all. To prevent this, use 'display name'.
    •             
    • Display Name: The custom name of the entity. Can be changed, which will also enable custom name visibility of the entity so name tag of the entity will be visible always.
    •         
        
  •     
  • Items         
                  
    • Name and Display Name: The custom name of the item (not the Minecraft locale name). Can be changed.
    •         
        
  •     
  • Inventories         
                  
    • Name and Display Name: The name/title of the inventory. Changing name of an inventory means opening the same inventory with the same contents but with a different name to its current viewers.
    •         
        
  •     
  • Gamerules (1.13+)         
                  
    • Name: The name of the gamerule. Cannot be changed.
    •         
        
  •     
  • Worlds         
                  
    • Name: The name of the world. Cannot be changed.
    •         
        

Examples:

on join:
    player has permission "name.red"
    set the player's display name to "<red>[admin] <gold>%name of player%"
    set the player's tab list name to "<green>%player's name%"
set the name of the player's tool to "Legendary Sword of Awesomeness"

Named Item/Inventory

🔗

Expression

Patterns:
Since: 2.0, 2.2-dev34 (inventories)
Return Type: object
Directly names an item/inventory, useful for defining a named item/inventory in a script. If you want to (re)name existing items/inventories you can either use this expression or use set name of <item/inventory> to <text>.

Examples:

give a diamond sword of sharpness 100 named "<gold>Excalibur" to the player
set tool of player to the player's tool named "<gold>Wand"
set the name of the player's tool to "<gold>Wand"
open hopper inventory named "Magic Hopper" to player

Nearest Entity

🔗

Expression

Patterns:
Since: 2.7
Return Type: entity
Gets the entity nearest to a location or another entity.

Examples:

kill the nearest pig and cow relative to player
teleport player to the nearest cow relative to player
teleport player to the nearest entity relative to player

on click:
    kill nearest pig

New Line

🔗

Expression

Patterns:
  • n[ew]l[ine]
  • line[ ]break
Since: 2.5
Return Type: string
Returns a line break separator.

Examples:

send "Hello%nl%Goodbye!" to player

No Damage Ticks

🔗

Expression

Patterns:
Since: 2.5
Return Type:
The number of ticks that an entity is invulnerable to damage for.

Examples:

on damage:
    set victim's invulnerability ticks to 20 #Victim will not take damage for the next second

Now

🔗

Expression

Patterns:
  • now
Since: 1.4
Return Type: date
The current system time of the server. Use time to get the Minecraft time of a world.

Examples:

broadcast "Current server time: %now%"

Number of Characters

🔗

Expression

Patterns:
  • number of upper[ ]case char(acters|s) in %text%
  • number of lower[ ]case char(acters|s) in %text%
  • number of digit char(acters|s) in %text%
Since: 2.5
Return Type:
The number of uppercase, lowercase, or digit characters in a string.

Examples:

#Simple Chat Filter
on chat:
    if number of uppercase chars in message / length of message > 0.5
        cancel event
        send "<red>Your message has to many caps!" to player

Numbers

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] (numbers|integers|decimals) (between|from) %number% (and|to) %number%
Since: 1.4.6 (integers & numbers), 2.5.1 (decimals)
Return Type: number
All numbers between two given numbers, useful for looping. Use 'numbers' if your start is not an integer and you want to keep the fractional part of the start number constant, or use 'integers' if you only want to loop integers. You may also use 'decimals' if you want to use the decimal precision of the start number. You may want to use the 'times' expression instead, for instance 'loop 5 times:'

Examples:

loop numbers from 2.5 to 5.5: # loops 2.5, 3.5, 4.5, 5.5
loop integers from 2.9 to 5.1: # same as '3 to 5', i.e. loops 3, 4, 5
loop decimals from 3.94 to 4: # loops 3.94, 3.95, 3.96, 3.97, 3.98, 3.99, 4

Offline players

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] offline[ ]players
Since: 2.2-dev35
Return Type: offlineplayer
All players that have ever joined the server. This includes the players currently online.

Examples:

send "Size of all players who have joined the server: %size of all offline players%"

Online Player Count

🔗

Expression

Patterns:
  • [the] [((real|default)|(fake|shown|displayed))] [online] player (count|amount|number)
  • [the] [((real|default)|(fake|shown|displayed))] (count|amount|number|size) of online players
Since: 2.3
Return Type:
The amount of online players. This can be changed in a server list ping event only to show fake online player amount. 'real online player count' always returns the real count of online players and can't be changed.

Fake online player count requires PaperSpigot 1.12.2+.

Examples:

on server list ping:
    # This will make the max players count 5 if there are 4 players online.
    set the fake max players count to (online players count + 1)

Opened Inventory

🔗

Expression

Patterns:
  • [the] (current|open|top) inventory [of %players%]
  • %players%'[s] (current|open|top) inventory
Since: 2.2-dev24, 2.2-dev35 (Just 'current inventory' works in player events)
Return Type: inventory
Return the currently opened inventory of a player. If no inventory is open, it returns the own player's crafting inventory.

Examples:

set slot 1 of player's current inventory to diamond sword

Parse

🔗

Expression

Patterns:
Since: 2.0
Return Type: object
Parses text as a given type, or as a given pattern. This expression can be used in two different ways: One which parses the entire text as a single instance of a type, e.g. as a number, and one that parses the text according to a pattern. If the given text could not be parsed, this expression will return nothing and the parse error will be set if some information is available. Some notes about parsing with a pattern: - The pattern must be a Skript pattern, e.g. percent signs are used to define where to parse which types, e.g. put a %number% or %items% in the pattern if you expect a number or some items there. - You have to save the expression's value in a list variable, e.g. set {parsed::*} to message parsed as "...". - The list variable will contain the parsed values from all %types% in the pattern in order. If a type was plural, e.g. %items%, the variable's value at the respective index will be a list variable, e.g. the values will be stored in {parsed::1::*}, not {parsed::1}.

Examples:

set {var} to line 1 parsed as number
on chat:
    set {var::*} to message parsed as "buying %items% for %money%"
    if parse error is set:
        message "%parse error%"
    else if {var::*} is set:
        cancel event
        remove {var::2} from the player's balance
        give {var::1::*} to the player

Parse Error

🔗

Expression

Patterns:
  • [the] [last] [parse] error
Since: 2.0
Return Type: string
The error which caused the last parse operation to fail, which might not be set if a pattern was used and the pattern didn't match the provided text at all.

Examples:

set {var} to line 1 parsed as integer
if {var} is not set:
    parse error is set:
        message "<red>Line 1 is invalid: %last parse error%"
    else:
        message "<red>Please put an integer on line 1!"

Passenger

🔗

Expression

Patterns:
Since: 2.0, 2.2-dev26 (Multiple passengers for 1.11.2+)
Return Type: entity
The passenger of a vehicle, or the rider of a mob. For 1.11.2 and above, it returns a list of passengers and you can use all changers in it. See also: vehicle

Examples:

#for 1.11 and lower
passenger of the minecart is a creeper or a cow
the saddled pig's passenger is a player
#for 1.11.2+
passengers of the minecart contains a creeper or a cow
the boat's passenger contains a pig
add a cow and a zombie to passengers of last spawned boat
set passengers of player's vehicle to a pig and a horse
remove all pigs from player's vehicle
clear passengers of boat

Pi

🔗

Expression

Patterns:
  • (pi|π)
Since: 2.7
Return Type:
Returns the mathematical constant pi. (approx. 3.1415926535)

Examples:

set {_tau} to pi * 2

Pickup Delay

🔗

Expression

Patterns:
Since: 2.7
Return Type: timespan
The amount of time before a dropped item can be picked up by an entity.

Examples:

drop diamond sword at {_location} without velocity
set pickup delay of last dropped item to 5 seconds

Ping

🔗

Expression

Patterns:
Since: 2.2-dev36
Return Type:
Pings of players, as Minecraft server knows them. Note that they will almost certainly be different from the ones you'd get from using ICMP echo requests. This expression is only supported on some server software (PaperSpigot).

Examples:

command /ping :
    trigger:
        send "%arg-1%'s ping is %arg-1's ping%"

Plain Item

🔗

Expression

Patterns:
Since: 2.6
Return Type: itemtype
A plain item is an item with no modifications. It can be used to convert items to their default state or to match with other default items.

Examples:

if the player's tool is a plain diamond: # check if player's tool has no modifications
    send "You are holding a plain diamond!"

Player List Header and Footer

🔗

Expression

Patterns:
  • [the] (player|tab)[ ]list (header|footer) [(text|message)] of %players%
  • %players%'[s] (player|tab)[ ]list (header|footer) [(text|message)]
Since: 2.4
Requirements: Minecraft 1.13 or newer
Return Type: string
The message above and below the player list in the tab menu.

Examples:

set all players' tab list header to "Welcome to the Server!"
send "%the player's tab list header%" to player
reset all players' tab list header

Player Protocol Version

🔗

Expression

Patterns:
Since: 2.6.2
Requirements: Paper 1.12.2 or newer
Return Type:
Player's protocol version. For more information and list of protocol versions visit wiki.vg.

Examples:

command /protocolversion <player>:
    trigger:
        send "Protocol version of %arg-1%: %protocol version of arg-1%"

Player Skull

🔗

Expression

Patterns:
Since: 2.0
Return Type: itemtype
Gets a skull item representing a player. Skulls for other entities are provided by the aliases.

Examples:

give the victim's skull to the attacker
set the block at the entity to the entity's skull

Player Weather

🔗

Expression

Patterns:
  • [the] [(client|custom)] weather of %players%
  • %players%'[s] [(client|custom)] weather
Since: 2.2-dev34
Return Type: weathertype
The weather for a player.

Examples:

set weather of arg-player to rainy
reset player's weather
if arg-player's weather is rainy

Portal

🔗

Expression

Patterns:
  • [the] portal['s] blocks
  • [the] blocks of [the] portal
Since: 2.4
Usable in events: portal_create
Return Type: block
The blocks associated with a portal in the portal creation event.

Examples:

on portal creation:
    loop portal blocks:
        broadcast "%loop-block% is part of a portal!"

Potion Effect

🔗

Expression

Patterns:
  • [new] potion effect of %potion% [potion] [[[of] tier] %number%] [without particles] [for %time span%]
  • [new] ambient potion effect of %potion% [potion] [[[of] tier] %number%] [without particles] [for %time span%]
Since: 2.5.2
Return Type: potioneffect
Create a new potion effect to apply to an entity or item type. Do note that when applying potion effects to tipped arrows/lingering potions, Minecraft reduces the timespan.

Examples:

set {_p} to potion effect of speed of tier 1 without particles for 10 minutes
add {_p} to potion effects of player's tool
add {_p} to potion effects of target entity
add potion effect of speed 1 to potion effects of player

Potion Effect Tier

🔗

Expression

Patterns:
Since: 2.7
Return Type:
An expression to obtain the amplifier of a potion effect applied to an entity.

Examples:

if the amplifier of haste of player >= 3:

Potion Effects

🔗

Expression

Patterns:
Since: 2.5.2
Return Type: potioneffect
Represents the active potion effects of entities and itemtypes. You can clear all potion effects of an entity/itemtype and add/remove a potion effect/type to/from an entity/itemtype. Do note you will not be able to clear the base potion effects of a potion item. In that case, just set the item to a water bottle. When adding a potion effect type (rather than a potion effect), it will default to 15 seconds with tier 1.

Examples:

set {_p::*} to active potion effects of player
clear all the potion effects of player
clear all the potion effects of player's tool
add potion effects of player to potion effects of player's tool
add speed to potion effects of target entity
remove speed and night vision from potion effects of player

Prefix/Suffix

🔗

Expression

Patterns:
  • [the] [chat] (prefix|suffix) of %players%
  • %players%'[s] [chat] (prefix|suffix)
Since: 2.0
Requirements: Vault, a chat plugin that supports Vault
Return Type: string
The prefix or suffix as defined in the server's chat plugin.

Examples:

on chat:
    cancel event
    broadcast "%player's prefix%%player's display name%%player's suffix%: %message%" to the player's world

set the player's prefix to "[<red>Admin] "

Projectile Bounce State

🔗

Expression

Patterns:
  • [the] projectile bounce (state|ability|mode) of %projectiles%
  • %projectiles%'[s] projectile bounce (state|ability|mode)
Since: 2.5.1
Return Type: boolean
A projectile's bounce state.

Examples:

on projectile hit:
    set projectile bounce mode of event-projectile to true

Projectile Critical State

🔗

Expression

Patterns:
  • [the] (projectile|arrow) critical (state|ability|mode) of %projectiles%
  • %projectiles%'[s] (projectile|arrow) critical (state|ability|mode)
Since: 2.5.1
Return Type: boolean
A projectile's critical state. The only currently accepted projectiles are arrows and tridents.

Examples:

on shoot:
    event-projectile is an arrow
    set projectile critical mode of event-projectile to true

Protocol Version

🔗

Expression

Patterns:
  • [the] [server] [(sent|required|fake)] protocol version [number]
Since: 2.3
Usable in events: server list ping
Requirements: Paper 1.12.2 or newer
Return Type:
The protocol version that will be sent as the protocol version of the server in a server list ping event. For more information and list of protocol versions visit wiki.vg. If this protocol version doesn't match with the protocol version of the client, the client will see the version string. But please note that, this expression has no visual effect over the version string. For example if the server uses PaperSpigot 1.12.2, and you make the protocol version 107 (1.9), the version string will not be "Paper 1.9", it will still be "Paper 1.12.2". But then you can customize the version string as you wish. Also if the protocol version of the player is higher than protocol version of the server, it will say "Server out of date!", and if vice-versa "Client out of date!" when you hover on the ping bars.

This can be set in a server list ping event only (increase and decrease effects cannot be used because that wouldn't make sense).

Examples:

on server list ping:
    set the version string to "<light green>Version: <orange>%minecraft version%"
    set the protocol version to 0 # 13w41a (1.7) - so the player will see the custom version string almost always

Random

🔗

Expression

Patterns:
Since: 1.4.9
Return Type: object
Gets a random item out of a set, e.g. a random player out of all players online.

Examples:

give a diamond to a random player out of all players
give a random item out of all items to the player

Random Number

🔗

Expression

Patterns:
  • [a] random (integer|number) (from|between) %number% (to|and) %number%
Since: 1.4
Return Type: number
A random number or integer between two given numbers. Use 'number' if you want any number with decimal parts, or use use 'integer' if you only want whole numbers. Please note that the order of the numbers doesn't matter, i.e. random number between 2 and 1 will work as well as random number between 1 and 2.

Examples:

set the player's health to a random number between 5 and 10
send "You rolled a %random integer from 1 to 6%!" to the player

Random UUID

🔗

Expression

Patterns:
  • [a] random uuid
Since: 2.5.1
Return Type: string
Returns a random UUID.

Examples:

set {_uuid} to random uuid

Raw Name

🔗

Expression

Patterns:
Since: unknown (2.2)
Return Type: string
The raw Minecraft material name of the given item. Note that this is not guaranteed to give same results on all servers.

Examples:

raw name of tool of player

Raw String

🔗

Expression

Patterns:
Since: 2.7
Return Type: string
Returns the string without formatting (colors etc.) and without stripping them from it, e.g. raw "&aHello There!" would output &aHello There!

Examples:

send raw "&aThis text is unformatted!" to all players

Redstone Block Power

🔗

Expression

Patterns:
  • [the] redstone power of %blocks%
  • %blocks%'[s] redstone power
Since: 2.5
Return Type:
Power of a redstone block

Examples:

if redstone power of targeted block is 15:
    send "This block is very powerful!"

Region

🔗

Expression

Patterns:
  • [the] [event-]region
Since: 2.1
Requirements: Supported regions plugin
Return Type: region
The region involved in an event. This expression requires a supported regions plugin to be installed.

Examples:

on region enter:
    region is {forbidden region}
    cancel the event

Region Members & Owners

🔗

Expression

Patterns:
  • [(all|the)] (members|owner[s]) of [[the] region[s]] %regions%
  • [[the] region[s]] %regions%'[s] (members|owner[s])
Since: 2.1
Requirements: Supported regions plugin
Return Type: offlineplayer
A list of members or owners of a region. This expression requires a supported regions plugin to be installed.

Examples:

on entering of a region:
    message "You're entering %region% whose owners are %owners of region%"

Regions At

🔗

Expression

Patterns:
Since: 2.1
Requirements: Supported regions plugin
Return Type: region
All regions at a particular location. This expression requires a supported regions plugin to be installed.

Examples:

On click on a sign:
    line 1 of the clicked block is "[region info]"
    set {_regions::*} to regions at the clicked block
    if {_regions::*} is empty:
        message "No regions exist at this sign."
    else:
        message "Regions containing this sign: <gold>%{_regions::*}%."

Remaining Air

🔗

Expression

Patterns:
Since: unknown (before 2.1)
Return Type: timespan
How much time a player has left underwater before starting to drown.

Examples:

player's remaining air is less than 3 seconds:
    send "hurry, get to the surface!" to the player

Respawn Anchor Charges

🔗

Expression

Patterns:
  • [the] [max[imum]] charge[s] of %blocks%
  • %blocks%'[s] [max[imum]] charge[s]
Since: 2.7
Requirements: Minecraft 1.16+
Return Type:
The charges of a respawn anchor.

Examples:

set the charges of event-block to 3

Respawn location

🔗

Expression

Patterns:
  • [the] respawn location
Since: 2.2-dev35
Return Type: location
The location that a player should respawn at. This is used within the respawn event.

Examples:

on respawn:
    set respawn location to {example::spawn}

Reversed List

🔗

Expression

Patterns:
Since: 2.4
Return Type: object
Reverses given list.

Examples:

set {_list::*} to reversed {_list::*}

Rounding

🔗

Expression

Patterns:
  • [(a|the)] round[ed] down %number%
  • [(a|the)] round[ed] %number%
  • [(a|the)] round[ed] up %number%
Since: 2.0
Return Type:
Rounds numbers normally, up (ceiling) or down (floor) respectively.

Examples:

set {var} to rounded health of player
set line 1 of the block to rounded "%(1.5 * player's level)%"
add rounded down argument to the player's health

Saturation

🔗

Expression

Patterns:
Since: 2.2-Fixes-v10, 2.2-dev35 (fully modifiable), 2.6.2 (syntax pattern changed)
Return Type: number
The saturation of a player. If used in a player event, it can be omitted and will default to event-player.

Examples:

set saturation of player to 20

Scoreboard Tags

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] scoreboard tags of %entities%
  • %entities%'[s] scoreboard tags
Since: 2.3
Return Type: string
Scoreboard tags are simple list of texts stored directly in the data of an entity. So this is a Minecraft related thing, not Bukkit, so the tags will not get removed when the server stops. You can visit visit Minecraft Wiki for more info. This is changeable and valid for any type of entity. Also you can use use the Has Scoreboard Tag condition to check whether an entity has the given tags.

Requires Minecraft 1.11+ (actually added in 1.9 to the game, but added in 1.11 to Spigot).

Examples:

on spawn of a monster:
    if the spawn reason is mob spawner:
        add "spawned by a spawner" to the scoreboard tags of event-entity

on death of a monster:
    if the attacker is a player:
        if the victim doesn't have the scoreboard tag "spawned by a spawner":
            add 1$ to attacker's balance

Script Name

🔗

Expression

Patterns:
  • [the] script[['s] name]
  • name of [the] script
Since: 2.0
Usable in events: Script Load/Unload
Return Type: string
Holds the current script's name (the file name without '.sk').

Examples:

on script load:
    set {running::%script%} to true
on script unload:
    set {running::%script%} to false

Sea Level

🔗

Expression

Patterns:
Since: 2.5.1
Return Type:
Gets the sea level of a world.

Examples:

send "The sea level in your world is %sea level in player's world%"

Sea Pickles

🔗

Expression

Patterns:
  • [the] [(min|max)[imum]] [sea] pickle(s| (count|amount)) of %blocks%
  • %blocks%'[s] [(min|max)[imum]] [sea] pickle(s| (count|amount))
Since: 2.7
Return Type:
An expression to obtain or modify data relating to the pickles of a sea pickle block.

Examples:

on block break:
    type of block is sea pickle
    send "Wow! This stack of sea pickles contained %event-block's sea pickle count% pickles!"
    send "It could've contained a maximum of %event-block's maximum sea pickle count% pickles!"
    send "It had to have contained at least %event-block's minimum sea pickle count% pickles!"
    cancel event
    set event-block's sea pickle count to event-block's maximum sea pickle count
    send "This bad boy is going to hold so many pickles now!!"

Server Icon

🔗

Expression

Patterns:
  • [the] [((default)|(shown|sent))] [server] icon
Since: 2.3
Requirements: Paper 1.12.2 or newer
Return Type: cachedservericon
Icon of the server in the server list. Can be set to an icon that loaded using the load server icon effect, or can be reset to the default icon in a server list ping. 'default server icon' returns the default server icon (server-icon.png) always and cannot be changed.

Examples:

on script load:
    set {server-icons::default} to the default server icon

Sets

🔗

Expression

Patterns:
  • [all [[of] the]|the|every] %*type%
Since: unknown (before 1.4.2), 2.7 (colors)
Return Type: object
Returns a list of all the values of a type; useful for looping.

Examples:

loop all attribute types:
    set loop-value attribute of player to 10
    message "Set attribute %loop-value% to 10!"

Shooter

🔗

Expression

Patterns:
Since: 1.3.7
Return Type: livingentity
The shooter of a projectile.

Examples:

shooter is a skeleton

Shuffled List

🔗

Expression

Patterns:
Since: 2.2-dev32
Return Type: object
Shuffles given list randomly. This is done by replacing indices by random numbers in resulting list.

Examples:

set {_list::*} to shuffled {_list::*}

Sign Text

🔗

Expression

Patterns:
  • [the] line %number% [of %block%]
  • [the] (1st|first|2nd|second|3rd|third|4th|fourth) line [of %block%]
Since: 1.3
Return Type: string
A line of text on a sign. Can be changed, but remember that there is a 16 character limit per line (including color codes that use 2 characters each).

Examples:

on rightclick on sign:
    line 2 of the clicked block is "[Heal]":
        heal the player
    set line 3 to "%player%"

Slot Index

🔗

Expression

Patterns:
Since: 2.2-dev35
Return Type:
Index of an an inventory slot. Other types of slots may or may not have indices. Note that comparing slots with numbers is also possible; if index of slot is same as the number, comparisonsucceeds. This expression is mainly for the cases where you must for some reason save the slot numbers.

Examples:

if index of event-slot is 10:
    send "You bought a pie!"

Sorted List

🔗

Expression

Patterns:
Since: 2.2-dev19
Return Type: object
Sorts given list in natural order. All objects in list must be comparable; if they're not, this expression will return nothing.

Examples:

set {_sorted::*} to sorted {_players::*}

Source Block

🔗

Expression

Patterns:
  • [the] source block
Since: 2.7
Usable in events: Spread
Return Type: block
The source block in a spread event.

Examples:

on spread:
    if the source block is a grass block:
        set the source block to a dirt block

Spawn

🔗

Expression

Patterns:
  • [the] spawn[s] [(point|location)[s]] [of %worlds%]
  • %worlds%'[s] spawn[s] [(point|location)[s]]
Since: 1.4.2
Return Type: location
The spawn point of a world.

Examples:

teleport all players to spawn
set the spawn point of "world" to the player's location

Spawn Reason

🔗

Expression

Patterns:
  • [the] spawn[ing] reason
Since: 2.3
Return Type: spawnreason
The spawn reason in a spawn event.

Examples:

on spawn:
    spawn reason is reinforcements or breeding

Spawner Type

🔗

Expression

Patterns:
  • [the] (spawner|entity|creature) type[s] of %blocks%
  • %blocks%'[s] (spawner|entity|creature) type[s]
Since: 2.4
Return Type: entitydata
Retrieves, sets, or resets the spawner's entity type

Examples:

on right click:
    if event-block is spawner:
        send "Spawner's type is %target block's entity type%"

Special Number

🔗

Expression

Patterns:
  • (NaN|[(-|minus)](infinity|∞)) value
  • value of (NaN|[(-|minus)](infinity|∞))
Since: 2.2-dev32d
Return Type: number
Special number values, namely NaN, Infinity and -Infinity

Examples:

if {_number} is NaN value:

Spectator Target

🔗

Expression

Patterns:
Since: 2.4-alpha4, 2.7 (Paper Spectator Event)
Requirements: Paper
Return Type: entity
Grabs the spectator target entity of the players.

Examples:

on player start spectating of player:
    message "&c%spectator target% currently has %{game::kills::%spectator target%}% kills!" to the player

on player stop spectating:
    past spectator target was a zombie
    set spectator target to the nearest skeleton

Speed

🔗

Expression

Patterns:
  • [the] (walk[ing]|fl(y[ing]|ight))[( |-)]speed of %players%
  • %players%'[s] (walk[ing]|fl(y[ing]|ight))[( |-)]speed
Since: unknown (before 2.1)
Return Type: number
A player's walking or flying speed. Both can be changed, but values must be between -1 and 1 (excessive values will be changed to -1 or 1 respectively). Negative values reverse directions. Please note that changing a player's speed will change their FOV just like potions do.

Examples:

set the player's walk speed to 1
increase the argument's fly speed by 0.1

Substring

🔗

Expression

Patterns:
  • [the] (part|sub[ ](text|string)) of %texts% (between|from) [ind(ex|ices)|character[s]] %number% (and|to) [(index|character)] %number%
  • [the] (first|last) [%number%] character[s] of %texts%
  • [the] %number% (first|last) characters of %texts%
  • [the] character[s] at [(index|position|indexes|indices|positions)] %numbers% (in|of) %texts%
Since: 2.1, 2.5.2 (character at, multiple strings support)
Return Type: string
Extracts part of a text. You can either get the first <x> characters, the last <x> characters, the character at index <x>, or the characters between indices <x> and <y>. The indices <x> and <y> should be between 1 and the length of the text (other values will be fit into this range).

Examples:

set {_s} to the first 5 characters of the text argument
message "%subtext of {_s} from characters 2 to (the length of {_s} - 1)%" # removes the first and last character from {_s} and sends it to the player or console
set {_characters::*} to characters at 1, 2 and 7 in player's display name
send the last character of all players' names

TPS (ticks per second)

🔗

Expression

Patterns:
  • tps from [the] last ([1] minute|1[ ]m[inute])
  • tps from [the] last 5[ ]m[inutes]
  • tps from [the] last 15[ ]m[inutes]
  • [the] tps
Since: 2.2-dev36
Return Type: number
Returns the 3 most recent TPS readings, like the /tps command. This expression is only supported on some server software (PaperSpigot).

Examples:

broadcast "%tps%"

Tamer

🔗

Expression

Patterns:
  • [the] tamer
Since: 2.2-dev25
Return Type: player
The tamer of an entity. Can only be used in entity tame events. You can use 'event-entity' to refer tamed entity itself.

Examples:

on tame:
    if the tamer is a player:
        send "someone tamed something!" to console

Target

🔗

Expression

Patterns:
Since: unknown (before 2.1)
Return Type: entity
For players this is the entity at the crosshair, while for mobs and experience orbs it represents the entity they are attacking/following (if any).

Examples:

on entity target:
    entity's target is a player
    send "You're being followed by an %entity%!" to target of entity

Targeted Block

🔗

Expression

Patterns:
  • [the] target[ed] block[s] [of %players%]
  • %players%'[s] target[ed] block[s]
  • [the] actual[ly] target[ed] block[s] [of %players%]
  • %players%'[s] actual[ly] target[ed] block[s]
Since: 1.0
Return Type: block
The block at the crosshair. This regards all blocks that are not air as fully solid, e.g. torches will be like a solid stone block for this expression.

Examples:

# A command to set the block a player looks at to a specific type:
command /setblock <material>:
    trigger:
        set targeted block to argument

Teleport Cause

🔗

Expression

Patterns:
  • [the] teleport (cause|reason|type)
Since: 2.2-dev35
Return Type: teleportcause
The teleport cause within a player teleport event.

Examples:

on teleport
    teleport cause is nether portal, end portal or end gateway

Temperature

🔗

Expression

Patterns:
  • [the] temperature[s] of %blocks%
  • %blocks%'[s] temperature[s]
Since: 2.2-dev35
Return Type: number
Temperature at given block.

Examples:

message "%temperature of the targeted block%"

Ternary

🔗

Expression

Patterns:
Since: 2.2-dev36
Return Type: object
A shorthand expression for returning something based on a condition.

Examples:

set {points} to 500 if {admin::%player's uuid%} is set else 100

The Egg

🔗

Expression

Patterns:
  • [the] [thrown] egg
Since: 2.7
Usable in events: Egg Throw
Return Type: projectile
The egg thrown in a Player Egg Throw event.

Examples:

spawn an egg at the egg

Time

🔗

Expression

Patterns:
  • [the] time[s] [([with]in|of) %worlds%]
  • %worlds%'[s] time[s]
Since: 1.0
Return Type: time
The time of a world.

Examples:

time in world is between 18:00 and 6:00:
    broadcast "It's night-time, watch out for monsters!"

Time Played

🔗

Expression

Patterns:
Since: 2.5, 2.7 (offline players)
Requirements: MC 1.15+ (offline players)
Return Type: timespan
The amount of time a player has played for on the server. This info is stored in the player's statistics in the main world's data folder. Changing this will also change the player's stats which can be views in the client's statistics menu. Using this expression on offline players on Minecraft 1.14 and below will return nothing <none>.

Examples:

set {_t} to time played of player
if player's time played is greater than 10 minutes:
    give player a diamond sword

set player's time played to 0 seconds

Time Since

🔗

Expression

Patterns:
  • [the] time since %dates%
Since: 2.5
Return Type: timespan
The time that has passed since a date. If the given date is in the future, a value will not be returned.

Examples:

send "%time since 5 minecraft days ago% has passed since 5 minecraft days ago!" to player

Tool

🔗

Expression

Patterns:
  • [the] ((tool|held item|weapon)|(off[ ]hand (tool|item))) [of %living entities%]
  • %living entities%'[s] ((tool|held item|weapon)|(off[ ]hand (tool|item)))
Since: 1.0
Return Type: slot
The item an entity is holding in their main or off hand.

Examples:

player's tool is a pickaxe
player's off hand tool is a shield
set tool of all players to a diamond sword
set offhand tool of target entity to a bow

Type of

🔗

Expression

Patterns:
Since: 1.4, 2.5.2 (potion effect), 2.7 (block datas)
Return Type: object
Type of a block, item, entity, inventory or potion effect. Types of items, blocks and block datas are item types similar to them but have amounts of one, no display names and, on Minecraft 1.13 and newer versions, are undamaged. Types of entities and inventories are entity types and inventory types known to Skript. Types of potion effects are potion effect types.

Examples:

on rightclick on an entity:
    message "This is a %type of clicked entity%!"

UUID

🔗

Expression

Patterns:
Since: 2.1.2, 2.2 (offline players' UUIDs), 2.2-dev24 (other entities' UUIDs)
Return Type: string
The UUID of a player, entity or world. In the future there will be an option to use a player's UUID instead of the name in variable names (i.e. when %player% is used), but for now this can be used. Please note that this expression does not work for offline players if you are under 1.8!

Examples:

# prevents people from joining the server if they use the name of a player
# who has played on this server at least once since this script has been added
on login:
    if {uuid::%name of player%} exists:
        {uuid::%name of player%} is not uuid of player
        kick player due to "Someone with your name has played on this server before"
    else:
        set {uuid::%name of player%} to uuid of player

Unbreakable Items

🔗

Expression

Patterns:
Since: 2.2-dev13b
Return Type: itemtype
Creates unbreakable copies of given items.

Examples:

unbreakable iron sword #Creates unbreakable iron sword

Unix Date

🔗

Expression

Patterns:
Since: 2.5
Return Type: date
Converts given Unix timestamp to a date. The Unix timespan represents the number of seconds elapsed since 1 January 1970.

Examples:

unix date of 946684800 #1 January 2000 12:00 AM (UTC Time)

Unix Timestamp

🔗

Expression

Patterns:
  • [the] unix timestamp of %dates%
  • %dates%'[s] unix timestamp
Since: 2.2-dev31
Return Type: number
Converts given date to Unix timestamp. This is roughly how many seconds have elapsed since 1 January 1970.

Examples:

unix timestamp of now

Value Within

🔗

Expression

Patterns:
Since: 2.7
Return Type: object
Gets the value within objects. Usually used with variables to get the value they store rather than the variable itself, or with lists to get the values of a type.

Examples:

set {_entity} to a random entity out of all entities
delete entity within {_entity} # This deletes the entity itself and not the value stored in the variable

set {_list::*} to "something", 10, "test" and a zombie
broadcast the strings within {_list::*} # "something", "test"

Vectors - Angle Between

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: number
Gets the angle between two vectors.

Examples:

send "%the angle between vector 1, 0, 0 and vector 0, 1, 1%"

Vectors - Arithmetic

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: vector
Arithmetic expressions for vectors.

Examples:

set {_v} to vector 1, 2, 3 // 5
set {_v} to {_v} ++ {_v}
set {_v} to {_v} ++ 5
set {_v} to {_v} -- {_v}
set {_v} to {_v} -- 5
set {_v} to {_v} ** {_v}
set {_v} to {_v} ** 5
set {_v} to {_v} // {_v}
set {_v} to {_v} // 5

Vectors - Create from XYZ

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: vector
Creates a vector from x, y and z values.

Examples:

set {_v} to vector 0, 1, 0

Vectors - Cross Product

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: vector
Gets the cross product between two vectors.

Examples:

send "%vector 1, 0, 0 cross vector 0, 1, 0%"

Vectors - Cylindrical Shape

🔗

Expression

Patterns:
  • [a] [new] cylindrical vector [(from|with)] [radius] %number%, [yaw] %number%(,| and) [height] %number%
Since: 2.2-dev28
Return Type: vector
Forms a 'cylindrical shaped' vector using yaw to manipulate the current point.

Examples:

loop 360 times:
    set {_v} to cylindrical vector radius 1, yaw loop-value, height 2
set {_v} to cylindrical vector radius 1, yaw 90, height 2

Vectors - Dot Product

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: number
Gets the dot product between two vectors.

Examples:

set {_v} to {_v2} dot {_v3}

Vectors - Length

🔗

Expression

Patterns:
  • [the] (vector|standard|normal) length[s] of %vectors%
  • %vectors%'[s] (vector|standard|normal) length[s]
Since: 2.2-dev28
Return Type: number
Gets or sets the length of a vector.

Examples:

send "%standard length of vector 1, 2, 3%"
set {_v} to vector 1, 2, 3
set standard length of {_v} to 2
send "%standard length of {_v}%"

Vectors - Location Vector Offset

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: location
Returns the location offset by vectors.

Examples:

set {_loc} to {_loc} ~ {_v}

Vectors - Normalized

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: vector
Returns the same vector but with length 1.

Examples:

set {_v} to normalized {_v}

Vectors - Random Vector

🔗

Expression

Patterns:
  • [a] random vector
Since: 2.2-dev28, 2.7 (signed components)
Return Type: vector
Creates a random vector.

Examples:

set {_v} to a random vector

Vectors - Spherical Shape

🔗

Expression

Patterns:
  • [new] spherical vector [(from|with)] [radius] %number%, [yaw] %number%(,| and) [pitch] %number%
Since: 2.2-dev28
Return Type: vector
Forms a 'spherical shaped' vector using yaw and pitch to manipulate the current point.

Examples:

loop 360 times:
    set {_v} to spherical vector radius 1, yaw loop-value, pitch loop-value
set {_v} to spherical vector radius 1, yaw 45, pitch 90

Vectors - Squared Length

🔗

Expression

Patterns:
  • [the] squared length[s] of %vectors%
  • %vectors%'[s] squared length[s]
Since: 2.2-dev28
Return Type: number
Gets the squared length of a vector.

Examples:

send "%squared length of vector 1, 2, 3%"

Vectors - Vector Between Locations

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: vector
Creates a vector between two locations.

Examples:

set {_v} to vector between {_loc1} and {_loc2}

Vectors - Vector from Location

🔗

Expression

Patterns:
Since: 2.2-dev28
Return Type: vector
Creates a vector from a location.

Examples:

set {_v} to vector of {_loc}

Vectors - Vector from Pitch and Yaw

🔗

Expression

Patterns:
  • [a] [new] vector (from|with) yaw %number% and pitch %number%
Since: 2.2-dev28
Return Type: vector
Creates a vector from a yaw and pitch value.

Examples:

set {_v} to vector from yaw 45 and pitch 45

Vectors - Velocity

🔗

Expression

Patterns:
Since: 2.2-dev31
Return Type: vector
Gets or changes velocity of an entity.

Examples:

set player's velocity to {_v}

Vectors - XYZ Component

🔗

Expression

Patterns:
  • [the] [vector] (x|y|z) [component[s]] of %vectors%
  • %vectors%'[s] [vector] (x|y|z) [component[s]]
Since: 2.2-dev28
Return Type: number
Gets or changes the x, y or z component of a vector.

Examples:

set {_v} to vector 1, 2, 3
send "%x of {_v}%, %y of {_v}%, %z of {_v}%"
add 1 to x of {_v}
add 2 to y of {_v}
add 3 to z of {_v}
send "%x of {_v}%, %y of {_v}%, %z of {_v}%"
set x component of {_v} to 1
set y component of {_v} to 2
set z component of {_v} to 3
send "%x component of {_v}%, %y component of {_v}%, %z component of {_v}%"

Vehicle

🔗

Expression

Patterns:
Since: 2.0
Return Type: entity
The vehicle an entity is in, if any. This can actually be any entity, e.g. spider jockeys are skeletons that ride on a spider, so the spider is the 'vehicle' of the skeleton. See also: passenger

Examples:

vehicle of the player is a minecart

Version

🔗

Expression

Patterns:
  • ([craft]bukkit|minecraft|skript)( |-)version
Since: 2.0
Return Type: string
The version of Bukkit, Minecraft or Skript respectively.

Examples:

message "This server is running Minecraft %minecraft version% on Bukkit %bukkit version%"
message "This server is powered by Skript %skript version%"

Version String

🔗

Expression

Patterns:
  • [the] [(shown|custom)] version [(string|text)]
Since: 2.3
Usable in events: server list ping
Requirements: Paper 1.12.2 or newer
Return Type: string
The text to show if the protocol version of the server doesn't match with protocol version of the client. You can check the protocol version expression for more information about this. This can only be set in a server list ping event.

Examples:

on server list ping:
    set the protocol version to 0 # 13w41a (1.7), so it will show the version string always
    set the version string to "<light green>Version: <orange>%minecraft version%"

View Distance

🔗

Expression

Patterns:
Since: 2.4
Requirements: Paper
Return Type:
The view distance of a player as set by the server. Can be changed. NOTE: This is the view distance sent by the server to the player. This has nothing to do with client side view distance settings NOTE: This may not work on some versions (such as MC 1.14.x). The return value in this case will be the view distance set in system.properties.

Examples:

set view distance of player to 10
set {_view} to view distance of player
reset view distance of all players
add 2 to view distance of player

View Distance of Client

🔗

Expression

Patterns:
  • [the] client view distance[s] of %players%
  • %players%'[s] client view distance[s]
Since: 2.5
Requirements: 1.13.2+
Return Type:
The view distance of the client. Can not be changed. This differs from the server side view distance of player as this will retrieve the view distance the player has set on their client.

Examples:

set {_clientView} to the client view distance of player
set view distance of player to client view distance of player

Weather

🔗

Expression

Patterns:
Since: 1.0
Usable in events: weather change
Return Type: weathertype
The weather in the given or the current world.

Examples:

set weather to clear
weather in "world" is rainy

Whitelist

🔗

Expression

Patterns:
  • [the] white[ ]list
Since: 2.5.2
Return Type: offlineplayer
A server's whitelist.This expression can be used to add/remove players to/from the whitelist, to enable it and disable it (set whitelist to true / set whitelist to false), and to empty it (reset whitelist)

Examples:

set whitelist to false
add all players to whitelist
reset the whitelist

World

🔗

Expression

Patterns:
Since: 1.0
Return Type: world
The world the event occurred in.

Examples:

world is "world_nether"
teleport the player to the world's spawn
set the weather in the player's world to rain
set {_world} to world of event-chunk

World Environment

🔗

Expression

Patterns:
  • [the] [world] environment of %worlds%
  • %worlds%'[s] [world] environment
Since: 2.7
Return Type: environment
The environment of a world

Examples:

if environment of player's world is nether:
    apply fire resistance to player for 10 minutes

World Seed

🔗

Expression

Patterns:
Since: 2.2-dev35
Return Type:
The seed of given world. Note that it will be returned as Minecraft internally treats seeds, not as you specified it in world configuration.

Examples:

broadcast "Seed: %seed of player's world%"

World from Name

🔗

Expression

Patterns:
  • [the] world [(named|with name)] %text%
Since: 2.6.1
Return Type: world
Returns the world from a string.

Examples:

world named {game::world-name}
the world "world"

Worlds

🔗

Expression

Patterns:
  • [(all [[of] the]|the)] worlds
Since: 1.0
Return Type: world
All worlds of the server, useful for looping.

Examples:

loop all worlds:
    broadcast "You're in %loop-world%" to loop-world

X Times

🔗

Expression

Patterns:
Since: 1.4.6
Return Type:
Integers between 1 and X, used in loops to loop X times.

Examples:

loop 20 times:
    broadcast "%21 - loop-number% seconds left.."
    wait 1 second

X of Item

🔗

Expression

Patterns:
Since: 1.2
Return Type: object
An expression to be able to use a certain amount of items where the amount can be any expression. Please note that this expression is not stable and might be replaced in the future.

Examples:

give level of player of pickaxes to the player

Yaw / Pitch

🔗

Expression

Patterns:
Since: 2.0, 2.2-dev28 (vector yaw/pitch)
Return Type: number
The yaw or pitch of a location or vector.

Examples:

log "%player%: %location of player%, %player's yaw%, %player's pitch%" to "playerlocs.log"
set {_yaw} to yaw of player
set {_p} to pitch of target entity