Add separate Iron Coast mission, weapon and enemy mods with SD HD artwork and audio

docs/iron-coast.md

@@ -0,0 +1,107 @@
+# Iron Coast content packages
+
+Iron Coast is a local campaign assembled from seven independently toggleable
+mods. Enable all six dependencies before enabling the campaign package. 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.
+
+| Package | Content |
+| --- | --- |
+| `iron_coast_mission_1` | Breakwater mission, campaign, supply depots, field repairs, terrain, briefing art and mission 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 |
+| `pulse_cannon` | Primary paired pulses and scripted burst rounds |
+| `seeker_swarm` | Selectable homing missile volleys |
+| `ion_lance` | Selectable penetrating beam |
+
+All packages are version 1.0.0 and use mod API 1. Mission 1 requires compatible
+1.x versions of the other six. Save compatibility also records each enabled
+package's exact version and content hash.
+
+## Mission 1: Breakwater
+
+The player raids a coastal industrial harbor. Ten 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. The boss stays in the playfield until
+killed; waiting out the mission duration cannot produce victory.
+
+The mission grants a trial Pulse Cannon, which fires alongside forward guns,
+and three field repairs. 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 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 |
+
+## 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.
+Every package includes generated masters, packaged SD/HD art, WAV files and
+prompt/provenance metadata in Git. Original style-reference images and original
+game data remain outside 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 generator and output hashes are tracked.
+
+The generated mod assets are included in Git, so a fresh checkout includes
+the complete seven packages. The original base-game asset catalog is still
+required locally to play the game and remains excluded from version control.
+To rebuild the mission assets from their included generated masters, run:
+
+```sh
+python3 examples/mods/iron_coast_mission_1/build_assets.py --palette data/misc/PALETTE_DAT
+cargo run --no-default-features -- --mods examples/mods --validate-mods iron_coast_scout,iron_coast_turret,iron_coast_boss,pulse_cannon,seeker_swarm,ion_lance,iron_coast_mission_1
+```
+
+## Acceptance checks
+
+`tests/iron_coast.rs` loads all seven real manifests, definitions and scripts
+with synthetic PNG/WAV fixtures. 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.
+
+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.

examples/mods/ion_lance/ART_PROVENANCE.md

@@ -0,0 +1,7 @@
+# ion_lance artwork provenance
+
+Generated locally with the built-in image generation tool and the imagegen skill. Original catalog IDs `0x102b1` (gray gun inventory icon) and `0x101cf` (8×8 projectile) were decoded and inspected as style/scale references. Original pixels are not included in the mod or Git. The prompt uses these references to create a distinct naval industrial weapon rather than copy the original.
+
+Generated master images, SD/HD sprites and sound WAVs are tracked with the package, as requested. Original game pixels and decoded reference images remain outside Git. The generated source is converted into 16×16/64×64 equipment canvases and a 4×32 logical projectile canvas plus its 4× HD counterpart. Transparent margins remain inside the logical canvas. Sound synthesis is deterministic, PCM16 mono 22,050 Hz; `generate_audio.py` is the complete reproduction source.
+
+Prompts and generated-source SHA256 hashes are recorded in `art-provenance.json` after output verification. Palette conversion occurs in the runtime loader; gameplay dimensions do not depend on HD artwork.

examples/mods/ion_lance/README.md

@@ -0,0 +1,9 @@
+# Ion Lance 1.0.0
+
+Enable **Ion Lance** in Mods and apply at the main menu. This independent API 1 example has no dependencies. Buy its equipment in the shop (22,000 credits, maximum one) or collect its pickup. Choose it in Inventory or cycle special weapons during a mission. The equipped weapon fires with Fire or Special; it consumes no ammunition.
+
+Projectile: 8 damage, 12 logical pixels per step, 14 step cooldown, `beam`, air and ground targets. The narrow beam pierces every enemy in its column for two steps (16 total damage per enemy per trigger). Rhai stores bounded burst/hit counters and emits local firing/impact sounds and effects.
+
+`art/equipment-sd.png` is a 16×16 logical icon, `art/equipment-hd.png` its detailed 4× variant. Projectile canvases are 4×32 SD and 16×128 HD. Switch HD artwork in Options. The generated master images, SD/HD sprites, WAV files, provenance and reproduction inputs are tracked in Git. Original game assets and decoded reference images remain outside version control. `python3 generate_audio.py` reproduces both sound files.
+
+Validate locally with `cargo run --no-default-features -- --mods examples/mods --validate-mods ion_lance`. Read the shared [API documentation](../../../docs/modding-api.md) for save pins, dependencies and sandbox limits.

examples/mods/ion_lance/art-provenance.json

