create-vimp-game 0.1.0

package/templates/default/core/src/lib.rs

@@ -0,0 +1,118 @@
+// {{GAME_TITLE}} — the game simulation (movement, hitscan, damage) on top of
+// vimp-engine-core. Compiles to WASM for the host Worker and the browser, and
+// to a Node build for tests and the headless runner (`npm run core:build`).
+//
+// Two exported classes: GameCore — the authoritative match in the host
+// Worker, ClientCore — the per-player prediction in the tab. Everything the
+// engine needs from them is generated by the two ABI macros below; only
+// `new` and the game-specific client methods are hand-written.
+
+use wasm_bindgen::prelude::*;
+
+pub mod actor;
+pub mod body_tag;
+pub mod client;
+pub mod config;
+pub mod game;
+pub mod motion;
+
+use client::ClientState;
+use config::{RootClientConfig, RootConfig};
+use game::GameState;
+use vimp_engine_core::snapshot::SnapshotPacker;
+
+/// Public ABI of the core for the JS host (Worker / Node test harness).
+/// The field names `state` and `packer` are a contract: the macro looks them
+/// up literally.
+#[wasm_bindgen]
+pub struct GameCore {
+    state: GameState,
+    packer: SnapshotPacker,
+}
+
+#[wasm_bindgen]
+impl GameCore {
+    /// Builds the core from the JSON config `{engine: {...}, game: {...}}`
+    /// assembled by the engine from src/config/.
+    #[wasm_bindgen(constructor)]
+    pub fn new(config_json: &str) -> Result<GameCore, JsError> {
+        let cfg: RootConfig =
+            serde_json::from_str(config_json).map_err(|e| JsError::new(&e.to_string()))?;
+
+        // both checks belong on the construction boundary: a duplicate block
+        // id or a panel key without a weapon corrupts frames silently
+        cfg.engine.snapshot.validate().map_err(|e| JsError::new(&e))?;
+        cfg.game.validate().map_err(|e| JsError::new(&e))?;
+
+        let packer = SnapshotPacker::new(cfg.engine.snapshot.clone());
+
+        Ok(GameCore {
+            state: GameState::new(cfg.engine, &cfg.game),
+            packer,
+        })
+    }
+}
+
+vimp_engine_core::export_game_core_abi!(GameCore);
+
+impl GameCore {
+    /// Access to the simulation for native tests (not exported to JS).
+    pub fn state(&self) -> &GameState {
+        &self.state
+    }
+
+    pub fn state_mut(&mut self) -> &mut GameState {
+        &mut self.state
+    }
+}
+
+/// Client half of the core: interpolation of snapshots, prediction of the
+/// local actor and the locally spawned tracer. Lives in the main thread of
+/// the tab.
+#[wasm_bindgen]
+pub struct ClientCore {
+    state: ClientState,
+}
+
+#[wasm_bindgen]
+impl ClientCore {
+    /// Builds the client core from `{engine: {...}, game: {...}}` assembled
+    /// by the engine from CONFIG_DATA.
+    #[wasm_bindgen(constructor)]
+    pub fn new(config_json: &str) -> Result<ClientCore, JsError> {
+        let cfg: RootClientConfig =
+            serde_json::from_str(config_json).map_err(|e| JsError::new(&e.to_string()))?;
+
+        cfg.engine.snapshot.validate().map_err(|e| JsError::new(&e))?;
+
+        Ok(ClientCore {
+            state: ClientState::new(cfg.engine, &cfg.game),
+        })
+    }
+
+    // ***** game-specific methods: called only from ClientPlugin.hooks ***** //
+
+    /// Local visual shot; the gates (cooldown, ammo, alive) are inside.
+    /// Returns the spawn JSON for the renderer or nothing.
+    pub fn try_fire(&mut self, local_now: f64) -> Option<String> {
+        self.state.try_action(local_now)
+    }
+
+    /// Model of the local actor (known at authorization).
+    pub fn set_model(&mut self, model: &str) {
+        self.state.set_model(model);
+    }
+
+    /// Authoritative panel state (PANEL_DATA).
+    pub fn sync_panel(&mut self, panel_json: &str) {
+        self.state.sync_panel(panel_json);
+    }
+
+    /// Cycles the active item; the template has one weapon, so this is the
+    /// place a game with an arsenal grows into.
+    pub fn cycle_weapon(&mut self, back: bool) {
+        self.state.cycle_item(back);
+    }
+}
+
+vimp_engine_core::export_client_core_abi!(ClientCore);

