@rb-games/core 0.1.0

package/README.md

@@ -0,0 +1,488 @@
+# @rb-games/core
+
+Core game engine package for RB Games framework. This package provides the foundational engine, plugin system, and utilities for building casino games.
+
+## Installation
+
+```bash
+npm install @rb-games/core
+# or
+yarn add @rb-games/core
+```
+
+## Quick Start
+
+```typescript
+import { PixiEngine } from '@rb-games/core/engine';
+import { ScenePlugin, ResourcePlugin } from '@rb-games/core/plugins';
+
+const engine = new PixiEngine({
+  width: 1920,
+  height: 1080,
+  backgroundColor: 0x1a1a1a,
+});
+
+// Register plugins
+engine.registerPlugin(new ResourcePlugin());
+engine.registerPlugin(new ScenePlugin());
+
+// Initialize
+await engine.init(document.getElementById('game-container'));
+```
+
+## Documentation
+
+Generate API documentation:
+
+```bash
+yarn docs
+```
+
+View documentation in browser:
+
+```bash
+yarn docs:serve
+# Opens at http://localhost:3001
+```
+
+---
+
+# Core Engine & Plugin System
+
+This document describes the core game engine architecture and the plugin system used in the `@rb-games/core` package.  
+It explains:
+
+- How the `PixiEngine` works
+- How plugins are defined and initialized
+- The plugin lifecycle
+- A short description of each core plugin
+
+---
+
+## 1. Overview
+
+The core package provides a lightweight game engine on top of [PixiJS].  
+Games (e.g. slot games) do not talk to Pixi directly; instead they use:
+
+- `PixiEngine` – a wrapper around `Pixi.Application`
+- A **plugin-based architecture** to add features such as:
+  - Rendering and layout
+  - Asset and resource loading
+  - Input handling
+  - Scene management
+  - Localization
+  - Device/network optimization
+  - Error tracking, etc.
+
+Typical game startup flow (example from a slot game):
+
+1. Game calls `setupApplication(container)` from the slot base module.
+2. `setupApplication` creates a `PixiEngine` instance.
+3. Core plugins are registered on the engine.
+4. `engine.initialize()` is called:
+   - Pixi application is initialized
+   - Plugins are initialized in the correct order
+   - Plugins are finalized and marked as ready
+5. Game scenes are registered and the initial scene is activated.
+
+---
+
+## 2. PixiEngine
+
+`PixiEngine` is the central runtime object:
+
+- Wraps a `Pixi.Application` instance
+- Manages **plugin registration, ordering, initialization, and lifecycle**
+- Exposes shared data storage
+- Handles window resize and per-frame updates
+- Provides access to the underlying Pixi app and stage
+
+Key responsibilities:
+
+- Initialize Pixi (`_pixiApp.init`) with configured width/height, antialias, etc.
+- Append the canvas to the DOM.
+- Maintain a `Map<string, EnginePlugin>` of registered plugins.
+- Track plugin states (`registered → initializing → initialized → ready`).
+- Sort plugins by **priority** and **dependencies** before initializing.
+- Drive the frame update loop by calling plugin `onUpdate`.
+- Handle global resize logic by calling plugin `onResize` first, then falling back to default resize behavior when not handled.
+
+---
+
+## 3. Plugin Architecture
+
+### 3.1 EnginePlugin Interface
+
+All engine plugins implement the `EnginePlugin` interface:
+
+```ts
+export interface EnginePlugin {
+  name: string; // Unique name of the plugin
+  priority: number; // Lower number = higher priority
+  state?: PluginState; // Current lifecycle state
+  dependencies?: string[]; // Other plugins that must be ready first
+
+  initialize(engine: PixiEngine): Promise<void> | void;
+
+  onReady?(engine: PixiEngine): Promise<void> | void;
+
+  cleanup?(): void;
+
+  onUpdate?(delta: number): boolean;
+
+  onResize?(width: number, height: number): boolean;
+}
+```
+
+This design allows each feature (rendering, resources, input, etc.) to be implemented as a self-contained plugin that can:
+
+- Run setup code on initialization,
+- Interact with other plugins after they are ready,
+- Participate in per-frame updates,
+- React to window resize events,
+- Perform cleanup when necessary.
+
+### 3.2 PluginState
+
+The lifecycle state of a plugin is represented by `PluginState`:
+
+```ts
+export enum PluginState {
+  REGISTERED = 'registered',
+  INITIALIZING = 'initializing',
+  INITIALIZED = 'initialized',
+  READY = 'ready',
+  ERROR = 'error',
+}
+```
+
+The engine transitions plugins through these states and logs all transitions for easier debugging.
+
+### 3.3 Registration and Ordering
+
+Plugins are registered via:
+
+```ts
+engine.registerPlugin(pluginInstance);
+```
+
+During registration:
+
+- Duplicate names are rejected.
+- Plugin state is set to `REGISTERED`.
+- If the engine was already initialized, the new plugin is immediately initialized.
+
+When `engine.initialize()` is called, the engine:
+
+1. Sorts all plugins primarily by `priority` (ascending; lower = earlier).
+2. Resolves the dependency graph:
+   - Ensures that dependencies are initialized before dependants.
+   - Detects circular dependencies and logs warnings.
+   - Collects missing dependencies and throws an error with a detailed message if any are missing.
+3. Calls the lifecycle methods in order (see below).
+
+---
+
+## 4. Plugin Lifecycle
+
+The engine lifecycle for plugins consists of two main phases: **initialization** and **finalization (ready)**.
+
+### 4.1 Initialization Phase
+
+For each registered plugin (in sorted order):
+
+1. The engine sets the plugin state to `INITIALIZING`.
+2. The engine calls `plugin.initialize(engine)`.
+3. On success, the engine sets the plugin state to `INITIALIZED`.
+4. On error, the plugin state is set to `ERROR` and the error is logged (and may be rethrown).
+
+This phase is meant for:
+
+- Internal setup
+- Registering data with the engine
+- Preparing resources needed by the plugin itself
+
+### 4.2 Ready Phase (onReady)
+
+After all plugins have been initialized, the engine runs a second pass:
+
+- Calls `plugin.onReady(engine)` for each plugin that implements it.
+- Sets the plugin state to `READY`.
+- Adds the plugin name to the `readyPlugins` set.
+
+This phase is designed for:
+
+- Cross-plugin integration
+- Accessing other plugins safely (e.g. a Scene plugin waiting for I18N or resources)
+- Hooking into engine events once everything is prepared
+
+Plugins can use helper APIs like `engine.waitForPlugins([...])` to wait for certain plugins to be ready before proceeding.
+
+### 4.3 Update Phase
+
+Every frame, the engine calls:
+
+```ts
+engine.onUpdate(deltaTime);
+```
+
+which internally:
+
+- Fetches the list of plugins, sorted by priority (highest priority first).
+- Calls `plugin.onUpdate(deltaTime)` for each plugin that implements it.
+- If a plugin returns `true`, the engine stops propagating the update to lower priority plugins (the update was “handled”).
+
+This allows high-priority plugins to “consume” the update if necessary.
+
+### 4.4 Resize Phase
+
+On window resize, the engine:
+
+1. Fetches the sorted plugin list.
+2. Calls `plugin.onResize(width, height)` for each plugin that implements it.
+3. If any plugin returns `true`, the resize event is considered handled.
+4. If no plugin handles the resize, the engine performs a default `renderer.resize(width, height)`.
+
+This pattern lets a display/layout plugin take complete control over how the game area is resized while still providing a safe fallback.
+
+---
+
+## 5. Data Storage in the Engine
+
+The engine exposes a small key/value storage API:
+
+- `engine.setData(key, value)`
+- `engine.getData(key)`
+- `engine.removeData(key)`
+
+Plugins and higher-level systems can use this shared storage to exchange small pieces of data without introducing hard dependencies.
+
+---
+
+## 6. Core Plugin Descriptions
+
+Below is a short overview of the main core plugins that are typically used by slot games.
+
+> Note: Actual implementation details live under `packages/core/plugins`.
+
+### 6.1 DeviceOptimizerPlugin
+
+**Purpose**
+
+- Collects and/or uses device- and environment-related information:
+  - Network characteristics
+  - Battery status (where available)
+  - Potentially other performance metrics
+
+**Typical Responsibilities**
+
+- Optimize quality settings or asset resolution based on device capabilities.
+- Enable/disable certain effects or features depending on network and battery conditions.
+- Provide a consistent way for other plugins or game logic to query device/environment data.
+
+**Special Notes**
+
+- Often configured with debug flags that are only true in development (`NODE_ENV === 'development'`).
+- Typically registered very early (high priority) so other plugins can adapt based on its results.
+
+---
+
+### 6.2 ResourcePlugin
+
+**Purpose**
+
+- Manages loading of all game assets (graphics, spritesheets, fonts, etc.).
+- Provides a higher-level bundle system on top of Pixi’s resources.
+
+**Typical Responsibilities**
+
+- Configure a `basePath` for all graphic assets (e.g. `/assets/graphics/`).
+- Support multiple resolutions:
+  - `availableResolutions: [0.25, 0.5, 1.0, 2.0]`
+- Define **bundles**:
+  - `preload-pack` – critical assets needed to boot the game.
+  - `game-pack` – main game assets.
+  - `gamble-pack` – optional, lazy-loaded assets.
+- Load fonts from remote URLs and register them with aliases.
+
+**API Examples**
+
+- `resourcePlugin.loadCriticalAssets(onProgress)` – load essential assets, with optional progress callback.
+- `resourcePlugin.preloadAssets()` – preload all non-lazy assets.
+
+---
+
+### 6.3 GsapPlugin
+
+**Purpose**
+
+- Integrates [GSAP] into the engine’s update loop.
+
+**Typical Responsibilities**
+
+- Manage and tick GSAP timelines each frame.
+- Provide a unified place to configure GSAP and synchronize it with the engine.
+
+**Benefits**
+
+- Games can use rich animations while staying in sync with the engine’s global timing.
+
+---
+
+### 6.4 DisplayPlugin
+
+**Purpose**
+
+- Manages the main display pipeline:
+  - Virtual resolution
+  - Scaling behavior
+  - Layout of the root stage/container
+
+**Typical Responsibilities**
+
+- Configure width/height (e.g. 1920x1080).
+- Implement scaling strategies like `contain`, `cover`, etc.
+- Position and scale the main scene container on resize.
+
+**Benefits**
+
+- Centralize all display and layout logic instead of duplicating it in each game.
+
+---
+
+### 6.5 I18NextPlugin
+
+**Purpose**
+
+- Provides localization support based on [i18next] or a similar solution.
+
+**Typical Responsibilities**
+
+- Load translation resources.
+- Offer an API for reading localized strings.
+- Manage active language / locale selection.
+
+**Benefits**
+
+- Games can be localized without each game re-implementing translation handling.
+- Other plugins (e.g. Skin or Scene) can depend on localization being ready.
+
+---
+
+### 6.6 InputPlugin
+
+**Purpose**
+
+- Centralizes all user input handling (mouse, touch, keyboard, etc.).
+
+**Typical Responsibilities**
+
+- Normalize different input sources into a set of consistent events.
+- Provide configuration such as:
+  - `enabled`: enable/disable input globally.
+  - `debug`: whether to log input events.
+  - `repeatRate`: control input repetition.
+
+**Benefits**
+
+- Single source of truth for user input.
+- Easier debugging and control (e.g. disabling input during transitions or modals).
+
+---
+
+### 6.7 SkinPlugin
+
+**Purpose**
+
+- Manages visual skins and themes for the game.
+
+**Typical Responsibilities**
+
+- Load and apply different skins (e.g. different art packs or themes).
+- Potentially integrate with localization (e.g. language-specific logos or typography).
+
+**Benefits**
+
+- Allows multiple visual variations of the same game logic (e.g. brand skins) without duplicating the code.
+
+---
+
+### 6.8 ScenePlugin
+
+**Purpose**
+
+- Provides a **scene management system** for the game.
+
+**Typical Responsibilities**
+
+- Register scenes by name.
+- Switch between scenes (`switchScene('mainMenu')`, etc.).
+- Manage the active scene’s lifecycle and transitions.
+
+**Example**
+
+- In a typical slot setup:
+  - A `mainMenu` scene is registered (e.g. an `EmptyScene` or full main menu scene).
+  - The plugin switches to `mainMenu` after all critical assets are ready.
+
+**Benefits**
+
+- Clear structure for complex games with multiple states (loading, lobby, game, bonus, etc.).
+- Unified approach to scene transitions and cleanup.
+
+---
+
+### 6.9 SentryPlugin (Optional)
+
+**Purpose**
+
+- Integrates error tracking using [Sentry].
+
+**Typical Responsibilities**
+
+- Initialize Sentry with a given DSN.
+- Capture and report unhandled errors or custom events.
+- Optionally enrich events with device or game state information.
+
+**Notes**
+
+- The plugin may be optional and only enabled in certain environments.
+- Setup code is usually small but powerful for monitoring production issues.
+
+---
+
+## 7. Adding New Plugins
+
+To add a new plugin:
+
+1. Implement the `EnginePlugin` interface.
+2. Choose a unique `name` and a sensible `priority`.
+3. Optionally declare `dependencies` on other plugins.
+4. Implement `initialize(engine)` to set up your plugin.
+5. Optionally implement:
+   - `onReady(engine)` for cross-plugin integration,
+   - `onUpdate(delta)` to participate in the frame loop,
+   - `onResize(width, height)` for layout changes,
+   - `cleanup()` for teardown.
+6. Register the plugin in your game or base module:
+
+```ts
+const myPlugin = new MyCustomPlugin(/* config */);
+engine.registerPlugin(myPlugin);
+```
+
+7. Ensure that:
+   - Dependencies are also registered,
+   - Plugin ordering (priority) does not conflict with other core systems.
+
+---
+
+## 8. Summary
+
+The core engine and plugin system are designed to:
+
+- Make casino/slot game development **faster and more consistent**,
+- Provide a reusable, testable, and debuggable foundation,
+- Allow each concern (rendering, input, scenes, resources, localization, optimization, analytics, etc.) to live in its own plugin.
+
+By building on this foundation, new games can focus on game-specific rules and content, while relying on `PixiEngine` and its plugins for all shared infrastructure.

