# abdooowd/ex-void architecture

> Architecture diagram of the GitHub repository abdooowd/ex-void, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abdooowd/ex-void
- Repository: https://github.com/abdooowd/ex-void

## Overview

#### Purpose and Runtime
Ex-Void is a native C space-exploration game built on raylib. The executable begins at `src/main.c`; game lifecycle and top-level orchestration are centered in `src/code/game.c` with public contracts in `include/game.h`.

#### Application Lifecycle
`src/main.c` initializes and runs the game through the game module rather than embedding gameplay directly. `src/code/game.c` likely owns the main loop, frame progression, and shutdown boundary; `include/config.h` provides project-wide compile-time game settings.

#### State-Based Game Flow
Game modes are separated into state modules. Setup/initialization behavior is implemented in `src/code/states/setup_state.c` and gameplay behavior in `src/code/states/play_state.c`, with interfaces in `include/states/setup_state.h` and `include/states/play_state.h`. The state transition/dispatch layer is represented by `include/tables/gamestate_table.h`, making state selection a central control-flow boundary.

#### Actor System
World entities use an actor abstraction defined by `include/actor.h` and implemented in `src/code/actor.c`. Actor behavior can be supplied through overlays/interfaces in `include/actor_ovl.h` and `src/code/actor_ovl.c`, separating generic actor lifecycle/storage from actor-specific logic. Registered actor types are indexed through `include/tables/actor_table.h`.

#### Concrete Content Modules
Individual game content lives under `src/actors/`. The current concrete actor is `src/actors/actor_test/actor_test.c`, with its local declaration in `src/actors/actor_test/actor_test.h`. New actor implementations are expected to integrate with the generic actor and actor-table layers rather than the game loop directly.

#### Shared Platform and Diagnostics Boundary
Common primitive types, utility APIs, and error handling are isolated under `include/lib/types.h`, `include/lib/utils.h`, and `src/lib/errors.c`. Debug facilities are separately exposed by `include/debug.h` and implemented in `src/code/debug.c`, providing a diagnostic boundary outside game-state and actor logic.

#### Generation and Build Infrastructure
The repository includes scaffolding tools for extending its two principal abstractions: `tools/new_actor/new_actor.py` generates actor modules, while `tools/new_state/new_state.py` generates state modules. `Makefile` is the build entry point; raylib is the material external runtime dependency.

