create-vimp-game 0.1.0

package/templates/default/src/client/bakers/actorTexture.js

@@ -0,0 +1,40 @@
+import { Graphics, Rectangle } from 'pixi.js';
+
+// Procedural texture of the actor: a disc with a muzzle wedge pointing along
+// the +X axis (angle 0 of the core). Baked ONCE per canvas at startup, before
+// any part exists — this is why the package ships no images.
+//
+// It is drawn WHITE and tinted per team in the part: one baked texture serves
+// every colour variant and keeps the draw calls batched.
+//
+// A baker owns what it returns. The engine re-bakes on a WebGL context
+// restore and destroys the previous result together with its TextureSource, so
+// never return a view onto a shared atlas or a texture someone else holds.
+//
+// `params` comes from parts.bakedAssets ({ size, color }); `renderer` is the
+// Pixi renderer of the canvas being baked.
+export default function actorTexture(params, renderer) {
+  const { size, color } = params;
+  const radius = size / 2;
+  const graphics = new Graphics();
+
+  graphics.circle(radius, radius, radius);
+  graphics.fill(color);
+
+  // the muzzle: a wedge from the centre to the +X edge, so a standing actor
+  // still shows where it is aiming
+  graphics.moveTo(radius, radius - radius * 0.35);
+  graphics.lineTo(size, radius);
+  graphics.lineTo(radius, radius + radius * 0.35);
+  graphics.closePath();
+  graphics.fill({ color, alpha: 0.55 });
+
+  const texture = renderer.generateTexture({
+    target: graphics,
+    frame: new Rectangle(0, 0, size, size),
+  });
+
+  graphics.destroy(true);
+
+  return texture;
+}

package/templates/default/src/client/bakers/index.js

@@ -0,0 +1,8 @@
+import actorTexture from './actorTexture.js';
+
+// ClientPlugin.bakers: baker name -> function. The names are the ones
+// parts.bakedAssets refers to (src/config/client.js); an entry naming a baker
+// that is not here is skipped in silence, and the part gets an empty `assets`.
+export default {
+  actorTexture,
+};

package/templates/default/src/client/index.js

@@ -0,0 +1,67 @@
+import { ENGINE_API_VERSION } from 'vimp-engine/config/opcodes.js';
+import styles from './style.css?inline';
+import parts from './parts/index.js';
+import bakers from './bakers/index.js';
+import { isNodeCore, loadNodeCore, loadWebCore } from '../host/nodeCore.js';
+
+// ClientPlugin — the render half, main thread: PixiJS parts, procedural
+// textures and the three hooks into the client core. Default export of the
+// client entry (vite build --mode client); the engine loads it by
+// GameManifest.entries.client.
+export default {
+  id: '{{GAME_ID}}',
+  engineApi: ENGINE_API_VERSION,
+
+  // MUST return { core, memory }: `memory` is the WebAssembly memory the
+  // engine reads the hot buffer out of every render tick. Without it the
+  // client silently renders nothing but the discrete frames.
+  async createClientCore(clientConfigJson, { wasmUrl } = {}) {
+    if (isNodeCore(wasmUrl)) {
+      const node = await loadNodeCore(wasmUrl);
+
+      // the Node build exposes no WASM memory: the headless client reads the
+      // hot buffer by copy (hot_values()) instead of through a view
+      return { core: new node.ClientCore(clientConfigJson), memory: null };
+    }
+
+    const { default: init, ClientCore } = await loadWebCore();
+    const wasm = await init({ module_or_path: wasmUrl });
+
+    return { core: new ClientCore(clientConfigJson), memory: wasm.memory };
+  },
+
+  parts,
+  bakers,
+
+  // CSS as a string — see src/client/style.css
+  styles,
+
+  // all three hooks are called unconditionally: an empty body is fine, a
+  // missing hook is a crash
+  hooks: {
+    // the model is known only after authorization, and the predictor cannot
+    // move an actor whose speed and turn rate it does not know
+    onAuth(core, authData) {
+      core.set_model(authData.model);
+    },
+
+    // the authoritative panel: the local shot is gated by ammo, and this is
+    // where the client core learns how much of it is left
+    onPanel(core, panelData) {
+      core.sync_panel(JSON.stringify(panelData));
+    },
+
+    // Local prediction of the shot: the tracer appears on the press instead
+    // of a round trip later, and the core drops the authoritative twin of it
+    // when the frame with it arrives. Returning null means "nothing to draw
+    // locally" — every gate (alive, cooldown, ammo) lives in the core, which
+    // mirrors the host: a guess the host would refuse is worse than no guess.
+    onLocalAction(core, action, name, now) {
+      if (action === 'down' && name === 'fire') {
+        return core.try_fire(now) ?? null;
+      }
+
+      return null;
+    },
+  },
+};

