@energy8platform/game-engine 0.33.3 → 0.33.4

package/dist/scene.d.ts

@@ -0,0 +1,344 @@
+import { Container, Texture } from 'pixi.js';
+
+type Orientation = 'landscape' | 'portrait';
+interface SceneDoc {
+    version: 1;
+    /** Stable document id (usually the game id). */
+    id: string;
+    /** Design space the layout rules are authored in (viewport arrives in these units). */
+    design: {
+        width: number;
+        height: number;
+    };
+    root: SceneNode;
+}
+interface SceneNode {
+    /** Stable id — flow, code and patches address the node by it. Unique per doc. */
+    id: string;
+    /** Node kind resolved through the registry (built-in or plugin-contributed). */
+    type: string;
+    /** Human label for the outliner; never used for addressing. */
+    name?: string;
+    /** Kind-specific properties (validated by the contribution's schema). */
+    props?: Record<string, unknown>;
+    layout?: LayoutRule;
+    /** Per-orientation override merged over the base node before layout. */
+    responsive?: Partial<Record<Orientation, NodeOverride>>;
+    /**
+     * Named variants toggled at runtime (flow `setState`, editor, code) — e.g. a reel
+     * frame's `anticipation` / `bonus` looks. A state is an override, not a new node.
+     */
+    states?: Record<string, NodeOverride>;
+    /** Id of another node in this doc used as this node's mask. */
+    mask?: string;
+    /**
+     * Tiny condition over runtime vars, e.g. `"mode === 'free_spins'"`. Supported form:
+     * `<var> <op> <literal>` with `=== !== >= <= > <`. Anything richer belongs in flow/code.
+     */
+    visibleWhen?: string;
+    /** Entry in the shared anchor vocabulary flow/animation use to address the node. */
+    anchorName?: string;
+    /** Order = z-order. */
+    children?: SceneNode[];
+}
+/** Partial node applied on top of the base for an orientation or a named state. */
+interface NodeOverride {
+    layout?: LayoutRule;
+    props?: Record<string, unknown>;
+    visible?: boolean;
+}
+interface LayoutCommon {
+    /** Content anchor [ax, ay] in 0..1 (applied via pivot on the node's natural size). */
+    anchor?: [number, number];
+    /** Final hand-tuned nudge in design px, applied after the rule resolves. */
+    pxNudge?: {
+        x?: number;
+        y?: number;
+    };
+    /** Static rotation in radians (choreographed rotation belongs to flow/animation). */
+    rotation?: number;
+}
+/** Fixed design-space coordinates. */
+interface AbsoluteLayout extends LayoutCommon {
+    mode: 'absolute';
+    x: number;
+    y: number;
+    scale?: number;
+    rotation?: number;
+}
+/**
+ * Position as a fraction of the live viewport. Sizing, strongest first:
+ * `widthFrac`/`heightFrac` size the node to that fraction of the viewport (contain when
+ * both are given) — the "frame is 92% of the screen in portrait" idiom; otherwise
+ * `scaleWith` multiplies `scale` by the viewport/design ratio; otherwise plain `scale`.
+ */
+interface ViewportFractionLayout extends LayoutCommon {
+    mode: 'viewport-fraction';
+    xFrac: number;
+    yFrac: number;
+    scale?: number;
+    /** Multiply `scale` by viewport/design ratio: width | height | min | max. */
+    scaleWith?: 'width' | 'height' | 'min' | 'max';
+    /** Size the node to this fraction of the viewport width (scale derived from natural size). */
+    widthFrac?: number;
+    /** Size the node to this fraction of the viewport height. */
+    heightFrac?: number;
+    /** With both fracs: contain (default) keeps aspect, stretch distorts to fill exactly. */
+    fit?: 'contain' | 'stretch';
+}
+/**
+ * Center-crop fill of the current space (backgrounds, diorama layers). `scale` multiplies
+ * the computed cover scale (the paper-duel `e` idiom); `pxNudge` offsets from center.
+ */
+interface CoverLayout extends LayoutCommon {
+    mode: 'cover';
+    scale?: number;
+}
+/**
+ * Place inside another node's laid-out rect using fractions of that rect.
+ * `use: 'inner'` reads the target's declared `props.inner` fractions (reel frames
+ * declare where their hollow is) instead of spelling the fractions twice.
+ * When a box (`wFrac`/`hFrac` or `use`) is given the node is contain-fitted into it
+ * (`fit: 'stretch'` distorts instead).
+ */
+interface FrameFractionLayout extends LayoutCommon {
+    mode: 'frame-fraction';
+    frame: string;
+    xFrac?: number;
+    yFrac?: number;
+    wFrac?: number;
+    hFrac?: number;
+    use?: 'inner';
+    fit?: 'contain' | 'stretch';
+}
+/**
+ * Center of a reel-grid cell (badges, per-cell VFX slots). `grid` defaults to the sole
+ * reelGrid. By default the node scales with the grid (sizes authored in grid-design px);
+ * `scaleWithGrid: false` keeps it in absolute design units.
+ */
+interface GridCellLayout extends LayoutCommon {
+    mode: 'grid-cell';
+    grid?: string;
+    col: number;
+    row: number;
+    scale?: number;
+    scaleWithGrid?: boolean;
+}
+/** Pin to an edge/center of another node's laid-out rect. */
+interface PinLayout extends LayoutCommon {
+    mode: 'pin';
+    to: string;
+    edge: PinEdge;
+    offset?: [number, number];
+    scale?: number;
+}
+type PinEdge = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+type LayoutRule = AbsoluteLayout | ViewportFractionLayout | CoverLayout | FrameFractionLayout | GridCellLayout | PinLayout;
+type ScenePatch = {
+    op: 'set-props';
+    id: string;
+    props: Record<string, unknown>;
+}
+/** Without `orientation` replaces the base rule; with it, that orientation's override. */
+ | {
+    op: 'set-layout';
+    id: string;
+    layout: LayoutRule;
+    orientation?: Orientation;
+} | {
+    op: 'set-state';
+    id: string;
+    state: string | null;
+} | {
+    op: 'set-var';
+    name: string;
+    value: unknown;
+};
+/** Outliner row — the tree the inspector and the agent both read. */
+interface OutlineNode {
+    id: string;
+    type: string;
+    name?: string;
+    anchorName?: string;
+    visible: boolean;
+    state: string | null;
+    children: OutlineNode[];
+}
+
+interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface Size {
+    width: number;
+    height: number;
+}
+/** Resolved transform for a node, in parent (scene) coordinates. */
+interface Placement {
+    x: number;
+    y: number;
+    scaleX: number;
+    scaleY: number;
+    rotation: number;
+    /** Content anchor in 0..1 — the engine applies it via pivot over the natural size. */
+    anchor: [number, number];
+    /** Present when the rule targeted a box (frame-fraction with a width/height). */
+    box?: Size;
+}
+/** Layout context the engine provides while resolving a pass. */
+interface LayoutContext {
+    viewport: Size;
+    design: Size;
+    /** Laid-out AABB of a node (undefined until that node resolved this pass). */
+    bounds(id: string): Rect | undefined;
+    /** Declared `props.inner` fractions of a node mapped onto its laid-out bounds. */
+    innerRect(id: string): Rect | undefined;
+    /** Scene-space center of a grid cell; `id` undefined targets the doc's sole reelGrid. */
+    gridCell(id: string | undefined, col: number, row: number): {
+        x: number;
+        y: number;
+    } | undefined;
+    /** World scale of a grid node (for grid-cell nodes that scale with the grid). */
+    gridScale(id: string | undefined): {
+        x: number;
+        y: number;
+    } | undefined;
+}
+type LayoutResolution = {
+    placement: Placement;
+} | {
+    waitingFor: string;
+};
+declare function orientationOf(width: number, height: number, portraitFactor?: number): Orientation;
+/** Base node + orientation override + active state override (state wins), for one frame. */
+declare function effectiveNode(node: SceneNode, orientation: Orientation, state: string | null): {
+    layout?: LayoutRule;
+    props: Record<string, unknown>;
+    visible: boolean;
+};
+/** Which node id (if any) must be laid out before this rule can resolve. */
+declare function dependencyOf(rule: LayoutRule | undefined): string | undefined;
+declare function edgePoint(rect: Rect, edge: PinEdge): {
+    x: number;
+    y: number;
+};
+/** AABB of a placement over a natural content size (rotation ignored — pin targets should not rotate). */
+declare function placementBounds(p: Placement, natural: Size): Rect;
+/**
+ * Resolve one rule. Returns `waitingFor` when a referenced node has no bounds yet — the
+ * engine re-queues the node for the next pass (bounded; see engine).
+ */
+declare function resolveLayoutRule(rule: LayoutRule, natural: Size, ctx: LayoutContext): LayoutResolution;
+/**
+ * Evaluate a `visibleWhen` micro-expression: `<var> <op> <literal>` with
+ * `=== !== >= <= > <`. Unknown shapes evaluate to visible (with the engine warning once) —
+ * richer conditions belong in flow or code, not in the scene doc.
+ */
+declare function evalVisibleWhen(expr: string, vars: Record<string, unknown>): boolean | undefined;
+
+/** A symbol's visual. Any Container; optionally implements the lifecycle the cell drives. */
+interface SymbolView extends Container {
+    playIdle?(): void;
+    playWin?(): Promise<void>;
+    showStatic?(): void;
+    /** Resize the symbol to the given cell size in pixels (square scalar or rectangular). */
+    resize?(size: number | {
+        width: number;
+        height: number;
+    }): void;
+}
+/** Game-supplied factory: build the view for a symbol id (sprite / layered sprites / Spine / composite). */
+type SymbolResolver = (symbolId: string) => SymbolView | null;
+
+interface NodeCreateContext {
+    registry: SceneRegistry;
+    /** Resolve a texture alias (defaults to Pixi `Texture.from`; tests/labs inject). */
+    texture(alias: string): Texture;
+    /** Game-supplied symbol factory — required by the `reelGrid` kind. */
+    resolveSymbol?: SymbolResolver;
+    log?: (msg: string) => void;
+}
+/** Live counterpart of one scene node, produced by its contribution. */
+interface NodeInstance {
+    view: Container;
+    /** Natural (unscaled) content size — drives anchor, cover and box fitting. */
+    measure(): Size;
+    /** Apply a props patch in place; absent → the engine rebuilds the node instead. */
+    applyProps?(props: Record<string, unknown>): void;
+    /** Scene-local center of a grid cell (reel-grid kinds only; enables `grid-cell` layout). */
+    gridCell?(col: number, row: number): {
+        x: number;
+        y: number;
+    };
+    destroy?(): void;
+}
+interface NodeTypeContribution {
+    kind: string;
+    /** JSON-Schema-ish description of `props` — validation, inspector autogen, agent docs. */
+    schema?: Record<string, unknown>;
+    /** 3–10 lines for the agent: when to use this kind, patterns, anti-patterns. */
+    agentDoc?: string;
+    create(node: SceneNode, ctx: NodeCreateContext): NodeInstance;
+}
+/** Reusable game component (meters, HUDs) addressed as `{type:'prefab', props:{prefab:'name'}}`. */
+interface PrefabContribution {
+    name: string;
+    schema?: Record<string, unknown>;
+    agentDoc?: string;
+    create(props: Record<string, unknown>, ctx: NodeCreateContext): NodeInstance;
+}
+interface ScenePlugin {
+    id: string;
+    nodeTypes?: NodeTypeContribution[];
+    prefabs?: PrefabContribution[];
+}
+interface SceneRegistry {
+    nodeType(kind: string): NodeTypeContribution | undefined;
+    prefab(name: string): PrefabContribution | undefined;
+    kinds(): string[];
+    prefabNames(): string[];
+}
+/** Merge built-ins with plugin contributions; later plugins may override earlier kinds. */
+declare function createSceneRegistry(plugins?: ScenePlugin[], builtins?: NodeTypeContribution[]): SceneRegistry;
+
+declare const BUILTIN_NODE_TYPES: NodeTypeContribution[];
+
+interface SceneValidationError {
+    nodeId?: string;
+    message: string;
+}
+declare function validateSceneDoc(doc: SceneDoc, registry: SceneRegistry): SceneValidationError[];
+
+interface CreateSceneOptions {
+    /** Extra contributions (official + game-local plugins) merged over the built-ins. */
+    plugins?: ScenePlugin[];
+    /** Texture alias resolver; defaults to Pixi's `Texture.from`. */
+    texture?: (alias: string) => Texture;
+    /** Symbol factory for `reelGrid` nodes. */
+    resolveSymbol?: SymbolResolver;
+    /** Initial runtime vars driving `visibleWhen` (e.g. { mode: 'base' }). */
+    vars?: Record<string, unknown>;
+    /** Treat near-square viewports as portrait below this width/height factor (default 1). */
+    portraitFactor?: number;
+    log?: (msg: string) => void;
+}
+interface SceneHandle {
+    view: Container;
+    node(id: string): Container | undefined;
+    instance(id: string): NodeInstance | undefined;
+    anchor(name: string): Container | undefined;
+    tree(): OutlineNode;
+    layout(width: number, height: number): void;
+    setVar(name: string, value: unknown): void;
+    setState(id: string, state: string | null): void;
+    patch(patch: ScenePatch): void;
+    /** The live doc (mutated by patches) — serialize this to persist the scene. */
+    doc(): SceneDoc;
+    destroy(): void;
+}
+declare function createSceneFromDoc(doc: SceneDoc, opts?: CreateSceneOptions): SceneHandle;
+
+export { BUILTIN_NODE_TYPES, createSceneFromDoc, createSceneRegistry, dependencyOf, edgePoint, effectiveNode, evalVisibleWhen, orientationOf, placementBounds, resolveLayoutRule, validateSceneDoc };
+export type { AbsoluteLayout, CoverLayout, CreateSceneOptions, FrameFractionLayout, GridCellLayout, LayoutContext, LayoutResolution, LayoutRule, NodeCreateContext, NodeInstance, NodeOverride, NodeTypeContribution, Orientation, OutlineNode, PinEdge, PinLayout, Placement, PrefabContribution, Rect, SceneDoc, SceneHandle, SceneNode, ScenePatch, ScenePlugin, SceneRegistry, SceneValidationError, Size, ViewportFractionLayout };