Skip to content
Sources: AGENTS.md ai/project-map.yml src/AGENTS.md data/AGENTS.md tests/AGENTS.md commit d32b9cc880a8 docs-explanation

CCB project architecture

CCB is a data-driven C++ game. The native engine owns object lifetimes, map and save handling, core simulation, UI, and loading. JSON defines much of the game content; EOC expresses conditional behaviour in JSON; Lua Platform v1 exposes the public MOD interface through require("ccb"). The former v5 runtime has been removed and does not apply to the current Candidate.

Layers and dependency direction

  1. Build and platform layer: Make, CMake, Gradle, CI, and packaging scripts define toolchains and artifacts.
  2. Native runtime: src/ owns objects, simulation, UI, serialization, and the native Lua bridge.
  3. Data contracts: data/json/, data/core/, and data/mods/ are consumed by registrations, factories, and validators.
  4. Scripting contract: Lua Platform v1 ModDefinition, LuaLS declarations, native registration, and generated inventories must agree.
  5. Validation layer: tests/ and repository tools validate behaviour, data, public contracts, and generated boundaries.

Data and scripts normally enter through registered engine interfaces. Explanatory documentation is not a new runtime contract, and source semantics must not be changed merely to match stale prose.

Data ownership

  • C++ types own runtime state and serialization invariants.
  • JSON IDs are compatibility boundaries across data, saves, and mods; a rename needs migration or obsoletion data.
  • EOC talkers, variables, and context determine evaluation semantics; field names alone are insufficient.
  • Lua Platform v1 public symbols come from ccb_platform_v1.d.lua and native registration. MODs are trusted code and no longer use the v5 capability manifest.
  • Generated files are derived from source contracts. Fix the generator or source rather than patching output.

Extension points

Prefer an existing JSON type, EOC facility, or supported Lua API for content. Extend C++ only when data interfaces cannot express the required behaviour, and review registration, validation, serialization, tests, and documentation impact together.

CCB selectively ports from CDDA, CBN, and compatible sources while retaining its own behaviour, data, and Lua API. Reviews distinguish shared ancestral behaviour, newer upstream behaviour, and intentional CCB divergence.