Battle log and history¶
GreatNPC maintains two different records: progression history used by gameplay rules, and an append-only result log used for auditing.
Result log¶
Completed NPC battle results are appended to:
The filename uses the UTC date. Each line is a standalone JSON object, so tools can read the file incrementally without loading an entire JSON array.
{"timestamp":"2026-11-18T12:00:00Z","event":"battle_result","player_uuid":"123e4567-e89b-12d3-a456-426614174001","player_name":"Alex","npc_uuid":"123e4567-e89b-12d3-a456-426614174002","trainer":"cobblemontrainerbattle:tutorial/brock","result":"victory","dimension":"minecraft:overworld","x":100.5,"y":64.0,"z":-20.5}
| Field | Meaning |
|---|---|
timestamp |
UTC result timestamp in ISO-8601 format. |
event |
Currently battle_result. |
player_uuid, player_name |
Player identity at the time of the result. |
npc_uuid |
NPC entity involved in the result. |
trainer |
Trainer ID used by progression history. |
result |
victory or defeat from the player's perspective. |
dimension, x, y, z |
NPC location when the result was recorded. |
This is a result audit log, not a turn-by-turn battle transcript. It does not currently record move selections, damage, failed starts, disconnects, or every aborted battle. Administrator test battles do not take the normal result-recording path. A logging failure is reported in the server log.
Progression history¶
By default, per-player progression files are stored in:
They hold trainer-keyed counters and state, including the last-victory timestamp, victory and defeat counts, battle-started state, and an attempt-reset override. When MySQL is enabled and available, history uses the configured database; see the server configuration documentation. Its table is <mysqlPrefix>history, with an auxiliary <mysqlPrefix>history_players table.
Use /gnpc history Alex to view a player's records, or /gnpc history Alex tutorial/brock for one trainer. The history command requires an online player argument. The reset commands change progression; they do not delete old JSONL audit events.
Operations¶
Back up both the world history and configuration before maintenance. Database-backed installations should back up the database as well. The result log contains player identifiers and names, so include it deliberately in your server's log retention and access policy. Files are separated daily; GreatNPC does not currently provide an automatic retention policy or an in-game battle-log browser.