@netforge/engine API reference

import { game, prefab, engine } from "@netforge/engine";

function achievement(id: string, def: AchievementInput): AchievementDef;

function card(id: string, def: CardInput): CardDef;

function cardTable(def: CardTableInput): CardTableDef;

function creature(id: string, def: CreatureInput): CreatureDef;

function director(def: DirectorInput): DirectorDef;

function dungeon(spec: DungeonSpec): DungeonLayout;

function economy(def?: EconomyInput): EconomyDef;

function game(def: GameInput): GameDef;

function keeper(id: string, def: KeeperInput): KeeperDef;

function marsh(def: MarshInput): MarshDef;

function metaUpgrade(id: string, def: MetaUpgradeInput): MetaUpgradeDef;

function mission(id: string, def: MissionInput): MissionDef;

function move(id: string, def: MoveInput): MoveDef;

function plant(id: string, def: PlantInput): PlantDef;

function prefab(id: string, def: PrefabInput): PrefabDef;

function saltFlat(def: SaltFlatInput): SaltFlatDef;

function system(name: string, setup: SystemSetup): void;

function title(id: string, def: TitleInput): TitleDef;

function tower(id: string, def: TowerInput): TowerDef;

function towerBoard(def: TowerBoardInput): TowerBoardDef;

function upgrade(id: string, def: UpgradeInput): UpgradeDef;

function waves(def: WavesInput): WavesDef;

function weapon(id: string, def: WeaponInput): WeaponDef;

class GameDefinitionError {
  constructor(where: string, issues: readonly string[]);
  readonly issues: readonly string[];
}

const AI_BEHAVIOURS: readonly ["none", "chase", "idle", "tank", "runner", "charger", "ranged", "bomber", "shielder", "healer", "summoner", "flee", "wander"];

const APPEARANCE_PARTS: readonly ["horns", "ears_long", "ears_round", "antenna", "crown", "hat_cap", "hat_top", "mustache", "tail", "tail_bolt", "wings", "armor", "backpack", "big_wheels"];

const appearanceSchema: z.ZodObject<{ tint: z.ZodOptional<z.ZodString>; accent: z.ZodOptional<z.ZodString>; scale: z.ZodOptional<z.ZodNumber>; parts: z.ZodDefault<z.ZodArray<z.ZodEnum<{ horns: "horns"; ears_long: "ears_long"; ears_round: "ears_round"; antenna: "antenna"; crown: "crown"; hat_cap: "hat_cap"; hat_top: "hat_top"; mustache: "mustache"; tail: "tail"; tail_bolt: "tail_bolt"; wings: "wings"; armor: "armor"; backpack: "backpack"; big_wheels: "big_wheels"; }>>>; }, z.core.$strict>;

const CARD_STATS: readonly ["maxHealth", "might", "haste", "amount"];

const COLLECTOR_STATS: readonly ["might", "maxHealth", "armor", "amount", "regen"];

const DECAL_PRESETS: readonly ["none", "scorch", "splat", "ring"];

const dungeonSchema: z.ZodObject<{ seed: z.ZodNumber; rooms: z.ZodNumber; cell: z.ZodDefault<z.ZodNumber>; size: z.ZodDefault<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>; corridor: z.ZodDefault<z.ZodNumber>; loops: z.ZodDefault<z.ZodNumber>; }, z.core.$strict>;

const earn: { rule(id: string, def: EarnRuleInput): EarnRuleDef; stake(def: EarnStakeInput): EarnStakeDef; pot(def: EarnPotInput): EarnPotDef; };

const EFFECT_KINDS: readonly ["damage", "heal", "draw", "buff"];

const EFFECT_TARGETS: readonly ["enemy", "enemy_hero", "all_enemies", "own_hero", "own_unit", "all_own"];

const ELEMENTS: readonly ["root", "tide", "spark", "stone"];

const engine: { readonly test: { readonly run: (opts: HarnessOptions) => Promise<HarnessReport>; }; };

const IDLE_MAX_TEND: 300;

const IDLE_MIN_SHIFT: 600;

const IDLE_STATS: readonly ["might", "haste", "amount"];

const LOOK_PRESETS: readonly ["night", "dusk", "day", "studio"];