Main entry points: [`src/code/game.c`](https://github.com/abdooowd/ex-void/blob/main/src/code/game.c) (Game lifecycle), [`src/code/actor.c`](https://github.com/abdooowd/ex-void/blob/main/src/code/actor.c) (Actor core), [`src/actors/actor_test/actor_test.c`](https://github.com/abdooowd/ex-void/blob/main/src/actors/actor_test/actor_test.c) (Test actor), [`include/tables/gamestate_table.h`](https://github.com/abdooowd/ex-void/blob/main/include/tables/gamestate_table.h) (State dispatch)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_raylib{{"raylib<br/>native runtime"}}
  node_main["Program entry<br/>C entry point<br/>[main.c]"]
  node_game["Game lifecycle<br/>orchestrator<br/>[game.c]"]
  node_game_api["Game contract<br/>public header<br/>[game.h]"]
  node_config["Game settings<br/>compile-time config<br/>[config.h]"]
  node_debug["Debug facilities<br/>diagnostics<br/>[debug.c]"]
  node_errors["Error handling<br/>shared library<br/>[errors.c]"]
end

subgraph group_gameplay["Game flow"]
  node_state_table["State dispatch<br/>state registry<br/>[gamestate_table.h]"]
  node_setup_state["Setup state<br/>game state<br/>[setup_state.c]"]
  node_play_state["Play state<br/>game state<br/>[play_state.c]"]
end

subgraph group_actors["Actor system"]
  node_actor_core["Actor core<br/>entity abstraction<br/>[actor.c]"]
  node_actor_api["Actor contract<br/>public header<br/>[actor.h]"]
  node_actor_overlay["Actor overlays<br/>behavior interface<br/>[actor_ovl.c]"]
  node_actor_table["Actor registry<br/>type registry<br/>[actor_table.h]"]
  node_test_actor["Test actor<br/>concrete actor<br/>[actor_test.c]"]
end

subgraph group_tooling["Build &amp; scaffolding"]
  node_build{{"Make build<br/>build entry"}}
  node_new_actor["Actor generator<br/>scaffolding tool<br/>[new_actor.py]"]
  node_new_state["State generator<br/>scaffolding tool<br/>[new_state.py]"]
end

node_build -->|"builds"| node_main
node_build -->|"links"| node_raylib
node_main -->|"starts"| node_game
node_game -.->|"implements"| node_game_api
node_game -->|"uses"| node_config
node_game -->|"runs on"| node_raylib
node_game -->|"dispatches through"| node_state_table
node_state_table -->|"selects"| node_setup_state
node_state_table -->|"selects"| node_play_state
node_play_state -->|"updates actors"| node_actor_core
node_actor_core -.->|"implements"| node_actor_api
node_actor_core -->|"delegates behavior"| node_actor_overlay
node_actor_table -->|"registers"| node_test_actor
node_test_actor -->|"integrates with"| node_actor_core
node_test_actor -->|"supplies behavior"| node_actor_overlay
node_game -.->|"emits diagnostics"| node_debug
node_debug -.->|"reports failures"| node_errors
node_new_actor -.->|"scaffolds modules like"| node_test_actor
node_new_state -.->|"scaffolds modules like"| node_setup_state

click node_build "https://github.com/abdooowd/ex-void/blob/main/Makefile"
click node_main "https://github.com/abdooowd/ex-void/blob/main/src/main.c"
click node_game "https://github.com/abdooowd/ex-void/blob/main/src/code/game.c"
click node_game_api "https://github.com/abdooowd/ex-void/blob/main/include/game.h"
click node_config "https://github.com/abdooowd/ex-void/blob/main/include/config.h"
click node_state_table "https://github.com/abdooowd/ex-void/blob/main/include/tables/gamestate_table.h"
click node_setup_state "https://github.com/abdooowd/ex-void/blob/main/src/code/states/setup_state.c"
click node_play_state "https://github.com/abdooowd/ex-void/blob/main/src/code/states/play_state.c"
click node_actor_core "https://github.com/abdooowd/ex-void/blob/main/src/code/actor.c"
click node_actor_api "https://github.com/abdooowd/ex-void/blob/main/include/actor.h"
click node_actor_overlay "https://github.com/abdooowd/ex-void/blob/main/src/code/actor_ovl.c"
click node_actor_table "https://github.com/abdooowd/ex-void/blob/main/include/tables/actor_table.h"
click node_test_actor "https://github.com/abdooowd/ex-void/blob/main/src/actors/actor_test/actor_test.c"
click node_debug "https://github.com/abdooowd/ex-void/blob/main/src/code/debug.c"
click node_errors "https://github.com/abdooowd/ex-void/blob/main/src/lib/errors.c"
click node_new_actor "https://github.com/abdooowd/ex-void/blob/main/tools/new_actor/new_actor.py"
click node_new_state "https://github.com/abdooowd/ex-void/blob/main/tools/new_state/new_state.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_raylib,node_main,node_game,node_game_api,node_config,node_debug,node_errors toneBlue
class node_state_table,node_setup_state,node_play_state toneAmber
class node_actor_core,node_actor_api,node_actor_overlay,node_actor_table,node_test_actor toneMint
class node_build,node_new_actor,node_new_state toneRose
```

## Components

### Runtime

- **raylib**: native runtime · External graphics and game runtime dependency.
- [Program entry](https://github.com/abdooowd/ex-void/blob/main/src/main.c): C entry point · `src/main.c`
- [Game lifecycle](https://github.com/abdooowd/ex-void/blob/main/src/code/game.c): orchestrator · Owns the main loop, frame progression, and shutdown. · `src/code/game.c`
- [Game contract](https://github.com/abdooowd/ex-void/blob/main/include/game.h): public header · `include/game.h`
- [Game settings](https://github.com/abdooowd/ex-void/blob/main/include/config.h): compile-time config · `include/config.h`
- [Debug facilities](https://github.com/abdooowd/ex-void/blob/main/src/code/debug.c): diagnostics · `src/code/debug.c`
- [Error handling](https://github.com/abdooowd/ex-void/blob/main/src/lib/errors.c): shared library · `src/lib/errors.c`

### Game flow

- [State dispatch](https://github.com/abdooowd/ex-void/blob/main/include/tables/gamestate_table.h): state registry · Central state selection and transition boundary. · `include/tables/gamestate_table.h`
- [Setup state](https://github.com/abdooowd/ex-void/blob/main/src/code/states/setup_state.c): game state · `src/code/states/setup_state.c`
- [Play state](https://github.com/abdooowd/ex-void/blob/main/src/code/states/play_state.c): game state · `src/code/states/play_state.c`

### Actor system

- [Actor core](https://github.com/abdooowd/ex-void/blob/main/src/code/actor.c): entity abstraction · Generic actor lifecycle and storage. · `src/code/actor.c`
- [Actor contract](https://github.com/abdooowd/ex-void/blob/main/include/actor.h): public header · `include/actor.h`
- [Actor overlays](https://github.com/abdooowd/ex-void/blob/main/src/code/actor_ovl.c): behavior interface · Separates actor-specific behavior from actor storage. · `src/code/actor_ovl.c`
- [Actor registry](https://github.com/abdooowd/ex-void/blob/main/include/tables/actor_table.h): type registry · `include/tables/actor_table.h`
- [Test actor](https://github.com/abdooowd/ex-void/blob/main/src/actors/actor_test/actor_test.c): concrete actor · `src/actors/actor_test/actor_test.c`

### Build & scaffolding

- [Make build](https://github.com/abdooowd/ex-void/blob/main/Makefile): build entry · `Makefile`
- [Actor generator](https://github.com/abdooowd/ex-void/blob/main/tools/new_actor/new_actor.py): scaffolding tool · `tools/new_actor/new_actor.py`
- [State generator](https://github.com/abdooowd/ex-void/blob/main/tools/new_state/new_state.py): scaffolding tool · `tools/new_state/new_state.py`

## Connections

- Make build → Program entry: builds
- Make build → raylib: links
- Program entry → Game lifecycle: starts
- Game lifecycle → Game contract: implements
- Game lifecycle → Game settings: uses
- Game lifecycle → raylib: runs on
- Game lifecycle → State dispatch: dispatches through
- State dispatch → Setup state: selects
- State dispatch → Play state: selects
- Play state → Actor core: updates actors
- Actor core → Actor contract: implements
- Actor core → Actor overlays: delegates behavior
- Actor registry → Test actor: registers
- Test actor → Actor core: integrates with
- Test actor → Actor overlays: supplies behavior
- Game lifecycle → Debug facilities: emits diagnostics
- Debug facilities → Error handling: reports failures
- Actor generator → Test actor: scaffolds modules like
- State generator → Setup state: scaffolds modules like