Skip to content

Update README.md #19

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
asn44nb merged 1 commit into from
May 24, 2026
Merged

Update README.md #19

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
93 changes: 81 additions & 12 deletions .github/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.

---

Expand All @@ -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
```
Expand Down Expand Up @@ -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: <int>, lvl: <0|1|2>, msg: "<string>"}`.

### 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
Expand Down Expand Up @@ -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 |
Expand All @@ -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.

---

Expand All @@ -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...
```
Expand All @@ -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

Expand All @@ -257,31 +301,56 @@ 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`.

---

## 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
Expand Down