Architecture

The key words MUST, MUST NOT, and MAY below are used as in RFC 2119.

The engine is organized in layers. Boot flows top-down: the bootstrap brings the asset pack online and hands off to the autoload singletons (Core State, Registry, Gameplay), which drive the Scene / UI layer, which in turn instantiates the Entity layer (player, enemies, NPCs). A lower layer MUST NOT reach up into a higher one — entities read state through the autoloads, scenes don't poke at bootstrap, and the registries are pure data lookups with no outbound dependencies.

Throughout the rest of this spec, every "Implemented by" badge is colored by the layer the script lives in, so you can trace a feature across layers at a glance. The legend below is the key.

Color legend

• bootstrap — the asset-pack loader and entry flow. bootstrap.gd (Title → Character Select).
• core — Core State: the authoritative game/session state singletons. GameState CharacterManager SaveManager Inventory SceneManager PlayerConfig.
• registry — data-only lookups, no outbound deps. WeaponRegistry ArmorRegistry ConsumableRegistry EnemyRegistry ClassRegistry MagRegistry TechniqueRegistry PhotonArtRegistry ShopRegistry DropRegistry MissionRegistry.
• gameplay — runtime systems that mutate state. CombatManager SessionManager QuestLoader EnemySpawner CityState TimeManager.
• scene — Scene / UI: 2D screens and field/city controllers. shops guild_counter char_select valley_field_controller.
• entity — instanced 3D actors. player.gd (CharacterBody3D) · enemies (AI) · GameElements (NPCs).

Key data flows

• Boot — bootstrap.gd fetches assets.pck → mounts the pack → transitions to Title, then Character Select.
• Combat — Input → ActionPalette → player.gd → CombatManager (damage calc) → hitbox / hurtbox → drops → Inventory.
• Save / Load — SaveManager → CharacterManager.get_save_data() + GameState → user://save_data.json.
• Quests — QuestLoader → SessionManager.start_quest() → valley_field_controller.gd → CellObjectSpawner.