@netforge/engine/rules API reference

import { rulesAdapter } from "@netforge/engine/rules";

function avatarEntity(player: number, a: Avatar): EntityState;

function bestTowerTile(g: CompiledTowerGame, occupied: ReadonlySet<number>, type: number, salt: number, jitter?: number): { tx: number; ty: number; } | null;

function cardsGenre(m: GameManifest): RulesGenre<CardsState> & { readonly game: CompiledCards; };

function collectorGenre(m: GameManifest): RulesGenre<CollectorState> & { readonly game: CompiledCollector; };

function compileBoard(def: { size: readonly [number, number]; path: readonly (readonly [number, number])[]; blocked: readonly (readonly [number, number])[]; }): CompiledBoard;

function compileCards(m: GameManifest): CompiledCards;

function compileCollector(m: GameManifest): CompiledCollector;

function compileIdleGame(m: GameManifest): CompiledIdleGame;

function compileTowerGame(m: GameManifest): CompiledTowerGame;

function effectiveness(attack: number, defend: number): number;

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;

function genreFor(m: GameManifest): RulesGenre<unknown>;

function hpAt(base: number, level: number): number;

function idleGenre(m: GameManifest): RulesGenre<IdleState> & { readonly game: CompiledIdleGame; policyInput(s: IdleState, player: number, a: Avatar, tick: number, policy: IdlePolicy): RulesInput; };

function isRulesBot(p: number): boolean;

function isRulesTemplate(template: string): boolean;

function labelledContent(m: GameManifest): string[];

function marshCenter(map: Pick<CompiledMarsh, "w" | "h">, tx: number, ty: number): { x: number; z: number; };

function marshRoute(map: CompiledMarsh, from: number, goal: number): number[];

function marshTile(map: Pick<CompiledMarsh, "w" | "h">, x: number, z: number): number;

function plantCost(g: CompiledIdleGame, i: number, level: number): number;

function plantSpot(i: number): { x: number; z: number; };

function playRules<S>(genre: RulesGenre<S>, manifest: GameManifest, opts: HarnessOptions): RulesPlaytest;

function plotCenter(slot: number): { x: number; z: number; };

function rand(r: Rng): number;

function randInt(r: Rng, n: number): number;

function roadCoverage(b: CompiledBoard, rangeQ: number): Int32Array;

function roadPoint(b: CompiledBoard, d: number): { qx: number; qy: number; yaw: number; };

function rulesAdapter<S>(genre: RulesGenre<S>, manifest: GameManifest, opts: RulesAdapterOptions): SimAdapter<RulesWorld<S>, RulesInput> & { readonly genre: RulesGenre<S>; readonly manifest: GameManifest; };

function shuffle<T>(r: Rng, list: T[]): T[];

function statAt(base: number, level: number): number;

function tileAt(b: Pick<CompiledBoard, "w" | "h">, x: number, z: number): { tx: number; ty: number; } | null;

function tileCenter(b: Pick<CompiledBoard, "w" | "h">, tx: number, ty: number): { x: number; z: number; };

function tileKey(x: number, y: number): number;

function towerGenre(m: GameManifest): RulesGenre<TowerState> & { readonly game: CompiledTowerGame; };

function wavePreview(g: CompiledTowerGame, n: number): { type: number; count: number; }[];

function waveSpawns(g: CompiledTowerGame, n: number, tickRate: number): Spawn[];

function works(g: CompiledIdleGame, w: Pick<Works, "levels">, might: number): { pump: number; pan: number; kiln: number; };

function xpNeed(level: number): number;

const CardAct: { readonly Play: 1; readonly Attack: 2; readonly End: 3; readonly Draft: 4; };

const CollectorAct: { readonly Pick: 1; readonly Move: 2; readonly Swap: 3; readonly Snare: 4; readonly Flee: 5; readonly Challenge: 6; };

const CreepFlag: { readonly Slowed: 1; readonly Boss: 2; readonly Dead: 4; readonly Leaked: 8; };

const ENTITY_BASE: 65536;

const IDLE_INPUT: RulesInput;

