npm - create-vimp-game - Versions diffs - 0.1.0 - Mend

create-vimp-game 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (72) hide show

package/bin/create-vimp-game.js +15 -0
package/package.json +40 -0
package/src/cli.js +227 -0
package/src/generator.js +196 -0
package/src/preflight.js +48 -0
package/src/prompts.js +79 -0
package/src/tokens.js +99 -0
package/src/ui.js +66 -0
package/src/versions.generated.json +4 -0
package/src/versions.js +87 -0
package/templates/default/CLAUDE.md.tpl +51 -0
package/templates/default/Cargo.toml.tpl +27 -0
package/templates/default/LICENSE.tpl +21 -0
package/templates/default/README.md.tpl +61 -0
package/templates/default/_gitignore +8 -0
package/templates/default/assets/audio-raw/death.wav +0 -0
package/templates/default/assets/audio-raw/shot.wav +0 -0
package/templates/default/assets/sounds/death.mp3 +0 -0
package/templates/default/assets/sounds/death.webm +0 -0
package/templates/default/assets/sounds/shot.mp3 +0 -0
package/templates/default/assets/sounds/shot.webm +0 -0
package/templates/default/core/Cargo.toml.tpl +19 -0
package/templates/default/core/src/actor.rs +407 -0
package/templates/default/core/src/body_tag.rs +56 -0
package/templates/default/core/src/client/mod.rs +385 -0
package/templates/default/core/src/client/predictor.rs +552 -0
package/templates/default/core/src/config.rs +236 -0
package/templates/default/core/src/game.rs +692 -0
package/templates/default/core/src/lib.rs +118 -0
package/templates/default/core/src/motion.rs +126 -0
package/templates/default/core/tests/sim.rs +351 -0
package/templates/default/dev/main.js +28 -0
package/templates/default/eslint.config.js +84 -0
package/templates/default/index.html.tpl +35 -0
package/templates/default/package.json.tpl +48 -0
package/templates/default/scripts/build-game-manifest.js +188 -0
package/templates/default/scripts/copy-game-images.js +35 -0
package/templates/default/scripts/copy-game-sounds.js +55 -0
package/templates/default/scripts/export-maps.js +19 -0
package/templates/default/scripts/lib/rangeToPattern.js +74 -0
package/templates/default/scripts/process-audio.js +115 -0
package/templates/default/src/client/bakers/actorTexture.js +40 -0
package/templates/default/src/client/bakers/index.js +8 -0
package/templates/default/src/client/index.js +67 -0
package/templates/default/src/client/parts/Actor.js +69 -0
package/templates/default/src/client/parts/Map.js +74 -0
package/templates/default/src/client/parts/ShotEffect.js +107 -0
package/templates/default/src/client/parts/index.js +13 -0
package/templates/default/src/client/style.css +26 -0
package/templates/default/src/config/auth.js +61 -0
package/templates/default/src/config/client.js +195 -0
package/templates/default/src/config/game.js +170 -0
package/templates/default/src/config/snapshot.js +70 -0
package/templates/default/src/config/sounds.js +17 -0
package/templates/default/src/data/maps/arena.js +69 -0
package/templates/default/src/data/maps/index.js +7 -0
package/templates/default/src/data/models.js +39 -0
package/templates/default/src/data/weapons.js +37 -0
package/templates/default/src/host/ScriptedManager.js +142 -0
package/templates/default/src/host/createModules.js +12 -0
package/templates/default/src/host/index.js +56 -0
package/templates/default/src/host/nodeCore.js +23 -0
package/templates/default/src/host/spawnCommand.js +32 -0
package/templates/default/src/host/systemMessages.js +10 -0
package/templates/default/tests/client/parts.test.js +128 -0
package/templates/default/tests/config/contract.test.js +132 -0
package/templates/default/tests/config/game.test.js +45 -0
package/templates/default/tests/core/nodeCore.test.js +61 -0
package/templates/default/tests/host/hostPlugin.test.js +198 -0
package/templates/default/tests/stubs/wasmCore.js +19 -0
package/templates/default/vite.config.js +74 -0
package/templates/default/vitest.config.js +55 -0