package/templates/default/src/client/parts/Actor.js

@@ -0,0 +1,69 @@
+import { Container, Sprite } from 'pixi.js';
+
+// One actor on the main canvas. The engine builds it from the `a1` snapshot
+// block (src/config/client.js -> parts.gameSets) and feeds it the field array
+// of that block, in the order of src/config/snapshot.js:
+//
+//   [x, y, angle, vx, vy, health, team]
+//
+// The very same layout also arrives from the local prediction (the predicted
+// tail of the hot buffer), so this class never learns whether the row it got
+// is authoritative or a guess — and must not care.
+const FIELD = {
+  X: 0,
+  Y: 1,
+  ANGLE: 2,
+  HEALTH: 5,
+  TEAM: 6,
+};
+
+// white texture + tint: one baked asset serves both teams
+const TEAM_TINT = {
+  1: 0x4fa3ff,
+  2: 0xff7a4f,
+};
+
+const NEUTRAL_TINT = 0xb0b0b0;
+
+export default class Actor extends Container {
+  constructor(data, assets) {
+    super();
+
+    // Paint order is `zIndex` and nothing else: the engine marks the stage
+    // sortable and calls stage.sortChildren() on every addChild, and PixiJS v8
+    // sorts by zIndex there. A `layer` property alone does nothing at all.
+    this.zIndex = 3;
+
+    this._sprite = new Sprite(assets.actorTexture);
+    this._sprite.anchor.set(0.5);
+
+    this.addChild(this._sprite);
+
+    this.update(data);
+  }
+
+  update(data) {
+    this.x = data[FIELD.X] || 0;
+    this.y = data[FIELD.Y] || 0;
+    this._sprite.rotation = data[FIELD.ANGLE] || 0;
+
+    const team = data[FIELD.TEAM];
+
+    if (team !== this._team) {
+      this._team = team;
+      this._sprite.tint = TEAM_TINT[team] ?? NEUTRAL_TINT;
+    }
+
+    // A dead actor never arrives here: the core sends a null row for it and
+    // the engine destroys the instance. Health is kept anyway — the first
+    // thing a game grows is a bar over the head, and this is where it reads
+    // its value.
+    this._health = data[FIELD.HEALTH];
+  }
+
+  destroy() {
+    // `true` destroys the children as well; the baked texture is NOT ours to
+    // destroy — the engine re-uses it for every actor on this canvas
+    super.destroy({ children: true });
+  }
+}

package/templates/default/src/client/parts/Map.js

@@ -0,0 +1,74 @@
+import { Container, Graphics } from 'pixi.js';
+
+// The map, drawn procedurally. The engine splits MAP_DATA into one instance
+// per render layer of `layers` (src/data/maps/arena.js) and hands each one:
+//
+//   { type: 'static', map, step, layer, tiles, physicsStatic, spriteSheet,
+//     scale }
+//
+// `tiles` are the tile values THIS layer draws — a map with several layers
+// gets several instances of this class, each drawing its own subset.
+//
+// A map with `physicsDynamic` also gets one instance per movable body, with
+// `type: 'dynamic'`; the template has none, and the branch below says so
+// rather than pretending the case cannot happen.
+//
+// Note what is NOT here: the step arrives ALREADY multiplied by the map
+// scale, so scaling the container again would draw the world twice as large
+// as the physics.
+const WALL_COLOR = 0x33384a;
+const WALL_EDGE = 0x4a5168;
+
+export default class Map extends Container {
+  constructor(data) {
+    super();
+
+    // an ARRAY is a row of the `c1` snapshot block — a movable body of the
+    // map, live position included ([x, y, angle]). The template declares no
+    // physicsDynamic, so no such row is ever packed; the branch exists so that
+    // adding one is a drawing problem, not a crash inside the render tick.
+    if (Array.isArray(data)) {
+      this.zIndex = 2;
+
+      return;
+    }
+
+    // under the actors and the tracers
+    this.zIndex = Number(data.layer) || 1;
+
+    if (data.type === 'dynamic') {
+      // the map payload of a movable body (image, size, angle) — same story
+      return;
+    }
+
+    this._draw(data);
+  }
+
+  _draw({ map, step, tiles }) {
+    const drawn = new Set(tiles ?? []);
+    const graphics = new Graphics();
+
+    for (let row = 0; row < map.length; row += 1) {
+      for (let col = 0; col < map[row].length; col += 1) {
+        if (!drawn.has(map[row][col])) {
+          continue;
+        }
+
+        graphics.rect(col * step, row * step, step, step);
+      }
+    }
+
+    graphics.fill(WALL_COLOR);
+    graphics.stroke({ color: WALL_EDGE, width: 2, alignment: 0 });
+
+    this.addChild(graphics);
+  }
+
+  // the static map never changes between two MAP_DATA payloads: a new map
+  // arrives as a CLEAR of this setId followed by fresh instances
+  update() {}
+
+  destroy() {
+    super.destroy({ children: true });
+  }
+}

