{"_id":"@dreams-engine/slot-state","_rev":"3-cf48ed2a91e03ddf7879547fff589749","name":"@dreams-engine/slot-state","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@dreams-engine/slot-state","version":"0.1.0","_id":"@dreams-engine/slot-state@0.1.0","maintainers":[{"name":"yujio","email":"xhuliomalaj37@gmail.com"}],"dist":{"shasum":"150484fafe34ac4170d09f86a2ef54c3bbaa657f","tarball":"https://registry.npmjs.org/@dreams-engine/slot-state/-/slot-state-0.1.0.tgz","fileCount":5,"integrity":"sha512-lqMEIJK7hoxAouFEYy3X8BgjXWOWqoAOTuorfjQ673e4X809GNxPhyx8u8EqG8u1JtzQfEthYwNOFss56PsMzQ==","signatures":[{"sig":"MEUCIEV4prQeNVMDTlngxlRAa2HUJ+HsrbWg+lb0/Rx5B9wKAiEAy2jw1KoKoG7quTc+OU+O+szASYmdS5bCjcJje34tRgo=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":82554},"main":"./dist/slot-engine-slot-state.umd.js","types":"./dist/index.d.ts","module":"./dist/slot-engine-slot-state.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/slot-engine-slot-state.mjs","require":"./dist/slot-engine-slot-state.umd.js"}},"gitHead":"feb9a96541a896e0aba1936690007acc6f2aaf01","scripts":{"dev":"vite build --watch","test":"vitest --config ../../vitest.config.ts","build":"vite build","clean":"rimraf dist","test:run":"vitest run --config ../../vitest.config.ts"},"_npmUser":{"name":"yujio","email":"xhuliomalaj37@gmail.com"},"_npmVersion":"10.9.2","description":"XState-based state machine for managing slot machine game flow, including spinning, autoplay, free spins, and presentation coordination.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"xstate":"^5.14.0"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^5.1.4","rimraf":"^5.0.5","pixi.js":"^8.1.1","typescript":"^5.3.3","@types/node":"^20.11.24","vite-plugin-dts":"^4.5.4","@dreams-engine/common":"workspace:*","@dreams-engine/slot-flow":"workspace:*"},"peerDependencies":{"tslib":"^2.6.2","pixi.js":"^8.1.1","@dreams-engine/slot":"workspace:*","@dreams-engine/engine":"workspace:*"},"_npmOperationalInternal":{"tmp":"tmp/slot-state_0.1.0_1777804278932_0.5470619494129487","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@dreams-engine/slot-state","version":"0.1.1","_id":"@dreams-engine/slot-state@0.1.1","maintainers":[{"name":"yujio","email":"xhuliomalaj37@gmail.com"}],"dist":{"shasum":"25878112d19b84d49ab6086909c6a6a3fb33aa10","tarball":"https://registry.npmjs.org/@dreams-engine/slot-state/-/slot-state-0.1.1.tgz","fileCount":5,"integrity":"sha512-B22kUQ85ry+XvbYDp4JvbUtM6JVxuUO2wShh0rkc70cte+GOkS4AZiWzRTVGh6OqVZu8TIkLjvRR+w0qMs8S/A==","signatures":[{"sig":"MEQCICrKyMskinXwIujyq3d7Cvi+omuT3ZvNOX4mY+I65d9LAiB7pufgD9RcQ54yH+xjXaalfdYyKyzQUxkshkV5BMP53w==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":82486},"main":"./dist/slot-engine-slot-state.umd.js","_from":"file:dreams-engine-slot-state-0.1.1.tgz","types":"./dist/index.d.ts","module":"./dist/slot-engine-slot-state.mjs","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/slot-engine-slot-state.mjs","require":"./dist/slot-engine-slot-state.umd.js"}},"scripts":{"dev":"vite build --watch","test":"vitest --config ../../vitest.config.ts","build":"vite build","clean":"rimraf dist","test:run":"vitest run --config ../../vitest.config.ts"},"_npmUser":{"name":"yujio","email":"xhuliomalaj37@gmail.com"},"_resolved":"C:\\Users\\GIGABYTE\\AppData\\Local\\Temp\\269419c9890df9acf7bb44fe615e53c8\\dreams-engine-slot-state-0.1.1.tgz","_integrity":"sha512-B22kUQ85ry+XvbYDp4JvbUtM6JVxuUO2wShh0rkc70cte+GOkS4AZiWzRTVGh6OqVZu8TIkLjvRR+w0qMs8S/A==","_npmVersion":"10.9.2","description":"XState-based state machine for managing slot machine game flow, including spinning, autoplay, free spins, and presentation coordination.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"xstate":"^5.14.0"},"_hasShrinkwrap":false,"devDependencies":{"vite":"^5.1.4","rimraf":"^5.0.5","pixi.js":"^8.1.1","typescript":"^5.3.3","@types/node":"^20.11.24","vite-plugin-dts":"^4.5.4","@dreams-engine/common":"1.0.1","@dreams-engine/slot-flow":"0.1.1"},"peerDependencies":{"tslib":"^2.6.2","pixi.js":"^8.1.1","@dreams-engine/slot":"1.0.1","@dreams-engine/engine":"1.0.1"},"_npmOperationalInternal":{"tmp":"tmp/slot-state_0.1.1_1777806912706_0.15916956651544778","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@dreams-engine/slot-state","version":"0.1.2","main":"./dist/slot-engine-slot-state.umd.js","module":"./dist/slot-engine-slot-state.mjs","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/slot-engine-slot-state.mjs","require":"./dist/slot-engine-slot-state.umd.js"}},"dependencies":{"xstate":"^5.14.0"},"peerDependencies":{"pixi.js":"^8.1.1","tslib":"^2.6.2","@dreams-engine/slot":"1.0.2","@dreams-engine/engine":"1.0.2"},"devDependencies":{"@types/node":"^20.11.24","rimraf":"^5.0.5","typescript":"^5.3.3","vite":"^5.1.4","pixi.js":"^8.1.1","vite-plugin-dts":"^4.5.4","@dreams-engine/slot-flow":"0.1.2","@dreams-engine/common":"1.0.2"},"scripts":{"build":"vite build","dev":"vite build --watch","clean":"rimraf dist","test":"vitest --config ../../vitest.config.ts","test:run":"vitest run --config ../../vitest.config.ts"},"_id":"@dreams-engine/slot-state@0.1.2","description":"XState-based state machine for managing slot machine game flow, including spinning, autoplay, free spins, and presentation coordination.","_integrity":"sha512-VDVLf8TCI0oCO5ZLke5HkPW4g85w4peOP+iNC7nFPQ7udYSkj9IjYO9olfgl4oKO8dGpD0TTqPeEfkElGI1HdA==","_resolved":"C:\\Users\\GIGABYTE\\AppData\\Local\\Temp\\670111bf03d3921725ccb9bbf935858e\\dreams-engine-slot-state-0.1.2.tgz","_from":"file:dreams-engine-slot-state-0.1.2.tgz","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-VDVLf8TCI0oCO5ZLke5HkPW4g85w4peOP+iNC7nFPQ7udYSkj9IjYO9olfgl4oKO8dGpD0TTqPeEfkElGI1HdA==","shasum":"6fff8fdfe7bce95e4d7305ed4d259ea255563c4c","tarball":"https://registry.npmjs.org/@dreams-engine/slot-state/-/slot-state-0.1.2.tgz","fileCount":5,"unpackedSize":82512,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIHyazdgldzyuWyWpdIVivMeEB4gDO5iuhIl27L4mgt69AiBrwoeCc16UDnokD1NBsRaJkbcXir0KU/Q43mVeze8TDw=="}]},"_npmUser":{"name":"yujio","email":"xhuliomalaj37@gmail.com"},"directories":{},"maintainers":[{"name":"yujio","email":"xhuliomalaj37@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/slot-state_0.1.2_1777929830062_0.20939022441902155"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-03T10:31:18.805Z","modified":"2026-05-04T21:23:50.325Z","0.1.0":"2026-05-03T10:31:19.104Z","0.1.1":"2026-05-03T11:15:12.858Z","0.1.2":"2026-05-04T21:23:50.213Z"},"description":"XState-based state machine for managing slot machine game flow, including spinning, autoplay, free spins, and presentation coordination.","maintainers":[{"name":"yujio","email":"xhuliomalaj37@gmail.com"}],"readme":"# Slot State\r\n\r\nXState-based state machine for managing slot machine game flow, including spinning, autoplay, free spins, and presentation coordination.\r\n\r\n## Features\r\n\r\n- State machine-driven game flow with XState 5\r\n- Spin cycle management (request, machine control, presentation)\r\n- Autoplay system with configurable limits and stops\r\n- Free spins state management with intro/playing/outro phases\r\n- Session management with automatic refresh and fallback\r\n- Configurable feature flags and delays\r\n- Win and big win presentation coordination\r\n- Game speed control (normal, quick, turbo)\r\n- Audio and UI state management\r\n\r\n## Installation\r\n\r\n```bash\r\nnpm i @dreams-engine/slot-state\r\n```\r\n\r\n## Core Architecture\r\n\r\n### Main State Machine\r\nCentral game controller managing all game states:\r\n\r\n```typescript\r\nimport { createSlotMachine } from '@dreams-engine/slot-state';\r\n\r\nconst slotOptions = {\r\n  transport: mockTransport,\r\n  auth: { token: 'demo-token' },\r\n  boot: { createGame: gameFactory },\r\n  features: { autoplay: true, winPresentation: true }\r\n};\r\n\r\nconst machine = createSlotMachine(slotOptions);\r\nconst actor = createActor(machine).start();\r\n```\r\n\r\n### State Flow\r\n**Main States:**\r\n- `boot` - Initial game loading and session setup\r\n- `idle` - Ready for player interaction\r\n- `spinning` - Active spin cycle\r\n- `freeSpins` - Free spin bonus rounds\r\n- `error` - Error/maintenance state\r\n\r\n### Child Machines\r\n\r\n#### SpinFlow Machine\r\nManages individual spin cycles:\r\n\r\n```typescript\r\n// Spin sequence: request → machine start → machine stop → presentation\r\nstates: {\r\n  requesting: {},      // HTTP spin request\r\n  machineSpinning: {}, // Physical reel spinning\r\n  presenting: {},      // Win presentations\r\n  done: {}            // Spin complete\r\n}\r\n```\r\n\r\n#### FreeSpins Machine  \r\nHandles free spin bonus rounds:\r\n\r\n```typescript\r\n// Free spin phases: intro → playing → outro\r\nstates: {\r\n  intro: {},    // Free spin introduction\r\n  playing: {},  // Active free spins\r\n  outro: {},    // Free spin conclusion\r\n  done: {}      // Return to base game\r\n}\r\n```\r\n\r\n#### Autoplay Machine\r\nControls automated spinning:\r\n\r\n```typescript\r\n// Autoplay cycle: waiting → trigger → awaiting → repeat\r\nstates: {\r\n  inactive: {},  // Autoplay disabled\r\n  waiting: {},   // Delay between spins\r\n  trigger: {},   // Request next spin\r\n  awaiting: {}   // Wait for spin completion\r\n}\r\n```\r\n\r\n## Configuration\r\n\r\n### SlotStateOptions\r\nMain configuration object:\r\n\r\n```typescript\r\ntype SlotStateOptions = {\r\n  transport?: Transport;           // Backend communication\r\n  auth?: AuthConfig;              // Authentication settings\r\n  boot?: GameBootstrapConfig;     // Game initialization\r\n  features?: FeatureFlags;        // Enabled features\r\n  delays?: DelayConfig;           // Timing configuration\r\n  presenters?: Presenters;        // Presentation handlers\r\n  adapters?: Adapters;            // Request/response adapters\r\n  machine?: IMachine;             // Pre-initialized slot machine\r\n};\r\n```\r\n\r\n### Feature Flags\r\nControl which features are enabled:\r\n\r\n```typescript\r\ntype FeatureFlags = {\r\n  autoplay?: boolean;           // Autoplay functionality\r\n  winPresentation?: boolean;    // Win animations\r\n  allowFsIntro?: boolean;       // Free spin introductions\r\n  allowFsOutro?: boolean;       // Free spin conclusions\r\n  bigWin?: boolean;            // Big win presentations\r\n  gameSpeed?: boolean;         // Speed control\r\n  soundFx?: boolean;           // Sound effects\r\n  music?: boolean;             // Background music\r\n  batterySave?: boolean;       // Battery optimization\r\n};\r\n```\r\n\r\n### Delay Configuration\r\nTiming settings for game flow:\r\n\r\n```typescript\r\ntype DelayConfig = {\r\n  winStartDelay?: number;        // Delay before win presentation\r\n  longRequestDelay?: number;     // Timeout for HTTP requests\r\n  delayAfterSpinEnd?: number;    // Pause after spin completion\r\n  minimumSpinDuration?: number;  // Minimum spin time\r\n  autoplayDelay?: number;        // Delay between autoplay spins\r\n};\r\n```\r\n\r\n## Events\r\n\r\n### UI Events\r\nPlayer-initiated actions:\r\n\r\n```typescript\r\n// Spinning\r\nactor.send({ type: 'UI_SPIN', payload: { betAmount: 10 } });\r\nactor.send({ type: 'UI_FORCE_STOP' });\r\n\r\n// Autoplay\r\nactor.send({ \r\n  type: 'UI_AUTOPLAY_TRIGGER', \r\n  count: 50, \r\n  stopOnFeature: true,\r\n  winLimit: 1000 \r\n});\r\n\r\n// Settings\r\nactor.send({ type: 'UI_SET_GAME_SPEED', speed: 'turbo' });\r\nactor.send({ type: 'UI_TOGGLE_SOUND_FX' });\r\n```\r\n\r\n### Machine Events\r\nInternal state transitions:\r\n\r\n```typescript\r\n// Spin cycle events\r\n{ type: 'MACHINE_SPIN_STARTED' }\r\n{ type: 'MACHINE_ALL_REELS_STOPPED' }\r\n{ type: 'PRESENTATION_DONE' }\r\n\r\n// Free spin events  \r\n{ type: 'FS_INTRO_COMPLETE' }\r\n{ type: 'FS_OUTRO_COMPLETE' }\r\n\r\n// System events\r\n{ type: 'SESSION_READY' }\r\n{ type: 'GAME_READY' }\r\n{ type: 'ERROR', message: string }\r\n```\r\n\r\n## Data Types\r\n\r\n### SpinResult\r\nServer response format:\r\n\r\n```typescript\r\ntype SpinResult = {\r\n  prevBalance: number;\r\n  balance: number;\r\n  betAmount: number;\r\n  reels?: string[][];              // Landing symbols\r\n  wins?: WinData[];               // Win information\r\n  bigWins?: BigWinData[];         // Big win information\r\n  roundWinAmount?: number;        // This spin's wins\r\n  totalWinAmount?: number;        // Total session wins\r\n  transition?: TransitionData;    // Game mode transitions\r\n  fs?: FreeSpinData;             // Free spin state\r\n};\r\n```\r\n\r\n### WinData\r\nIndividual win information:\r\n\r\n```typescript\r\ninterface WinData {\r\n  symbolId: string;               // Winning symbol\r\n  matrix: WinMatrix;             // Win positions\r\n  amount: number;                // Win amount\r\n  total: number;                 // Total amount\r\n  multiplier?: number;           // Win multiplier\r\n  lineNumber?: number;           // Payline number\r\n  cascade?: CascadeMatrix;       // Cascade information\r\n  wildWin?: boolean;             // Wild symbol win\r\n  meta?: Record<string, unknown>; // Additional data\r\n}\r\n```\r\n\r\n### AutoplayState\r\nAutoplay configuration and status:\r\n\r\n```typescript\r\ntype AutoplayState = {\r\n  active: boolean;               // Currently running\r\n  remaining: number;             // Spins left\r\n  initial: number;               // Original count\r\n  stopOnFeature: boolean;        // Stop on bonus features\r\n  totalWin: number;             // Session win total\r\n  winLimit?: number;            // Stop on win limit\r\n  lossLimit?: number;           // Stop on loss limit\r\n};\r\n```\r\n\r\n## State Context\r\n\r\n### GameContext\r\nComplete game state:\r\n\r\n```typescript\r\ntype GameContext = {\r\n  app?: Application;             // PIXI application\r\n  machine?: IMachine;            // Slot machine instance\r\n  transport?: Transport;         // HTTP transport\r\n  features: FeatureFlags;        // Enabled features\r\n  delays: DelayConfig;           // Timing settings\r\n  presenters: Presenters;        // Presentation handlers\r\n  \r\n  // Game state\r\n  balance: number;               // Current balance\r\n  prevBalance: number;           // Previous balance\r\n  betAmount: number;             // Current bet\r\n  isSpinning: boolean;          // Spin in progress\r\n  autoplay: AutoplayState;       // Autoplay status\r\n  gameSpeed: GameSpeed;          // Speed setting\r\n  gameReady: boolean;           // Game initialized\r\n  \r\n  // Session\r\n  sessionId?: string;           // Backend session\r\n  token?: string;               // Auth token\r\n  ping: number;                 // Last request latency\r\n  \r\n  // Features\r\n  soundFxEnabled: boolean;      // Sound effects on/off\r\n  musicEnabled: boolean;        // Music on/off\r\n  batterySaveEnabled: boolean;  // Battery save mode\r\n};\r\n```\r\n\r\n## Actor System\r\n\r\n### Master Bridge Actor\r\nBridges slot game presentation events to the state machine:\r\n\r\n```typescript\r\nimport { fromCallback } from 'xstate';\r\nimport { attachSlotBridge } from '@dreams-engine/slot';\r\n\r\n// Listens master application's events and forwards them to the state machine.\r\nexport const masterBridge = fromCallback(({ sendBack }) => {\r\n  const detach = attachSlotBridge({\r\n    onBigWinComplete: () => sendBack({ type: 'BIG_WIN_DONE' } as any),\r\n    onGameReady: () => sendBack({ type: 'GAME_READY' } as any),\r\n    onFreeSpinsIntroComplete: () => sendBack({ type: 'FS_INTRO_COMPLETE' } as any),\r\n    onFreeSpinsOutroComplete: () => sendBack({ type: 'FS_OUTRO_COMPLETE' } as any),\r\n  } as any);\r\n\r\n  return () => {\r\n    detach?.();\r\n  };\r\n});\r\n```\r\n\r\n**Bridge Events:**\r\n- `game:ready` → `GAME_READY` - Game initialization complete\r\n- `game:bigwincomplete` → `BIG_WIN_DONE` - Big win presentation finished\r\n- `game:fsintrocomplete` → `FS_INTRO_COMPLETE` - Free spins intro complete\r\n- `game:fsoutrocomplete` → `FS_OUTRO_COMPLETE` - Free spins outro complete\r\n\r\nThe bridge automatically attaches to the master application's event system and forwards presentation-level events to the state machine. It handles cleanup when the actor is stopped.\r\n\r\n## HTTP Transport\r\n\r\n### Transport Interface\r\nBackend communication:\r\n\r\n```typescript\r\ntype Transport = {\r\n  request<T>(params: { path: string; payload?: any }): Promise<T>;\r\n};\r\n```\r\n\r\n### Session Management\r\nAutomatic session handling:\r\n\r\n```typescript\r\n// Session refresh on 401 errors\r\ntry {\r\n  const data = await transport.request({ path: 'spin', payload: spinData });\r\n} catch (error) {\r\n  if (error.status === 401) {\r\n    // Auto-refresh session and retry\r\n    const newSession = await transport.request({ \r\n      path: 'session/refresh', \r\n      payload: { id: sessionId, token } \r\n    });\r\n    // Retry original request with new session\r\n  }\r\n}\r\n```\r\n\r\n## Presentation Integration\r\n\r\n### Win Presenter\r\nCoordinate with @dreams-engine/slot-flow:\r\n\r\n```typescript\r\nconst presenters = {\r\n  win: new WinPresenter(machine)\r\n};\r\n\r\nconst slotOptions = {\r\n  presenters,\r\n  features: { winPresentation: true }\r\n};\r\n```\r\n\r\n### Game Events\r\nListen to game events:\r\n\r\n```typescript\r\nimport { emitSlotEvent } from '@dreams-engine/slot';\r\n\r\n// Events emitted by state machine:\r\nemitSlotEvent('game:balancechange', { current: 1000, old: 990 });\r\nemitSlotEvent('game:autoplaychange', { autoplay: state });\r\nemitSlotEvent('game:fsintro', { remaining: 10, total: 10 });\r\nemitSlotEvent('game:speedchange', { speed: 'turbo' });\r\nemitSlotEvent('game:forcestop');\r\n```\r\n\r\n## Usage Examples\r\n\r\n### Basic Setup\r\n\r\n```typescript\r\nimport { createSlotMachine, createActor } from '@dreams-engine/slot-state';\r\n\r\nconst machine = createSlotMachine({\r\n  transport: mockTransport,\r\n  auth: { token: 'demo-token' },\r\n  boot: { \r\n    createGame: async ({ signal }) => {\r\n      const app = new Application();\r\n      await app.init();\r\n      return app;\r\n    }\r\n  }\r\n});\r\n\r\nconst actor = createActor(machine);\r\nactor.start();\r\n\r\n// Trigger spin\r\nactor.send({ type: 'UI_SPIN' });\r\n```\r\n\r\n> **Note:** This is a basic example for demonstration. In production environments (such as in `@dreams-engine/slot-launcher`), actor initialization is handled within service layers with additional features like state subscription management, canvas attachment, cleanup handling, and error management. See the `SlotStateService` in the slot-launcher package for the complete production implementation.\r\n\r\n### Autoplay Configuration\r\n\r\n```typescript\r\n// Start 100 autoplay spins, stop on bonus features\r\nactor.send({ \r\n  type: 'UI_AUTOPLAY_TRIGGER',\r\n  count: 100,\r\n  stopOnFeature: true,\r\n  winLimit: 5000,\r\n  lossLimit: 1000\r\n});\r\n\r\n// Cancel autoplay\r\nactor.send({ type: 'AUTOPLAY_CANCEL' });\r\n```\r\n\r\n### State Observation\r\n\r\n```typescript\r\nactor.subscribe((state) => {\r\n  console.log('Current state:', state.value);\r\n  console.log('Balance:', state.context.balance);\r\n  console.log('Is spinning:', state.context.isSpinning);\r\n  console.log('Autoplay active:', state.context.autoplay.active);\r\n});\r\n```\r\n\r\n## Dependencies\r\n\r\n- **XState 5**: State machine implementation\r\n- **@dreams-engine/slot**: Core slot machine interfaces\r\n- **@dreams-engine/engine**: Game engine integration\r\n- **@dreams-engine/slot-flow**: Presentation coordination\r\n- **PIXI.js**: Graphics framework integration\r\n\r\nThe package provides a complete state management solution for slot machine games with robust error handling, session management, and presentation coordination.\r\n","readmeFilename":"README.md"}