create-vimp-game 0.1.0

package/templates/default/src/host/systemMessages.js

@@ -0,0 +1,10 @@
+// System chat codes of the game. A code is 'group:index' and carries no text:
+// the text lives on the client, at the same index of
+// modules.chat.params.messages[group] (src/config/client.js).
+//
+// Groups s, v, m, c and n belong to the engine. Registration is a blind
+// Object.assign into its registry, so a code in one of them replaces an engine
+// message with no warning at all — the game picks its own letter instead.
+export default {
+  BOTS_SPAWNED: 'g:0', // client text: '{0} bot(s) spawned'
+};

package/templates/default/tests/client/parts.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Texture } from 'pixi.js';
+import parts from '../../src/client/parts/index.js';
+import actorTexture from '../../src/client/bakers/actorTexture.js';
+import mapData from '../../src/data/maps/arena.js';
+
+// Parts are constructed inside the render tick, on a path with no try/catch
+// anywhere: an exception in a constructor aborts the whole frame, so every
+// entity of that frame is lost with it. These cases only build them — no
+// WebGL context is created in happy-dom.
+const { Map: MapPart, Actor, ShotEffect } = parts;
+
+// [x, y, angle, vx, vy, health, team] — the a1 block of src/config/snapshot.js
+const actorRow = [100, 200, 1.5, 0, 0, 100, 1];
+
+describe('Actor', () => {
+  const assets = { actorTexture: Texture.EMPTY };
+
+  it('places itself by the snapshot row', () => {
+    const actor = new Actor(actorRow, assets);
+
+    expect(actor.x).toBe(100);
+    expect(actor.y).toBe(200);
+    expect(actor.zIndex).toBe(3);
+
+    actor.update([10, 20, 0, 0, 0, 50, 2]);
+
+    expect(actor.x).toBe(10);
+    expect(actor.y).toBe(20);
+
+    actor.destroy();
+  });
+
+  it('tints the two teams differently', () => {
+    const one = new Actor(actorRow, assets);
+    const two = new Actor([0, 0, 0, 0, 0, 100, 2], assets);
+
+    expect(one.children[0].tint).not.toBe(two.children[0].tint);
+
+    one.destroy();
+    two.destroy();
+  });
+});
+
+describe('Map', () => {
+  it('draws the tiles of its own layer', () => {
+    const [layer, tiles] = Object.entries(mapData.layers)[0];
+    const part = new MapPart({
+      type: 'static',
+      map: mapData.map,
+      step: mapData.step,
+      layer,
+      tiles,
+      physicsStatic: mapData.physicsStatic,
+      scale: mapData.scale,
+    });
+
+    expect(part.zIndex).toBe(Number(layer));
+    expect(part.children.length).toBe(1);
+
+    part.destroy();
+  });
+
+  it('survives a dynamic body it has nothing to draw for', () => {
+    const part = new MapPart({ type: 'dynamic', layer: 2, angle: 0 });
+
+    expect(part.children.length).toBe(0);
+
+    part.destroy();
+  });
+});
+
+describe('ShotEffect', () => {
+  // [startX, startY, endX, endY, wasHit, author] — the e1 block
+  const row = [0, 0, 100, 0, 1, 7];
+
+  it('plays a positional sound and releases it on destroy', () => {
+    const soundId = Symbol('shot');
+    const soundManager = {
+      registerSound: vi.fn(() => soundId),
+      releaseSound: vi.fn(),
+    };
+
+    const effect = new ShotEffect(row, {}, { soundManager });
+
+    effect.run();
+
+    expect(soundManager.registerSound).toHaveBeenCalledWith('shot', {
+      position: { x: 0, y: 0 },
+    });
+
+    effect.destroy();
+
+    expect(soundManager.releaseSound).toHaveBeenCalledWith(soundId);
+  });
+
+  it('destroys itself once its lifetime is over', () => {
+    const effect = new ShotEffect(row, {}, { soundManager: null });
+
+    effect.run();
+    // the engine drives this through Ticker.shared; a direct call keeps the
+    // test free of real time
+    effect._update(1000);
+
+    expect(effect.destroyed).toBe(true);
+  });
+
+  // the effect destroys itself from the ticker, so the scene tearing down
+  // afterwards calls destroy() a second time
+  it('survives a second destroy()', () => {
+    const effect = new ShotEffect(row, {}, { soundManager: null });
+
+    effect.run();
+    effect._update(1000);
+
+    expect(() => effect.destroy()).not.toThrow();
+  });
+});
+
+describe('actorTexture baker', () => {
+  it('bakes through the renderer it is given', () => {
+    const renderer = { generateTexture: vi.fn(() => Texture.EMPTY) };
+    const texture = actorTexture({ size: 32, color: 0xffffff }, renderer);
+
+    expect(renderer.generateTexture).toHaveBeenCalled();
+    expect(texture).toBe(Texture.EMPTY);
+  });
+});

