# linleyh/liberation-circuit architecture

> Architecture diagram of the GitHub repository linleyh/liberation-circuit, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/linleyh/liberation-circuit
- Repository: https://github.com/linleyh/liberation-circuit

## Overview

1. **What this repository is**
   - Liberation Circuit is a complete game runtime plus content pack for an RTS/programming game.
   - The executable lives in `bin`, while nearly all engine code is in `src` and game content/scripts live under `bin/story` and `bin/proc`.

2. **Top-level runtime boundary**
   - The game starts from `src/m_main.c`, which pulls together configuration, platform setup, rendering, input, audio, and the main game loop.
   - `bin/init.txt` is the runtime configuration file for resolution, fullscreen, sound volume, key bindings, and similar options.
   - The app expects to run from the `bin` directory so it can read assets and write mission progress/save data there.

3. **Platform and dependency layer**
   - The only major external dependency is **Allegro 5** plus its audio/image/dialog addons.
   - This layer is responsible for windowing, drawing, input events, dialogs, audio playback, and image loading.
   - Files with `i_`, `x_`, and parts of `m_` handle this platform-facing work.

4. **Game simulation core**
   - The `g_` files form the heart of the simulation: world state, unit/proc behavior, movement, packets, groups, procedural execution, and method dispatch.
   - Important pieces include `g_world*` for world/map state, `g_proc*` for processor entities and execution, `g_motion` for movement, `g_packet` for communication, and `g_method*` for the command/API methods available to game scripts.
   - This is the boundary where scripted behavior becomes actual in-game state changes.

5. **Turn and mission orchestration**
   - `f_` and `s_` modules coordinate gameplay progression: loading/saving, turn resolution, mission flow, and menu state transitions.
   - `h_mission` and `h_story` appear to connect mission content to the runtime, including persistence of progress and scenario selection.
   - The engine is not just a freeform sandbox; it is structured around missions and turn/state progression.

6. **In-game programming language toolchain**
   - The `c_` files implement a custom C-like language pipeline: lexer, keywords, preprocessor, compiler, code generation, and initialization.
   - This is the main architectural differentiator of the game: player-authored code is parsed and transformed into executable game logic.
   - The `e_` and `d_` groups support editing, completion, UI assistance, code design/visualization, and related tooling around that language.

7. **Editor and console subsystem**
   - `e_editor`, `e_files`, `e_complete`, `e_help`, `e_log`, `e_tools`, and `e_inter` implement the code-editing experience inside the game.
   - `i_console` and related input/display modules provide the interactive console/debugging/UI surface for scripting and command entry.
   - This means the game includes a built-in development environment, not just a play screen.

8. **UI, panels, and screen composition**
   - `i_display`, `i_view`, `i_background`, `i_buttons`, `i_sysmenu`, and `i_input` are the general UI/navigation layer.
   - `p_` and `v_` modules handle panels and panel rendering/initialization, suggesting a screen system composed of reusable UI panes.
   - This layer sits between user input and the simulation/editor/game states.

9. **Audio subsystem**
   - `x_sound`, `x_music`, and `x_synth` manage sound effects, music playback, and procedural/engine-generated audio.
   - The `bin/data/sound` tree contains the shipped wave assets used by this layer.
   - Audio is content-driven but invoked by gameplay events and UI state changes.

10. **Game content and scripted scenarios**
   - `bin/story` contains mission and campaign scripts organized by color/faction and tutorial content.
   - `bin/proc` contains shared procedure code used by the game’s scripted logic.
   - These files are not engine source in the normal sense; they are game-authored code that the engine loads/compiles/executed through the custom language/runtime.

11. **Asset and presentation data**
   - `bin/data/images` holds fonts and title graphics; `bin/data/sound` and its `music` subfolder hold all audio assets.
   - `bin/Manual.html` is the player manual and also documents the in-game API.
   - Presentation is asset-driven: the engine renders from these packed resources rather than generating most UI art procedurally.

