API reference

const createApp: (options?: {
  plugins?: readonly AnyPluginInstance[];
  config?: { orientation?: "portrait" | "landscape"; referenceSide?: number; referenceLong?: number };
  pluginConfigs?: { [pluginName: string]: Partial<PluginConfig> };
  onReady?: (ctx: AppCallbackContext) => void;
  onError?: (error: Error, ctx: AppCallbackContext) => void;
  onStart?: (ctx: AppCallbackContext) => void | Promise<void>;
  onStop?: (ctx: AppCallbackContext) => void | Promise<void>;
}) => App;

const createPlugin: (name: string, spec: PluginSpec) => PluginInstance;

function defineGame<Types extends Flow.GameTypes>(): GameKit<Types>;

type GameTypes = {
  player: Json;
  session: Json;
  assets: string;
  strings: Record<string, unknown>;
  bundles?: string;
  scenes?: string;
  textStyles?: string;
  textFormats?: string;
  emitters?: string;
  hud?: string;
};

function type<Payload = void>(): TypeTag<Payload>;
function exit<const Name extends string>(outcome: Name): Exit<Name>;
function to<const Target extends string, Payload, Output>(target: Target, map: (payload: Payload) => Output): Mapped<Target, Payload, Output>;
function slot<const Name extends string, const Tags extends OutcomeTags = {}>(name: Name, outcomes?: Tags): SlotNode<Tags, Name>;
function contribution(slot: SlotNode, spec: { flow: AnyFlow; order: number; when?: (snapshot: Snapshot) => boolean }): Record<string, ContributionSpec>;
function defineFeature(name: string, description: FeatureDescription): FeaturePlugin;
function flattenFeatures(list: readonly FeatureTree[]): FeatureTree[];

function schedule(moment: number | undefined): Descriptor<void>;
function guide(options: GuideOptions): Descriptor<void>;
function hint(kind: string, payload?: Json): Hint;
function defineEffect<Payload, Result>(kind: string, options?: { fast?: "run" | "skip"; cosmetic?: boolean }): Effect<Payload, Result>;

class SaveUnreadableError extends Error {
  savedVersion: number;
  schemaVersion: number;
}

const timePlugin: PluginInstance<"time">;
const lifecyclePlugin: PluginInstance<"lifecycle">;
const modelPlugin: PluginInstance<"model">;
const clockPlugin: PluginInstance<"clock">;
const flowPlugin: PluginInstance<"flow">;
const worldPlugin: PluginInstance<"world">;
const rendererPlugin: PluginInstance<"renderer">;
const inputPlugin: PluginInstance<"input">;
const assetsPlugin: PluginInstance<"assets">;
const scenesPlugin: PluginInstance<"scenes">;
const animPlugin: PluginInstance<"anim">;
const i18nPlugin: PluginInstance<"i18n">;
const textPlugin: PluginInstance<"text">;
const uiPlugin: PluginInstance<"ui">;
const effectsPlugin: PluginInstance<"effects">;
const audioPlugin: PluginInstance<"audio">;
const platformPlugin: PluginInstance<"platform">;
const debugPlugin: PluginInstance<"debug">;
const screen: readonly [worldPlugin, rendererPlugin, inputPlugin, assetsPlugin, scenesPlugin, animPlugin, i18nPlugin, textPlugin, uiPlugin];

function component<Value extends object>(name: string, defaults: Value, options?: { owned?: readonly (keyof Value)[] }): ComponentType<Value>;
function tag(name: string): TagType;
function resource<Value extends object>(name: string, defaults: Value | (() => Value)): ResourceType<Value>;
function mut<Value extends object>(component: ComponentHandle<Value>): Mut<Value>;
function system<const Terms extends readonly QueryTerm[]>(definition: {
  name: string;
  phase: "input" | "animate" | "layout" | "sync";
  query: Terms;
  scenes?: readonly string[];
  run(entities: Iterable<QueryTuple<Terms>>, ctx: { world; res; snapshot; time; resumed }): void;
}): SystemDefinition<Terms>;
function projection<Item>(spec: ProjectionSpec<Item>): ProjectionSpec<Item>;

const Layer: ComponentType<{ name: string }>;
const Order: ComponentType<{ value: number }>;
const Tree: ComponentType<{ node: DescriptionNode }>;
const Exiting: TagType;
const Now: ResourceType<{ now: number }>;

const Transform: ComponentType<{ x: number; y: number; rotation: number; scale: number }>;
const Sprite: ComponentType<SpriteValue>;
const NineSlice: ComponentType<NineSliceValue>;
const Shape: ComponentType<ShapeValue>;
const Parent: ComponentType<{ entity: Entity }>;
const Display: ComponentType<DisplayValue>;
const Overlay: ComponentType<OverlayValue>;
const HudPart: ComponentType<{ key: string }>;
function sprite(options: SpriteOptions): [SpriteValue, TransformValue];

