Advanced techniques & tricks

The crown-jewel patterns that turn vanilla data packs into full custom systems — event hooks, raycasting, GUIs, custom crafting, bosses, state machines and the math that powers them, each with a copy-pasteable sketch and the primitives it leans on.

Event detection via advancements

Vanilla has no "on right-click" hook. The community synthesises events by attaching a reward function to an advancement whose criteria fire on a game action, then revoking the advancement immediately so it can fire again. This event loop is the backbone of almost every interaction pack. The full advancement schema lives on the advancements page; this is the event-loop recap.

Common triggers pressed into service as events:

data/example/advancement/right_click.json

{
  "criteria": {
    "click": {
      "trigger": "minecraft:item_used_on_block",
      "conditions": {
        "item": { "items": ["minecraft:stick"] }
      }
    }
  },
  "rewards": { "function": "example:on_click" }
}

data/example/function/on_click.mcfunction

# runs as the player who triggered it
advancement revoke @s only example:right_click
# ... your event logic here ...
say I was clicked!

Raycasting in mcfunction

A ray is simulated by a recursive function that steps forward in small increments using local coordinates (^ ^ ^<step>), checking a stop condition (block ≠ air, or an entity in range) at each step, guarded by a decrementing counter so it can't loop forever.

data/example/function/ray.mcfunction (hand-rolled block raycast)

# start: run as @s at @s anchored eyes, then:
#   scoreboard players set @s ray_steps 50
#   scoreboard players set @s ray_hit 0
#   function example:ray

# function example:ray
execute unless block ~ ~ ~ minecraft:air run function example:hit
scoreboard players remove @s ray_steps 1
execute if score @s ray_steps matches 1.. if score @s ray_hit matches 0 \
    positioned ^ ^ ^0.1 run function example:ray

# function example:hit
scoreboard players set @s ray_hit 1
setblock ~ ~ ~ minecraft:glowstone

Key mechanics: the step size (0.1) trades precision against command count; the counter caps range (50 × 0.1 = 5 blocks); the hit flag short-circuits recursion. For an entity raycast, at each step test execute if entity @e[type=…,distance=..0.3] instead of a block.

Hand-rolled step-marching over- and under-shoots thin hitboxes and ignores real collision shapes (slabs, stairs, fences). Unless you're learning, prefer a library. Iris (Aeldrion) is a precision raycasting library 1.20.3+ that walks real block AABBs:

data/example/function/aim.mcfunction (Iris entry point)

execute as <player> at @s anchored eyes positioned ^ ^ ^ run function iris:get_target
# results land in storage iris:output — target type, coords,
# hit block face, and distance in micrometers

Iris accounts for real block AABBs (ray/plane intersection + back-face culling), supports entity targeting, a configurable MaxRecursionDepth (default 16), block whitelist/blacklist, and a Callback function run at the endpoint — all set through iris:settings storage.

Custom GUIs

Three families of "menu" exist in vanilla-only packs:

• Container menus (chest/hopper/shulker/dropper): open a block or entity inventory, populate slots with clickable custom items, and detect clicks by scanning which slot changed. AjjGUI is the mature take on this.
• Display-entity menus: text_display + item_display entities placed in the world (or, with 1.20.2+ eye-anchored positioning, as a HUD-like overlay), with interaction entities as invisible hitboxes over each "button."
• Book / actionbar / title text as lightweight menus — clickable run_command/suggest_command text components in written books.

AjjGUI lets a mapmaker drag widgets into a shulker/chest boat in-game and compile them — no file editing. Widget types: placeholder, button, counter, switch, radiobutton, itembin, itemslot, scrollbutton. API convention: ajjgui:__<name> is verbose (feedback), ajjgui:_<name> is silent. Install by dropping the pack, running /reload, then /function ajjgui:__install. Menus open per-player, are multiplayer-safe, and don't disturb inventories.

In-game (AjjGUI)

/function ajjgui:__compile                  # build a GUI from the staged widgets
/function ajjgui:_openself {id:"my_menu"}    # open a personalized instance for @s

data/example/function/scan_click.mcfunction (roll-your-own chest menu)

# Give buttons a namespaced custom_data id; while the menu is open,
# scan the container each tick and read whether a tagged button is in slot 0:
execute as @a[tag=menu_open] run \
  execute store result score @s clicked run \
  data get entity @s Inventory[{Slot:0b,components:{"minecraft:custom_data":{btn:1b}}}] 0

Player motion & custom movement

