RustRaptor/docs/iron-coast.md

# Iron Coast content packages

Iron Coast Stage 1 contains six independently toggleable mission mods, five shared
weapon and enemy mods, a shared soundtrack, six stage boss mods, and an optional
campaign assembly mod. Enable **Iron Coast S1: Complete Campaign** (`iron_coast_campaign`) to select the full campaign
and its eighteen dependencies automatically. Each individual mission can also be
enabled separately; it selects the five shared content mods, soundtrack and its
own boss. Disabling a package also deselects unused dependencies. When this
affects other packages, a confirmation lists all affected mods; a single-mod
toggle with no dependency changes applies immediately. Dependencies still
needed by another enabled mod remain selected. The Mods manager validates versions
and dependency order and applies the change at the main menu. The new weapons can also be used in the original campaigns;
the enemy packages can be referenced from other missions.

Stage 2 — **Black Tide** adds eight more independent missions, eight bosses,
three shared enemies, two weapons and a three-track soundtrack. Enable
`iron_coast_stage2_campaign` to select that route and its dependencies. See
[Black Tide’s package instructions](../mods/iron_coast_stage2_campaign/README.md).
The [pacing and presentation update](iron-coast-retune.md) documents the current
waves, enemy patterns, weapon feedback and all four difficulty comparisons.

## Mission names

Mission packages and the mission menu share `Iron Coast S<stage> M<mission>: <title>`.
Stages use S1 and S2; mission numbers are zero-padded within each stage. The
campaign packages are **Iron Coast S1: Complete Campaign** and
**Iron Coast S2: Black Tide**. Stable package IDs, mission IDs and dependency
IDs retain their original spelling.

| Stage | Mission | Display name |
| --- | --- | --- |
| 1 | 01 | Iron Coast S1 M01: Breakwater |
| 1 | 02 | Iron Coast S1 M02: Tidal Relay |
| 1 | 03 | Iron Coast S1 M03: Saltworks Convoy |
| 1 | 04 | Iron Coast S1 M04: Stormwall |
| 1 | 05 | Iron Coast S1 M05: Cinder Docks |
| 1 | 06 | Iron Coast S1 M06: Iron Crown |
| 2 | 01 | Iron Coast S2 M01: Nightbreak Inlet |
| 2 | 02 | Iron Coast S2 M02: Undertow Run |
| 2 | 03 | Iron Coast S2 M03: Stormglass Refinery |
| 2 | 04 | Iron Coast S2 M04: Floodgate Zero |
| 2 | 05 | Iron Coast S2 M05: Skybreaker Arsenal |
| 2 | 06 | Iron Coast S2 M06: Emberwake Shipyards |
| 2 | 07 | Iron Coast S2 M07: Siege of the Iron Fleet |
| 2 | 08 | Iron Coast S2 M08: Black Tide |

These labels also identify the standalone Stage 2 campaign entries. The Stage 1
campaign is **Iron Coast S1**, whether Breakwater is enabled alone or the full
six-mission assembly is selected. Artwork, scripts, objectives, waves, rewards
and equipment are unchanged by this naming update.

Changing these display labels changes package content hashes, including when
package versions are unchanged. Existing pilots therefore show the normal changed-mod
confirmation. Accept it only when ready to use the updated packages; stable IDs
preserve equipment and progression, and the game keeps its normal original-save
backup before the next write. This update does not modify pilot files.

| Package | Content |
| --- | --- |
| `iron_coast_campaign` | Links all six missions into one campaign without replacing mission scripts or artwork |
| `iron_coast_mission_1` | Breakwater mission, campaign, supply depots, field repairs, terrain, briefing art and mission audio |
| `iron_coast_mission_2` | Tidal Relay mission and its local communications targets, terrain, briefing art and audio |
| `iron_coast_mission_3` | Saltworks Convoy mission and its local cargo transports, terrain, briefing art and audio |
| `iron_coast_mission_4` | Stormwall mission, cliff batteries, terrain, briefing art and audio |
| `iron_coast_mission_5` | Cinder Docks mission and its armored foundries, coolant repairs, terrain, briefing art and audio |
| `iron_coast_mission_6` | Iron Crown finale, fortified batteries, dreadnoughts, terrain, briefing art and audio |
| `iron_coast_scout` | Airborne scout, weaving AI, projectiles, art and audio |
| `iron_coast_turret` | Ground turret, aimed firing, projectiles, art and audio |
| `iron_coast_boss` | Harbor command ship, persistent patrol and fan volleys, art and audio |
| `iron_coast_boss_2` | Relay Warden, authored movement and firing pattern, SD/HD art and audio |
| `iron_coast_boss_3` | Saltbreaker VTOL, authored movement and firing pattern, SD/HD art and audio |
| `iron_coast_boss_4` | Stormwall Arsenal, authored movement and firing pattern, SD/HD art and audio |
| `iron_coast_boss_5` | Cinder Hammer, authored movement and firing pattern, SD/HD art and audio |
| `iron_coast_boss_6` | Iron Crown Dreadnought, authored movement and firing pattern, SD/HD art and audio |
| `iron_coast_music` | Coastal Steel, original 96-second MUS loop played through the game's Rust FM synthesizer |
| `pulse_cannon` | Primary paired pulses and scripted burst rounds |
| `seeker_swarm` | Selectable homing missile volleys |
| `ion_lance` | Selectable penetrating beam |

