Mod loading¶
Responsibility¶
mod_manager discovers MOD_INFO, builds the dependency graph, selects usable/default mods,
records each world's ordered active list, applies declared mod migrations/removals, and supplies
the ordered source set to data loading.
Entry points¶
Read src/mod_manager.h and src/mod_manager.cpp. refresh_mod_list, load_modfile,
load_mods_list, check_mods_list, and worldfactory world creation/loading are the main
entry points.
Data ownership¶
The manager owns discovered MOD_INFORMATION, dependency state, and migration maps. A WORLD
owns its active ordered mod IDs. Individual factories own objects loaded from those mod paths.
Dependencies¶
Mod loading depends on filesystem paths, modinfo.json, dependency-tree rules, worldfactory,
JSON dispatch, stable IDs, obsoletion/migration data, localization, and optional Lua manifests.
Lifecycle¶
Startup discovers core and user mod directories, validates metadata and dependencies, a world chooses an ordered set, missing/renamed mods are reconciled, then data and scripts load in that order; the list persists with the world.
Invariants¶
Mod IDs are unique and valid; a mod cannot depend on itself; dependencies precede dependents; the world order has no duplicates; missing mods require an explicit migration or user decision; and source attribution retains its mod origin.
Extension points¶
Express metadata, dependencies, conflicts, obsoletion, and migration in data. New loader phases must preserve deterministic order, failure diagnostics, source attribution, and world checks.
Serialization¶
mods.json stores the world's ordered mod IDs; manager registries are rediscovered. Renames or
removals need migration entries so existing worlds are not silently rewritten or corrupted.
Tests¶
Use tests/worldfactory_test.cpp, JSON loading, dependency errors, duplicate IDs, missing mods,
migrations, conflicts, and a complete example-mod load. Include Lua manifest validation when a
mod contains Lua.
Performance¶
Discovery and JSON load are startup costs. Avoid repeated directory traversal, unstable sorting, and reloading whole registries for one metadata query.
CCB divergence¶
CCB's bundled mods, migration tables, Lua v5 manifests, and accepted upstream content form its own compatibility set. Do not substitute another project's default mod list or load policy.
Technical debt¶
Discovery, user decisions, dependency resolution, and data loading are coupled through startup. Future separation must preserve exact order and diagnostics before changing behavior.