🕸️Game Engine Licensing

OmniSigma Game Engine — Technical Documentation

🎯Purpose & Scope

The OmniSigma Game Engine (OSGE) is a cross-platform, responsive runtime for instant, browser-based games. It provides:

• Deterministic visual/state orchestration over math outcomes from the Math API.

• A modular plugin system for rapid addition of new reels, features, animations, audio, and UI skins.

• Native integration with OmniSigma RGS, sessions, telemetry, and compliance tooling.

Targets: Chrome, Safari, Firefox, Edge (desktop & mobile), iOS WebView, Android WebView.

---

🧩Architecture Overview

Core (minimal and stable)

• Application (boot, resize, ticker)

• SceneManager (scene stack + transitions)

• ResourceManager (Pixi Assets, atlases, fonts, json, sounds)

• EventBus (typed pub/sub, no hard dependencies)

• Time/Ticker (bridging GSAP and Pixi ticker)

• AbstractDrawable (your base view: attach/detach, zIndex, mask, cleanup)

Systems (cross-game services)

• Audio (SoundManager)

• Input (pointer/keyboard, click guards)

• Localization (i18n/)

• Networking (game.websocket.ts + request/response queue)

• State (store + selectors; already using store.dispatch)

• Config (game configuration, RTP tables, paytable)

• UIFramework (modal/popup service, toast, fullscreen, verifyComponent)

Game (slot runtime)

• Grid (layout, symbol matrix)

• Reels (spin/stop mechanism, inertia, RNG hook)

• Symbols (atlas/id → sprite/spine)

• Lines (line calculation, highlight, win mask)

• Payout (win evaluation, scatter, bonus triggers)

• Controllers (orchestrators: FreeSpinController, LinesController, etc.)

• Assets (game-specific atlas mapping)

Features (self-contained mini-mechanics)

• freeSpin/ (enter/exit flow, counter, retrigger)

• wheel/ (wheel-of-fortune)

• bigwin/ (animation sequences, multipliers)

• loaderBonus/, bonusBalls/ (e.g. BaseBonusBall)

• Each feature includes: FeatureController, FeatureView, FeatureState (+ events)

UI (HUD + screens)

• menu/, balance/, betControlBar/, button/, volume/, fullscreen/

• popUpDialog/, noFundsMessage/, verifyComponent/

• responsiveText/, multiColorText/, slider/, scrollBox/, scrBox/

• tutorial/, gameNameLogo/, blueBackground/

Scenes/Flows

• LandingPage, MainPage, LoadingPage

• SlotMachine (main gameplay scene)

---

📱 Responsiveness & Aspect Ratio

Supported Aspect Ratios

• Landscape: 16:9, 16:10, 21:9

• Portrait: 9:16, 3:4

• Square: 1:1

Layout Strategies

• Adaptive Canvas Scaling (fit/cover with min/max scale).

• Anchors & Constraints for HUD, buttons, meters.

• Safe Area Insets (iOS notches, Android cutouts).

• Dynamic Grid: symbol cell size derives from viewport and reel/row count.

• Asset LOD: swap textures/audio quality by DPR & bandwidth.

Config Example

{
  "layout": {
    "orientation": "auto",
    "aspectPolicies": {
      "landscape": "fit-width",
      "portrait": "fit-height"
    },
    "safeAreaPadding": { "top": 24, "bottom": 24, "left": 12, "right": 12 }
  }
}

---

⚡ Renderer & Performance

• WebGL2 renderer with Canvas2D fallback.

• Sprite batching, texture atlases, object pooling.

• Delta-time capping (avoid jump animations on tab return).

• VSync aware; 60fps target, graceful degrade to 30fps.

• Memory budgeter (mobile): evict least-recent atlases, audio streams.

---

🔄 Lifecycle Flow

1. Application.boot() → initializes Pixi app, EventBus, ResourceManager, loads gameConfig.

2. SceneManager.push(LoadingPage) → loads all resources via ResourceManager.preload().

3. SceneManager.replace(SlotMachine):

   • Initializes Grid, Reels, SymbolFactory

   • Registers Controllers to EventBus (e.g., FREE_SPIN_TRIGGERED, SPIN_START, SPIN_STOP, etc.)

   • Binds HUD to state/selectors (balance, bet, etc.)

4. Gameplay loop (spin → evaluation → feature → settle).

5. Cleanup (scene.destroy() calls AbstractDrawable.destroy() recursively).

---

📏 Conventions and Rules

• Unidirectional flow: UI and Features never call Grid or Reels directly — they go through EventBus or controllers.

• Typed events & selectors: no any usage, rely on TypeScript for safety.

• GSAP only in views: Controllers only emit "start/stop/highlight" events.