package/dist/devtools/DraggableController.d.ts

@@ -0,0 +1,10 @@
+import type { Container } from 'pixi.js';
+export interface DraggableContainer extends Container {
+    __draggable?: boolean;
+    __dragging?: boolean;
+}
+export declare function enableDrag(container: DraggableContainer): void;
+export declare function disableDrag(container: DraggableContainer): void;
+export declare function isDraggable(container: DraggableContainer): boolean;
+export declare function isDragging(container: DraggableContainer): boolean;
+//# sourceMappingURL=DraggableController.d.ts.map

package/dist/devtools/DraggableController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DraggableController.d.ts","sourceRoot":"","sources":["../../devtools/DraggableController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAyB,MAAM,SAAS,CAAC;AAEhE,MAAM,WAAW,kBAAmB,SAAQ,SAAS;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAqDD,wBAAgB,UAAU,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAW9D;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAoB/D;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAElE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAEjE"}

package/dist/devtools/ResizableController.d.ts

@@ -0,0 +1,19 @@
+import type { Container } from 'pixi.js';
+export interface ResizableContainer extends Container {
+    __resizable?: boolean;
+    __resizing?: boolean;
+    __resizeOverlay?: ResizeOverlay;
+}
+type HandlePosition = 'nw' | 'n' | 'ne' | 'e' | 'se' | 's' | 'sw' | 'w';
+interface ResizeOverlay {
+    container: HTMLDivElement;
+    handles: Map<HandlePosition, HTMLDivElement>;
+    border: HTMLDivElement;
+    animationId: number | null;
+}
+export declare function enableResize(container: ResizableContainer): void;
+export declare function disableResize(container: ResizableContainer): void;
+export declare function isResizable(container: ResizableContainer): boolean;
+export declare function isResizing(container: ResizableContainer): boolean;
+export {};
+//# sourceMappingURL=ResizableController.d.ts.map

