feat: add missing function tags and new util APIs (v2.1.1)

data/mce/function/api/log/clear.mcfunction

@@ -0,0 +1,11 @@
+# PUBLIC API — mce:api/log/clear
+# MCE version: 2.2.0
+#
+# Clears all log entries from mce:log entries and resets the entry counter.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Usage:
+#   function mce:api/log/clear
+
+data remove storage mce:log entries
+scoreboard players set #log.n mce.log 0

data/mce/function/api/log/show.mcfunction

@@ -0,0 +1,24 @@
+# PUBLIC API — mce:api/log/show
+# MCE version: 2.2.0
+#
+# Prints all current log entries to the caller (@s) via tellraw.
+# Each entry is displayed as: [#n] [LEVEL] message
+# Colors: INFO = white, WARN = yellow, ERROR = red.
+# If the log is empty, prints a notice instead.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Usage:
+#   function mce:api/log/show
+
+execute store result score #log.size mce.log run data get storage mce:log entries
+
+execute if score #log.size mce.log matches 0 run tellraw @s ["",{"text":"[MCE/log] ","color":"aqua"},{"text":"Log is empty.","color":"gray"}]
+execute if score #log.size mce.log matches 0 run return 0
+
+tellraw @s ["",{"text":"=== MCE Log (","color":"gold"},{"score":{"name":"#log.size","objective":"mce.log"}},{"text":" entries) ===","color":"gold"}]
+
+# Copy entries to iteration workspace (preserves originals)
+data modify storage mce:log_iter entries set from storage mce:log entries
+
+function mce:core/log/show_iter
+data remove storage mce:log_iter

data/mce/function/api/log/write.mcfunction

@@ -0,0 +1,46 @@
+# PUBLIC API — mce:api/log/write
+# MCE version: 2.2.0
+#
+# Appends a structured entry to the in-memory log (mce:log entries).
+# The log holds the last 64 entries; oldest is dropped when full.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input (mce:log_write storage):
+#   mce:log_write msg   — string, the log message (required)
+#   mce:log_write level — string, severity level (optional, default: "INFO")
+#                         Valid values: "INFO", "WARN", "ERROR"
+#
+# Entry format written to mce:log entries[]:
+#   {n: <int>, level: "<string>", msg: "<string>"}
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Player joined the arena."
+#   data modify storage mce:log_write level set value "INFO"
+#   function mce:api/log/write
+
+execute unless data storage mce:log_write msg run data modify storage mce:error Last set value "mce:log_write msg is not set — provide a message before calling log/write"
+execute unless data storage mce:log_write msg run data modify storage mce:error Code set value "ERR_NO_MSG"
+execute unless data storage mce:log_write msg run function mce:core/error/raise
+execute unless data storage mce:log_write msg run return 0
+
+# Default level to "INFO" if not provided
+execute unless data storage mce:log_write level run data modify storage mce:log_write level set value "INFO"
+
+# Increment entry counter
+scoreboard players add #log.n mce.log 1
+execute store result storage mce:log_write n int 1 run scoreboard players get #log.n mce.log
+
+# Append entry as compound
+data modify storage mce:log entries append value {n: 0, level: "INFO", msg: ""}
+execute store result storage mce:log entries[-1].n int 1 run scoreboard players get #log.n mce.log
+data modify storage mce:log entries[-1].level set from storage mce:log_write level
+data modify storage mce:log entries[-1].msg set from storage mce:log_write msg
+
+# Enforce 64-entry cap — drop oldest
+execute store result score #log.size mce.log run data get storage mce:log entries
+execute if score #log.size mce.log matches 65.. run data remove storage mce:log entries[0]
+
+# Cleanup input
+data remove storage mce:log_write msg
+data remove storage mce:log_write level
+data remove storage mce:log_write n

data/mce/function/api/util/error_clear.mcfunction

@@ -0,0 +1,22 @@
+# PUBLIC API — mce:api/util/error_clear
+# MCE version: 2.1.1
+#
+# Resets the MCE error state: clears mce:error Last, Code, and Count,
+# and resets the internal error counter scoreboard.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Use this after handling or acknowledging an error so that
+# subsequent error checks start from a clean state.
+#
+# Storage written:
+#   mce:error Last  — removed
+#   mce:error Code  — removed
+#   mce:error Count — reset to 0
+#
+# Usage:
+#   function mce:api/util/error_clear
+
+data remove storage mce:error Last
+data remove storage mce:error Code
+data modify storage mce:error Count set value 0
+scoreboard players set #error.count mce.queue 0

