create-vimp-game 0.1.0

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

@@ -0,0 +1,170 @@
+import snapshot from './snapshot.js';
+import models from '../data/models.js';
+import weapons from '../data/weapons.js';
+import maps from '../data/maps/index.js';
+
+// HostPlugin.gameConfig — the authoritative description of the game: what the
+// engine meta needs (rounds, teams, panel, stat, room form) and what it hands
+// over to the Rust core untouched (models, weapons, playerKeys, snapshot).
+//
+// The engine asserts nine paths right after import — roomDefaults.maxPlayers,
+// snapshot, parts.models, parts.weapons, parts.friendlyFire, panel.fields,
+// playerKeys, teams, spectatorTeam — plus `spectatorTeam` being a key of
+// `teams`. Everything else is read lazily, which is why a typo elsewhere
+// surfaces as a black canvas rather than an error: run `npm run
+// check:contract` after every change here.
+export default {
+  title: '{{GAME_TITLE}}',
+
+  parts: {
+    models,
+    weapons,
+    // overridable per room through the lobby form below
+    friendlyFire: false,
+  },
+
+  // the binary protocol layout; the engine passes it to both cores and to the
+  // client, knowing nothing about the meaning of a field
+  snapshot,
+
+  // engine event -> name in the sound registry (src/config/sounds.js).
+  // All five keys exist so that filling one in is editing a value, not
+  // remembering the vocabulary; an unmapped cue is simply not sent, and the
+  // template ships only the two sounds a match cannot do without.
+  soundCues: {
+    roundStart: null,
+    victory: null,
+    defeat: null,
+    frag: null,
+    death: 'death',
+  },
+
+  // the vote a player is offered right after their first frame: without it a
+  // joining participant stays a spectator with no way to ask for a team
+  initialVote: 'teamChange',
+
+  maps,
+  currentMap: 'arena',
+  mapScale: 1,
+  // fallback for a map without its own setId
+  mapSetId: 'c1',
+  mapsInVote: 1,
+
+  // starting profile of a player with no saved record on the auth service.
+  // The engine keeps it as opaque JSON — the game is the only reader
+  playerState: {
+    defaultState: { kills: 0, shots: 0 },
+  },
+
+  spectatorTeam: 'spectators',
+  teams: {
+    team1: 1,
+    team2: 2,
+    spectators: 3,
+  },
+
+  // bots: the name prefix the engine numbers, and the model they spawn with
+  scripted: {
+    namePrefix: 'Bot',
+    defaultModel: 'a1',
+  },
+
+  // Action name -> bit and kind. The engine ships this table into both cores
+  // verbatim and never interprets it: `type: 1` (one-shot) is a CONVENTION
+  // core/src/actor.rs implements — `down` arms the bit, exactly one fixed step
+  // consumes it, `up` is ignored. Every name here must have a key in
+  // keySetList[1] (src/config/client.js) or it can never be pressed.
+  playerKeys: {
+    forward: { key: 1 << 0 },
+    back: { key: 1 << 1 },
+    left: { key: 1 << 2 },
+    right: { key: 1 << 3 },
+    fire: { key: 1 << 4, type: 1 },
+  },
+
+  // HUD, host half: `key` is the short wire key, `value` the starting amount —
+  // and the same number is what the core hands the actor as health and ammo.
+  // `health` is read by the core by that exact name; every other key must name
+  // a weapon (the core refuses to boot otherwise).
+  // The key 't' is reserved by the engine for the round time — never declare it.
+  panel: {
+    fields: {
+      health: { key: 'h', value: 100 },
+      e1: { key: 'a', value: 100 },
+    },
+    // Cell showing the active weapon. It is NOT a field: the engine writes
+    // the weapon name into it whenever the core reports a change, and it does
+    // so unconditionally — leaving this null makes the panel send the literal
+    // key 'null' to every client, which nothing on the other side can render.
+    activeKey: 'wa',
+  },
+
+  // Statistics table, host half. The engine writes exactly five names —
+  // name, status, score, deaths, latency — and nothing else; `key` is the
+  // column index on the wire, matched positionally by src/config/client.js.
+  stat: {
+    name: {
+      key: 0,
+      bodyMethod: '=',
+      headSync: true,
+      headMethod: '#',
+    },
+    status: {
+      key: 1,
+      bodyMethod: '=',
+      bodyValue: '',
+      headValue: '',
+    },
+    score: {
+      key: 2,
+      bodyMethod: '+',
+      bodyValue: 0,
+      headMethod: '+',
+      headValue: 0,
+    },
+    deaths: {
+      key: 3,
+      bodyMethod: '+',
+      bodyValue: 0,
+      headMethod: '+',
+      headValue: 0,
+    },
+    latency: {
+      key: 4,
+      bodyMethod: '=',
+    },
+  },
+
+  roomDefaults: {
+    maxPlayers: 8,
+  },
+
+  // The lobby "create server" form. The names must be exactly the keys the
+  // host honours (maxPlayers, map, roundTime, mapTime, friendlyFire) —
+  // anything else is accepted by the form and silently dropped. Numeric
+  // bounds are injected as `regExp` by scripts/build-game-manifest.js.
+  roomForm: [
+    {
+      name: 'maxPlayers',
+      control: 'text',
+      label: 'Max players',
+      numeric: true,
+    },
+    {
+      name: 'roundTime',
+      control: 'text',
+      label: 'Round time',
+      unit: 's',
+      numeric: true,
+    },
+    {
+      name: 'mapTime',
+      control: 'text',
+      label: 'Map time',
+      unit: 's',
+      numeric: true,
+    },
+    { name: 'friendlyFire', control: 'checkbox', label: 'Friendly fire' },
+    { name: 'map', control: 'select', label: 'Map', source: 'maps' },
+  ],
+};

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