All packages use mod API 1. Retuned enemies, bosses and missions use patch
versions 1.0.1 (Iron Crown 1.0.2); the five retuned weapons use 1.1.0.
Unchanged packages retain 1.0.0. Every Stage I mission requires
compatible 1.x versions of its five shared content mods, soundtrack and stage
boss. The campaign assembly requires all six mission packages; shared dependencies are selected transitively.
Save compatibility records each enabled package's exact version and content
hash. A changed or missing mod prompts before loading. Unavailable saved
equipment and progression are retained, and the first subsequent write backs
up the original pilot.

The assembly explicitly overrides `iron_coast_mission_1:campaign`, changing its
mission list from Breakwater alone to missions 1–6. The Mods manager reports
this winning override. Campaign order supplies the next mission when a mission
has no explicit `next` ID, so each mission keeps its own asset root and saved
script identity. Finishing the sixth mission marks it completed and leaves it
available for replay. Disabling the assembly leaves each mission independently
playable. Disabling it while another enabled package needs one of its dependencies
retains that dependency; the confirmation lists the actual affected packages.

## Mission 1: Breakwater

The player raids a coastal industrial harbor. Difficulty-scaled scouts cover the approach,
four ground turrets protect the docks, two destructible supply depots release
repair kits, and the command ship arrives at step 720. Destroy at least two
turrets and the command ship to finish. Surviving turrets stop at y=72 and the boss stays in the playfield until
killed; waiting out the mission duration cannot produce victory. Missing an
early battery does not leave an unreachable required target.

When inventory space allows, the mission grants a trial Pulse Cannon, which
fires alongside forward guns, and three field repairs. The cannon is a mission-only loan and is returned before a successful flight
is saved; a cannon already owned by the pilot remains untouched. A full inventory can still start; new grants are
skipped while existing equipment is preserved. Cycle equipment to **Iron Coast Field Repair** and
press the special button to restore 25 shield per repair. Depots drop extra
repairs. Victory pays 5,000 credits plus ordinary enemy rewards. The central
turrets and boss patrol overlap the starter-gun firing corridor; the mission
is intended to remain playable without the trial weapon.

Script objectives are namespaced and tracked for the current flight. Script
state and completed mission IDs are saved with the pilot:

| Objective | Meaning |
| --- | --- |
| `iron_coast_mission_1:phase` | 1 approach, 2 docks, 3 command ship, 4 complete |
| `iron_coast_mission_1:turrets_required` | Required count of two |
| `iron_coast_turret:defeated` | Turrets destroyed |
| `iron_coast_boss:defeated` | Command ships destroyed |
| `iron_coast_mission_1:depots_opened` | Supply depots destroyed |
| `iron_coast_mission_1:complete` | All required targets destroyed |
| `iron_coast_mission_1:trial_issued` | A loan or an already owned cannon is available |

## Six-mission route

The linked route progresses from the outer harbor to the fleet headquarters.
Every mission requires explicit objectives; reaching its duration never awards
victory. Every mission holds essential structures in the firing area so
missed targets cannot make the rest of a flight impossible. Bosses patrol until
destroyed. Optional scouts and additional enemies pay their normal rewards.

