feat: log system + missing tags + util APIs (v2.2.0)

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

@@ -0,0 +1,15 @@
+# PUBLIC API — mce:api/log/error
+# MCE version: 2.2.0
+#
+# Shorthand: sets lvl=2 (ERROR) then calls mce:api/log/write.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Something went wrong."
+#   function mce:api/log/error
+
+data modify storage mce:log_write lvl set value 2
+function mce:api/log/write

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

@@ -0,0 +1,15 @@
+# PUBLIC API — mce:api/log/info
+# MCE version: 2.2.0
+#
+# Shorthand: sets lvl=0 (INFO) then calls mce:api/log/write.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Something went wrong."
+#   function mce:api/log/info
+
+data modify storage mce:log_write lvl set value 0
+function mce:api/log/write

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

@@ -2,9 +2,8 @@
 # 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.
+# Each entry: [#n] [LEVEL]  message
+# Colors: INFO=white  WARN=yellow  ERROR=red
 # Macro-free. Compatible with Minecraft 1.19.3+.
 #
 # Usage:
@@ -17,8 +16,9 @@ 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)
+# Copy to iteration scratch (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 remove storage mce:log_iter entries

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

@@ -0,0 +1,15 @@
+# PUBLIC API — mce:api/log/warn
+# MCE version: 2.2.0
+#
+# Shorthand: sets lvl=1 (WARN) then calls mce:api/log/write.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Something went wrong."
+#   function mce:api/log/warn
+
+data modify storage mce:log_write lvl set value 1
+function mce:api/log/write

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

@@ -5,42 +5,49 @@
 # 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"
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#   mce:log_write lvl — int, severity level (optional, default: 0)
+#                       0 = INFO  1 = WARN  2 = ERROR
 #
 # Entry format written to mce:log entries[]:
-#   {n: <int>, level: "<string>", msg: "<string>"}
+#   {n: <int>, lvl: <0|1|2>, msg: "<string>"}
+#
+# Convenience helpers that set lvl automatically:
+#   function mce:api/log/info   (sets lvl=0 then calls write)
+#   function mce:api/log/warn   (sets lvl=1 then calls write)
+#   function mce:api/log/error  (sets lvl=2 then calls write)
 #
 # Usage:
 #   data modify storage mce:log_write msg set value "Player joined the arena."
-#   data modify storage mce:log_write level set value "INFO"
+#   data modify storage mce:log_write lvl set value 1
 #   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"
+# Default lvl to 0 (INFO) if not provided
+execute unless data storage mce:log_write lvl run data modify storage mce:log_write lvl set value 0
+
+# Clamp lvl to valid range 0-2
+execute store result score #log.lvl mce.log run data get storage mce:log_write lvl
+execute if score #log.lvl mce.log matches ..0 run scoreboard players set #log.lvl mce.log 0
+execute if score #log.lvl mce.log matches 3..  run scoreboard players set #log.lvl mce.log 0
 
 # 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
+# Append compound entry
+data modify storage mce:log entries append value {n:0, lvl:0, msg:""}
+execute store result storage mce:log entries[-1].n   int 1 run scoreboard players get #log.n   mce.log
+execute store result storage mce:log entries[-1].lvl int 1 run scoreboard players get #log.lvl mce.log
 data modify storage mce:log entries[-1].msg set from storage mce:log_write msg
 
-# Enforce 64-entry cap — drop oldest
+# Enforce 64-entry cap
 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 remove storage mce:log_write

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

