Storage and backups¶
GreatNPC's optional database backend covers battle history only. Enabling MySQL does not move every NPC, preset, interaction counter or shop record into SQL.
What is stored where¶
| Data | Location/backend |
|---|---|
| Global settings and trainer/team definitions | config/greatnpc/ JSON files |
| Reusable preset-item snapshots | config/greatnpc/item_presets/ |
| Placed NPC entities and saved variables | Minecraft world/entity saves |
| Per-player battle history | World greatnpc/battle_history/<uuid>.json, or optional MySQL |
| Action/button/trade usage counters | World greatnpc/interaction_state/<uuid>.json |
| Shared rotating shop stock | World greatnpc/trade_restock.json |
| Known trainer/NPC location index | World greatnpc/locations.json |
| Battle result audit log | Instance/server logs/greatnpc/battles/<UTC-date>.jsonl |
Battle history contains the victory timestamp, victory/defeat/kill counters and the one-battle attempt/reset flags. Cooldown state is derived from the recorded victory timestamp and the trainer's current cooldown settings. The battle log is an append-only result record; deleting a log does not reset gameplay counters.
File-backed history¶
The default backend writes per-player JSON in the active world. Battle-history, interaction-state and restock saves use temporary-file replacement to reduce partial-write damage. This is not a substitute for world backups and does not mean every file in the mod uses the same writer.
Interaction and shop state are also saved on supported server lifecycle events. Always stop the server cleanly before replacing persistent data by hand. The in-memory state can otherwise overwrite manual file edits.
Optional MySQL/MariaDB¶
Enable mysqlEnabled and configure the connection using the camelCase settings. The database itself must exist; GreatNPC creates its own tables within it.
With the default prefix, the tables are:
| Table | Purpose |
|---|---|
greatnpc_history |
Battle history keyed by player UUID and trainer ID. |
greatnpc_history_players |
Marker that the player's history has already been saved, including an intentionally empty reset. |
The marker name is derived from the history table name plus _players. Both history replacement and marker insertion happen in the same save transaction. A saved empty history must remain empty; it must not look like a player who has never been imported.
History saves use independent snapshots before being queued to a single writer. Clean shutdown and the supported settings-reload flow wait for previously queued writes before closing/replacing the connection. SQL errors are logged; this does not provide durable delivery if the database rejects or loses a transaction.
Import and fallback behavior¶
When MySQL is active and a player has no SQL history and no saved-player marker, GreatNPC can import that player's existing world-local history file. A player marker prevents a later intentional reset from reimporting an old file. If the marker query fails, the code avoids treating that failure as permission to import a possibly stale local file.
If MySQL is unavailable when the storage layer chooses its backend, it can read/write the world-local JSON fallback. If a save is already queued for MySQL and that SQL operation later fails, it is logged; it is not automatically replayed into JSON by that queued writer.
This is a fallback path, not bidirectional synchronization or a multi-server conflict-resolution system. Local files can differ from the database after an outage or backend change. Preserve both copies and establish which one is authoritative before manually migrating/resetting data. Do not assume that simply toggling MySQL merges both histories.
The MySQL changes have been reviewed and the project compiled, but a real database integration test is still needed for this build. Do not treat unit tests of history snapshots as proof of live JDBC behavior or outage recovery.
Backup checklist¶
For a restorable snapshot, include:
- The complete Minecraft world, including entity data and its
greatnpc/directory. config/greatnpc/, including teams, presets, rename mappings and item preset snapshots.- A database backup if MySQL is enabled, including both history and marker tables.
- Battle result logs if you need the audit trail.
Use a consistent maintenance window or a supported database snapshot procedure. config/greatnpc/backups/ contains backups from particular editing operations and is not a complete backup of those four data sources.
Old language configurations and files from removed features are not automatically deleted. Retain them in an archival backup before deciding whether they are still needed by an older server version.