feat(command-block): add new command block module

data/datalib/function/api/cb/cancel.mcfunction

@@ -0,0 +1,16 @@
+# datalib:api/cb/cancel
+# ─────────────────────────────────────────────────────────────────
+# Clears all pending delayed CB commands from the queue.
+#
+# No input required. Clears the entire queue.
+#
+# SECURITY: caller must hold dl.perm_level >= security.cmd_min_level.
+#
+# EXAMPLE:
+#   function datalib:api/cb/cancel
+# ─────────────────────────────────────────────────────────────────
+
+execute unless function datalib:core/security/cmd_gate run return 0
+
+data remove storage datalib:engine cb_queue
+data modify storage datalib:engine cb_queue set value []

data/datalib/function/api/cb/internal/apply_defaults.mcfunction

@@ -0,0 +1,5 @@
+# datalib:api/cb/internal/apply_defaults
+# Fills in missing x/y/z fields before the macro call.
+execute unless data storage datalib:input cb.x run data modify storage datalib:input cb.x set value 0
+execute unless data storage datalib:input cb.y run data modify storage datalib:input cb.y set value -64
+execute unless data storage datalib:input cb.z run data modify storage datalib:input cb.z set value 0

data/datalib/function/api/cb/internal/exec.mcfunction

@@ -0,0 +1,14 @@
+# datalib:api/cb/internal/exec
+# Macro: called via "function ... with storage datalib:input cb"
+# Expected keys: cmd (string), x (int), y (int), z (int)
+#
+# Side-effects:
+#   • Writes datalib:engine _cb_last {x,y,z} for the cleanup step.
+#   • Schedules datalib:api/cb/internal/reset 2t later.
+
+$data modify storage datalib:engine _cb_last set value {x:$(x),y:$(y),z:$(z)}
+$forceload add $(x) $(z)
+$setblock $(x) $(y) $(z) minecraft:command_block{Command:"",auto:0b,TrackOutput:0b} replace
+$data modify block $(x) $(y) $(z) Command set value "$(cmd)"
+$data modify block $(x) $(y) $(z) auto set value 1b
+schedule function datalib:api/cb/internal/reset 2t replace

data/datalib/function/api/cb/internal/reset.mcfunction

@@ -0,0 +1,6 @@
+# datalib:api/cb/internal/reset
+# Scheduled 2t after exec — cleans up the temporary command block.
+# Reads coordinates from transient cb_slot storage so reset targets
+# the correct location even if run() was called again in the meantime.
+
+function datalib:api/cb/internal/reset_exec with storage datalib:engine _cb_last

data/datalib/function/api/cb/internal/reset_exec.mcfunction

@@ -0,0 +1,4 @@
+# Macro: receives {x, y, z}
+$data modify block $(x) $(y) $(z) auto set value 0b
+$setblock $(x) $(y) $(z) minecraft:air replace
+$forceload remove $(x) $(z)

data/datalib/function/api/cb/list.mcfunction

@@ -0,0 +1,12 @@
+# datalib:api/cb/list
+# ─────────────────────────────────────────────────────────────────
+# Prints pending queue entries to the executor.
+# Shows each queued command and its remaining ticks.
+# ─────────────────────────────────────────────────────────────────
+
+execute unless function datalib:core/security/cmd_gate run return 0
+
+execute store result score #cb_queue_size dl.tmp run data get storage datalib:engine cb_queue
+execute if score #cb_queue_size dl.tmp matches 0 run tellraw @s [{"text":"[DL/cb] ","color":"#00AAAA","bold":true},{"text":"Queue is empty","color":"gray"}]
+execute unless score #cb_queue_size dl.tmp matches 0 run tellraw @s [{"text":"[DL/cb] Queue (","color":"#00AAAA","bold":true},{"score":{"name":"#cb_queue_size","objective":"dl.tmp"}},{"text":" entries):","color":"#00AAAA","bold":true}]
+execute unless score #cb_queue_size dl.tmp matches 0 run tellraw @s {"nbt":"cb_queue","storage":"datalib:engine","interpret":false}

data/datalib/function/api/cb/queue_size.mcfunction

@@ -0,0 +1,11 @@
+# datalib:api/cb/queue_size
+# ─────────────────────────────────────────────────────────────────
+# Returns the number of pending delayed CB commands.
+# Result is stored in score #cb_queue_size dl.tmp.
+#
+# EXAMPLE:
+#   function datalib:api/cb/queue_size
+#   # read: scoreboard players get #cb_queue_size dl.tmp
+# ─────────────────────────────────────────────────────────────────
+
+execute store result score #cb_queue_size dl.tmp run data get storage datalib:engine cb_queue