function frameAt(ring: FrameRing, age: number): FrameRecord | undefined;
const PERF_LOG_VERSION = 1;
const PERF_GAP_BUCKETS = 81;
const PERF_CAUSES: readonly ["gap", "js", "gpu", "compile", "upload", "longFrame", "gc?"];
const MONITOR_SECTIONS: readonly ["gpu", "passes", "shaders", "problems", "memory", "systems", "nodes", "longFrames"];
const DEMAND_REASONS: readonly ["always", "first", "resize", "restore", "layers", "debug", "wake", "capture", "request", "mark", "verify", "none", "overlay", "retake"];
const PASS_KINDS: readonly ["canvas", "texture", "filter"];
const CANVAS_RESTARTS: readonly ["none", "first", "filter", "mask", "depth", "empty"];
const SHADER_WHATS: readonly ["compile", "module"];
const PROBLEM_RULES: readonly ["filter-still", "target-churn", "retakes"];

const Tappable: ComponentType<{ intent: string; payload: Json }>;
const Pressable: ComponentType<{ intent: string; payload: Json }>;
const Draggable: ComponentType<{ payload: Json; carry?: unknown; aim?: { x: number; y: number } | null }>;
const DropTarget: ComponentType<{ intent: string; payload: Json }>;
const Swipeable: ComponentType<{ intent: string; payload: Json }>;
const Traceable: ComponentType<{ intent: string; payload: Json }>;
const Touchable: TagType;
const Held: TagType;
const Hovered: TagType;
const PointerOver: TagType;
const Pressed: TagType;
const Traced: TagType;
const Pointer: ResourceType<PointerValue>;

function defineBundles<Key extends string>(map: Partial<Record<Key, { tier: Tier; files?: readonly string[]; release?: "budget" | "leave"; mipmaps?: true | readonly string[] }>>): BundleMap<Key>;
function load(bundle: string | readonly string[]): Descriptor<LoadResult | undefined>;
function ready(bundle: string | readonly string[]): Descriptor<boolean | undefined>;
function defineScene(id: string, scene: { bundle: string; bundles?: (state) => string[]; layers: LayerMap; projections: readonly Projection[]; music?: string; leave?: SceneLeave | false; enter?: SceneEnter }): SceneDefinition;

function defineAnimation<Tags extends SlotTags>(id: string, spec: { slots: Tags; build: (slots, tools: { at }) => Step }): AnimationDefinition<Tags>;
function sequence(...steps: readonly Step[]): Step;
function parallel(...steps: readonly Step[]): Step;
function stagger<Item>(items: readonly Item[], staggerMs: number, build: (item: Item, index: number) => Step): Step;
function tween<Value>(target: Target, component: ComponentHandle<Value>, to: Partial<Value>, options: { ms: number; ease?: Ease; delayMs?: number; additive?: boolean; space?: "local" | "root"; reduced?: "cut" | "keep"; segments?; repeat? }): Step;
function set<Value>(target: Target, component: ComponentHandle<Value>, patch: Partial<Value>): Step;
function wait(durationMs: number): Step;
function mark(name: string): Step;
function frames(target: Target, options: { keys: readonly string[]; fps: number; loop?: boolean }): Step;
function sfx(key: string, options?: { bus?: string; id?: string; fadeMs?: number }): SfxDescriptor;
function stopSfx(id: string, options?: { fadeMs?: number }): StopSfxDescriptor;
function haptic(kind: HapticKind): HapticDescriptor;
function use<Tags>(animation: AnimationDefinition<Tags>, slots: SlotValues<Tags>, tools?: BuildTools): Step;
function spawn(id: string, components: readonly ComponentValue[], options?: { layer?: string; order?: number }): Step;
function spawned(id: string): { spawned: string };
function play<Tags>(animation: AnimationDefinition<Tags>, slots: SlotValues<Tags>): PlayDescriptor;
function external(player: ExternalPlayer, clip: string): never;
function defineMotion(spec: { states?; transition?; on: { enter?; exit?; change? }; when?: "always" | "change" }): ProjectionMotion;
function cubicBezier(x1: number, y1: number, x2: number, y2: number): (t: number) => number;

const Animation: ComponentType<AnimationValue>;
const Frames: ComponentType<{ keys: readonly string[]; fps: number; loop: boolean; playing: boolean }>;
const AnimPlayer: ResourceType<{ play(animation, slots): PlayHandle }>;

function tr(key: string, params?: Record<string, Argument>): Message;
function messageArgument(value: unknown, intl: IntlKit): Part;
function messageDuration(ms: number): Partial<Record<Intl.DurationFormatUnit, number>>;

