@netforge/engine 0.0.0-stage → 0.1.0

package/dist/rules/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @netforge/engine/rules: the board genres (tower defense, idle, card
+ * battler, monster collector) on the room server's SimAdapter seam. Used by
+ * the room server, the headless harness and the template clients; game code
+ * declares content through @netforge/engine and never imports this.
+ */
+export * from "./kit.js";
+export { rulesAdapter } from "./adapter.js";
+export type { RulesAdapterOptions, RulesWorld } from "./adapter.js";
+export { playRules } from "./harness.js";
+export type { RulesPlaytest } from "./harness.js";
+export { genreFor, isRulesTemplate, labelledContent } from "./genres.js";
+export * from "./tower.js";
+export * from "./idle.js";
+export * from "./cards.js";
+export * from "./collector.js";

package/dist/rules/index.js

@@ -0,0 +1,14 @@
+/**
+ * @netforge/engine/rules: the board genres (tower defense, idle, card
+ * battler, monster collector) on the room server's SimAdapter seam. Used by
+ * the room server, the headless harness and the template clients; game code
+ * declares content through @netforge/engine and never imports this.
+ */
+export * from "./kit.js";
+export { rulesAdapter } from "./adapter.js";
+export { playRules } from "./harness.js";
+export { genreFor, isRulesTemplate, labelledContent } from "./genres.js";
+export * from "./tower.js";
+export * from "./idle.js";
+export * from "./cards.js";
+export * from "./collector.js";

package/dist/rules/kit.d.ts