| Mission | Required targets | Completion bonus | Support |
| --- | --- | ---: | --- |
| 1 — Breakwater | Two turrets and one command cruiser | 5,000 | Pulse Cannon loan and three 25-shield field repairs when inventory fits; depot repairs |
| 2 — Tidal Relay | Three radar relays and Relay Warden | 7,500 | Pulse Cannon loan when inventory fits; each destroyed relay restores 12 shield |
| 3 — Saltworks Convoy | Three cargo transports, two escort turrets and Saltbreaker VTOL | 7,500 | Each intercepted transport restores 15 shield; no equipment grant |
| 4 — Stormwall | Four cliff batteries and Stormwall Arsenal | 12,000 | Pulse Cannon loan when inventory fits |
| 5 — Cinder Docks | Two armored foundries and Cinder Hammer | 15,000 | Three selectable 30-shield coolant injectors when inventory fits; outer-lane slag volleys have audible warnings |
| 6 — Iron Crown | Six citadel batteries and two Iron Crown Dreadnoughts, including the final arrival | 30,000 | Ion Lance loan when inventory fits; 25 shield on entry and 20 at each dreadnought phase |

Loaned weapons are returned at mission end; owned weapons remain equipped.
Inventory grants check the twenty-slot limit, including reserve super-shield
modules, and never remove existing equipment to make room. Mission repair
items use normal equipment selection and the **Special** control. Keep **Ctrl**
held to fire, use **Alt** or **Shift** to cycle, **Z** for Special, and **Space**
for a carried bomb with the default bindings.

Missions 2–6 reference original `base:enemy_*` definitions directly. Those foes
retain the original sprite library's flight paths, firing types, animation and
rewards; no mod override substitutes generic downward movement.

Progression records each completed mission and carries shield charge, credits,
equipment and script state into the hangar. The player can buy an original
Energy refill for 10,000 credits to recover 25 shield between sorties. Selecting
a mission directly remains available for replay and independent level mods.

## Art and audio

Original terrain asset `0x10360` and military sprite `0x102f6` were decoded and
inspected before generating the new art with the built-in imagegen skill.
Mission, enemy and weapon packages include generated masters, packaged
SD/HD art, WAV files and prompt/provenance metadata in Git. The assembly owns
its SD/HD campaign portrait; the soundtrack package owns its MUS composition. Original style-reference images remain external; the packaged original
game data is tracked in Git. Mission sources are a generated shoreline texture,
harbor briefing backdrop and transparent supply depot. The source images
remain unchanged; the build step normalizes logical footprints and derives
palette SD versions and HD counterparts.

Mission tiles have 32×32 logical canvases, 32×32 palette SD images and 128×128
HD images. The 288×384 logical shoreline map is converted globally before
cropping into 108 tiles. A reflected copy produces 216 definitions; twelve
forward rows followed by twelve reflected rows give exact matching pixels
at each vertical repetition boundary. This keeps the map continuous but
repeats and reflects port structures. The 72-row mission map uses three such
periods. This is a deliberate first-mission content choice, not unique terrain
for the whole original game.

Briefing/menu art uses a 320×200 logical canvas, with 320×200 SD and 1280×800
HD files. Supply depots preserve a 32×32 collision canvas and transparent
sprite margins; repair icons use 16×16 logical canvases. The asset report
records hashes, palette membership, footprints and repeat-boundary checks.
HD remains constrained by the renderer's indexed palette, so generated color
detail is reduced to the selected palette during play.

Mission audio is original procedural synthesis: approach signal, dock alarm,
boss warning, victory arpeggio, depot impact and repair cue. These are bounded
mono PCM16 WAVs at 22,050 Hz, 0.35–1.2 seconds, made from deterministic
oscillators and seeded noise. No original sound recording, SoundFont or online
audio service is used. The generators and output hashes are tracked. The soundtrack is an original
MUS score played through the same FM synthesizer as the original game music;
its source composition, generated score and provenance are included.

The generated mod assets are included in Git, so a fresh checkout includes
the complete content packages. The original base-game asset catalog is included in the standalone
`RustRaptor/data/` folder and tracked in this repository. Local review captures
and build caches remain excluded from version control.
To rebuild the mission assets from their included generated masters, run:

```sh
python3 mods/iron_coast_mission_1/build_assets.py --palette ../data/misc/PALETTE_DAT
cargo run --no-default-features -- --mods mods --validate-mods iron_coast_scout,iron_coast_turret,iron_coast_boss,iron_coast_music,pulse_cannon,seeker_swarm,ion_lance,iron_coast_mission_1
```

From `RustRaptor/`, validating the full assembly uses all dependencies explicitly
at the CLI (the in-game Mods manager selects them automatically):

```sh
cargo run --no-default-features -- --mods mods --validate-mods iron_coast_scout,iron_coast_turret,iron_coast_boss,iron_coast_boss_2,iron_coast_boss_3,iron_coast_boss_4,iron_coast_boss_5,iron_coast_boss_6,iron_coast_music,pulse_cannon,seeker_swarm,ion_lance,iron_coast_mission_1,iron_coast_mission_2,iron_coast_mission_3,iron_coast_mission_4,iron_coast_mission_5,iron_coast_mission_6,iron_coast_campaign
```