@@ -20,7 +20,7 @@ tellraw @s ["",{"text":" data modify storage mce:multi Title set value '{\"text\
 tellraw @s ["",{"text":" data modify storage mce:multi Subtitle set value '{\"text\":\"<subtitle>\"}'","color":"white"}]
 tellraw @s ["",{"text":" data modify storage mce:multi Actionbar set value '{\"text\":\"<text>\"}'","color":"white"}]
 tellraw @s ["",{"text":" data modify storage mce:multi Msg set value '{\"text\":\"<message>\"}'","color":"white"}]
-tellraw @s ["",{"text":" data modify storage mce:multi Cmds set value ["<cmd1>","<cmd2>"]","color":"white"}]
+tellraw @s ["",{"text":" data modify storage mce:multi Cmds set value [\"<cmd1>\",\"<cmd2>\"]","color":"white"}]
 tellraw @s ["",{"text":" function mce:api/multi/run (all keys optional)","color":"gray"}]
 tellraw @s ["",{"text":"--- Queue ---","color":"yellow"}]
 tellraw @s ["",{"text":" data modify storage mce:cmd Command set value \"<cmd>\"","color":"white"}]
@@ -53,9 +53,10 @@ tellraw @s ["",{"text":" data modify storage mce:broadcast Prefix set value \"[T
 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: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":" data modify storage mce:log_write msg set value \"<msg>\"","color":"white"}]
+tellraw @s ["",{"text":" function mce:api/log/info  (lvl 0)","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/warn  (lvl 1)","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/error (lvl 2)","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"}]

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

@@ -1,17 +1,16 @@
 # 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.
+# Branches on entries[0].lvl score: 0=INFO 1=WARN 2=ERROR
 # 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
+# Read lvl of first entry into score
+execute store result score #log.lvl mce.log run data get storage mce:log_iter entries[0].lvl
 
-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"}]
+execute if score #log.lvl mce.log matches 0 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 score #log.lvl mce.log matches 1 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 score #log.lvl mce.log matches 2 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/error.mcfunction

@@ -0,0 +1,15 @@
+# PUBLIC API — mce:api/log/error
+# MCE version: 2.2.0
+#
+# Shorthand: sets lvl=2 (ERROR) then calls mce:api/log/write.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Something went wrong."
+#   function mce:api/log/error
+
+data modify storage mce:log_write lvl set value 2
+function mce:api/log/write

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

@@ -0,0 +1,15 @@
+# PUBLIC API — mce:api/log/info
+# MCE version: 2.2.0
+#
+# Shorthand: sets lvl=0 (INFO) then calls mce:api/log/write.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Something went wrong."
+#   function mce:api/log/info
+
+data modify storage mce:log_write lvl set value 0
+function mce:api/log/write

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

@@ -2,9 +2,8 @@
 # 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.
+# Each entry: [#n] [LEVEL]  message
+# Colors: INFO=white  WARN=yellow  ERROR=red
 # Macro-free. Compatible with Minecraft 1.19.3+.
 #
 # Usage:
@@ -17,8 +16,9 @@ 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)
+# Copy to iteration scratch (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 remove storage mce:log_iter entries

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

@@ -0,0 +1,15 @@
+# PUBLIC API — mce:api/log/warn
+# MCE version: 2.2.0
+#
+# Shorthand: sets lvl=1 (WARN) then calls mce:api/log/write.
+# Macro-free. Compatible with Minecraft 1.19.3+.
+#
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#
+# Usage:
+#   data modify storage mce:log_write msg set value "Something went wrong."
+#   function mce:api/log/warn
+
+data modify storage mce:log_write lvl set value 1
+function mce:api/log/write

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

@@ -5,42 +5,49 @@
 # 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"
+# Input:
+#   mce:log_write msg — string, the log message (required)
+#   mce:log_write lvl — int, severity level (optional, default: 0)
+#                       0 = INFO  1 = WARN  2 = ERROR
 #
 # Entry format written to mce:log entries[]:
-#   {n: <int>, level: "<string>", msg: "<string>"}
+#   {n: <int>, lvl: <0|1|2>, msg: "<string>"}
+#
+# Convenience helpers that set lvl automatically:
+#   function mce:api/log/info   (sets lvl=0 then calls write)
+#   function mce:api/log/warn   (sets lvl=1 then calls write)
+#   function mce:api/log/error  (sets lvl=2 then calls write)
 #
 # Usage:
 #   data modify storage mce:log_write msg set value "Player joined the arena."
-#   data modify storage mce:log_write level set value "INFO"
+#   data modify storage mce:log_write lvl set value 1
 #   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"
+# Default lvl to 0 (INFO) if not provided
+execute unless data storage mce:log_write lvl run data modify storage mce:log_write lvl set value 0
+
+# Clamp lvl to valid range 0-2
+execute store result score #log.lvl mce.log run data get storage mce:log_write lvl
+execute if score #log.lvl mce.log matches ..0 run scoreboard players set #log.lvl mce.log 0
+execute if score #log.lvl mce.log matches 3..  run scoreboard players set #log.lvl mce.log 0
 
 # 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
+# Append compound entry
+data modify storage mce:log entries append value {n:0, lvl:0, msg:""}
+execute store result storage mce:log entries[-1].n   int 1 run scoreboard players get #log.n   mce.log
+execute store result storage mce:log entries[-1].lvl int 1 run scoreboard players get #log.lvl mce.log
 data modify storage mce:log entries[-1].msg set from storage mce:log_write msg
 
-# Enforce 64-entry cap — drop oldest
+# Enforce 64-entry cap
 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 remove storage mce:log_write

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

@@ -20,7 +20,7 @@ tellraw @s ["",{"text":" data modify storage mce:multi Title set value '{\"text\
 tellraw @s ["",{"text":" data modify storage mce:multi Subtitle set value '{\"text\":\"<subtitle>\"}'","color":"white"}]
 tellraw @s ["",{"text":" data modify storage mce:multi Actionbar set value '{\"text\":\"<text>\"}'","color":"white"}]
 tellraw @s ["",{"text":" data modify storage mce:multi Msg set value '{\"text\":\"<message>\"}'","color":"white"}]
-tellraw @s ["",{"text":" data modify storage mce:multi Cmds set value ["<cmd1>","<cmd2>"]","color":"white"}]
+tellraw @s ["",{"text":" data modify storage mce:multi Cmds set value [\"<cmd1>\",\"<cmd2>\"]","color":"white"}]
 tellraw @s ["",{"text":" function mce:api/multi/run (all keys optional)","color":"gray"}]
 tellraw @s ["",{"text":"--- Queue ---","color":"yellow"}]
 tellraw @s ["",{"text":" data modify storage mce:cmd Command set value \"<cmd>\"","color":"white"}]
@@ -53,9 +53,10 @@ tellraw @s ["",{"text":" data modify storage mce:broadcast Prefix set value \"[T
 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: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":" data modify storage mce:log_write msg set value \"<msg>\"","color":"white"}]
+tellraw @s ["",{"text":" function mce:api/log/info  (lvl 0)","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/warn  (lvl 1)","color":"gray"}]
+tellraw @s ["",{"text":" function mce:api/log/error (lvl 2)","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"}]