package/templates/default/eslint.config.js ADDED Viewed

@@ -0,0 +1,84 @@
+import js from '@eslint/js';
+import globals from 'globals';
+// Minimal config: the split that matters is by environment. src/host/ runs
+// inside a Web Worker (no DOM, no PixiJS) and src/client/ in the main thread;
+// mixing their globals hides the mistake the engine cannot catch for you.
+export default [
+  js.configs.recommended,
+  // build scripts and root configs
+  {
+    files: ['*.js', 'scripts/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: { ...globals.es2023, ...globals.node },
+    },
+  },
+  // host half: Worker-safe — no browser globals on purpose
+  {
+    files: ['src/host/**/*.js', 'src/config/**/*.js', 'src/data/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: { ...globals.es2023, ...globals.worker },
+    },
+  },
+  // client half and the dev harness: main thread
+  {
+    files: ['src/client/**/*.js', 'dev/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: { ...globals.es2023, ...globals.browser },
+    },
+  },
+  {
+    files: ['tests/**/*.js'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      sourceType: 'module',
+      globals: {
+        ...globals.es2023,
+        ...globals.node,
+        ...globals.browser,
+        // vitest globals: true
+        describe: 'readonly',
+        it: 'readonly',
+        expect: 'readonly',
+        vi: 'readonly',
+        beforeEach: 'readonly',
+        afterEach: 'readonly',
+        beforeAll: 'readonly',
+        afterAll: 'readonly',
+      },
+    },
+  },
+  {
+    rules: {
+      eqeqeq: ['error', 'always'],
+      curly: ['error', 'all'],
+      'no-var': 'error',
+      'prefer-const': 'warn',
+      'no-unused-vars': ['warn', { argsIgnorePattern: '^_' }],
+    },
+  },
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      'build/**',
+      'target/**',
+      'core/pkg-web/**',
+      'core/pkg-node/**',
+      '**/.*',
+      '**/_*',
+    ],
+  },
+];

package/templates/default/index.html.tpl ADDED Viewed

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>{{GAME_TITLE}} — dev</title>
+    <!--
+      No engine stylesheet here: the entry point imports it (and the game CSS),
+      Vite bundles them. Below are only the rules of the SDK container itself.
+      #game must be full-screen and positioned: both the interface frame and
+      the canvases mount into it, and the engine's #panel/#stat/#vote are
+      position: absolute — their containing block is the nearest positioned
+      ancestor.
+    -->
+    <style>
+      html,
+      body {
+        margin: 0;
+        height: 100%;
+      }
+      #game {
+        position: relative;
+        width: 100%;
+        height: 100%;
+        overflow: hidden;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="game"></div>
+    <script type="module" src="/dev/main.js"></script>
+  </body>
+</html>

package/templates/default/package.json.tpl ADDED Viewed

@@ -0,0 +1,48 @@
+{
+  "name": "{{PACKAGE_NAME}}",
+  "version": "0.1.0",
+  "description": "{{GAME_TITLE}} — a VIMP game plugin",
+  "author": "{{AUTHOR}}",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20.11.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && npm run build:client && npm run build:host && npm run build:assets && npm run build:manifest",
+    "build:client": "vite build --mode client",
+    "build:host": "vite build --mode host",
+    "build:assets": "node ./scripts/export-maps.js && node ./scripts/copy-game-sounds.js && node ./scripts/copy-game-images.js",
+    "build:manifest": "node ./scripts/build-game-manifest.js",
+    "audio:process": "node ./scripts/process-audio.js",
+    "core:build": "npm run core:build:web && npm run core:build:node",
+    "core:build:web": "wasm-pack build core --release --target web --out-dir pkg-web",
+    "core:build:node": "wasm-pack build core --release --target nodejs --out-dir pkg-node",
+    "core:test": "cargo test --workspace",
+    "check:contract": "vimp-contract --game .",
+    "sim": "vimp-sim --game .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "predev": "node ./scripts/copy-game-images.js && node ./scripts/copy-game-sounds.js",
+    "dev": "vite"
+  },
+  "peerDependencies": {
+    "pixi.js": "^8.14.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.37.0",
+    "eslint": "^9.37.0",
+    "globals": "^16.2.0",
+    "happy-dom": "^20.10.6",
+    "pixi.js": "^8.14.0",
+    "vimp-engine": "{{ENGINE_VERSION}}",
+    "vite": "^7.1.11",
+    "vitest": "^4.1.9"
+  }
+}