@@ -0,0 +1,171 @@
+import type { EntitySchema, EntityState } from "../net/schema.js";
+import type { InputCodec } from "../net/sim-adapter.js";
+import type { GameEvent } from "../game/earn.js";
+/** Fixed-point units per metre for avatars and entities. */
+export declare const UNITS = 64;
+/** One tick of a player's input. */
+export interface RulesInput {
+    /** Stick, -127..127 (walking avatars). */
+    readonly mx: number;
+    readonly mz: number;
+    /** Cursor or target on the ground, 1/16 m, -32768..32767. */
+    readonly cx: number;
+    readonly cz: number;
+    /** The action this tick: 0 none; the genre names the rest. */
+    readonly act: number;
+    readonly a: number;
+    readonly b: number;
+    readonly c: number;
+}
+export declare const IDLE_INPUT: RulesInput;
+/** 50 bits a tick idle, 99 with an action. */
+export declare const rulesInputCodec: InputCodec<RulesInput>;
+/** Entity kinds on the wire. */
+export declare const RulesKind: {
+    readonly Avatar: 1;
+    readonly Unit: 2;
+    readonly Shot: 3;
+    readonly Structure: 4;
+    readonly Pickup: 5;
+};
+/** Field indices in RULES_SCHEMA. */
+export declare const RF: {
+    readonly x: 0;
+    readonly z: 1;
+    readonly yaw: 2;
+    readonly type: 3;
+    readonly hp: 4;
+    readonly flags: 5;
+    readonly value: 6;
+    readonly aux: 7;
+};
+/**
+ * The wire schema every board genre shares: position (1/64 m), facing, a
+ * type, health, flags and two small values. Units interpolate their
+ * position; everything else steps.
+ */
+export declare const RULES_SCHEMA: EntitySchema;
+/** A player's avatar (fixed point). The only state a client predicts. */
+export interface Avatar {
+    x: number;
+    z: number;
+    /** u16 turn. */
+    yaw: number;
+    /** Look the player wears (store cosmetic id, 0 the default). */
+    cosmetic: number;
+    /** Genre flags drawn with the avatar (e.g. "ready"). */
+    flags: number;
+}
+/** Entity state for an avatar. Avatar entity ids are the player ids. */
+export declare function avatarEntity(player: number, a: Avatar): EntityState;
+/** Entity ids a genre uses start here (avatars take the player ids below). */
+export declare const ENTITY_BASE = 65536;
+export declare function entity(id: number, kind: number, owner: number, x: number, z: number, yawTurn: number, type: number, hp: number, flags?: number, value?: number, aux?: number): EntityState;
+/** Seat bots and only them: player ids at 0xff00 and up (engine-sim's BOT_PLAYER_BASE). */
+export declare const RULES_BOT_BASE = 65280;
+export declare const isRulesBot: (p: number) => boolean;
+/** mulberry32 on a state word kept in the genre's state (so a restored state continues the same stream). */
+export interface Rng {
+    s: number;
+}
+export declare function rand(r: Rng): number;
+/** 0..n-1. */
+export declare function randInt(r: Rng, n: number): number;
+/** Fisher-Yates in place. */
+export declare function shuffle<T>(r: Rng, list: T[]): T[];
+/** What a genre reads about the players from the adapter. */
+export interface RulesContext {
+    /** A store upgrade's bonus for this player: the sum of step x level over the player's upgrades of `stat`. */
+    bonus(player: number, stat: string): number;
+    isBot(player: number): boolean;
+}
+export type RunOutcome = "won" | "lost";
+/** Numbers the headless harness reports (HarnessReport), in the genre's own sense. */
+export interface RulesStats {
+    /** Enemies defeated (TD creeps, duels won, wild creatures beaten). */
+    readonly kills: number;
+    /** Progress through the run: wave, tier, floor (1-based). */
+    readonly wave: number;
+    /** Highest level any player reached. */
+    readonly level: number;
+    /** Times a player lost something (lives lost, duels lost, a creature fainted). */
+    readonly deaths: number;
+    /** Most units alive at once. */
+    readonly peakUnits: number;
+    /** Players with at least one kill. */
+    readonly scorers: number;
+    /** Best single player's kills. */
+    readonly topScore: number;
+}
+/** A genre's own line in the playtest gate: a hard check or a scored part. */
+export interface RulesCheck {
+    readonly ok: boolean;
+    /** The line the model reads when it fails, or what it measured. */
+    readonly line: string;
+}
+/**
+ * One board genre. `S` is its whole authoritative state: integers, arrays
+ * and maps in insertion order, a PRNG word. Factories build one from the
+ * game's manifest (rules/genres.ts).
+ */
+export interface RulesGenre<S> {
+    /** The engine template it plays (game({ template })). */
+    readonly template: string;
+    readonly tickRate: number;
+    /** Seconds the end screen stays before a fresh run. */
+    readonly endSeconds: number;
+    /** Ticks between per-player run-state sends. */
+    readonly infoEveryTicks: number;
+    create(seed: number, ctx: RulesContext): S;
+    /** Where a joining player's avatar starts. */
+    spawn(s: S | null, player: number): {
+        x: number;
+        z: number;
+    };
+    /** Moves an avatar one tick from its own input and static world state only (both sides: the client predicts it). */
+    moveAvatar(a: Avatar, input: RulesInput): void;
+    join(s: S, player: number): void;
+    leave(s: S, player: number): void;
+    /** Applies a player's action (validated here: the server never trusts a client's numbers). */
+    act(s: S, player: number, input: RulesInput, avatar: Avatar, emit: (e: GameEvent) => void): void;
+    /**
+     * Server only, every tick, after each avatar moved: what the world does
+     * with where a player stands (a step into tall grass). It may move the
+     * avatar (a teleport home), which the client then reconciles.
+     */
+    tend?(s: S, player: number, avatar: Avatar, emit: (e: GameEvent) => void): void;
+    /** One tick of the world. */
+    step(s: S, emit: (e: GameEvent) => void): void;
+    /** The run ended (null while it goes on). */
+    outcome(s: S): RunOutcome | null;
+    /** What `player` may see (null: what everyone may see). JSON-safe. Never another player's secrets. */
+    view(s: S, player: number | null): Record<string, unknown>;
+    /** Networked entities other than avatars (ids from 0). */
+    entities(s: S, out: EntityState[]): void;
+    /** Seat bots wanted with `humans` people in the room (bots never earn). Omit for none. */
+    seats?(s: S, humans: number): number;
+    /** A bot's (or a playtest player's) input this tick. `skill` 0..1 (playtests use 1). */
+    bot(s: S, player: number, avatar: Avatar, tick: number, skill: number): RulesInput;
+    stats(s: S): RulesStats;
+    /** Changes whenever anything happens (the softlock detector). */
+    activity(s: S): number;
+    /** The genre's own playtest checks on one playtest run (the gate fails the draft on any that is not ok in the squad run). */
+    checks(run: RulesHarnessRun): RulesCheck[];
+    /** How far the playtest got through the genre's arc, 0..1 (the gate's progression score). */
+    progress(run: RulesHarnessRun): number;
+}
+/** One harness run's numbers, for a genre's checks. */
+export interface RulesHarnessRun {
+    readonly seconds: number;
+    readonly players: number;
+    readonly stats: RulesStats;
+    readonly runs: {
+        readonly won: number;
+        readonly lost: number;
+    };
+    readonly earned: Readonly<Record<string, number>>;
+    /** Seconds until the first earn award (null if none). */
+    readonly firstEarnSeconds: number | null;
+    /** Seconds the first run lasted (null if it never ended). */
+    readonly firstRunSeconds: number | null;
+}

