-
Notifications
You must be signed in to change notification settings - Fork 27
Command IR Instruction Reference
- Basic Commands and Instructions
- Control Flow
- Events
-
Execute Instructions
exec_alignexec_anchorexec_asexec_at_entityexec_at_entity_posexec_at_posexec_face_entityexec_face_posexec_finishexec_if_blockexec_if_blocksexec_if_cmpexec_if_entityexec_if_varexec_rot_entityexec_rotateexec_runexec_storeexec_store_barexec_store_entityexec_store_varexec_unless_blockexec_unless_blocksexec_unless_cmpexec_unless_entityexec_unless_varexecute
- Function Properties
- NBT Instructions
- Variable Arithmetic Instructions
- Text Instructions
- Type Constructor Instructions
<ret> = as_single_cmd <block>
Forces a basic block to become a single command, the command is returned as a command variable. An error is raised if the block cannot be a single command.
block: BasicBlock The basic block
ret: CmdFunction
bar_set_max <bar>, <max>
Sets the maximum value for a bossbar.
bar: BossbarRef Bar to modify
max: int Max value
bar_set_players <bar>, <players>
Set the players who can see the bossbar.
bar: BossbarRef Bossbar
players: Opt(EntitySelection) Players. If NULL then no players will be shown the bar
bar_set_value <bar>, <val>
Sets the current value of the given bossbar.
bar: BossbarRef Bossbar to modify
val: int Bar value
clear <targets>, <item>, <max_count>
Clears items matching the given item type from targetted entities.
targets: EntitySelection Entities to clear the item from
item: ItemType Item to clear
max_count: int Max count of items. -1 to clear all matching items.
clone <src0>, <src1>, <dest>
Clones a region of blocks specified by a lower left and upper right bound to a given destination position.
src0: Position Lower left position
src1: Position Upper right position
dest: Position Destination position
<ret> = copy <any>
Creates a deep copy of an object. Only certain object types can be copied.
any: NativeType Any object that supports copying
ret: NativeType
<ret> = getter <var>
Returns a command variable that when run, gives the variable's value in the 'result' of the command's execution.
var: Variable The variable to create the getter for
ret: CmdFunction
give <targets>, <item>, <count>
Gives targetted entities an item.
targets: EntitySelection Entities to give the item to
item: ItemType The item to give
count: int Item count
give_effect <target>, <effect>, <seconds>, <amp>, <hide_particles>
Gives target entities the specified effect. See /effect for details.
target: EntitySelection Entities to give the effect to
effect: VirtualString The effect name
seconds: Opt(int) Number of seconds the effect will last
amp: Opt(int) Amplifier
hide_particles: Opt(str) Whether to hide particles (true|false)
join_team <team>, <members>
Adds the specified entities to the given team.
team: TeamRef The team to join
members: Opt(EntitySelection) Members joining the team. If NULL then the current command sender is added.
kill <target>
Despawns the target entities from the world.
target: EntitySelection Entities to despawn
move_to_entity <sources>, <target>
Moves entities to another target entity.
sources: EntitySelection Entities to move
target: EntitySelection Destination entity
pragma <key>, <value>
Set a pragma value. Pragmas are implementation defined and generally should not be configured by end users.
key: str Pragma name
value: VirtualString Pragma value
replace_block_item <pos>, <slot>, <item>, <amount>
Replaces an item in a block's inventory at a specified slot with the
given item. See /replaceitem for details.
pos: Position Block position
slot: VirtualString Inventory slot
item: ItemType Replacement item
amount: Opt(int) Replace amount
replace_entity_item <target>, <slot>, <item>, <amount>
Replaces an item in an entity's inventory at a specified slot with the
given item. See /replaceitem for details.
target: EntitySelection Target entities to replace their items
slot: VirtualString Inventory slot
item: ItemType Replacement item
amount: Opt(int) Replace amount
run_cmd <cmd>
Runs the command given in the command variable.
cmd: CmdFunction The command variable
set_title_times <player>, <fade_in>, <stay>, <fade_out>
Sets the timer parameters for a title being shown to the player.
player: EntitySelection Players to set the times on
fade_in: int Title fade in time
stay: int Title stay time
fade_out: int Title fade out time
setblock <pos>, <block>
Sets a block in the world at the given position to the given block type.
pos: Position The block position
block: BlockType The block type
spawn_entity <entity>, <pos>, <data>
Spawns an entity of the given type at a position.
entity: VirtualString Entity type name
pos: Opt(Position) Position. Defaults to the location of the sender
data: Opt(NBTCompound) Optional NBT data for the entity
spawn_particle <name>, <pos>, <delta>, <speed>, <count>, <mode>, <targets>
Spawn particle effects with the given parameters. See /particle
for details.
name: VirtualString Particle name
pos: Position Position to spawn at
delta: Position Volume to spawn in
speed: float Speed of the particle
count: int Number of particles
mode: str Display mode (normal|force)
targets: Opt(EntitySelection) Players to show the particles to
team_collision <team>, <behaviour>
Sets the collision behavious for a given team.
team: TeamRef Team to modify
behaviour: str Collision behaviour
team_color <team>, <color>
Sets the color for a team.
team: TeamRef Team to modify
color: TextColor Color of the team
teleport <target>, <pos>
Moves target entities to a specified position.
target: EntitySelection Entities to move
pos: Position Position to move to
title <player>, <action>, <text>
Show a title text to the specified players.
player: EntitySelection Players to show to
action: str 'clear' or 'reset', otherwise title|subtitle|actionbar
text: Opt(TextObject) Text to show
tp_with_rot <target>, <pos>, <yrot>, <xrot>
Moves entities to the given position with a specific rotation.
target: EntitySelection Entities to move
pos: Position Position to move to
yrot: (int|float|RelPosVal|AncPosVal) y rotation
xrot: (int|float|RelPosVal|AncPosVal) x rotation
branch <label>
Unconditionally branch to the given label.
label: BasicBlock Destination to branch to
call <label>
'calls' a label instead of branching. The label must be tagged with the 'function' modifier. Control will resume to the next instruction after the label has been executed.
label: BasicBlock Label tagged as a function
clear_command_block
Remove any value from the special command block.
clear_zero_tick
Remove any function from the special zero-tick command block and clear the zero-tick flag.
cmpbr <left>, <op>, <right>, <if_true>, <if_false>
Compare two variables and jump depending on the comparison.
left: Variable Left variable
op: str Operator for comparison, one of: lt|le|eq|ge|gt
right: Variable Right variable
if_true: Opt(FunctionLike) Label to branch if true
if_false: Opt(FunctionLike) Label to branch to otherwise
get_stack_head <dest>
Copies the head of the global stack into the given variable. Do not use in normal circumstances, instead use paramteter passing.
dest: Variable Variable to copy into
invoke <func>, <fnargs>, <retvars>
Invokes a function.
func: VisibleFunction Function to invoke
fnargs: Opt(tuple) Parameters to pass to the function
retvars: Opt(tuple) Tuple of Variables to place return values into
pop_stack
Removes the head of the global stack. Do not use in normal circumstances, instead use parameter passing.
push_function <func>
Push a function pointer to the top of the global stack.
func: FunctionLike Function to push
push_stack_frame <framevals>
(Internal) Create a new stackframe.
framevals: tuple Frame content
push_stack_val <value>
Push a value to the top of the global stack.
value: (Variable|int) Value to push
rangebr <var>, <min>, <max>, <if_true>, <if_false>
Branch to a label depending on the value of a variable.
var: Variable Variable to test
min: Opt(int) Minimum value, or NULL for negative infinity
max: Opt(int) Maximum value, or NULL for positive infinity
if_true: Opt(FunctionLike) Label to jump to if min <= var <= max
if_false: Opt(FunctionLike) Label to jump to otherwise
ret
Return from a function.
set_command_block <func>
Sets the special command block to run the given function on the next tick.
func: FunctionLike Function to run
set_command_block_from_stack
Copies the value from the top of the stack into the special command block.
set_zero_tick_from_stack
Sets the special zero-tick command block to execute the function at the top of the global stack. The function will execute in the same tick once control is returned to the command block.
zero_tick_set <ref>
Sets the special zero-tick command block to the given function or function reference. The function will execute in the same tick once control is returned to the command block.
ref: (Variable|FunctionLike) Function reference
add_event_condition <event>, <path>, <value>
Add a condition to an event that must be true for the event handler to be invoked.
event: EventRef Event to add the condition to
path: VirtualString JSON path in the advancement
value: VirtualString Value that must match
<ret> = event <event_name>
Creates a new event object.
event_name: VirtualString The event name
ret: EventRef
event_handler <handler>, <event>
Add an event handler to the given event specification.
handler: IRFunction Event handler
event: EventRef Event
revoke_event_adv <func>
(Internal) Revokes an advancement to allow an event to re-fire.
func: IRFunction Handler
setupfn <func>
Tags a function as being part of the setup phase. It is called whenever the datapack is reloaded.
func: VisibleFunction The setup function
exec_align <chain>, <axes>
Executes the rest of the chain with the position aligned to the given
axes. See /execute align for details.
chain: ExecChain Execute chain
axes: str Axes
exec_anchor <chain>, <anchor>
Execute the rest of the chain with the anchor position (^) fixed to either feet or eyes of the current entity.
chain: ExecChain Execute chain
anchor: str 'feet' or 'eyes'
exec_as <chain>, <target>
Executes the rest of the chain for each entity matching the given
selection, changing @s to refer to the current matching entity.
chain: ExecChain Execute chain
target: EntitySelection Entities to iterate over
exec_at_entity <chain>, <target>
Executes the rest of the chain for each entity matching the given selection, changing the relative position, rotation and dimension to originate from the matching entity.
chain: ExecChain Execute chain
target: EntitySelection Entities to iterate over
exec_at_entity_pos <chain>, <target>
Executes the rest of the chain using just the position of each matching entity.
chain: ExecChain Execute chain
target: EntitySelection Entities to iterate over
exec_at_pos <chain>, <pos>
Executes the rest of the chain from the given position.
chain: ExecChain Execute chain
pos: Position Position
exec_face_entity <chain>, <target>, <feature>
Executes the rest of the chain with a rotation that faces the given target entity's feature.
chain: ExecChain Execute chain
target: EntitySelection Target entity to face
feature: str 'eyes' or 'feet'
exec_face_pos <chain>, <pos>
Executes the rest of the chain with a rotation that faces the given position.
chain: ExecChain Execute chain
pos: Position Look position
exec_finish <exec>
Finishes an execute chain without running an action. Used when only interested in whether a conditional matched or not.
exec: ExecChain Execute chain
exec_if_block <chain>, <pos>, <block>
Only execute the rest of the chain if the given block specification matches.
chain: ExecChain Execute chain
pos: Position Block position
block: BlockType Block type to test for
exec_if_blocks <chain>, <begin>, <end>, <dest>, <type>
See /execute if blocks.
chain: ExecChain Execute chain
begin: Position Begin position
end: Position End position
dest: Position Test position
type: str all or masked
exec_if_cmp <chain>, <left>, <op>, <right>
Executes the rest of the chain if the left variable relates to the right variable using the given operation.
chain: ExecChain Execute chain
left: Variable Left variable
op: str Operator, one of: lt|le|eq|ge|gt
right: Variable Right variable
exec_if_entity <chain>, <target>
Execute the rest of the chain if at least one entity is found matching the given selection.
chain: ExecChain Execute chain
target: EntitySelection Entities
exec_if_var <chain>, <var>, <min>, <max>
Execute the rest of the chain if the given variable is within the given bounds.
chain: ExecChain Execute chain
var: Variable Variable
min: Opt(int) Minimum value, or NULL for negative infinity
max: Opt(int) Maximum value, or NULL for positive infinity
exec_rot_entity <chain>, <target>
Executes the rest of the chain with the rotation equivalent to the rotation of the given entity.
chain: ExecChain Execute chain
target: EntitySelection Entities to execute with the rotation of
exec_rotate <chain>, <y>, <x>
Executes the rest of the chain with the given rotation.
chain: ExecChain Execute chain
y: (int|float|RelPosVal) Y rotation
x: (int|float|RelPosVal) X rotation
exec_run <exec>, <func>
Finishes the execute chain by running either a command variable, a function label, or a function that takes no parameters.
exec: ExecChain Execute chain
func: (CmdFunction|FunctionLike) Function or command to run
exec_store <chain>, <storetype>, <spec>
Adds an execute store component to the execute chain.
chain: ExecChain Execute chain
storetype: str Either result or success
spec: ExecStoreSpec Execute store specificaion
<ret> = exec_store_bar <bar>, <attr>
Creates an execute store specification that stores into a bossbar.
bar: BossbarRef Bossbar to store into
attr: str Attribute to store into, either 'value' or 'max'
ret: ExecStoreSpec
<ret> = exec_store_entity <target>, <path>, <nbttype>, <scale>
Create an execute store specification that stores into an entity's NBT.
target: EntitySelection Target entity
path: VirtualString NBT path
nbttype: NBTType NBT type
scale: (int|float) Scale before storing
ret: ExecStoreSpec
<ret> = exec_store_var <var>
Creates an execute store specification that stores into a variable.
var: Variable Variable to store into
ret: ExecStoreSpec
exec_unless_block <chain>, <pos>, <block>
Only execute the rest of the chain if the given block specification doesn't match.
chain: ExecChain Execute chain
pos: Position Block position
block: BlockType Block type to test for
exec_unless_blocks <chain>, <begin>, <end>, <dest>, <type>
See /execute unless blocks.
chain: ExecChain Execute chain
begin: Position Begin position
end: Position End position
dest: Position Test position
type: str all or masked
exec_unless_cmp <chain>, <left>, <op>, <right>
Executes the rest of the chain if the left variable doesn't relate to the right variable using the given operation.
chain: ExecChain Execute chain
left: Variable Left variable
op: str Operator, one of: lt|le|eq|ge|gt
right: Variable Right variable
exec_unless_entity <chain>, <target>
Execute the rest of the chain if no entity is found to match the given selection.
chain: ExecChain Execute chain
target: EntitySelection Entities
exec_unless_var <chain>, <var>, <min>, <max>
Execute the rest of the chain if the given variable is not within the given bounds.
chain: ExecChain Execute chain
var: Variable Variable
min: Opt(int) Minimum value, or NULL for negative infinity
max: Opt(int) Maximum value, or NULL for positive infinity
<ret> = execute
Create a new execute chain.
ret: ExecChain
extern
Marks the function as externally visible. The function will not be removed during optimization.
inline
Marks the function as inline-able. invoke calls to this function will result in the body of the function being inserted at the call site
pure_func
Marks the function as a pure function (i.e. no side-effects). No checks are done to ensure it is side-effect free, allowing for functions with irrelevant side-effects (e.g. caching) to be marked as pure.
<ret> = entity_local_nbt <type>, <target>, <path>
Create an NBT variable that references an entity's NBT
type: VarType Variable type
target: EntityRef Target entity
path: VirtualString NBT path
ret: Variable
<ret> = func_ref <func>
Create an NBT compound value that refers to the given function. Caveat: The function must be defined before this instruction is used.
func: FunctionLike Function to create a reference to
ret: NBTCompound
nbt_assign <var>, <nbt>
Sets NBT data on the given variable (which must have type 'nbt').
var: Variable Variable to set the value on
nbt: NBTBase NBT value
<ret> = nbt_compound
Creates a new NBT compound.
ret: NBTCompound
nbt_compound_set <var>, <name>, <val>
Sets a key to the given NBT value in a compound tag.
var: NBTCompound Compound to set on
name: str Key
val: NBTBase Value
<ret> = nbt_data_getter <target>, <path>, <scale>
Creates a command variable that when called, sets the 'result' value to whatever the value at the path is in a block or entity.
target: (BlockRef|EntitySelection) Block or entity to retrieve the value from
path: VirtualString NBT path to the value
scale: float Scale the result before returning
ret: CmdFunction
nbt_data_merge <target>, <data>
Merge the given NBT compound with a block or entity.
target: (BlockRef|EntityRef) Block or entity to merge with
data: NBTCompound Compound tag holding values to merge into the target
<ret> = nbt_list <list_type>
Creates a new NBT list of the given element type.
list_type: Opt(NBTType) Type of elements. NULL leaves the list with an unknown type
ret: NBTList
nbt_list_append <list>, <value>
Appends the given NBT value to an NBT list.
list: NBTList List to append to
value: NBTBase Value to append. The value type must be compatible with the list's element type
nbt_modify_from <target>, <target_path>, <action>, <source>, <source_path>
Modify a block or entity at the given NBT path, performing the given action, choosing the value from a path in another block or entity.
target: (BlockRef|EntitySelection) Block or entity to modify
target_path: VirtualString NBT path to modify
action: str Action, one of: append|insert|merge|prepend|set
source: (BlockRef|EntitySelection) Source entity or block
source_path: VirtualString Path in source
nbt_modify_val <target>, <path>, <action>, <source>
Modify a block or entity at the given NBT path, performing the given action, with the given NBT value.
target: (BlockRef|EntitySelection) Block or entity to modify
path: VirtualString NBT path to modify
action: str Action, one of: append|insert|merge|prepend|set
source: NBTBase Value
<ret> = nbt_val <type>, <value>
Creates an NBT value of the given NBT type and value.
type: NBTType NBT type
value: (NoneType|float|int|VirtualString) Value of this NBT component. Must be valid for the NBT type
ret: NBTBase
nbt_var_append <var>, <nbt>
Appends NBT data to the given nbt variable. The variable must point to an NBT list, else it will fail at runtime.
var: Variable Variable to set the value on
nbt: NBTBase NBT value
<ret> = nbtsubpath <root>, <path>, <vartype>
Create a derivative NBT variable from a sub-path of a parent NBT variable.
root: Variable Original variable
path: VirtualString subpath
vartype: VarType Type of the variable
ret: Variable
<var> = <value>
Sets a variable to a given value.
var: Variable Variable to set the value on
value: (int|Variable|float) Value to set
<dest> <op> <src>
Performs an operation on a destination variable using a
source value. See /scoreboard for details on each operation.
Valid operations are:
+=
/=
%=
>
<
*=
-=
><
dest: Variable Destination for the operation
src: (int|Variable|float) Source for the operation
<ret> = text
Creates a text object.
ret: TextObject
text_append <text>, <value>
Appends the given value to the text object.
text: TextObject Text to append to
value: (VirtualString|int|Variable|TextObject) Value to append
text_click_action <text>, <action>, <value>
Sets the click action on a text object.
text: TextObject Text object
action: str Action, one of: open_url|open_file|change_page
value: VirtualString Value of the action
text_click_func <text>, <action>, <func>
Sets the click action of a text object to run or suggest a function or command.
text: TextObject Text object
action: str Either run or suggest
func: (FunctionLike|CmdFunction) Function or command
text_send <text>, <target>
Sends a text object to target players.
text: TextObject Text to send
target: EntitySelection Players to send the text to
text_style <text>, <prop>, <val>
Sets a style property of a text object.
text: TextObject Text to change the style of
prop: str Style property
val: (str|VirtualString) Style value
add_block_prop <block>, <key>, <value>
Adds a property to the block reference.
block: BlockType Block
key: str Property name
value: VirtualString Property value
add_item_prop <item>, <nbtprop>
Adds an NBT value to the item properties.
item: ItemType Item
nbtprop: NBTCompound NBT value
<ret> = anc_pos <val>
Creates a position component that is relative to the current anchor location (i.e. '^').
val: (float|int) Offset from anchor
ret: AncPosVal
<ret> = block <block_id>
Creates a block type reference.
block_id: VirtualString ID of the block
ret: BlockType
<ret> = bossbar <name>, <display>
Creates a bossbar reference.
name: str Bossbar name
display: TextObject Display text
ret: BossbarRef
<ret> = command <cmd>
Creates a command variable out of a raw command string.
cmd: VirtualString Raw command string
ret: CmdFunction
<ret> = define <type>
Creates a local variable of the given variable type.
type: VarType Variable type
ret: Variable
<ret> = entity_local_access <local>, <target>
Creates a variable whose value depends on the objective and target entities.
local: EntityLocal Scoreboard objective
target: EntitySelection Target entities
ret: Variable
<ret> = global <type>
Creates a global variable of the given variable type.
type: VarType Variable type
ret: Variable
<ret> = item <item_id>
Creates an item reference.
item_id: VirtualString Item ID
ret: ItemType
<ret> = objective <name>, <criteria>
Creates a new objective reference, optionally with some criteria.
name: VirtualString Objective name
criteria: Opt(VirtualString) Criteria. If NULL then it will be 'dummy'
ret: EntityLocal
<ret> = parameter <type>, <passtype>
Add a required parameter of a given type to a function.
type: VarType Parameter type
passtype: str Parameter pass type (byref or byval)
ret: Variable
<ret> = player_ref <name>
Creates a reference to a player name.
name: VirtualString Player name
ret: EntityRef
<ret> = position <x>, <y>, <z>
Create a position variable.
x: (int|float|RelPosVal|AncPosVal) X value
y: (int|float|RelPosVal|AncPosVal) Y value
z: (int|float|RelPosVal|AncPosVal) Z value
ret: Position
<ret> = rel_pos <val>
Create a position component that is relative to the sender (i.e. '~').
val: (float|int) Offset from sender
ret: RelPosVal
<ret> = return <type>
Define a variable to hold a return value of the given type for a function.
type: VarType Return type
ret: Variable
sel_nbt <sel>, <path>, <val>
Adds an NBT specification to the selector. Candidate entities must have the NBT value specified in the given NBT value.
sel: Selector Selector
path: VirtualString Path to NBT, empty string is the root path
val: NBTBase Value that candidate entities must match
select_score_range <sel>, <score>, <min>, <max>
Adds a score range parameter to the selector.
sel: Selector Selector
score: EntityLocal Score
min: Opt(int) Minimum value, or NULL for negative infinity
max: Opt(int) Maximum value, or NULL for positive infinity
<ret> = selector <type>
Creates a new selector object.
type: SelectorType Type of selector (a|e|s|p|r)
ret: EntitySelection
set_block_nbt <block>, <nbt>
Sets NBT data to a block reference.
block: BlockType Block
nbt: NBTCompound NBT value
set_selector <sel>, <key>, <value>
Sets a selector key to the given value.
sel: Selector Selector
key: str Key
value: VirtualString Value
<ret> = team <name>, <display>
Creates a team reference.
name: str Team name
display: Opt(TextObject) Optional display text
ret: TeamRef