package/templates/default/src/client/parts/ShotEffect.js

@@ -0,0 +1,107 @@
+import { Container, Graphics, Ticker } from 'pixi.js';
+
+// The tracer of one shot. This part is an EFFECT, not an entity: the `e1`
+// block is a list16, its payload is an ARRAY of rows, and for an array the
+// engine creates one short-lived instance per row instead of an addressable
+// object. An effect class implements `run()` on top of the usual contract —
+// the engine calls it right after adding the instance to the stage — and is
+// expected to destroy ITSELF when the animation ends.
+//
+// Row layout (src/config/snapshot.js -> e1):
+//
+//   [startX, startY, endX, endY, wasHit, author]
+//
+// The local prediction draws its own tracer the moment the trigger is pressed
+// and the client core then drops the authoritative twin of it by `author`, so
+// a row for the local player normally reaches this class once — from the
+// prediction, one round trip earlier.
+const LIFETIME = 140;
+const HIT_COLOR = 0xffd166;
+const MISS_COLOR = 0x9fb3c8;
+
+export default class ShotEffect extends Container {
+  constructor(data, assets, dependencies) {
+    super();
+
+    // above the map, below the actors
+    this.zIndex = 2;
+
+    this._startX = data[0];
+    this._startY = data[1];
+    this._endX = data[2];
+    this._endY = data[3];
+    this._wasHit = Boolean(data[4]);
+
+    this._soundManager = dependencies.soundManager;
+    this._soundId = null;
+    this._tick = null;
+    this._elapsed = 0;
+
+    this._line = new Graphics();
+    this.addChild(this._line);
+  }
+
+  run() {
+    this._line
+      .moveTo(this._startX, this._startY)
+      .lineTo(this._endX, this._endY)
+      .stroke({
+        color: this._wasHit ? HIT_COLOR : MISS_COLOR,
+        width: 2,
+        alpha: 1,
+      });
+
+    if (this._wasHit) {
+      this._line.circle(this._endX, this._endY, 4).fill(HIT_COLOR);
+    }
+
+    // spatial voice: the engine ranks voices by priority and distance and
+    // plays the loudest 30, so a busy match stays audible
+    this._soundId =
+      this._soundManager?.registerSound('shot', {
+        position: { x: this._startX, y: this._startY },
+      }) ?? null;
+
+    this._tick = ticker => this._update(ticker.deltaMS);
+    Ticker.shared.add(this._tick);
+  }
+
+  _update(deltaMS) {
+    this._elapsed += deltaMS;
+
+    const left = 1 - this._elapsed / LIFETIME;
+
+    if (left <= 0) {
+      this.destroy();
+
+      return;
+    }
+
+    this._line.alpha = left;
+  }
+
+  // an effect has no update path: every row is a new instance
+  update() {}
+
+  destroy() {
+    // the effect destroys itself from the ticker, so a second call is normal
+    // (the scene being torn down right after the flash expired)
+    if (this.destroyed) {
+      return;
+    }
+
+    if (this._tick) {
+      Ticker.shared.remove(this._tick);
+      this._tick = null;
+    }
+
+    // the flash is over long before the sample is: release, do not
+    // unregister — unregistering cuts the sound off mid-shot
+    if (this._soundId) {
+      this._soundManager.releaseSound(this._soundId);
+      this._soundId = null;
+    }
+
+    super.destroy({ children: true });
+  }
+}

package/templates/default/src/client/parts/index.js

@@ -0,0 +1,13 @@
+import Map from './Map.js';
+import Actor from './Actor.js';
+import ShotEffect from './ShotEffect.js';
+
+// ClientPlugin.parts: class name -> class. The names are the ones
+// parts.gameSets and parts.entitiesOnCanvas use (src/config/client.js) —
+// all three lists must agree, and entitiesOnCanvas is the one that actually
+// registers a class with the factory.
+export default {
+  Map,
+  Actor,
+  ShotEffect,
+};

package/templates/default/src/client/style.css

