@netforge/engine/game API reference

import { compileGame } from "@netforge/engine/game";

function arenaBotInput(v: ArenaBotView, mem: ArenaBotMemory, tick: number, tickRate?: number): InputCommand;

function arenaBotMemory(): ArenaBotMemory;

function botDelaySeconds(id: number, skill: number): number;

function botInput(me: BotView, enemies: Iterable<readonly [number, number]>, tick: number, id: number): InputCommand;

function collectManifest(): GameManifest;

function compileGame(m: GameManifest, opts?: { maxEntities?: number; views?: readonly CameraView[]; }): CompiledGame;

function compilePlatformer(m: GameManifest, tickRate: number, issues: string[]): CompiledPlatformer;

function compileRacer(m: GameManifest, issues: string[]): CompiledRacer;

function curveAt(c: Curve, t: number): number;

function disposeEngineWorld(w: EngineRoomWorld): void;

function engineSimAdapter(opts: EngineAdapterOptions): SimAdapter<EngineRoomWorld, InputCommand>;

function footprint(v: CameraView): [number, number][];

function insideView(radii: readonly number[], dx: number, dz: number): boolean;

function kartAdapter(o: KartAdapterOptions): SimAdapter<KartRoomWorld, InputCommand>;

function kartAutopilot(compiled: CompiledRacer, tickRate: number): (self: EntityState | undefined, tick: number, skill?: number, others?: readonly EntityState[]) => InputCommand;

function kartBotInput(w: KartWorld, k: Kart, clock: number, skill: number, lane?: number, mem?: { driftUntil: number; }): InputCommand;

function kartFromValues(e: EntityState): Wire;

function laneLength(def: EnemyTypeDef | undefined): number;

function levelTable(w: ApiWeaponDef, tickRate: number): WeaponLevelStats[];

function metaBonus(spec: ProfileSpec, levels: Readonly<Record<string, number>>): Partial<Record<MetaStat, number>>;

function metaPrice(def: MetaUpgradeDef, level: number): number | null;

function openKeepers(spec: ProfileSpec, state: ProfileUnlockState): number[];

function ownedCosmetics(spec: ProfileSpec, owned: Iterable<string>): number[];

function ownedGear(spec: ProfileSpec, owned: Iterable<string>): Array<{ sku: string; upgrade: string; loseBelow: number; coins: number; }>;

function packMeta(spec: ProfileSpec, levels: Readonly<Record<string, number>>): number;

function planCourse(level: PlatformLevel, opts: { tickRate: number; tuning?: Partial<PlatformTuning>; statSteps?: readonly number[]; startTick?: number; budget?: number; from?: ReturnType<typeof capturePlatformPlayer>; }): PlanResult;

function platformAdapter(o: PlatformAdapterOptions): SimAdapter<PlatformRoomWorld, InputCommand>;

function platformAutopilot(compiled: CompiledPlatformer, tickRate: number): (self: EntityState | undefined, course: number, tick: number) => InputCommand;

function platformBotInput(w: PlatformWorld, p: PlatformPlayer, mem: PlatformBotMemory, clock: number, skill: number): InputCommand;

function prefabKind(m: GameManifest, id: string, p: PrefabDef): "enemy" | "pickup";

function profileSpec(m: GameManifest): ProfileSpec;

function radiusAt(radii: readonly number[], a: number): number;

function resetRegistry(): void;

function routeFor(level: PlatformLevel, tickRate: number, tuning: Partial<PlatformTuning>, startTick: number, from?: ReturnType<typeof capturePlatformPlayer>): readonly InputCommand[] | null;

function sightBlocked(x0: number, z0: number, x1: number, z1: number, pillars: ArenaBotView["pillars"]): boolean;

function skuKind(grants: SkuGrant | undefined | null): SkuKind;

function threatOf(enemyTypes: readonly EnemyTypeDef[], kind: number, flags: number, type: number, level: number, x: number, z: number, vx?: number, vz?: number): ThreatShape | null;

function todaysGoals(ids: readonly string[], day: number, n?: number): string[];

function unpackMeta(spec: ProfileSpec, value: number): Record<string, number>;

function unroutable(level: PlatformLevel): boolean;

function utcDay(ms: number): number;

function viewRadii(views: readonly CameraView[], n?: number): number[];

function viewsFor(template: string): readonly CameraView[];

class Director {
  constructor(def: DirectorDef, world: SimWorld, hooks: DirectorHooks);
  pause(now: number, ticks: number): void;
  surge(now: number, k: number, ticks: number): void;
  aliveTarget(tick: number): number;
  tick(tick: number): void;
}

