stakeengine/web-sdk

1. Repository shape

This is a Turborepo monorepo for a web SDK aimed at building and launching Stake Engine games. The top-level split is:

• apps/*: complete playable game apps (lines, cluster, scatter, price, ways, number-picker)

• packages/*: reusable building blocks for rendering, state, game flow, UI, utilities, and tooling

• root config: pnpm workspace, TurboRepo, shared lint/format settings, plus caddyfile for static hosting

2. Primary runtime model

Each app is a SvelteKit application that renders a game shell and is designed to ship as a static frontend. The game surface is mostly PixiJS-driven visuals wrapped by Svelte components, while HTML/Svelte is used for orchestration, overlays, and UI panels. The repo is optimized for local dev, Storybook-driven testing, and static build output for Stake Engine deployment.

3. App-level composition

Every app has the same high-level entry pattern:

• src/routes/+page.svelte sets up app context

• src/components/Game.svelte is the main game composition root

• src/game/* contains the app-specific state, event mapping, config, and actor logic

• src/stories/* provides Storybook scenarios for books and single book events

• static/assets/* holds the game’s audio, fonts, Spine atlases/JSON, and spritesheets

The apps differ by game mechanic and component set. For example:

• lines is the base line game

• cluster and scatter use cluster/tumble style structures

• price adds expanding/sticky wild mechanics

• number-picker is much smaller and mostly shows the same state/flow patterns in a reduced form

4. Shared domain model: books and bookEvents

The central game-data abstraction is the book returned by the RGS/math side. A book contains an ordered list of bookEvents. Apps replay those bookEvents locally to reproduce the round. Storybook uses this same model with static fixture data under src/stories/data/*, which lets developers test full rounds, specific event types, or random books without a live backend.

5. Event-driven execution flow

The key runtime flow is:

• a bookEvent is read

• bookEventHandlerMap selects the handler for that event type

• the handler emits one or more emitterEvents

• Svelte components subscribe to those emitterEvents and animate/update themselves

• async emitterEvents can be awaited so later steps only happen after animations finish

This creates a clear separation between game rules and visual timing. The repo emphasizes “task breakdown”: a single complex bookEvent is often decomposed into many smaller emitterEvents distributed across components.

6. State and control boundaries

Each app builds four major contexts at the entry boundary:

• eventEmitter: pub/sub channel between game logic and components

• stateXstate: finite state machine for bet/render/play/resume states

• stateLayout: viewport, orientation, canvas sizing, and responsive layout info

• stateApp: app/asset loading state and Pixi application reference

This is a strong architectural boundary: game logic reads/writes shared state through these contexts instead of passing props through deep trees.

7. XState as the game-control layer

packages/utils-xstate and each app’s src/game/stateXstate.ts formalize the betting lifecycle with an XState machine. That machine handles states like rendering, idle, bet, auto-bet, and resume-bet, and prevents UI actions from conflicting with active gameplay. UI components typically consult derived state like isPlaying() or isBetting() to disable controls at the right time.

8. Rendering stack

The visual engine is PixiJS 8, integrated through the in-house pixi-svelte package. That package provides Svelte components for Pixi primitives such as App, Container, Sprite, Spine, Text, Graphics, Particle systems, and asset loading. Game apps then build domain-specific components on top of those primitives, often using Spine animations and sprite sheets stored under each app’s static/assets.

9. UI package split

The UI is split into two reusable layers:

• components-ui-pixi: Pixi-based in-game UI widgets such as bet buttons, labels, orientation-specific layouts, and UI chrome

• components-ui-html: HTML/Svelte overlays and modals such as settings, paytable, game rules, auto-spin, buy bonus, and error dialogs

This separation matters architecturally: Pixi handles the animated game canvas, while HTML handles traditional overlay UI and dialogs.

10. Reusable infrastructure packages

Several packages form the shared backend of the frontend architecture:

• utils-book: sequencing and execution helpers for books/bookEvents

• utils-event-emitter: typed event bus and Svelte context wiring

• utils-layout: responsive canvas/layout state

• utils-sound: audio playback helpers

• utils-slots: slot-specific board/reel/tumble helpers

• constants-shared, utils-shared, state-shared: cross-app constants, helpers, and Svelte state modules

• config-*: shared TS/Svelte/Vite/Storybook/Lingui config packages

These packages keep app code focused on game specifics rather than infrastructure repetition.

11. Storybook as a first-class test harness

Storybook is not just documentation here; it is the main interactive test environment. It can run:

• component-level stories

• single bookEvent stories

• full book playback stories for base, bonus, and special modes

That means the architecture is designed so any game mechanic can be validated in isolation before being wired into the full app flow.

12. Assets and loading pipeline

All app-specific runtime assets live in static/assets, including:

• audio files and sound manifests

• fonts for stylized number rendering

• Spine animations for reels, wins, transitions, loaders, multipliers, and feature sequences

• spritesheets for symbols, UI frames, coin effects, and text

The app loading layer uses stateApp.loadedAssets so Pixi components can consume already-loaded assets rather than managing fetch/load concerns themselves.

13. Internationalisation

i18n is implemented per app and per UI package using Lingui-derived message maps, with English and Chinese message sources visible in the repo. The architecture supports locale-aware text without entangling localization with game logic; this is important for Stake-style variants such as social-casino text changes.

14. Deployment boundary

The repository is meant to produce static frontend builds that are then uploaded into Stake Engine. The README shows the expected build artifact flow: prerendered index.html plus client assets copied into a deployable directory. caddyfile indicates a simple static-serving deployment path rather than a custom server runtime.