@@ -0,0 +1,65 @@
+{
+  "package": "ion_lance",
+  "tool": "built-in image_gen",
+  "skill": "/home/quintine/.codex/skills/.system/imagegen/SKILL.md",
+  "reference_role": "Original catalog sprites inspected as style and scale references, not copied as mod artwork",
+  "reference_assets": [
+    "0x102b1",
+    "0x101cf"
+  ],
+  "sources": [
+    {
+      "kind": "equipment",
+      "path": "/home/quintine/.codex/generated_images/01a12340-dd1f-71e1-869a-0c9f61a82318/exec-2c5afac0-cc57-42f9-a0ca-f01125ba186a.png",
+      "prompt": "Use case: stylized-concept. Asset type: HD sprite for equipment shop/inventory in 1990s military science-fiction vertical shooter. Input image is an ORIGINAL STYLE REFERENCE ONLY, not an edit target. Generate a distinct Ion Lance: compact single long railgun barrel pointing exactly UP from an armored gray rectangular gun pod, two subtle electric-blue induction rails, red service panel. Top-down orthographic overhead view, precise thin symmetrical military silhouette. Isolated single object centered on genuinely transparent 1024x1024 square canvas, silhouette central 70% with12% transparentmargin. Match reference muted gunmetal, chunky readability, upper-left highlight. Restrained panel/machined detail forHD. No text, labels, outside glow/shadows, frame, border, extraobjects. Displaylogical16x16SDand64x64HD, so silhouette must survive reduction.",
+      "sha256": "145215af5159eb196fc18c8c4f9f0e1c318ff552b9a83e4d8fc0d354309da4f5",
+      "local_path": "art/equipment-generated-source.png"
+    },
+    {
+      "kind": "projectile",
+      "path": "/home/quintine/.codex/generated_images/01a12340-dd1f-71e1-869a-0c9f61a82318/exec-da141e14-efd2-4a36-a56f-bbc33225674f.png",
+      "prompt": "Use case: stylized-concept. Asset type: ONE isolated ion beam pulse projectile sprite for a military science-fiction vertical shooter. Original input is STYLE reference only for readable chunky projectile palette. Generate a straight very narrow vertical electric blue/white ion lance beam traveling exactly UP: continuous thin pale core, bounded cobalt/cyan stepped edges, brightest pointed upper tip, slightly tapered bottom tail. No gun, no spacecraft, no extraneous light halo. Orthographic view, perfectly straight, centered, width:height1:8. Genuine transparent square canvas with generous sides and15%transparent top/bottom margin. Pixel-inspired military science-fiction HD detail, minimal colors, reference's crispbounded silhouette. No text, labels, shadows, frame, multiple objects. Intendedlogicalcanvas4x32 and16x128HD.",
+      "sha256": "1a1c19b40354554658a4b72073ed7a7aec9a2bfb185c20d9654a29e2eef75614",
+      "local_path": "art/projectile-generated-source.png"
+    }
+  ],
+  "conversion": "prepare_art.rs crops to alpha>=128 silhouette, fits with transparent margins, preserves aspect and reduces to logical SD/4xHD. SD nearest sampling alpha128; HD Lanczos3 alpha64. Pixel values quantized at runtime.",
+  "outputs": {
+    "art/equipment-generated-source.png": {
+      "sha256": "145215af5159eb196fc18c8c4f9f0e1c318ff552b9a83e4d8fc0d354309da4f5",
+      "bytes": 324909
+    },
+    "art/equipment-sd.png": {
+      "sha256": "bb366d1604bd54079cb5e4c23f7e14aa9da1c9f494e66be1f9f3b870e0adec40",
+      "bytes": 338
+    },
+    "art/equipment-hd.png": {
+      "sha256": "66aa9a088453059518d4f76d961518edc577729018262d270bc6c3d806f665e4",
+      "bytes": 2451
+    },
+    "art/projectile-generated-source.png": {
+      "sha256": "1a1c19b40354554658a4b72073ed7a7aec9a2bfb185c20d9654a29e2eef75614",
+      "bytes": 162173
+    },
+    "art/projectile-sd.png": {
+      "sha256": "d8d2376739d39c343e9afc242b48956fcc8e48bc09fbc626360f8b3c4a52b730",
+      "bytes": 308
+    },
+    "art/projectile-hd.png": {
+      "sha256": "671cae899e2c5c9fd180663255915faaefe14267ddc46bd33ccd04dc51ba0dd4",
+      "bytes": 1688
+    }
+  },
+  "sounds": {
+    "audio/fire.wav": {
+      "sha256": "c155d02643f92f4e06373987d97728052617fca36d8ee9e712199078e89480a6",
+      "bytes": 5776,
+      "synthesis": "generate_audio.py PCM16 mono22050Hz"
+    },
+    "audio/impact.wav": {
+      "sha256": "19b9be1a9fc960faa616a497535f5489c8d3021fc60f324aca9489c1be4a5ab6",
+      "bytes": 7540,
+      "synthesis": "generate_audio.py PCM16 mono22050Hz"
+    }
+  }
+}

examples/mods/ion_lance/content.json

@@ -0,0 +1,67 @@
+{
+  "weapons": [
+    {
+      "id": "ion_lance:projectile",
+      "name": "Ion Lance Projectile",
+      "damage": 8,
+      "speed": 12,
+      "cooldown": 14,
+      "behavior": "beam",
+      "target": "all",
+      "offsets": [
+        [
+          0,
+          -4
+        ]
+      ],
+      "art": {
+        "png": "art/projectile-sd.png",
+        "hd_png": "art/projectile-hd.png",
+        "logical_width": 4,
+        "logical_height": 32,
+        "nearest": true
+      },
+      "script": "scripts/weapon.rhai"
+    }
+  ],
+  "items": [
+    {
+      "id": "ion_lance:equipment",
+      "name": "Ion Lance",
+      "price": 22000,
+      "max_count": 1,
+      "initial_count": 1,
+      "weapon": "ion_lance:projectile",
+      "special": true,
+      "consumable": false,
+      "art": {
+        "png": "art/equipment-sd.png",
+        "hd_png": "art/equipment-hd.png",
+        "logical_width": 16,
+        "logical_height": 16,
+        "nearest": true
+      },
+      "script": "scripts/equipment.rhai"
+    }
+  ],
+  "sounds": [
+    {
+      "id": "ion_lance:fire",
+      "name": "Ion Lance Fire",
+      "file": "audio/fire.wav",
+      "volume": 92,
+      "pan": 127,
+      "pitch": 128,
+      "priority": 1
+    },
+    {
+      "id": "ion_lance:impact",
+      "name": "Ion Lance Impact",
+      "file": "audio/impact.wav",
+      "volume": 78,
+      "pan": 127,
+      "pitch": 128,
+      "priority": 2
+    }
+  ]
+}

