Cosmetics and Digger Forms

Cosmetics are the customization layer for the digger: skin, hair, beard, headwear, tunic, boots, an extra slot, a class-signature slot, and a full-body "form". scripts/core/CosmeticManager.gd owns ownership and the equipped loadout, every unlock routes through unlock(), and data/cosmetics.json holds the registry. Ownership is account-wide; the equipped loadout is per-run (save v4 for the loadout split, v5 for the class slot — see below).

Ownership in config.json, loadout in the run save

CosmeticManager caches account-level config state in memory. On _ready() it pulls two structures from SaveManager, backed by config.json:

var owned:   Array      = []   # ids the account has unlocked (account-wide)
var loadout: Dictionary = {}   # the new-run TEMPLATE (slot -> item id + colour keys)

• owned — SaveManager.get_cosmetics_owned() / set_cosmetics_owned(), stored under cosmetics_owned. Account-wide, survives slot deletion: cosmetics are permanent progression.
• loadout — since SAVE_VERSION = 4 this is only the new-run template: the look a fresh run inherits. The active run's truth is current_run["cosmetics_loadout"], reached exclusively through the private _run_loadout() accessor, which lazily seeds it from the template on first touch (new runs; migrated saves are seeded by _migrate()'s v4 step; the title screen's default run dict is harmless — it is rebuilt on play).

Every read goes through the run: get_loadout(), get_effect_mult(), and get_effect_chance() all resolve against _run_loadout(), so gameplay traits and rendering always reflect this slot's digger. One consequence: ledger score rows (save_score) capture the look of the run that died, not whatever another slot equipped since.

After a factory reset, reload_from_config() re-pulls owned and the template from disk; without it, the stale in-memory owned array would resurrect every erased cosmetic on the next write.

_ensure_defaults() fills any missing template slot with that slot's default variant (via DataRegistry.get_default_cosmetic_for_slot(slot)), plus the companion colour keys hair_color, beard_color, and tunic_dye, so a fresh or newly extended config always renders a complete digger.

Ownership rules

func is_owned(item_id: String) -> bool:
	var def := DataRegistry.get_cosmetic(item_id)
	if str(def.get("source", "")) == "free":
		return true
	return item_id in owned

Free items are always owned. Everything else must be in owned.

All unlocks route through unlock()

Every grant path funnels through one private helper, _grant(item_id), which appends to owned, persists via SaveManager.set_cosmetics_owned(), and emits EventBus.cosmetic_unlocked. It returns false if already owned (so grants are idempotent). Three public entry points wrap it:

Because unlock() is a no-op once owned, re-entering a redemption code or re-hitting a milestone can never double-grant. This is what makes back-filling a cosmetic onto an already-redeemed code farm-safe (see the codes article).

Milestone hooks

_connect_milestones() wires the account-wide unlocks to EventBus signals — cosmetics are never connected node-to-node:

Challenge mastery trophies

_check_challenge_mastery(), called from _on_astrolabe_activated(), grants a trophy for each Challenge active when the Ritual fires. The mapping is CHALLENGE_TROPHY:

Each trophy carries a gameplay effect (see below) and a one-line trait blurb in TROPHY_TRAIT_TEXT, read by the mastery cutscene. Newly earned trophies are emitted together via EventBus.challenge_mastered.

The ultimate reward is form_maweaten (The Maw-Eaten), granted by _check_maw_eaten() on EventBus.player_died when the player dies having held all six Challenges and performed at least one Ritual.

Class cosmetics

The class slot (last in slot_order, additive to extra) holds the champion-class signature look — it never competes with the gloves/amulet/mantle in extra. CosmeticManager maps class and skill to the relevant items:

const _CLASS_SIGNATURE := {  # class -> signature (free)
	"miner": "class_ropecoil", "hunter": "class_hunterkit", "smith": "class_apron",
	"mason": "class_toolbelt", "chieftain": "class_pauldrons", "merchant": "class_moneybag",
}
const _CLASS_PRESTIGE := {   # skill -> prestige variant (champion peak)
	"digging": "class_ropecoil_prestige", "foraging": "class_hunterkit_prestige",
	"crafting": "class_apron_prestige", "building": "class_toolbelt_prestige",
	"population": "class_pauldrons_prestige", "trading": "class_moneybag_prestige",
}

• Signature accessory — one per class, source: free (always equippable, removable in the customizer): Miner's Rope, Hunter's Kit, Smith's Apron, Mason's Tool-Belt, Chieftain's Pauldrons, Merchant's Purse. _class_signature() resolves the current calling's id (or the class default for a classless run). It is auto-seeded on new game (reset_run_equipment) and re-pointed on a carry-on calling switch (reseed_class_signature, called from GameManager.switch_calling).
• Prestige variant — class_*_prestige (gilded + glow, hidden_until_owned, trigger: champion:<class>), granted account-wide at champion peak. _on_skill_leveled(skill, node) fires the _grant when node >= 7 and SkillManager.is_champion(skill) (node 7 is champion-only, so the node check alone nearly implies it), with a tailored "Champion peak!" toast.