package/templates/default/tests/config/contract.test.js

@@ -0,0 +1,132 @@
+import { describe, it, expect } from 'vitest';
+import { ENGINE_API_VERSION } from 'vimp-engine/config/opcodes.js';
+import { assertGameConfigShape } from 'vimp-engine/lib/gamePlugin.js';
+import hostPlugin from '../../src/host/index.js';
+import clientPlugin from '../../src/client/index.js';
+
+// Local safety net over `npm run check:contract`: the engine-side validator
+// is the source of truth, but it runs as a separate command — these cases
+// fail the ordinary test run, in the same change that broke them.
+const clientConfig = hostPlugin.buildClientGameConfig();
+
+describe('game config', () => {
+  it('passes the engine gate that runs on plugin load', () => {
+    expect(() => assertGameConfigShape(hostPlugin)).not.toThrow();
+  });
+
+  it('declares one API version in both halves', () => {
+    expect(hostPlugin.engineApi).toBe(ENGINE_API_VERSION);
+    expect(clientPlugin.engineApi).toBe(ENGINE_API_VERSION);
+    expect(hostPlugin.id).toBe(clientPlugin.id);
+  });
+});
+
+describe('snapshot schema', () => {
+  const { snapshot } = hostPlugin.gameConfig;
+
+  it('gives every block a unique id', () => {
+    const ids = Object.values(snapshot).map(block => block.id);
+
+    expect(new Set(ids).size).toBe(ids.length);
+  });
+
+  it("keeps class 'hot' on indexed blocks only", () => {
+    for (const [key, block] of Object.entries(snapshot)) {
+      if (block.class === 'hot') {
+        expect(['indexed8', 'indexedNoNull8'], key).toContain(block.kind);
+      }
+    }
+  });
+
+  it('interpolates f32 fields of hot blocks only', () => {
+    for (const block of Object.values(snapshot)) {
+      for (const field of block.fields) {
+        if (field.interp !== undefined) {
+          expect(block.class).toBe('hot');
+          expect(field.ty).toBe('f32');
+        }
+      }
+    }
+  });
+
+  it('keys every block after a model, a weapon or a map set', () => {
+    const { models, weapons } = hostPlugin.gameConfig.parts;
+    const setIds = new Set(
+      Object.values(hostPlugin.gameConfig.maps).map(
+        map => map.setId ?? hostPlugin.gameConfig.mapSetId,
+      ),
+    );
+
+    // the core builds a block per model and per weapon under their own names,
+    // and the engine one for the dynamic map bodies under the map setId — a
+    // block keyed by none of them is one nothing ever fills, and a MISSING one
+    // makes the packer reject the frame
+    for (const key of Object.keys(snapshot)) {
+      expect(key in models || key in weapons || setIds.has(key), key).toBe(true);
+    }
+
+    for (const setId of setIds) {
+      expect(Object.keys(snapshot), setId).toContain(setId);
+    }
+  });
+});
+
+describe('client config', () => {
+  const { gameSets, entitiesOnCanvas, bakedAssets } = clientConfig.parts;
+
+  it('has a gameSets entry for every snapshot key and map setId', () => {
+    for (const key of Object.keys(hostPlugin.gameConfig.snapshot)) {
+      expect(Object.keys(gameSets)).toContain(key);
+    }
+
+    for (const map of Object.values(hostPlugin.gameConfig.maps)) {
+      expect(Object.keys(gameSets)).toContain(
+        map.setId ?? hostPlugin.gameConfig.mapSetId,
+      );
+    }
+  });
+
+  it('registers every part of a set on a canvas and exports its class', () => {
+    for (const names of Object.values(gameSets)) {
+      for (const name of names) {
+        expect(entitiesOnCanvas[name], name).toBeDefined();
+        expect(clientPlugin.parts[name], name).toBeDefined();
+      }
+    }
+  });
+
+  it('bakes only assets that have a baker', () => {
+    for (const entries of Object.values(bakedAssets)) {
+      for (const entry of entries) {
+        expect(clientPlugin.bakers[entry.name], entry.name).toBeDefined();
+        expect(entitiesOnCanvas[entry.component], entry.component).toBeDefined();
+      }
+    }
+  });
+
+  it('binds exactly the player keys the host declares', () => {
+    const bound = new Set(
+      Object.values(clientConfig.modules.controls.keySetList[1]),
+    );
+    const declared = new Set(Object.keys(hostPlugin.gameConfig.playerKeys));
+
+    expect([...bound].sort()).toEqual([...declared].sort());
+  });
+
+  it("maps the engine time key 't' to a time field", () => {
+    const { keys, fields } = clientConfig.modules.panel;
+    const field = fields.find(item => item.name === keys.t);
+
+    expect(field?.type).toBe('time');
+  });
+
+  it('gives every system message code a text', () => {
+    const texts = clientConfig.modules.chat.params.messages;
+
+    for (const code of Object.values(hostPlugin.systemMessages)) {
+      const [group, index] = code.split(':');
+
+      expect(texts[group]?.[Number(index)], code).toBeDefined();
+    }
+  });
+});