examples/mods/ion_lance/generate_audio.py

@@ -0,0 +1,46 @@
+#!/usr/bin/env python3
+"""Reproduce local procedural weapon audio; WAV outputs are tracked with the package."""
+import math
+import struct
+import wave
+from pathlib import Path
+
+PACKAGE = "ion_lance"
+RATE = 22050
+
+def render(kind):
+    duration = 0.13 if kind == "fire" else 0.17
+    count = int(RATE * duration)
+    phase = 0.0
+    seed = 0xA7C51D3
+    samples = []
+    for n in range(count):
+        t = n / count
+        seed ^= (seed << 13) & 0xffffffff
+        seed ^= seed >> 17
+        seed ^= (seed << 5) & 0xffffffff
+        seed &= 0xffffffff
+        noise = (seed / 2147483648.0) - 1.0
+        if PACKAGE == "pulse_cannon":
+            frequency = (1350 * (1 - t) + 190) if kind == "fire" else 130
+            tone = math.sin(phase) * 0.64 + noise * 0.22
+        elif PACKAGE == "seeker_swarm":
+            frequency = 330 + 850 * t if kind == "fire" else 95
+            tone = noise * 0.48 + math.sin(phase) * 0.35
+        else:
+            frequency = 1850 + 680 * t if kind == "fire" else 680 * (1 - t) + 110
+            tone = math.sin(phase) * 0.52 + math.sin(phase * 1.997) * 0.2 + noise * 0.06
+        phase += 2 * math.pi * frequency / RATE
+        attack = min(1.0, n / (RATE * 0.003))
+        envelope = attack * (1 - t) ** (3 if kind == "impact" else 2)
+        samples.append(round(max(-1, min(1, tone * envelope)) * 21000))
+    return struct.pack("<" + "h" * len(samples), *samples)
+
+if __name__ == "__main__":
+    output = Path(__file__).resolve().parent / "audio"
+    output.mkdir(exist_ok=True)
+    for kind in ["fire", "impact"]:
+        with wave.open(str(output / (kind + ".wav")), "wb") as wav:
+            wav.setparams((1, 2, RATE, 0, "NONE", "not compressed"))
+            wav.writeframes(render(kind))
+        print(output / (kind + ".wav"))

examples/mods/ion_lance/mod.toml

@@ -0,0 +1,7 @@
+id = "ion_lance"
+name = "Ion Lance"
+version = "1.0.0"
+api_version = 1
+description = "Naval science-fiction ion lance: independent weapon, equipment, SD/HD artwork and local firing/impact audio."
+content = "content.json"
+scripts = ["scripts/weapon.rhai", "scripts/equipment.rhai"]

examples/mods/ion_lance/prepare_art.rs

@@ -0,0 +1,90 @@
+//! Build game-ready logical and HD PNG canvases from the inspected generated sources.
+//! Compile with the project's image dependency, then pass equipment source, shot source.
+use image::{Rgba, RgbaImage, imageops};
+use std::{env, fs, path::Path};
+const PACKAGE: &str = "ion_lance";
+const SHOT: (u32, u32) = (4, 32);
+fn canvas(source: &RgbaImage, width: u32, height: u32, hd: bool) -> RgbaImage {
+    // Only the solid silhouette defines its fitting box; faint outer glows stay bounded.
+    let mut bounds = (source.width(), source.height(), 0, 0);
+    for (x, y, p) in source.enumerate_pixels() {
+        if p[3] >= 128 {
+            bounds.0 = bounds.0.min(x);
+            bounds.1 = bounds.1.min(y);
+            bounds.2 = bounds.2.max(x + 1);
+            bounds.3 = bounds.3.max(y + 1);
+        }
+    }
+    assert!(
+        bounds.2 > bounds.0 && bounds.3 > bounds.1,
+        "source has no opaque silhouette"
+    );
+    let cropped = imageops::crop_imm(
+        source,
+        bounds.0,
+        bounds.1,
+        bounds.2 - bounds.0,
+        bounds.3 - bounds.1,
+    )
+    .to_image();
+    let margin = if hd { 4 } else { 1 };
+    let available = (
+        width.saturating_sub(margin * 2).max(1),
+        height.saturating_sub(margin * 2).max(1),
+    );
+    let factor = (available.0 as f64 / cropped.width() as f64)
+        .min(available.1 as f64 / cropped.height() as f64);
+    let size = (
+        (cropped.width() as f64 * factor).round().max(1.) as u32,
+        (cropped.height() as f64 * factor).round().max(1.) as u32,
+    );
+    let filter = if hd {
+        imageops::FilterType::Lanczos3
+    } else {
+        imageops::FilterType::Nearest
+    };
+    let mut scaled = imageops::resize(&cropped, size.0, size.1, filter);
+    for p in scaled.pixels_mut() {
+        if p[3] < (if hd { 64 } else { 128 }) {
+            *p = Rgba([0, 0, 0, 0]);
+        } else {
+            p[3] = 255;
+        }
+    }
+    let mut out = RgbaImage::new(width, height);
+    imageops::overlay(
+        &mut out,
+        &scaled,
+        ((width - size.0) / 2) as i64,
+        ((height - size.1) / 2) as i64,
+    );
+    out
+}
+fn main() {
+    let args: Vec<_> = env::args_os().collect();
+    assert_eq!(
+        args.len(),
+        4,
+        "usage: prepare_art EQUIPMENT_SOURCE SHOT_SOURCE PACKAGE_DIRECTORY"
+    );
+    let output = Path::new(&args[3]).join("art");
+    fs::create_dir_all(&output).unwrap();
+    for (kind, path, logical) in [
+        ("equipment", &args[1], (16, 16)),
+        ("projectile", &args[2], SHOT),
+    ] {
+        let source = image::open(path).unwrap().into_rgba8();
+        fs::copy(path, output.join(format!("{kind}-generated-source.png"))).unwrap();
+        for (mode, scale) in [("sd", 1), ("hd", 4)] {
+            let image = canvas(&source, logical.0 * scale, logical.1 * scale, scale == 4);
+            let path = output.join(format!("{kind}-{mode}.png"));
+            image.save(&path).unwrap();
+            println!(
+                "{PACKAGE}: {}×{} {}",
+                image.width(),
+                image.height(),
+                path.display()
+            );
+        }
+    }
+}

