Slot Flow

Command-based presentation framework for orchestrating visual effects and animations in slot machine games with support for cancellation and parallel execution.

Features

• Command pattern for atomic visual actions
• Sequential and parallel execution with Runner
• Presenter pattern for complex visual sequences
• Cooperative cancellation via AbortSignal
• Built-in commands for common slot effects

Installation

npm i @dreams-engine/slot-flow

Core Architecture

ICommand

Atomic visual action with execution and cancellation:

interface ICommand {
  readonly name: string;
  execute(signal: AbortSignal): Promise<void>;
  cancel?(reason?: string): void;
}

Runner

Executes command plans sequentially or in parallel:

const runner = new Runner();
await runner.run([
  command1,                    // Sequential
  [command2, command3],        // Parallel
  command4                     // Sequential
]);

IPresenter

High-level strategy for presentation sequences:

interface IPresenter<TPlanInput, TMachine> {
  present(input: TPlanInput, signal?: AbortSignal): Promise<void>;
  cancel(reason?: string): void;
}

Built-in Commands

DimCommand

Dims non-target symbols (default alpha: 0.4), with clear mode to restore all symbols:

new DimCommand(machine, positions, { alpha: 0.4, clear: false });

HighlightCommand

Ensures target symbols are fully visible (alpha: 1.0):

new HighlightCommand(machine, positions);

PlayWinCommand

Plays win animations with configurable duration:

new PlayWinCommand(machine, positions, { durationMs: 1200, revertToIdle: false });

Built-in Presenters

WinPresenter

Orchestrates standard win sequences: dim → highlight/animate → clear

const presenter = new WinPresenter(machine);
await presenter.present(winData);

Usage Examples

Basic Command Execution

import { Runner, DimCommand, HighlightCommand } from '@dreams-engine/slot-flow';

const runner = new Runner();
await runner.run([
  new DimCommand(machine, winMatrix),
  [
    new HighlightCommand(machine, winMatrix),
    new PlayWinCommand(machine, winMatrix)
  ],
  new DimCommand(machine, [], { clear: true })
]);

Win Presentation

const winData = [{
  symbolId: 'A',
  matrix: [0, 0, 0, null, null], // Win on first 3 reels, row 0
  amount: 100,
  total: 100
}];

const presenter = new WinPresenter(machine);
await presenter.present(winData);

Cancellation

const controller = new AbortController();
const execution = runner.run(plan, controller.signal);

// Cancel execution
setTimeout(() => {
  controller.abort();
  runner.cancel('timeout');
}, 2000);

Data Types

WinMatrix

Defines symbol positions for commands:

type WinMatrix = (number | number[] | null)[];

// Examples:
[0, 0, 0, null, null]           // Single row win
[[0, 1], [1, 2], 0, null, null] // Multiple positions

WinData

Win information for presentations:

interface WinData {
  symbolId: string;
  matrix: WinMatrix;
  amount: number;
  total: number;
  multiplier?: number;
  lineNumber?: number | null;
  cascade?: CascadeMatrix | null;
  wildWin?: boolean;
  meta?: Record<string, unknown>;
}

Symbol States

Commands manipulate symbols through:

• Visual properties: alpha and resetFilter()
• Animation states: setState('win') and setState('idle')
• Position calculation: Uses reel.extraCount + row formula

Dependencies

• @dreams-engine/slot: Core slot machine interfaces
• TypeScript: Full type safety support

Zero runtime dependencies beyond peer dependencies.