create-vimp-game 0.1.0

package/src/ui.js

@@ -0,0 +1,66 @@
+// Вывод CLI. Текст интерфейса английский (как у bin/vimp-sim.js): его
+// читает автор игры, в том числе вне этого репозитория.
+
+// цвета гасятся, когда вывод уходит не в терминал (пайп, CI) или задан
+// NO_COLOR — иначе escape-последовательности попадают в лог
+const enabled =
+  process.stdout.isTTY === true && process.env.NO_COLOR === undefined;
+
+const CODES = {
+  bold: '1',
+  dim: '2',
+  red: '31',
+  green: '32',
+  yellow: '33',
+  cyan: '36',
+};
+
+// ESC собирается из кода: буквальный управляющий символ в исходнике
+// невидим при чтении и теряется при копировании
+const ESC = String.fromCharCode(27);
+
+function paint(name, text) {
+  return enabled ? `${ESC}[${CODES[name]}m${text}${ESC}[0m` : String(text);
+}
+
+export const color = {
+  bold: text => paint('bold', text),
+  dim: text => paint('dim', text),
+  red: text => paint('red', text),
+  green: text => paint('green', text),
+  yellow: text => paint('yellow', text),
+  cyan: text => paint('cyan', text),
+};
+
+export function log(message = '') {
+  process.stdout.write(`${message}\n`);
+}
+
+export function warn(message) {
+  process.stderr.write(`${color.yellow('warning:')} ${message}\n`);
+}
+
+// финальный экран: команды, которые автор игры выполняет следующими.
+// Порядок повторяет docs/ai/11-authoring-workflow.md: зависимости → ядро →
+// проверка контракта → headless-прогон → браузер
+export function nextSteps({ directory, tokens }) {
+  const lines = [
+    '',
+    `${color.green('Done.')} ${color.bold(tokens.GAME_TITLE)} scaffolded in ${color.cyan(directory)}`,
+    '',
+    'Next steps:',
+    `  cd ${directory}`,
+    '  npm install',
+    '  npm run core:build     # cargo + wasm-pack',
+    '  npm run check:contract # static plugin contract check',
+    '  npm run build',
+    '  npm run sim            # headless match',
+    '',
+    color.dim(
+      'Read CLAUDE.md in the generated project before writing gameplay.',
+    ),
+    '',
+  ];
+
+  return lines.join('\n');
+}

package/src/versions.generated.json

@@ -0,0 +1,4 @@
+{
+  "engine": "0.10.0",
+  "core": "0.3.2"
+}

package/src/versions.js

@@ -0,0 +1,87 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Пины vimp-engine / vimp-engine-core для сгенерированной игры. В шаблоне
+// они не хардкодятся: устаревший пин — тихая поломка, которая всплывает
+// только на сборке ядра (vimp-street-fighters приехал на
+// vimp-engine-core = "0.1.0" при актуальном 0.3.2).
+//
+// Два источника, в порядке приоритета:
+//   1. запуск из монорепозитория движка — версии читаются из
+//      packages/engine/package.json и packages/engine/core/Cargo.toml;
+//   2. установка из npm — src/versions.generated.json, который пишет
+//      scripts/write-versions.js хуком prepack.
+
+const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+
+export const GENERATED_FILE = path.join(moduleDir, 'versions.generated.json');
+
+// packages/create-vimp-game/src → корень репозитория
+export const REPO_ROOT = path.resolve(moduleDir, '..', '..', '..');
+
+// версия крейта — первый `version = "…"` после [package]: в Cargo.toml
+// ниже идут секции зависимостей со своими version.
+//
+// Копия живёт в движке (devtools/contract/loadContext.js): скаффолдер
+// ставится через `npm create` и обязан работать без движка в зависимостях.
+// Разбор обязан совпадать — правьте обе или ни одной.
+export function parseCrateVersion(toml) {
+  const packageSection = toml
+    .split(/^\s*\[/m)
+    .find(part => part.startsWith('package]'));
+
+  if (packageSection === undefined) {
+    throw new Error('Cargo.toml has no [package] section');
+  }
+
+  const match = packageSection.match(/^\s*version\s*=\s*"([^"]+)"/m);
+
+  if (match === null) {
+    throw new Error('Cargo.toml [package] has no version');
+  }
+
+  return match[1];
+}
+
+export async function readRepoVersions(root = REPO_ROOT) {
+  const enginePackage = JSON.parse(
+    await readFile(
+      path.join(root, 'packages', 'engine', 'package.json'),
+      'utf8',
+    ),
+  );
+  const cargo = await readFile(
+    path.join(root, 'packages', 'engine', 'core', 'Cargo.toml'),
+    'utf8',
+  );
+
+  return { engine: enginePackage.version, core: parseCrateVersion(cargo) };
+}
+
+async function readGeneratedVersions(file = GENERATED_FILE) {
+  const raw = JSON.parse(await readFile(file, 'utf8'));
+
+  if (typeof raw.engine !== 'string' || typeof raw.core !== 'string') {
+    throw new Error(`${file} is malformed: expected { engine, core }`);
+  }
+
+  return { engine: raw.engine, core: raw.core };
+}
+
+// пины для buildTokens: движок — caret-диапазон (патчи подхватываются),
+// крейт — точная версия (cargo сам трактует её как ^)
+export function toPins({ engine, core }) {
+  return { engineVersion: `^${engine}`, coreVersion: core };
+}
+
+export async function resolveVersions({
+  root = REPO_ROOT,
+  generated = GENERATED_FILE,
+} = {}) {
+  try {
+    return await readRepoVersions(root);
+  } catch {
+    return readGeneratedVersions(generated);
+  }
+}