## Acceptance checks

`tests/iron_coast.rs` loads the standalone Breakwater manifests, definitions
and scripts with synthetic PNG/WAV fixtures and the mod-authored MUS score. It checks dependency activation, artwork
footprints, explicit boss/turret completion gating, one-time victory rewards,
and actual headless runs through the scout waves and boss using starter guns
and the trial Pulse Cannon. These tests use no original images and replace the
generated assets with synthetic fixtures. Local package validation additionally checks
the actual generated SD/HD images and WAV files.

The standalone suite also checks mission-only loan cleanup, preservation of
owned equipment, full-inventory starts, and required turrets remaining reachable
after their scheduled entrance. The full campaign run below exercises the
current Mission 1 package together with the later missions and shared soundtrack.

Release measurements exclude compilation.

`tests/iron_coast_campaign.rs` adds six portable structural checks and one
original-data integration check for the complete route. The portable tests
load the real nineteen manifests, content definitions and Rhai scripts with
synthetic PNG/WAV resources. Referenced native IDs receive labeled registry
placeholders only for these structural checks; their movement is tested using
the original catalog in the separate integration run. Generated artwork and
sound files are checked separately by local package validation. The six portable checks passed in **0.54 seconds** in release mode, excluding
compilation. The suite checks automatic dependency selection, shared dependency retention, independent
mission activation, one explicit campaign override, unchanged mission owners,
full twenty-slot inventory starts, explicit-next priority, deterministic
campaign ordering, terminal replay behavior and versioned pilot save/load.

The original-data headless campaign starts with the registered pilot's 75
shield and 10,000 credits at difficulty 2. It holds fire, moves at most four horizontal
pixels per step toward mission structures, turrets, cruisers and scouts, and
uses actual consumable callbacks when shield is at most 70. It carries damage,
equipment, credits and script state between all six flights and round-trips an
atomic save after each victory. It then replays the finale with the recovered
mission and boss state, verifies both boss deaths and keeps exactly six
completed mission records after another save/load. The harness uses no direct shield refills, enemy-damage commands, invulnerability or
objective mutations. Any Energy refills use the actual shop purchase and are
recorded in the report.

The final nineteen-package release run passed in **19.44 seconds**, excluding
compilation, after every package was frozen and ignored bytecode was removed.
It needed no Energy refills or purchased weapons. All original enemy types
authored into missions 2–6 appeared and moved through their native paths.

| Mission | Completion step | Starting shield | Final shield | Total credits | Native types seen moving |
| --- | ---: | ---: | ---: | ---: | ---: |
| 1 — Breakwater | 785 | 75 | 92 | 18,480 | 0 |
| 2 — Tidal Relay | 926 | 92 | 86 | 30,685 | 3 |
| 3 — Saltworks Convoy | 1,290 | 86 | 82 | 43,425 | 4 |
| 4 — Stormwall | 1,217 | 82 | 91 | 61,280 | 6 |
| 5 — Cinder Docks | 1,818 | 91 | 89 | 84,510 | 6 |
| 6 — Iron Crown | 2,428 | 89 | 100 | 122,705 | 6 |

The recovered finale replay also completed in **2,428 steps** with **100 shield**,
bringing credits to **160,900**. Both dreadnought deaths were required again,
and the completed mission list stayed at six entries. Pilot saves and loads
preserved the exact active package versions, hashes, inventory, script state
and script RNG after every flight and the replay. The local JSON report records
these package pins, objectives, native movement metadata and state digests.

The machine-readable report can be captured locally with:

```sh
RAPTOR_TEST_DATA=../data RAPTOR_IRON_COAST_REPORT=../.reference/iron-coast-six-level.json cargo test --locked --release --no-default-features --test iron_coast_campaign -- --ignored --nocapture
```

A passing original-data run establishes a viable continuous route using
ordinary controls and campaign-provided support. It does not establish balance
for every loadout, difficulty or normal-player route. Each individual mission also includes its
own acceptance runner and generated asset provenance.

Visual approval remains provisional: sprite and terrain previews were
inspected for readability, canvas alignment and transparency, with numeric
palette and repeat-seam checks. Wider player testing should assess difficulty,
audio balance and HD details during normal play before treating the new art
as final. These packages extend the Rust engine; they do not establish full
parity across the original campaigns.