const META_MAX_LEVELS: 5;

const META_MAX_PER_STAT: 0.15;

const META_MAX_TOTAL: 0.3;

const META_MAX_UPGRADES: 8;

const META_MIN_GROWTH: 1.5;

const META_STATS: readonly ["speed", "maxHealth", "magnet", "might", "haste", "area"];

const MOVE_EFFECTS: readonly ["none", "drain", "heal", "guard"];

const PARTICLE_PRESETS: readonly ["sparks", "burst", "embers", "smoke", "hitSpark", "dust", "magic"];

const PLANT_KINDS: readonly ["pump", "pan", "kiln"];

const POT_REASON: "pot";

const SOUND_CUES: readonly ["none", "hit", "crunch", "boom", "zap", "chime", "thud"];

const STAKE_MAX_COINS: 1000000;

const STAKE_MAX_MULTIPLE: 2;

const STAKE_REASON: "stake";

const STAT_KINDS: readonly ["speed", "maxHealth", "magnet", "might", "haste", "regen", "armor", "area", "amount"];

const store: { sku(id: string, def: SkuInput): SkuDef; };

const STYLES: readonly ["pixel", "lowpoly", "toon", "voxel", "ps1", "handdrawn"];

const TEMPLATES: readonly ["survivor", "arena", "dungeon", "racer", "platformer", "tower-defense", "party", "idle", "cards", "collector"];

const TITLE_STATS: readonly ["kills", "damage", "revives", "downs", "level", "pickups"];

const TOWER_KINDS: readonly ["bolt", "splash", "frost", "chain"];

const TOWER_STATS: readonly ["might", "haste", "area", "maxHealth"];

const WEAPON_KINDS: readonly ["nova", "bolt", "orbit", "blaster", "beam", "cone", "chain", "aura", "meteor", "boomerang"];

type AchievementDef = z.output<typeof achievementSchema>;

type AchievementInput = z.input<typeof achievementSchema>;

type AppearanceDef = z.output<typeof appearanceSchema>;

type AppearanceInput = z.input<typeof appearanceSchema>;

type AppearancePart = (typeof APPEARANCE_PARTS)[number];

type AssetId = string;

type CardDef = z.output<typeof cardSchema>;

type CardInput = z.input<typeof cardSchema>;

type CardTableDef = z.output<typeof cardTableSchema>;

type CardTableInput = z.input<typeof cardTableSchema>;

type CreatureDef = z.output<typeof creatureSchema>;

type CreatureInput = z.input<typeof creatureSchema>;

type Curve = z.output<typeof curveSchema>;

type CurveInput = z.input<typeof curveSchema>;

type DecalPreset = (typeof DECAL_PRESETS)[number];

type DirectorDef = z.output<typeof directorSchema>;

type DirectorInput = z.input<typeof directorSchema>;

interface DungeonLayout {
  readonly field: { readonly halfSize: number; readonly pillars: [number, number, number][]; readonly walls: Box[]; readonly floors: Box[] };
  readonly rooms: readonly DungeonRoom[];
  readonly start: DungeonRoom;
  readonly boss: DungeonRoom;
  roomAt(x: number, z: number): number;
}

interface DungeonRoom {
  readonly id: number;
  readonly x: number;
  readonly z: number;
  readonly hx: number;
  readonly hz: number;
  readonly depth: number;
  readonly links: readonly number[];
}

type DungeonSpec = z.input<typeof dungeonSchema>;

type EarnPotDef = z.output<typeof earnPotSchema>;

type EarnPotInput = z.input<typeof earnPotSchema>;

type EarnRuleDef = z.output<typeof earnRuleSchema>;

type EarnRuleInput = z.input<typeof earnRuleSchema>;

type EarnStakeDef = z.output<typeof earnStakeSchema>;

type EarnStakeInput = z.input<typeof earnStakeSchema>;

type EconomyDef = z.output<typeof economySchema>;

type EconomyInput = z.input<typeof economySchema>;

type EdgeSide = "any" | "ahead" | "behind" | "north" | "south" | "east" | "west";

type Element = (typeof ELEMENTS)[number];

type FeelDef = z.output<typeof feelSchema>;