package/templates/default/scripts/build-game-manifest.js ADDED Viewed

@@ -0,0 +1,188 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { createHash } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { ENGINE_API_VERSION } from 'vimp-engine/config/opcodes.js';
+import hostDefaults from 'vimp-engine/config/hostDefaults.js';
+import gameConfig from '../src/config/game.js';
+import { rangeToPattern } from './lib/rangeToPattern.js';
+// Writes dist/manifest.json — the only thing the master reads about a built
+// game (docs/ai/02-packaging.md). Runs last, after both Vite bundles and the
+// asset steps: it hashes what they produced.
+// Run: node scripts/build-game-manifest.js (build:manifest)
+const distPath = fileURLToPath(new URL('../dist/', import.meta.url));
+const assetsPath = path.join(distPath, 'assets');
+const mapsPath = path.join(distPath, 'maps');
+// The nodejs build of the same core, for the engine's headless runner
+// (`npm run sim`). Unlike the other entries it is a filesystem path relative
+// to the manifest, and it must point INSIDE dist/ — dist/ is the only
+// published content, so pkg-node is copied here rather than referenced in
+// place (../core/pkg-node/ works in the checkout and breaks once installed).
+const NODE_CORE_SRC = fileURLToPath(new URL('../core/pkg-node/', import.meta.url));
+const NODE_CORE_DIR = 'core-node';
+const NODE_CORE_ENTRY = `./${NODE_CORE_DIR}/{{CRATE_SNAKE}}.js`;
+function hashFile(filePath) {
+  return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
+}
+function findOne(dir, pattern) {
+  const files = fs.readdirSync(dir).filter(name => pattern.test(name));
+  if (files.length !== 1) {
+    throw new Error(
+      `expected exactly one file matching ${pattern} in ${dir}, found: ` +
+        `${files.join(', ') || 'none'}`,
+    );
+  }
+  return files[0];
+}
+const clientFile = findOne(distPath, /^client-.+\.js$/);
+const hostFile = findOne(distPath, /^host-.+\.js$/);
+const wasmFile = findOne(assetsPath, /\.wasm$/);
+// clients compare this to detect a stale bundle
+const version = createHash('sha256')
+  .update(hashFile(path.join(distPath, clientFile)))
+  .update(hashFile(path.join(distPath, hostFile)))
+  .update(hashFile(path.join(assetsPath, wasmFile)))
+  .digest('hex')
+  .slice(0, 16);
+const mapNames = fs
+  .readdirSync(mapsPath)
+  .filter(name => name.endsWith('.json'))
+  .map(name => name.slice(0, -'.json'.length))
+  .sort();
+const mapsHash = createHash('sha256');
+const maps = [];
+for (const name of mapNames) {
+  const raw = fs.readFileSync(path.join(mapsPath, `${name}.json`));
+  mapsHash.update(name).update(raw);
+  maps.push(JSON.parse(raw));
+}
+// A map may name images (spriteSheet.img, physicsDynamic[].img); the engine
+// serves none of them, and a missing file fails silently at runtime — an
+// empty canvas and a clean console. So it is a build gate. A procedural map
+// names nothing and the gate is a no-op.
+const requiredImages = [
+  ...new Set(
+    maps.flatMap(map => [
+      map?.spriteSheet?.img,
+      ...(map?.physicsDynamic ?? []).map(body => body?.img),
+    ]),
+  ),
+]
+  .filter(Boolean)
+  .sort();
+const missingImages = requiredImages.filter(
+  file => !fs.existsSync(path.join(distPath, 'img', file)),
+);
+if (missingImages.length) {
+  throw new Error(
+    `maps reference image(s) missing from dist/img/: ${missingImages.join(', ')} — ` +
+      'add them to assets/img/ and run `npm run build:assets`',
+  );
+}
+// one value per roomForm field; roomForm is the single source of the names,
+// which keeps roomDefaults from drifting away from the form
+const roomValues = {
+  maxPlayers: gameConfig.roomDefaults.maxPlayers,
+  roundTime: hostDefaults.timers.roundTime,
+  mapTime: hostDefaults.timers.mapTime,
+  friendlyFire: gameConfig.parts.friendlyFire,
+  map: gameConfig.currentMap,
+};
+// bounds of the numeric fields (v3 text controls know no min/max): the same
+// numbers the host clamps by, not an independent copy
+const { roomTimeMin, roomTimeMax } = hostDefaults.timers;
+const roomTimeRegExp = rangeToPattern(roomTimeMin / 1000, roomTimeMax / 1000);
+const fieldRegExp = {
+  maxPlayers: rangeToPattern(1, gameConfig.roomDefaults.maxPlayers),
+  roundTime: roomTimeRegExp,
+  mapTime: roomTimeRegExp,
+};
+const roomForm = gameConfig.roomForm.map(field =>
+  field.name in fieldRegExp
+    ? { ...field, regExp: fieldRegExp[field.name] }
+    : field,
+);
+const hasNodeCore = fs.existsSync(NODE_CORE_SRC);
+if (hasNodeCore) {
+  fs.rmSync(path.join(distPath, NODE_CORE_DIR), {
+    recursive: true,
+    force: true,
+  });
+  fs.cpSync(NODE_CORE_SRC, path.join(distPath, NODE_CORE_DIR), {
+    recursive: true,
+    // wasm-pack drops a `.gitignore` with `*` next to the glue, and npm
+    // applies ignore files inside dist/ too — with it the directory would
+    // never reach the tarball. package.json stays: without it Node reads the
+    // CommonJS glue as ESM (the package root is "type": "module").
+    filter: src => path.basename(src) !== '.gitignore',
+  });
+}
+const manifest = {
+  id: '{{GAME_ID}}',
+  engineApi: ENGINE_API_VERSION,
+  version,
+  title: '{{GAME_TITLE}}',
+  entries: {
+    client: `/games/{{GAME_ID}}/${clientFile}`,
+    host: `/games/{{GAME_ID}}/${hostFile}`,
+    wasm: `/games/{{GAME_ID}}/assets/${wasmFile}`,
+    ...(hasNodeCore ? { wasmNode: NODE_CORE_ENTRY } : {}),
+  },
+  assetsBase: '/games/{{GAME_ID}}/',
+  maps: {
+    version: mapsHash.digest('hex').slice(0, 16),
+    list: mapNames,
+  },
+  roomDefaults: Object.fromEntries(
+    roomForm.map(({ name }) => {
+      if (!(name in roomValues)) {
+        throw new Error(`roomForm field "${name}" has no value source`);
+      }
+      return [name, roomValues[name]];
+    }),
+  ),
+  roomForm,
+};
+fs.writeFileSync(
+  path.join(distPath, 'manifest.json'),
+  JSON.stringify(manifest, null, 2),
+);
+console.log(`manifest written: ${path.join(distPath, 'manifest.json')}`);
+console.log(`  version: ${version}`);
+console.log(`  maps: ${mapNames.join(', ')}`);
+if (hasNodeCore) {
+  console.log(`  wasmNode: ${NODE_CORE_ENTRY}`);
+} else {
+  console.warn(
+    `  wasmNode: skipped (no ${NODE_CORE_SRC}) — the headless run needs ` +
+      '`npm run core:build:node` or an explicit --core flag',
+  );
+}

