Developer Documentation

The complete guide to understanding, navigating, and contributing to the ASH & BRASS codebase. If you know software engineering but not Godot, start here.

🏗️ Architecture

Scene tree, autoloads, signal flow, collision layers, UI stack, data-driven content, and where to add new things.

📜 Coding Standards

Naming conventions, _physics_process vs _process, caching patterns, signals vs direct references, constants, type safety, and anti-patterns.

🤝 Contributing

Step-by-step guides for adding enemies, levels, and UI panels. How the signal bus works. Testing with GUT. Code review checklist.

📡 Signal Bus

Complete reference of all Events signals: who emits them, who listens, and what parameters they carry.

Quick Stats

Metric	Value
Game Scripts	90
Scenes	36
Data Resources	34
Autoloads	10
GUT Tests	40 (185 passing)
Engine	Godot 4.4
Language	GDScript (typed)

Project Structure

scripts/
├── autoload/        ← Singletons (Events, ContentRegistry, etc.)
├── content/         ← Data resource scripts (EnemyData, WeaponData)
├── entities/        ← Reusable entities (enemy, pickup, module)
├── levels/          ← Level controllers
├── player/          ← Player controllers
├── systems/         ← Gameplay systems (wave director, projectile pool)
└── ui/              ← UI panels and widgets

data/                 ← Content definitions (.tres files)
scenes/               ← Scene files (.tscn)
tests/                ← GUT tests
docs/                 ← Markdown source of this documentation

Recently Fixed Issues

Severity	Issue	Status
CRITICAL	Input conflicts: dash+halt both on Space, scan+interact both on F	✅ Fixed
CRITICAL	Collision masks wrong on club door, pickups (player couldn't interact)	✅ Fixed
HIGH	load() called during gameplay causing frame stutters	✅ Fixed (preloaded)
HIGH	get_nodes_in_group() called every frame in 8+ locations	✅ Fixed (signal caching)
HIGH	O(n²) separation force every physics frame	✅ Fixed (throttled)
MEDIUM	Greybox enemy code duplication (5 files, ~80% identical)	✅ Base class extracted
MEDIUM	Orphaned mode_indicator scene (no script attached)	✅ Fixed