package/templates/default/CLAUDE.md.tpl

@@ -0,0 +1,51 @@
+# CLAUDE.md
+
+## Overview
+
+`{{PACKAGE_NAME}}` is a game plugin for the VIMP engine: the engine owns
+networking, rounds, chat, panel and stat; this package owns the game. Only
+`dist/` is published. The full contract lives in the engine repository under
+`docs/ai/` (`03-host-plugin`, `04-client-plugin`, `05-wasm-core`,
+`06-snapshot-protocol`, `10-pitfalls`) — read it there, it is not copied here.
+
+## Boundaries
+
+- `src/host/` runs in a **Web Worker**: no DOM, no PixiJS, no `window`.
+- `src/client/` runs in the **main thread**: PixiJS parts and bakers only.
+- `core/` (Rust) owns **all** physics, movement and damage. The engine does
+  none of it: `core/src/game.rs` and `core/src/motion.rs` are the simulation,
+  and `motion.rs` is shared by the host step and the client predictor — moving
+  logic out of it desynchronises prediction from the server.
+
+## Contract constants
+
+- `ENGINE_API_VERSION` is always imported from
+  `vimp-engine/config/opcodes.js`, never written as a literal.
+- `PLAYER_STATE_LEN = 8` — the prediction budget `[x, y, angle, vx, vy, hp,
+  ammo, 0]`; the JS and Rust sides must agree on it.
+- Hot snapshot buffers are `indexed8` / `indexedNoNull8` only.
+- `src/config/auth.js` must declare the `model` parameter — the engine expects
+  that exact name.
+
+## Order of work
+
+1. snapshot schema and `src/config/` — decide what travels the wire first;
+2. Rust simulation in `core/`, with `npm run core:test` green;
+3. `npm run check:contract` and `npm run sim` — the machine reads the
+   invariants the browser only hints at;
+4. rendering: `src/client/parts/` and bakers.
+
+## Commands
+
+```bash
+npm run core:build      # REQUIRED before npm run dev
+npm run core:test
+npm run check:contract
+npm run sim
+npm run build
+npm test && npx eslint .
+npm run dev
+```
+
+Any functional change updates the tests covering it in the same change;
+`npx eslint .` and `npm test` end every change green.

package/templates/default/Cargo.toml.tpl

