CSSL Modules

How a CSSL program names and organizes its source files.

A module is a named part of a program, usually stored in its own file. Modules help keep a larger program organized. CSSL can name modules today, but compiling several CSSL modules together is still unfinished.

Declaring a module

Every CSSL source file begins with one module declaration. The path is reverse-DNS, mirroring the directory layout under the project root.

Reverse-DNS module paths

module com.apocky.loa.main                       // main.cssl
module com.apocky.loa.systems.combat              // systems/combat.csl
module com.apocky.loa.systems.crafting            // systems/crafting.csl
module com.apocky.loa.scenes.city_central_hub     // scenes/city_central_hub.csl
module com.apocky.loa.scenes.dungeon_template     // scenes/dungeon_template.csl

Note

Why reverse-DNS

Reverse-DNS naming begins with a reversed internet domain, such as com.apocky. It helps prevent two projects from accidentally using the same module name. For example,com.apocky.loa.* versus com.apocky.cssl.* versus com.apocky.sigma.*.

Today · single-module compile — available now

csslc build accepts one positional <input> and produces one binary. The auto-default-link mechanism finds cssl-rt and loa-host in compiler-rs/target/release/ and links them in. This is the path that produces the shipping LoA.exe today.

The build command shipping today

csslc build "Labyrinth of Apocalypse/main.cssl" \
  --output target/release/LoA.exe \
  --release
# csslc auto-discovers cssl-rt + loa-host staticlibs and prepends
# them to the linker invocation. The result is a single ~8.9 MB
# self-contained Windows .exe.

Sibling modules · how POD-3 staged the contracts

While csslc is single-module-only, the LoA project already authors all 10 sibling modules in CSSL. They are tracked in git, they declare their extern "C" contracts to the host-side staticlibs, and they are forward-looking specs that future wave-phases compile in place.

Module	Path	Host staticlib
`.systems.combat`	`systems/combat.csl`	`cssl-host-combat-sim`
`.systems.inventory`	`systems/inventory.csl`	`cssl-host-inventory`
`.systems.crafting`	`systems/crafting.csl`	`cssl-host-craft-graph`
`.systems.alchemy`	`systems/alchemy.csl`	`cssl-host-alchemy`
`.systems.magic`	`systems/magic.csl`	`cssl-host-magic`
`.systems.run`	`systems/run.csl`	`cssl-host-roguelike-run`
`.systems.npc`	`systems/npc.csl`	`cssl-host-npc-bt`
`.systems.multiplayer`	`systems/multiplayer.csl`	`cssl-host-mycelium`
`.scenes.city_central_hub`	`scenes/city_central_hub.csl`	`cssl-host-procgen-city`
`.scenes.dungeon_template`	`scenes/dungeon_template.csl`	`cssl-host-procgen-dungeon`

Multi-module compile roadmap — in progress

The main.cssl file documents the gap explicitly. Three POD-4 slices unlock the full multi-module pipeline:

Planned

POD-4-D3 · multi-module compile

Planned command: csslc build main.cssl --module-path systems/combat.csl --module-path systems/...OR auto-discover sibling .csl files from main.cssl's manifest. This unlocks invoking the per-system tick functions from main.

Planned

POD-4-D4 · temporary host functions

Planned: add temporary __cssl_<sys>_tick_* functions so the per-system extern decls resolve while the per-system staticlibs are still in development.

Planned

POD-4-D5..D8 · per-system staticlibs auto-link

Planned: extend the compiler’s automatic linking so it can discover the additional compiled libraries, mirroring how cssl-rt and loa-host are discovered today.

The eventual hot loop

Once the three slices land, main.cssl evolves from the thin shim shipping today into a per-frame driver that calls each sibling's tick:

Forward-looking · main.cssl after POD-4-D3..D8

fn __cssl_loa_frame_tick(dt: f32) -> i32 {
    tick_run_systems(dt) ;          // run.csl       — meta-loop · seed · run-state
    tick_combat_systems(dt) ;       // combat.csl    — combat-sim per-frame step
    tick_npc_systems(dt) ;          // npc.csl       — BT + GOAP planner LOD
    tick_inventory_systems(dt) ;    // inventory.csl — bag + equip + transmute
    tick_crafting_systems(dt) ;     // crafting.csl  — DAG recipe + deconstruct
    tick_alchemy_systems(dt) ;      // alchemy.csl   — brew + reagent-quality
    tick_magic_systems(dt) ;        // magic.csl     — spell + glyph + cast-graph
    tick_multiplayer_systems(dt) ;  // multiplayer.csl — peer-mesh + sync · CRDT
    tick_scene_dungeon(dt) ;        // dungeon_template.csl — floor procgen
    tick_scene_city_hub(dt) ;       // city_central_hub.csl — hub orchestration
    0
}