data/mce/function/api/util/help.mcfunction

@@ -1,7 +1,7 @@
 # PUBLIC API — mce:api/util/help
-# MCE version: 2.0.1
+# MCE version: 2.1.1
 
-tellraw @s ["",{"text":"=== MCE v2.0.1 ===","color":"gold"}]
+tellraw @s ["",{"text":"=== MCE v2.1.1 ===","color":"gold"}]
 tellraw @s ["",{"text":"--- Run ---","color":"yellow"}]
 tellraw @s ["",{"text":" data modify storage mce:cmd Command set value \"<cmd>\"","color":"white"}]
 tellraw @s ["",{"text":" function mce:api/run/cmd","color":"gray"}]
@@ -46,13 +46,18 @@ tellraw @s ["",{"text":" function mce:api/util/version","color":"gray"}]
 tellraw @s ["",{"text":" function mce:api/util/announce_times (preset: fast/normal/slow/instant)","color":"gray"}]
 tellraw @s ["",{"text":" function mce:api/util/cancel","color":"gray"}]
 tellraw @s ["",{"text":" function mce:api/util/debug_toggle","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/util/log_clear","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/util/error_clear","color":"gray"}]
 tellraw @s ["",{"text":"--- Broadcast ---","color":"yellow"}]
 tellraw @s ["",{"text":" data modify storage mce:broadcast Prefix set value \"[Tag]\"","color":"white"}]
 tellraw @s ["",{"text":" data modify storage mce:broadcast Msg set value \"<text>\"","color":"white"}]
 tellraw @s ["",{"text":" function mce:api/util/broadcast (Prefix optional)","color":"gray"}]
 tellraw @s ["",{"text":"--- Log ---","color":"yellow"}]
-tellraw @s ["",{"text":" data modify storage mce:cmd Command set value \"<cmd>\"","color":"white"}]
-tellraw @s ["",{"text":" function mce:api/util/log  -> mce:log entries (last 10)","color":"gray"}]
+tellraw @s ["",{"text":" data modify storage mce:log_write msg set value \"<message>\"","color":"white"}]
+tellraw @s ["",{"text":" data modify storage mce:log_write level set value \"INFO|WARN|ERROR\"","color":"white"}]
+tellraw @s ["",{"text":" function mce:api/log/write","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/show","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/clear","color":"gray"}]
 tellraw @s ["",{"text":"--- Error Handling ---","color":"yellow"}]
 tellraw @s ["",{"text":" data get storage mce:error Last","color":"white"}]
 tellraw @s ["",{"text":" data get storage mce:error Code","color":"white"}]

data/mce/function/api/util/log.mcfunction

@@ -1,24 +1,26 @@
 # PUBLIC API — mce:api/util/log
-# MCE version: 2.0.1 (extended)
+# MCE version: 2.2.0
 #
-# Appends the current mce:cmd Command value to an in-memory log list
-# (mce:log entries). Useful for audit trails or debug history.
-# Macro-free. Compatible with Minecraft 1.19.3+.
+# DEPRECATED — use mce:api/log/write instead.
+# This function is kept for backwards compatibility only.
+# It will be removed in a future major version.
 #
-# The log holds the last 10 entries. Older entries are dropped automatically.
+# Appends mce:cmd Command to the log as an INFO entry.
+# Wraps mce:api/log/write internally.
 #
-# Input:
-#   mce:cmd Command — string, the command string to log (required)
+# Usage (legacy):
+#   data modify storage mce:cmd Command set value "some command"
+#   function mce:api/util/log
 #
-# Output:
-#   mce:log entries — list of strings (last 10 commands logged)
+# Preferred:
+#   data modify storage mce:log_write msg set value "some command"
+#   function mce:api/log/write
 
 execute unless data storage mce:cmd Command run data modify storage mce:error Last set value "mce:cmd Command is not set — nothing to log"
 execute unless data storage mce:cmd Command run data modify storage mce:error Code set value "ERR_NO_CMD"
 execute unless data storage mce:cmd Command run function mce:core/error/raise
 execute unless data storage mce:cmd Command run return 0
 