package/templates/default/tests/config/game.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import gameConfig from '../../src/config/game.js';
+import maps from '../../src/data/maps/index.js';
+
+// Starter test of the config invariants the build itself depends on. Keep it
+// growing with the config: a silent mismatch here surfaces as a game missing
+// from the lobby, not as a stack trace.
+describe('gameConfig', () => {
+  it('names an existing current map', () => {
+    expect(Object.keys(maps)).toContain(gameConfig.currentMap);
+  });
+
+  it('has a spectator team among the teams', () => {
+    expect(gameConfig.teams).toHaveProperty(gameConfig.spectatorTeam);
+  });
+
+  it('gives every playing team respawns for a full room', () => {
+    const playing = Object.keys(gameConfig.teams).filter(
+      team => team !== gameConfig.spectatorTeam,
+    );
+
+    for (const map of Object.values(maps)) {
+      for (const team of playing) {
+        expect(map.respawns[team]?.length ?? 0).toBeGreaterThanOrEqual(
+          gameConfig.roomDefaults.maxPlayers,
+        );
+      }
+    }
+  });
+
+  it('builds the room form out of the fields the host honours', () => {
+    const honoured = [
+      'maps',
+      'maxPlayers',
+      'map',
+      'roundTime',
+      'mapTime',
+      'friendlyFire',
+    ];
+
+    for (const field of gameConfig.roomForm) {
+      expect(honoured).toContain(field.name);
+    }
+  });
+});

package/templates/default/tests/core/nodeCore.test.js