@@ -0,0 +1,70 @@
+// The wire layout of the game (gameConfig.snapshot): one block per entity
+// kind. The engine never learns what a field means — only how many bytes it
+// takes and whether it interpolates (docs/ai/06-snapshot-protocol.md).
+//
+// The KEY of a block is not free: the Rust core names the actor block after
+// the model (`src/data/models.js`) and the tracer block after the weapon
+// (`src/data/weapons.js`) that produced it, so `a1` and `e1` below are those
+// two names. Renaming a model or a weapon renames its block. The third key is
+// the `setId` of the map — see the comment on `c1`.
+//
+// The field ORDER is positionally bound to `core/src/game.rs` — `ActorRow`
+// and `TracerRow` push their values in exactly this sequence. Nothing
+// validates the correspondence: swapping two entries here without swapping
+// them there produces garbage instead of an error.
+export default {
+  // the actor: continuous state, so `hot` — the only class the render-rate
+  // buffer carries, and it carries only indexed8 / indexedNoNull8
+  a1: {
+    id: 1,
+    kind: 'indexed8',
+    class: 'hot',
+    fields: [
+      { name: 'x', ty: 'f32', interp: 'lerp' },
+      { name: 'y', ty: 'f32', interp: 'lerp' },
+      { name: 'angle', ty: 'f32', interp: 'lerpAngle' },
+      // velocity is not interpolated: the client only reads it to tell a
+      // moving actor from a standing one, and a lerped copy of a value that
+      // already changes every frame buys nothing
+      { name: 'vx', ty: 'f32' },
+      { name: 'vy', ty: 'f32' },
+      { name: 'health', ty: 'u8' },
+      { name: 'team', ty: 'u8' },
+    ],
+  },
+
+  // the shot: an anonymous one-shot event, so `list16` + class 'event' —
+  // a frame carrying it goes over the reliable channel
+  e1: {
+    id: 2,
+    kind: 'list16',
+    class: 'event',
+    fields: [
+      { name: 'startX', ty: 'f32' },
+      { name: 'startY', ty: 'f32' },
+      { name: 'endX', ty: 'f32' },
+      { name: 'endY', ty: 'f32' },
+      { name: 'wasHit', ty: 'u8' },
+      // the author id is LAST by convention: the client drops the
+      // authoritative twin of a tracer it already drew by this field
+      { name: 'author', ty: 'u8' },
+    ],
+  },
+
+  // The movable bodies of the map (`physicsDynamic`). This block belongs to
+  // the ENGINE: it is packed by the engine half of the core, under the map's
+  // `setId` as the key, and its row is fixed at [x, y, angle]. The template
+  // has no dynamic bodies, and the block is still mandatory — the packer
+  // refuses a key it does not know, and `npm run sim` dies on the first tick
+  // with "unknown snapshot key 'c1'".
+  c1: {
+    id: 3,
+    kind: 'indexedNoNull8',
+    class: 'hot',
+    fields: [
+      { name: 'x', ty: 'f32', interp: 'lerp' },
+      { name: 'y', ty: 'f32', interp: 'lerp' },
+      { name: 'angle', ty: 'f32', interp: 'lerpAngle' },
+    ],
+  },
+};

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