data/datalib/function/api/cb/run.mcfunction

@@ -0,0 +1,31 @@
+# datalib:api/cb/run
+# ─────────────────────────────────────────────────────────────────
+# Executes a raw command string via a temporary command block.
+# Zero-delay variant: fires next tick, cleaned up 2t later.
+#
+# INPUT  (storage datalib:input cb):
+#   cmd   (string)  — the command to run  [REQUIRED]
+#   x     (int)     — CB block X          [default: 0]
+#   y     (int)     — CB block Y          [default: -64]
+#   z     (int)     — CB block Z          [default: 0]
+#
+# SECURITY: caller must hold dl.perm_level >= security.cmd_min_level.
+#
+# EXAMPLE:
+#   data modify storage datalib:input cb set value {cmd:"say hello"}
+#   function datalib:api/cb/run
+# ─────────────────────────────────────────────────────────────────
+
+# Security gate
+execute unless function datalib:core/security/cmd_gate run return 0
+
+# Verify required input
+execute unless data storage datalib:input cb.cmd run tellraw @s [{"text":"[DL/cb] ","color":"#00AAAA","bold":true},{"text":"cb.cmd not set","color":"red"}]
+execute unless data storage datalib:input cb.cmd run return 0
+
+# Fill coordinate defaults
+function datalib:api/cb/internal/apply_defaults
+
+# Execute
+function datalib:api/cb/internal/exec with storage datalib:input cb
+data remove storage datalib:input cb

data/datalib/function/api/cb/run_delayed.mcfunction

@@ -0,0 +1,33 @@
+# datalib:api/cb/run_delayed
+# ─────────────────────────────────────────────────────────────────
+# Schedules a command string to execute via command block after a delay.
+#
+# INPUT  (storage datalib:input cb):
+#   cmd     (string)  — the command to run    [REQUIRED]
+#   delay   (int)     — delay in ticks        [REQUIRED, min 1]
+#   x       (int)     — CB block X            [default: 0]
+#   y       (int)     — CB block Y            [default: -64]
+#   z       (int)     — CB block Z            [default: 0]
+#
+# SECURITY: caller must hold dl.perm_level >= security.cmd_min_level.
+#
+# EXAMPLE:
+#   data modify storage datalib:input cb set value {cmd:"say delayed!",delay:40}
+#   function datalib:api/cb/run_delayed
+# ─────────────────────────────────────────────────────────────────
+
+# Security gate
+execute unless function datalib:core/security/cmd_gate run return 0
+
+# Verify required inputs
+execute unless data storage datalib:input cb.cmd run tellraw @s [{"text":"[DL/cb] ","color":"#00AAAA","bold":true},{"text":"cb.cmd not set","color":"red"}]
+execute unless data storage datalib:input cb.cmd run return 0
+execute unless data storage datalib:input cb.delay run tellraw @s [{"text":"[DL/cb] ","color":"#00AAAA","bold":true},{"text":"cb.delay not set","color":"red"}]
+execute unless data storage datalib:input cb.delay run return 0
+
+# Fill coordinate defaults
+function datalib:api/cb/internal/apply_defaults
+
+# Push to delay queue and schedule flush
+function datalib:systems/cb/internal/queue_push with storage datalib:input cb
+data remove storage datalib:input cb

data/datalib/function/api/cb/run_sequence.mcfunction