@@ -0,0 +1,26 @@
+/*
+ * Styles of the game, imported with ?inline and handed to the engine as a
+ * string (ClientPlugin.styles) — the engine injects them into the document.
+ * The plugin build has no HTML entry, so a plain CSS import would be
+ * auto-injected by Vite into nothing.
+ *
+ * The engine ships the layout of #panel, #stat, #chat and #vote; everything
+ * here is only the look of the cells THIS game declares
+ * (src/config/client.js -> modules.panel.fields).
+ */
+
+#panel {
+  gap: 16px;
+  font: 600 20px/1 system-ui, sans-serif;
+  color: #e6ecf5;
+  text-shadow: 0 1px 2px rgb(0 0 0 / 60%);
+}
+
+#panel-am::before {
+  content: '⌁ ';
+  opacity: 0.7;
+}
+
+#panel-time {
+  opacity: 0.8;
+}

package/templates/default/src/config/auth.js

@@ -0,0 +1,61 @@
+import models from '../data/models.js';
+
+// HostPlugin.authSchema — the entry screen the engine renders before a player
+// joins (docs/ai/04-client-plugin.md § Auth screen).
+//
+// Three traps live in this file, and each one has already cost a debugging
+// session in a real game:
+//   * the container id is `fieldsId`, NOT `formId` — the engine resolves the
+//     wrong key to null and the screen dies with a TypeError on first render;
+//   * there is NO nickname field: identity comes from the lobby JWT;
+//   * the model field must be named exactly `model` — the engine reads
+//     `params.model` when it creates the participant, and any other name never
+//     reaches it.
+export default {
+  elems: {
+    authId: 'auth',
+    fieldsId: 'auth-fields',
+    errorId: 'auth-error',
+    enterId: 'auth-enter',
+    titleId: 'auth-title',
+    informsId: 'auth-informs',
+  },
+
+  texts: {
+    title: '{{GAME_TITLE}}',
+    sections: [
+      {
+        heading: 'Controls',
+        lines: [
+          { keys: 'W, S', text: 'drive' },
+          { keys: 'A, D', text: 'turn' },
+          { keys: 'J', text: 'fire' },
+          { separator: true },
+          { keys: 'C', text: 'chat' },
+          { keys: 'M', text: 'vote' },
+          { keys: 'Tab', text: 'stats', last: true },
+        ],
+      },
+    ],
+  },
+
+  params: [
+    {
+      name: 'model',
+      value: 'a1',
+      options: {
+        control: 'select',
+        label: 'Model',
+        options: Object.keys(models),
+        validator: 'isValidModel',
+        storage: 'model',
+      },
+    },
+  ],
+
+  // validators are functions: they are not serialised to the client, they run
+  // on the host when the answer comes back
+  validators: {
+    isValidModel: model => model in models,
+  },
+};

package/templates/default/src/config/client.js

