# AfterWar AI modding — start here (kit v1.0.1)

Official easy mod creation page: https://www.afterwargame.com/modding.php?lang=en#modding-kit
Direct complete kit ZIP: https://www.afterwargame.com/downloads/afterwar-modding-kit-v2.zip?v=1.0.1.20261111-fixes
Complete authoring guide: https://www.afterwargame.com/downloads/afterwar-modding-guide.md
Machine-readable manifest: https://www.afterwargame.com/downloads/afterwar-modding-kit.json

Kit version: 1.0.1. Game support snapshot: 1.0.1. Archive size: 83846082 bytes.

For a new map, the AI can generate connected sector IDs from an opaque RGB24 source image with `generate-world-map`, or edit an independent world directly. The complete instructions include workflows for countries, sectors, images and every supported content family. This kit is for ordinary AI chats and does not require a special agent mode, provider API or platform integration. The chat must be able to receive the kit files, read and write files, and run Python 3.10+. These tools depend on the provider and account; without them, the AI can prepare sources but cannot build the binary `.awmod`.

For edits to inherited Earth map layers, the AI needs access to the matching installation's `game_data.awreal`. Attach/provide that archive to a file-enabled AI environment, or use an environment that can read it locally. The resulting Earth map mod contains the complete map source set and is much larger than a typical partial scenario mod.

Download and extract the entire kit. Read START_HERE.md, AI_INSTRUCTIONS.md and CONTENT_AUTHORING.md. Choose the workflow from the request: edit any current allowlisted entry in an existing .awmod with export-project/build-project; author an existing-map scenario with SCENARIO.md; or create a new universe/map/country and sector IDs with WORLD.md and world.schema.json. Scenario and world country schemas include startup controls and a partial `ai_settings` update for every writable field in the Runtime Mod Studio AIData editor, including diplomacy, relationships, decisions, battle state and garrisons. Existing-map scenarios edit owner and forces for Region, Sea and Ocean sectors by numeric ID, plus population for Region; Lake remains MapSettings-only. Both map workflows also accept partial `map_control_settings` for map display, reflections, shading, normal-generation parameters and label placement. Independent worlds can author city and town records with `cities` and `map-cities.schema.json`. World countries support starting reserves, research and factories. Existing projects can export and edit object catalogs, placements, model assets, routes, variants and climate cells through `scene-objects.schema.json`; `import-glb` converts supported static GLB 2.0 models. Biome definitions, ecology, surface properties and opaque material texture files can be exported and edited with `scene-biomes.schema.json`. Existing-project biome rasters can be reset to the current Sea catalog color with reset-biome-map or exported and edited as exact-pixel opaque RGB24 PNG with `biome-map.schema.json`; preserve the map axes and palette, replace only `scene_biomeTextures.bin`, and delete stale `sector_terrain.bin` for runtime rebuilding. Existing projects can export and edit startup time and all serialized general settings through world-settings.schema.json version 2, including maritime transitions, suppressions, colonization/decolonization progress, abandoned-neutral records, administrator grants and AI war cooldown state. Version 1 documents preserve fields they do not contain. Projects can also edit environment profile versions 1–4 with `map-environment-settings.schema.json`; legacy profiles are upgraded to version 4 when edited, baked environment placements with `map-environment-edits.schema.json` and ordered loading-screen images with `loading-backgrounds.schema.json`. For complete world-source projects, `fill-world-height --mode reset` reproduces the HeightTexture reset without topology; the land/water modes reproduce the fills from sector types. `generate-world-normal` uses the current map normal settings, shade-height lookup, Geography layer and sector types to write the opaque NormalTexture source entry. For an existing project, export and edit map settings through `map-control-settings.schema.json` and city catalogs through `map-cities.schema.json`; use resize-world-project on complete source projects for map dimensions; complete world-source projects can change the repeat count from 1 to 16 with `set-horizontal-map-copies`; rebuild the mod with `prepare-world` and `validate-world` afterward. `content.schema.json` builds country artwork credits; decode existing credit records first to preserve the six ordered fields. Use the structured feature builders listed in CONTENT_AUTHORING.md. The generic project workflow exposes all 85 fixed current Runtime Mod Studio entries plus accepted dynamic names; other entries are edited in their original binary format. Report which families were structurally validated and which were binary-only edits. Never substitute Earth for a requested independent map. Python 3.10+ and file execution on Windows x64 or Linux x64 are sufficient. The tools include their runtime and do not require the game, Unity, SPG, .NET installation, an account or network during authoring.

## Existing-project sector topology