@@ -0,0 +1,61 @@
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect } from 'vitest';
+import { buildCoreConfig } from 'vimp-engine/lib/coreConfig.js';
+import gameConfig from '../../src/config/game.js';
+import mapData from '../../src/data/maps/arena.js';
+
+// The `integration` project (node environment): the REAL Rust core, driven
+// through the --target nodejs build. That build is not part of `npm test`, so
+// without `npm run core:build:node` there is nothing to import and the whole
+// file is skipped — a fresh checkout must not fail here, it must tell you the
+// core is missing.
+const gluePath = fileURLToPath(
+  new URL('../../core/pkg-node/{{CRATE_SNAKE}}.js', import.meta.url),
+);
+
+const hasCore = existsSync(gluePath);
+
+describe.skipIf(!hasCore)('the Rust core through pkg-node', () => {
+  it('boots from the config the engine assembles', async () => {
+    const { GameCore } = await import(gluePath);
+    const core = new GameCore(JSON.stringify(buildCoreConfig(gameConfig)));
+
+    expect(core).toBeTruthy();
+  });
+
+  it('simulates one actor for a second of steps', async () => {
+    const { GameCore } = await import(gluePath);
+    const core = new GameCore(
+      // a fixed seed: two runs of this test must produce the same match
+      JSON.stringify(buildCoreConfig(gameConfig, { seed: 1 })),
+    );
+
+    core.load_map(JSON.stringify(mapData));
+
+    const [x, y, angle] = mapData.respawns.team1[0];
+
+    core.spawn_actor(1, 'a1', 1, x, y, angle);
+
+    expect(core.is_alive(1)).toBe(true);
+
+    core.apply_input(1, 1, 'down', 'forward');
+
+    // 120 steps of 1/120 s — the engine's own fixed step
+    for (let i = 0; i < 120; i += 1) {
+      core.step(1 / 120);
+    }
+
+    const moved = core.position_of(1);
+
+    // it drove forward: the angle of respawn 0 is +X, and the wall is far
+    expect(moved[0]).toBeGreaterThan(x);
+    expect(Math.abs(moved[1] - y)).toBeLessThan(1);
+  });
+});
+
+describe.skipIf(hasCore)('the Rust core', () => {
+  it('is not built — run `npm run core:build:node`', () => {
+    expect(hasCore).toBe(false);
+  });
+});

package/templates/default/tests/host/hostPlugin.test.js