class EarnTracker {
  constructor(rules: ReadonlyMap<string, EarnRuleDef>);
  record(e: GameEvent): EarnAward[];
  resetRun(): void;
  forget(player: number): void;
  count(player: number, event: string): number;
}

class GameRunner {
  constructor(compiled: CompiledGame, world: SimWorld, opts?: RunnerOptions);
  takeProgress(): RunProgress[];
  get phaseNow(): RunPhase;
  get runNumber(): number;
  beforeStep(inputs?: Map<number, InputCommand>): void;
  autopilot(id: number): InputCommand;
  afterStep(simEvents: readonly SimEvent[]): RunnerStep;
  summary(): RunSummary;
  info(): RunInfo;
  bossIds(): number[];
  startRun(player: number): void;
  count(player: number, event: string): number;
  emittedCount(event: string): number;
  killsOf(player: number): number;
}

class HumanBot {
  constructor(opts?: HumanBotOptions);
  input(now: HumanBotView, tick: number): InputCommand;
}

class KartCore {
  constructor(compiled: CompiledRacer, tickRate: number, authority?: boolean);
  readonly tickRate: number;
  readonly world: KartWorld;
  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;
}

class PlatformCore {
  constructor(compiled: CompiledPlatformer, tickRate: number);
  readonly tickRate: number;
  readonly world: PlatformWorld;
  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;
}

class RaceRunner {
  constructor(manifest: GameManifest, core: RaceCore, opts: { readonly bots: number; readonly roundSeconds: number | null; readonly courses: number; readonly seed: number; } & RaceRunnerOptions);
  get phaseNow(): RacePhase;
  get runNumber(): number;
  get courseNow(): number;
  placeOf(id: number): number | null;
  joined(id: number): void;
  left(id: number): void;
  beforeStep(inputs: Map<number, InputCommand>): void;
  afterStep(sim: readonly RaceSimEvent[]): RaceStep;
  takeProgress(): RunProgress[];
  startRun(player: number): void;
  count(player: number, event: string): number;
  standings(): number[];
  info(): RaceInfo;
}

const ARENA_DEFAULTS: { readonly roundSeconds: 180; readonly respawnSeconds: 3; readonly spawnProtectSeconds: 2; readonly pickupSeconds: 20; readonly pillarHeight: 2.4; };

const CROWD_UNITS: 16;

const DUNGEON_VIEWS: readonly CameraView[];

const engineSchema: EntitySchema;

const F: { readonly px: 0; readonly py: 1; readonly pz: 2; readonly vx: 3; readonly vy: 4; readonly vz: 5; readonly yaw: 6; readonly health: 7; readonly flags: 8; readonly cooldown: 9; readonly buttons: 10; readonly timers: 11; readonly type: 12; readonly level: 13; readonly xp: 14; readonly weapons: 15; readonly wcd: 16; readonly stats: 17; readonly choices: 18; readonly bleed: 19; readonly revive: 20; readonly iframes: 21; readonly dash: 22; readonly ex: 23; readonly ez: 24; readonly value: 25; };

const kartSchema: EntitySchema;

const KF: { readonly x: 0; readonly z: 1; readonly yaw: 2; readonly vx: 3; readonly vz: 4; readonly flags: 5; readonly timers: 6; readonly track: 7; readonly coinsLo: 8; readonly coinsHi: 9; readonly finishTick: 10; readonly stats: 11; readonly cosmetic: 12; readonly clock: 13; };

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; };

const PLATFORMER_DEFAULTS: { readonly roundSeconds: 180; readonly tickRate: 60; readonly bots: 3; };

const platformSchema: EntitySchema;

const PLAYER_UNITS: 1024;

const raceInputCodec: { idle: InputCommand; write(w: BitWriter, i: InputCommand): void; read(r: BitReader): InputCommand; };

const RACER_DEFAULTS: { readonly roundSeconds: 240; readonly tickRate: 60; readonly bots: 5; };

const RESERVED_COMMANDS: ReadonlySet<string>;

const SURVIVOR_VIEWS: readonly CameraView[];

interface ArenaBotMemory {
  target: number;
  since: number;
  aimError: number;
  lastHealth: number;
  sightSince?: number;
}

interface ArenaBotOpponent {
  readonly id: number;
  readonly x: number;
  readonly z: number;
  readonly skill?: number;
  readonly crowded?: boolean;
}