-data modify storage mce:log entries append from storage mce:cmd Command
-
-execute store result score #log.size mce.queue run data get storage mce:log entries
-execute if score #log.size mce.queue matches 11.. run data remove storage mce:log entries[0]
+data modify storage mce:log_write msg set from storage mce:cmd Command
+data modify storage mce:log_write level set value "INFO"
+function mce:api/log/write

data/mce/function/api/util/log_clear.mcfunction

@@ -0,0 +1,13 @@
+# PUBLIC API — mce:api/util/log_clear
+# MCE version: 2.2.0
+#
+# DEPRECATED — use mce:api/log/clear instead.
+# This function is kept for backwards compatibility only.
+#
+# Usage (legacy):
+#   function mce:api/util/log_clear
+#
+# Preferred:
+#   function mce:api/log/clear
+
+function mce:api/log/clear

data/mce/function/api/util/version.mcfunction

@@ -1,5 +1,5 @@
 # PUBLIC API — mce:api/util/version
-# MCE version: 2.0.1
+# MCE version: 2.1.1
 #
 # Writes the current MCE version to storage and prints it to the caller.
 # Output: mce:output Version.string — string ("2.0.1")
@@ -8,6 +8,6 @@
 # Usage:
 # function mce:api/util/version
 
-data modify storage mce:output Version.string set value "2.0.1"
+data modify storage mce:output Version.string set value "2.1.1"
 execute store result storage mce:output Version.numeric int 1 run scoreboard players get #mce load.status
 tellraw @s ["",{"text":"[MCE] ","color":"aqua"},{"text":"Version: ","color":"white"},{"storage":"mce:output","nbt":"Version.string","color":"gold"}]

data/mce/function/core/load.mcfunction

@@ -7,11 +7,14 @@ scoreboard objectives add mce.queue dummy
 scoreboard objectives add mce.tick dummy
 scoreboard objectives add mce.compat dummy
 scoreboard objectives add mce.cd dummy
+scoreboard objectives add mce.log dummy
 
 scoreboard players set #tick mce.tick 0
 scoreboard players set #queue.active mce.compat 0
 scoreboard players set #sched.exists mce.compat 0
 scoreboard players set #error.count mce.queue 0
+scoreboard players set #log.n mce.log 0
+scoreboard players set #log.size mce.log 0
 data remove storage mce:error Last
 data remove storage mce:error Code
 data modify storage mce:error Count set value 0
@@ -23,7 +26,7 @@ data modify storage mce:error Count set value 0
 execute unless data storage mce:config {mce:{debug:1b}} run data modify storage mce:config mce.debug set value 0b
 
 # mce.version: human-readable version string (set on every load)
-data modify storage mce:config mce.version set value "2.0.1"
+data modify storage mce:config mce.version set value "2.1.1"
 
 # mce.queue_interval: ticks between queue executions (read-only reference, hardcoded in core/queue/tick)
 data modify storage mce:config mce.queue_interval set value 3
@@ -36,7 +39,7 @@ data modify storage mce:config mce.queue_interval set value 3
 execute unless data storage mce:config api.announce_default_preset run data modify storage mce:config api.announce_default_preset set value "normal"
 
 # --- LanternLoad: advertise MCE version ---
-# v2.0.1 -> 2000100
-scoreboard players set #mce load.status 2000100
+# v2.1.1 -> 2001100
+scoreboard players set #mce load.status 2001100
 
-tellraw @a ["",{"text":"[MCE] ","color":"aqua"},{"text":"Marker Command Engine v2.0.1 loaded!","color":"white"}]
+tellraw @a ["",{"text":"[MCE] ","color":"aqua"},{"text":"Marker Command Engine v2.1.1 loaded!","color":"white"}]

data/mce/function/core/log/show_iter.mcfunction

