Diagnostics en

中文 | English

Diagnostics: trace, replay & simulation

The diagnostic system answers one question: when an order misbehaves, how do we turn "what actually happened" into submittable evidence. Three tools work on one artifact — a trace:

1. Trace — a full in-game recording of one crafting request: decision points, every extraction, pattern expansion, the resulting plan, written to a hash-chained file;
2. Replay — re-run the same trace through the current engine and diff the plan (reproduces calculation-layer problems);
3. Simulate — run the replayed plan through an offline cluster that mirrors the AE2UEL crafting CPU and classify whether it would stall (reproduces execution-layer problems, see CPU simulation).

Design principles: traces are strictly human-triggered (zero cost and zero footprint during normal play); automatic pseudonymization (names are tokenized at the recording boundary; the mapping never leaves the server); tamper-evident evidence (event hash chain + payload digest).

In-game commands

All are server-side commands under /ae2vm trace …, usable from a vanilla client; every reply is visible only to its sender.

Command	Who	Effect
/ae2vm trace record next	anyone	Set up a one-shot recording: your next order is recorded in full (one order only)
/ae2vm trace record on / off	op	Open/close a global recording window: every order placed inside the window is recorded (for reproducing machine/stock-keeper orders)
/ae2vm trace list	anyone	Lists only your own traces (players and ops alike); one line per trace with a three-color status; the [Download]/[Upload] buttons execute directly; append a page number to paginate
/ae2vm trace list all	op only	List everyone's traces on this server (extra source column)
/ae2vm trace show <id>	owner or op	Print a trace summary in chat
/ae2vm trace download <id>	owner or op	Send the trace to the client (see file locations below; requires the mod on the client)
/ae2vm trace upload <id>	owner or op (gated by traceUploadEnabled)	Upload to mclo.gs and get a short link — the main evidence channel for players without the client mod; traces are pseudonymized before upload

Typical flow: a player sees a broken order → record next → re-place the order manually → list → upload the short link into the issue. For machine-placed orders a human opens a window with record on.

The full reporting walkthrough lives in Filing a report.

Where trace files live

• Traces live under aevm/traces/ (gzip JSON: version metadata + event hash chain + embedded sub-pattern bytecode + multi-pattern repair attribution (REPAIR_CHOICE)) — on the client under .minecraft/aevm/traces/, on the server under the server directory's aevm/traces/;
• The token vault sits next to them in aevm/vault.json and never leaves the server;
• Retention is lazily enforced by two caps: traceRetentionCount (default 20) + traceRetentionMaxBytes (default 100 MiB); the oldest files go first.

Replay entry points

• Out-of-game CLI (recommended): the mod jar + the replay-shim jar attached to every release — two files to replay and get the simulation verdict; command and exit codes in CPU simulation.
• In-server replay (planned): /ae2vm trace replay <id> re-runs the trace inside the running server, no external setup at all.

Configuration

Key	Default	Meaning
traceSessionEventCap	100000	Event cap per recording session (ring eviction; the oldest events go first)
traceRetentionCount	20	Trace files kept
traceRetentionMaxBytes	104857600	Total trace bytes kept (100 MiB)
traceUploadEnabled	true	When false, upload is disabled for everyone
language	en_us	Command feedback language (en_us / zh_cn)
stallWatchdogTicks	0 (off)	Watchdog: after N ticks of an unchanged CPU fingerprint with a non-empty waitingFor, the CPU's NBT snapshot is dumped to aevm/ (for stall shapes that cannot be reproduced manually; enabled explicitly by server owners)