interface ArenaBotView {
  readonly id: number;
  readonly x: number;
  readonly z: number;
  readonly health: number;
  readonly maxHealth: number;
  readonly up: boolean;
  readonly slot: number;
  readonly loadout: readonly ArenaBotWeapon[];
  readonly opponents: readonly ArenaBotOpponent[];
  readonly pickups: readonly { readonly x: number; readonly z: number }[];
  readonly pillars: readonly { readonly x: number; readonly z: number; readonly radius: number }[];
  readonly half: number;
  readonly seed?: number;
  readonly skill?: number;
}

interface ArenaBotWeapon {
  readonly kind: string;
  readonly range: number;
  readonly count: number;
}

interface BotDanger {
  readonly x: number;
  readonly z: number;
  readonly r: number;
  readonly dx?: number;
  readonly dz?: number;
  readonly len?: number;
}

interface BotView {
  readonly x: number;
  readonly z: number;
  readonly choices: number;
  readonly half: number;
}

interface CameraView {
  readonly distance: number;
  readonly pitch: number;
  readonly fov: number;
  readonly aspect: number;
  readonly focusHeight?: number;
}

interface CompiledGame {
  readonly manifest: GameManifest;
  readonly sim: SimConfig;
  readonly enemyPrefabs: readonly string[];
  readonly enemyType: ReadonlyMap<string, number>;
  readonly pickupPrefabs: readonly string[];
  readonly specialPickups: readonly string[];
  readonly weaponIds: readonly string[];
  readonly upgradeIds: readonly string[];
  readonly tickRate: number;
  readonly mode: "survivor" | "arena" | "platformer" | "racer";
  readonly platformer?: CompiledPlatformer;
  readonly racer?: CompiledRacer;
  readonly loadout: readonly number[];
  readonly bots: number;
  readonly round: { readonly seconds: number; readonly frags: number | null } | null;
  readonly view: readonly number[];
}

interface CompiledPlatformer {
  readonly levels: readonly PlatformLevel[];
  readonly names: readonly string[];
  readonly tuning: Partial<PlatformTuning>;
  readonly statSteps: readonly number[];
  readonly upgradeStat: readonly PlatStat[];
}

interface CompiledRacer {
  readonly tracks: readonly KartTrackDef[];
  readonly names: readonly string[];
  readonly tuning: Partial<KartTuning>;
  readonly statSteps: readonly number[];
  readonly upgradeStat: readonly KartStat[];
}

interface EarnAward {
  readonly player: number;
  readonly rule: string;
  readonly units: number;
}

interface EngineAdapterOptions {
  readonly name: string;
  readonly version: string;
  readonly game?: CompiledGame;
  readonly arena?: SimConfig;
  readonly runner?: RunnerOptions;
}

interface EngineRoomWorld {
  readonly sim: SimWorld;
  readonly role: 'server' | 'client';
  readonly runner: GameRunner | null;
  readonly shots: Map<PlayerId, BeamShot>;
}

interface GameEvent {
  readonly name: string;
  readonly players: readonly number[];
  readonly unpaid?: true;
  readonly own?: true;
}

interface HumanBotOptions {
  readonly reactionTicks?: number;
  readonly picks?: "random" | "greedy";
  readonly weaponCount?: number;
  readonly evolved?: readonly number[];
  readonly pairs?: readonly (readonly [number, number])[];
  readonly seed?: number;
}

interface HumanBotView {
  readonly x: number;
  readonly z: number;
  readonly up: boolean;
  readonly choices: number;
  readonly weapons: number;
  readonly half: number;
  readonly enemies: readonly (readonly [number, number])[];
  readonly gems: readonly (readonly [number, number])[];
  readonly pillars: readonly { readonly x: number; readonly z: number; readonly radius: number }[];
  readonly dangers?: readonly BotDanger[];
  readonly reach?: number;
  readonly bosses?: readonly (readonly [number, number])[];
  readonly downed?: readonly (readonly [number, number])[];
}

interface KartAdapterOptions {
  readonly name: string;
  readonly version: string;
  readonly manifest: GameManifest;
  readonly compiled: CompiledRacer;
  readonly tickRate: number;
  readonly bots: number;
  readonly roundSeconds: number | null;
  readonly runner?: RaceRunnerOptions;
}

interface KartRoomWorld {
  readonly role: "server" | "client";
  readonly core: KartCore;
  readonly runner: RaceRunner | null;
}

interface KillFeedEntry {
  readonly by: number;
  readonly victim: number;
  readonly ago: number;
}

interface PlanResult {
  readonly found: boolean;
  readonly seconds: number;
  readonly bestX: number;
  readonly expanded: number;
  readonly tape: readonly InputCommand[];
}

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;
}

interface PlatformBotMemory {
  bestX: number;
  since: number;
  holdJump: number;
  tape?: readonly InputCommand[] | null;
  tapeAt?: number;
}