@@ -0,0 +1,17 @@
+# Private: not part of MCE public API — subject to change without notice
+# Iterates over mce:log_iter entries, printing each via tellraw (no macros).
+# Reads entries[0], branches on level, then removes it.
+# Compatible with Minecraft 1.19.3+.
+
+execute unless data storage mce:log_iter entries[0] run return 0
+
+# Copy first entry's level to scratch for safe branch (avoid false match on entries[1+])
+data modify storage mce:log_cur level set from storage mce:log_iter entries[0].level
+
+execute if data storage mce:log_cur {level:"INFO"}  run tellraw @s ["",{"text":"[","color":"dark_gray"},{"storage":"mce:log_iter","nbt":"entries[0].n","color":"dark_gray"},{"text":"] ","color":"dark_gray"},{"text":"[INFO]  ","color":"white"},{"storage":"mce:log_iter","nbt":"entries[0].msg","color":"white"}]
+execute if data storage mce:log_cur {level:"WARN"}  run tellraw @s ["",{"text":"[","color":"dark_gray"},{"storage":"mce:log_iter","nbt":"entries[0].n","color":"dark_gray"},{"text":"] ","color":"dark_gray"},{"text":"[WARN]  ","color":"yellow"},{"storage":"mce:log_iter","nbt":"entries[0].msg","color":"yellow"}]
+execute if data storage mce:log_cur {level:"ERROR"} run tellraw @s ["",{"text":"[","color":"dark_gray"},{"storage":"mce:log_iter","nbt":"entries[0].n","color":"dark_gray"},{"text":"] ","color":"dark_gray"},{"text":"[ERROR] ","color":"red"},{"storage":"mce:log_iter","nbt":"entries[0].msg","color":"red"}]
+
+data remove storage mce:log_cur
+data remove storage mce:log_iter entries[0]
+function mce:core/log/show_iter

data/mce/functions/api/log/clear.mcfunction

@@ -0,0 +1,11 @@
+# PUBLIC API — mce:api/log/clear
+# MCE version: 2.2.0
+#
+# Clears all log entries from mce:log entries and resets the entry counter.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Usage:
+#   function mce:api/log/clear
+
+data remove storage mce:log entries
+scoreboard players set #log.n mce.log 0

data/mce/functions/api/log/show.mcfunction

@@ -0,0 +1,24 @@
+# PUBLIC API — mce:api/log/show
+# MCE version: 2.2.0
+#
+# Prints all current log entries to the caller (@s) via tellraw.
+# Each entry is displayed as: [#n] [LEVEL] message
+# Colors: INFO = white, WARN = yellow, ERROR = red.
+# If the log is empty, prints a notice instead.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Usage:
+#   function mce:api/log/show
+
+execute store result score #log.size mce.log run data get storage mce:log entries
+
+execute if score #log.size mce.log matches 0 run tellraw @s ["",{"text":"[MCE/log] ","color":"aqua"},{"text":"Log is empty.","color":"gray"}]
+execute if score #log.size mce.log matches 0 run return 0
+
+tellraw @s ["",{"text":"=== MCE Log (","color":"gold"},{"score":{"name":"#log.size","objective":"mce.log"}},{"text":" entries) ===","color":"gold"}]
+
+# Copy entries to iteration workspace (preserves originals)
+data modify storage mce:log_iter entries set from storage mce:log entries
+
+function mce:core/log/show_iter
+data remove storage mce:log_iter

data/mce/functions/api/log/write.mcfunction

@@ -0,0 +1,46 @@
+# PUBLIC API — mce:api/log/write
+# MCE version: 2.2.0
+#
+# Appends a structured entry to the in-memory log (mce:log entries).
+# The log holds the last 64 entries; oldest is dropped when full.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input (mce:log_write storage):
+#   mce:log_write msg   — string, the log message (required)
+#   mce:log_write level — string, severity level (optional, default: "INFO")
+#                         Valid values: "INFO", "WARN", "ERROR"
+#
+# Entry format written to mce:log entries[]:
+#   {n: <int>, level: "<string>", msg: "<string>"}
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Player joined the arena."
+#   data modify storage mce:log_write level set value "INFO"
+#   function mce:api/log/write
+
+execute unless data storage mce:log_write msg run data modify storage mce:error Last set value "mce:log_write msg is not set — provide a message before calling log/write"
+execute unless data storage mce:log_write msg run data modify storage mce:error Code set value "ERR_NO_MSG"
+execute unless data storage mce:log_write msg run function mce:core/error/raise
+execute unless data storage mce:log_write msg run return 0
+
+# Default level to "INFO" if not provided
+execute unless data storage mce:log_write level run data modify storage mce:log_write level set value "INFO"
+
+# Increment entry counter
+scoreboard players add #log.n mce.log 1
+execute store result storage mce:log_write n int 1 run scoreboard players get #log.n mce.log
+
+# Append entry as compound
+data modify storage mce:log entries append value {n: 0, level: "INFO", msg: ""}
+execute store result storage mce:log entries[-1].n int 1 run scoreboard players get #log.n mce.log
+data modify storage mce:log entries[-1].level set from storage mce:log_write level
+data modify storage mce:log entries[-1].msg set from storage mce:log_write msg
+
+# Enforce 64-entry cap — drop oldest
+execute store result score #log.size mce.log run data get storage mce:log entries
+execute if score #log.size mce.log matches 65.. run data remove storage mce:log entries[0]
+
+# Cleanup input
+data remove storage mce:log_write msg
+data remove storage mce:log_write level
+data remove storage mce:log_write n

