@energy8platform/game-engine 0.23.0 → 0.25.0

package/src/core/GameApplication.ts

@@ -87,7 +87,7 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
   public platformSession: PlatformSession | null = null;
 
   /** Branded game shell (only when config.shell is set). */
-  public shell?: import('@energy8platform/platform-core/shell').GameShell;
+  public shell?: import('@energy8platform/shell/html').GameShell;
 
   /** Configuration */
   public readonly config: GameApplicationConfig;
@@ -169,7 +169,7 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
 
       // 4b. Mount the branded game shell after the SDK handshake (optional)
       if (this.config.shell) {
-        const { createGameShell } = await import('@energy8platform/platform-core/shell');
+        const { createGameShell } = await import('@energy8platform/shell/html');
         this.shell = createGameShell(this.config.shell);
       }
 
@@ -209,7 +209,7 @@ export class GameApplication extends EventEmitter<GameEngineEvents> {
     this._running = false;
 
     if (this.shell) {
-      const { removeGameShell } = await import('@energy8platform/platform-core/shell');
+      const { removeGameShell } = await import('@energy8platform/shell/html');
       await removeGameShell();
       this.shell = undefined;
     }

package/src/harness/index.ts

@@ -0,0 +1,35 @@
+/**
+ * `@energy8platform/game-engine/harness` — node-only entry.
+ *
+ * Contributes the reel-config **panel** to `@energy8platform/harness`: a docked
+ * right sidebar that tunes a running game's ReelSystem live. Pair it with
+ * `mountReelDevBridge` (from `@energy8platform/game-engine/devtools`) in the game.
+ *
+ * Usage in a game's vite.config:
+ *   import { createHarness } from '@energy8platform/harness';
+ *   import { reelDevtoolsPlugin } from '@energy8platform/game-engine/harness';
+ *   createHarness({ plugins: [ reelDevtoolsPlugin() ] });
+ *
+ * Node-only: resolves the built, self-contained panel-client ESM the harness serves.
+ */
+
+import { fileURLToPath } from 'node:url';
+
+import type { HarnessPanel, HarnessPlugin } from '@energy8platform/harness';
+
+export interface ReelDevtoolsPluginOptions {
+  /** Sidebar header / tab label. Default 'Reels'. */
+  title?: string;
+}
+
+export function reelDevtoolsPlugin(opts: ReelDevtoolsPluginOptions = {}): HarnessPlugin {
+  // The self-contained panel client sits next to this module in dist/.
+  const clientEntry = fileURLToPath(new URL('./reel-panel-client.esm.js', import.meta.url));
+  const panel: HarnessPanel = {
+    id: 'reels',
+    title: opts.title ?? 'Reels',
+    placement: 'sidebar',
+    clientEntry,
+  };
+  return { panel };
+}

package/src/host/createSlotGame.ts

@@ -6,7 +6,7 @@ import { loadFonts, applyTextureDefaults, bootGuard } from './preboot';
 import { showFatalError, installGlobalErrorHandlers } from './fatalError';
 import type { CreateSlotGameOptions, SlotGameHandle } from './types';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
-import type { ShellMode } from '@energy8platform/pixi-shell';
+import type { ShellMode } from '@energy8platform/shell/pixi';
 import type { SceneApi, SlotSceneController } from './sceneController';
 
 /**
@@ -143,7 +143,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
   });
 
   if (opts.shell) {
-    const { createPixiShell } = await import('@energy8platform/pixi-shell');
+    const { createPixiShell } = await import('@energy8platform/shell/pixi');
     const { buildShellConfig } = await import('./shellConfig');
     const { resolveReplayBonusId } = await import('./replay');
 
@@ -206,7 +206,10 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // pixi-shell mounts its root onto the engine's unscaled, screen-space UI layer (above the
     // scaled world/scene root) so the control bar fills the real screen, not the letterboxed game.
     // The host adds the mount target (`app`) + parent; buildShellConfig produces everything else.
-    shell = createPixiShell({ ...buildShellConfig(opts.shell, opts.model, runtime), app: game.app, parent: game.uiLayer });
+    const pixiShellCfg: import('@energy8platform/shell/pixi').PixiShellConfig = { ...buildShellConfig(opts.shell, opts.model, runtime), app: game.app, parent: game.uiLayer };
+    // The game may swap in its own shell (a custom renderer over the same core) via shellFactory;
+    // default is the built-in Pixi shell. The host drives whichever it gets through the Shell contract.
+    shell = (opts.shellFactory ?? createPixiShell)(pixiShellCfg);
     // Scope the bar to the slot scene: show only when a SlotSceneController scene is current
     // (hidden over the intro / non-slot scenes). Applies in BOTH base and replay modes.
     shell.setVisible(!!gameScene());

package/src/host/index.ts

@@ -6,7 +6,17 @@ export type {
   StakeIntegration,
   SceneRegistration,
   SceneNavData,
+  ShellFactory,
 } from './types';
+
+// Shell contract for authors plugging a custom renderer via createSlotGame({ shellFactory }).
+// Implement `ShellRenderer`, build the shell with `createShell({ renderer, ...config })`, and the
+// shell core drives bet/balance/overlays unchanged. `createPixiShell`/`PixiRenderer` are the built-in.
+export { createShell, createPixiShell, PixiRenderer } from '@energy8platform/shell/pixi';
+export type {
+  Shell, ShellRenderer, ShellSurface, SafeArea, ShellHost, ShellActions, ShellTokens,
+  ShellLayoutMode, OverlayRequest, OverlayHandle, ResolvedShellConfig, PixiShellConfig,
+} from '@energy8platform/shell/pixi';
 export { buildShellConfig, stakeForAction } from './shellConfig';
 export type { SlotShellOptions } from './shellConfig';
 export { resolveReplayBonusId } from './replay';
@@ -17,4 +27,4 @@ export type {
 } from './sceneController';
 // Social-casino word-swap. The shell auto-socializes all gameInfo/buyBonus text in social mode;
 // authors only need this to socialize strings they render themselves (e.g. inside a custom DOM node).
-export { socialize } from '@energy8platform/platform-core/shell';
+export { socialize } from '@energy8platform/shell';

package/src/host/shellConfig.ts

@@ -1,12 +1,14 @@
 // packages/game-engine/src/host/shellConfig.ts
-// `socialize` / `createI18n` are runtime helpers sourced from platform-core/shell;
-// pixi-shell re-exports only types so we import directly from platform-core.
-import { socialize, createI18n } from '@energy8platform/platform-core/shell';
-import type { Lang } from '@energy8platform/platform-core/shell';
+// `socialize` / `createI18n` / `Lang` are renderer-agnostic helpers from the shell core
+// (@energy8platform/shell). Renderer-agnostic types (GameInfoSection/Content, PaytableRow,
+// GameMode) and the pixi-specific surface types come from the @energy8platform/shell/pixi entry.
+import { socialize, createI18n } from '@energy8platform/shell';
+import type { Lang } from '@energy8platform/shell';
+import type { GameInfoContent, GameInfoSection, PaytableRow, GameMode } from '@energy8platform/shell/pixi';
 import type {
-  PixiShellConfig, ShellMode, CurrencyConfig, GameInfoContent, GameInfoSection, PaytableRow,
-  BonusOption, ShellFeatures, GameMode,
-} from '@energy8platform/pixi-shell';
+  PixiShellConfig, ShellMode, CurrencyConfig,
+  BonusOption, ShellFeatures,
+} from '@energy8platform/shell/pixi';
 import type { GameModel } from '@energy8platform/platform-core/game-spec';
 import type { WinTier } from '../slot';
 
@@ -276,20 +278,26 @@ function sectionKey(s: GameInfoSection): string {
  */
 export function mergeGameInfo(derived: GameInfoContent, override?: GameInfoContent): GameInfoContent {
   if (!override) return derived;
+  // `GameInfoContent.sections` is typed with the core GameInfoSection (node?: unknown) because
+  // shell/pixi re-exports GameInfoContent unchanged from core. Host-built sections never set `node`,
+  // so they are structurally compatible with pixi's GameInfoSection (node?: Container). Cast once
+  // here so the rest of the function works against the pixi-widened type.
+  const derivedSections = (derived.sections ?? []) as GameInfoSection[];
+  const overrideSections = (override.sections ?? []) as GameInfoSection[];
   const authorByKey = new Map<string, GameInfoSection>();
-  for (const s of override.sections ?? []) authorByKey.set(sectionKey(s), s);
+  for (const s of overrideSections) authorByKey.set(sectionKey(s), s);
 
   const out: GameInfoSection[] = [];
   const used = new Set<string>();
   // Keep derived order; swap in the author's version where identities collide.
-  for (const s of derived.sections ?? []) {
+  for (const s of derivedSections) {
     const k = sectionKey(s);
     const replacement = authorByKey.get(k);
     if (replacement) { out.push(replacement); used.add(k); }
     else out.push(s);
   }
   // Append author sections whose identity wasn't in the derived set, in author order.
-  for (const s of override.sections ?? []) {
+  for (const s of overrideSections) {
     const k = sectionKey(s);
     if (!used.has(k)) { out.push(s); used.add(k); }
   }
@@ -340,7 +348,7 @@ export function buildShellConfig(
   opts: SlotShellOptions,
   model: GameModel,
   runtime: ShellRuntime,
-): Omit<PixiShellConfig, 'app' | 'parent'> {
+): Omit<PixiShellConfig, 'app' | 'parent' | 'gameInfo'> & { gameInfo: GameInfoContent } {
   // Prefer the currency-specific ladder from /wallet/authenticate; fall back to the spec (dev/devBridge).
   const betLevels = runtime.betLevels?.length ? runtime.betLevels : model.spec.betLevels;
   // Stake requires the default to come from authenticate on every entry; spec default is the dev fallback.
@@ -360,7 +368,9 @@ export function buildShellConfig(
   const authored = typeof opts.gameInfo === 'function' ? opts.gameInfo(t) : opts.gameInfo;
   // Pass t() through to spec-derived sections so symbol names, mode titles, and descriptions are
   // pre-translated before they reach the shell renderer.
-  let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime, t), authored);
+  // Cast to { sections?: GameInfoSection[] } (pixi-widened) so downstream map/filter calls work
+  // against the pixi section union. Host-derived sections never set `node`, so the widening is safe.
+  let gameInfo: { sections?: GameInfoSection[] } = mergeGameInfo(defaultGameInfo(model, runtime, t), authored) as { sections?: GameInfoSection[] };
   // The DISCLAIMER is required legal copy and must be shown VERBATIM — never socialized (its
   // wording is mandated, and word-swaps like "bet → play" would corrupt the legal text).
   if (isSocial) {

package/src/host/types.ts

@@ -2,7 +2,7 @@
 import type { ApplicationOptions } from 'pixi.js';
 import type { GameModel } from '@energy8platform/platform-core/game-spec';
 import type { AssetManifest, LoadingScreenConfig } from '@energy8platform/platform-core';
-import type { PixiGameShell } from '@energy8platform/pixi-shell';
+import type { Shell, PixiShellConfig } from '@energy8platform/shell/pixi';
 import type { AudioConfig, ScaleMode, Orientation, SceneConstructor } from '../types';
 import type { BookAdapter, AdapterModule, StakeBridge } from '@energy8platform/stake-bridge';
 import type { GameApplication } from '../core';
@@ -58,14 +58,25 @@ export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinRe
   dev?: boolean;
   stake?: StakeIntegration;
   shell?: SlotShellOptions;
+  /** Override how the control-bar shell is built. The host resolves the full shell config (theme,
+   *  features, gameInfo, currency, balance) and the Pixi mount (`app`/`parent`) and hands it to this
+   *  factory; return any `Shell` — e.g. `createShell({ renderer: new MyRenderer(...), ...config })`
+   *  to plug a custom renderer while the shell core still drives bet/balance/overlays. A custom
+   *  renderer can ignore `app`/`parent` and mount elsewhere (a DOM overlay, another canvas).
+   *  Default: the built-in Pixi shell (`createPixiShell`). */
+  shellFactory?: ShellFactory;
   /** Double-tap on the play area to skip the current spin animation. Default `true`. Set `false`
    *  to disable the gesture (e.g. games where a tap means something else). */
   skipGesture?: boolean;
   onFatalError?: (message: string) => void;
 }
 
+/** Builds the shell the host drives. Receives the fully-resolved Pixi shell config (a custom
+ *  renderer may ignore the `app`/`parent` mount fields). Must return a `Shell`. */
+export type ShellFactory = (config: PixiShellConfig) => Shell;
+
 export interface SlotGameHandle {
   game: GameApplication;
   stakeBridge: StakeBridge | null;
-  shell: PixiGameShell | null;
+  shell: Shell | null;
 }

package/src/shell/index.ts

@@ -1,10 +1,10 @@
-// Re-export the renderer-agnostic branded game shell from platform-core so
+// Re-export the renderer-agnostic branded game shell from @energy8platform/shell/html so
 // game-engine consumers can import it via @energy8platform/game-engine/shell.
 export {
   createGameShell,
   removeGameShell,
   GameShell,
-} from '@energy8platform/platform-core/shell';
+} from '@energy8platform/shell/html';
 export type {
   ShellConfig,
   ShellMode,
@@ -17,4 +17,5 @@ export type {
   GameInfoContent,
   AutoplayOptions,
   FreeSpinsState,
-} from '@energy8platform/platform-core/shell';
+  Lang,
+} from '@energy8platform/shell/html';

package/src/slot/cascade/TumbleController.ts

@@ -147,8 +147,11 @@ export class TumbleController {
     }
     this._undim();
 
-    // 3. gravity: survivors slide down, new cells drop from above
-    const rowStep = this._grid.cellPosition(0, 1).y - this._grid.cellPosition(0, 0).y;
+    // 3. gravity: survivors slide down, new cells drop from above (per-reel row step)
+    const rowStepOf = (col: number): number =>
+      this._grid.rowsOf(col) > 1
+        ? this._grid.cellPosition(col, 1).y - this._grid.cellPosition(col, 0).y
+        : this._grid.cellSize(col).height;
     const slides = this._cfg.gravity ? (step.drops ?? this.deriveDrops(step)) : [];
     const anims: Promise<void>[] = [];
 
@@ -172,7 +175,7 @@ export class TumbleController {
       cell.setState({ fresh: true });
       cell.alpha = 1;
       cell.scale.set(1);
-      cell.position.set(home.x, home.y - rowStep * (this._grid.rowsOf(n.col) + 1));
+      cell.position.set(home.x, home.y - rowStepOf(n.col) * (this._grid.rowsOf(n.col) + 1));
       const idx = (perCol[n.col] = (perCol[n.col] ?? 0) + 1);
       anims.push(
         (async () => {

package/src/slot/config/ReelSystemConfig.ts

@@ -8,6 +8,9 @@
 // Design notes are in docs/reels-analysis-and-design.md.
 
 import type { CellFrameStyle } from '../grid/SymbolCell';
+import { resolveGeometry, type CellSizeSpec, type ResolvedGeometry } from '../grid/geometry';
+
+export type { CellSizeSpec, ResolvedGeometry };
 
 /** Names of easing functions available in the engine's `Easing` map (see anim/easing-map.ts). */
 export type EasingName =
@@ -41,8 +44,19 @@ export interface GridConfig {
   rows: number;
   /** Per-reel row counts (Megaways / variable-height reels). Length should equal `cols`. */
   rowsPerReel?: number[];
+  /** Square cell size (shorthand: same width & height, all reels). */
   cellSize: number;
+  /** Rectangular cells, uniform across reels. Override `cellSize` when set. */
+  cellWidth?: number;
+  cellHeight?: number;
+  /** Per-strip cell size (square scalar or {width,height}). Overrides the above for that reel. */
+  cellSizePerReel?: CellSizeSpec[];
+  /** Uniform gap (shorthand for both axes). */
   gap: number;
+  /** Horizontal gap between adjacent reels. Scalar, or per-boundary (length cols-1). Overrides `gap`. */
+  colGap?: number | number[];
+  /** Vertical gap between rows. Scalar, or per-reel (length cols). Overrides `gap`. */
+  rowGap?: number | number[];
   evaluation: EvaluationMode;
   /** For Megaways: clamp per-reel rows to [minRows, maxRows]. */
   minRows?: number;
@@ -553,6 +567,11 @@ export function effectiveRowsPerReel(grid: GridConfig): number[] {
   return Array.from({ length: grid.cols }, () => grid.rows);
 }
 
+/** Resolve a `GridConfig` into a fully-populated per-reel geometry (rectangular / per-strip aware). */
+export function resolveGridGeometry(grid: GridConfig): ResolvedGeometry {
+  return resolveGeometry(grid);
+}
+
 /** Total ways-to-win for a ways/megaways grid (product of per-reel heights). */
 export function waysCount(grid: GridConfig): number {
   return effectiveRowsPerReel(grid).reduce((a, b) => a * b, 1);

package/src/slot/devtools/configDiff.ts

@@ -0,0 +1,41 @@
+// packages/game-engine/src/slot/devtools/configDiff.ts
+//
+// Compute the minimal override diff of a reel config against the defaults, and emit a
+// paste-ready `resolveReelConfig({...})` TypeScript snippet. Pure — no pixi, no DOM.
+
+import { resolveReelConfig, type ReelSystemConfig } from '../config/ReelSystemConfig';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/** Deep diff `obj` against `base`: arrays compared whole, objects recursed, scalars by !==. */
+export function configDiff(base: any, obj: any): any {
+  const out: any = {};
+  for (const k of Object.keys(obj ?? {})) {
+    const a = base?.[k];
+    const b = obj[k];
+    if (Array.isArray(b)) {
+      if (JSON.stringify(a) !== JSON.stringify(b)) out[k] = b;
+    } else if (b && typeof b === 'object') {
+      const d = configDiff(a ?? {}, b);
+      if (Object.keys(d).length) out[k] = d;
+    } else if (a !== b) {
+      out[k] = b;
+    }
+  }
+  return out;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+/** Diff a working config against DEFAULT_REEL_CONFIG (via resolveReelConfig()). */
+export function diffFromDefaults(config: ReelSystemConfig): Partial<ReelSystemConfig> {
+  return configDiff(resolveReelConfig(), config) as Partial<ReelSystemConfig>;
+}
+
+/** Emit a paste-ready TS module exporting the reel config as overrides-only. */
+export function emitReelConfigTs(config: ReelSystemConfig): string {
+  const diff = diffFromDefaults(config);
+  return (
+    `import { resolveReelConfig } from '@energy8platform/game-engine/slot';\n\n` +
+    `// Only the overrides vs DEFAULT_REEL_CONFIG.\n` +
+    `export const reelConfig = resolveReelConfig(${JSON.stringify(diff, null, 2)} as const);\n`
+  );
+}

package/src/slot/devtools/controlPanel.ts

@@ -0,0 +1,151 @@
+// packages/game-engine/src/slot/devtools/controlPanel.ts
+//
+// Renders the reel-config field schema into a DOM panel and binds each control to a
+// live config object. Pure DOM — no pixi. Shared by the harness reel sidebar and the
+// reel-lab playground.
+
+import { REEL_FIELD_SCHEMA, type Control, type Section } from './fieldSchema';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export function getPath(obj: any, path: string): any {
+  return path.split('.').reduce((o, k) => (o == null ? o : o[k]), obj);
+}
+export function setPath(obj: any, path: string, value: any): void {
+  const keys = path.split('.');
+  const last = keys.pop() as string;
+  const target = keys.reduce((o, k) => (o[k] ??= {}), obj);
+  target[last] = value;
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+
+export interface ControlPanelOptions {
+  /** The live config object the controls read from and mutate. */
+  config: unknown;
+  /** Called with the changed dot-path after each edit. */
+  onChange: (path: string) => void;
+  /** Schema to render. Defaults to REEL_FIELD_SCHEMA. */
+  schema?: Section[];
+}
+
+/** Build the control panel into `root`. Returns a `refresh()` that re-syncs inputs from config. */
+export function buildControlPanel(
+  root: HTMLElement,
+  opts: ControlPanelOptions,
+): { refresh: () => void } {
+  const schema = opts.schema ?? REEL_FIELD_SCHEMA;
+  const updaters: (() => void)[] = [];
+  root.innerHTML = '';
+  for (const section of schema) root.appendChild(renderSection(section, opts, updaters));
+  return { refresh: () => updaters.forEach((u) => u()) };
+}
+
+function renderSection(
+  section: Section,
+  opts: ControlPanelOptions,
+  updaters: (() => void)[],
+): HTMLElement {
+  const wrap = document.createElement('section');
+  wrap.className = 'panel-section';
+  const head = document.createElement('button');
+  head.className = 'section-head';
+  head.textContent = section.title;
+  const body = document.createElement('div');
+  body.className = 'section-body';
+  if (section.collapsed) body.style.display = 'none';
+  head.addEventListener('click', () => {
+    body.style.display = body.style.display === 'none' ? '' : 'none';
+  });
+  wrap.appendChild(head);
+  wrap.appendChild(body);
+  for (const c of section.controls) body.appendChild(renderControl(c, opts, updaters));
+  return wrap;
+}
+
+function renderControl(c: Control, opts: ControlPanelOptions, updaters: (() => void)[]): HTMLElement {
+  const row = document.createElement('label');
+  row.className = 'control';
+  const name = document.createElement('span');
+  name.className = 'control-label';
+  name.textContent = c.label;
+  row.appendChild(name);
+
+  const emit = (): void => opts.onChange(c.path);
+
+  if (c.kind === 'toggle') {
+    const input = document.createElement('input');
+    input.type = 'checkbox';
+    const sync = (): void => {
+      input.checked = !!getPath(opts.config, c.path);
+    };
+    sync();
+    input.addEventListener('change', () => {
+      setPath(opts.config, c.path, input.checked);
+      emit();
+    });
+    row.classList.add('control-toggle');
+    row.appendChild(input);
+    updaters.push(sync);
+  } else if (c.kind === 'select') {
+    const sel = document.createElement('select');
+    for (const o of c.options) {
+      const opt = document.createElement('option');
+      opt.value = o;
+      opt.textContent = o;
+      sel.appendChild(opt);
+    }
+    const sync = (): void => {
+      sel.value = String(getPath(opts.config, c.path));
+    };
+    sync();
+    sel.addEventListener('change', () => {
+      setPath(opts.config, c.path, sel.value);
+      emit();
+    });
+    row.appendChild(sel);
+    updaters.push(sync);
+  } else if (c.kind === 'range') {
+    const input = document.createElement('input');
+    input.type = 'range';
+    input.min = String(c.min);
+    input.max = String(c.max);
+    input.step = String(c.step);
+    const val = document.createElement('output');
+    val.className = 'control-value';
+    const sync = (): void => {
+      let raw = getPath(opts.config, c.path);
+      if ((raw == null || typeof raw !== 'number') && c.fallback != null)
+        raw = getPath(opts.config, c.fallback);
+      const v = Number(raw);
+      input.value = String(v);
+      val.textContent = String(v);
+    };
+    sync();
+    input.addEventListener('input', () => {
+      const v = Number(input.value);
+      setPath(opts.config, c.path, v);
+      val.textContent = String(v);
+      emit();
+    });
+    row.appendChild(input);
+    row.appendChild(val);
+    updaters.push(sync);
+  } else {
+    const input = document.createElement('input');
+    input.type = 'color';
+    const sync = (): void => {
+      input.value =
+        '#' +
+        Number(getPath(opts.config, c.path) ?? 0)
+          .toString(16)
+          .padStart(6, '0');
+    };
+    sync();
+    input.addEventListener('input', () => {
+      setPath(opts.config, c.path, parseInt(input.value.slice(1), 16));
+      emit();
+    });
+    row.appendChild(input);
+    updaters.push(sync);
+  }
+  return row;
+}