@@ -0,0 +1,17 @@
+// Sound registry of the client. Every entry must ship as a webm + mp3 PAIR:
+// the client walks codecList and takes the first codec the browser supports,
+// so a missing .mp3 breaks Safari only — i.e. never for the author.
+//
+// `file` is the base name in dist/sounds/ (assets/sounds/ or, after
+// `npm run audio:process`, build/sounds/). Do NOT set `path`: the engine
+// overwrites it with `${assetsBase}sounds/`, and a hand-written one only
+// works until the game is served from the lobby.
+const sounds = {
+  shot: { file: 'shot', priority: 100, volume: 0.4 },
+  death: { file: 'death', priority: 150, volume: 0.4 },
+};
+
+export default {
+  codecList: ['webm', 'mp3'],
+  sounds,
+};

package/templates/default/src/data/maps/arena.js

@@ -0,0 +1,69 @@
+// The single map of the game: a walled rectangle with four pillars, drawn
+// procedurally by `src/client/parts/Map.js` — no `spriteSheet`, so the package
+// ships no images at all (docs/ai/07-maps-and-assets.md).
+//
+// `map` is the grid of tiles (0 — empty, 1 — wall), `step` its cell size in
+// world units; `physicsStatic` lists the tile values the core turns into
+// colliders, and `layers` maps a render layer to the tile values drawn on it —
+// WITHOUT it the client builds no map parts at all (the engine derives the
+// static map data from `layers`, one entry per layer).
+//
+// `respawns` holds one entry per playing team, and the length of a list is the
+// hard capacity of that team on this map: the engine hands the points out
+// sequentially and refuses the next joiner when they run out. Keep every
+// point on an EMPTY cell — the engine does not check, and an actor spawned
+// inside a wall is stuck there for the round.
+const W = 1;
+
+export default {
+  // which parts.gameSets entry builds this map (src/config/client.js)
+  setId: 'c1',
+  scale: 1,
+  step: 64,
+  physicsStatic: [W],
+  physicsDynamic: [],
+
+  // render layer -> tile values drawn on it
+  layers: { 1: [W] },
+
+  map: [
+    [W, W, W, W, W, W, W, W, W, W, W, W],
+    [W, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, W],
+    [W, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, W],
+    [W, 0, 0, W, W, 0, 0, W, W, 0, 0, W],
+    [W, 0, 0, W, 0, 0, 0, 0, W, 0, 0, W],
+    [W, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, W],
+    [W, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, W],
+    [W, 0, 0, W, 0, 0, 0, 0, W, 0, 0, W],
+    [W, 0, 0, W, W, 0, 0, W, W, 0, 0, W],
+    [W, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, W],
+    [W, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, W],
+    [W, W, W, W, W, W, W, W, W, W, W, W],
+  ],
+
+  // [x, y, angleDeg] — DEGREES, not radians: the core converts them itself.
+  // The two teams start along the opposite short walls, in the two columns
+  // that are empty on every row (x = 96/160 and x = 608/672).
+  respawns: {
+    team1: [
+      [96, 96, 0],
+      [96, 224, 0],
+      [96, 352, 0],
+      [96, 480, 0],
+      [160, 160, 0],
+      [160, 288, 0],
+      [160, 416, 0],
+      [160, 544, 0],
+    ],
+    team2: [
+      [672, 96, 180],
+      [672, 224, 180],
+      [672, 352, 180],
+      [672, 480, 180],
+      [608, 160, 180],
+      [608, 288, 180],
+      [608, 416, 180],
+      [608, 544, 180],
+    ],
+  },
+};

package/templates/default/src/data/maps/index.js

@@ -0,0 +1,7 @@
+import arena from './arena.js';
+
+// Map registry: the key is the map name the lobby shows and the file name
+// scripts/export-maps.js writes into dist/maps/<name>.json.
+export default {
+  arena,
+};

package/templates/default/src/data/models.js

