The Autoload Model

Underroot runs almost all of its game state through Godot autoload singletons. Below: every autoload in load order with a one-line role, and the reset() contract that returns the shared singletons to a clean state for a new run.

What the autoloads are

Autoloads are registered in the [autoload] block of project.godot. Each entry is a script attached as a globally accessible singleton node; the * prefix means the singleton is a node added to the scene tree root. Because they are nodes at the tree root, they persist across scene changes (IntroStory to TitleScreen to Main) and hold the run's authoritative state while scenes come and go.

Load order matters: an autoload listed later can safely reference one listed earlier during _ready(), but not the reverse. For example EventBus loads before every system that emits on it, and DataRegistry loads before the managers that read material and recipe data at startup.

All autoloads (load order)

The 36 autoloads, in the exact order they appear in project.godot:

HarrowManager is a real autoload (registered in project.godot) but is absent from the architecture guide's autoload table. Effect math for a Harrow config lives in ChallengeManager; HarrowManager owns the dial catalog and encode/decode.

The skill/class system spans two of these autoloads plus one non-autoload helper: SkillManager is the numeric spine (XP crediting, get_mult, handicaps, inheritance), SkillNotify is its UI adapter, and SkillMath (below) is the pure math. See Skill Tree and Classes.

The singleton pattern

Every autoload script extends Node. State lives in plain member variables (current_run, resources, walls, fronts, …), and behaviour is exposed as public methods. Callers reference the singleton by its registered name from anywhere:

Inventory.get_amount("iron")            # → int
DataRegistry.get_material(mat_id)       # → Dictionary ({} on miss)
MawController.refresh_threat_state()

Two conventions keep this decoupled:

• Cross-system events go through EventBus. Managers emit signals rather than calling each other's methods directly. See EventBus and the Signal Convention.
• Data lookups go through DataRegistry and return {} on a miss, so callers always use .get("key", default).

Note that some frequently referenced globals are not autoloads. GameConstants (scripts/core/GameConstants.gd), SkillMath (scripts/core/SkillMath.gd — pure static leveling math for the skill system; takes its config explicitly so tools/smoke_test.gd can exercise it deterministically), CommunityStats (scripts/core/CommunityStats.gd), UITheme (scripts/ui/UITheme.gd), HudShell (scripts/ui/HudShell.gd — HUD-skin state for the two-skin HUD), and LayerNav (scripts/ui/LayerNav.gd) are class_name types used statically — they are not in the [autoload] block and hold no per-run state.

The reset() contract

A fresh run must return the shared singletons to a clean baseline without reloading the whole game. GameManager.reset_for_new_run() is the single orchestration point: it rebuilds current_run and then calls each subsystem's reset entry point in dependency order.

The architecture guide highlights three singletons that expose an explicit reset() and should be reset through it rather than by poking _-prefixed fields:

SurvivalManager.reset() takes the starter stores explicitly; reset_for_new_run() passes the canonical GameConstants.STARTER_* values:

SurvivalManager.reset(GameConstants.STARTER_FOOD, GameConstants.STARTER_WATER,
        GameConstants.STARTER_STORED_FOOD, GameConstants.STARTER_STORED_WATER)
MawController.reset()
MawAdaptation.familiarity.clear()
Inventory.resources.clear()
ToolState.reset()

The same reset_for_new_run() continues through the rest of the world: MachineManager.reset(), WorldManager.reset_world(randi()), RockManager.generate(randi()), ForestManager.reset(), VillageManager.reset_village(), ProjectManager.reset(), TaskQueue.clear(), DiscoveryManager.reset(), CraftingUnlockManager.reset(), AstrolabeManager.reset(), and finally ChallengeManager.apply_run_start() (applied last so challenge starting conditions win over the normal resets). Several other autoloads expose their own reset() for this purpose, including WeatherManager, MachineManager, ForestManager, ProjectManager, AstrolabeManager, CraftingUnlockManager, and DiscoveryManager. SkillManager.reset() is a no-op — the run's skills/class are rebuilt with current_run by GameManager, and the chosen class is applied from SkillManager.pending_class. BlackHollowManager needs no reset(): its only per-run state is current_run.black_hollow_cooldown, rebuilt with current_run; everything else it owns — the chronicle, schematic count, best depths, and the story mode's chain and best scores — is account-level in config.json and deliberately survives a new run.

A lineage continuation (carry-on after a death) is not a new run: it keeps the same world and never calls reset_for_new_run(). See GameManager and the Run Lifecycle for the revive path.

Key files

• project.godot — the [autoload] block; authoritative load order.
• scripts/core/GameManager.gd — owns reset_for_new_run() and the run lifecycle.
• scripts/core/EventBus.gd — the signal hub every autoload emits through.
• scripts/resources/DataRegistry.gd — startup data load consumed by the manager autoloads.
• scripts/core/GameConstants.gd — non-autoload constants (STARTER_*, TILE_SIZE) used during reset.

Related

• EventBus and the Signal Convention
• GameManager and the Run Lifecycle
• Skill Tree and Classes
• Black Hollow
• World Coordinate System and Camera
• The Scene Tree
• DataRegistry and the Data Files