@energy8platform/game-engine 0.34.0 → 0.34.2

package/dist/scene.d.ts

@@ -11,6 +11,8 @@ interface SceneDoc {
         width: number;
         height: number;
     };
+    /** Authoring modes the scene has views for (e.g. ['base','free_spins']); base is implicit. */
+    modes?: string[];
     root: SceneNode;
 }
 interface SceneNode {
@@ -30,6 +32,13 @@ interface SceneNode {
      * frame's `anticipation` / `bonus` looks. A state is an override, not a new node.
      */
     states?: Record<string, NodeOverride>;
+    /**
+     * Per-GAME-MODE override, applied automatically when the runtime `mode` var matches
+     * (base / free_spins / …). This is why base and free_spins are ONE scene, not two: a
+     * node re-poses per mode instead of being duplicated into a separate scene. Layered
+     * after orientation, before the active state.
+     */
+    modes?: Record<string, NodeOverride>;
     /** Id of another node in this doc used as this node's mask. */
     mask?: string;
     /** Filters applied to the node's view; kinds resolve through the registry (core: blur). */
@@ -149,17 +158,21 @@ interface PinLayout extends LayoutCommon {
 }
 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 = {
+type ScenePatch = 
+/** `mode` targets that mode's override (node.modes[mode].props); else base props. */
+{
     op: 'set-props';
     id: string;
     props: Record<string, unknown>;
+    mode?: string;
 }
-/** Without `orientation` replaces the base rule; with it, that orientation's override. */
+/** Targets, in precedence: `mode` (node.modes[mode]) → `orientation` (responsive) → base. */
  | {
     op: 'set-layout';
     id: string;
     layout: LayoutRule;
     orientation?: Orientation;
+    mode?: string;
 } | {
     op: 'set-state';
     id: string;
@@ -250,7 +263,7 @@ type LayoutResolution = {
 };
 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): {
+declare function effectiveNode(node: SceneNode, orientation: Orientation, state: string | null, mode?: string | null): {
     layout?: LayoutRule;
     props: Record<string, unknown>;
     visible: boolean;
@@ -501,6 +514,8 @@ interface TransformGizmoOptions {
     app: Application;
     applyPatch?: (patch: ScenePatch) => void;
     getOrientation?: () => Orientation;
+    /** Current authoring mode; when set and not 'base', edits target that mode's override. */
+    getMode?: () => string | null;
     /** Override screen→design conversion for move drags. Default: the node's parent world scale. */
     designPerPixel?: (nodeId: string) => number;
 }
@@ -556,6 +571,32 @@ declare abstract class Scene implements IScene {
     onDestroy?(): void;
 }
 
+/**
+ * Gate for the PROGRESSIVE (cascade / tumble) WIN readout.
+ *
+ * By default the WIN readout is entirely host-driven: cleared to 0 when a segment starts, set to
+ * that segment's win once `onSpin` resolves. A cascade game pays in steps, so its scene wants the
+ * number to climb WHILE the segment presents — `api.shell.reportWin(amountSoFar)`.
+ *
+ * The gate keeps the host in charge:
+ *   - reports are honoured ONLY between `open()` (segment start, WIN already cleared) and `close()`
+ *     (the host paints the segment's final value) — a scene still animating after an abort, or one
+ *     reporting from a mode transition, can't overwrite the host's number,
+ *   - `amountSoFar` is ABSOLUTE (the segment's win up to now, not the step delta), so a re-report or
+ *     a collapse-to-final on skip is idempotent. Reports should be non-decreasing within a segment;
+ *     a lower value counts the readout back DOWN,
+ *   - garbage (NaN / Infinity) is dropped and negatives clamp to 0, so a math bug can't paint "NaN"
+ *     into the bar.
+ *
+ * Pure + unit-testable: the shell paint is injected.
+ */
+interface WinReportOptions {
+    /** `false` snaps instead of counting up (e.g. collapsing to the final value on skip). */
+    animate?: boolean;
+    /** Count-up length in ms (shell default 450) — pass the cascade step's length. */
+    durationMs?: number;
+}
+
 /** Everything a scene needs to render one segment. The host builds it per segment. */
 interface RenderContext {
     /** Bet for this round (major units). Stable for the whole round. */
@@ -623,6 +664,25 @@ interface SceneShell {
         bottom: number;
         left: number;
     };
+    /**
+     * Grow the shell's WIN readout WHILE a segment presents — for cascade/tumble games that pay in
+     * steps instead of one lump at the end.
+     *
+     * `amountSoFar` is ABSOLUTE: the win accumulated by this segment up to now (not the step's
+     * delta), so a re-report, a skip, or an aborted step can just restate the truth. The host owns
+     * the readout around it — it clears WIN to 0 when the segment starts and sets the segment's
+     * final value once `onSpin` resolves (counting up from your last report, so matching numbers
+     * produce no jump). In a bonus this moves WIN only; the Total Win accumulator still lands once
+     * per segment.
+     *
+     * Only honoured while a segment is presenting (inside `onSpin`); calls from anywhere else are
+     * ignored, so a scene still ticking after an abort can't overwrite the host's final number.
+     *
+     * `durationMs` sets this count-up's length (default 450ms) — pass your step length (or a shorter
+     * one under turbo) so each count-up finishes before the next step lands. `{ animate: false }`
+     * snaps, e.g. when collapsing to the final value on skip.
+     */
+    reportWin(amountSoFar: number, opts?: WinReportOptions): void;
 }
 interface AutoplaySceneState {
     running: boolean;

package/dist/scene.esm.js

@@ -10,9 +10,11 @@ function orientationOf(width, height, portraitFactor = 1) {
     return width < height * portraitFactor ? 'portrait' : 'landscape';
 }
 /** Base node + orientation override + active state override (state wins), for one frame. */
-function effectiveNode(node, orientation, state) {
+function effectiveNode(node, orientation, state, mode) {
+    // Layer order: base → orientation → mode → active state (later wins).
     const layers = [
         node.responsive?.[orientation],
+        mode ? node.modes?.[mode] : undefined,
         state ? node.states?.[state] : undefined,
     ];
     let layout = node.layout;
@@ -2880,6 +2882,7 @@ function createReelSystem(opts) {
             for (let i = 0; i < steps.length; i++) {
                 await tumble.step(steps[i], i, cOpts);
                 board = steps[i].settledGrid;
+                await cOpts?.onStep?.(i, steps[i], tumble.multiplier);
             }
             if (config.cascade.multiplier.enabled)
                 log?.(`Cascade multiplier ×${tumble.multiplier}`);
@@ -2891,6 +2894,7 @@ function createReelSystem(opts) {
             for (let i = 0; i < steps.length; i++) {
                 await reelStepCtl.step(steps[i], i, rOpts);
                 board = steps[i].settledGrid;
+                await rOpts?.onStep?.(i, steps[i], reelStepCtl.multiplier);
             }
             if (config.cascade.multiplier.enabled)
                 log?.(`ReelStep multiplier ×${reelStepCtl.multiplier}`);
@@ -3434,9 +3438,10 @@ function createSceneFromDoc(doc, opts = {}) {
         lastWidth = width;
         lastHeight = height;
         const orientation = orientationOf(width, height, opts.portraitFactor ?? 1);
-        // Phase 1 — effective props (base + orientation + state), applied before measuring.
+        const mode = typeof vars.mode === 'string' ? vars.mode : null;
+        // Phase 1 — effective props (base + orientation + mode + state), applied before measuring.
         for (const runtime of [...runtimes.values()]) {
-            const eff = effectiveNode(runtime.node, orientation, runtime.state);
+            const eff = effectiveNode(runtime.node, orientation, runtime.state, mode);
             runtime.visibleBase = eff.visible;
             const space = eff.props.space;
             runtime.spaceSize =
@@ -3540,7 +3545,7 @@ function createSceneFromDoc(doc, opts = {}) {
                 const parentOriginY = parentIsFrame ? 0 : (runtime.parent?.bounds?.y ?? 0);
                 const parentScaleX = parentIsFrame ? 1 : (runtime.parent?.worldScaleX ?? 1);
                 const parentScaleY = parentIsFrame ? 1 : (runtime.parent?.worldScaleY ?? 1);
-                const eff = effectiveNode(runtime.node, orientation, runtime.state);
+                const eff = effectiveNode(runtime.node, orientation, runtime.state, mode);
                 const natural = runtime.instance.measure();
                 const rule = eff.layout;
                 // `space:'viewport'` resolves against the live viewport even inside a nested
@@ -3713,14 +3718,25 @@ function createSceneFromDoc(doc, opts = {}) {
                 const node = findNode(doc.root, patch.id);
                 if (!node)
                     return warnOnce(`patch:${patch.id}`, `patch: unknown node "${patch.id}"`);
-                node.props = { ...(node.props ?? {}), ...patch.props };
+                if (patch.mode) {
+                    node.modes = { ...(node.modes ?? {}) };
+                    const over = node.modes[patch.mode] ?? {};
+                    node.modes[patch.mode] = { ...over, props: { ...(over.props ?? {}), ...patch.props } };
+                }
+                else {
+                    node.props = { ...(node.props ?? {}), ...patch.props };
+                }
                 break;
             }
             case 'set-layout': {
                 const node = findNode(doc.root, patch.id);
                 if (!node)
                     return warnOnce(`patch:${patch.id}`, `patch: unknown node "${patch.id}"`);
-                if (patch.orientation) {
+                if (patch.mode) {
+                    node.modes = { ...(node.modes ?? {}) };
+                    node.modes[patch.mode] = { ...(node.modes[patch.mode] ?? {}), layout: patch.layout };
+                }
+                else if (patch.orientation) {
                     node.responsive = { ...(node.responsive ?? {}) };
                     node.responsive[patch.orientation] = {
                         ...(node.responsive[patch.orientation] ?? {}),
@@ -4137,6 +4153,7 @@ function createTransformGizmo(opts) {
     layer.addChildAt(body, 1);
     let nodeId = null;
     let drag = null;
+    const getMode = () => opts.getMode?.() ?? null;
     const findDocNode = (id, node = handle.doc().root) => {
         if (node.id === id)
             return node;
@@ -4147,14 +4164,22 @@ function createTransformGizmo(opts) {
         }
         return undefined;
     };
-    /** Effective layout rule for the current orientation (base or portrait/landscape override). */
+    /**
+     * Effective layout rule + which override an edit should target. Editing in a non-base
+     * mode targets that mode's override (so base and free_spins are edited independently);
+     * otherwise the current orientation override, else base.
+     */
     const effectiveRule = (id) => {
         const node = findDocNode(id);
         if (!node)
-            return {};
+            return { target: {} };
+        const mode = getMode();
+        if (mode && mode !== 'base') {
+            return { rule: node.modes?.[mode]?.layout ?? node.layout, target: { mode } };
+        }
         const o = getOrientation();
         const override = node.responsive?.[o]?.layout;
-        return override ? { rule: override, orientation: o } : { rule: node.layout };
+        return override ? { rule: override, target: { orientation: o } } : { rule: node.layout, target: {} };
     };
     const boxOf = (id) => {
         const view = handle.node(id);
@@ -4168,7 +4193,7 @@ function createTransformGizmo(opts) {
         if (!nodeId)
             return;
         const box = boxOf(nodeId);
-        const { rule, orientation } = effectiveRule(nodeId);
+        const { rule, target } = effectiveRule(nodeId);
         if (!box || !rule)
             return;
         const center = { x: box.x + box.width / 2, y: box.y + box.height / 2 };
@@ -4176,7 +4201,7 @@ function createTransformGizmo(opts) {
             handle: h,
             startBox: box,
             baseRule: JSON.parse(JSON.stringify(rule)),
-            orientation,
+            target,
             start: { x: e.global.x, y: e.global.y },
             center,
             startAngle: Math.atan2(e.global.y - center.y, e.global.x - center.x),
@@ -4200,7 +4225,7 @@ function createTransformGizmo(opts) {
             const { factorX, factorY } = resizeFactors(drag.startBox, drag.handle, { x: e.global.x, y: e.global.y });
             rule = resizeRule(drag.baseRule, factorX, factorY);
         }
-        applyPatch({ op: 'set-layout', id: nodeId, layout: rule, orientation: drag.orientation });
+        applyPatch({ op: 'set-layout', id: nodeId, layout: rule, orientation: drag.target.orientation, mode: drag.target.mode });
     };
     const onUp = () => {
         drag = null;