Upgrading from 2.x to 3.x

3.x changes configuration, wire protocol, persisted gym/player metadata, and the trainer runtime. A 2.x backup is the only supported rollback path after a world has been saved by 3.x.

Before the first start

1. Stop every backend and make an offline backup of the complete world, config/brecher_trainers/, datapacks, and the player-data transfer store.
2. Keep a copy of the 2.2.0 jars and dependencies with that backup.
3. Remove RCT and RCT API only after confirming no other installed mod requires them. Brecher Trainers itself no longer links either dependency.
4. Install matching current 3.x Fabric or NeoForge jars on every server and client. Current releases use network protocol 10; clients using protocols 6–9 cannot connect.
5. For proxies, choose exactly one authority backend. Configure it as PROXY_AUTHORITY and every other backend as PROXY_SATELLITE; copy the same tier catalog and catalog_identity to all backends.

First start and migration order

Migration runs config, then canonical gym state, then native trainer/spawner data. Each step is version-gated and idempotent, and completion is recorded only after a successful save.

The authority imports the retired brecher_trainers_gyms SavedData into brecher_trainers_gym_registry, including gym identity, links, cooldowns, reset state, metrics, and creator-earnings totals. Controller NBT is then treated only as a one-way migration source; subsequent saves no longer duplicate registry classification or metrics. Satellites do not load or rewrite either world-state file.

An unversioned league.yaml becomes schema 2. A sidecar league.yaml.schema-1.bak is created before the rewrite. Unknown future schemas and invalid candidates abort startup rather than silently enabling defaults. Expect a warning if settle_sessions_on_logout is present; remove the key.

Legacy trainer JSON and NBT are read by a standalone converter. The legacy spawner payload is retained in a migration-backup NBT key through the first successful native save, then removed on the following successful save.

Verify before opening the server

1. Confirm every backend reaches a clean startup with the same current 3.x release and network protocol 10.
2. Compare /league info catalog hashes across all proxy backends.
3. Run /trainer migration report; resolve malformed rosters and required missing templates. The release gate is zero unresolved required templates and zero legacy-backed entities.
4. Run /gym admin registry validate and prune stale showcase entries if reported.
5. Restart the copied world once more and repeat the migration/registry reports.
6. Test one win, loss, flee, and disconnect; confirm session settlement, reward, cooldown, LP, tier, and restart persistence behavior.
7. On a proxy, transfer repeatedly in both directions and verify no duplicated LP, catalog mismatch rejection, satellite mutation denial, and attachment restore.

Rollback limitations

Do not attempt to downgrade the rewritten world in place. Stop all backends and restore the entire pre-upgrade world, config, datapacks, and transferred player store as one consistent snapshot. Restoring only a single SavedData file can create orphan sessions, showcase references, or duplicate settlements.