Challenges

Challenges are opt-in run modifiers (meta-progression) that make a run harder in exchange for mastery rewards. scripts/core/ChallengeManager.gd stores the active set, exposes effect multipliers, and gets consulted by hook sites across the codebase.

Overview

The ChallengeManager autoload owns three things:

• The catalog the selection UI renders (CATALOG, ORDER, ACCENT, comic art).
• The active set for the current run, read from GameManager.current_run.challenges.
• The effect-multiplier accessors that every hook site consults to apply a Challenge's mechanical changes.

The active set is an Array of Challenge ids. ChallengeManager doesn't own that array; GameManager does, inside current_run, so it rides the save blob and survives save-load like any other run state. ChallengeManager only reads it.

The catalog

Every Challenge is a key in the CATALOG dictionary. Six are defined and rendered in ORDER:

Each catalog entry carries name, icon (an emoji glyph from the bundled Noto subset), tier, implemented, effects, unlock_hint, backstory, and aid_pool. Two fields gate behavior:

• tier is "free" (selectable the moment the system unlocks) or "earned" (must be unlocked by playing).
• implemented is false for a catalog entry whose effects are not wired yet; such a Challenge shows on the locked grid but can never be selected.

ACCENT maps each id to a thematic hex accent colour; resolve it with accent_color(id) (returns a Color, defaulting to #9a8f6e on miss). comic_path(id) returns the res:// path to a Challenge's one-page comic intro, or "" if none.

The unlock flow

The whole system is gated behind the Astrolabe (referred to only as "the Ritual" in player-facing copy). In _on_ritual_performed() — connected to EventBus.astrolabe_activated — once AstrolabeManager.get_uses_count() >= 3, ChallengeManager calls SaveManager.mark_challenges_unlocked() and announces the unlock with fireworks in the six accent colours plus a toast. The unlocked flag lives account-wide in config.json (SaveManager.challenges_unlocked()).

Earned Challenges unlock individually through _evaluate_earn(), connected to EventBus.new_day and EventBus.generation_started. Conditions are endurance / resilience / stacking based, never depth. Each earned Challenge unlocks when ANY one of its conditions is met during a Challenge run (a run with at least one active Challenge):

_earn(id) records the earn via SaveManager.add_challenge_earned(id) (persisted in config.json under challenges_earned) and toasts once. is_selectable(id) returns true for an implemented free Challenge, or for an earned Challenge whose id is in SaveManager.get_challenges_earned().

From selection to active run

The selection overlay stages the player's chosen ids on ChallengeManager.pending_selection (an Array[String]). GameManager.reset_for_new_run() reads that into current_run.challenges, then clears it. From that point the active set is queried with:

func active_ids() -> Array:
	var raw: Variant = GameManager.current_run.get("challenges", [])
	return raw if raw is Array else []

func is_active(id: String) -> bool:
	return id in active_ids()

Effect multipliers and hook sites

Each mechanical change is exposed as an accessor that a hook site elsewhere in the codebase multiplies into its own value. The pattern is uniform: the accessor returns 1.0 (or the neutral value) when the Challenge is inactive, and its Challenge value when active. Each accessor also folds in the matching Artificer's Harrow dial (HarrowManager.dial_value / dial_t), which is the identity when no harrow rides the run, and clamps the product to a floor or cap so stacked configs stay disastrous but never degenerate.

Representative accessors:

A few accessors (food_drain_mult(), water_drain_mult(), surge_interval_mult(), surge_boost_mult()) have no backing Challenge — they are Harrow-only levers and return the identity unless a harrow is active.

Because the multipliers compose by multiplication and are individually clamped, a hook site should call the accessor once per tick and multiply — never re-derive the Challenge condition itself. Adding a new hook means adding an accessor here, not an is_active() check at the call site.

Run-start application

Some Challenges need imperative setup that a multiplier cannot express. apply_run_start() is called from GameManager.reset_for_new_run() after the normal manager resets, so its overrides win:

• lone_villager — SurvivalManager.reset(10, 10, 0, 0), VillageManager.population = 1, and ForestManager.pond_water = 10.
• black_rot — adds a strange_root buffer of population * 2 (read after Lone Villager and the souls dial so a 1-pop run gets 2 root).
• two_fronts — calls MawController.spawn_west_front() to append the western Maw after fronts[0] (east) already exists.

Day-20 Elder's Aid

On the first day-20 of a Challenge run, _maybe_deliver_aid() (connected to EventBus.new_day) delivers one care package per active Challenge, rolled from that Challenge's aid_pool via _roll_aid_package() (3–4 distinct entries, each quantity in its [min, max]). Food and water route through SurvivalManager.add_supplies(); everything else through Inventory.add(). The package is deposited immediately and gated single-fire by the challenge_aid_delivered flag on current_run, so it survives save-load and resets with the run. EventBus.challenge_aid_offered drives the ceremony modal.

Mastery rewards

Performing the Ritual with a Challenge active earns that Challenge's trophy cosmetic. That flow lives in scripts/core/CosmeticManager.gd (CHALLENGE_TROPHY, _check_challenge_mastery()), which reads ChallengeManager.active_ids() and ChallengeManager.CATALOG. See the cosmetics article for detail.

Key files

Related

• The Artificer's Harrow
• The Astrolabe
• The Maw
• Weather
• Cosmetics and Digger Forms
• Adding a Challenge