@@ -0,0 +1,195 @@
+import sounds from './sounds.js';
+
+// The game half of the client CONFIG_DATA: render entities, canvases, key
+// sets, panel/stat schemas and the chat/vote texts. The engine deep-merges its
+// own defaults under this object and adds `prediction` and `snapshot` itself —
+// the host hands the result over through HostPlugin.buildClientGameConfig(),
+// so the client never loads this file directly.
+export default {
+  parts: {
+    // snapshot key (or map setId) -> the part classes built for it. A key
+    // without an entry is a black canvas: the frame arrives and the client
+    // does not know what to draw it with.
+    gameSets: {
+      a1: ['Actor'],
+      e1: ['ShotEffect'],
+      c1: ['Map'],
+    },
+
+    // part class -> canvas. This is the ONLY registration: a class listed in
+    // ClientPlugin.parts and in gameSets but missing here answers
+    // "Constructor for X not found." at the first frame that needs it.
+    entitiesOnCanvas: {
+      Map: 'vimp',
+      Actor: 'vimp',
+      ShotEffect: 'vimp',
+    },
+
+    // procedural textures, baked once per canvas at startup — the reason this
+    // package ships no images. `name` must exist in ClientPlugin.bakers and
+    // `component` names the part class that receives the result in `assets`.
+    bakedAssets: {
+      vimp: [
+        {
+          name: 'actorTexture',
+          component: 'Actor',
+          // white on purpose: one baked texture is tinted per team at runtime
+          params: { size: 32, color: 0xffffff },
+        },
+      ],
+    },
+
+    // the service pool has exactly three entries — renderer, soundManager,
+    // assetsBase. An unknown name is not an error: the part just gets
+    // undefined and draws nothing.
+    componentDependencies: {
+      soundManager: ['ShotEffect'],
+    },
+
+    sounds,
+  },
+
+  // DOM ids hidden until authentication completes; 'panel' is revealed as
+  // display: flex, everything else as display: block
+  initIdList: ['vimp', 'panel', 'chat'],
+
+  modules: {
+    canvasManager: {
+      // the engine CREATES these <canvas> elements — they are not in the HTML.
+      // baseScale '2:1' means world->screen 2 at the 1920 px design width, so
+      // the 768-unit arena is fully visible on a laptop.
+      canvases: {
+        vimp: {
+          width: 960,
+          height: 600,
+          aspectRatio: '16:10',
+          baseScale: '2:1',
+          dynamicCamera: true,
+          shakeCamera: true,
+        },
+      },
+    },
+
+    controls: {
+      // [0] spectator, [1] player. The engine switches between them by the
+      // KEYSET_DATA port; codes 9, 13, 27, 67 and 77 belong to the engine
+      // (stat, enter, escape, chat, vote) and never reach the game.
+      keySetList: [
+        {
+          78: 'nextPlayer', // n
+          80: 'prevPlayer', // p
+        },
+        // every action here must be a key of gameConfig.playerKeys, and vice
+        // versa: a name on one side only is a key that sends nothing
+        {
+          87: 'forward', // w
+          83: 'back', // s
+          65: 'left', // a
+          68: 'right', // d
+          74: 'fire', // j
+        },
+      ],
+    },
+
+    chat: {
+      params: {
+        // texts of the system message codes: the host sends 'group:index',
+        // the text lives here. Groups s/v/m/c/n are the engine's — the game
+        // owns 'g' (see src/host/systemMessages.js).
+        messages: {
+          s: [
+            'Team {0} is full. Your current team: {1}',
+            'Your team: {0}',
+            'Your new team: {0}',
+            'Your new status: spectator',
+            '{0} killed {1}',
+            '{0} joined the game',
+            '{0} left the game',
+          ],
+          v: [
+            'A vote has been created',
+            'Voting has started',
+            'Your vote has been accepted',
+            'Voting is temporarily unavailable',
+            'Vote passed',
+            'Vote failed',
+          ],
+          m: ['Current map: {0}', 'Next map: {0}'],
+          c: ['Command not found', 'Your rank: {0}'],
+          n: ['Invalid name', '{0} changed name to {1}'],
+          g: ['{0} bot(s) spawned'],
+        },
+      },
+    },
+
+    panel: {
+      // wire key (gameConfig.panel.fields[*].key) -> field name here.
+      // 't' is sent by the engine itself and MUST map to a type: 'time'
+      // field, or the round time never appears on the HUD.
+      keys: {
+        h: 'hp',
+        a: 'am',
+        // gameConfig.panel.activeKey — the active weapon, written by the
+        // engine itself; a cell of type 'weapon' takes the .active class
+        wa: 'weapon',
+        t: 'time',
+      },
+      fields: [
+        { name: 'hp', elem: 'panel-hp', type: 'bar', max: 100, blocks: 20 },
+        { name: 'am', elem: 'panel-am', type: 'value' },
+        { name: 'weapon', elem: 'panel-weapon', type: 'weapon' },
+        { name: 'time', elem: 'panel-time', type: 'time' },
+      ],
+    },
+
+    stat: {
+      params: {
+        // five columns, positionally matched to the host's `key` indexes —
+        // the engine populates exactly these and its CSS is laid out for five
+        columns: ['names', 'status', 'score', 'deaths', 'latency'],
+        heads: {
+          1: 'team1',
+          2: 'team2',
+        },
+        bodies: {
+          1: 'team1',
+          2: 'team2',
+          3: 'spectators',
+        },
+        // [columnIndex, descending]; sorting is numeric, a text column sorts
+        // as 0
+        sortList: {
+          team1: [
+            [2, true],
+            [3, false],
+          ],
+          team2: [
+            [2, true],
+            [3, false],
+          ],
+        },
+      },
+    },
+
+    vote: {
+      params: {
+        // template = [title, values?, timeOff?]; 'teams' and 'maps' are
+        // substituted by the engine with the live lists
+        templates: {
+          teamChange: ['Choose a team', 'teams', true],
+          mapChangeBySystem: ['Choose the next map'],
+          mapChangeByUser: ['{0} suggested the map: {1}', ['Yes', 'No']],
+        },
+        menu: [
+          ['teamChange', ['Switch team', 'teams']],
+          ['mapChange', ['Suggest map', 'maps']],
+        ],
+      },
+    },
+  },
+
+  // texts of the GAME_INFORM_DATA port, addressed by index
+  gameInform: {
+    list: ['{0} WINS!', 'ROUND START!', 'GAME OVER!'],
+  },
+};