@@ -0,0 +1,198 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import hostPlugin from '../../src/host/index.js';
+import ScriptedManager from '../../src/host/ScriptedManager.js';
+import spawnCommand from '../../src/host/spawnCommand.js';
+import mapData from '../../src/data/maps/arena.js';
+
+// The engine dereferences the fields below without a guard and calls the five
+// scripted methods by name — both are contracts no browser run announces
+// before it crashes.
+describe('HostPlugin surface', () => {
+  it('exports every field the engine reads', () => {
+    expect(typeof hostPlugin.id).toBe('string');
+    expect(typeof hostPlugin.engineApi).toBe('number');
+    expect(typeof hostPlugin.createCore).toBe('function');
+    expect(typeof hostPlugin.gameConfig).toBe('object');
+    expect(typeof hostPlugin.authSchema).toBe('object');
+    expect(typeof hostPlugin.createModules).toBe('function');
+    expect(typeof hostPlugin.buildClientGameConfig).toBe('function');
+    expect(Array.isArray(hostPlugin.chatCommands)).toBe(true);
+  });
+
+  it('does not shadow an engine chat command', () => {
+    const reserved = ['/name', '/nr', '/timeleft', '/mapname', '/rank'];
+
+    for (const command of hostPlugin.chatCommands) {
+      expect(command.name.startsWith('/')).toBe(true);
+      expect(reserved).not.toContain(command.name);
+    }
+  });
+
+  it('keeps its system message codes out of the engine groups', () => {
+    // engine groups and their last index
+    const reserved = { s: 6, v: 5, m: 1, c: 1, n: 1 };
+
+    for (const code of Object.values(hostPlugin.systemMessages)) {
+      const [group, index] = code.split(':');
+
+      expect(Number(index) > (reserved[group] ?? -1)).toBe(true);
+    }
+  });
+});
+
+// Minimal doubles of the engine modules: the manager only ever talks to these
+// five, and a real one would drag the whole host runtime into a unit test.
+function createContext({ teamSizes = { team1: 0, team2: 0 }, isFull = false }) {
+  const created = [];
+  const sizes = { ...teamSizes };
+  let nextId = 10;
+
+  const participants = {
+    isFull,
+    getPlayableTeams: () => Object.keys(sizes),
+    getTeamSize: team => sizes[team] ?? 0,
+    createScripted: ({ team, model }) => {
+      const gameId = (nextId += 1);
+
+      created.push({ gameId, team, model, isScripted: true, teamId: 1 });
+      sizes[team] += 1;
+
+      return gameId;
+    },
+    get: gameId => created.find(item => item.gameId === gameId),
+    getScripted: () => created,
+    remove: gameId => {
+      const index = created.findIndex(item => item.gameId === gameId);
+
+      if (index !== -1) {
+        sizes[created[index].team] -= 1;
+        created.splice(index, 1);
+      }
+    },
+  };
+
+  return {
+    participants,
+    coreAdapter: { removePlayer: vi.fn() },
+    panel: { addUser: vi.fn(), removeUser: vi.fn() },
+    stat: { addUser: vi.fn(), removeUser: vi.fn() },
+    scripted: hostPlugin.gameConfig.scripted,
+  };
+}
+
+describe('ScriptedManager', () => {
+  let ctx;
+  let manager;
+
+  beforeEach(() => {
+    ctx = createContext({});
+    manager = new ScriptedManager(ctx);
+    manager.createMap(mapData);
+  });
+
+  it('creates nothing before a map is known', () => {
+    const fresh = new ScriptedManager(createContext({}));
+
+    expect(fresh.createScripted(2)).toBe(0);
+  });
+
+  it('spreads bots over the emptiest team', () => {
+    expect(manager.createScripted(4)).toBe(4);
+    expect(manager.getCountsPerTeam()).toEqual({ team1: 2, team2: 2 });
+  });
+
+  it('stops at the respawn capacity of a team', () => {
+    const capacity = mapData.respawns.team1.length;
+
+    expect(manager.createScripted(capacity + 3, 'team1')).toBe(capacity);
+  });
+
+  // the emptiest team can be the one out of respawn points; before the
+  // fallback that case burned every iteration and created nobody
+  it('falls back to a team that still has respawn points', () => {
+    const capacity = mapData.respawns.team1.length;
+    const crowded = new ScriptedManager(
+      createContext({ teamSizes: { team1: capacity, team2: 0 } }),
+    );
+
+    crowded.createMap(mapData);
+
+    expect(crowded.createScripted(1)).toBe(1);
+    expect(crowded.getCountsPerTeam()).toEqual({ team2: 1 });
+  });
+
+  it('creates nothing once the room is full', () => {
+    const full = new ScriptedManager(createContext({ isFull: true }));
+
+    full.createMap(mapData);
+
+    expect(full.createScripted(3)).toBe(0);
+  });
+
+  it('frees exactly one slot for a human', () => {
+    manager.createScripted(2, 'team1');
+
+    expect(manager.removeOneForHuman('team1')).toBe(true);
+    expect(manager.getCountsPerTeam()).toEqual({ team1: 1 });
+    expect(manager.removeOneForHuman('team2')).toBe(false);
+  });
+
+  it('removes bots of one team or of all of them', () => {
+    manager.createScripted(2, 'team1');
+    manager.createScripted(1, 'team2');
+
+    manager.removeScripted('team1');
+    expect(manager.getCountsPerTeam()).toEqual({ team2: 1 });
+
+    manager.removeScripted();
+    expect(manager.getCountsPerTeam()).toEqual({});
+  });
+});
+
+describe('/spawn', () => {
+  const spawnContext = (created, maxPlayers = 16) => ({
+    chat: { pushSystem: vi.fn() },
+    roundManager: { initiateNewRound: vi.fn() },
+    participants: { maxPlayers },
+    scripted: { createScripted: vi.fn(() => created) },
+  });
+
+  it('reports the number actually created and restarts the round', () => {
+    const ctx = spawnContext(2);
+
+    spawnCommand.handler(ctx, 1, ['3']);
+
+    expect(ctx.scripted.createScripted).toHaveBeenCalledWith(3);
+    expect(ctx.chat.pushSystem).toHaveBeenCalledWith('BOTS_SPAWNED', [2]);
+    expect(ctx.roundManager.initiateNewRound).toHaveBeenCalled();
+  });
+
+  it('defaults to a single bot', () => {
+    const ctx = spawnContext(1);
+
+    spawnCommand.handler(ctx, 1, []);
+
+    expect(ctx.scripted.createScripted).toHaveBeenCalledWith(1);
+  });
+
+  // the argument comes straight from a chat line
+  it('clamps the count to [1, maxPlayers]', () => {
+    const negative = spawnContext(1);
+    const huge = spawnContext(1);
+
+    spawnCommand.handler(negative, 1, ['-3']);
+    spawnCommand.handler(huge, 1, ['1e9']);
+
+    expect(negative.scripted.createScripted).toHaveBeenCalledWith(1);
+    expect(huge.scripted.createScripted).toHaveBeenCalledWith(16);
+  });
+
+  it('does not restart the round when nothing was created', () => {
+    const ctx = spawnContext(0);
+
+    spawnCommand.handler(ctx, 1, ['3']);
+
+    expect(ctx.chat.pushSystem).toHaveBeenCalledWith('BOTS_SPAWNED', [0]);
+    expect(ctx.roundManager.initiateNewRound).not.toHaveBeenCalled();
+  });
+});

