diff --git a/.github/README.md b/.github/README.md index 1a7b2c1..f750ae6 100644 --- a/.github/README.md +++ b/.github/README.md @@ -22,6 +22,7 @@ - **Per-player cooldown system** — macro-free, scoreboard-based - **Run at fixed world coordinates** — execute commands from any integer coordinate - **Announce system** — title, subtitle, and actionbar in a single call +- **Structured log system** — write/show/clear with severity levels - **Version query API** — check MCE version from storage at runtime - **LanternLoad integrated** — other packs can depend on MCE with guaranteed load order - Versioned API (`load.status` score for dependency checks) @@ -37,7 +38,7 @@ 1. Download the latest release zip. 2. Place the `marker-command-engine` folder into your world's `datapacks/` folder. 3. Run `/reload`. -4. You should see `[MCE] Marker Command Engine v2.0.0 loaded!` in chat. +4. You should see `[MCE] Marker Command Engine v2.2.0 loaded!` in chat. --- @@ -57,7 +58,7 @@ function mce:api/run/cmd tag @a[name=Steve,limit=1] add mce.executor # Set the command and call -data modify storage mce:cmd Command set value "say I am Steve!" +data modify storage mce:cmd Command set value "execute as @a[tag=mce.executor] run say I am Steve!" function mce:api/run/as # mce.executor tag is removed automatically ``` @@ -141,13 +142,41 @@ data modify storage mce:announce Title set value "Go!" function mce:api/util/announce ``` +### Log + +```mcfunction +# Write an entry using level shorthands (recommended) +data modify storage mce:log_write msg set value "Player joined the arena." +function mce:api/log/info # severity 0 — white + +data modify storage mce:log_write msg set value "Cooldown nearly expired." +function mce:api/log/warn # severity 1 — yellow + +data modify storage mce:log_write msg set value "Command failed." +function mce:api/log/error # severity 2 — red + +# Or set lvl manually and call write +data modify storage mce:log_write msg set value "Custom entry." +data modify storage mce:log_write lvl set value 1 +function mce:api/log/write + +# Show all entries to @s (colored by level) +function mce:api/log/show + +# Clear all entries +function mce:api/log/clear +``` + +The log holds the last **64 entries**. Older entries are dropped automatically. +Each entry is stored as `{n: , lvl: <0|1|2>, msg: ""}`. + ### Version ```mcfunction # Prints version to chat and writes to storage. function mce:api/util/version -# mce:output Version.string -> "2.0.0" -# mce:output Version.numeric -> 2000000 +# mce:output Version.string -> "2.2.0" +# mce:output Version.numeric -> 2002000 ``` ### Help @@ -201,6 +230,17 @@ Only `mce:api/*` functions are part of the public API. All `mce:core/*` function | `mce:api/cooldown/clear` | 1.19.3+ | Clear cooldown for `@s` immediately | | `mce:api/cooldown/get` | 1.19.3+ | Write remaining ticks to `mce:output Cooldown.remaining` | +### `mce:api/log/` + +| Function | Description | +|---|---| +| `mce:api/log/write` | Append entry from `mce:log_write {msg, lvl}` | +| `mce:api/log/info` | Shorthand: write with `lvl=0` (INFO) | +| `mce:api/log/warn` | Shorthand: write with `lvl=1` (WARN) | +| `mce:api/log/error` | Shorthand: write with `lvl=2` (ERROR) | +| `mce:api/log/show` | Print all entries to `@s` (colored by level) | +| `mce:api/log/clear` | Clear all entries and reset counter | + ### `mce:api/util/` | Function | Description | @@ -211,6 +251,10 @@ Only `mce:api/*` functions are part of the public API. All `mce:core/*` function | `mce:api/util/cancel` | Abort active command execution (does not affect queue) | | `mce:api/util/debug_toggle` | Toggle debug output on/off | | `mce:api/util/help` | Print usage in chat | +| `mce:api/util/broadcast` | Send message to all players from `mce:broadcast {Msg, Prefix}` | +| `mce:api/util/error_clear` | Reset `mce:error` state and counter | + +> `mce:api/util/log` and `mce:api/util/log_clear` are deprecated — use `mce:api/log/*` instead. --- @@ -227,9 +271,9 @@ To make your pack load after MCE, add your load function to `#load:post_load` an ```mcfunction # yourpack:load -# Require MCE v2.0.0+ (score format: major*1000000 + minor*1000 + patch) -execute unless score mce load.status matches 2000000.. run tellraw @a {"text":"[YourPack] ERROR: MCE v2.0.0+ required!","color":"red"} -execute unless score mce load.status matches 2000000.. run return 0 +# Require MCE v2.2.0+ (score format: major*1000000 + minor*1000 + patch) +execute unless score mce load.status matches 2002000.. run tellraw @a {"text":"[YourPack] ERROR: MCE v2.2.0+ required!","color":"red"} +execute unless score mce load.status matches 2002000.. run return 0 # Your init here... ``` @@ -242,7 +286,7 @@ execute unless score mce load.status matches 2000000.. run return 0 - **Command block position**: `0 -64 0` - **Reset delay**: 3 ticks after execution - **Queue interval**: 3 ticks between commands -- **Version score**: `mce load.status` = `2000000` (v2.0.0) +- **Version score**: `mce load.status` = `2002000` (v2.2.0) ## Storage Reference @@ -257,24 +301,34 @@ execute unless score mce load.status matches 2000000.. run return 0 | `mce:queue` | `commands` | List | Pending queue commands | | `mce:batch` | `commands` | List | Batch staging area | | `mce:schedule` | `jobs` | List | Scheduled job list | -| `mce:config` | `debug` | Byte | Debug mode flag (`1b` = on) | +| `mce:config` | `mce.debug` | Byte | Debug mode flag (`1b` = on) | +| `mce:config` | `mce.version` | String | MCE version string | | `mce:announce` | `Title` | String | Title text for `util/announce` | | `mce:announce` | `Subtitle` | String | Subtitle text for `util/announce` | | `mce:announce` | `Actionbar` | String | Actionbar text for `util/announce` | | `mce:announce_times` | `Preset` | String | Timing preset: `fast` `normal` `slow` `instant` | +| `mce:log_write` | `msg` | String | Message to write (input for `log/write`) | +| `mce:log_write` | `lvl` | Int | Severity level: `0`=INFO `1`=WARN `2`=ERROR | +| `mce:log` | `entries` | List | Log entries: `{n, lvl, msg}` (max 64) | +| `mce:broadcast` | `Msg` | String | Message text for `util/broadcast` | +| `mce:broadcast` | `Prefix` | String | Optional prefix for `util/broadcast` | | `mce:output` | `Cooldown.ready` | Byte | `1b` if `@s` is ready, `0b` if on cooldown | | `mce:output` | `Cooldown.remaining` | Int | Remaining cooldown ticks | -| `mce:output` | `Version.string` | String | MCE version string (e.g. `"2.0.0"`) | -| `mce:output` | `Version.numeric` | Int | MCE version as int (e.g. `2000000`) | +| `mce:output` | `Version.string` | String | MCE version string (e.g. `"2.2.0"`) | +| `mce:output` | `Version.numeric` | Int | MCE version as int (e.g. `2002000`) | +| `mce:error` | `Last` | String | Last error message | +| `mce:error` | `Code` | String | Last error code (e.g. `ERR_NO_CMD`) | +| `mce:error` | `Count` | Int | Total error count since load | ## Scoreboard Reference | Objective | Description | |---|---| -| `mce.queue` | Queue state | +| `mce.queue` | Queue state and error counter | | `mce.tick` | Internal tick counters | | `mce.compat` | Compat system flags | | `mce.cd` | Per-player cooldown (remaining ticks, 0 = ready) | +| `mce.log` | Log entry counter and size tracking | > **Note:** `mce:cmd Executor` is no longer used. Tag your target entity with `mce.executor` before calling `mce:api/run/as`. @@ -282,6 +336,21 @@ execute unless score mce load.status matches 2000000.. run return 0 ## Changelog +### v2.2.0 +- Added `mce:api/log/write` — structured log entries `{n, lvl, msg}`, 64-entry cap +- Added `mce:api/log/info` / `log/warn` / `log/error` — level shorthands +- Added `mce:api/log/show` — level-colored tellraw output, macro-free +- Added `mce:api/log/clear` — clears entries and resets counter +- Added `mce:api/util/error_clear` — resets error state and counter +- Added missing function tags for `api/run/at`, `api/util/announce`, `announce_times`, `version`, `api/multi/run` +- Deprecated `mce:api/util/log` and `util/log_clear` (compat wrappers kept) +- Added `mce.log` scoreboard objective + +### v2.1.0 +- Added `mce:api/multi/run` — execute title, subtitle, actionbar, message, and commands in a single call +- Added `mce:api/util/broadcast` — send a message to all players from storage +- Added `mce:api/util/log` — append command string to in-memory audit log + ### v2.0.0 - Added `mce:api/run/at` — execute commands from fixed world coordinates - Added `mce:api/util/announce` — send title, subtitle, actionbar in one call