@@ -0,0 +1,39 @@
+// Actor classes of the game (gameConfig.parts.models). The engine passes this
+// object verbatim into BOTH cores — the authoritative one and the predictor —
+// so every number here is gameplay, not decoration (core/src/config.rs,
+// struct ActorConfig).
+//
+// The key is the model name: it is the snapshot block key of the actor
+// (`src/config/snapshot.js`), the value of the `model` field of the auth form
+// and `gameConfig.scripted.defaultModel`. One class is enough to play; adding
+// a second one is adding a key here — nothing in the core is hard-coded to a
+// name.
+export default {
+  a1: {
+    // key of `src/data/weapons.js` the actor spawns with
+    currentWeapon: 'e1',
+
+    // diameter of the body in world units (the collider is a ball of size/2)
+    size: 32,
+
+    // units per second; the reverse cap is deliberately lower — an actor that
+    // backs away as fast as it charges makes every duel a stalemate
+    maxSpeed: 220,
+    maxReverseSpeed: 110,
+
+    // speed gained per second while a drive key is held / lost with none
+    acceleration: 520,
+    braking: 700,
+
+    // radians per second
+    turnSpeed: 3.2,
+
+    // Rapier collider parameters. restitution 0: actors that bounce off each
+    // other turn a crowd into a pinball table
+    fixture: {
+      density: 1,
+      friction: 0.2,
+      restitution: 0,
+    },
+  },
+};

package/templates/default/src/data/weapons.js

@@ -0,0 +1,37 @@
+// Weapons of the game (gameConfig.parts.weapons) — the same object reaches
+// the authoritative core and the predictor (core/src/config.rs, struct
+// WeaponConfig).
+//
+// The key is the weapon name, and the core names the tracer snapshot block
+// after it: `e1` here is the `e1` block of `src/config/snapshot.js`. It is
+// also the panel field holding the ammo (`src/config/game.js`) — the core
+// validates that pairing at construction and refuses to boot without it.
+export default {
+  e1: {
+    // hitscan: the ray is cast on the same step the trigger is consumed, so
+    // there is no projectile body and no contact handling in the core
+    damage: 25,
+
+    // ray length in world units — a bit less than the long side of the arena,
+    // so the map itself limits the duel range
+    range: 620,
+
+    // SECONDS between shots (the client predictor multiplies by 1000 itself)
+    fireRate: 0.35,
+
+    // radians of random spread; it goes through the engine Rng on both sides,
+    // never through Math.random — determinism is what makes a replay and a
+    // host handoff reproduce the same match
+    spread: 0.03,
+
+    // ammo spent per shot; the pool is the panel value of this key
+    consumption: 1,
+
+    // the victim's canvas shakes on a hit (needs shakeCamera on the canvas,
+    // `src/config/client.js`)
+    cameraShake: {
+      intensity: 4,
+      duration: 200,
+    },
+  },
+};

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