package/templates/default/core/src/motion.rs

@@ -0,0 +1,126 @@
+//! The ONLY source of movement math: pure functions, no Rapier bodies and no
+//! world state. Both halves call them — the authoritative `Actor::update`
+//! (which then writes the result onto the body) and the client `Predictor`
+//! (which integrates it without collisions). Every change here is a change to
+//! both halves at once; re-run `mod parity` in `client/predictor.rs` after it.
+//!
+//! The model is deliberately inertia-free: the velocity is written directly
+//! from the held keys instead of being accumulated by impulses, so the
+//! prediction parity is exact in open space and only collisions can pull the
+//! two halves apart.
+
+use rapier2d::prelude::Vector;
+use vimp_engine_core::physics::normalize_angle;
+
+use crate::config::ActorConfig;
+
+/// Movement keys held on this step.
+#[derive(Clone, Copy, Default)]
+pub struct MoveInput {
+    pub forward: bool,
+    pub back: bool,
+    pub left: bool,
+    pub right: bool,
+}
+
+/// New facing angle (radians, normalised to [-PI, PI]).
+pub fn step_angle(angle: f32, input: MoveInput, model: &ActorConfig, dt: f32) -> f32 {
+    let mut delta = 0.0;
+
+    if input.left {
+        delta -= model.turn_speed * dt;
+    }
+
+    if input.right {
+        delta += model.turn_speed * dt;
+    }
+
+    normalize_angle(angle + delta)
+}
+
+/// New signed speed along the facing direction: accelerate while a drive key
+/// is held, brake towards zero otherwise.
+pub fn step_speed(speed: f32, input: MoveInput, model: &ActorConfig, dt: f32) -> f32 {
+    if input.forward && !input.back {
+        (speed + model.acceleration * dt).min(model.max_speed)
+    } else if input.back && !input.forward {
+        (speed - model.acceleration * dt).max(-model.max_reverse_speed)
+    } else if speed > 0.0 {
+        (speed - model.braking * dt).max(0.0)
+    } else {
+        (speed + model.braking * dt).min(0.0)
+    }
+}
+
+/// Velocity vector of an actor facing `angle` and moving at `speed`.
+pub fn velocity(angle: f32, speed: f32) -> Vector {
+    Vector::new(angle.cos() * speed, angle.sin() * speed)
+}
+
+/// Muzzle point: the edge of the body along the facing direction. The client
+/// replicates it for the locally predicted tracer — keep the two in sync.
+pub fn muzzle(x: f32, y: f32, angle: f32, model: &ActorConfig) -> Vector {
+    let offset = model.size * 0.6;
+
+    Vector::new(x + angle.cos() * offset, y + angle.sin() * offset)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn model() -> ActorConfig {
+        serde_json::from_value(serde_json::json!({
+            "currentWeapon": "w1",
+            "size": 32.0,
+            "maxSpeed": 200.0,
+            "maxReverseSpeed": 100.0,
+            "acceleration": 400.0,
+            "braking": 600.0,
+            "turnSpeed": 3.0,
+            "fixture": { "density": 1.0, "friction": 0.2, "restitution": 0.0 }
+        }))
+        .unwrap()
+    }
+
+    #[test]
+    fn speed_is_capped_by_the_model() {
+        let mut speed = 0.0;
+        let input = MoveInput {
+            forward: true,
+            ..MoveInput::default()
+        };
+
+        for _ in 0..600 {
+            speed = step_speed(speed, input, &model(), 1.0 / 120.0);
+        }
+
+        assert_eq!(speed, 200.0);
+    }
+
+    #[test]
+    fn braking_stops_exactly_at_zero() {
+        let mut speed = 50.0;
+
+        for _ in 0..600 {
+            speed = step_speed(speed, MoveInput::default(), &model(), 1.0 / 120.0);
+        }
+
+        assert_eq!(speed, 0.0);
+    }
+
+    #[test]
+    fn angle_stays_normalised() {
+        let mut angle = 0.0;
+        let input = MoveInput {
+            right: true,
+            ..MoveInput::default()
+        };
+
+        for _ in 0..1000 {
+            angle = step_angle(angle, input, &model(), 1.0 / 120.0);
+        }
+
+        assert!(angle.abs() <= core::f32::consts::PI);
+    }
+}

package/templates/default/core/tests/sim.rs