Player velocity can't be written directly with /data the way a mob's Motion can — the client owns player physics. Two approaches: for non-player entities, write Motion:[x,y,z] NBT; for players, use the 1.20.5+ data-driven enchantment impulse / knockback, or a momentary spectator-swap — which is exactly what the player_motion library (MulverineX) automates.

player_motion applies additive velocity to players via a data-driven impulse enchantment (implemented with a saddle-slot / spectator swap so there are no side effects):

data/example/function/dash.mcfunction (player_motion API)

# Local (relative to facing): x = left/right, y = up/down, z = forward.
# 10000 ≈ 1 block/tick. Additive — stacks with current motion.
function player_motion:api/launch_local_xyz {x:0, y:8000, z:15000}
# Global (absolute axes):
function player_motion:api/launch_global_xyz {x:0, y:5000, z:0}

Limits: MSPT/ping can desync continuous forces; it's experimental on Realms and can't be used on mounted or spectator players. Available on smithed.net/packs/player_motion, MIT, pure mcfunction. For a mob, write Motion directly (doubles, applied for one tick):

data/example/function/mob_dash.mcfunction

# Launch a mob straight up; for a directional launch compute
# the components from rotation via trig (see below) or a library:
execute as @e[type=zombie,tag=dash] at @s run \
  data modify entity @s Motion set value [0.0d, 0.4d, 0.0d]

Custom crafting beyond vanilla

Vanilla recipes match custom-component items poorly, so the community uses four patterns:

1. recipe_crafted advancement 1.20+: a dummy shaped/shapeless recipe crafts a placeholder; the minecraft:recipe_crafted trigger (with an ingredients predicate array that can match components) fires a function that swaps the output for the real item. Shows in the recipe book. On 1.21+ results can carry components directly in the recipe JSON.
2. Floor / drop crafting: scan for dropped item entities in a small radius, verify all ingredients are present, despawn them (Age:6000s), summon the result.
3. Container-based crafter: a dropper/dispenser or barrel whose Items NBT is compared against recipe patterns each tick.
4. Smithing / anvil: intercept via minecraft:crafter, or detect smithing-table use with a recipe + trigger.

data/example/advancement/custom_sword.json (recipe_crafted route)

{ "trigger": "minecraft:recipe_crafted",
  "conditions": { "recipe_id": "example:custom_sword",
    "ingredients": [ { "items": ["minecraft:emerald"] },
                     { "items": ["minecraft:diamond"] } ] } }

data/example/function/crafted_sword.mcfunction (reward)

advancement revoke @s only example:crafted_sword
clear @s example:placeholder_result 1
give @s minecraft:netherite_sword[custom_data={custom_sword:true}]

data/example/function/floor_craft.mcfunction (drop crafting, concept)

execute at @a as @e[type=item,distance=..6,nbt={Item:{id:"minecraft:emerald"}}] at @s \
  if block ~ ~ ~ minecraft:air \
  store success entity @s Age short 6000 \
  store success entity @e[type=item,distance=..0.5,limit=1,nbt={Item:{id:"minecraft:diamond"}}] Age short 6000 \
  run summon item ~ ~ ~ {Item:{id:"minecraft:diamond_block",count:1}}

Libraries: Smithed Crafter is the community-standard shared 3×3 so multiple packs coexist; Bookshelf has helpers too.

Custom mobs & bosses

A "custom mob" is a vanilla entity — often armor_stand, marker, interaction, or a re-skinned real mob — driven by functions for AI, attributes for stats, and a bossbar for HP display. Marker/interaction entities are cheap anchors; a visible mob or item_display provides the body.

• Body/AI anchor: armor_stand (equipment/pose), interaction (a real clickable hitbox, 1.19.4+), or a real mob with NoAI:1 moved by functions.
• Stats: attribute @s minecraft:generic.max_health base set 300, plus attack_damage, armor, movement_speed, and scale 1.20.5+.
• HP bar: bossbar add, bossbar set <id> players @a[…], and store result bossbar <id> value from the mob's Health.
• Custom AI: a per-tick execute as @e[tag=boss] at @s run function … doing targeting, ability cooldowns and phase changes via a score.

data/example/function/boss/tick.mcfunction (boss bar wired to health)

# on summon:
#   bossbar add example:king "The Ancient King"
#   bossbar set example:king max 300
#   scoreboard players tag @s add king

# every tick — pull the bar value straight from the mob's Health:
execute as @e[tag=king,limit=1] store result bossbar example:king value \
  run data get entity @s Health 1
execute as @e[tag=king,limit=1] run \
  bossbar set example:king players @a[distance=..40]

Scheduling & self-ticking clocks

