Architecture

Understand the codebase in 10 minutes without opening the editor.

Big Picture

ASH & BRASS is a 2D top-down bullet-heaven action RPG built in Godot 4.

The architecture follows these principles:

• Data-driven: Enemies, weapons, waves, biomes are defined in .tres resource files, not hardcoded.
• Signal-based: Scripts communicate through an Events autoload (pub/sub), not direct references.
• Scene composition: Each "thing" (player, enemy, UI panel) is a self-contained scene that can be instantiated.
• Autoload managers: Global systems (save, audio, time) live as singletons.

Scene Tree

Runtime Hierarchy (main.tscn)

Greybox Prototype (mayo_breach_greybox.tscn)

The Mayo Breach greybox is a self-contained vertical slice for testing combat mechanics. It does NOT use main.tscn.

Note: There are two parallel player systems: player.tscn (the "real" game) and greybox_player.tscn (the prototype). Eventually these will converge.

Autoloads

Autoloads are configured in Project Settings → Autoload. They exist before any scene loads and persist across scene changes.

Golden Rule for Autoloads: Read freely. Write sparingly. Any script can read FortressController._scrap. But ONLY FortressController should mutate its own state. If you need to change scrap, call a public method or emit a signal.

Signal Flow

All gameplay events flow through the Events autoload. This is how scripts talk to each other without knowing each other exists.

Emitting an event

# ANYWHERE in the codebase:
Events.player_damaged.emit(10, "enemy.swarmer")

Listening to an event

func _ready() -> void:
    Events.player_damaged.connect(_on_player_damaged)

func _on_player_damaged(amount: float, source_id: String) -> void:
    print("Player took ", amount, " damage from ", source_id)

Why signals instead of direct references?

Bad (tight coupling):

var player = get_tree().get_first_node_in_group("player")
player.take_damage(10)  # If player is refactored, this breaks

Good (loose coupling via Events):

Events.player_damaged.emit(10, "enemy.swarmer")
# Player listens and handles it. Enemy doesn't care HOW.

See the Signal Bus Reference for the complete list of signals.

Collision Layers

Configured in Project Settings → Layer Names → 2D Physics.

Layer vs Mask

• Layer = "What I am" (other things detect me)
• Mask = "What I detect" (I collide with these)

Common mistakes

• Forgetting to set layers explicitly (relying on Godot defaults = layer 1 only)
• Setting mask to your OWN layer (a pickup masking layer 6 won't detect the player)
• Not updating masks when adding new entity types

UI Stack

UI uses CanvasLayer nodes with explicit layer values to control draw order:

Rule: Higher layer = drawn on top. PauseMenu at 20 means it covers ALL other UI.

Data-Driven Content

All game content is defined in data/ as .tres files with custom Resource scripts.

Content Folders

Where to Add New Things

New Enemy

1. Add EnemyData resource to data/enemies/
2. If greybox: extend GreyboxEnemyBase (see Contributing Guide)
3. If main game: ensure enemy.gd handles the archetype
4. Add to a WaveData resource in data/waves/
5. Add GUT test in tests/unit/

New Level

1. Create scene in scenes/levels/
2. Root should be Node2D
3. Use TileMap for terrain
4. Instantiate player from scenes/player/greybox_player.tscn or player.tscn
5. Add Spawner node with WaveData reference
6. Add UI CanvasLayer with labels

New UI Panel

1. Create scene in scenes/ui/
2. Root should be CanvasLayer (for overlays) or Control (for widgets)
3. Pick appropriate layer number (see UI Stack above)
4. Script goes in scripts/ui/
5. Connect to Events signals; avoid direct scene references

New Autoload

Don't. We already have 10. If you think you need one, ask. Most global state can live in an existing autoload or be passed through signals.