@@ -0,0 +1,351 @@
+// Integration tests of the simulation: they drive the real `GameCore` ABI —
+// the very methods the host Worker calls — instead of the internals, so a
+// change that breaks the host is caught here and not in the browser.
+
+use vimp_engine_core::events::CoreEvent;
+use {{CRATE_SNAKE}}::GameCore;
+
+const DT: f32 = 1.0 / 120.0;
+
+/// Core config — a mirror of src/config/game.js + src/data/. The same flat
+/// object is put into both halves of `{engine, game}`: each side ignores the
+/// fields that are not its own.
+fn config_json() -> String {
+    let flat = flat_config_json();
+
+    serde_json::json!({ "engine": flat.clone(), "game": flat }).to_string()
+}
+
+fn flat_config_json() -> serde_json::Value {
+    serde_json::json!({
+        "timeStep": DT,
+        "friendlyFire": false,
+        "mapScale": 1,
+        "mapSetId": "m1",
+        "models": {
+            "a1": {
+                "currentWeapon": "w1",
+                "size": 32.0,
+                "maxSpeed": 200.0,
+                "maxReverseSpeed": 100.0,
+                "acceleration": 400.0,
+                "braking": 600.0,
+                "turnSpeed": 3.0,
+                "fixture": { "density": 1.0, "friction": 0.2, "restitution": 0.0 }
+            }
+        },
+        "weapons": {
+            "w1": {
+                "damage": 25.0,
+                "range": 600.0,
+                "fireRate": 0.05,
+                "spread": 0,
+                "consumption": 1,
+                "cameraShake": { "intensity": 12, "duration": 150 }
+            }
+        },
+        "playerKeys": {
+            "forward": { "key": 1 },
+            "back": { "key": 2 },
+            "left": { "key": 4 },
+            "right": { "key": 8 },
+            "fire": { "key": 16, "type": 1 }
+        },
+        "panel": {
+            "health": { "value": 100 },
+            "w1": { "value": 30 }
+        },
+        "snapshot": {
+            "version": 3,
+            "port": 5,
+            "keys": {
+                "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" },
+                    { "name": "vx", "ty": "f32", "interp": "lerp" },
+                    { "name": "vy", "ty": "f32", "interp": "lerp" },
+                    { "name": "health", "ty": "u8" },
+                    { "name": "team", "ty": "u8" }
+                ] },
+                "w1": { "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" },
+                    { "name": "shooterId", "ty": "u8" }
+                ] },
+                "m1": { "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" }
+                ] }
+            }
+        },
+        "seed": 42
+    })
+}
+
+/// A walled 20x20 room, cell 32 — the shape of src/data/maps/arena.js.
+fn map_json() -> String {
+    let mut grid: Vec<Vec<i32>> = vec![vec![0; 20]; 20];
+
+    for (y, row) in grid.iter_mut().enumerate() {
+        for (x, cell) in row.iter_mut().enumerate() {
+            if y == 0 || y == 19 || x == 0 || x == 19 {
+                *cell = 1;
+            }
+        }
+    }
+
+    serde_json::json!({
+        "setId": "m1",
+        "scale": 1,
+        "step": 32,
+        "map": grid,
+        "physicsStatic": [1],
+        "physicsDynamic": [],
+        "respawns": {
+            "team1": [[100.0, 100.0, 0.0], [100.0, 200.0, 0.0]],
+            "team2": [[500.0, 100.0, 180.0], [500.0, 200.0, 180.0]]
+        }
+    })
+    .to_string()
+}
+
+fn make_core() -> GameCore {
+    GameCore::new(&config_json()).unwrap()
+}
+
+fn steps(core: &mut GameCore, count: usize) {
+    for _ in 0..count {
+        core.step(DT);
+    }
+}
+
+fn events(core: &mut GameCore) -> Vec<CoreEvent> {
+    serde_json::from_str(&core.take_events()).unwrap()
+}
+
+/// One broadcast frame as bytes — the unit the determinism tests compare.
+fn frame(core: &mut GameCore, seq: u32) -> Vec<u8> {
+    core.pack_body().unwrap();
+    core.pack_frame(1000.0 + seq as f64, seq, false, 0.0, 0.0, false, None, -1);
+
+    core.frame_bytes()
+}
+
+/// Kills `victim` with shots from `shooter` (both must already exist and see
+/// each other).
+fn kill(core: &mut GameCore, shooter: u32, victim: u32) {
+    for _ in 0..8 {
+        if !core.is_alive(victim) {
+            break;
+        }
+
+        core.apply_input(shooter, 1, "down", "fire");
+        steps(core, 8);
+    }
+}
+
+#[test]
+fn spawns_actors_at_the_respawns_of_their_team() {
+    let mut core = make_core();
+
+    core.load_map(&map_json()).unwrap();
+
+    let info: serde_json::Value = serde_json::from_str(&core.map_info()).unwrap();
+    let team1 = info["respawns"]["team1"].as_array().unwrap();
+    let team2 = info["respawns"]["team2"].as_array().unwrap();
+
+    assert_eq!(team1.len(), 2);
+    assert_eq!(team2.len(), 2);
+
+    let spawn = |core: &mut GameCore, id: u32, team: u8, point: &serde_json::Value| {
+        let x = point[0].as_f64().unwrap() as f32;
+        let y = point[1].as_f64().unwrap() as f32;
+        let angle = point[2].as_f64().unwrap() as f32;
+
+        core.spawn_actor(id, "a1", team, x, y, angle).unwrap();
+    };
+
+    spawn(&mut core, 1, 1, &team1[0]);
+    spawn(&mut core, 2, 2, &team2[0]);
+
+    assert_eq!(core.position_of(1), vec![100.0, 100.0]);
+    assert_eq!(core.position_of(2), vec![500.0, 100.0]);
+
+    // [id, team, x, y] per alive actor
+    assert_eq!(core.alive_players(), vec![1.0, 1.0, 100.0, 100.0, 2.0, 2.0, 500.0, 100.0]);
+}
+
+#[test]
+fn input_drives_the_actor_and_a_wall_stops_it() {
+    let mut core = make_core();
+
+    core.load_map(&map_json()).unwrap();
+    // facing 180 degrees — towards the left wall (inner face at x = 32)
+    core.spawn_actor(1, "a1", 1, 100.0, 100.0, 180.0).unwrap();
+    core.apply_input(1, 7, "down", "forward");
+
+    steps(&mut core, 60);
+
+    let moved = core.position_of(1);
+
+    assert!(moved[0] < 90.0, "the actor should drive off, x = {}", moved[0]);
+    assert_eq!(core.last_input_seq(1), 7);
+
+    steps(&mut core, 300);
+
+    let stopped = core.position_of(1);
+
+    assert!(
+        stopped[0] > 32.0,
+        "the wall should stop the actor, x = {}",
+        stopped[0]
+    );
+}
+
+#[test]
+fn hitscan_takes_health_and_death_removes_the_actor_from_the_canvas() {
+    let mut core = make_core();
+
+    // the shooter faces the target point blank
+    core.spawn_actor(1, "a1", 1, 0.0, 0.0, 0.0).unwrap();
+    core.spawn_actor(2, "a1", 2, 60.0, 0.0, 0.0).unwrap();
+
+    // warm-up: the broad phase learns about the new bodies on the first step
+    core.step(DT);
+    core.take_events();
+
+    core.apply_input(1, 1, "down", "fire");
+    steps(&mut core, 8);
+
+    let health = events(&mut core)
+        .into_iter()
+        .find_map(|event| match event {
+            CoreEvent::PanelSet { id: 2, field, value } if field == "health" => Some(value),
+            _ => None,
+        })
+        .expect("a hit must report the new health of the victim");
+
+    assert_eq!(health, 75.0);
+    assert!(core.is_alive(2));
+
+    kill(&mut core, 1, 2);
+
+    assert!(!core.is_alive(2));
+    assert!(
+        events(&mut core)
+            .iter()
+            .any(|event| matches!(event, CoreEvent::Death { victim: 2, killer: 1 })),
+        "death must report the kill to the engine scoring"
+    );
+
+    // the dead actor leaves alive_players and the frame carries its removal
+    assert!(!core.alive_players().contains(&2.0));
+
+    frame(&mut core, 1);
+
+    assert!(
+        core.body_has_events(),
+        "a removal row is an event row: the frame must go over the reliable channel"
+    );
+}
+
+#[test]
+fn friendly_fire_off_protects_the_own_team() {
+    let mut core = make_core();
+
+    core.spawn_actor(1, "a1", 1, 0.0, 0.0, 0.0).unwrap();
+    core.spawn_actor(2, "a1", 1, 60.0, 0.0, 0.0).unwrap();
+
+    core.step(DT);
+    core.take_events();
+
+    for _ in 0..4 {
+        core.apply_input(1, 1, "down", "fire");
+        steps(&mut core, 8);
+    }
+
+    assert!(core.is_alive(2));
+    assert!(
+        !events(&mut core).iter().any(|event| matches!(
+            event,
+            CoreEvent::PanelSet { id: 2, field, .. } if field == "health"
+        )),
+        "a team mate must take no damage while friendlyFire is off"
+    );
+}
+
+#[test]
+fn wiping_a_team_leaves_only_the_other_one_alive() {
+    let mut core = make_core();
+
+    core.spawn_actor(1, "a1", 1, 0.0, 0.0, 0.0).unwrap();
+    core.spawn_actor(2, "a1", 2, 60.0, 0.0, 0.0).unwrap();
+    core.spawn_actor(3, "a1", 2, 120.0, 0.0, 0.0).unwrap();
+
+    core.step(DT);
+    core.take_events();
+
+    kill(&mut core, 1, 2);
+    kill(&mut core, 1, 3);
+
+    assert!(core.is_alive(1));
+    assert!(!core.is_alive(2));
+    assert!(!core.is_alive(3));
+
+    // [id, team, x, y] — only the surviving team is left for the round meta
+    let alive = core.alive_players();
+
+    assert_eq!(alive.len(), 4);
+    assert_eq!(alive[0], 1.0);
+    assert_eq!(alive[1], 1.0);
+}
+
+#[test]
+fn serialize_deserialize_round_trips_the_frame() {
+    let mut core = make_core();
+
+    core.load_map(&map_json()).unwrap();
+    core.spawn_actor(1, "a1", 1, 100.0, 100.0, 0.0).unwrap();
+    core.apply_input(1, 1, "down", "forward");
+    steps(&mut core, 30);
+
+    let dump = core.serialize_state().unwrap();
+    let mut restored = make_core();
+
+    restored.deserialize_state(&dump).unwrap();
+
+    // both continue from the dump: the frames must stay bit-identical
+    for seq in 0..10 {
+        steps(&mut core, 6);
+        steps(&mut restored, 6);
+
+        assert_eq!(frame(&mut core, seq), frame(&mut restored, seq));
+    }
+}
+
+#[test]
+fn one_seed_gives_one_stream_of_frames() {
+    let run = || {
+        let mut core = make_core();
+
+        core.load_map(&map_json()).unwrap();
+        core.spawn_scripted_actor(1, "a1", 1, 100.0, 100.0, 0.0).unwrap();
+        core.spawn_scripted_actor(2, "a1", 2, 500.0, 100.0, 180.0).unwrap();
+
+        let mut frames: Vec<Vec<u8>> = Vec::new();
+
+        for seq in 0..40 {
+            steps(&mut core, 6);
+            frames.push(frame(&mut core, seq));
+        }
+
+        frames
+    };
+
+    assert_eq!(run(), run());
+}