12. **Build and packaging structure**
   - The project supports simple source compilation via `make` or `do`, with the expectation that all C files in `src` are compiled and linked against Allegro.
   - Packaging artifacts for Linux and desktop launchers are present, but they are peripheral to runtime architecture.
   - The key architectural split is still: engine code in `src`, content/scripts in `bin/story` and `bin/proc`, and runtime assets/config in `bin/data` and `bin/init.txt`.

Main entry points: [`src/m_main.c`](https://github.com/linleyh/liberation-circuit/blob/master/src/m_main.c) (Main loop), [`bin/Manual.html`](https://github.com/linleyh/liberation-circuit/blob/master/bin/Manual.html) (Manual), [`bin/data`](https://github.com/linleyh/liberation-circuit/tree/master/bin/data) (Assets), [`bin/init.txt`](https://github.com/linleyh/liberation-circuit/blob/master/bin/init.txt) (Runtime config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_src["Engine src"]
  node_node_main["Main loop<br/>entry/runtime<br/>[m_main.c]"]
  node_node_platform["Platform layer<br/>allegro backend"]
  node_node_ui["UI shell<br/>interface/view"]
  node_node_panels["Panels"]
  node_node_audio["Audio system<br/>sound/music"]
  node_node_sim["Simulation core<br/>world/proc runtime"]
  node_node_world["World state<br/>map/state"]
  node_node_proc["Proc runtime<br/>execution"]
  node_node_methods["Game methods<br/>command API"]
  node_node_turn["Turn flow<br/>progression"]
  node_node_mission["Mission flow<br/>missions"]
  node_node_compiler["C-like compiler<br/>language pipeline"]
  node_node_editor["Editor tools<br/>code editor"]
  node_node_design["Design tools<br/>code viz"]
end

subgraph group_group_bin["Game content"]
  node_node_config["Runtime config<br/>settings<br/>[init.txt]"]
  node_node_story["Story scripts<br/>content code"]
  node_node_proc_content["Proc library<br/>shared scripts"]
  node_node_manual["Manual<br/>docs/api<br/>[Manual.html]"]
  node_node_assets[("Assets<br/>images/sound")]
end

node_node_main -->|"loads"| node_node_config
node_node_main -->|"initializes"| node_node_platform
node_node_main -->|"starts"| node_node_ui
node_node_main -->|"starts"| node_node_audio
node_node_main -->|"runs"| node_node_sim
node_node_platform -->|"uses"| node_node_assets
node_node_ui -->|"composes"| node_node_panels
node_node_ui -->|"hosts"| node_node_editor
node_node_ui -->|"references"| node_node_manual
node_node_sim -->|"maintains"| node_node_world
node_node_sim -->|"executes"| node_node_proc
node_node_sim -->|"invokes"| node_node_methods
node_node_sim -->|"advances"| node_node_turn
node_node_turn -->|"orchestrates"| node_node_mission
node_node_mission -->|"loads"| node_node_story
node_node_mission -->|"includes"| node_node_proc_content
node_node_editor -->|"drives"| node_node_compiler
node_node_editor -->|"supports"| node_node_design
node_node_compiler -->|"produces"| node_node_proc
node_node_manual -->|"documents"| node_node_methods
node_node_assets -->|"skins"| node_node_ui

click node_node_main "https://github.com/linleyh/liberation-circuit/blob/master/src/m_main.c"
click node_node_config "https://github.com/linleyh/liberation-circuit/blob/master/bin/init.txt"
click node_node_story "https://github.com/linleyh/liberation-circuit/tree/master/bin/story"
click node_node_proc_content "https://github.com/linleyh/liberation-circuit/tree/master/bin/proc"
click node_node_manual "https://github.com/linleyh/liberation-circuit/blob/master/bin/Manual.html"
click node_node_assets "https://github.com/linleyh/liberation-circuit/tree/master/bin/data"

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_node_main,node_node_platform,node_node_ui,node_node_panels,node_node_audio,node_node_sim,node_node_world,node_node_proc,node_node_methods,node_node_turn,node_node_mission,node_node_compiler,node_node_editor,node_node_design toneBlue
class node_node_config,node_node_story,node_node_proc_content,node_node_manual,node_node_assets toneAmber
```

## Components

### Engine src

Core runtime, simulation, compiler, UI, and audio code under src/

- [Main loop](https://github.com/linleyh/liberation-circuit/blob/master/src/m_main.c): entry/runtime · Bootstraps config, platform, rendering, input, audio, and the game loop. · `src/m_main.c`
- **Platform layer**: allegro backend · Windowing, input, drawing, dialogs, image loading, and audio device integration.
- **UI shell**: interface/view · General screen composition, navigation, buttons, console, and display plumbing.
- **Panels**: screen panels · Reusable panel initialization and drawing used to compose game/editor screens.
- **Audio system**: sound/music · Sound effects, music playback, and synth-driven audio generation.
- **Simulation core**: world/proc runtime · World state, units, movement, packets, groups, and processor entities.
- **World state**: map/state · World and map representations plus background and map helpers.
- **Proc runtime**: execution · Processor entities, creation, and runtime execution of scripted behavior.
- **Game methods**: command API · Built-in command and method set exposed to scripts and gameplay logic.
- **Turn flow**: progression · Turn resolution and state progression that structure mission play.
- **Mission flow**: missions · Load/save, mission orchestration, and scenario progression.
- **C-like compiler**: language pipeline · Lexer, preprocessor, keywords, compilation, and code generation for player code.
- **Editor tools**: code editor · In-game editing, completion, help, logs, file browsing, and tooling.
- **Design tools**: code viz · Code design, drawing, and geometry helpers supporting the language tooling.

### Game content

Runtime config, assets, missions, and scripted content under bin/

- [Runtime config](https://github.com/linleyh/liberation-circuit/blob/master/bin/init.txt): settings · Startup options and player/runtime settings loaded from bin/init.txt. · `bin/init.txt`
- [Story scripts](https://github.com/linleyh/liberation-circuit/tree/master/bin/story): content code · Faction and tutorial scenario scripts loaded as game-authored code. · `bin/story`
- [Proc library](https://github.com/linleyh/liberation-circuit/tree/master/bin/proc): shared scripts · Shared procedure code used by scripted scenario logic. · `bin/proc`
- [Manual](https://github.com/linleyh/liberation-circuit/blob/master/bin/Manual.html): docs/api · Player manual and API reference bundled with the runtime. · `bin/Manual.html`
- [Assets](https://github.com/linleyh/liberation-circuit/tree/master/bin/data): images/sound · Packed fonts, title art, and audio assets consumed by rendering and sound. · `bin/data`

## Connections

- Main loop → Runtime config: loads · Reads startup settings and bindings before initializing subsystems.
- Main loop → Platform layer: initializes · Creates the platform-facing window, input, display, and audio environment.
- Main loop → UI shell: starts · Brings up navigation, display, and interactive shell surfaces.
- Main loop → Audio system: starts · Initializes sound and music services.
- Main loop → Simulation core: runs · Enters the main gameplay/simulation loop.
- Platform layer → Assets: uses · Loads images and plays packaged audio assets.
- UI shell → Panels: composes · Builds screens from reusable panels.
- UI shell → Editor tools: hosts · Provides the in-game editing and console experience.
- UI shell → Manual: references · Surfaces player-facing documentation and API help.
- Simulation core → World state: maintains · Owns map and world state.
- Simulation core → Proc runtime: executes · Advances processor entities and their scripted behavior.
- Simulation core → Game methods: invokes · Applies gameplay commands and API methods.
- Simulation core → Turn flow: advances · Resolves turn-based progression and state changes.
- Turn flow → Mission flow: orchestrates · Coordinates mission progression and load/save flow.
- Mission flow → Story scripts: loads · Selects and runs scenario scripts.
- Mission flow → Proc library: includes · Reuses shared scripted procedure code.
- Editor tools → C-like compiler: drives · Feeds source text through the language toolchain.
- Editor tools → Design tools: supports · Uses code visualization and design helpers.
- C-like compiler → Proc runtime: produces · Compiles player-authored code into executable game logic.
- Manual → Game methods: documents · Explains the in-game API surface.
- Assets → UI shell: skins · Provides fonts, title art, and sound cues for the UI.