@@ -0,0 +1,142 @@
+// The bot manager: the game half of "scripted participants". The engine calls
+// exactly five methods on it — createMap, getCountsPerTeam, createScripted,
+// removeScripted, removeOneForHuman — and never anything else
+// (docs/ai/03-host-plugin.md § The `scripted` module contract).
+//
+// It holds no state that a host handoff may not lose: a restored room
+// re-creates the map and respawns everyone, and this object is rebuilt from
+// scratch. Worker-safe.
+export default class ScriptedManager {
+  constructor({ participants, coreAdapter, panel, stat, scripted }) {
+    this._participants = participants;
+    this._coreAdapter = coreAdapter;
+    this._panel = panel;
+    this._stat = stat;
+
+    // `scripted` in the context is gameConfig.scripted — a config object, not
+    // a module
+    this._model = scripted.defaultModel;
+    this._respawns = null;
+  }
+
+  // called on every map load, with the map data ALREADY scaled
+  createMap(mapData) {
+    this._respawns = mapData.respawns;
+  }
+
+  // { teamName: count } — the engine balances the teams by it
+  getCountsPerTeam() {
+    const counts = {};
+
+    for (const participant of this._participants.getScripted()) {
+      counts[participant.team] = (counts[participant.team] ?? 0) + 1;
+    }
+
+    return counts;
+  }
+
+  // returns how many were actually created — the caller reports that number,
+  // not the number asked for
+  createScripted(count, teamName = null) {
+    if (!this._respawns) {
+      return 0;
+    }
+
+    const playableTeams = this._participants.getPlayableTeams();
+    let created = 0;
+
+    for (let i = 0; i < count; i += 1) {
+      if (this._participants.isFull) {
+        break;
+      }
+
+      // no team asked for: fill the emptiest one that still has room, so a
+      // room of bots stays balanced without anyone steering it. Trying only
+      // the emptiest team would stall the whole loop once that one team is
+      // out of respawn points while its neighbour still has some.
+      const targetTeam = teamName ?? this._pickTeam(playableTeams);
+
+      // team sizes only grow inside this loop, so «no room» is final: the
+      // remaining iterations would do nothing but burn `count`
+      if (!targetTeam || !this._hasRoom(targetTeam)) {
+        break;
+      }
+
+      const gameId = this._participants.createScripted({
+        team: targetTeam,
+        model: this._model,
+      });
+      const participant = this._participants.get(gameId);
+
+      // a bot has no socket, so the engine never writes its latency cell —
+      // whatever is passed here is what the table shows for the whole match
+      this._stat.addUser(gameId, participant.teamId, {
+        name: participant.name,
+        status: 'dead',
+        latency: 'BOT',
+      });
+      this._panel.addUser(gameId);
+
+      created += 1;
+    }
+
+    return created;
+  }
+
+  // the number of respawn points is the hard capacity of a team: past it the
+  // engine has nowhere to put the actor
+  _hasRoom(teamName) {
+    const respawns = this._respawns[teamName];
+
+    return Boolean(
+      respawns && this._participants.getTeamSize(teamName) < respawns.length,
+    );
+  }
+
+  _pickTeam(playableTeams) {
+    return (
+      [...playableTeams]
+        .sort(
+          (a, b) =>
+            this._participants.getTeamSize(a) -
+            this._participants.getTeamSize(b),
+        )
+        .find(team => this._hasRoom(team)) ?? null
+    );
+  }
+
+  removeScripted(teamName = null) {
+    const scripted = this._participants.getScripted();
+    const toRemove = teamName
+      ? scripted.filter(participant => participant.team === teamName)
+      : scripted;
+
+    toRemove.forEach(participant => this._remove(participant.gameId));
+  }
+
+  // a human needs a slot in a full team: free one and say whether it worked
+  removeOneForHuman(teamName) {
+    for (const participant of this._participants.getScripted()) {
+      if (participant.team === teamName) {
+        this._remove(participant.gameId);
+
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  _remove(gameId) {
+    const participant = this._participants.get(gameId);
+
+    if (!participant || !participant.isScripted) {
+      return;
+    }
+
+    this._stat.removeUser(gameId, participant.teamId);
+    this._panel.removeUser(gameId);
+    this._coreAdapter.removePlayer(gameId);
+    this._participants.remove(gameId);
+  }
+}

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

@@ -0,0 +1,12 @@
+import ScriptedManager from './ScriptedManager.js';
+
+// Factory of the game's host modules (HostPlugin.createModules). The engine
+// reads exactly ONE key off the result — `scripted`; anything else returned
+// here is never called by it.
+//
+// The context is { participants, coreAdapter, panel, stat, chat,
+// socketManager, scripted } — there is no timerManager and no
+// voteCoordinator in it (those exist only in a chat-command context).
+export default function createModules(ctx) {
+  return { scripted: new ScriptedManager(ctx) };
+}

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

@@ -0,0 +1,56 @@
+import { ENGINE_API_VERSION } from 'vimp-engine/config/opcodes.js';
+import gameConfig from '../config/game.js';
+import authSchema from '../config/auth.js';
+import clientConfig from '../config/client.js';
+import createModules from './createModules.js';
+import spawnCommand from './spawnCommand.js';
+import systemMessages from './systemMessages.js';
+import { isNodeCore, loadNodeCore, loadWebCore } from './nodeCore.js';
+
+// HostPlugin — the game half of the authoritative match, Worker-safe: no DOM,
+// no PixiJS, no Node globals. Default export of the host entry
+// (vite build --mode host); the engine loads it by GameManifest.entries.host.
+//
+// Every field below is dereferenced by the engine without a guard, so a
+// missing one is a TypeError far from its cause (docs/ai/03-host-plugin.md).
+export default {
+  id: '{{GAME_ID}}',
+  // never a literal: a number written by hand agrees with the engine on the
+  // day it is typed and silently disagrees after the next release
+  engineApi: ENGINE_API_VERSION,
+
+  // wasmUrl comes from the manifest: init() loads by an explicit URL instead
+  // of the glue module's own import.meta.url resolution, which does not
+  // survive inside a Worker
+  async createCore(coreConfigJson, { wasmUrl } = {}) {
+    if (isNodeCore(wasmUrl)) {
+      const node = await loadNodeCore(wasmUrl);
+
+      return new node.GameCore(coreConfigJson);
+    }
+
+    const { default: init, GameCore } = await loadWebCore();
+
+    // module_or_path — the wasm-bindgen init() option name
+    await init({ module_or_path: wasmUrl });
+
+    return new GameCore(coreConfigJson);
+  },
+
+  gameConfig,
+  authSchema,
+
+  // REQUIRED array — the engine iterates it unguarded; `[]` for no commands
+  chatCommands: [spawnCommand],
+
+  // merged into the engine chat registry by a blind Object.assign: a code in
+  // an engine group would overwrite an engine message without a word
+  systemMessages,
+
+  // the engine calls it and reads exactly one key off the result: `scripted`
+  createModules,
+
+  // the client half of the config has no file of its own on the client: the
+  // host builds it and sends it over
+  buildClientGameConfig: () => clientConfig,
+};

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

@@ -0,0 +1,23 @@
+// Loading the WASM core, both shapes of it. `wasmUrl` arrives from the
+// manifest and differs between the two runtimes (docs/ai/03-host-plugin.md):
+//
+//   browser — the hashed `.wasm` asset (entries.wasm): the `--target web`
+//             glue is imported and `init()` fetches the binary by that URL;
+//   Node    — a file: URL of the `--target nodejs` glue (entries.wasmNode),
+//             used by `npm run sim`: that build pulls the wasm in itself, and
+//             fetch() cannot read file: URLs anyway.
+//
+// Both halves of the plugin branch through THIS file: a headless run that used
+// a different core than the browser would prove nothing.
+//
+// The web glue is loaded by a dynamic import on purpose. As a static one it
+// would make `src/host/index.js` unimportable in Node until `npm run
+// core:build` has run — and with it `npm run check:contract` and every unit
+// test of the host half.
+
+export const isNodeCore = wasmUrl => (wasmUrl ?? '').endsWith('.js');
+
+// @vite-ignore: the path is a runtime value, Vite must not try to resolve it
+export const loadNodeCore = wasmUrl => import(/* @vite-ignore */ wasmUrl);
+
+export const loadWebCore = () => import('../../core/pkg-web/{{CRATE_SNAKE}}.js');

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

@@ -0,0 +1,32 @@
+// Chat command '/spawn <count>' — fills the room with bots without a vote.
+// It is also what `npm run dev` uses to get a match going (startupCommands in
+// dev/main.js).
+//
+// The name must not collide with the engine's own commands (/name, /nr,
+// /timeleft, /mapname, /rank): those are matched by a switch BEFORE the game
+// registry, so a same-named command registers fine and never fires.
+export default {
+  name: '/spawn',
+
+  // ctx = { participants, chat, scripted, roundManager, voteCoordinator,
+  //         timerManager, playerDataSync, teams, spectatorTeam, spectatorId,
+  //         isDevMode }
+  handler(ctx, gameId, args) {
+    // the argument is whatever a player typed: '/spawn -3' must not mean
+    // zero bots, and '/spawn 1e9' must not mean a billion loop iterations
+    const { maxPlayers } = ctx.participants;
+    const requested = Math.max(1, Math.trunc(Number(args[0])) || 1);
+    const count = maxPlayers > 0 ? Math.min(requested, maxPlayers) : requested;
+    const created = ctx.scripted.createScripted(count);
+
+    // the code is the game's own (src/host/systemMessages.js); the TEXT lives
+    // on the client, in modules.chat.params.messages
+    ctx.chat.pushSystem('BOTS_SPAWNED', [created]);
+
+    // restart the round so the fresh bots enter the world at once instead of
+    // waiting out the current one as corpses — pointless if nobody was added
+    if (created > 0) {
+      ctx.roundManager.initiateNewRound();
+    }
+  },
+};