See Skill Tree and Classes for the class system itself.

Digger forms

The form slot is a full-body reskin, distinct from the piecewise slots — while a form is equipped it overrides the hat/garment/dye layers visually. Defined forms:

Secret forms are granted through code redemption, which calls CosmeticManager.unlock().

Cosmetic effects

Cosmetics can carry a generic effect bag, and CosmeticManager aggregates it across every equipped slot of the active run's loadout. Two readers cover the two effect shapes:

func get_effect_mult(key: String) -> float   # product across slots; absent -> 1.0
func get_effect_chance(key: String) -> float  # max across slots; absent -> 0.0

get_effect_mult() multiplies each equipped item's effect[key] (used for dig_speed_mult, food_drain_mult, shelter_fuel_mult, wager_luck_mult, etc.). get_effect_chance() takes the max (used for proc-style traits like ward_bad_ingest_chance). Slot competition — one item per slot — is the natural cap on how many trait multipliers stack. The class signature and prestige items carry no effect — they are cosmetic only; the class's gameplay bonus comes from SkillManager, not the accessory.

Two named wrappers delegate to get_effect_mult() for their call sites, both of them the Berry-picking Gloves' traits:

• get_berry_speed_mult() — divides BerryBush.GATHER_TIME in GatherController, captured once when a pick starts so swapping gloves mid-pick cannot retroactively speed it up.
• get_berry_yield_mult() — scales the food a bush harvest grants, in ForestManager.harvest_bush(). It deliberately does not scale the berries deducted from the bush: a bush is a 20-berry stock that then rests a full day, so scaling the deduction would strip bushes faster for the same total. Food is a float on the supply bar, so the multiplier applies with no rounding loss. This is the trait that matters at scale — bush stock and regrowth are the real ceiling on berries, not pick speed.

describe_effect(def) turns an effect bag into player-facing one-liners ("+60% berry picking"). Every surface that advertises a cosmetic reads it — the Your Digger customizer tiles (in the hover tooltip) and Wren's wares board (as a visible line under the item name, since the point of sale must explain itself and the web build has no hover). A new effect key without a line there is invisible to the player even when the hook site honours it.

Equipping and per-run reset

equip(key, value) writes the run loadout (the per-slot truth, persisted by the normal autosave), mirrors the value into the account template (so the next new run inherits the look), persists the template, and emits EventBus.cosmetic_changed.

On a new game, reset_run_equipment() (called from GameManager.reset_for_new_run(), new game only — lineage successors keep their look) resets four slots in that run's loadout only: headwear, extra, and form go bare (to their defaults), and class is seeded to the current calling's signature via _class_signature() (the class is already set by this point). A fresh digger starts bare-headed, without extras, without a suit form — a carried-over form would paint over everything the intro customizer applies — but wearing its calling's signature accessory. The account template and every other slot's look are untouched; face and body slots persist.

data/cosmetics.json structure

The registry has three top-level keys:

{
  "slot_order": ["form","skin","headwear","hair","beard","tunic","boots","extra","class"],
  "items": { "...": { } },
  "dyes":  { "...": { } }
}

slot_order (read by DataRegistry.get_cosmetic_slot_order()) drives both the customizer layout and the effect-aggregation loops. Each entry in items looks like:

"boots_furcuff": {
  "slot": "boots",
  "name": "Fur-cuffed Boots",
  "kind": "style",
  "source": "discovery",
  "effect": {"dig_speed_mult": 1.1}
}

dyes are simpler {name, color, source, default} entries for the tunic dye picker, read via DataRegistry.get_cosmetic_dye().

hidden_until_owned

hidden_until_owned: true keeps an item out of the customizer grid until it is owned. It is used for the secret forms (form_axel, form_dave, form_hugo), for head_headlamp_gold, and for the six class_*_prestige variants, so unredeemed secret cosmetics and un-earned prestige looks do not hint at their existence in the UI. It does not affect ownership or effects — only visibility.

Single-tile dig finds

A handful of cosmetics are seeded into the world as luck-based digs. reseed_dig_finds() (called on _ready() and on EventBus.generation_started) assigns each un-owned discovery item a single random tile within SEED_X_MIN..SEED_X_MAX / SEED_Y_MIN..SEED_Y_MAX. The seeds are re-rolled each run and never persisted. On EventBus.tile_dug, if the dug tile matches a seed, unlock() (or _unlock_dye() for dye seeds) fires. Current seeds: boots_furcuff, plus the moss and royal dyes.

Key files

Related

• Codes and Redemption
• Challenges
• Skill Tree and Classes
• Save System and Migration
• DataRegistry and the Data Files
• Adding a Cosmetic