package/templates/default/scripts/copy-game-images.js ADDED Viewed

@@ -0,0 +1,35 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// Lays the game images (map tile sheets, dynamic-body sprites) out for their
+// two consumers:
+//
+//   build/img/ — dev root of the standalone launch (`npm run dev`): the SDK
+//                gets assetsBase '/build/', so a tile lives at /build/img/<file>
+//   dist/img/  — the packaged asset under GameManifest.assetsBase: the master
+//                mounts dist/ at /games/<id>/
+//
+// Images need no processing step, so both targets are written in one pass.
+// A scaffolded game draws everything procedurally and ships no images at all,
+// so a missing assets/img/ is a no-op, not an error.
+// Run: node scripts/copy-game-images.js (build:assets and predev)
+const sourceDir = fileURLToPath(new URL('../assets/img/', import.meta.url));
+const targetDirs = [
+  fileURLToPath(new URL('../build/img/', import.meta.url)),
+  fileURLToPath(new URL('../dist/img/', import.meta.url)),
+];
+if (!fs.existsSync(sourceDir)) {
+  console.log(`no images: '${sourceDir}' does not exist — nothing to copy`);
+  process.exit(0);
+}
+for (const targetDir of targetDirs) {
+  // full replacement, not a merge: a file deleted from assets/img/ would
+  // otherwise survive in dist/ and travel into the published tarball
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  fs.cpSync(sourceDir, targetDir, { recursive: true });
+  console.log(`copied images: ${sourceDir} -> ${targetDir}`);
+}