• ZIndex policy: centralize in ZLayers.ts (e.g. BACKGROUND=0, REELS=10, HUD=100, MODAL=1000).

• Destroy discipline: every AbstractDrawable unsubscribes from EventBus/Ticker in destroy().

🎬 Animation & Tweening System

• Timeline-based sequencer with easing curves, bezier paths, spring.

• Row/line tweening (e.g., shimmer/trace across a payline, pulse on win).

• Symbol choreography: drop, bounce, shake, explode, trail, particle systems.

• Event-addressable “summoning” of animations:

  • Animations.summon(id, payload) to call any registered VFX.

• Async composition: parallel/sequential groups with awaitable Promises.

Animation Registration

Animations.register("winPulse", ({target, amount}) => 
  Timeline()
    .to(target.scale, {x:1.1, y:1.1, dur:0.12, ease:"outBack"})
    .to(target.scale, {x:1.0, y:1.0, dur:0.10, ease:"inQuad"})
    .repeat(Math.min(3, 1 + Math.floor(amount/10)))
);

🔊 Audio Engine

• WebAudio with fallback to HTML5 audio.

• Cue system tied to state events (spin_start, stop, feature_enter).

• Dynamic ducking for voice/VFX, latency-aware scheduling.

• Per-device volume caps; mute/persist via local storage.

Audio Cue Map

{
  "cues": {
    "spin_start": "sfx/spin_start.ogg",
    "reel_stop": "sfx/reel_stop_%{index}.ogg",
    "big_win": "music/big_win_loop.ogg"
  }
}

🗺️ Game State & Flow

State Machine

• IDLE → SPIN_REQUESTED → RESULT_RECEIVED → REVEAL → WINS_APPLIED → FEATURES → ROUND_END → IDLE

Round Controller

• Accepts Math API result; orchestrates reel stops, cascades, feature entries.

• Guarantees deterministic reveal order.

---

💻 Minimal Entry Point Example

// src/index.ts
import { Application } from "./core/Application";
import { SceneManager } from "./core/SceneManager";
import { LoadingPage } from "./scenes/LoadingPage";
import { SlotMachine } from "./scenes/SlotMachine";

async function main() {
  const app = await Application.boot({ width: 1280, height: 720 });
  const scenes = new SceneManager(app);

  await scenes.push(new LoadingPage(app));      // preload bundles
  await scenes.replace(new SlotMachine(app));   // start game
}

main();

🎰 Reels, Symbols & Mechanics

Reel Manager

• Supports fixed strips, weighted symbol bags, virtual reels, stacks, tower reels, expanding reels, reel sets switching.

• Stop map construction based on math outcome.

Mechanics Engines

• Lines (n-line), Ways (e.g., 243, 1024), Clusters, Cascades, Hold-and-Spin / Respin, Multipliers, Wild behaviors, Symbol upgrade, Link features, Pick features, Trail/meters.

• Volatility tuning via math inputs; RTP targets handled server-side.

Sample Game Definition

{
  "grid": { "reels": 5, "rows": [3,3,3,3,3] },
  "symbols": ["A","K","Q","J","10","9","WILD","SCATTER"],
  "reels": {
    "setId": "base",
    "strips": [
      ["A","K","Q","J","10","9","A","Q","WILD"],
      ["K","Q","J","10","9","K","SCATTER","Q","A"],
      ["Q","J","10","9","Q","A","WILD","K"],
      ["J","10","9","A","K","Q","J","SCATTER"],
      ["10","9","A","K","Q","WILD","A","K"]
    ]
  },
  "mechanics": { "type": "lines", "lines": 20 },
  "features": ["freeGames", "randomWilds", "bigWinCelebration"]
}

🎁 Feature Framework (Bonus/Events)

• Feature Bus: subscribe/emit lifecycle events (feature:enter, feature:exit).

• Pluggable modules for free rounds, respin, pick bonus, progressive multipliers, random events (e.g., symbol swaps).

• UI overlays and persistent meters with serialization.

Feature Contract

interface Feature {
  id: string;
  canEnter(ctx: RoundCtx): boolean;
  enter(ctx: RoundCtx): Promise<void>;
  onRoundEvent?(evt: RoundEvent, ctx: RoundCtx): void;
  exit(ctx: RoundCtx): Promise<void>;
}

🔗 Math/API Integration

• Server-authoritative results via RGS Math API.

• Client consumes SpinResult and renders accordingly; no client math decisions.

Spin Flow

await UI.lockInputs();
const req = buildSpinRequest({ stake: UI.stake(), session: Session.id });
const result = await MathApi.spin(req);             // network w/ retry/backoff
await Orchestrator.reveal(result);                  // reels, stops, wins, fx
await Payout.apply(result);
UI.unlockInputs();

