@energy8platform/game-engine 0.23.0 → 0.25.0

package/src/slot/grid/ReelGrid.ts

@@ -1,6 +1,12 @@
 import { Container, Graphics, Sprite, type Texture } from 'pixi.js';
 import { SymbolCell, type CellData, type CellFrameStyle } from './SymbolCell';
 import type { SymbolResolver } from './SymbolView';
+import {
+  resolveGeometry,
+  cellPositionOf,
+  type CellSizeSpec,
+  type ResolvedGeometry,
+} from './geometry';
 
 export interface DecorationConfig {
   texture?: Texture;
@@ -12,8 +18,19 @@ export interface ReelGridConfig {
   rows: number;
   /** Per-reel row counts for Megaways / variable-height reels. Length must 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}). */
+  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[];
   resolve: SymbolResolver;
   frameStyle?: CellFrameStyle;
   decoration?: DecorationConfig;
@@ -21,17 +38,16 @@ export interface ReelGridConfig {
 }
 
 /**
- * A grid of `SymbolCell`s. Supports uniform grids and variable-height reels (Megaways):
- * when `rowsPerReel` is set each reel is vertically centred inside the tallest reel's envelope.
+ * A grid of `SymbolCell`s. Supports uniform grids, variable-height reels (Megaways), and
+ * rectangular / per-strip cell sizes with per-strip gaps. All layout flows through a single
+ * resolved geometry (see grid/geometry.ts); every consumer reads positions via `cellPosition`
+ * and dimensions via `cellSize(col)` rather than assuming a square cell.
  */
 export class ReelGrid extends Container {
   readonly __uiComponent = true as const;
 
-  private _cols: number;
-  private _rowsPerReel: number[];
-  private _maxRows: number;
-  private _cellSize: number;
-  private _gap: number;
+  private _cfg: ReelGridConfig;
+  private _geom: ResolvedGeometry;
   private _cells: SymbolCell[][] = [];
   private _cellLayer = new Container();
   private _resolve: SymbolResolver;
@@ -40,28 +56,18 @@ export class ReelGrid extends Container {
 
   constructor(config: ReelGridConfig) {
     super();
-    this._cols = config.cols;
-    this._rowsPerReel =
-      config.rowsPerReel && config.rowsPerReel.length === config.cols
-        ? config.rowsPerReel.slice()
-        : Array.from({ length: config.cols }, () => config.rows);
-    this._maxRows = Math.max(1, ...this._rowsPerReel);
-    this._cellSize = config.cellSize;
-    this._gap = config.gap ?? 0;
+    this._cfg = { ...config };
     this._resolve = config.resolve;
     this._frameStyle = config.frameStyle;
+    this._geom = resolveGeometry(config);
 
-    if (config.decoration) {
+    if (config.decoration?.texture) {
       const pad = config.decoration.padding ?? 0;
-      const w = this._cols * (this._cellSize + this._gap) - this._gap + pad * 2;
-      const h = this._maxRows * (this._cellSize + this._gap) - this._gap + pad * 2;
-      if (config.decoration.texture) {
-        const deco = new Sprite(config.decoration.texture);
-        deco.width = w;
-        deco.height = h;
-        deco.position.set(-pad - this._cellSize / 2, -pad - this._cellSize / 2);
-        this.addChild(deco);
-      }
+      const deco = new Sprite(config.decoration.texture);
+      deco.width = this._geom.gridW + pad * 2;
+      deco.height = this._geom.gridH + pad * 2;
+      deco.position.set(this._geom.leftX - pad, this._geom.topY - pad);
+      this.addChild(deco);
     }
 
     this.addChild(this._cellLayer);
@@ -70,12 +76,19 @@ export class ReelGrid extends Container {
     if (config.mask) this._applyMask();
   }
 
+  private get _cols(): number {
+    return this._geom.cols;
+  }
+  private get _rowsPerReel(): number[] {
+    return this._geom.rowsPerReel;
+  }
+
   private _buildCells(): void {
     for (let c = 0; c < this._cols; c++) {
       this._cells[c] = [];
       for (let r = 0; r < this._rowsPerReel[c]; r++) {
         const cell = new SymbolCell({
-          size: this._cellSize,
+          size: this.cellSize(c),
           resolve: this._resolve,
           frameStyle: this._frameStyle,
         });
@@ -87,10 +100,19 @@ export class ReelGrid extends Container {
     }
   }
 
+  /** Per-strip mask: one window per reel sized to that reel's own cell width × column height. */
   private _applyMask(): void {
-    const w = this._cols * (this._cellSize + this._gap) - this._gap;
-    const h = this._maxRows * (this._cellSize + this._gap) - this._gap;
-    const m = new Graphics().rect(-this._cellSize / 2, -this._cellSize / 2, w, h).fill(0xffffff);
+    const g = this._geom;
+    const m = new Graphics();
+    for (let c = 0; c < this._cols; c++) {
+      const rows = this._rowsPerReel[c];
+      const w = g.cellW[c];
+      const h = rows * g.cellH[c] + Math.max(0, rows - 1) * g.rowGap[c];
+      const x = g.colX[c] - w / 2;
+      const y = g.yOff[c] - g.cellH[c] / 2;
+      m.rect(x, y, w, h);
+    }
+    m.fill(0xffffff);
     this._cellLayer.mask = m;
     this.addChild(m);
     this._mask = m;
@@ -101,10 +123,15 @@ export class ReelGrid extends Container {
   }
   /** Tallest reel's row count (the grid's visual height in rows). */
   get rows(): number {
-    return this._maxRows;
+    return this._geom.maxRows;
+  }
+  /** Cell dimensions (px) for a reel. Rectangular / per-strip aware. */
+  cellSize(col: number): { width: number; height: number } {
+    return { width: this._geom.cellW[col] ?? 0, height: this._geom.cellH[col] ?? 0 };
   }
-  get cellSize(): number {
-    return this._cellSize;
+  /** The fully-resolved grid geometry (read-only view). */
+  get geometry(): ResolvedGeometry {
+    return this._geom;
   }
   rowsOf(col: number): number {
     return this._rowsPerReel[col] ?? 0;
@@ -113,12 +140,14 @@ export class ReelGrid extends Container {
     return this._rowsPerReel.slice();
   }
 
-  /** Cell centre position. Variable-height reels are centred in the max-rows envelope. */
+  /** Cell centre position. Variable-height reels are centred about a shared centre line. */
   cellPosition(col: number, row: number): { x: number; y: number } {
-    const step = this._cellSize + this._gap;
-    const reelRows = this._rowsPerReel[col] ?? this._maxRows;
-    const yOffset = ((this._maxRows - reelRows) / 2) * step;
-    return { x: col * step, y: yOffset + row * step };
+    return cellPositionOf(this._geom, col, row);
+  }
+
+  /** Grid bounding-box centre in local coords. */
+  center(): { x: number; y: number } {
+    return { x: this._geom.centerX, y: this._geom.centerY };
   }
 
   getCell(col: number, row: number): SymbolCell {
@@ -138,8 +167,8 @@ export class ReelGrid extends Container {
     if (rowsPerReel.length !== this._cols) return;
     this._cellLayer.removeChildren().forEach((c) => c.destroy());
     this._cells = [];
-    this._rowsPerReel = rowsPerReel.slice();
-    this._maxRows = Math.max(1, ...this._rowsPerReel);
+    this._cfg = { ...this._cfg, rowsPerReel: rowsPerReel.slice() };
+    this._geom = resolveGeometry(this._cfg);
     this._buildCells();
     if (this._mask) {
       this._mask.destroy();
@@ -149,8 +178,18 @@ export class ReelGrid extends Container {
     }
   }
 
-  resize(cellSize: number): void {
-    this._cellSize = cellSize;
+  /**
+   * Re-resolve geometry after a base cell-size change and reposition cells. Accepts a square
+   * scalar (updates `cellSize`) or explicit `{width,height}`. Per-strip overrides still apply.
+   * (Cell frames are not re-drawn here — a geometry change routes through a full rebuild upstream.)
+   */
+  resize(size: number | { width: number; height: number }): void {
+    if (typeof size === 'number') {
+      this._cfg = { ...this._cfg, cellSize: size, cellWidth: undefined, cellHeight: undefined };
+    } else {
+      this._cfg = { ...this._cfg, cellWidth: size.width, cellHeight: size.height };
+    }
+    this._geom = resolveGeometry(this._cfg);
     for (let c = 0; c < this._cols; c++) {
       for (let r = 0; r < this._rowsPerReel[c]; r++) {
         const { x, y } = this.cellPosition(c, r);

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 ───────────────────────────────────────────