package/dist/devtools/ResizableController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ResizableController.d.ts","sourceRoot":"","sources":["../../devtools/ResizableController.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAEzC,MAAM,WAAW,kBAAmB,SAAQ,SAAS;IACnD,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,eAAe,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,KAAK,cAAc,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,GAAG,IAAI,GAAG,GAAG,CAAC;AAaxE,UAAU,aAAa;IACrB,SAAS,EAAE,cAAc,CAAC;IAC1B,OAAO,EAAE,GAAG,CAAC,cAAc,EAAE,cAAc,CAAC,CAAC;IAC7C,MAAM,EAAE,cAAc,CAAC;IACvB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B;AA6RD,wBAAgB,YAAY,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CAchE;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,kBAAkB,GAAG,IAAI,CASjE;AAED,wBAAgB,WAAW,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAElE;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,kBAAkB,GAAG,OAAO,CAEjE"}

package/dist/devtools/index.d.ts

@@ -0,0 +1,7 @@
+export * from './treePlugin';
+export * from './overlayPlugin';
+export * from './DraggableController';
+export * from './ResizableController';
+export * from './spriteTextPropertiesPlugin';
+export * from './spinePropertiesPlugin';
+//# sourceMappingURL=index.d.ts.map

package/dist/devtools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../devtools/index.ts"],"names":[],"mappings":"AAKA,cAAc,cAAc,CAAC;AAC7B,cAAc,iBAAiB,CAAC;AAChC,cAAc,uBAAuB,CAAC;AACtC,cAAc,uBAAuB,CAAC;AACtC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,yBAAyB,CAAC"}