interface FunMetrics {
  readonly genre: "horde" | "arena" | "race";
  readonly firstThreatSeconds: number | null;
  readonly firstRewardSeconds: number | null;
  readonly levelAt: { readonly "60": number | null; readonly "180": number | null; readonly "360": number | null; readonly "540": number | null };
  readonly deathsBeforeMinute: number | null;
  readonly onScreenAt30: number | null;
  readonly contactHitsFirstMinute: number | null;
  readonly telegraphedDeathShare: number | null;
  readonly spawnsOnScreen: number | null;
  readonly survivalSeconds: number | null;
  readonly spawnToDamageSeconds: number | null;
  readonly spawnDeathShare: number | null;
  readonly killSpread: number | null;
  readonly leadChanges: number | null;
  readonly bossKills: readonly { readonly prefab: string; readonly seconds: number }[];
  readonly downsBySource: Readonly<Record<string, number>>;
  readonly firstHitSeconds?: number | null;
  readonly lowestHealthBy120?: number | null;
  readonly firstEliteSeconds?: number | null;
  readonly firstBossSeconds?: number | null;
  readonly downTimeShare?: number | null;
  readonly finishSeconds?: number | null;
  readonly finishRate?: number | null;
  readonly mishapsPerRound?: number | null;
  readonly firstCoinSeconds?: number | null;
  readonly routes?: readonly { readonly course: number; readonly found: boolean; readonly seconds: number | null }[];
}

type GameDef = z.output<typeof gameSchema>;

type GameInput = z.input<typeof gameSchema>;

interface GameManifest {
  readonly game: GameDef;
  readonly prefabs: ReadonlyMap<string, PrefabDef>;
  readonly weapons: ReadonlyMap<string, WeaponDef>;
  readonly upgrades: ReadonlyMap<string, UpgradeDef>;
  readonly systems: ReadonlyMap<string, SystemSetup>;
  readonly earnRules: ReadonlyMap<string, EarnRuleDef>;
  readonly stake: EarnStakeDef;
  readonly pot: EarnPotDef | null;
  readonly skus: ReadonlyMap<string, SkuDef>;
  readonly director: DirectorDef | null;
  readonly keepers: ReadonlyMap<string, KeeperDef>;
  readonly achievements: ReadonlyMap<string, AchievementDef>;
  readonly missions: ReadonlyMap<string, MissionDef>;
  readonly titles: ReadonlyMap<string, TitleDef>;
  readonly economy: EconomyDef;
  readonly metaUpgrades: ReadonlyMap<string, MetaUpgradeDef>;
  readonly content: ReadonlyMap<string, unknown>;
}

interface HarnessAssertion {
  readonly name: string;
  readonly check: (report: HarnessReport) => boolean;
}

interface HarnessOptions {
  readonly ticks: number;
  readonly bots: number;
  readonly enemies?: number;
  readonly seed?: number;
  readonly tickRate?: number;
  readonly assert?: readonly HarnessAssertion[];
  readonly bot?: "basic" | "human";
  readonly picks?: "random" | "greedy";
  readonly enemyMix?: boolean;
}

interface HarnessReport {
  readonly ticks: number;
  readonly bots: number;
  readonly deaths: number;
  readonly kills: number;
  readonly wave: number;
  readonly runs: { readonly won: number; readonly lost: number };
  readonly maxLevel: number;
  readonly peakEnemies: number;
  readonly topScore: number;
  readonly scorers: number;
  readonly earned: Readonly<Record<string, number>>;
  readonly msPerTick: number;
  readonly p99MsPerTick: number;
  readonly earnEmitted: number;
  readonly softlock: boolean;
  readonly fun?: FunMetrics;
  readonly rules?: { readonly template: string; readonly checks: readonly { readonly ok: boolean; readonly line: string }[]; readonly progress: number };
  readonly failed: readonly string[];
}

type KeeperDef = z.output<typeof keeperSchema>;

type KeeperInput = z.input<typeof keeperSchema>;

type LookDef = z.output<typeof lookSchema>;

type LookInput = z.input<typeof lookSchema>;

type LookPreset = (typeof LOOK_PRESETS)[number];

type MarshDef = z.output<typeof marshSchema>;

type MarshInput = z.input<typeof marshSchema>;

type MetaStat = (typeof META_STATS)[number];

