Architecture Chapter

This chapter explains EchoWarrior from the outside in. Start with the big picture, then move down through module boundaries, runtime flow, data loading, release packaging, choreography, and extension patterns.

The goal is not to memorize every file. The goal is to know where a change belongs and what contracts it must preserve.

Chapter Path

1. Fundamentals: the shortest possible architecture map.
2. Module Boundaries: which folder owns which kind of work.
3. Runtime Loop: how the Macroquad prototype advances a frame.
4. Data And Modding Flow: how TOML, YAML, and Lua become game behavior.
5. Assets And Release Packs: why loose files and data.pak both matter.
6. Choreography: the single authored-beat engine.
7. Extension Patterns: where to add new behavior safely.
8. Commands And Events: how scripts, scenes, upgrades, runtime, and logs communicate.
9. Simulation And ECS: how pure run logic and the ECS bridge coexist with runtime actors.
10. Rendering And UI: how world rendering, effects, post-processing, and UI layers stack.
11. Persistence And State: how saves, settings, progression, and mod metadata are separated.
12. Verification Architecture: how checks map to code and content boundaries.
13. Graceful Degradation: how missing or broken content should fail without taking down the game.
14. Performance And Observability: how contributors find slow or noisy paths.
15. Feature Slice Walkthrough: how a new capability crosses data, runtime, tools, docs, and release packaging.
16. Design Principles: how to choose between valid approaches.
17. Architecture Glossary: shared terms used across the wiki and codebase.
18. Migration Status: what is already pure, what is bridged, and what is still runtime-owned.
19. Anti-Patterns: common moves that fight the architecture.

One-Screen Map

flowchart TB
    contributor[Contributor]
    assets[Assets and Mods]
    bins[src/bin tools]
    lib[src/lib shared crate]
    runtime[src/runtime Macroquad runtime]
    game[src/game pure gameplay]
    data[src/data loaders]
    ui[src/ui UI models]
    save[src/save persistence]
    script[src/scripting Lua]
    pack[data.pak / identity.pak]

    contributor --> assets
    contributor --> bins
    contributor --> lib
    lib --> game
    lib --> data
    lib --> ui
    lib --> save
    lib --> script
    runtime --> lib
    data --> assets
    script --> assets
    bins --> lib
    assets --> pack
    runtime --> pack

North Star

EchoWarrior is built to keep content easy to modify while keeping core rules testable:

• content lives in Assets/ and Mods/ when practical
• pure rules live in src/game
• data schemas and fallback loading live in src/data
• Macroquad rendering/input/audio live in src/runtime
• release asset discovery lives in src/asset_pack.rs
• shipping confidence comes from mod_check, asset_pack, tests, and cargo check

Quick Decisions

If you are changing…	Read next
any code for the first time	Fundamentals
where a module belongs	Module Boundaries
frame update/drawing behavior	Runtime Loop
TOML/YAML/Lua content	Data And Modding Flow
release asset inclusion	Assets And Release Packs
story beats, movement beats, scenes	Choreography
adding a new capability	Extension Patterns
adding Lua/choreography/upgrades behavior	Commands And Events
touching actors, ECS, or pure run tests	Simulation And ECS
changing draw order, effects, or HUD	Rendering And UI
changing saves, settings, or account progress	Persistence And State
deciding which checks to run	Verification Architecture
adding fallbacks or loader behavior	Graceful Degradation
chasing frame time or logs	Performance And Observability
planning a complete capability	Feature Slice Walkthrough
deciding between two designs	Design Principles
decoding architecture vocabulary	Architecture Glossary
understanding current migration seams	Migration Status
checking whether an approach is risky	Anti-Patterns