package/templates/default/tests/stubs/wasmCore.js

@@ -0,0 +1,19 @@
+// Stand-in for core/pkg-web/ in the unit tests (see the alias in
+// vitest.config.js). The web build of the core is a product of
+// `npm run core:build:web`; a unit test never instantiates it, but Vite
+// resolves the dynamic import of src/host/nodeCore.js at transform time, so
+// without this module every test that touches a plugin half would fail in a
+// fresh checkout with "Failed to resolve import".
+//
+// It throws rather than pretending to be a core: a test that DOES need the
+// simulation belongs in tests/core/, against the real Node build.
+const notBuilt = () => {
+  throw new Error(
+    'the WASM core is not available in unit tests — run `npm run core:build` ' +
+      'and use tests/core/ (the integration project) for the real thing',
+  );
+};
+
+export default notBuilt;
+export const GameCore = notBuilt;
+export const ClientCore = notBuilt;

package/templates/default/vite.config.js

@@ -0,0 +1,74 @@
+import { defineConfig } from 'vite';
+import path from 'node:path';
+
+// Three modes in one file (docs/ai/02-packaging.md):
+//
+//   vite            — dev harness of `npm run dev`: index.html -> dev/main.js,
+//                     a match against bots in the tab, no master;
+//   vite build --mode client|host
+//                   — the published halves, built by TWO independent runs:
+//                     a chunk shared between them would drag DOM code
+//                     (PixiJS) into the Worker-safe host bundle.
+//
+// PixiJS is a singleton supplied by the engine through an import map, so it
+// stays external in the builds and deduped in dev — two PixiJS copies mean
+// two extension registries, and objects of one copy fail inside the other.
+const entries = {
+  client: path.resolve(import.meta.dirname, 'src/client/index.js'),
+  host: path.resolve(import.meta.dirname, 'src/host/index.js'),
+};
+
+export default defineConfig(({ command, mode }) => {
+  if (command === 'serve') {
+    return {
+      server: {
+        open: true,
+        // `npm link vimp-engine` resolves the engine outside this package:
+        // without the allowance Vite refuses to serve its sources
+        fs: { allow: ['..'] },
+      },
+      resolve: { dedupe: ['pixi.js'] },
+      optimizeDeps: {
+        // the engine ships ESM sources: pre-bundling breaks its dynamic
+        // imports and the boot config it shares with the SDK
+        exclude: ['vimp-engine'],
+        // ...but its npm dependencies must stay pre-bundled: as transitive
+        // imports of an excluded package they would be served as CJS
+        // sources, which the browser cannot resolve
+        include: ['pixi.js', 'pixi.js/unsafe-eval', 'howler'],
+      },
+    };
+  }
+
+  const entry = entries[mode];
+
+  if (!entry) {
+    throw new Error(
+      `{{GAME_ID}} build: unknown --mode "${mode}" (expected "client" or "host")`,
+    );
+  }
+
+  return {
+    build: {
+      outDir: 'dist',
+      // both runs write into the same dist/ — the second must not wipe the first
+      emptyOutDir: false,
+      // the .wasm must stay a separate asset with a URL: base64 inlining costs
+      // +33 %, breaks instantiateStreaming and duplicates the binary in both
+      // bundles. build.lib is not used at all — it inlines assets regardless.
+      assetsInlineLimit: 0,
+      rollupOptions: {
+        input: entry,
+        // without it Vite tree-shakes the entry's default export (the plugin)
+        preserveEntrySignatures: 'strict',
+        external: [/^pixi\.js(\/.*)?$/],
+        output: {
+          format: 'es',
+          entryFileNames: `${mode}-[hash].js`,
+          assetFileNames: 'assets/[name]-[hash][extname]',
+          inlineDynamicImports: true,
+        },
+      },
+    },
+  };
+});