package/templates/default/dev/main.js

@@ -0,0 +1,28 @@
+// Entry point of the local standalone launch (`npm run dev`): a match against
+// bots right in the tab — no master, no OAuth, no lobby screen. It is not part
+// of the plugin build (--mode client|host) and is never published (files: ["dist"]).
+import 'vimp-engine/style.css';
+import { startStandaloneGame } from 'vimp-engine/standalone';
+import hostPlugin from '../src/host/index.js';
+import clientPlugin from '../src/client/index.js';
+// This file does not exist until `npm run core:build` — Vite fails to resolve
+// it, and that is the first thing `npm run dev` breaks on in a fresh checkout.
+import wasmUrl from '../core/pkg-web/{{CRATE_SNAKE}}_bg.wasm?url';
+
+await startStandaloneGame({
+  hostPlugin,
+  clientPlugin,
+  wasmUrl,
+  container: document.getElementById('game'),
+  // dev asset root: build/img (staged by `predev`) and build/sounds (the
+  // product of `npm run audio:process`). The engine client reads them as
+  // `${assetsBase}img/` and `${assetsBase}sounds/`.
+  assetsBase: '/build/',
+  playerName: localStorage.getItem('vimp_dev_nick') || 'Player',
+  playerModel: 'a1',
+  // leave the spectators first and only then ask for bots: the chat command
+  // is rejected for a spectator, and a joining participant is one
+  startupVotes: [['teamChange', 'team1']],
+  startupCommands: ['/spawn 3'],
+  devMode: true,
+});