For Runtime Mod Studio's Reset Regions action, run `reset-region-map MyMod.project/project.json --output MyMod.project/topology_assets/region-reset.png`. It writes a new opaque RGB24 PNG filled with #FFFFFF at the exact map dimensions and preserves the source chunk layout. It does not change the project or sector catalog. Use the PNG as `region_map.image` in the exported `topology.schema.json`, then edit the sector list so its registered color IDs match the image and run `edit-topology --allow-pixel-assignment-changes`. The reset image has only one color, so a package is not ready to build until the topology has been reconciled.

For one unregistered map color, run `replace-unknown-region-color MyMod.project/project.json '#A1B2C3' --target-type Region --target-id 123 --output MyMod.project/unknown-color-fixed`. The command replaces only that exact unknown RGB with the selected registered sector color, writes a new project, and marks topology caches for rebuilding. It never selects a target automatically. Repeat for each unknown color, then build and validate the resulting project.

For connected sector cleanup, create a preview plan with `preview-sector-redistribution MyMod.project/project.json --type Region --sector-id 123 --output redistribution-plan.json`, review its component and target counts, then apply that plan with `apply-sector-redistribution MyMod.project/project.json redistribution-plan.json --output MyMod.project/redistributed`. The largest connected component remains assigned to the selected sector. Smaller fragments move only to a registered sector of the same type and subregion, chosen by shared boundary count, then target area, then numeric ID. Fragments without a safe target remain unchanged. The preview detects four-neighbor components and respects horizontal map wrapping. Applying creates a new project, invalidates dependent topology caches, and refuses a stale plan; the source project and sector catalog are preserved. Build the new project with `build-project`, then run `prepare-world` and `validate-world` before delivering the mod so ServerBase adjacency and map caches match the changed pixels.

For boundary-spike cleanup, use `preview-boundary-spike-cleanup` before `apply-boundary-spike-cleanup`. Choose `--scope selected-subregion` with `--type` and `--subregion`, `--scope all-subregions-of-type` with `--type`, or `--scope all-subregions-of-all-types`. Defaults are four passes, four minimum pixels remaining in a sector, and one target contact edge. Only safe one-pixel-wide branches inside typed subregions are removed; the operation rejects bridges, entire thin sectors, disconnected starting sectors, and moves across sector types or subregions. It preserves every sector ID and nonzero area, validates sector connectedness, respects horizontal map wrapping, writes a new project, and refuses a stale preview. One subregion is limited to 4,000,000 planned pixel moves; if reached, narrow the scope or reduce the pass count and preview again. Build that project, then run `prepare-world` and `validate-world` before delivery.

For current Region, Sea, Ocean and Lake metadata, export and edit `topology.schema.json` with `export-topology` and `edit-topology`. The default mode supports sector colors, Lake border values and recoloring flags, and subregion membership by numeric sector ID while keeping each province-map pixel assigned to its existing sector. For any complete world-source project, including an Earth map, pass `--allow-pixel-assignment-changes` to reassign pixels or add a new sector ID. A new ID needs a globally unused numeric ID, a name, a unique RGB color and at least one assigned pixel. New Region, Sea and Ocean records start neutral with zero forces and population; Lake remains MapSettings-only. To delete or merge, omit each removed sector and reassign all of its pixels to surviving registered colors. The transaction removes it from the registry, MapSettings and applicable ServerBase records; prunes subregion membership and Lake-boundary links; and refreshes country control lists and an affected capital. Supported sector references are validated; unresolved references abort the edit. Every remaining sector must retain a pixel. Split by adding a new ID and assigning pixels. For sector ID compaction, use `preview-sector-id-compaction` and `apply-sector-id-compaction`; the apply command is tied to a source-revision plan and stops before output if a binary layout is unsupported. Build the project, then run `prepare-world` and `validate-world` to regenerate and check adjacency, Lake boundaries and map caches.

Sector ID compaction supports clean version 9 scenario country data, remapping current military-entry and schema-v2 general-settings references. Persistent runtime country payloads, active battle payloads and unsupported binary layouts are live simulation state outside static mod authoring; the command stops before writing output for them.

## Existing-map replacement

For a complete source project, replace an existing mod map with `replace-world-map`. Both the target project and source project must contain all world-source entries. The command replaces map and country source data, preserves target metadata and non-map content, removes legacy environment stores absent from the source, and validates references before output. Preserved reference-bearing entries require matching numeric country and sector ID/name catalogs.

```text
python afterwar_modkit.py replace-world-map ExistingMod.project/project.json EarthSource.project/project.json --output ExistingMod.project/new-map
```

Build the new project, then run `prepare-world` and `validate-world`. For an Earth source, create the source project with `import-world-archive` and the matching local `game_data.awreal`.

