Functions & commands

How .mcfunction files work, the full /execute grammar, storing command output, macros, /return, and /schedule — the executable core of every data pack.

.mcfunction files

A function is a plain-text file of commands executed top-to-bottom. Functions are the backbone of a data pack: they are triggered by /function, by function tags (#minecraft:load, #minecraft:tick), by /schedule, by advancement rewards, and by other functions.

Location & naming

Function files live under the function folder of your namespace. The path (minus the .mcfunction extension) becomes the resource id, with subfolders joined by /:

data/<namespace>/function/<name>.mcfunction      # 1.21+ (SINGULAR "function")
data/<namespace>/functions/<name>.mcfunction     # 1.20.6 and earlier (plural)

So data/foo/function/summon/pig.mcfunction has the id foo:summon/pig. Namespaces and paths may use only [a-z0-9_.-] (the path also allows /).

File syntax rules

• One valid command per line, WITHOUT the leading forward slash — write say hi, not /say hi.
• Comments begin a line with #: # this is a comment.
• A line may have leading/trailing tabs and spaces around the command.
• Blank lines are allowed and ignored.
• Line continuation 1.20.2+ — a single backslash \ as the last non-whitespace character continues the command on the next line.
• Macro lines begin with $ (see Macros).

Example — file + call

data/foo/function/greet.mcfunction

# One command per line, no leading slash, comments with #
say Hello from foo:greet
effect give @a minecraft:glowing 5 0 true

# blank line above is fine; next line uses backslash continuation (1.20.2+)
tellraw @a \
    {"text":"Long message split across lines","color":"gold"}

Run it with /function foo:greet.

The /execute grammar

/execute chains modifier subcommands that mutate the execution context (executor @s, position, rotation, dimension, anchor), optional condition subcommands (if/unless), and terminates in exactly one run <command> — or ends after a final condition, which then reports success/fail. The modern grammar dates from the 1.13 rework (17w45a). The context fields a subcommand can change are the executor, execution position, execution rotation, execution dimension, and execution anchor.

Modifier subcommands

Condition subcommands (if / unless)

All support both if (true → continue/succeed) and unless (negated).

Examples

data/foo/function/execute_demo.mcfunction

# Loop over all zombies, at each one's feet check the block below
execute as @e[type=minecraft:zombie] at @s if block ~ ~-1 ~ minecraft:grass_block \
    run particle minecraft:flame ~ ~ ~ 0 0 0 0 1

# Relation: give the vehicle of every player glowing
execute as @a on vehicle run effect give @s minecraft:glowing 3 0 true

# 'if items' with an item predicate (both 1.20.5+): any main-hand item with a damage component
execute if items entity @s weapon.mainhand *[minecraft:damage] run say holding a damageable item

execute store result | success

store captures the terminal command's result (its numeric return value) or success (1 if it succeeded, else 0) into a data sink, evaluated AFTER the run command finishes.

execute store (result|success) <sink> … run <command>

Sinks

Examples

data/foo/function/store_demo.mcfunction

# Count nearby armor stands into a score
execute store result score #count temp run execute if entity @e[type=armor_stand,distance=..10]

# Read an entity's Y-position (×1) into storage as a double
execute store result storage mypack:tmp pos.y double 1 run data get entity @s Pos[1]

# Store command success (0/1) into a block entity flag
execute store success block ~ ~ ~ CustomFlag byte 1 run scoreboard players test #x obj 1 1

Macros 1.20.2+

Macros let a function build commands from runtime data. A macro line starts with $ and contains $(key) placeholders; before each execution the placeholders are substituted from the arguments passed to the function, and the resulting string is parsed as a command at call time. Added in 1.20.2 (23w31a) and unavailable before it.

Syntax

• A macro line must begin with $ as the first character: $say hello $(name).
• Placeholder $(key), where key matches [a-zA-Z0-9_]+.
• Non-$ lines in the same file are normal commands and are NOT substituted.
• Value conversion: numeric NBT values are inserted as plain text with the type suffix removed (e.g. 10b → 10, 3.0d → 3.0). Compounds/lists are inserted as their SNBT text — so you often must re-add quotes/braces yourself in the template.

Calling forms

function <name>                                   # no args (error if the function has macro lines needing args)
function <name> {key:"value", n:10}               # inline SNBT compound as arguments
function <name> with block   <sourcePos> [<path>]  # args = NBT compound read from a block entity
function <name> with entity  <source>   [<path>]  # args = NBT compound read from an entity
function <name> with storage <source>   [<path>]  # args = NBT compound read from command storage

The optional [<path>] narrows to a sub-compound of the source. The source compound's top-level keys become the available $(key) names.

Worked example A — inline compound

data/foo/function/spawn.mcfunction

$summon $(mob) ~ ~ ~ {CustomName:'{"text":"$(name)"}'}

Call it with a compound of arguments:

/function foo:spawn {mob:"minecraft:cow", name:"Bessie"}

Worked example B — with storage (scoreboard → macro)

Build the argument compound in the caller, then invoke the macro function in a separate file:

data/example/function/summon/pig.mcfunction

# 1) build the argument compound in storage from scores
execute store result storage example:macro pos.x int 1 run scoreboard players get X pos
execute store result storage example:macro pos.y int 1 run scoreboard players get Y pos
execute store result storage example:macro pos.z int 1 run scoreboard players get Z pos
# 2) call the macro function, feeding storage path pos
function example:summon/pig_macro with storage example:macro pos

data/example/function/summon/pig_macro.mcfunction

$summon minecraft:pig $(x) $(y) $(z) {Tags:["custom_pig"]}
$tellraw @a "Pig summoned at $(x) $(y) $(z)"

/return 1.20.3+

/return ends the current function immediately and sets the function's success and result (return value). It is how a function reports a value to execute … run function, execute if function, or return run function.

Syntax & semantics

return <value>        # end function, success=true, result = <value> (32-bit int, -2147483648..2147483647)
return fail           # end function, success=false, result = 0
return run <command>  # run <command>, then end function using THAT command's success & result

• Early exit: everything after /return in the function is skipped.
• Forking: inside a forking execute (e.g. as @e … run return …), /return ends the whole function after the first branch that reaches it — a common way to "return the first match."
• execute if function <f> treats the callee as true when its result is non-zero / non-void; a function that never calls /return is void (neither true nor false — counts as 0 for sums).

Example

data/foo/function/is_day.mcfunction

execute unless predicate foo:is_daytime run return fail
return 1

data/foo/function/caller.mcfunction

# Use is_day as a boolean:
execute if function foo:is_day run say It is daytime

# Return the first matching entity's Health, short-circuiting a fork:
execute as @e[tag=target] run return run data get entity @s Health

/schedule

Delays a function to run later, measured in game time. Schedules survive as pending timers and fire during the scheduled-functions phase of a tick.

schedule function <function> <time> [append|replace]
schedule clear <function>

Arguments

Time — a float with a unit suffix:

• t (default) = 1 gametick.
• s = 1 second = 20 gameticks.
• d = 1 in-game day = 24000 gameticks (.5d = 12000t).

append vs replace — the mode for stacking timers on the same function id:

• replace (default): overwrite the existing pending schedule for that function with the new time — only one pending timer per function.
• append: add another independent timer, allowing the same function to have multiple pending schedules at different times.

schedule clear <function> removes all pending schedule(s) for that function id.

Example — a self-rescheduling clock

data/foo/function/clock.mcfunction

say tick every second
schedule function foo:clock 1s replace

Kick it off once from load with function foo:clock. Using replace prevents timer pile-up if clock is ever triggered twice.

Recursion & per-entity loops

A function may call itself. Combined with a terminating condition, this gives you loops without a per-tick counter.

data/foo/function/countdown.mcfunction

# Recurse with a scoreboard guard: stop when #i reaches 0
scoreboard players remove #i foo.loop 1
say counting...
execute if score #i foo.loop matches 1.. run function foo:countdown

Sources

• minecraft.wiki — Function (Java Edition)
• minecraft.wiki — Data pack
• minecraft.wiki — Commands/execute
• minecraft.wiki — Commands/function
• minecraft.wiki — Commands/return
• minecraft.wiki — Commands/schedule
• minecraftcommands.github.io — Move to score