data/mce/functions/api/util/error_clear.mcfunction

@@ -0,0 +1,22 @@
+# PUBLIC API — mce:api/util/error_clear
+# MCE version: 2.1.1
+#
+# Resets the MCE error state: clears mce:error Last, Code, and Count,
+# and resets the internal error counter scoreboard.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Use this after handling or acknowledging an error so that
+# subsequent error checks start from a clean state.
+#
+# Storage written:
+#   mce:error Last  — removed
+#   mce:error Code  — removed
+#   mce:error Count — reset to 0
+#
+# Usage:
+#   function mce:api/util/error_clear
+
+data remove storage mce:error Last
+data remove storage mce:error Code
+data modify storage mce:error Count set value 0
+scoreboard players set #error.count mce.queue 0

data/mce/functions/api/util/help.mcfunction

@@ -1,7 +1,7 @@
 # PUBLIC API — mce:api/util/help
-# MCE version: 2.0.1
+# MCE version: 2.1.1
 
-tellraw @s ["",{"text":"=== MCE v2.0.1 ===","color":"gold"}]
+tellraw @s ["",{"text":"=== MCE v2.1.1 ===","color":"gold"}]
 tellraw @s ["",{"text":"--- Run ---","color":"yellow"}]
 tellraw @s ["",{"text":" data modify storage mce:cmd Command set value \"<cmd>\"","color":"white"}]
 tellraw @s ["",{"text":" function mce:api/run/cmd","color":"gray"}]
@@ -46,13 +46,18 @@ tellraw @s ["",{"text":" function mce:api/util/version","color":"gray"}]
 tellraw @s ["",{"text":" function mce:api/util/announce_times (preset: fast/normal/slow/instant)","color":"gray"}]
 tellraw @s ["",{"text":" function mce:api/util/cancel","color":"gray"}]
 tellraw @s ["",{"text":" function mce:api/util/debug_toggle","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/util/log_clear","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/util/error_clear","color":"gray"}]
 tellraw @s ["",{"text":"--- Broadcast ---","color":"yellow"}]
 tellraw @s ["",{"text":" data modify storage mce:broadcast Prefix set value \"[Tag]\"","color":"white"}]
 tellraw @s ["",{"text":" data modify storage mce:broadcast Msg set value \"<text>\"","color":"white"}]
 tellraw @s ["",{"text":" function mce:api/util/broadcast (Prefix optional)","color":"gray"}]
 tellraw @s ["",{"text":"--- Log ---","color":"yellow"}]
-tellraw @s ["",{"text":" data modify storage mce:cmd Command set value \"<cmd>\"","color":"white"}]
-tellraw @s ["",{"text":" function mce:api/util/log  -> mce:log entries (last 10)","color":"gray"}]
+tellraw @s ["",{"text":" data modify storage mce:log_write msg set value \"<message>\"","color":"white"}]
+tellraw @s ["",{"text":" data modify storage mce:log_write level set value \"INFO|WARN|ERROR\"","color":"white"}]
+tellraw @s ["",{"text":" function mce:api/log/write","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/show","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/clear","color":"gray"}]
 tellraw @s ["",{"text":"--- Error Handling ---","color":"yellow"}]
 tellraw @s ["",{"text":" data get storage mce:error Last","color":"white"}]
 tellraw @s ["",{"text":" data get storage mce:error Code","color":"white"}]