package/templates/default/scripts/copy-game-sounds.js ADDED Viewed

@@ -0,0 +1,55 @@
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+// Copies the processed sounds into dist/sounds/ — the asset the client reads
+// as `${assetsBase}sounds/<file>.<codec>`.
+//
+// Source order matters:
+//   build/sounds/    — the product of `npm run audio:process` (ffmpeg);
+//   assets/sounds/   — placeholders shipped with the template.
+//
+// The fallback is deliberate: the first build of a freshly scaffolded game
+// must be green WITHOUT ffmpeg installed. Once you run `npm run audio:process`
+// on your own assets/audio-raw/, build/sounds/ wins and the placeholders stop
+// being used.
+// Run: node scripts/copy-game-sounds.js (build:assets)
+const processedDir = fileURLToPath(new URL('../build/sounds/', import.meta.url));
+const placeholderDir = fileURLToPath(
+  new URL('../assets/sounds/', import.meta.url),
+);
+const distDir = fileURLToPath(new URL('../dist/sounds/', import.meta.url));
+const sourceDir = fs.existsSync(processedDir) ? processedDir : placeholderDir;
+// dist/ is the packaged asset; build/sounds/ is also the dev asset root of
+// `npm run dev` (assetsBase '/build/'), so the placeholders are staged there
+// as well — otherwise a developer without ffmpeg plays a silent match
+const targetDirs =
+  sourceDir === placeholderDir
+    ? [distDir, fileURLToPath(new URL('../build/sounds/', import.meta.url))]
+    : [distDir];
+if (!fs.existsSync(sourceDir)) {
+  console.error(
+    `Error: no sounds found (looked in '${processedDir}' and ` +
+      `'${placeholderDir}'). Run 'npm run audio:process' first.`,
+  );
+  process.exit(1);
+}
+for (const targetDir of targetDirs) {
+  // full replacement, not a merge: a file deleted from the source would
+  // otherwise survive in dist/ and travel into the published tarball
+  fs.rmSync(targetDir, { recursive: true, force: true });
+  fs.cpSync(sourceDir, targetDir, { recursive: true });
+  console.log(`copied sounds: ${sourceDir} -> ${targetDir}`);
+}
+if (sourceDir === placeholderDir) {
+  console.warn(
+    '  using the template placeholders — run `npm run audio:process` to ' +
+      'build your own sounds from assets/audio-raw/',
+  );
+}

