diff --git a/README.md b/README.md
new file mode 100644
index 0000000..eabe825
--- /dev/null
+++ b/README.md
@@ -0,0 +1,42 @@
+# airship-phaser
+
+Top-down Phaser.js airship combat prototype.
+
+## Development
+
+```bash
+npm install
+npm test
+npm run dev
+```
+
+Production builds run the regression suite before Vite:
+
+```bash
+npm run build
+```
+
+## Runtime diagnostics
+
+The browser keeps the latest 300 structured events in memory.
+
+In Chrome DevTools:
+
+```js
+airshipDebug.getLogs()
+airshipDebug.snapshot()
+airshipDebug.clearLogs()
+```
+
+Useful events include:
+
+- `scene:init`, `scene:create`, `scene:heartbeat`, `scene:shutdown`
+- `combat:broadside-fired`
+- `combat:player-hit-queued`
+- `combat:player-hit-processed`
+- `combat:pirate-hit`
+- `game:finish`
+- `hud:image-error`, `hud:helm-frame-error`, `hud:helm-knob-error`
+- `runtime:error`, `runtime:unhandled-rejection`
+
+If gameplay appears frozen, inspect `airshipDebug.snapshot()` first, then the tail of `airshipDebug.getLogs()`.
diff --git a/index.html b/index.html
new file mode 100644
index 0000000..8002bca
--- /dev/null
+++ b/index.html
@@ -0,0 +1,234 @@
+
+
+
+
+
+
+ Arrowstack Airship
+
+
+
+
+
+
+
+
+
+
+
+
+
+ HELM
+ `);
+ hud.appendChild(radarPiece);
+
+ addPiece('steam-cannon-port', cannonRoundelSrc, `
+ PORT
+
+ `);
+
+ addPiece('steam-cannon-starboard', cannonRoundelSrc, `
+ STBD
+
+ `);
+
+ const status = document.createElement('div');
+ status.className = 'steam-status';
+ status.dataset.steam = 'status';
+ hud.appendChild(status);
+
+ const fields = Object.fromEntries(
+ [...hud.querySelectorAll('[data-steam]')].map((el) => [el.dataset.steam, el]),
+ );
+
+ const radarContacts = radarPiece.querySelector('#steam-radar-contacts');
+
+ const setHelmKnob = (x = 0, y = 0) => {
+ const maxOffset = Math.min(radarPiece.clientWidth * 0.16, 24);
+ const px = Math.max(-1, Math.min(1, x)) * maxOffset;
+ const py = Math.max(-1, Math.min(1, y)) * maxOffset;
+ helmKnob.style.transform = `translate(-50%, -50%) translate(${px}px, ${py}px)`;
+ };
+
+ window.addEventListener('airship:helm-vector', (event) => {
+ setHelmKnob(event.detail?.x ?? 0, event.detail?.y ?? 0);
+ });
+
+ window.addEventListener('blur', () => setHelmKnob(0, 0));
+ const radarDots = Array.from({ length: 10 }, () => {
+ const dot = document.createElement('span');
+ dot.className = 'steam-radar-dot';
+ dot.hidden = true;
+ radarContacts.appendChild(dot);
+ return dot;
+ });
+
+ const clamp01 = (value) => Math.max(0, Math.min(1, value));
+
+ const healthFrame = (current, max) => {
+ const pct = max > 0 ? clamp01(current / max) : 0;
+ return Math.max(0, Math.min(11, Math.round((1 - pct) * 11)));
+ };
+
+ const setHealthFrame = (piece, frame) => {
+ const col = frame % 4;
+ const row = Math.floor(frame / 4);
+ const art = piece.querySelector('.steam-health-art');
+ if (!art) return;
+ art.style.backgroundPosition = `${(col / 3) * 100}% ${(row / 2) * 100}%`;
+ };
+
+ const updateRadar = (contacts = []) => {
+ radarDots.forEach((dot, index) => {
+ const contact = contacts[index];
+ if (!contact) {
+ dot.hidden = true;
+ return;
+ }
+
+ let dx = Number(contact.dx) || 0;
+ let dy = Number(contact.dy) || 0;
+ const distance = Math.hypot(dx, dy);
+ if (distance > 1) {
+ dx /= distance;
+ dy /= distance;
+ }
+
+ dot.style.left = `${50 + dx * 36}%`;
+ dot.style.top = `${50 + dy * 36}%`;
+ dot.hidden = false;
+ });
+ };
+
+ let lastPlayerHitSequence = 0;
+
+ const pulsePlayerHit = (sequence) => {
+ if (!Number.isFinite(sequence) || sequence <= lastPlayerHitSequence) return;
+ lastPlayerHitSequence = sequence;
+ playerHealthPiece.classList.remove('steam-hit');
+ void playerHealthPiece.offsetWidth;
+ playerHealthPiece.classList.add('steam-hit');
+ };
+
+ const renderHudState = (state) => {
+ if (!state?.player) return;
+
+ const playerHull = Math.max(0, state.player.hull ?? 100);
+ const playerMaxHull = Math.max(1, state.player.maxHull ?? 100);
+ const target = state.target || null;
+
+ fields.speed.textContent = `${Math.abs(state.speed || 0).toFixed(0)}${state.speed < 0 ? 'R' : ''}`;
+ fields.heading.textContent = `${(state.heading || 0).toFixed(0).padStart(3, '0')}°`;
+ fields.wave.textContent = String(state.wave || 1);
+ fields.hostiles.textContent = String(state.hostiles || 0);
+ fields.kills.textContent = String(state.kills || 0);
+ fields.range.textContent = target && Number.isFinite(target.range) ? `${Math.round(target.range)}m` : '--';
+ fields['player-hull'].textContent = `${playerHull}/${playerMaxHull}`;
+ fields['enemy-name'].textContent = target?.name || 'PIRATE';
+ fields['enemy-hull'].textContent = target ? `${Math.max(0, target.hull || 0)}/${Math.max(1, target.maxHull || 120)}` : 'CLEAR';
+
+ setHealthFrame(
+ playerHealthPiece,
+ healthFrame(playerHull, playerMaxHull),
+ );
+ setHealthFrame(
+ enemyHealthPiece,
+ target ? healthFrame(target.hull || 0, target.maxHull || 120) : 11,
+ );
+
+ fields['port-reload'].style.transform = `scaleX(${clamp01(state.reload?.port ?? 1)})`;
+ fields['starboard-reload'].style.transform = `scaleX(${clamp01(state.reload?.starboard ?? 1)})`;
+
+ const statusText = String(state.status || '').trim();
+ fields.status.textContent = statusText;
+ fields.status.classList.toggle('visible', Boolean(statusText));
+
+ pulsePlayerHit(state.player.hitSequence ?? 0);
+ updateRadar(state.radar || []);
+ };
+
+ window.addEventListener('airship:hud-state', (event) => {
+ renderHudState(event.detail);
+ });
+
+ airshipLog('hud:mounted', {
+ mobile: true,
+ pieces: hud.querySelectorAll('.steam-piece').length,
+ });
+
+ }
+}
diff --git a/src/pirate-ai.js b/src/pirate-ai.js
new file mode 100644
index 0000000..36a70ae
--- /dev/null
+++ b/src/pirate-ai.js
@@ -0,0 +1,159 @@
+export const PIRATE_CLASSES = {
+ raider: {
+ key: 'raider',
+ label: 'RAIDER',
+ hull: 80,
+ speed: 148,
+ turnRate: 70,
+ reloadMs: 1280,
+ projectileDamage: 4,
+ preferredRange: 300,
+ retreatRange: 175,
+ broadsideRange: 380,
+ broadsideError: 34,
+ displaySize: 70,
+ },
+ frigate: {
+ key: 'frigate',
+ label: 'FRIGATE',
+ hull: 120,
+ speed: 118,
+ turnRate: 52,
+ reloadMs: 1650,
+ projectileDamage: 6,
+ preferredRange: 335,
+ retreatRange: 210,
+ broadsideRange: 420,
+ broadsideError: 38,
+ displaySize: 78,
+ },
+ captain: {
+ key: 'captain',
+ label: 'CAPTAIN',
+ hull: 180,
+ speed: 102,
+ turnRate: 44,
+ reloadMs: 1450,
+ projectileDamage: 8,
+ preferredRange: 365,
+ retreatRange: 225,
+ broadsideRange: 470,
+ broadsideError: 32,
+ displaySize: 88,
+ },
+};
+
+export const PIRATE_CLASS_COSTS = {
+ raider: 1,
+ frigate: 2,
+ captain: 3,
+};
+
+const normalizeDegrees = (deg) => ((deg % 360) + 360) % 360;
+
+const signedAngleDelta = (target, current) => {
+ let delta = normalizeDegrees(target) - normalizeDegrees(current);
+ if (delta > 180) delta -= 360;
+ if (delta < -180) delta += 360;
+ return delta;
+};
+
+export const waveDifficultyBudget = (wave) => {
+ const safeWave = Math.max(1, Math.floor(Number(wave) || 1));
+ return safeWave + 1 + Math.floor((safeWave - 1) / 2);
+};
+
+export const pirateRosterForWave = (wave, maxPirates = 6) => {
+ const safeWave = Math.max(1, Math.floor(Number(wave) || 1));
+ const safeMaxPirates = Math.max(1, Math.floor(Number(maxPirates) || 1));
+ const count = Math.min(safeWave, safeMaxPirates);
+ let remainingBudget = Math.max(count, waveDifficultyBudget(safeWave));
+ let captainSlots = safeWave >= 4 ? Math.max(1, Math.floor(safeWave / 4)) : 0;
+ const roster = [];
+
+ for (let index = 0; index < count; index += 1) {
+ const remainingSlots = count - index - 1;
+ const minimumRemainingCost = remainingSlots * PIRATE_CLASS_COSTS.raider;
+
+ if (
+ captainSlots > 0
+ && remainingBudget - PIRATE_CLASS_COSTS.captain >= minimumRemainingCost
+ ) {
+ roster.push(PIRATE_CLASSES.captain);
+ remainingBudget -= PIRATE_CLASS_COSTS.captain;
+ captainSlots -= 1;
+ continue;
+ }
+
+ if (remainingBudget - PIRATE_CLASS_COSTS.frigate >= minimumRemainingCost) {
+ roster.push(PIRATE_CLASSES.frigate);
+ remainingBudget -= PIRATE_CLASS_COSTS.frigate;
+ continue;
+ }
+
+ roster.push(PIRATE_CLASSES.raider);
+ remainingBudget -= PIRATE_CLASS_COSTS.raider;
+ }
+
+ return roster;
+};
+
+export const pirateDesiredHeading = ({
+ bearing,
+ currentHeading,
+ distance,
+ preferredRange,
+ retreatRange,
+}) => {
+ if (distance < retreatRange) {
+ return normalizeDegrees(bearing + 180);
+ }
+
+ if (distance < preferredRange + 40) {
+ const optionA = normalizeDegrees(bearing + 90);
+ const optionB = normalizeDegrees(bearing - 90);
+ return Math.abs(signedAngleDelta(optionA, currentHeading))
+ < Math.abs(signedAngleDelta(optionB, currentHeading))
+ ? optionA
+ : optionB;
+ }
+
+ return normalizeDegrees(bearing);
+};
+
+export const pirateSpeedForRange = ({
+ distance,
+ preferredRange,
+ retreatRange,
+ baseSpeed,
+}) => {
+ if (distance < retreatRange) return baseSpeed * 0.9;
+ if (distance > preferredRange + 100) return baseSpeed;
+ return baseSpeed * 0.82;
+};
+
+export const separationVector = (ship, ships, radius = 125) => {
+ let x = 0;
+ let y = 0;
+
+ for (const other of ships) {
+ if (!other || other === ship || !other.active) continue;
+
+ const dx = other.x - ship.x;
+ const dy = other.y - ship.y;
+ const distance = Math.hypot(dx, dy);
+ if (distance <= 0 || distance >= radius) continue;
+
+ const strength = (radius - distance) / radius;
+ x -= (dx / distance) * strength;
+ y -= (dy / distance) * strength;
+ }
+
+ const magnitude = Math.hypot(x, y);
+ if (magnitude > 1) {
+ x /= magnitude;
+ y /= magnitude;
+ }
+
+ return { x, y };
+};
diff --git a/src/progression/modules.js b/src/progression/modules.js
new file mode 100644
index 0000000..6cc6780
--- /dev/null
+++ b/src/progression/modules.js
@@ -0,0 +1,125 @@
+export const SHIP_BASE_STATS = {
+ maxHull: 100,
+ maxSpeed: 180,
+ reverseSpeed: -55,
+ acceleration: 92,
+ brake: 118,
+ turnRate: 76,
+ reloadMs: 850,
+ cannonDamage: 16,
+ windExposure: 1,
+ cargoCapacity: 4,
+ salvageCapacity: 2,
+ radarRange: 900,
+};
+
+export const MODULE_CATALOG = {
+ 'stock-engine': {
+ id: 'stock-engine',
+ name: 'Stock Twin Propellers',
+ slot: 'engine',
+ rarity: 'common',
+ price: 0,
+ modifiers: {},
+ },
+ 'tuned-propellers': {
+ id: 'tuned-propellers',
+ name: 'Tuned Propellers',
+ slot: 'engine',
+ rarity: 'improved',
+ price: 280,
+ modifiers: { maxSpeed: 20, acceleration: 10 },
+ },
+ 'corsair-overdrive': {
+ id: 'corsair-overdrive',
+ name: 'Corsair Overdrive',
+ slot: 'engine',
+ rarity: 'rare',
+ price: 690,
+ modifiers: { maxSpeed: 34, acceleration: 18, turnRate: -5 },
+ },
+ 'standard-broadside': {
+ id: 'standard-broadside',
+ name: 'Standard Broadside',
+ slot: 'weapon',
+ rarity: 'common',
+ price: 0,
+ modifiers: {},
+ },
+ 'long-nine-cannons': {
+ id: 'long-nine-cannons',
+ name: 'Long Nine Cannons',
+ slot: 'weapon',
+ rarity: 'improved',
+ price: 360,
+ modifiers: { cannonDamage: 4, reloadMs: 70 },
+ },
+ 'quicklock-breeches': {
+ id: 'quicklock-breeches',
+ name: 'Quicklock Breeches',
+ slot: 'weapon',
+ rarity: 'rare',
+ price: 620,
+ modifiers: { cannonDamage: 2, reloadMs: -180 },
+ },
+ 'timber-hull': {
+ id: 'timber-hull',
+ name: 'Timber Hull',
+ slot: 'hull',
+ rarity: 'common',
+ price: 0,
+ modifiers: {},
+ },
+ 'reinforced-keel': {
+ id: 'reinforced-keel',
+ name: 'Reinforced Keel',
+ slot: 'hull',
+ rarity: 'improved',
+ price: 420,
+ modifiers: { maxHull: 28, maxSpeed: -7 },
+ },
+ 'stormglass-nav': {
+ id: 'stormglass-nav',
+ name: 'Stormglass Navigator',
+ slot: 'navigation',
+ rarity: 'rare',
+ price: 560,
+ modifiers: { windExposure: -0.22, radarRange: 240 },
+ },
+ 'brass-compass': {
+ id: 'brass-compass',
+ name: 'Brass Compass',
+ slot: 'navigation',
+ rarity: 'common',
+ price: 0,
+ modifiers: {},
+ },
+ 'salvage-rig': {
+ id: 'salvage-rig',
+ name: 'Deck Salvage Rig',
+ slot: 'utility',
+ rarity: 'improved',
+ price: 330,
+ modifiers: { salvageCapacity: 2 },
+ },
+ 'expanded-hold': {
+ id: 'expanded-hold',
+ name: 'Expanded Cargo Hold',
+ slot: 'cargo',
+ rarity: 'improved',
+ price: 350,
+ modifiers: { cargoCapacity: 4, maxSpeed: -4 },
+ },
+};
+
+export const STARTER_LOADOUT = {
+ engine: 'stock-engine',
+ weapon: 'standard-broadside',
+ hull: 'timber-hull',
+ navigation: 'brass-compass',
+ utility: null,
+ cargo: null,
+};
+
+export const purchasableModules = () => Object.values(MODULE_CATALOG)
+ .filter((module) => module.price > 0);
diff --git a/src/progression/ship-loadout.js b/src/progression/ship-loadout.js
new file mode 100644
index 0000000..43c3652
--- /dev/null
+++ b/src/progression/ship-loadout.js
@@ -0,0 +1,153 @@
+import {
+ MODULE_CATALOG,
+ SHIP_BASE_STATS,
+ STARTER_LOADOUT,
+ purchasableModules,
+} from './modules.js';
+import { createSeededRandom } from '../world/seeded-random.js';
+
+const clamp = (value, min, max) => Math.max(min, Math.min(max, value));
+
+export const createStarterProgression = () => ({
+ credits: 650,
+ scrap: 0,
+ loadout: { ...STARTER_LOADOUT },
+ inventory: [],
+});
+
+export const deriveShipStats = (loadout = STARTER_LOADOUT) => {
+ const stats = { ...SHIP_BASE_STATS };
+
+ for (const moduleId of Object.values(loadout)) {
+ if (!moduleId) continue;
+ const module = MODULE_CATALOG[moduleId];
+ if (!module) continue;
+ for (const [key, value] of Object.entries(module.modifiers || {})) {
+ stats[key] = (stats[key] ?? 0) + value;
+ }
+ }
+
+ stats.maxHull = Math.max(1, stats.maxHull);
+ stats.maxSpeed = Math.max(40, stats.maxSpeed);
+ stats.acceleration = Math.max(10, stats.acceleration);
+ stats.turnRate = Math.max(15, stats.turnRate);
+ stats.reloadMs = Math.max(260, stats.reloadMs);
+ stats.cannonDamage = Math.max(1, stats.cannonDamage);
+ stats.windExposure = clamp(stats.windExposure, 0.35, 1.5);
+ stats.cargoCapacity = Math.max(1, Math.floor(stats.cargoCapacity));
+ stats.salvageCapacity = Math.max(1, Math.floor(stats.salvageCapacity));
+ return stats;
+};
+
+export const installModule = (progression, moduleId) => {
+ const module = MODULE_CATALOG[moduleId];
+ if (!module) return { ...progression, installed: false, reason: 'unknown-module' };
+
+ const inventory = [...(progression.inventory || [])];
+ const inventoryIndex = inventory.indexOf(moduleId);
+ if (inventoryIndex >= 0) inventory.splice(inventoryIndex, 1);
+
+ const loadout = { ...(progression.loadout || STARTER_LOADOUT) };
+ const replaced = loadout[module.slot] || null;
+ loadout[module.slot] = moduleId;
+ if (replaced && MODULE_CATALOG[replaced]?.price > 0) inventory.push(replaced);
+
+ return {
+ ...progression,
+ loadout,
+ inventory,
+ installed: true,
+ replaced,
+ installedModule: moduleId,
+ };
+};
+
+export const buyAndInstallModule = (progression, moduleId) => {
+ const module = MODULE_CATALOG[moduleId];
+ if (!module || module.price <= 0) return { ...progression, purchased: false, reason: 'not-for-sale' };
+ if ((progression.credits || 0) < module.price) {
+ return { ...progression, purchased: false, reason: 'insufficient-credits' };
+ }
+
+ const purchased = {
+ ...progression,
+ credits: progression.credits - module.price,
+ inventory: [...(progression.inventory || []), moduleId],
+ };
+ return { ...installModule(purchased, moduleId), purchased: true };
+};
+
+export const marketForPort = (port) => {
+ const stock = purchasableModules().filter((module) => {
+ if (port?.type === 'industrial') return ['engine', 'hull', 'utility', 'cargo'].includes(module.slot);
+ if (port?.type === 'military') return ['weapon', 'hull', 'navigation'].includes(module.slot);
+ if (port?.type === 'fuel') return ['engine', 'navigation', 'cargo'].includes(module.slot);
+ return true;
+ });
+
+ return stock.sort((a, b) => a.price - b.price);
+};
+
+export const salvageForPirate = ({
+ seed = 'salvage',
+ classKey = 'raider',
+ wave = 1,
+ sequence = 0,
+} = {}) => {
+ const random = createSeededRandom(`${seed}:${classKey}:${wave}:${sequence}`);
+ const chance = classKey === 'captain' ? 0.86 : classKey === 'frigate' ? 0.62 : 0.42;
+ const modulePool = purchasableModules();
+ const module = random() < chance
+ ? modulePool[Math.floor(random() * modulePool.length)]
+ : null;
+ const scrap = 1 + Math.floor(random() * (classKey === 'captain' ? 8 : classKey === 'frigate' ? 5 : 3));
+ const credits = 20 + Math.floor(random() * (35 + wave * 8));
+
+ return {
+ moduleId: module?.id || null,
+ scrap,
+ credits,
+ condition: module ? clamp(0.28 + random() * 0.67, 0.28, 0.95) : null,
+ };
+};
+
+export const collectSalvage = (progression, salvage, stats = deriveShipStats(progression.loadout)) => {
+ const inventory = [...(progression.inventory || [])];
+ let moduleCollected = false;
+
+ if (salvage?.moduleId && inventory.length < stats.salvageCapacity) {
+ inventory.push(salvage.moduleId);
+ moduleCollected = true;
+ }
+
+ return {
+ ...progression,
+ inventory,
+ scrap: (progression.scrap || 0) + Math.max(0, salvage?.scrap || 0),
+ credits: (progression.credits || 0) + Math.max(0, salvage?.credits || 0),
+ lastSalvage: { ...salvage, moduleCollected },
+ };
+};
+
+export const bestAffordableMarketUpgrade = (progression, port) => {
+ const stats = deriveShipStats(progression.loadout);
+ const candidates = marketForPort(port)
+ .filter((module) => module.price <= (progression.credits || 0))
+ .filter((module) => progression.loadout?.[module.slot] !== module.id)
+ .map((module) => {
+ const next = deriveShipStats({ ...progression.loadout, [module.slot]: module.id });
+ const score = (next.maxHull - stats.maxHull) * 0.7
+ + (next.maxSpeed - stats.maxSpeed)
+ + (next.acceleration - stats.acceleration) * 0.45
+ + (next.turnRate - stats.turnRate) * 0.35
+ + (stats.reloadMs - next.reloadMs) * 0.06
+ + (next.cannonDamage - stats.cannonDamage) * 5
+ + (stats.windExposure - next.windExposure) * 30
+ + (next.salvageCapacity - stats.salvageCapacity) * 8
+ + (next.cargoCapacity - stats.cargoCapacity) * 4;
+ return { module, score };
+ })
+ .sort((a, b) => b.score - a.score);
+
+ return candidates[0]?.module || null;
+};
diff --git a/src/style.css b/src/style.css
new file mode 100644
index 0000000..d829460
--- /dev/null
+++ b/src/style.css
@@ -0,0 +1,15 @@
+html, body, #app, #game {
+ margin: 0;
+ width: 100%;
+ height: 100%;
+ overflow: hidden;
+ background: #0f1720;
+}
+
+body {
+ font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+canvas {
+ display: block;
+}
diff --git a/src/world/seeded-random.js b/src/world/seeded-random.js
new file mode 100644
index 0000000..6a0cd4a
--- /dev/null
+++ b/src/world/seeded-random.js
@@ -0,0 +1,22 @@
+export const hashSeed = (seed = '') => {
+ let hash = 2166136261;
+ for (const char of String(seed)) {
+ hash ^= char.charCodeAt(0);
+ hash = Math.imul(hash, 16777619);
+ }
+ return hash >>> 0;
+};
+
+export const createSeededRandom = (seed = '') => {
+ let state = hashSeed(seed) || 0x6d2b79f5;
+ return () => {
+ state += 0x6d2b79f5;
+ let value = state;
+ value = Math.imul(value ^ (value >>> 15), value | 1);
+ value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+ return ((value ^ (value >>> 14)) >>> 0) / 4294967296;
+ };
+};
+
+export const randomBetween = (random, min, max) => min + (max - min) * random();
+export const randomInt = (random, min, max) => Math.floor(randomBetween(random, min, max + 1));