@@ -0,0 +1,33 @@
+# datalib:api/cb/run_sequence
+# ─────────────────────────────────────────────────────────────────
+# Schedules a list of commands to run sequentially, each separated
+# by a configurable interval.
+#
+# INPUT  (storage datalib:input cb):
+#   cmds      (list of strings) — commands to run  [REQUIRED, min 1]
+#   interval  (int)             — ticks between each command  [default: 2]
+#   x         (int)             — CB block X  [default: 0]
+#   y         (int)             — CB block Y  [default: -64]
+#   z         (int)             — CB block Z  [default: 0]
+#
+# SECURITY: caller must hold dl.perm_level >= security.cmd_min_level.
+#
+# EXAMPLE:
+#   data modify storage datalib:input cb set value {cmds:["say one","say two","say three"],interval:20}
+#   function datalib:api/cb/run_sequence
+# ─────────────────────────────────────────────────────────────────
+
+# Security gate
+execute unless function datalib:core/security/cmd_gate run return 0
+
+# Verify required input
+execute unless data storage datalib:input cb.cmds[0] run tellraw @s [{"text":"[DL/cb] ","color":"#00AAAA","bold":true},{"text":"cb.cmds is empty or not set","color":"red"}]
+execute unless data storage datalib:input cb.cmds[0] run return 0
+
+# Fill defaults
+function datalib:api/cb/internal/apply_defaults
+execute unless data storage datalib:input cb.interval run data modify storage datalib:input cb.interval set value 2
+
+# Expand cmds list into individual delayed queue entries
+function datalib:systems/cb/internal/seq_expand
+data remove storage datalib:input cb

data/datalib/function/api/toggle/cb/false.mcfunction

@@ -0,0 +1,2 @@
+data modify storage datalib:engine modules.cb set value 0b
+tellraw @s [{"text":"[DL] ","color":"#00AAAA","bold":true},{"text":"cb module: ","color":"aqua"},{"text":"disabled","color":"red"}]

data/datalib/function/api/toggle/cb/true.mcfunction

@@ -0,0 +1,2 @@
+data modify storage datalib:engine modules.cb set value 1b
+tellraw @s [{"text":"[DL] ","color":"#00AAAA","bold":true},{"text":"cb module: ","color":"aqua"},{"text":"enabled","color":"green"}]

data/datalib/function/core/tick/queue_systems.mcfunction

@@ -1 +1,4 @@
 function datalib:core/lib/process_queue
+
+# CB delay queue — process pending command block executions
+execute if data storage datalib:engine modules{cb:1b} run execute if data storage datalib:engine cb_queue[0] run function datalib:systems/cb/internal/tick

data/datalib/function/systems/cb/internal/fire_entry.mcfunction

@@ -0,0 +1,8 @@
+# datalib:systems/cb/internal/fire_entry
+# Fires the command in _cb_entry via command block.
+# Reuses api/cb/internal machinery.
+
+# Copy to input storage, reuse exec path
+data modify storage datalib:input cb set from storage datalib:engine _cb_entry
+function datalib:api/cb/internal/exec with storage datalib:input cb
+data remove storage datalib:input cb

data/datalib/function/systems/cb/internal/process_step.mcfunction

@@ -0,0 +1,22 @@
+# datalib:systems/cb/internal/process_step
+# Pops first entry from _cb_work.
+# ticks_left == 1 → fire now.
+# ticks_left > 1  → decrement and return to cb_queue.
+
+# Pop first entry
+data modify storage datalib:engine _cb_entry set from storage datalib:engine _cb_work[0]
+data remove storage datalib:engine _cb_work[0]
+
+# Decrement ticks_left
+execute store result score #cb_tl dl.tmp run data get storage datalib:engine _cb_entry.ticks_left
+scoreboard players remove #cb_tl dl.tmp 1
+
+execute if score #cb_tl dl.tmp matches ..0 run function datalib:systems/cb/internal/fire_entry
+
+execute unless score #cb_tl dl.tmp matches ..0 run execute store result storage datalib:engine _cb_entry.ticks_left int 1 run scoreboard players get #cb_tl dl.tmp
+execute unless score #cb_tl dl.tmp matches ..0 run data modify storage datalib:engine cb_queue append from storage datalib:engine _cb_entry
+
+data remove storage datalib:engine _cb_entry
+
+# Recurse if more entries remain
+execute if data storage datalib:engine _cb_work[0] run function datalib:systems/cb/internal/process_step

data/datalib/function/systems/cb/internal/queue_push.mcfunction

@@ -0,0 +1,7 @@
+# datalib:systems/cb/internal/queue_push
+# Macro: receives {cmd, delay, x, y, z}
+# Appends an entry to datalib:engine cb_queue list.
+# Each entry: {cmd, delay, x, y, z, ticks_left}
+# ticks_left is decremented each tick; fires when it hits 0.
+
+$data modify storage datalib:engine cb_queue append value {cmd:"$(cmd)",x:$(x),y:$(y),z:$(z),ticks_left:$(delay)}

data/datalib/function/systems/cb/internal/seq_expand.mcfunction