const IDLE_MIN_FIRST_EARN: 180;

const IDLE_SEATS: number;

const IdleAct: { readonly Rake: 1; readonly Buy: 2; readonly Ship: 3; };

const LogKind: { readonly Hit: 1; readonly Miss: 2; readonly Heal: 3; readonly Guard: 4; readonly Swap: 5; readonly Snared: 6; readonly Slipped: 7; readonly Fled: 8; readonly Won: 9; readonly Fainted: 10; readonly Wiped: 11; readonly Level: 12; readonly Met: 13; readonly Warden: 14; };

const MARSH_TILE: 2;

const MILLI: 1000;

const PLOT: { readonly w: 12; readonly d: 10; readonly cols: 4; readonly rows: 2; readonly gapX: 1.5; readonly gapZ: 5; };

const Q: 256;

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

const RULES_BOT_BASE: 65280;

const RULES_SCHEMA: EntitySchema;

const rulesInputCodec: InputCodec<RulesInput>;

const RulesKind: { readonly Avatar: 1; readonly Unit: 2; readonly Shot: 3; readonly Structure: 4; readonly Pickup: 5; };

const Target: { readonly None: 0; readonly EnemyHero: 1; readonly OwnHero: 2; readonly EnemyUnit: 10; readonly OwnUnit: 20; };

const TILE_M: 2;

const TowerAct: { readonly Build: 1; readonly Upgrade: 2; readonly Sell: 3; readonly Ready: 4; };

const UNITS: 64;

interface Avatar {
  x: number;
  z: number;
  yaw: number;
  cosmetic: number;
  flags: number;
}

interface CardsState {
  rng: { s: number };
  ctx: RulesContext;
  tick: number;
  stage: "waiting" | "duel" | "draft" | "done";
  duelNo: number;
  duel: Duel | null;
  countdown: number;
  players: Map<number, CardPlayer>;
  alone: number;
  log: LogLine[];
  finished: number;
  draws: number;
  peakBoard: number;
  activity: number;
  turnsPlayed: number[];
}

interface CollectorState {
  rng: { s: number };
  ctx: RulesContext;
  tick: number;
  dusk: number;
  wardenHp: number;
  wardenMax: number;
  wardenDown: boolean;
  wardenHurt: Set<number>;
  keepers: Map<number, Keeper>;
  activity: number;
  battlesWon: number;
  catches: number;
  wipes: number;
  peakBattles: number;
}

interface CompiledBoard {
  readonly w: number;
  readonly h: number;
  readonly path: readonly (readonly [number, number])[];
  readonly cum: readonly number[];
  readonly length: number;
  readonly road: ReadonlySet<number>;
  readonly blocked: ReadonlySet<number>;
}

interface CompiledCards {
  readonly table: CardTableDef;
  readonly cards: readonly { readonly id: string; readonly def: CardDef }[];
  readonly starter: readonly number[];
  readonly pool: readonly number[];
}

interface CompiledCollector {
  readonly marsh: MarshDef;
  readonly map: CompiledMarsh;
  readonly creatures: readonly (CreatureDef & { id: string; el: number; moveIdx: number[] })[];
  readonly moves: readonly (MoveDef & { id: string; el: number })[];
  readonly starters: readonly number[];
  readonly wardenSpecies: number;
  readonly pools: readonly { rate: number; pool: { species: number; weight: number; level: readonly [number, number] }[] }[];
}

interface CompiledIdleGame {
  readonly shiftTicks: number;
  readonly tendTicks: number;
  readonly start: number;
  readonly rakeSalt: number;
  readonly rakeTicks: number;
  readonly brinePerSalt: number;
  readonly saltPerCrystal: number;
  readonly packEvery: number;
  readonly contract: number;
  readonly plants: readonly { readonly id: string; readonly def: PlantDef }[];
}

interface CompiledMarsh {
  readonly w: number;
  readonly h: number;
  readonly blocked: Uint8Array;
  readonly water: Uint8Array;
  readonly grass: Uint8Array;
  readonly camp: readonly [number, number];
  readonly warden: readonly [number, number];
}

