Safe edit loop on Xubuntu
1. Start from a clean worktree
git status --short git switch -c trow/your-change git diff --check
Several Wesnoth maintenance tools can rewrite files or create backups. A clean branch makes every generated change visible and reversible.
2. Format and statically inspect WML
python3 data/tools/wmlindent data/campaigns/The_Rise_Of_Wesnoth python3 data/tools/wmllint --dryrun data/campaigns/The_Rise_Of_Wesnoth python3 data/tools/wmlscope data/core data/campaigns/The_Rise_Of_Wesnoth
| Tool | Role | Caution |
|---|---|---|
wmlindent | Normalizes WML indentation. | Review the diff; formatting can touch many lines. |
wmllint | Checks and ports WML constructs. | Use --dryrun first. Write mode creates -bak backups and can modify files. |
wmlscope | Finds unresolved macro, unit, and resource references. | Place mainline WML before the campaign so core symbols are known. |
3. Validate every difficulty
From a Wesnoth source tree or with paths adjusted to the installed data directory:
wesnoth --validate data/_main.cfg --preprocess-defines=EASY,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL wesnoth --validate data/_main.cfg --preprocess-defines=NORMAL,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL wesnoth --validate data/_main.cfg --preprocess-defines=HARD,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL
Campaign validation must be repeated because preprocessor branches can produce different WML on each difficulty. Depending on how the executable was installed or built, add --data-dir and --userconfig-dir.
4. Inspect the preprocessor output
rm -rf /tmp/trow-preprocessed wesnoth -p data/campaigns/The_Rise_Of_Wesnoth /tmp/trow-preprocessed --preprocess-defines=NORMAL,CAMPAIGN_THE_RISE_OF_WESNOTH,DISABLE_GRAND_MARSHAL
This is the fastest way to answer “what did this macro actually produce?” It is especially valuable for Scenario 16’s option macros, Scenario 19’s dynamic variables, and difficulty-specific recruit lists.
5. Launch a target scenario
wesnoth --nocache --campaign=The_Rise_of_Wesnoth --campaign-scenario=19_The_Vanguard
If no difficulty is supplied, the difficulty selector can appear. Add --campaign-difficulty=1, 2, or 3 for a fixed run. --campaign-skip-story can shorten repeated scenario debugging.
From the main menu, F5 also reloads changed WML. --nocache is safer for scripted repeatability.
6. Inspect live state
| Technique | Use |
|---|---|
Run with --debug | Enables extra command-mode operations. |
:inspect | View WML variables, units, recall lists, sides, and AI configuration. |
:help | Lists commands supported by the current build. |
| Save at transition points | Verify stored units and branch variables before and after scenario changes. |
7. Regression matrix
| Change area | Minimum tests |
|---|---|
| Any shared utility or unit type | All three difficulties plus one early, middle, and late scenario using it. |
| Scenario 03–05 routing | Both 04a and 04b, then Scenario 05 cleanup. |
| Jessene identity/storage | Accept and reject in Scenario 02; Scenario 07 reconstruction; Scenarios 18–21 storage paths. |
| Ka’lian hub | Each quest first and last; exhaustive order testing is 24 permutations. |
| Persistent object | Acquire, advance the bearer, save/load, remove the object, and enter the next scenario. |
| Final battle | Every required failure: wrong Aethyr killer, Jevyan too early, zero or two surviving orcs, plus all four escape routes. |
8. Final review
git status --short git diff --check find data/campaigns/The_Rise_Of_Wesnoth -name '*-bak' -o -name '*.bak' git diff --stat git diff
ValidationFAQ · Maintenance tools · Preprocessor reference · Current wmllint source
Bundled maintenance tools
After checking out Wesnoth locally, run tools/trow_unit_dependency_audit.py to refresh the custom-unit closure. Run tools/validate_reference.py before packaging the site.