Two vanilla mechanisms drive time: the #minecraft:tick function tag (runs every tick) and the schedule command (runs a function after N ticks; append vs replace). A self-scheduling function — one that ends by re-scheduling itself — is the idiomatic clock: a controllable-period loop without a heavy per-tick tag.

data/example/function/loop.mcfunction (self-scheduling clock, every 20 ticks)

# ... periodic work ...
schedule function example:loop 20t replace

data/example/function/tick.mcfunction (per-entity ticking)

execute as @e[tag=custom_mob] at @s run function example:mob_tick

Kick loops off from #minecraft:load (or Lantern Load's #load:load), not from #tick directly, so a /reload re-arms them cleanly.

Hitbox detection with interaction entities

Two ways to know "is something here":

• Interaction entities 1.19.4+: invisible entities with a real width/height hitbox that record who clicked/attacked them in their interaction/attack NBT compounds (each holds {player:UUID, timestamp}). Scan those to detect clicks precisely, per-hitbox.
• Area scanning: execute positioned … if entity @e[distance=..r] or if block sweeps; combine with dx dy dz volume selectors for box checks.

data/example/function/buttons.mcfunction (interaction-entity click detection)

# each tick, find interaction entities that were right-clicked, then clear
# the NBT so they can fire again:
execute as @e[type=interaction,tag=button] \
  if data entity @s interaction run function example:button_pressed
execute as @e[type=interaction,tag=button] run data remove entity @s interaction

data/example/function/zone.mcfunction (volume test)

execute positioned 100 64 100 if entity @e[type=player,dx=5,dy=3,dz=5] run function example:in_zone

State machines via storage & macros

data storage holds structured, typed state (nested compounds/lists) that scoreboards can't. Macros 1.20.2+ template a function's commands from storage/arguments ($(key)), so you can dispatch to different "states" and parameterise behaviour — a genuine state machine.

data/example/function/fsm/step.mcfunction (macro dispatch)

# input: {state:"charging", power:3}
$function example:fsm/state_$(state) {power:$(power)}

data/example/function/fsm/state_charging.mcfunction

$scoreboard players add @s power_meter $(power)
data modify storage example:fsm state set value "release"

Keep the whole machine in one storage path so it's atomic and inspectable; each tick, read it, run the matching state function via macro, and write the next state back.

Fixed-point math & trig

Scoreboards are integers only, so decimals are emulated by scaling (store x×1000, remember the implied divisor). Trig comes from lookup tables, polynomial approximations (Bhaskara), or the classic teleport trick — rotate an entity by the angle and read its facing-vector components as sine/cosine.

data/example/function/scale.mcfunction (fixed-point arithmetic)

# represent 3.14159 as 3142 (×1000); multiply two scaled values then re-divide:
scoreboard players operation #a math = #pi math          # 3142  (= 3.142)
scoreboard players operation #a math *= #radius math     # * 5 -> 15710 (= 15.710)
# read a decimal NBT value into a score at scale 1000:
execute store result score #y math run data get entity @s Pos[1] 1000

data/example/function/sin_trick.mcfunction (sine via teleport trick)

# rotate a marker to the angle, then read its local forward vector:
execute as @e[tag=trig,limit=1] rotated <angle> 0 positioned ^ ^ ^1 \
  store result score #sin math run data get entity @s Pos[0] 1000   # x-offset ~ sin

The Bookshelf math module provides sin/cos/tan/asin/acos/atan/atan2 (degrees), sincos, exp/log (bases e/2/10/arbitrary), integer & decimal pow/sqrt, factorial (0–12), gcd, and combinations. Fixed-point convention: angle inputs ×100, trig outputs ×1000.

data/example/function/bs_sin.mcfunction (Bookshelf)

scoreboard players set $math.sin.x bs.in 4200   # 42.00 degrees
function #bs.math:sin
# result in bs.out, scaled x1000

Best practices

data/yourpack/function/load.mcfunction

execute if score dep_pack load.status matches 1.. run function yourpack:init
# yourpack:init — create objectives, seed storage, then schedule the loop
scoreboard objectives add yp.timer dummy
schedule function yourpack:tick 1t replace

Pitfalls & workarounds

Sources

• MCC wiki — questions hub
• MCC wiki — item click & interaction entities
• MCC wiki — raycast
• MCC wiki — custom crafting
• Iris raycasting library (Aeldrion)
• AjjGUI
• player_motion (MulverineX) · smithed.net/packs/player_motion
• Smithed libraries (Crafter, Damage, …)
• Bookshelf documentation (math, raycast)
• Lantern Load
• moxlib
• minecraft.wiki — Data pack