@netforge/engine 0.0.0-stage → 0.1.0

package/dist/game/platformer.d.ts

@@ -0,0 +1,156 @@
+/**
+ * The platformer template's machinery: compile a manifest's levels into the
+ * engine-sim platform sim, drive it with the race runner (race.ts), seat
+ * bots that run the course, a route planner that proves every level can be
+ * finished (the gate's softlock check), and the netcode SimAdapter.
+ */
+import { capturePlatformPlayer } from "@netforge/engine-sim";
+import type { InputCommand, PlatformLevel, PlatformPlayer, PlatformTuning, PlatformWorld, PlatStat } from "@netforge/engine-sim";
+import type { GameManifest } from "../api/registry.js";
+import type { BitReader, BitWriter } from "../net/bits.js";
+import type { EntitySchema, EntityState } from "../net/schema.js";
+import type { SimAdapter } from "../net/sim-adapter.js";
+import { RaceRunner } from "./race.js";
+import type { RaceCore, RaceRunnerOptions, RaceSimEvent } from "./race.js";
+/** Platformer defaults: a 3 minute limit, 60 Hz, three seat bots. */
+export declare const PLATFORMER_DEFAULTS: {
+    readonly roundSeconds: 180;
+    readonly tickRate: 60;
+    readonly bots: 3;
+};
+export interface CompiledPlatformer {
+    readonly levels: readonly PlatformLevel[];
+    /** Level names for the HUD (declared or "Level n"). */
+    readonly names: readonly string[];
+    readonly tuning: Partial<PlatformTuning>;
+    /** Per PLAT_STATS index: the step of the declared upgrade on that stat. */
+    readonly statSteps: readonly number[];
+    /** Per declared upgrade (declaration order): its platform stat. */
+    readonly upgradeStat: readonly PlatStat[];
+}
+/** Compile the platformer parts of a manifest. Issues are agent-readable. */
+export declare function compilePlatformer(m: GameManifest, tickRate: number, issues: string[]): CompiledPlatformer;
+/** Per-bot memory for the course runner. */
+export interface PlatformBotMemory {
+    bestX: number;
+    since: number;
+    holdJump: number;
+    /** The planned run this bot follows, from the tick it started. */
+    tape?: readonly InputCommand[] | null;
+    tapeAt?: number;
+}
+/**
+ * What a course-running bot does this tick: run toward the flag, jump at
+ * walls, gaps and hazards, wait for a moving platform, hold Jump for a full
+ * jump, dash across a gap it is falling into. Deterministic.
+ */
+export declare function platformBotInput(w: PlatformWorld, p: PlatformPlayer, mem: PlatformBotMemory, clock: number, skill: number): InputCommand;
+export interface PlanResult {
+    readonly found: boolean;
+    /** Seconds the route takes. */
+    readonly seconds: number;
+    /** Furthest x reached. */
+    readonly bestX: number;
+    readonly expanded: number;
+    /** One input per tick from the start signal. */
+    readonly tape: readonly InputCommand[];
+}
+/**
+ * Search for a run from the start to the flag (the gate's softlock check:
+ * every level must be finishable). Best-first over short macro moves (run,
+ * jump of three heights, dash, wait) on a one-player copy of the sim, keyed
+ * by position cells so it never re-explores. Moving platforms run on the
+ * real clock from `startTick`.
+ */
+export declare function planCourse(level: PlatformLevel, opts: {
+    tickRate: number;
+    tuning?: Partial<PlatformTuning>;
+    statSteps?: readonly number[];
+    startTick?: number;
+    budget?: number;
+    from?: ReturnType<typeof capturePlatformPlayer>;
+}): PlanResult;
+/** True when routeFor found no way from this course's start to its flag. */
+export declare function unroutable(level: PlatformLevel): boolean;
+/**
+ * A planned run from a climber's exact state (cached), or null when the
+ * planner found none. Without `from`, from the start at `startTick`.
+ */
+export declare function routeFor(level: PlatformLevel, tickRate: number, tuning: Partial<PlatformTuning>, startTick: number, from?: ReturnType<typeof capturePlatformPlayer>): readonly InputCommand[] | null;
+/** Seconds a bot of this skill waits after the start signal before running its route (quarter seconds). */
+export declare function botDelaySeconds(id: number, skill: number): number;
+/** The platform sim as the race runner drives it. */
+export declare class PlatformCore implements RaceCore {
+    readonly compiled: CompiledPlatformer;
+    readonly tickRate: number;
+    readonly world: PlatformWorld;
+    private readonly memory;
+    /** World tick of this round's start signal (-1 while frozen). */
+    private startTick;
+    /** Players present at the start signal: they may run a planned route. */
+    private readonly starters;
+    constructor(compiled: CompiledPlatformer, tickRate: number);
+    ids(): number[];
+    add(id: number, bot: boolean, frozen: boolean): void;
+    remove(id: number): void;
+    reset(course: number, frozen: boolean): void;
+    setFrozen(frozen: boolean): void;
+    finished(id: number): boolean;
+    progress(id: number): number;
+    position(id: number): readonly [number, number, number];
+    step(inputs: ReadonlyMap<number, InputCommand>): RaceSimEvent[];
+    botInput(id: number, clock: number, skill: number): InputCommand;
+    grant(id: number, upgrade: number): boolean;
+    setCosmetic(id: number, cosmetic: number): void;
+}
+/** Field indices of the platformer wire schema. */
+export declare const PF: {
+    readonly x: 0;
+    readonly y: 1;
+    readonly vx: 2;
+    readonly vy: 3;
+    readonly flags: 4;
+    readonly timers: 5;
+    readonly timers2: 6;
+    readonly cp: 7;
+    readonly coinsLo: 8;
+    readonly coinsHi: 9;
+    readonly finishTick: 10;
+    readonly stats: 11;
+    readonly cosmetic: 12;
+    readonly clock: 13;
+};
+export declare const platformSchema: EntitySchema;
+/** The engine InputCommand on the wire (moves int8, yaw u16, buttons u16), shared by the race templates. */
+export declare const raceInputCodec: {
+    idle: InputCommand;
+    write(w: BitWriter, i: InputCommand): void;
+    read(r: BitReader): InputCommand;
+};
+export interface PlatformRoomWorld {
+    readonly role: "server" | "client";
+    readonly core: PlatformCore;
+    readonly runner: RaceRunner | null;
+}
+export interface PlatformAdapterOptions {
+    readonly name: string;
+    readonly version: string;
+    readonly manifest: GameManifest;
+    readonly compiled: CompiledPlatformer;
+    readonly tickRate: number;
+    readonly bots: number;
+    readonly roundSeconds: number | null;
+    readonly runner?: RaceRunnerOptions;
+}
+/** The platformer's SimAdapter: the room runs the race; a client predicts only its own runner. */
+export declare function platformAdapter(o: PlatformAdapterOptions): SimAdapter<PlatformRoomWorld, InputCommand>;
+/** Throw the collected compile issues, agent-readable. */
+export declare function assertNoIssues(issues: readonly string[]): void;
+/**
+ * A playing autopilot for a client (measurement, previews, load tests): from
+ * the newest predicted state of our own climber it plans a route to the flag
+ * (cached by state), plays it back tick for tick on the course clock, and
+ * replans after a fall, a new course or the end of the tape. Falls back to
+ * the course bot's reflexes while no route is known.
+ */
+export declare function platformAutopilot(compiled: CompiledPlatformer, tickRate: number): (self: EntityState | undefined, course: number, tick: number) => InputCommand;