Skip to content
Sources: data/AGENTS.md data/mods/AGENTS.md doc/MODDING.md data/mods/TEST_DATA/modinfo.json data/mods/TEST_DATA/effect_on_condition.json Makefile data/reference/json/ccb_json_object_types.json data/reference/json/ccb_eoc_conditions.json data/reference/json/ccb_eoc_effects.json commit d32b9cc880a8 source-and-tests

Complete JSON/EOC mod tutorial

The maintained fixture lives at examples/complete-json-eoc-mod/ in CCB-Docs and contains two files:

complete-json-eoc-mod/
├── modinfo.json
└── eocs.json

1. Declare the mod

modinfo.json is a complete JSON array. Its ID uses a project-specific prefix and explicitly depends on core dda:

[
  {
    "type": "MOD_INFO",
    "id": "ccb_docs_json_eoc_example",
    "name": "CCB Docs JSON/EOC Example",
    "authors": [ "CCB contributors" ],
    "description": "A minimal contract-tested EOC mod used by the bilingual developer documentation.",
    "category": "misc_additions",
    "dependencies": [ "dda" ]
  }
]

2. Add an EOC

eocs.json defines an activation EOC that is not triggered automatically, so merely loading the fixture does not alter normal play:

[
  {
    "type": "effect_on_condition",
    "id": "EOC_CCB_DOCS_HELLO",
    "eoc_type": "ACTIVATION",
    "condition": { "math": [ "1 == 1" ] },
    "effect": [ { "u_message": "The CCB Docs example EOC ran." } ]
  }
]

3. Validate the maintained fixture

Run this from the CCB-Docs root, replacing the path with a CCB clone containing the PR #566 commit:

# validation: docs-json-eoc-example
python3 scripts/check_json_eoc_example_mod.py --source-repo /path/to/Cataclysm-Cleanwater-Bomb

The check parses both JSON files and proves that MOD_INFO, effect_on_condition, math, and u_message exist in generated inventories at the pinned commit. It deliberately does not claim to invoke the game loader.

Run the base repository check from the CCB source root:

# validation: json-load
make -j2 json-check

The current json-check does not scan this external CCB-Docs fixture. Before release, place the directory in a supported third-party mod location and invoke the real loader:

# validation: json-mod-load
ccb_source=/path/to/Cataclysm-Cleanwater-Bomb
ccb_example_user=/tmp/ccb-docs-example-user
mkdir -p "$ccb_example_user/mods"
cp -R examples/complete-json-eoc-mod "$ccb_example_user/mods/ccb_docs_json_eoc_example"
"$ccb_source/cataclysm" --basepath "$ccb_source/" --userdir "$ccb_example_user/" --check-mods ccb_docs_json_eoc_example

After --check-mods succeeds, enable dda plus this mod in a test world, exercise the trigger, and retain the load log.

4. Keep extensions verifiable

  • Confirm every top-level type in the object-type registry.
  • Confirm every condition/effect key in the condition and effect registries.
  • Never treat a lexical_only candidate as a minimal valid contract.
  • Keep IDs stable and mod-prefixed; declare dependencies explicitly.
  • Start from the minimal EOC, then add nesting, variables, and talker use one layer at a time and test each layer with the real loader.