@@ -0,0 +1,27 @@
+# Workspace root of the Rust core. The crate itself lives in core/.
+[workspace]
+members = ["core"]
+resolver = "3"
+
+[workspace.package]
+version = "0.1.0"
+edition = "2024"
+license = "MIT"
+authors = ["{{AUTHOR}}"]
+
+[workspace.dependencies]
+vimp-engine-core = "{{CORE_VERSION}}"
+# insertion order of models/weapons/panel is a contract: the weapon index of
+# the snapshot row is the position of the key in the config, so a HashMap
+# would silently reshuffle it between runs
+indexmap = { version = "2.14.0", features = ["serde"] }
+# enhanced-determinism is mandatory: without it physics diverges between
+# machines, and the host and the client predictor stop agreeing
+rapier2d = { version = "0.34.0", features = ["enhanced-determinism", "serde-serialize"] }
+serde = { version = "1.0.228", features = ["derive"] }
+serde_json = "1.0.150"
+wasm-bindgen = "0.2.126"
+
+[profile.release]
+opt-level = 3
+lto = true

package/templates/default/LICENSE.tpl

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) {{YEAR}} {{AUTHOR}}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/templates/default/README.md.tpl

@@ -0,0 +1,61 @@
+# {{GAME_TITLE}}
+
+A VIMP game plugin (`{{PACKAGE_NAME}}`), scaffolded with `npm create vimp-game`.
+
+## Run it
+
+```bash
+npm install
+npm run core:build   # REQUIRED before npm run dev
+npm run dev
+```
+
+`npm run core:build` is not optional and not a later step: the dev harness
+(`dev/main.js`) imports the wasm out of `core/pkg-web/`, so until the Rust core
+has been built once Vite fails to resolve the import and `npm run dev` dies on
+startup. The same holds before the master is started against this package,
+even in dev mode — build the core and then `npm run build` at least once.
+
+## Commands
+
+```bash
+npm run core:build      # wasm-pack -> core/pkg-web (runtime) + core/pkg-node (tests)
+npm run core:test       # cargo test --workspace
+npm run build           # dist/: both bundles, maps, sounds, manifest.json
+npm run check:contract  # static engine<->game contract check (vimp-contract)
+npm test                # vitest
+npm run sim             # headless match on the real core
+npm run dev             # a match against bots in the tab
+npm run audio:process   # ffmpeg: assets/audio-raw/ -> build/sounds/ (optional)
+```
+
+## Layout
+
+| Path | What |
+| --- | --- |
+| `core/` | the Rust crate `{{CRATE_NAME}}` — physics, damage, movement |
+| `src/host/` | HostPlugin: runs in a Web Worker, no DOM and no PixiJS |
+| `src/client/` | ClientPlugin: render parts and bakers, main thread |
+| `src/config/` | game, client, auth, snapshot and sound configuration |
+| `src/data/` | maps and balance data |
+| `scripts/` | build steps: bundles -> `dist/` + `manifest.json` |
+| `dev/` | the standalone dev harness — never published |
+
+Only `dist/` is published (`files: ["dist"]`).
+
+## Sounds without ffmpeg
+
+The real pipeline is `assets/audio-raw/*.wav` → `npm run audio:process` →
+`build/sounds/*.{webm,mp3}`. That needs ffmpeg, so the template also ships
+ready-made placeholders in `assets/sounds/`: when `build/sounds/` is absent,
+`scripts/copy-game-sounds.js` falls back to them and the first build stays
+green on a bare machine. Process your own audio and the fallback stops being
+used.
+
+## Engine
+
+- `vimp-engine` `{{ENGINE_VERSION}}`
+- `vimp-engine-core` `{{CORE_VERSION}}`
+
+Game id: `{{GAME_ID}}`. The plugin contract lives in the engine repository
+under `docs/ai/`.

package/templates/default/_gitignore

@@ -0,0 +1,8 @@
+node_modules/
+dist/
+build/
+target/
+core/pkg-web/
+core/pkg-node/
+.debug/
+_*

package/templates/default/core/Cargo.toml.tpl

@@ -0,0 +1,19 @@
+[package]
+name = "{{CRATE_NAME}}"
+description = "{{GAME_TITLE}} — game simulation + wasm-bindgen ABI on top of vimp-engine-core."
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+
+[lib]
+# cdylib — the .wasm itself, rlib — the same code for `cargo test`
+crate-type = ["cdylib", "rlib"]
+
+[dependencies]
+vimp-engine-core = { workspace = true }
+indexmap = { workspace = true }
+rapier2d = { workspace = true }
+serde = { workspace = true }
+serde_json = { workspace = true }
+wasm-bindgen = { workspace = true }