const Text: ComponentType<TextValue>;
function label(options: { text: string | Message; style: string; at: Point; anchor?: Point }): [TextValue, TransformValue];
function defineTextStyles(map: Record<string, TextStyleInput>): TextStyles;
function defineTextFormats(map: Readonly<Record<string, (value: number) => { content; style }>>): TextFormats;
function bind<Value extends object>(component: ComponentHandle<Value>, field: BindField<Value>, options?: { format?: "int" | "mm:ss" | "h:mm:ss" | "duration" }): TextBind;
const Countdown: ComponentType<{ until: number; left: number }>;

function defineComponent<Properties, Local, Outcomes>(name: string, spec: { local?: Local; outcomes?: Outcomes; view: (props: Properties, local: Local) => DescriptionNode }): ComponentDefinition;
function popup(component: PopupComponent, props: Properties, options?: { over?: string }): Descriptor<Answer>;
function defineStyle<const Given extends Style>(style: Given): Readonly<Given>;
function defineTokens<const Given extends Tokens>(tokens: Given): Readonly<Given>;
function resolve(style: Style | undefined, flags: StyleFlags, viewport: ViewportSize): ResolvedStyle;
function music(key: string | null, options?: { fadeMs?: number }): Descriptor<void>;

const Box: ComponentType<{ x: number; y: number; w: number; h: number }>;
const LocalWrite: ComponentType<LocalWriteValue>;
const ScrollState: ComponentType<{ offset: number; max: number; moving: boolean }>;
const DebugTrigger: TagType;

function defineEmitter(id: string, config: EmitterConfig): EmitterDefinition;
const Emitter: ComponentType<{ effect: string; active: boolean }>;
function defineFilter<Uniforms>(id: string, spec: { wgsl: string; glsl: string; uniforms?: Uniforms; passes?; padding?; inputs?; fallback?; cache?; area? }): FilterComponent;
const Glow: FilterComponent<GlowValue>;
const Outline: FilterComponent<OutlineValue>;
const Blur: ComponentType<BlurValue>;
const ColorMatrix: ComponentType<ColorMatrixValue>;
const Noise: ComponentType<NoiseValue>;
const Displacement: ComponentType<DisplacementValue>;
const Alpha: ComponentType<AlphaValue>;

const HAPTIC_KINDS: readonly ["light", "medium", "heavy", "selection", "success", "warning", "error"];

import type { Anim, Clock, Flow, I18n, Lifecycle, Model, Time } from "@moku-labs/game";

export type Step = Flow.RouteStep; // { at, intent, payload? } or { at, result }
export type Context = Flow.NodeContext;
export type Save = Model.Json;
export type Provider = Model.PlayerStateProvider;
export type Source = Clock.ClockSource;
export type Phase = Time.Phase;
export type Reason = Lifecycle.PauseReason;
export type Target = Anim.Target;
export type Text = I18n.Message;

function createHeadless(app: HeadlessApp): Promise<HeadlessGame>;
function runRepro(app: HeadlessApp, repro: { player: Json; session?: Json; rng?: RngState; checkpoint?: string; route: Flow.RouteStep[] }): Promise<{ path: string[]; player: Json; session: Json }>;
function stepFrames(app: HeadlessApp, count: number, deltaMs: number): void;
function fakeClock(start?: number): ClockSource & { advance(ms: number): void; set(moment: number): void };
function fakeFx(options?: { answer?: (descriptor: Descriptor) => unknown }): { fx; awaited; started; emitted };
function memory(fixture?: { state: SaveDoc; version: number }): PlayerStateProvider & { calls: ProviderCall[] };
function saveOf(player: Json, seed?: number): SaveDoc;
function isolate(feature: FeaturePlugin, options: { flow: AnyFlow; player: Json; as?: string; shared?; stubs?; plugins?; session?: Json; seed?: number }): (seams?) => App;
function stub<const Name extends string>(outcome: Name, payload?: Json): Stub<Name>;

function defineGameApp(definition: {
  flow: AnyFlow;
  player: Json;
  session: Json;
  safeNode?: string;
  orientation?: "portrait" | "landscape";
  referenceSide?: number;
  referenceLong?: number;
  seed?: number;
  shared?: FeaturePlugin;
  features?: readonly FeaturePlugin[];
  plugins?: readonly AnyPluginInstance[];
  headless?: { features?: readonly FeaturePlugin[]; plugins?: readonly AnyPluginInstance[] };
  pluginConfigs?: GamePluginConfigs;
}): GameApp;
const startMoment = 1_000_000;

function startPage(game: GameApp, config: GameConfig, options?: { scenarios?; system?; agents?; devModules? }): Promise<StartedPage>;

function systemShellOf(modules: SystemModules): SystemShellFactory;
function fromSystem(system: SystemSlice): PlatformProvider;
function storeSave(store: StoreSlice, key: string, report: (problem: string) => void): PlayerStateProvider;
function createSystemApp(names: readonly SystemName[], namespace: string, modules: SystemModules): Promise<SystemApp>;

