How linleyh/liberation-circuit works
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: m_main.c Main loop · Manual.html Manual · data Assets · init.txt Runtime config
Components 19
Engine src
Core runtime, simulation, compiler, UI, and audio code under src/
- Main loop · Bootstraps config, platform, rendering, input, audio, and the game loop.
src/m_main.c - Platform layer · Windowing, input, drawing, dialogs, image loading, and audio device integration.
- UI shell · General screen composition, navigation, buttons, console, and display plumbing.
- Panels · Reusable panel initialization and drawing used to compose game/editor screens.
- Audio system · Sound effects, music playback, and synth-driven audio generation.
- Simulation core · World state, units, movement, packets, groups, and processor entities.
- World state · World and map representations plus background and map helpers.
- Proc runtime · Processor entities, creation, and runtime execution of scripted behavior.
- Game methods · Built-in command and method set exposed to scripts and gameplay logic.
- Turn flow · Turn resolution and state progression that structure mission play.
- Mission flow · Load/save, mission orchestration, and scenario progression.
- C-like compiler · Lexer, preprocessor, keywords, compilation, and code generation for player code.
- Editor tools · In-game editing, completion, help, logs, file browsing, and tooling.
- Design tools · Code design, drawing, and geometry helpers supporting the language tooling.
Game content
Runtime config, assets, missions, and scripted content under bin/
- Runtime config · Startup options and player/runtime settings loaded from bin/init.txt.
bin/init.txt - Story scripts · Faction and tutorial scenario scripts loaded as game-authored code.
bin/story - Proc library · Shared procedure code used by scripted scenario logic.
bin/proc - Manual · Player manual and API reference bundled with the runtime.
bin/Manual.html - Assets · Packed fonts, title art, and audio assets consumed by rendering and sound.
bin/data
Connections 21
- 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.