Gym badges

Since v3.1

Badge definitions are datapack JSON resources under data/<namespace>/brecher_trainers/badges/<name>.json. The resource path becomes the badge ID; a namespace is a convenient badge set. Reload is transactional: one malformed definition, duplicate custom_model_data, oversized catalog, or unknown schema keeps the complete previously installed catalog active.

{
  "schema_version": 1,
  "display_name": "Volcano Badge",
  "description": "Awarded for mastering the volcano circuit.",
  "custom_model_data": 100
}

Rules

• The full badge ID (namespace plus resource path) is limited to 256 characters.
• display_name is 1–64 characters; description is optional and at most 256.
• custom_model_data must be a unique integer from 1 through 65535 across all loaded packs. Values 1–99 are reserved for badges shipped by Brecher Trainers; server packs should start at 100.

Use /reload to install datapack changes, then verify the server log reports Loaded <n> gym badge definition(s). A rejected badge sub-registry retains the prior catalog even if the broader reload command finishes. Gym owners may select an installed definition from the Gym Controller.

Operator commands

These commands are authority-only; quote gym names that contain spaces.

• /gym admin badge info <gym_name> shows the explicit/default assignment, its resolved ID, generation, and whether the definition is loaded.
• /gym admin badge set <gym_name> <badge_id> assigns a loaded definition.
• /gym admin badge clear <gym_name> returns the gym to its type default.
• /gym admin badge bump <gym_name> advances the entitlement generation. It does not immediately give or remove an item; each player can earn the new generation on a later completion, which then replaces that gym's gallery entry.
• /gym admin badge reissue <player> <gym_name_or_gym_uuid> mints another physical copy from an online target's ledger without changing its generation or entitlement state. If reused gym names are ambiguous, use the UUID.

Changing an assignment does not reopen an entitlement by itself. Players who already hold that gym's current generation can earn the replacement only after an operator deliberately uses badge bump; gym owners cannot grant that re-award power to themselves.

Resource pack models

The companion resource pack must replace assets/brecher_trainers/models/item/gym_badge.json wholesale: copy the shipped file, retain its ascending overrides, append an override for every custom model data value, and provide the referenced item model and texture.

Minecraft 1.21.1 tests custom_model_data predicates as thresholds (>=). A definition whose value has no matching override therefore renders as the nearest lower badge, which falsely displays another badge identity rather than merely showing a generic missing texture. Always deploy the JSON definition and its model override together, and distribute the pack with require-resource-pack=true when identity matters.

For the example definition above, the copied root model needs an ascending entry like this after the shipped overrides:

{
  "predicate": {"custom_model_data": 100},
  "model": "my_badges:item/badge/volcano_badge"
}

That model belongs at assets/my_badges/models/item/badge/volcano_badge.json and should reference a texture such as my_badges:item/badge/volcano_badge. Keep every definition's numeric value, root-model predicate, model path, and texture path in lockstep.

/reload refreshes only datapacks. A resource-pack model or texture change needs a client resource-pack reload or reconnect; change the server-pack hash to bust cached downloads.

Deleting an explicitly assigned definition does not substitute the gym-type default: the controller reports the missing definition and future awards preserve the original logical ID on a raw badge. If a gym-type default is missing, the controller likewise reports its resolved default ID as missing rather than presenting the raw fallback without an operator-visible warning.

Badge ledgers and proxy networks

The earned badge ledger is part of the transferred player data. Every linked PlayerSync backend must run this version in lockstep: an older backend that reads and writes the attachment silently drops the earned badges, even if the authority backend itself is current.

Each player's ledger has a hard limit of 1,024 distinct gym UUIDs. At capacity, a new gym's badge is not recorded or awarded; a newer generation for an already-recorded gym can still replace that entry. There is no automatic eviction or pruning command, because removing an entitlement record would permit a duplicate physical award. Resolving an exceptional full ledger is a manual support operation and requires preserving the once-per-generation history.