## Existing-map resize

For a complete world-source project, use `resize-world-project` with a target width, height and one of the nine Runtime Mod Studio anchors. It moves all six source layers and adjusts map-bound cities, objects and environment placements. Cropping is rejected by default if a registered sector would lose every pixel. Add `--remove-lost-sectors` to remove such IDs and their direct topology/country links; every supported remaining reference must validate or the operation stops before output. When both legacy environment placement and model entries are present, resize applies legacy placement edits, merges placements and climate into unified `scene_objects.bin` before moving them, and preserves the model library. Then use `build-project`, `prepare-world` and `validate-world`.

```text
python afterwar_modkit.py resize-world-project Earth.project/project.json 7000 5000 --anchor Center --remove-lost-sectors --output Earth.project/resized
```

## Existing-project biome reset

Use `reset-biome-map` to reproduce Runtime Mod Studio's Reset Biome action with the current Sea biome color. It preserves the existing RGB24 chunk layout and leaves the province map unchanged. Replace the project entry for `scene_biomeTextures.bin`, add `sector_terrain.bin` to `delete_entries`, then build and validate the project.

## Existing-project map source layers

For an Earth map that is inherited from the game, import its `game_data.awreal` to create a complete source project. Add `--mod ExistingEarth.awmod` to merge an existing mod over that base. Without an existing mod, supply `--id` and `--title`:

New Earth map mod:

```text
python afterwar_modkit.py import-world-archive path/to/game_data.awreal --output Earth.project --id earth-map-edit --title "Earth Map Edit"
```

Merge an existing Earth mod over the game base:

```text
python afterwar_modkit.py import-world-archive path/to/game_data.awreal --mod ExistingEarth.awmod --output Earth.project
```

The importer copies the complete map and country source entry set into the project. Building the resulting `.awmod` therefore creates a full map overlay and can produce a much larger archive than a typical partial mod. The game executable is not needed; the authoring environment must be able to access the user's `.awreal` file.

For any project containing the complete world-source entry set, use `export-world-sources` and `edit-world-sources` with `world-sources.schema.json` to edit Regions, Geography, Height, Normal, Biomes and Rivers as PNGs. This image workflow preserves exact dimensions and chunk axes; Regions remains opaque RGB24, Height and Rivers remain grayscale, and other layers remain opaque RGB. Register new sector IDs through `edit-topology --allow-pixel-assignment-changes`, supplying a globally unused numeric ID, name, unique RGB color and assigned pixels. To delete or merge, omit IDs from the topology document and reassign every pixel to surviving registered colors. The transaction updates direct topology records and checks supported references before writing. It creates neutral ServerBase scenario records for new Region, Sea and Ocean IDs with zero forces and population; assign ownership only through a workflow that also updates country control records. Every remaining sector must retain a pixel. Split by adding an ID and assigning pixels. For sector ID compaction, use `preview-sector-id-compaction` and `apply-sector-id-compaction`; the apply command is tied to a source-revision plan and stops before output if a binary layout is unsupported. Build the edited project, then run `prepare-world` and `validate-world` to regenerate textures, topology and map caches.

```text
python afterwar_modkit.py export-world-sources Earth.project/project.json --output map-sources.json
python afterwar_modkit.py export-topology Earth.project/project.json --output topology.json
python afterwar_modkit.py fill-world-height map-sources.json topology.json --mode land --output map-sources-land-filled.json
python afterwar_modkit.py edit-world-sources Earth.project/project.json map-sources-land-filled.json --output Earth.project/maps-edited
python afterwar_modkit.py build-project Earth.project/maps-edited.project.json --output EarthEdited.awmod
python afterwar_modkit.py prepare-world EarthEdited.awmod --output EarthPrepared.awmod
python afterwar_modkit.py validate-world EarthPrepared.awmod
```

## Biome terrain texture authoring

For an existing project, use `export-biome-terrain` and `edit-biome-terrain` with `scene-biome-terrain.schema.json` to update all 12 opaque RGB24 source images and regenerate desktop BC7 plus Android ASTC entries. The bundled ABI 4 compiler works on Windows x64; Linux x64 needs a compatible native library passed with `--native-library`.

## Loading-screen slideshow editing

For an existing project, export the slideshow to original PNG/JPEG files, edit the ordered list and rebuild the binary entry:

```text
python afterwar_modkit.py export-loading-backgrounds MyMod.project/entries/ui_loading_backgrounds.bin --output loading-backgrounds.json
python afterwar_modkit.py edit-loading-backgrounds loading-backgrounds.json --output MyMod.project/entries/ui_loading_backgrounds.edited.bin
```