examples/mods/ion_lance/scripts/equipment.rhai

@@ -0,0 +1,6 @@
+// Recovery is recorded separately from the weapon firing state.
+fn on_pickup(event, state, random) {
+    let recovered = if state.contains("recovered") { state.recovered % 100000 + 1 } else { 1 };
+    #{ commands: [#{ op: "objective", key: "ion_lance:recovered", value: recovered }],
+       state: #{ recovered: recovered } }
+}

examples/mods/ion_lance/scripts/weapon.rhai

@@ -0,0 +1,21 @@
+// Built-in beam projectiles handle the normal volley and collision rules.
+// Callbacks add deterministic visuals, audio and serializable weapon counters.
+fn on_fire(event, state, random) {
+    let bursts = if state.contains("bursts") { state.bursts % 100000 + 1 } else { 1 };
+    let hits = if state.contains("hits") { state.hits } else { 0 };
+    let commands = [
+        #{ op: "play_sound", sound: "ion_lance:fire" },
+#{ op: "effect", x: event.x, y: event.y - 3 }
+    ];
+    #{ commands: commands, state: #{ bursts: bursts, hits: hits } }
+}
+
+fn on_hit(event, state, random) {
+    let bursts = if state.contains("bursts") { state.bursts } else { 0 };
+    let hits = if state.contains("hits") { state.hits % 100000 + 1 } else { 1 };
+    let commands = [
+        #{ op: "play_sound", sound: "ion_lance:impact" },
+        #{ op: "effect", x: event.x, y: event.y }
+    ];
+    #{ commands: commands, state: #{ bursts: bursts, hits: hits } }
+}

examples/mods/iron_coast_boss/README.md

@@ -0,0 +1,17 @@
+# Iron Coast Command Cruiser
+
+Independent version 1.0.0 enemy package for mod API 1. Enable/disable it from the in-game Mods screen and use it in any mission through `iron_coast_boss:unit`. Iron Coast mission 1 supplies placements and completion objectives; this package does not add a mission or override base content.
+
+Airborne command cruiser enters at 2 pixels/tick, settles at y24 and patrols x80..144 indefinitely. It fires a fan of three 3 damage shells every 54 ticks. A standard pilot can destroy it with starter guns; it stays in their firing corridor.
+
+Logical collision canvas `96×64`, top-left anchor `(0,0)`, health `160`, reward `1800` credits, firing interval `54` simulation ticks. The engine halves boss health on difficulties 0/1; difficulty 2/3 uses the declared health. SD mode uses `art/unit-sd.png`; enable HD art in Settings for `art/unit-hd.png`. The HD canvas is 8× logical resolution and bypasses automatic ScaleNx. Projectile artwork has an 8×8 logical canvas and an independent 64×64 HD version.
+
+The boss uses two registered frames (idle/amber charged); the scout and turret use stable single frames. All supplied variants stay on the same canvas and anchor. `art-qa.json` records transparency bounds and, for the boss, animation silhouette overlap.
+
+Enemy deaths increment the current mission objective `iron_coast_boss:defeated`. Persistent script `destroyed`, `hits` and `shots` counters are statistics; current-mission objectives reset when the mission restarts. Callbacks guard retired entities and use deterministic simulation data. No wall clock or unseeded random input enters the scripts.
+
+Generated PNG masters, SD/HD strips, previews and WAV sounds are included in Git. Original reference images under `art/source/` are excluded. Exact built-in imagegen prompts are in `prompts/`, with source IDs and generated-image provenance in `provenance.json`.
+
+To rebuild derived artwork from supplied generated masters and regenerate audio, install Pillow and run `python3 build_assets.py`. To regenerate only audio with the Python standard library, run `python3 build_assets.py --audio-only`. WAVs are original procedural mono 16-bit PCM at 22050 Hz; `audio-recipe.json` records deterministic seeds, sizes and hashes. The art pipeline resizes and assembles supplied images; it does not redraw them.
+
+Validate from the repository root: `cargo run -- --mods examples/mods --validate-mods iron_coast_boss`. Synthetic behavior and save/replay tests: `cargo test --test enemies_mods`. Verify shipped artwork locally: `cargo test --test enemies_mods shipped_enemy_assets_are_valid_and_aligned`.

examples/mods/iron_coast_boss/art-qa.json