type MetaUpgradeDef = z.output<typeof metaUpgradeSchema>;

type MetaUpgradeInput = z.input<typeof metaUpgradeSchema>;

type MissionDef = z.output<typeof missionSchema>;

type MissionInput = z.input<typeof missionSchema>;

type MoveDef = z.output<typeof moveSchema>;

type MoveInput = z.input<typeof moveSchema>;

type ParticlePreset = (typeof PARTICLE_PRESETS)[number];

type PlantDef = z.output<typeof plantSchema>;

type PlantInput = z.input<typeof plantSchema>;

interface PlayerView {
  readonly id: number;
  readonly position: readonly [number, number, number];
  readonly health: number;
  readonly alive: boolean;
  readonly kills: number;
  readonly deaths: number;
  readonly bot: boolean;
}

type PrefabDef = z.output<typeof prefabSchema>;

type PrefabInput = z.input<typeof prefabSchema>;

type SaltFlatDef = z.output<typeof saltFlatSchema>;

type SaltFlatInput = z.input<typeof saltFlatSchema>;

type SkuDef = z.output<typeof skuSchema>;

type SkuGrant = z.output<typeof skuGrantSchema>;

type SkuInput = z.input<typeof skuSchema>;

type SoundCue = (typeof SOUND_CUES)[number];

interface SpawnEdgeOptions {
  readonly count: number;
  readonly around?: number;
  readonly side?: EdgeSide;
  readonly spread?: number;
  readonly scale?: { readonly health?: number; readonly damage?: number; readonly xp?: number };
  readonly elite?: boolean;
}

interface SpawnRingOptions {
  readonly count: number;
  readonly radius: number;
  readonly around?: number;
}

type Style = (typeof STYLES)[number];

interface SystemContext {
  readonly tick: () => number;
  readonly time: () => number;
  readonly players: () => readonly PlayerView[];
  readonly every: (seconds: number, fn: (n: number) => void) => void;
  readonly after: (seconds: number, fn: () => void) => void;
  readonly onTick: (fn: () => void) => void;
  readonly spawn: (prefab: string, at: readonly [number, number, number], opts?: { readonly elite?: boolean }) => void;
  readonly spawnRing: (prefab: string, opts: SpawnRingOptions) => void;
  readonly spawnEdge: (prefab: string, opts: SpawnEdgeOptions) => number;
  readonly emit: (event: string, players?: readonly number[]) => void;
  readonly random: () => number;
  readonly alive: (prefab?: string) => number;
  readonly on: (event: string, fn: (players: readonly number[]) => void) => void;
  readonly respawnDead: () => void;
  readonly end: (outcome: "won" | "lost") => void;
  readonly spawnPickup: (prefab: string, at: readonly [number, number, number]) => void;
  readonly announce: (text: string, opts?: { readonly tone?: "info" | "danger" | "reward" }) => void;
  readonly bossAlive: () => boolean;
  readonly pauseDirector: (seconds: number) => void;
  readonly surge: (multiplier: number, seconds: number) => void;
  readonly upcoming: (label: string, seconds: number) => void;
  readonly xpBoost: (multiplier: number, seconds: number) => void;
  readonly scatter: (prefab: string, count: number) => number;
  readonly clear: (prefab: string) => number;
  readonly onScreen: (x: number, z: number) => boolean;
}

type SystemSetup = (ctx: SystemContext) => void;

type Template = (typeof TEMPLATES)[number];

type TitleDef = z.output<typeof titleSchema>;

type TitleInput = z.input<typeof titleSchema>;

type TitleStat = (typeof TITLE_STATS)[number];

type TowerBoardDef = z.output<typeof towerBoardSchema>;

type TowerBoardInput = z.input<typeof towerBoardSchema>;

type TowerDef = z.output<typeof towerSchema>;

type TowerInput = z.input<typeof towerSchema>;

type UpgradeDef = z.output<typeof upgradeSchema>;

type UpgradeInput = z.input<typeof upgradeSchema>;

type WavesDef = z.output<typeof wavesSchema>;

type WavesInput = z.input<typeof wavesSchema>;

type WeaponDef = z.output<typeof weaponSchema>;

type WeaponInput = z.input<typeof weaponSchema>;