Replace the matching entry under `entries/`, then run `build-project` and `validate`.

## 3D object catalog and GLB models

Export `scene_objects.bin` to JSON with its models and texture assets, edit the slots and placements, then rebuild the entry:

```text
python afterwar_modkit.py export-scene-objects MyMod.project/entries/scene_objects.bin --output scene-objects.json
python afterwar_modkit.py edit-scene-objects scene-objects.json --output MyMod.project/entries/scene_objects.edited.bin
python afterwar_modkit.py import-glb Tree.glb --output Tree.awmodel
```

The schema exposes model slots, RGB colors, placement transforms, conditional variants, water routes and climate cells. Use `import-glb` for supported static GLB 2.0 models and reference the result from a slot's `model` path. See CONTENT_AUTHORING.md for limits and format details.

## Biome catalog and materials

Use `export-scene-biomes` and `edit-scene-biomes` with `scene-biomes.schema.json` to edit biome ecology, surface properties and opaque albedo/normal/roughness files while preserving their raw payloads.

For a complete AI record in an existing project, export and edit the binary entry through the schema-backed JSON workflow:

```text
python afterwar_modkit.py export-project MyMod.awmod --output MyMod.project
python afterwar_modkit.py export-ai-settings MyMod.project/entries/serverbase_ai.bin --output ai-settings.json
python afterwar_modkit.py edit-ai-settings MyMod.project/entries/serverbase_ai.bin ai-settings.json --output serverbase_ai.edited.bin
```

Replace the AI entry in the project with the edited binary, then run `build-project` and `validate`. Each record can update or create a country AI record with `action: "upsert"`, or remove one with `action: "delete"`; every other AIData field can be edited. Scenario and world country records can use the same `ai_settings` fields directly. All country and sector references use numeric IDs and are checked by validation.

For map display and generation settings, use the version 43 structured codec:

```text
python afterwar_modkit.py export-map-control-settings MyMod.project/entries/mapcontrolsettings.bin --output map-control.json
python afterwar_modkit.py edit-map-control-settings MyMod.project/entries/mapcontrolsettings.bin map-control.json --output mapcontrolsettings.edited.bin
```

Replace the extracted project entry with the edited file, then build and validate the project. Layout-derived fields remain read-only in this codec. Use `set-horizontal-map-copies` on a complete world-source project to change horizontal repeats from 1 to 16; it preserves source pixels while updating layout data and invalidates dependent caches. Build, run `prepare-world` and `validate-world` afterward.

For an existing project's cities and towns, use the current binary city-catalog codec:

```text
python afterwar_modkit.py export-map-cities MyMod.project/entries/scene_cities.bin --output cities.json
python afterwar_modkit.py edit-map-cities MyMod.project/entries/scene_cities.bin cities.json --output scene_cities.edited.bin
```

Replace the extracted city entry and run `build-project` and `validate`. The codec edits city/town IDs, city-map colors and pixels, land Region references, urban styles, placement and translations. Independent worlds accept the same record fields in their `cities` array.

```text
python afterwar_modkit.py build-world examples/NewWorld/world.json --output MyWorld.awmod
python afterwar_modkit.py validate-world MyWorld.awmod
python afterwar_modkit.py prepare-world ExistingWorld.awmod --output PreparedWorld.awmod
```

For an existing map scenario:

```text
python afterwar_modkit.py build scenario.json --output MyScenario.awmod
python afterwar_modkit.py validate MyScenario.awmod
```

Independent worlds supply their own lossless RGB24 province map, registered country/sector IDs, geography and optional heights, normals, biomes and rivers. Chunks are at most 1024 pixels per axis; world dimensions are multiples of four from 64 to 8192. Required topology, neighbors, region cache, battle raster, boundaries, terrain, river geometry/style, ownership and country label caches are prepared from that world's sources. A world without rivers has a valid empty river cache. Runtime GPU uploads, glyphs, scene activation and simulation initialization remain runtime work.

The complete editable fictional world example is examples/NewWorld/. Custom calendars and explicit supported_languages are supported. Optional current-format binary world content is described in WORLD.md. Existing map scenarios may inherit only assets whose dependencies are unchanged. An independent world must not inherit Earth map caches or Earth country assignments.

Deliver the real .awmod, the editable world.json or scenario.json, every referenced source asset and .preparation.json. Require Prepared=true, GameRequired=false and PreparationMode=standalone-world for new worlds or standalone for existing-map scenarios. Validation regenerates/checks caches; it is separate from gameplay verification. If your environment cannot download files or execute the builder, say so before claiming a mod was created. Engine binaries, runtime libraries and the kit itself stay outside .awmod archives. No new hash entries are added to game archives.