package/templates/default/scripts/export-maps.js ADDED Viewed

@@ -0,0 +1,19 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import maps from '../src/data/maps/index.js';
+// Serialises the maps from JS modules into static JSON: the format the Rust
+// core loads (load_map) and the master serves without rebuilding the halves
+// (GameManifest.maps -> /games/<id>/maps/<name>).
+// Run: node scripts/export-maps.js -> dist/maps/<name>.json
+const outDir = new URL('../dist/maps/', import.meta.url);
+await mkdir(outDir, { recursive: true });
+for (const [name, map] of Object.entries(maps)) {
+  // the URL constructor encodes spaces, fs decodes them back on write
+  const file = new URL(`${name}.json`, outDir);
+  await writeFile(file, JSON.stringify(map));
+  console.log(`exported: ${name}.json`);
+}

package/templates/default/scripts/lib/rangeToPattern.js ADDED Viewed

@@ -0,0 +1,74 @@
+// Exact regExp pattern for an integer range [min, max]. Engine API v3 text
+// controls have no min/max attributes — only `pattern` — so the room form
+// gets its numeric bounds as a generated regex (build-game-manifest.js).
+// The pattern is a UX hint; the authoritative clamp happens on the host.
+// wraps a pattern in a non-capturing group when it contains an alternation:
+// otherwise concatenation with a neighbouring prefix binds to the first
+// branch only ('9' + 'a|b' matches '9a' or 'b', not '9a'/'9b')
+function wrapAlternation(pattern) {
+  return pattern.includes('|') ? `(?:${pattern})` : pattern;
+}
+function digitsPattern(len) {
+  return len === 1 ? '[0-9]' : `[0-9]{${len}}`;
+}
+// lo/hi are equal-length digit strings, lo <= hi, no leading zeros: eats the
+// common prefix, then splits into "tail of the lo digit", "full middle
+// digits" and "tail of the hi digit"
+function digitGroupPattern(lo, hi) {
+  if (lo === hi) {
+    return lo;
+  }
+  if (lo.length === 1) {
+    return `[${lo}-${hi}]`;
+  }
+  if (lo[0] === hi[0]) {
+    return lo[0] + wrapAlternation(digitGroupPattern(lo.slice(1), hi.slice(1)));
+  }
+  const restLen = lo.length - 1;
+  const zeros = '0'.repeat(restLen);
+  const nines = '9'.repeat(restLen);
+  const parts = [
+    lo[0] + wrapAlternation(digitGroupPattern(lo.slice(1), nines)),
+  ];
+  const midLo = Number(lo[0]) + 1;
+  const midHi = Number(hi[0]) - 1;
+  if (midLo <= midHi) {
+    const midDigit = midLo === midHi ? String(midLo) : `[${midLo}-${midHi}]`;
+    parts.push(`${midDigit}${digitsPattern(restLen)}`);
+  }
+  parts.push(hi[0] + wrapAlternation(digitGroupPattern(zeros, hi.slice(1))));
+  return parts.join('|');
+}
+// Pattern for an integer in [min, max] (0 <= min <= max), unanchored and
+// without an enclosing group: the caller uses it as the HTML `pattern`
+// attribute (implicitly anchored by the browser).
+export function rangeToPattern(min, max) {
+  if (min > max) {
+    throw new Error(`rangeToPattern: min ${min} > max ${max}`);
+  }
+  const groups = [];
+  let lo = min;
+  while (lo <= max) {
+    const digits = String(lo).length;
+    const hi = Math.min(max, 10 ** digits - 1);
+    groups.push(digitGroupPattern(String(lo), String(hi)));
+    lo = hi + 1;
+  }
+  return wrapAlternation(groups.join('|'));
+}