Math Result (Example)

{
  "roundId":"r-834902",
  "stops":[12,8,33,5,21],
  "wins":[{"line":7,"amount":120,"symbols":["K","K","K"]}],
  "features":[{"id":"freeGames","spins":10,"multiplier":2}],
  "nextState":"FEATURE_PENDING"
}

🌐 RGS/Platform Integration

• Session API: create/resume, currency, limits, jurisdiction flags.

• Wallet Adapter: debit/credit, transactional safety, idempotency keys.

• Telemetry: round timings, fps, error codes, device profile.

• Remote Config: A/B feature toggles, RTP profile selection (server-side).

---

🖼️ Asset Pipeline

• Texture atlases (multi-dpi), webp/png fallback.

• Audio: ogg/opus primary, aac fallback.

• Localization: ICU messages, RTL support, font fallbacks.

• Theming/Skinning: color tokens, typography, symbol packs hot-swappable.

---

🤲 Input, Accessibility & UX

• Pointer/touch/keyboard; gesture affordances for mobile (swipe to spin).

• Focus order, screen-reader labels for controls, high-contrast theme.

• Haptics (where available), reduced-motion preference respected.

---

🧪 QA, Simulation & Telemetry

• Deterministic playback: record/replay of rounds (devtools).

• Auto-sim runner generating heatmaps for outcomes, feature hit rates.

• Golden-frame tests for reels/stop positions and animation baselines.

• Crash reporting with symbolicated stacks and breadcrumb logs.

---

🔒 Security & Compliance Hooks

• Obfuscation, runtime integrity checks, asset signature verification.

• Jurisdictional flags to toggle features/UX.

• Hooks for reality checks, session timers, limit banners (where required).

---

➕ Adding New Content (Fast Path)

Add a new reel set

1. Create strip CSV/JSON.

2. Reference in reels.sets[].

3. Bind to state (base/feature) via rules.

Add animations

Animations.register("rowTrace", ({row}) => 
  Timeline().add(TraceEffect.forRow(row)).to(...));

Add sounds

{ "cues": { "row_trace": "sfx/row_trace.ogg" } }

EventBus.on("row:highlight", r => Audio.play("row_trace"));

Add a feature

• Implement Feature interface, register with FeatureRegistry.register("myFeature", impl).

📡 Example of Public APIs

// core/EventBus.ts
export type Events =
  | { type: "SPIN_START" }
  | { type: "SPIN_STOP"; payload: { stops: number[] } }
  | { type: "WIN_EVALUATED"; payload: { total: number } }
  | { type: "FEATURE_TRIGGERED"; payload: { kind: "FREE_SPIN" | "WHEEL" } }
  | { type: "UI/OPEN_MODAL"; payload: { id: string } };

export interface IEventBus {
  on<T extends Events["type"]>(type: T, cb: (e: Extract<Events, {type: T}>) => void): () => void;
  emit(e: Events): void;
}

// game/controllers/FreeSpinController.ts (simplified)
export interface IFeatureController {
  canEnter(): boolean;
  enter(): Promise<void>;
  exit(): Promise<void>;
}

// core/ResourceManager.ts
export interface IResourceManager {
  loadBundle(name: string): Promise<void>;
  getTexture(id: string): Texture;
  getSound(id: string): Howl;
}

---

⚙️ Configuration Schemas (Excerpts)

EngineConfig

{
  "renderer": { "backend": "webgl2", "antialias": true },
  "layout": { "orientation": "auto", "minScale": 0.85, "maxScale": 1.25 },
  "assets": { "atlas": ["[e-mail]","[e-mail]"], "audio": ["bank1.json"] },
  "features": ["freeGames","randomWilds"],
  "telemetry": { "endpoint": "/t", "sampleRate": 0.25 }
}

TweenOpts

{ "dur": 0.35, "ease": "outCubic", "from": {"y":0}, "to": {"y":-12}, "repeat": 1, "yoyo": true }

---

🔁 Versioning & Backward Compatibility

• SemVer across engine core, mechanic plugins, and UI kits.

• Back-compat layer for schema evolution (symbol aliases, reel set migration).

• Deprecation window policy (two minor versions).

---

✅ Deliverables & Checklists

• ✅ Cross-device responsive behavior verified (phones, tablets, desktop, notches).

• ✅ 60fps target under typical loads; fallback to 30fps with quality scaling.

• ✅ Animation summon APIs & row tweening implemented.

• ✅ Easy addition of new reels, features, sounds, animations via registry.

• ✅ Integration with RGS Math API, sessions, telemetry.

• ✅ Security & compliance hooks wired.