@energy8platform/game-engine 0.23.0 → 0.24.0

package/src/slot/grid/SymbolCell.ts

@@ -21,7 +21,8 @@ export interface CellState {
   fresh?: boolean;
 }
 export interface SymbolCellConfig {
-  size: number;
+  /** Square scalar or rectangular cell size in px. */
+  size: number | { width: number; height: number };
   resolve: SymbolResolver;
   frameStyle?: CellFrameStyle;
 }
@@ -34,10 +35,14 @@ const DEFAULT_STYLE: Required<CellFrameStyle> = {
   fresh: { color: 0xffffff, alpha: 0.6 },
 };
 
+const cellDims = (size: number | { width: number; height: number }) =>
+  typeof size === 'number' ? { width: size, height: size } : size;
+
 export class SymbolCell extends Container {
   readonly __uiComponent = true as const;
 
-  private _size: number;
+  private _w: number;
+  private _h: number;
   private _resolve: SymbolResolver;
   private _style: Required<CellFrameStyle>;
   private _frame: Graphics;
@@ -50,7 +55,9 @@ export class SymbolCell extends Container {
 
   constructor(config: SymbolCellConfig) {
     super();
-    this._size = config.size;
+    const { width, height } = cellDims(config.size);
+    this._w = width;
+    this._h = height;
     this._resolve = config.resolve;
     this._style = { ...DEFAULT_STYLE, ...(config.frameStyle ?? {}) } as Required<CellFrameStyle>;
     this._frame = new Graphics();
@@ -78,7 +85,7 @@ export class SymbolCell extends Container {
       }
       const v = this._resolve(data.symbol);
       if (v) {
-        v.resize?.(this._size);
+        v.resize?.({ width: this._w, height: this._h });
         this.addChildAt(v, 1); // above frame, below badges
         this._view = v;
       }
@@ -123,7 +130,7 @@ export class SymbolCell extends Container {
     const s = this._style[key];
     this._frame.clear();
     this._frame
-      .roundRect(-this._size / 2, -this._size / 2, this._size, this._size, this._style.radius)
+      .roundRect(-this._w / 2, -this._h / 2, this._w, this._h, this._style.radius)
       .fill({ color: s.color, alpha: s.alpha });
     // store the colour as tint for cheap inspection/testing
     this._frame.tint = s.color;
@@ -136,7 +143,7 @@ export class SymbolCell extends Container {
     }
     if (!value || value <= 1) return;
     this._multBadge = this._badge(`×${value}`, 0xffd24a);
-    this._multBadge.position.set(this._size / 2 - 12, -this._size / 2 + 12);
+    this._multBadge.position.set(this._w / 2 - 12, -this._h / 2 + 12);
     this._badges.addChild(this._multBadge);
   }
 
@@ -147,7 +154,7 @@ export class SymbolCell extends Container {
     }
     if (!value || value <= 0) return;
     this._bonusBadge = this._badge(`+${value}`, 0x7ad7ff);
-    this._bonusBadge.position.set(-this._size / 2 + 12, -this._size / 2 + 12);
+    this._bonusBadge.position.set(-this._w / 2 + 12, -this._h / 2 + 12);
     this._badges.addChild(this._bonusBadge);
   }
 

package/src/slot/grid/SymbolView.ts

@@ -5,8 +5,8 @@ export interface SymbolView extends Container {
   playIdle?(): void;
   playWin?(): Promise<void>;
   showStatic?(): void;
-  /** Resize the symbol to the given cell size in pixels. */
-  resize?(size: number): 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). */

package/src/slot/grid/geometry.ts

@@ -0,0 +1,155 @@
+// packages/game-engine/src/slot/grid/geometry.ts
+//
+// Pure geometry resolver for the reel grid. Turns the (backward-compatible) grid config
+// — a square `cellSize` + single `gap`, optionally overridden by rectangular / per-strip
+// dimensions and per-strip gaps — into a fully-resolved, per-reel layout.
+//
+// Coordinate convention (unchanged from the original square grid):
+//   - `cellPosition` returns CELL-CENTRE coordinates.
+//   - Cell (0,0)'s centre sits at local x = 0. Reels extend to the right.
+//   - Variable-height reels are vertically CENTRED about a shared centre line, so the
+//     tallest reel's row 0 sits at y = 0 (matching the old Megaways behaviour).
+//
+// See docs/reels-analysis-and-design.md §6.
+
+/** Per-strip cell size override: a square scalar, or an explicit width/height. */
+export type CellSizeSpec = number | { width: number; height: number };
+
+/** Structural input any grid config (GridConfig / ReelGridConfig) satisfies. */
+export interface GeometryInput {
+  cols: number;
+  /** Uniform row count. Ignored when `rowsPerReel` is set (and length matches `cols`). */
+  rows: number;
+  rowsPerReel?: number[];
+  /** Square cell size (shorthand: same width & height, all reels). */
+  cellSize: number;
+  /** Rectangular cells, uniform across reels. Override `cellSize`. */
+  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). */
+  colGap?: number | number[];
+  /** Vertical gap between rows. Scalar, or per-reel (length cols). */
+  rowGap?: number | number[];
+}
+
+export interface ResolvedGeometry {
+  cols: number;
+  rowsPerReel: number[];
+  maxRows: number;
+  /** Per-reel cell width / height (px). */
+  cellW: number[];
+  cellH: number[];
+  /** Per-reel vertical gap between rows (px). */
+  rowGap: number[];
+  /** Horizontal gap between reel i and i+1 (px), length cols-1. */
+  colGap: number[];
+  /** Cell-centre X of each reel (px). */
+  colX: number[];
+  /** Row-0 cell-centre Y of each reel (px) — centring offset baked in. */
+  yOff: number[];
+  /** Total grid bounding size (px). */
+  gridW: number;
+  gridH: number;
+  /** Grid bounding-box centre in local coords (px). */
+  centerX: number;
+  centerY: number;
+  /** Top-left corner of the grid bounding box in local coords (px). */
+  leftX: number;
+  topY: number;
+}
+
+const perReelSize = (spec: CellSizeSpec | undefined, w: number, h: number): [number, number] => {
+  if (typeof spec === 'number') return [spec, spec];
+  if (spec && typeof spec === 'object') return [spec.width, spec.height];
+  return [w, h];
+};
+
+const gapAt = (g: number | number[] | undefined, i: number, base: number): number =>
+  Array.isArray(g) ? (g[i] ?? base) : (g ?? base);
+
+/** Resolve a grid config into a fully-populated per-reel geometry. */
+export function resolveGeometry(g: GeometryInput): ResolvedGeometry {
+  const cols = Math.max(0, g.cols);
+  const rowsPerReel =
+    g.rowsPerReel && g.rowsPerReel.length === cols
+      ? g.rowsPerReel.slice()
+      : Array.from({ length: cols }, () => g.rows);
+  const maxRows = cols ? Math.max(1, ...rowsPerReel) : 0;
+
+  const baseW = g.cellWidth ?? g.cellSize;
+  const baseH = g.cellHeight ?? g.cellSize;
+  const baseGap = g.gap ?? 0;
+
+  const cellW: number[] = [];
+  const cellH: number[] = [];
+  const rowGap: number[] = [];
+  for (let c = 0; c < cols; c++) {
+    const [w, h] = perReelSize(g.cellSizePerReel?.[c], baseW, baseH);
+    cellW[c] = w;
+    cellH[c] = h;
+    rowGap[c] = gapAt(g.rowGap, c, baseGap);
+  }
+  const colGap: number[] = [];
+  for (let i = 0; i < Math.max(0, cols - 1); i++) colGap[i] = gapAt(g.colGap, i, baseGap);
+
+  // Horizontal: reel 0 centre at x = 0, then accumulate half-widths + between-reel gaps.
+  const colX: number[] = [];
+  if (cols) colX[0] = 0;
+  for (let c = 1; c < cols; c++)
+    colX[c] = colX[c - 1] + cellW[c - 1] / 2 + colGap[c - 1] + cellW[c] / 2;
+
+  // Vertical: each reel's rows span (rows-1)*step; centre every reel about a shared line so
+  // the tallest reel's row 0 stays at y = 0 (parity with the old uniform Megaways layout).
+  const span: number[] = rowsPerReel.map((rr, c) => Math.max(0, rr - 1) * (cellH[c] + rowGap[c]));
+  const halfMaxSpan = cols ? Math.max(...span) / 2 : 0;
+  const yOff: number[] = span.map((s) => halfMaxSpan - s / 2);
+
+  // Bounding box.
+  let leftX = 0;
+  let rightX = 0;
+  let topY = 0;
+  let bottomY = 0;
+  for (let c = 0; c < cols; c++) {
+    leftX = Math.min(leftX, colX[c] - cellW[c] / 2);
+    rightX = Math.max(rightX, colX[c] + cellW[c] / 2);
+    const reelTop = yOff[c] - cellH[c] / 2;
+    topY = Math.min(topY, reelTop);
+    bottomY = Math.max(bottomY, reelTop + rowsPerReel[c] * cellH[c] + Math.max(0, rowsPerReel[c] - 1) * rowGap[c]);
+  }
+  const gridW = rightX - leftX;
+  const gridH = bottomY - topY;
+
+  return {
+    cols,
+    rowsPerReel,
+    maxRows,
+    cellW,
+    cellH,
+    rowGap,
+    colGap,
+    colX,
+    yOff,
+    gridW,
+    gridH,
+    centerX: (leftX + rightX) / 2,
+    centerY: (topY + bottomY) / 2,
+    leftX,
+    topY,
+  };
+}
+
+/** Cell-centre position from a resolved geometry. */
+export function cellPositionOf(
+  geom: ResolvedGeometry,
+  col: number,
+  row: number,
+): { x: number; y: number } {
+  return {
+    x: geom.colX[col] ?? 0,
+    y: (geom.yOff[col] ?? 0) + row * ((geom.cellH[col] ?? 0) + (geom.rowGap[col] ?? 0)),
+  };
+}

package/src/slot/index.ts

@@ -5,6 +5,8 @@ export { SymbolCell } from './grid/SymbolCell';
 export type { CellFrameStyle, CellData, CellState, SymbolCellConfig } from './grid/SymbolCell';
 export { ReelGrid } from './grid/ReelGrid';
 export type { DecorationConfig, ReelGridConfig } from './grid/ReelGrid';
+export { resolveGeometry, cellPositionOf } from './grid/geometry';
+export type { GeometryInput, ResolvedGeometry, CellSizeSpec } from './grid/geometry';
 export { CascadeController } from './anim/CascadeController';
 export type { CascadeStepData, CascadeTimings, CascadeAnim } from './anim/CascadeController';
 export { ReelSpinController } from './anim/ReelSpinController';
@@ -19,6 +21,7 @@ export {
   resolveReelConfig,
   mergeReelConfig,
   effectiveRowsPerReel,
+  resolveGridGeometry,
   waysCount,
 } from './config/ReelSystemConfig';
 export type {

package/src/slot/motion/SpinEngine.ts

@@ -210,7 +210,7 @@ export class SpinEngine {
     tape.x = base.x;
     const landingStart = tapeLen - rows;
     for (let i = 0; i < tapeLen; i++) {
-      const cell = new SymbolCell({ size: this._grid.cellSize, resolve: this._resolve });
+      const cell = new SymbolCell({ size: this._grid.cellSize(p.reel), resolve: this._resolve });
       const sym =
         i >= landingStart
           ? (p.landing[i - landingStart]?.symbol ?? null)

package/src/slot/system/ReelSystem.ts

@@ -121,7 +121,12 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
       rows: config.grid.rows,
       rowsPerReel: config.grid.rowsPerReel ?? effectiveRowsPerReel(config.grid),
       cellSize: config.grid.cellSize,
+      cellWidth: config.grid.cellWidth,
+      cellHeight: config.grid.cellHeight,
+      cellSizePerReel: config.grid.cellSizePerReel,
       gap: config.grid.gap,
+      colGap: config.grid.colGap,
+      rowGap: config.grid.rowGap,
       resolve,
       frameStyle: config.grid.frameStyle,
       mask: config.grid.mask,
@@ -145,8 +150,13 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
       a.cols !== b.cols ||
       a.rows !== b.rows ||
       a.cellSize !== b.cellSize ||
+      a.cellWidth !== b.cellWidth ||
+      a.cellHeight !== b.cellHeight ||
       a.gap !== b.gap ||
       a.mask !== b.mask ||
+      JSON.stringify(a.cellSizePerReel) !== JSON.stringify(b.cellSizePerReel) ||
+      JSON.stringify(a.colGap) !== JSON.stringify(b.colGap) ||
+      JSON.stringify(a.rowGap) !== JSON.stringify(b.rowGap) ||
       JSON.stringify(a.rowsPerReel) !== JSON.stringify(b.rowsPerReel) ||
       (a.decoration?.padding ?? 0) !== (b.decoration?.padding ?? 0)
     );

package/src/types.ts

@@ -113,7 +113,7 @@ export interface GameApplicationConfig {
   debug?: boolean;
 
   /** When set, GameApplication mounts the branded game shell after the SDK handshake. */
-  shell?: import('@energy8platform/platform-core/shell').ShellConfig | false;
+  shell?: import('@energy8platform/shell/html').ShellConfig | false;
 }
 
 // ─── Scene Types ───────────────────────────────────────────