package/dist/rules/kit.js

@@ -0,0 +1,88 @@
+/** Fixed-point units per metre for avatars and entities. */
+export const UNITS = 64;
+export const IDLE_INPUT = { mx: 0, mz: 0, cx: 0, cz: 0, act: 0, a: 0, b: 0, c: 0 };
+const clampInt = (v, lo, hi) => (Number.isFinite(v) ? Math.max(lo, Math.min(hi, Math.round(v))) : 0);
+/** 50 bits a tick idle, 99 with an action. */
+export const rulesInputCodec = {
+    idle: IDLE_INPUT,
+    write(w, i) {
+        w.writeSigned(clampInt(i.mx, -127, 127), 8);
+        w.writeSigned(clampInt(i.mz, -127, 127), 8);
+        w.writeSigned(clampInt(i.cx, -32768, 32767), 16);
+        w.writeSigned(clampInt(i.cz, -32768, 32767), 16);
+        const act = clampInt(i.act, 0, 255);
+        w.writeBool(act !== 0);
+        if (act !== 0) {
+            w.writeBits(act, 8);
+            w.writeBits(clampInt(i.a, 0, 0xffff), 16);
+            w.writeBits(clampInt(i.b, 0, 0xffff), 16);
+            w.writeBits(clampInt(i.c, 0, 0xffff), 16);
+        }
+    },
+    read(r) {
+        const mx = r.readSigned(8);
+        const mz = r.readSigned(8);
+        const cx = r.readSigned(16);
+        const cz = r.readSigned(16);
+        if (!r.readBool())
+            return { mx, mz, cx, cz, act: 0, a: 0, b: 0, c: 0 };
+        return { mx, mz, cx, cz, act: r.readBits(8), a: r.readBits(16), b: r.readBits(16), c: r.readBits(16) };
+    },
+};
+/** Entity kinds on the wire. */
+export const RulesKind = { Avatar: 1, Unit: 2, Shot: 3, Structure: 4, Pickup: 5 };
+/** Field indices in RULES_SCHEMA. */
+export const RF = { x: 0, z: 1, yaw: 2, type: 3, hp: 4, flags: 5, value: 6, aux: 7 };
+/**
+ * The wire schema every board genre shares: position (1/64 m), facing, a
+ * type, health, flags and two small values. Units interpolate their
+ * position; everything else steps.
+ */
+export const RULES_SCHEMA = {
+    fields: [
+        { name: "x", kind: "int", bits: 20, deltaBits: 10 },
+        { name: "z", kind: "int", bits: 20, deltaBits: 10 },
+        { name: "yaw", kind: "angle16", deltaBits: 9 },
+        { name: "type", kind: "uint", bits: 8, interp: "step" },
+        { name: "hp", kind: "uint", bits: 20, interp: "step", deltaBits: 8 },
+        { name: "flags", kind: "uint", bits: 8, interp: "step" },
+        { name: "value", kind: "uint", bits: 16, interp: "step", deltaBits: 6 },
+        { name: "aux", kind: "uint", bits: 16, interp: "step", deltaBits: 6 },
+    ],
+    xField: RF.x,
+    yField: RF.z,
+    unitsPerWorld: UNITS,
+};
+/** Entity state for an avatar. Avatar entity ids are the player ids. */
+export function avatarEntity(player, a) {
+    return { id: player, kind: RulesKind.Avatar, owner: player, values: [a.x, a.z, (a.yaw / 65536) * Math.PI * 2, 0, 0, a.flags & 0xff, a.cosmetic & 0xffff, 0] };
+}
+/** Entity ids a genre uses start here (avatars take the player ids below). */
+export const ENTITY_BASE = 0x10000;
+export function entity(id, kind, owner, x, z, yawTurn, type, hp, flags = 0, value = 0, aux = 0) {
+    return { id: ENTITY_BASE + id, kind, owner, values: [x, z, (yawTurn / 65536) * Math.PI * 2, type, Math.max(0, Math.min(0xfffff, Math.round(hp))), flags & 0xff, value & 0xffff, aux & 0xffff] };
+}
+/** Seat bots and only them: player ids at 0xff00 and up (engine-sim's BOT_PLAYER_BASE). */
+export const RULES_BOT_BASE = 0xff00;
+export const isRulesBot = (p) => p >= RULES_BOT_BASE;
+export function rand(r) {
+    r.s = (r.s + 0x6d2b79f5) | 0;
+    let t = r.s;
+    t = Math.imul(t ^ (t >>> 15), t | 1);
+    t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+}
+/** 0..n-1. */
+export function randInt(r, n) {
+    return Math.floor(rand(r) * n) % Math.max(1, n);
+}
+/** Fisher-Yates in place. */
+export function shuffle(r, list) {
+    for (let i = list.length - 1; i > 0; i--) {
+        const j = randInt(r, i + 1);
+        const t = list[i];
+        list[i] = list[j];
+        list[j] = t;
+    }
+    return list;
+}