@@ -0,0 +1,11 @@
+# datalib:systems/cb/internal/seq_expand
+# Converts cb.cmds list + interval into individual cb_queue entries.
+# Each entry gets ticks_left = (index + 1) * interval.
+
+# Init sequence state
+data modify storage datalib:engine _cb_seq set from storage datalib:input cb
+execute store result score #cb_seq_idx dl.tmp run data get storage datalib:engine _cb_seq.interval
+scoreboard players set #cb_seq_step dl.tmp 0
+
+execute if data storage datalib:engine _cb_seq.cmds[0] run function datalib:systems/cb/internal/seq_expand_loop
+data remove storage datalib:engine _cb_seq

data/datalib/function/systems/cb/internal/seq_expand_loop.mcfunction

@@ -0,0 +1,17 @@
+# datalib:systems/cb/internal/seq_expand_loop
+# Pops first cmd from _cb_seq.cmds, computes its delay, pushes to queue.
+
+# Increment step counter and compute cumulative delay
+scoreboard players add #cb_seq_step dl.tmp 1
+execute store result score #cb_delay dl.tmp run scoreboard players get #cb_seq_step dl.tmp
+scoreboard players operation #cb_delay dl.tmp *= #cb_seq_idx dl.tmp
+
+# Pop cmd from list into scratch
+data modify storage datalib:engine _cb_seq_cmd set from storage datalib:engine _cb_seq.cmds[0]
+data remove storage datalib:engine _cb_seq.cmds[0]
+
+# Write queue entry
+function datalib:systems/cb/internal/seq_push_entry
+
+# Continue if more cmds remain
+execute if data storage datalib:engine _cb_seq.cmds[0] run function datalib:systems/cb/internal/seq_expand_loop

data/datalib/function/systems/cb/internal/seq_push_entry.mcfunction

@@ -0,0 +1,14 @@
+# datalib:systems/cb/internal/seq_push_entry
+# Pushes current sequence step as a cb_queue entry.
+# Reads: _cb_seq_cmd (string), _cb_delay (score), _cb_seq.{x,y,z}
+
+# Build entry storage
+data modify storage datalib:engine _cb_seq_entry set from storage datalib:engine _cb_seq
+data remove storage datalib:engine _cb_seq_entry.cmds
+data remove storage datalib:engine _cb_seq_entry.interval
+data modify storage datalib:engine _cb_seq_entry.cmd set from storage datalib:engine _cb_seq_cmd
+execute store result storage datalib:engine _cb_seq_entry.ticks_left int 1 run scoreboard players get #cb_delay dl.tmp
+
+data modify storage datalib:engine cb_queue append from storage datalib:engine _cb_seq_entry
+data remove storage datalib:engine _cb_seq_entry
+data remove storage datalib:engine _cb_seq_cmd

data/datalib/function/systems/cb/internal/tick.mcfunction

@@ -0,0 +1,11 @@
+# datalib:systems/cb/internal/tick
+# Called each tick when cb_queue is non-empty.
+# Processes all entries: decrements ticks_left, fires those that reach 0.
+
+# Copy queue to work buffer, clear queue, rebuild after processing
+data modify storage datalib:engine _cb_work set from storage datalib:engine cb_queue
+data remove storage datalib:engine cb_queue
+data modify storage datalib:engine cb_queue set value []
+
+execute if data storage datalib:engine _cb_work[0] run function datalib:systems/cb/internal/process_step
+data remove storage datalib:engine _cb_work

data/dl_load/function/load/storages.mcfunction

@@ -128,3 +128,15 @@ execute unless data storage datalib:engine modules.interaction run data modify s
 execute unless data storage datalib:engine modules.perm run data modify storage datalib:engine modules.perm set value 1b
 execute unless data storage datalib:engine modules.wand run data modify storage datalib:engine modules.wand set value 1b
 execute unless data storage datalib:engine modules.geo run data modify storage datalib:engine modules.geo set value 1b
+
+# ─────────────────────────────────────────────────────────────────
+# cb module init
+# cb_queue is always cleared on reload — in-flight delayed commands
+# cannot be safely resumed across a reload boundary.
+# ─────────────────────────────────────────────────────────────────
+data remove storage datalib:engine cb_queue
+data modify storage datalib:engine cb_queue set value []
+data remove storage datalib:engine _cb_last
+data remove storage datalib:engine _cb_work
+data remove storage datalib:engine _cb_entry
+execute unless data storage datalib:engine modules.cb run data modify storage datalib:engine modules.cb set value 1b