package/templates/default/scripts/process-audio.js ADDED Viewed

@@ -0,0 +1,115 @@
+import { exec } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+// ffmpeg pipeline: normalises loudness (EBU R128) and emits BOTH .webm and
+// .mp3 for every source sound — the client's codec list is ['webm', 'mp3']
+// and it picks per browser support, so a missing .mp3 breaks Safari only.
+//
+// assets/audio-raw/*  ->  build/sounds/*.{mp3,webm}
+//
+// Optional for a fresh checkout: without ffmpeg the build falls back to the
+// placeholders in assets/sounds/ (see copy-game-sounds.js).
+// Run: npm run audio:process
+const execPromise = promisify(exec);
+const sourceDir = 'assets/audio-raw';
+const outputDir = 'build/sounds';
+const AUDIO_EXTENSIONS = ['.wav', '.mp3', '.flac', '.aiff', '.ogg', '.m4a'];
+// loudness targets (EBU R128)
+const LOUDNESS = {
+  // integrated loudness, a good balance for games and web content
+  I: -16,
+  // loudness range: keeps quiet and loud sounds apart without extremes
+  LRA: 7,
+  // true peak: a safe ceiling against clipping
+  TP: -1.5,
+};
+// leading silence trim
+const SILENCE_THRESHOLD = '-50dB';
+const CODEC_SETTINGS = {
+  MP3_QUALITY: '2', // VBR ~190 kbps
+  WEBM_BITRATE: '96k', // Opus bitrate
+};
+async function isFfmpegInstalled() {
+  try {
+    await execPromise('ffmpeg -version');
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function main() {
+  console.log('--- Starting Audio Processing ---');
+  if (!(await isFfmpegInstalled())) {
+    console.error('Error: ffmpeg is not installed.');
+    process.exit(1);
+  }
+  try {
+    await fs.access(sourceDir);
+  } catch {
+    console.error(`Error: source directory '${sourceDir}' not found.`);
+    process.exit(1);
+  }
+  await fs.mkdir(outputDir, { recursive: true });
+  console.log(`> output directory: ${outputDir}`);
+  const sourceFiles = await fs.readdir(sourceDir);
+  for (const file of sourceFiles) {
+    const extension = path.extname(file).toLowerCase();
+    if (!AUDIO_EXTENSIONS.includes(extension)) {
+      continue;
+    }
+    const sourcePath = path.join(sourceDir, file);
+    const baseName = path.basename(file, extension);
+    const outputMp3 = path.join(outputDir, `${baseName}.mp3`);
+    const outputWebm = path.join(outputDir, `${baseName}.webm`);
+    console.log(`\nprocessing: ${file}`);
+    const audioFilters = [
+      `silenceremove=start_periods=1:start_threshold=${SILENCE_THRESHOLD}`,
+      `loudnorm=I=${LOUDNESS.I}:LRA=${LOUDNESS.LRA}:tp=${LOUDNESS.TP}`,
+    ].join(',');
+    const command = [
+      'ffmpeg',
+      '-nostdin',
+      `-i "${sourcePath}"`,
+      '-hide_banner -loglevel error -y',
+      `-af "${audioFilters}"`,
+      `-c:a libmp3lame -q:a ${CODEC_SETTINGS.MP3_QUALITY} "${outputMp3}"`,
+      `-c:a libopus -b:a ${CODEC_SETTINGS.WEBM_BITRATE} "${outputWebm}"`,
+    ].join(' ');
+    try {
+      await execPromise(command);
+      console.log(`done: ${outputMp3}, ${outputWebm}`);
+    } catch (error) {
+      console.error(`error processing: ${file}`);
+      console.error(error.stderr);
+    }
+  }
+  console.log('\nAll files processed.');
+}
+main().catch(error => {
+  console.error('\nCritical script error:', error);
+  process.exit(1);
+});