interface PlatformRoomWorld {
  readonly role: "server" | "client";
  readonly core: PlatformCore;
  readonly runner: RaceRunner | null;
}

interface ProfileSku {
  readonly id: string;
  readonly kind: SkuKind;
  readonly coins: number | null;
  readonly grants: SkuGrant | null;
}

interface ProfileSpec {
  readonly keepers: readonly { readonly id: string; readonly unlock: string | null; readonly sold: boolean }[];
  readonly achievements: readonly string[];
  readonly missions: ReadonlyMap<string, { readonly when: string; readonly n: number }>;
  readonly titles: readonly string[];
  readonly skus: ReadonlyMap<string, ProfileSku>;
  readonly meta: ReadonlyMap<string, MetaUpgradeDef>;
  readonly economy: EconomyDef;
}

interface ProfileUnlockState {
  readonly achievements: Iterable<string>;
  readonly imported?: Iterable<string>;
  readonly owned: Iterable<string>;
}

interface RaceCore {
  readonly 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;
}

interface RaceInfo {
  readonly run: number;
  readonly phase: RacePhase;
  readonly course: number;
  readonly countdown: number;
  readonly seconds: number;
  readonly left: number | null;
  readonly players: readonly RacePlayerInfo[];
  readonly announce: { readonly id: number; readonly text: string; readonly tone: "info" | "danger" | "reward" } | null;
  readonly next: { readonly label: string; readonly in: number } | null;
  readonly nextRunIn: number | null;
  readonly coins: readonly { readonly id: number; readonly rules: readonly { readonly rule: string; readonly units: number }[] }[];
}

type RacePhase = "countdown" | "racing" | "results";

interface RacePlayerInfo {
  readonly id: number;
  readonly bot: boolean;
  readonly place: number | null;
  readonly time: number | null;
  readonly progress: number;
  readonly rank: number;
  readonly counts: Readonly<Record<string, number>>;
  readonly ready: boolean;
}

interface RaceRunnerOptions {
  readonly countdownSeconds?: number;
  readonly endSeconds?: number;
  readonly graceSeconds?: number;
  readonly finishWindowSeconds?: number;
}

interface RaceSimEvent {
  readonly name: string;
  readonly player: number;
}

interface RaceStep {
  readonly events: readonly GameEvent[];
  readonly awards: readonly EarnAward[];
  readonly reset: boolean;
}

interface RunInfo {
  readonly run: number;
  readonly phase: RunPhase;
  readonly seconds: number;
  readonly wave: number;
  readonly kills: number;
  readonly enemies: number;
  readonly boss: { readonly prefab: string; readonly health: number; readonly max: number } | null;
  readonly bosses: readonly { readonly prefab: string; readonly health: number; readonly max: number; readonly x: number; readonly z: number }[];
  readonly paused: boolean;
  readonly announce: { readonly id: number; readonly text: string; readonly tone: "info" | "danger" | "reward" } | null;
  readonly players: readonly RunPlayerInfo[];
  readonly nextRunIn: number | null;
  readonly round: { readonly seconds: number; readonly left: number; readonly frags: number | null } | null;
  readonly feed: readonly KillFeedEntry[];
  readonly next: { readonly label: string; readonly in: number } | null;
  readonly summary: RunSummary | null;
}

interface RunnerOptions {
  readonly holdEnemies?: number;
  readonly godMode?: boolean;
  readonly holdMix?: boolean;
  readonly loseGraceSeconds?: number;
  readonly endSeconds?: number;
}

interface RunnerStep {
  readonly events: readonly GameEvent[];
  readonly awards: readonly EarnAward[];
  readonly reset: boolean;
}

type RunPhase = "playing" | "won" | "lost";

interface RunPlayerInfo {
  readonly id: number;
  readonly level: number;
  readonly kills: number;
  readonly downed: boolean;
  readonly dead: boolean;
  readonly deaths: number;
  readonly bot: boolean;
  readonly keeper: string | null;
  readonly buffed: boolean;
  readonly counts: Readonly<Record<string, number>>;
  readonly achievements: readonly string[];
  readonly ready: boolean;
}

interface RunProgress {
  readonly player: number;
  readonly kind: "achievement" | "goal" | "title";
  readonly id: string;
}

type SkuKind = "consumable" | "cosmetic" | "unlock" | "gear";

interface ThreatShape {
  readonly kind: "circle" | "lane" | "aura";
  readonly x: number;
  readonly z: number;
  readonly r: number;
  readonly dx?: number;
  readonly dz?: number;
  readonly len?: number;
  readonly progress: number;
  readonly shot?: boolean;
}