interface CompiledTower {
  readonly id: string;
  readonly def: TowerDef;
  readonly levels: readonly TowerStats[];
  readonly upgradeCost: readonly number[];
}

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

type IdlePolicy = "best" | "human" | "clicker" | "idle";

interface IdleState {
  rng: { s: number };
  ctx: RulesContext;
  tick: number;
  players: Map<number, Works>;
  contract: number;
  filled: boolean;
  done: boolean;
  activity: number;
}

interface LogLine {
  readonly n: number;
  readonly kind: number;
  readonly who: 0 | 1;
  readonly move?: number;
  readonly dmg?: number;
  readonly eff?: number;
  readonly value?: number;
}

interface Mon {
  species: number;
  level: number;
  hp: number;
  xp: number;
  guard: boolean;
}

interface Rng {
  s: number;
}

interface RulesAdapterOptions {
  readonly name: string;
  readonly version: string;
}

interface RulesCheck {
  readonly ok: boolean;
  readonly line: string;
}

interface RulesContext {
  bonus(player: number, stat: string): number;
  isBot(player: number): boolean;
}

interface RulesGenre<S> {
  readonly template: string;
  readonly tickRate: number;
  readonly endSeconds: number;
  readonly infoEveryTicks: number;
  create(seed: number, ctx: RulesContext): S;
  spawn(s: S | null, player: number): { x: number; z: number };
  moveAvatar(a: Avatar, input: RulesInput): void;
  join(s: S, player: number): void;
  leave(s: S, player: number): void;
  act(s: S, player: number, input: RulesInput, avatar: Avatar, emit: (e: GameEvent) => void): void;
  tend?(s: S, player: number, avatar: Avatar, emit: (e: GameEvent) => void): void;
  step(s: S, emit: (e: GameEvent) => void): void;
  outcome(s: S): RunOutcome | null;
  view(s: S, player: number | null): Record<string, unknown>;
  entities(s: S, out: EntityState[]): void;
  seats?(s: S, humans: number): number;
  bot(s: S, player: number, avatar: Avatar, tick: number, skill: number): RulesInput;
  stats(s: S): RulesStats;
  activity(s: S): number;
  checks(run: RulesHarnessRun): RulesCheck[];
  progress(run: RulesHarnessRun): number;
}

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>>;
  readonly firstEarnSeconds: number | null;
  readonly firstRunSeconds: number | null;
}

interface RulesInput {
  readonly mx: number;
  readonly mz: number;
  readonly cx: number;
  readonly cz: number;
  readonly act: number;
  readonly a: number;
  readonly b: number;
  readonly c: number;
}

interface RulesPlaytest {
  readonly report: HarnessReport;
  readonly run: RulesHarnessRun;
}

interface RulesStats {
  readonly kills: number;
  readonly wave: number;
  readonly level: number;
  readonly deaths: number;
  readonly peakUnits: number;
  readonly scorers: number;
  readonly topScore: number;
}

interface RulesWorld<S = unknown> {
  readonly role: "server" | "client";
  state: S | null;
  readonly avatars: Map<PlayerId, Avatar>;
  tick: number;
  runTick: number;
  phase: "playing" | "ended";
  outcome: RunOutcome | null;
  endTick: number;
  readonly earn: EarnTracker | null;
  readonly late: Set<PlayerId>;
  progressed: boolean;
  readonly upgrades: Map<PlayerId, Map<string, number>>;
  readonly paid: Map<PlayerId, Set<string>>;
  readonly bots: Set<PlayerId>;
  awards: number;
}

type RunOutcome = "won" | "lost";

interface TowerState {
  rng: { s: number };
  ctx: RulesContext;
  tick: number;
  wave: number;
  phase: "build" | "wave";
  countdown: number;
  lives: number;
  livesMax: number;
  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;
  activity: number;
}

interface Works {
  slot: number;
  brine: number;
  salt: number;
  crystals: number;
  made: number;
  packs: number;
  cutAcc: number;
  cut: number;
  levels: number[];
  lastTend: number;
  rakeAt: number;
  shipped: number;
  rakes: number;
}