function runCli(argv: readonly string[]): Promise<number>;
function preparePage(root: string, options?: { agents?: readonly string[]; preload?: readonly string[]; servePlugins?: readonly string[] }): Promise<{ html: string; bunfig: string; engine: EngineFingerprint }>;
function watchKeys(root: string, options?: { onError?: (message: string) => void }): Promise<{ close(): void }>;
function watchEngine(root: string, options?: { onChange?: (change: { before; after; restart: boolean }) => void; onError? }): { close(): void };

function defineVisualTest(name: string, test: { start: VisualStart; steps: readonly VisualStep[]; webgl?: boolean }): VisualTest;
function runVisualTests(setup: VisualSetup, tests: readonly VisualTest[], options?: VisualOptions): Promise<VisualReport>;
function parseVisualArgv(argv: readonly string[]): VisualFlags;

function scanAssets(options: ScanOptions): Promise<ScanResult>;
function emitKeys(manifest: Manifest): string;
function emitManifest(manifest: Manifest): string;
function compileStrings(root: string, out: string, options?: CompileOptions): Promise<CompileReport>;
function checkStrings(root: string, out: string): Promise<boolean>;
function exportStrings(root: string, dir: string, options?: ExchangeOptions): Promise<ExportReport>;
function importStrings(root: string, dir: string, options?: ImportOptions): Promise<ImportReport>;
function packAssets(options: PackOptions): Promise<PackResult>;
function runCli(argv: string[], strings: StringsTools, ui?: ScanUi): Promise<number>;

function read<Output>(app: App, source: Source<Output>, input?: Input): Output;
function watch<Output>(app: App, source: Source<Output>, input: Input, fn: (value: Output) => void): () => void;
function defineSource(source: { id: string; title: string; input: InputSchema; changes: "frame" | "commit" | "edge"; read(app, input): Output }): Source;
const sources: Readonly<{ graph; position; history; tainted; cheats; model; entities; projections; ui; locate; render; sounds; audioMuted; effects; filters; assets; log; explain; diff; schema; at }>;

function run<Output>(app: App, command: Command<Output>, input?: Input): Promise<{ value: Output; state: { path: string; frame: number; tainted: boolean } }>;
function defineCommand(command: { id: string; title: string; input: InputSchema; effect: "read" | "route" | "cosmetic" | "cheat" | "raw"; run(app, input); overlay?: "toggle" | "button" }): Command;
function controlRefused(): ControlRefusedError;
function controlReadOnly(id: string): ControlReadOnlyError;
const commands: Readonly<{ answer; tap; drag; key; walk; bookmark; restore; saveExport; saveImport; step; pause; resume; capture; debug; reducedMotion; fill; scroll; timeScale; frameRate; mute; trace; filter }>;

function hot(options?: { include?; exclude? }): HotPlugin;

function aliasTargetsOf(tsconfig: string, root: string, specifier: string): string[];
function globToRegExp(glob: string): RegExp;

function openProject(options: { root: string; manifest?: string; tsconfig?: string; debounceMs?: number }): Promise<ProjectApi>;
function runCli(argv: readonly string[], ui?: IndexUi): Promise<number>;

function jsx(type: unknown, props: JsxProperties, key?: string): DescriptionNode;
const jsxs: typeof jsx;
function jsxDEV(type: unknown, props: JsxProperties, key?: string, isStatic?: boolean, source?: unknown, self?: unknown): DescriptionNode;
function Fragment(props: JsxProperties): DescriptionNode;

import { defineGame, type } from "@moku-labs/game";
import { defineGameApp, startMoment } from "@moku-labs/game/app";
import { createHeadless } from "@moku-labs/game/testing";

const { defineNode, defineFlow } = defineGame<{
  player: { coins: number };
  session: { rolls: number };
  assets: string;
  strings: Record<string, unknown>;
}>();

const home = defineNode({ outcomes: { roll: type() }, rest: true, checkpoint: true });
const roll = defineNode({
  outcomes: { done: type() },
  run: ({ player, session, rng, out }) => {
    player.coins += rng.stream("dice").range(1, 6);
    session.rolls += 1;
    return out.done();
  }
});

const mainFlow = defineFlow("main", {
  nodes: { home, roll },
  start: "home",
  edges: { home: { roll: "roll" }, roll: { done: "home" } }
});

const game = defineGameApp({ flow: mainFlow, safeNode: "home", player: { coins: 0 }, session: { rolls: 0 } });

const { app, clock } = game.headless();
const run = await createHeadless(app);

clock.now() === startMoment; // true
await run.walk([{ at: "home", intent: "roll" }, { at: "home", intent: "roll" }]);
app.model.store.snapshot().session; // { rolls: 2 }
await run.stop();