package/dist/rules/tower.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The tower defense genre (template "tower-defense"): a co-op board where
+ * up to four players build and upgrade towers along one road while waves of
+ * creeps walk it toward the spire. Shared lives, gold of your own, bounties
+ * to the tower's builder and a share to everyone else.
+ *
+ * Fixed point: Q units per tile (a tile is 2 m), integer creep progress
+ * along the road, integer ranges compared squared. Targeting is "first"
+ * (the creep furthest along), ties to the lower id, so the run replays
+ * exactly from its inputs.
+ */
+import type { GameManifest } from "../api/registry.js";
+import { type TowerDef } from "../api/tower.js";
+import type { RulesContext, RulesGenre } from "./kit.js";
+/** Fixed-point units per tile. */
+export declare const Q = 256;
+/** Metres per tile. */
+export declare const TILE_M = 2;
+/** Actions (RulesInput.act). */
+export declare const TowerAct: {
+    readonly Build: 1;
+    readonly Upgrade: 2;
+    readonly Sell: 3;
+    readonly Ready: 4;
+};
+/** Creep flags on the wire. */
+export declare const CreepFlag: {
+    readonly Slowed: 1;
+    readonly Boss: 2;
+    readonly Dead: 4;
+    readonly Leaked: 8;
+};
+interface Creep {
+    id: number;
+    type: number;
+    hp: number;
+    maxHp: number;
+    /** Progress along the road, Q units. */
+    d: number;
+    /** Q units a tick at full speed. */
+    speed: number;
+    slowTicks: number;
+    slow: number;
+    value: number;
+    dmg: number;
+    boss: boolean;
+    /** Ticks left as a corpse (dead or leaked); 0 while alive. */
+    gone: number;
+    flags: number;
+    /** Who dealt the killing blow (tower owner), for the feed. */
+    by: number;
+}
+interface Tower {
+    id: number;
+    type: number;
+    owner: number;
+    tx: number;
+    ty: number;
+    level: number;
+    cd: number;
+    spent: number;
+    /** Shots fired (u16 wrap): the client draws a tracer when it changes. */
+    shots: number;
+    /** Local id of the last creep shot. */
+    target: number;
+    yaw: number;
+    kills: number;
+}
+interface TowerPlayer {
+    gold: number;
+    kills: number;
+    ready: boolean;
+    built: number;
+}
+interface Spawn {
+    tick: number;
+    type: number;
+}
+export interface TowerState {
+    rng: {
+        s: number;
+    };
+    ctx: RulesContext;
+    tick: number;
+    wave: number;
+    phase: "build" | "wave";
+    countdown: number;
+    lives: number;
+    livesMax: number;
+    /** Lives the team bought (maxHealth upgrades) already added. */
+    livesBought: Map<number, number>;
+    queue: Spawn[];
+    waveTick: number;
+    creeps: Creep[];
+    towers: Tower[];
+    players: Map<number, TowerPlayer>;
+    nextId: number;
+    kills: number;
+    leaks: number;
+    peak: number;
+    won: boolean;
+    /** Bumped whenever anything happens (softlock detector). */
+    activity: number;
+}
+interface TowerStats {
+    damage: number;
+    rate: number;
+    range: number;
+    radius: number;
+    slow: number;
+    slowSeconds: number;
+    chains: number;
+}
+export interface CompiledTower {
+    readonly id: string;
+    readonly def: TowerDef;
+    /** Stats at each level (0 = built). */
+    readonly levels: readonly TowerStats[];
+    /** Cost of each upgrade (index 0 buys level 1). */
+    readonly upgradeCost: readonly number[];
+}
+export interface CompiledBoard {
+    readonly w: number;
+    readonly h: number;
+    /** Waypoints, tile coords. */
+    readonly path: readonly (readonly [number, number])[];
+    /** Cumulative road length at each waypoint, Q units. */
+    readonly cum: readonly number[];
+    readonly length: number;
+    readonly road: ReadonlySet<number>;
+    readonly blocked: ReadonlySet<number>;
+}
+/** Tile key. */
+export declare const tileKey: (x: number, y: number) => number;
+/** A tile's centre in metres, board centred on the origin. */
+export declare function tileCenter(b: Pick<CompiledBoard, "w" | "h">, tx: number, ty: number): {
+    x: number;
+    z: number;
+};
+/** The tile under a point in metres, or null off the board. */
+export declare function tileAt(b: Pick<CompiledBoard, "w" | "h">, x: number, z: number): {
+    tx: number;
+    ty: number;
+} | null;
+export declare function compileBoard(def: {
+    size: readonly [number, number];
+    path: readonly (readonly [number, number])[];
+    blocked: readonly (readonly [number, number])[];
+}): CompiledBoard;
+/** Position on the road at progress `d` (Q units), in Q units with the board's corner at 0, and the heading (u16 turn). */
+export declare function roadPoint(b: CompiledBoard, d: number): {
+    qx: number;
+    qy: number;
+    yaw: number;
+};
+/** Everything a tower defense game declared, compiled (shared by the room, the harness and the client). */
+export interface CompiledTowerGame {
+    readonly board: CompiledBoard;
+    readonly towers: readonly CompiledTower[];
+    readonly creeps: readonly {
+        id: string;
+        model: string;
+        health: number;
+        speed: number;
+        value: number;
+        damage: number;
+        boss: boolean;
+    }[];
+    readonly lives: number;
+    readonly gold: number;
+    readonly prep: number;
+    readonly breather: number;
+    readonly share: number;
+    readonly waveGold: {
+        base: number;
+        perWave: number;
+    };
+    readonly refund: number;
+    readonly totalWaves: number;
+    readonly healthGrowth: number;
+    readonly groups: readonly {
+        type: number;
+        from: number;
+        until: number;
+        every: number;
+        count: number;
+        grow: number;
+        gap: number;
+        delay: number;
+    }[];
+}
+export declare function compileTowerGame(m: GameManifest): CompiledTowerGame;
+/** The spawns of wave `n` (1-based), by tick offset into the wave. */
+export declare function waveSpawns(g: CompiledTowerGame, n: number, tickRate: number): Spawn[];
+/** What the next wave brings, by creep type (the HUD's preview). */
+export declare function wavePreview(g: CompiledTowerGame, n: number): {
+    type: number;
+    count: number;
+}[];
+export declare function roadCoverage(b: CompiledBoard, rangeQ: number): Int32Array;
+/**
+ * The best free tile for a tower of `type` (the most road in reach), with a
+ * per-player tie-break and `jitter` (0 for the sharpest choice). Null when
+ * no free tile reaches the road. Used by the playtest bots and the
+ * client's autopilot alike.
+ */
+export declare function bestTowerTile(g: CompiledTowerGame, occupied: ReadonlySet<number>, type: number, salt: number, jitter?: number): {
+    tx: number;
+    ty: number;
+} | null;
+export declare function towerGenre(m: GameManifest): RulesGenre<TowerState> & {
+    readonly game: CompiledTowerGame;
+};
+export {};