Extension Recipes

Recipe 1: insert a linear tactical scenario

1. Create scenarios/NN_New_Scenario.cfg with a unique id.
2. Point the previous scenario’s next_scenario at the new ID.
3. Point the new scenario at the original destination.
4. Add a map only when existing geography cannot carry the story.
5. Use TROW_DEATHS unless the chapter intentionally changes protected-character behavior.
6. Add journey-map support in bigmap.cfg.
7. Validate EASY, NORMAL, and HARD separately.

Recipe 2: add a cutscene that reuses a map

[scenario]
    id=NN_Your_Cutscene
    next_scenario=NN_Next
    map_file=05_The_Oldwood.map
    turns=1
    theme=Cutscene_Minimal
    {AFTERNOON}
[/scenario]

• Use 100% carryover and suppress the carryover report.
• Hide or teleport persistent units instead of creating duplicate IDs accidentally.
• Use store_unit kill=no only when a temporary modified copy is intended.
• Reuse a known map when the changed meaning of the place matters.

Recipe 3: add a fifth Ka’lian-style quest

Five quests have 120 possible completion orders. Prefer automated state tests or a carefully designed pairwise matrix rather than hand-playing every permutation.

Recipe 4: add a named persistent hero

{HERO "Core Unit Type" "Stable Internal ID" _"Display Name" 1 x y "portraits/example.webp"}

• Choose a stable ID before publishing.
• Give recurring heroes the loyal trait through the macro rather than duplicating unit blocks.
• Add a shared death event only when the character’s behavior is stable across scenarios.
• Use stored-unit state when removing the hero temporarily; do not recreate a fresh unit if XP and traits matter.

Recipe 5: add a persistent artifact

Recipe 6: add an achievement safely

1. Define a stable achievement_group and ID in root achievements.cfg.
2. Use a full path for its icon because normal binary paths are unavailable there.
3. Attach [set_achievement] to an existing unambiguous victory or boss event.
4. Test repeated loads and replays; completion actions should be harmless when already complete.
5. Never make required campaign progression depend on local achievement state.

Recipe 7: choose between WML events and Lua AI

Recipe 8: add or replace campaign-local art

• Place binary assets under the campaign’s images/ or sounds/ tree.
• Use campaign-relative paths after the binary path is active.
• Use full data paths in metadata and achievement definitions, where the normal binary-path context may not exist.
• Update ART_LICENSE.txt when a file needs specific attribution or license clarification.
• Update the image manifest and run the consistency report.

Pre-merge extension checklist