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

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 }
+}