@@ -0,0 +1,41 @@
+{
+  "logical_size": [
+    96,
+    64
+  ],
+  "hd_scale": 8,
+  "origin": [
+    0,
+    0
+  ],
+  "frames": 2,
+  "frame_order": [
+    "idle",
+    "charged"
+  ],
+  "alpha": "Preserved RGBA; runtime uses alpha>=128 indexed transparency",
+  "registration": "Common full-canvas resize and equal padding for every frame",
+  "sources": [
+    {
+      "source": "art/unit-generated-v1.png",
+      "source_sha256": "87d644a5d584ad82e285241e3a5cdc58e5c61fa851415a4d6660e0ae83ec5e85",
+      "sd_opaque_bounds": [
+        25,
+        3,
+        71,
+        61
+      ]
+    },
+    {
+      "source": "art/unit-charge-generated-v1.png",
+      "source_sha256": "cc8401140982260b4675a0a28fd209b8ed8d636e4cd4fa98a9cdf2fed37b1bff",
+      "sd_opaque_bounds": [
+        25,
+        3,
+        71,
+        61
+      ]
+    }
+  ],
+  "animation_silhouette_overlap": 0.9985000050675504
+}

examples/mods/iron_coast_boss/audio-recipe.json

@@ -0,0 +1,23 @@
+{
+  "generator": "build_assets.py deterministic chirp/noise synthesis; no recordings",
+  "kind": "boss",
+  "seed": 83,
+  "files": {
+    "audio/shot.wav": {
+      "sample_rate": 22050,
+      "channels": 1,
+      "bits": 16,
+      "samples": 5292,
+      "peak": 25558,
+      "sha256": "32d2e5ea26a9333f8163f7653c9b5a7dc00cf16ac9956f4abfbf32802ca459a7"
+    },
+    "audio/death.wav": {
+      "sample_rate": 22050,
+      "channels": 1,
+      "bits": 16,
+      "samples": 19845,
+      "peak": 25558,
+      "sha256": "3bf364c2fa21dbaca81af03e9d2e19552ede430912e1bd4fd967da0611a0c438"
+    }
+  }
+}

examples/mods/iron_coast_boss/build_assets.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""Convert saved imagegen artwork and synthesize reproducible package-local WAVs.
+
+This script resizes/atlases supplied art; it never redraws source or generated art.
+Generated source PNGs stay in ignored art/. See prompts/ and provenance.json.
+Use --audio-only to regenerate sound without Pillow or private artwork.
+"""
+import argparse
+import hashlib
+import json
+import math
+from pathlib import Path
+import random
+import struct
+import wave
+
+
+def sounds(root, kind):
+    rate = 22050
+    values = {
+        "scout": (0.11, 1400, 380, 0.34, 230, 19),
+        "turret": (0.18, 900, 160, 0.52, 150, 37),
+        "boss": (0.24, 500, 80, 0.90, 75, 83),
+    }
+    shot_length, start, end, death_length, bass, seed = values[kind]
+    (root / "audio").mkdir(exist_ok=True)
+    stats = {}
+    for name, duration in [("shot", shot_length), ("death", death_length)]:
+        rng = random.Random(seed + (100 if name == "death" else 0))
+        count = int(duration * rate)
+        phase = low_noise = 0.0
+        samples = []
+        for index in range(count):
+            t = index / rate
+            position = index / max(1, count - 1)
+            noise = rng.uniform(-1, 1)
+            low_noise = low_noise * 0.86 + noise * 0.14
+            if name == "shot":
+                frequency = end + (start - end) * (1 - position) ** 2
+                phase += 2 * math.pi * frequency / rate
+                value = (0.60 * math.sin(phase) + 0.15 * math.sin(2.31 * phase)
+                         + 0.16 * noise + 0.16 * math.sin(2 * math.pi * bass * t))
+                envelope = min(1, t / 0.002) * math.exp(-position * 6.0)
+            else:
+                frequency = bass * (1.0 - position * 0.65)
+                phase += 2 * math.pi * frequency / rate
+                value = 0.62 * low_noise + 0.19 * noise + 0.28 * math.sin(phase)
+                envelope = min(1, t / 0.003) * math.exp(-position * 4.7)
+            # Five milliseconds at the tail avoid discontinuities at mixer retirement.
+            envelope *= min(1, (count - 1 - index) / (rate * 0.005))
+            samples.append(value * max(0, envelope))
+        peak = max(abs(value) for value in samples)
+        pcm = [round(value / peak * 0.78 * 32767) for value in samples]
+        path = root / "audio" / (name + ".wav")
+        with wave.open(str(path), "wb") as output:
+            output.setnchannels(1)
+            output.setsampwidth(2)
+            output.setframerate(rate)
+            output.writeframes(struct.pack("<" + "h" * len(pcm), *pcm))
+        stats[str(path.relative_to(root))] = {
+            "sample_rate": rate, "channels": 1, "bits": 16,
+            "samples": count, "peak": max(abs(value) for value in pcm),
+            "sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+        }
+    (root / "audio-recipe.json").write_text(json.dumps({
+        "generator": "build_assets.py deterministic chirp/noise synthesis; no recordings",
+        "kind": kind, "seed": seed, "files": stats,
+    }, indent=2) + "\n")
+
+
+def artwork(root, kind):
+    from PIL import Image
+    dimensions = {"scout": (24, 24), "turret": (32, 32), "boss": (96, 64)}
+    width, height = dimensions[kind]
+    paths = [root / "art/unit-generated-v1.png"]
+    if kind == "boss":
+        paths.append(root / "art/unit-charge-generated-v1.png")
+    hd_frames, sd_frames = [], []
+    stats = []
+    for path in paths:
+        source = Image.open(path).convert("RGBA")
+        if source.width * height != source.height * width:
+            raise ValueError(f"{path}: source canvas aspect differs from logical canvas")
+        # Identical canvas resize and padding for all frames retain their registration.
+        hd = Image.new("RGBA", (width * 8, height * 8), (0, 0, 0, 0))
+        pad_x, pad_y = width // 3, height // 3
+        resized = source.resize((hd.width - 2 * pad_x, hd.height - 2 * pad_y), Image.Resampling.LANCZOS)
+        hd.alpha_composite(resized, (pad_x, pad_y))
+        sd = hd.resize((width, height), Image.Resampling.BOX)
+        for image in [hd, sd]:
+            bbox = image.getchannel("A").point(lambda value: 255 if value >= 128 else 0).getbbox()
+            if bbox is None or bbox[0] == 0 or bbox[1] == 0 or bbox[2] == image.width or bbox[3] == image.height:
+                raise ValueError(f"{path}: opaque silhouette touches logical canvas edge")
+        hd_frames.append(hd)
+        sd_frames.append(sd)
+        stats.append({"source": str(path.relative_to(root)),
+                      "source_sha256": hashlib.sha256(path.read_bytes()).hexdigest(),
+                      "sd_opaque_bounds": list(sd.getchannel("A").point(lambda value: 255 if value >= 128 else 0).getbbox())})
+    for name, frames in [("unit-hd.png", hd_frames), ("unit-sd.png", sd_frames)]:
+        atlas = Image.new("RGBA", (frames[0].width * len(frames), frames[0].height), (0, 0, 0, 0))
+        for index, frame in enumerate(frames):
+            atlas.alpha_composite(frame, (index * frame.width, 0))
+        atlas.save(root / "art" / name)
+    # Shared visual ammunition language; each package includes its own local copy.
+    source = Image.open(root / "art/projectile-generated-v1.png").convert("RGBA")
+    hd = source.resize((64, 64), Image.Resampling.LANCZOS)
+    hd.save(root / "art/projectile-hd.png")
+    hd.resize((8, 8), Image.Resampling.BOX).save(root / "art/projectile-sd.png")
+    metadata = {"logical_size": [width, height], "hd_scale": 8, "origin": [0, 0],
+                "frames": len(paths), "frame_order": ["idle", "charged"][:len(paths)],
+                "alpha": "Preserved RGBA; runtime uses alpha>=128 indexed transparency",
+                "registration": "Common full-canvas resize and equal padding for every frame",
+                "sources": stats}
+    if len(hd_frames) == 2:
+        masks = [f.getchannel("A").point(lambda value: 255 if value >= 128 else 0) for f in hd_frames]
+        pairs = list(zip(masks[0].get_flattened_data(), masks[1].get_flattened_data()))
+        metadata["animation_silhouette_overlap"] = sum(bool(a and b) for a, b in pairs) / sum(bool(a or b) for a, b in pairs)
+        if metadata["animation_silhouette_overlap"] < 0.99:
+            raise ValueError("generated animation changes the silhouette beyond accepted registration tolerance")
+    (root / "art-qa.json").write_text(json.dumps(metadata, indent=2) + "\n")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--audio-only", action="store_true")
+    args = parser.parse_args()
+    root = Path(__file__).resolve().parent
+    kind = root.name.removeprefix("iron_coast_")
+    sounds(root, kind)
+    if not args.audio_only:
+        artwork(root, kind)
+    print(f"Generated {root.name} package assets")
+
+
+if __name__ == "__main__":
+    main()

examples/mods/iron_coast_boss/content.json

@@ -0,0 +1,59 @@
+{
+  "weapons": [
+    {
+      "id": "iron_coast_boss:projectile",
+      "name": "Iron Coast Command Cruiser cannon shell",
+      "damage": 3,
+      "speed": 4,
+      "cooldown": 54,
+      "behavior": "straight",
+      "target": "all",
+      "art": {
+        "png": "art/projectile-sd.png",
+        "hd_png": "art/projectile-hd.png",
+        "logical_width": 8,
+        "logical_height": 8
+      }
+    }
+  ],
+  "enemies": [
+    {
+      "id": "iron_coast_boss:unit",
+      "name": "Iron Coast Command Cruiser",
+      "health": 160,
+      "speed": 0,
+      "reward": 1800,
+      "ground": false,
+      "boss": true,
+      "cooldown": 54,
+      "art": {
+        "png": "art/unit-sd.png",
+        "hd_png": "art/unit-hd.png",
+        "logical_width": 96,
+        "logical_height": 64,
+        "frames": 2
+      },
+      "script": "scripts/ai.rhai"
+    }
+  ],
+  "sounds": [
+    {
+      "id": "iron_coast_boss:shot",
+      "name": "Iron Coast Command Cruiser cannon",
+      "file": "audio/shot.wav",
+      "volume": 95,
+      "pan": 127,
+      "pitch": 128,
+      "priority": 2
+    },
+    {
+      "id": "iron_coast_boss:death",
+      "name": "Iron Coast Command Cruiser destruction",
+      "file": "audio/death.wav",
+      "volume": 120,
+      "pan": 127,
+      "pitch": 128,
+      "priority": 4
+    }
+  ]
+}

examples/mods/iron_coast_boss/mod.toml

@@ -0,0 +1,7 @@
+id = "iron_coast_boss"
+name = "Iron Coast Command Cruiser"
+version = "1.0.0"
+api_version = 1
+description = "A persistent patrol boss with a three-shell cannon fan. Includes SD and HD artwork, deterministic Rhai AI and generated sound effects."
+content = "content.json"
+scripts = ["scripts/ai.rhai"]

examples/mods/iron_coast_boss/prompts/projectile-hd-v1.txt

@@ -0,0 +1,6 @@
+Use case: style-transfer
+Asset type: transparent HD projectile sprite for hostile cannon fire in a top-down military science-fiction shoot-em-up.
+Input: original Raptor ESHOT_BLK 8×8 amber projectile, enlarged nearest-neighbor, is a reference for color and readability.
+Primary request: a single small compact circular amber/orange energy shell viewed directly overhead, bright pale-yellow center fading to orange metal/plasma rim, dark crisp outer edge. Match the naval steel/amber Raptor remaster style. It will be reduced to an 8×8 logical square, so keep a simple readable round footprint and avoid microdetails. This is one ammunition projectile, no weapon or spacecraft.
+Composition: perfectly centered isolated circular sprite on square canvas, visible orb occupies about62% width/height with equal large transparent margins. Keep all glow contained inside the circular orb, no external haze, shadow, trail or rays. Do not stretch it.
+Constraints: true transparent background, no extra objects, no checkerboard or black background baked into pixels, no text, logos, watermarks, perspective or decorative framing.

examples/mods/iron_coast_boss/prompts/unit-charge-v1.txt

@@ -0,0 +1,3 @@
+Use case: precise-object-edit
+Asset type: second animation frame of the Iron Coast Command Cruiser boss HD sprite.
+Input image is the completed sprite edit target. Create a charged-weapons variant changing ONLY the existing small amber lamps and the two central circular side cannon wells: slightly brighten those lamps and illuminate inside each cannon well with a compact amber/orange core. Keep every hull panel, prong, silhouette edge, x/y anchor, exact 3:2 image dimensions, and camera view pixel-aligned with the input. No new external glow, muzzle flash, particles, smoke or shadow. Preserve the exact transparent background and empty side margins. Add a thin transparent margin around top/bottom if necessary to avoid edge clipping, but do not shift or reshape the vessel. Do not render a background, text, logos or watermarks. Single isolated overhead sprite facing DOWN.

examples/mods/iron_coast_boss/prompts/unit-hd-v1.txt

@@ -0,0 +1,6 @@
+Use case: style-transfer
+Asset type: transparent HD enemy boss sprite for a top-down vertical shoot-em-up, Iron Coast Command Cruiser.
+Input image: original Raptor SHIP32G1_PIC (96×64 logical canvas, enlarged nearest-neighbor) is the source of truth for silhouette, proportions, center anchoring and DOWNWARD orientation.
+Primary request: regenerate the pictured large military science-fiction coastal command cruiser as clean HD game art. Preserve the original very specific shape: tall central armored hull oriented vertically nose DOWN, twin small stern engine towers at the TOP, wide lateral blocky wing/weapon platforms across the upper-middle, a central bridge/reactor block, and two prongs flanking the narrow lower bow. Keep all sections recognizable and in the same positions. Heavy naval steel/slate plates, subtle olive and brown industrial accents, bolted hatches, narrow amber status lamps, small red service panels. Original utilitarian Raptor overhead sprite style with sharper surface detail. It is one aircraft/hover cruiser rather than a ship floating in water.
+Composition: a WIDE 3:2 transparent canvas corresponding exactly to96×64 logical pixels. Full perfectly top-down view without perspective. Cruiser centered on x48,y32. Keep original transparent side margins: actual vessel about55% of canvas width and94% of canvas height, with no clipping or cropped tips. Bow points downward. Do not rotate or enlarge the vessel to fill the side margins. Gentle light from upper-left, crisp silhouette, no external shadow.
+Constraints: one isolated single sprite, true transparent background. No sea, terrain, floor, wake, exhaust trails, motion blur, text, logos, watermark, smoke, UI, borders or painted checkerboard. Preserve the attached silhouette and exact canvas proportions.

examples/mods/iron_coast_boss/provenance.json

@@ -0,0 +1,36 @@
+{
+  "api_version": 1,
+  "mod_version": "1.0.0",
+  "tool": "built-in image_gen.imagegen via imagegen skill",
+  "skill": "/home/quintine/.codex/skills/.system/imagegen/SKILL.md",
+  "generated_at": "2026-10-10",
+  "source_reference": {
+    "asset_id_hex": "10335",
+    "catalog_path": "sprites/SHIP32G1_PIC",
+    "sha256": "640ed8f1d45ead01337ce2ed95a1be1b44f88fe0cfecdc61e98537093d1e9324",
+    "role": "Original silhouette/orientation/style reference inspected before imagegen. Original reference pixels excluded from Git under art/source/."
+  },
+  "assets": [
+    {
+      "file": "art/unit-generated-v1.png",
+      "prompt": "prompts/unit-hd-v1.txt",
+      "tool_output": "exec-3e7092b2-f469-4d4d-9eee-c7d760172125.png",
+      "sha256": "87d644a5d584ad82e285241e3a5cdc58e5c61fa851415a4d6660e0ae83ec5e85"
+    },
+    {
+      "file": "art/unit-charge-generated-v1.png",
+      "prompt": "prompts/unit-charge-v1.txt",
+      "tool_output": "exec-7a5f11a2-bb90-4007-81c1-865e2058f912.png",
+      "sha256": "cc8401140982260b4675a0a28fd209b8ed8d636e4cd4fa98a9cdf2fed37b1bff"
+    },
+    {
+      "file": "art/projectile-generated-v1.png",
+      "prompt": "prompts/projectile-hd-v1.txt",
+      "tool_output": "exec-96076703-18b2-4aad-9bce-4eaceef4d8bd.png",
+      "note": "Common generated amber projectile copied into each independent package.",
+      "sha256": "386709d83ebf8a9e6c5119c785afc77152ae934780b3b0afcf8ede510622bc20"
+    }
+  ],
+  "pipeline": "build_assets.py: common full-canvas resize/padding, alpha-preserving RGBA SD/8xHD strips; no bitmap redraw",
+  "version_control": "Generated masters, shipped SD/HD artwork, previews and synthesized WAVs included in Git per user request. Original catalog reference pixels excluded."
+}

examples/mods/iron_coast_boss/scripts/ai.rhai

@@ -0,0 +1,56 @@
+fn is_alive(event) {
+    for unit in event.entities {
+        if unit.entity == event.entity && unit.health > 0 { return true; }
+    }
+    false
+}
+
+// Per-entity directions permit multiple cruisers without sharing a patrol cursor.
+fn on_spawn(event, state, random) {
+    if !is_alive(event) { return #{ commands: [], state: state }; }
+    if !state.contains("directions") { state.directions = #{}; }
+    state.directions[event.entity.to_string()] = 1;
+    #{ commands: [#{ op: "velocity", entity: event.entity, vx: 0, vy: 2 }], state: state }
+}
+
+fn on_tick(event, state, random) {
+    if event.health <= 0 || !is_alive(event) { return #{ commands: [], state: state }; }
+    if event.y < 24 {
+        return #{ commands: [#{ op: "velocity", entity: event.entity, vx: 0, vy: 2 }], state: state };
+    }
+    let key = event.entity.to_string();
+    if !state.contains("directions") { state.directions = #{}; }
+    let direction = if state.directions.contains(key) { state.directions[key] } else { 1 };
+    if event.x >= 144 { direction = -1; }
+    if event.x <= 80 { direction = 1; }
+    state.directions[key] = direction;
+    let commands = [
+        #{ op: "move", entity: event.entity, x: event.x, y: 24 },
+        #{ op: "velocity", entity: event.entity, vx: direction, vy: 0 }
+    ];
+    if event.tick % 54 == 0 {
+        commands.push(#{ op: "projectile", weapon: "iron_coast_boss:projectile", x: event.x + 35, y: 64, vx: -2, vy: 4, hostile: true });
+        commands.push(#{ op: "projectile", weapon: "iron_coast_boss:projectile", x: event.x + 48, y: 64, vx: 0, vy: 4, hostile: true });
+        commands.push(#{ op: "projectile", weapon: "iron_coast_boss:projectile", x: event.x + 61, y: 64, vx: 2, vy: 4, hostile: true });
+        commands.push(#{ op: "play_sound", sound: "iron_coast_boss:shot" });
+        state.shots = if state.contains("shots") { state.shots + 1 } else { 1 };
+    }
+    #{ commands: commands, state: state }
+}
+
+fn on_hit(event, state, random) {
+    state.hits = if state.contains("hits") { state.hits + 1 } else { 1 };
+    #{ commands: [], state: state }
+}
+
+fn on_death(event, state, random) {
+    if state.contains("directions") { state.directions.remove(event.entity.to_string()); }
+    state.destroyed = if state.contains("destroyed") { state.destroyed + 1 } else { 1 };
+    let defeated = if event.objectives.contains("iron_coast_boss:defeated") { event.objectives["iron_coast_boss:defeated"] + 1 } else { 1 };
+    #{ commands: [
+        #{ op: "objective", key: "iron_coast_boss:defeated", value: defeated },
+        #{ op: "effect", x: event.x + 35, y: event.y + 36 },
+        #{ op: "effect", x: event.x + 61, y: event.y + 36 },
+        #{ op: "play_sound", sound: "iron_coast_boss:death" }
+    ], state: state }
+}

examples/mods/iron_coast_mission_1/README.md

@@ -0,0 +1,29 @@
+# Iron Coast — Mission 1: Breakwater
+
+Enable this package and its six dependencies in the in-game Mods screen:
+`iron_coast_scout`, `iron_coast_turret`, `iron_coast_boss`, `pulse_cannon`,
+`seeker_swarm`, and `ion_lance`. Each package is independent and version 1.0.0.
+Choose **Iron Coast 1 — Breakwater** in the mission list.
+
+Disable at least two harbor turrets and destroy the command ship to complete
+the raid. Scout waves arrive during the approach; two supply depots release
+repair kits. The mission grants a trial Pulse Cannon and three field repairs.
+Repairs restore 25 shield when selected and used with the special button.
+Victory awards 5,000 credits in addition to ordinary destruction rewards.
+
+This mission uses explicit script completion. Its duration is a catalog hint;
+waiting out the timer cannot win. The boss stays in the firing corridor, and
+the two central turrets can be hit with starter forward guns. Equipment and
+mission progress remain subject to the normal mod-save compatibility checks.
+
+The generated masters, packaged SD/HD PNGs and synthesized WAVs are included
+in Git with their definitions, scripts, generator, prompts and validation
+report. Original game data and the original style-reference PNGs remain
+outside Git. The three
+`art/*-source-hd.png` inputs were generated with the built-in imagegen tool
+using the original terrain and military sprite as style/scale references.
+Run `python3 examples/mods/iron_coast_mission_1/build_assets.py --palette
+data/misc/PALETTE_DAT` to regenerate the exact
+packaged crops, SD palette conversion, HD footprints and synthesized WAVs.
+See `prompts.md`, `asset-report.json`, and `docs/iron-coast.md` for provenance
+and validation limits.