handler-playable-sdk 0.3.1 → 0.3.2

package/dist/pixi/index.d.ts

@@ -1,4 +1,6 @@
+import * as PixiJS from 'pixi.js';
 import { Application, Container, Texture, Sprite, Text, Graphics, Point } from 'pixi.js';
+import { O as ObjectCentricConfig$1 } from '../loader-object-centric-C1QteFfG.js';
 
 /**
  * Handler SDK - PixiJS Base Context
@@ -255,104 +257,12 @@ declare function registerFont(fontId: string, definition: FontDefinition): void;
 declare function getRegisteredFontIds(): string[];
 
 /**
- * Handler SDK - Type Definitions for PixiJS Integration
+ * Object-centric configuration
  *
- * DO NOT EDIT - Handler SDK Core
- */
-/**
- * Object configuration from JSON files
+ * Single source of truth is the config loader type.
+ * Pixi systems/engine should never diverge from that shape.
  */
-interface ObjectConfig {
-    object_config?: string;
-    transform?: {
-        position?: {
-            x: number;
-            y: number;
-        };
-        scale?: number;
-        rotation?: number;
-        offset?: {
-            x?: number;
-            y?: number;
-        };
-    };
-    render?: {
-        z_index?: number;
-        alpha?: number;
-        visible?: boolean;
-        tint?: number | string | null;
-        background_color?: string;
-        background_alpha?: number;
-        border_color?: string;
-        anchor?: {
-            x: number;
-            y: number;
-        };
-    };
-    gameplay?: {
-        rules?: Record<string, unknown>;
-        tuning?: Record<string, unknown>;
-    };
-    ui?: {
-        text?: string;
-        font?: string;
-        fontSize?: number;
-        letterSpacing?: number;
-        align?: string;
-    };
-    effects?: Record<string, unknown>;
-    audio?: Record<string, unknown>;
-    physics?: Record<string, unknown>;
-    interaction?: Record<string, unknown>;
-    identity?: Record<string, unknown>;
-    visibility?: Record<string, unknown>;
-}
-/**
- * Engine configuration
- */
-interface EngineConfig {
-    assets?: Record<string, string>;
-    runtime?: {
-        ui?: Record<string, unknown>;
-        theme?: Record<string, unknown>;
-        ui_styles?: Record<string, unknown>;
-        timeline?: Record<string, number>;
-    };
-}
-/**
- * Theme configuration
- */
-interface ThemeConfig {
-    background_color?: string;
-    text_color?: string;
-    square_color?: string;
-    cta_background?: string;
-    cta_text?: string;
-    melt_color?: string;
-    danger_color?: string;
-    brush_color?: string;
-    success_color?: string;
-}
-/**
- * Gameplay configuration
- */
-interface GameplayConfig {
-    [key: string]: unknown;
-}
-/**
- * Object-centric configuration
- * This is the main config type that students work with
- */
-interface ObjectCentricConfig {
-    /** Map of object instance IDs to their configurations */
-    objects: Map<string, ObjectConfig>;
-    /** Engine configuration (assets, runtime settings) */
-    engine: EngineConfig;
-    /** Theme configuration */
-    theme: ThemeConfig;
-    /** Gameplay configuration */
-    gameplay: GameplayConfig;
-}
+type ObjectCentricConfig = ObjectCentricConfig$1;
 
 /**
  * Handler SDK - EndGame UI Panel
@@ -387,6 +297,69 @@ declare function animatePanelEntrance(elements: EndGamePanelElements, config: Ob
  */
 declare function animateHandClick(hand: Sprite, ctaButton: Graphics, config: ObjectCentricConfig, onClick: () => void): void;
 
+interface SplashScreenConfig {
+    enabled: boolean;
+    show_on_start: boolean;
+    background_color: string;
+    background_alpha: number;
+    title: string;
+    subtitle: string;
+    button_label: string;
+    title_color: string;
+    subtitle_color: string;
+    button_bg: string;
+    button_text: string;
+    button_width: number;
+    button_height: number;
+    button_radius: number;
+    loading_blur: boolean;
+    loading_blur_strength: number;
+    loading_overlay_alpha: number;
+    font_family: string;
+    title_size: number;
+    subtitle_size: number;
+    loading_text: string;
+    loading_text_scale: number;
+}
+declare class SplashScreen {
+    private app;
+    private stage;
+    private activeConfig;
+    private splashConfig;
+    private splashEnabled;
+    private loadingBlurEnabled;
+    private loadingBlurStrength;
+    private loadingOverlayAlpha;
+    private splashLayer;
+    private splashBg;
+    private splashTitle;
+    private splashSubtitle;
+    private splashButton;
+    private splashButtonText;
+    private loadingLayer;
+    private loadingBg;
+    private loadingText;
+    private loadingTime;
+    private tickLoadingHandler;
+    constructor(app: Application, stage: Container, activeConfig: ObjectCentricConfig);
+    private resolveLoadingTextStyle;
+    syncConfig(next?: any): void;
+    updateLayout(width: number, height: number): void;
+    private updateSplashLayout;
+    private updateLoadingLayout;
+    show(): void;
+    hide(): void;
+    startLoadingAnimation(): void;
+    stopLoadingAnimation(): void;
+    destroyLoadingLayer(): void;
+    applyLoadingBlur(background: Sprite | Graphics): any[] | null;
+    removeLoadingBlur(background: Sprite | Graphics, prevFilters: any[] | null): void;
+    setupWindowGlobals(): void;
+    getSplashButton(): Graphics;
+    shouldShowOnStart(): boolean;
+    destroy(): void;
+}
+
 /**
  * Handler SDK - Tutorial UI Components
  *
@@ -562,4 +535,322 @@ declare class ObjectFactory {
     private static applyTransform;
 }
 
-export { AssetCache, type AssetDefinition, AssetLoader, type EndGamePanelElements, GameObject, GameObjectManager, type ObjectCentricConfig, ObjectFactory, type PixiBaseContext, type PixiTheme, Renderer, Transform, animateHandClick, animatePanelEntrance, createEndGamePanel, createHandTutorial, createPixiBase, createTutorialLabel, getRegisteredFontIds, playLottieOverlay, registerFont, registerType, resolveFont, resolveFontWeight, setLottieInstance, updateHandAnimation };
+/**
+ * Base context provided to all systems
+ */
+interface SystemContext {
+    app: Application;
+    stage: Container;
+    config: ObjectCentricConfig$1;
+    gameObjectManager: GameObjectManager;
+    destinationUrl: string;
+    root: HTMLElement;
+    engine: GameEngine;
+}
+/**
+ * Base class for all game systems
+ */
+declare abstract class BaseSystem {
+    protected context: SystemContext;
+    /**
+     * Internal initialization by GameEngine
+     */
+    setContext(context: SystemContext): void;
+    /**
+     * Called once during engine initialization
+     */
+    init?(): void | Promise<void>;
+    /**
+     * Called after all systems are initialized
+     */
+    onStart?(): void | Promise<void>;
+    /**
+     * Called every frame
+     * @param deltaTime normalized time since last frame
+     * @param totalTime total time elapsed since start
+     */
+    update?(deltaTime: number, totalTime: number): void;
+    /**
+     * Called when the screen is resized
+     */
+    onResize?(width: number, height: number): void;
+    /**
+     * Called when config changes (hot-reload)
+     */
+    onConfigUpdate?(newConfig: ObjectCentricConfig$1): void;
+    /**
+     * Cleanup system
+     */
+    onDestroy?(): void;
+}
+
+declare class GameEngine {
+    private app;
+    private stage;
+    private gameObjectManager;
+    private systems;
+    private totalTime;
+    private config;
+    private destinationUrl;
+    private root;
+    constructor(root: HTMLElement, config: ObjectCentricConfig$1, destinationUrl: string);
+    /**
+     * Initialize PIXI and systems
+     */
+    init(theme: any): Promise<{
+        app: Application;
+        gameObjectManager: GameObjectManager;
+    }>;
+    /**
+     * Register systems before starting
+     */
+    registerSystems(systems: BaseSystem[]): void;
+    /**
+     * Start the game loop
+     */
+    start(): Promise<void>;
+    /**
+     * Central update loop
+     */
+    private update;
+    /**
+     * Propagate resize
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Handle hot-reload
+     */
+    updateConfig(newConfig: ObjectCentricConfig$1): void;
+    /**
+     * Destroy engine and systems
+     */
+    destroy(): void;
+    getApp(): Application;
+    getGameObjectManager(): GameObjectManager;
+    getTotalTime(): number;
+    /**
+     * Find a registered system by its class
+     */
+    getSystem<T extends BaseSystem>(type: new (...args: any[]) => T): T;
+}
+
+/**
+ * Runtime Object Registry
+ *
+ * Passive config registry that reads object configs from loaded ObjectCentricConfig.
+ * Hot-reload friendly - config passed at runtime.
+ *
+ * DO NOT EDIT - Base Layer
+ */
+
+/**
+ * Runtime object registry - provides access to object configs
+ */
+declare class RuntimeObjectRegistry {
+    private config;
+    /**
+     * Initialize registry with config
+     */
+    init(config: ObjectCentricConfig$1): void;
+    /**
+     * Get object config by instance ID
+     */
+    get(instanceId: string): any;
+    /**
+     * Get all object instance IDs
+     */
+    getAllIds(): string[];
+    /**
+     * Check if object exists
+     */
+    has(instanceId: string): boolean;
+}
+
+/**
+ * Base Layer - PixiJS Instance
+ *
+ * Provides isolated pixi.js instance for base layer.
+ * Prevents conflicts with student layer's pixi instance.
+ *
+ * DO NOT EDIT - Base Layer
+ */
+
+declare const basePixi: typeof PixiJS;
+
+/**
+ * Assets Proxy - Student-Facing API
+ *
+ * Provides simple API: Assets.ready() then Assets.xxx
+ *
+ * RULES:
+ * - Singleton instances by default
+ * - Assets.ready() resolves when all objects preloaded and Assets.xxx accesses are sync/safe
+ * - resetScene() clears instance cache only (NOT asset cache)
+ * - reloadObject(id) explicitly recreates single object
+ * - Separate asset cache (global) and instance cache (scene-scoped, strong references)
+ *
+ * DO NOT EDIT - Base Layer
+ */
+
+/**
+ * Assets core implementation
+ */
+declare class AssetsCore {
+    private registry;
+    private instanceCache;
+    private readyPromise;
+    private app;
+    constructor();
+    /**
+     * Initialize with config and app
+     */
+    init(config: ObjectCentricConfig$1, app: any): void;
+    /**
+     * Update config (for hot-reload)
+     * Re-initializes registry and clears instance cache
+     */
+    updateConfig(config: ObjectCentricConfig$1): void;
+    /**
+     * Preload all objects
+     * RULE: Resolves when all objects are preloaded and Assets.xxx accesses are sync/safe
+     * RULE: Idempotent - subsequent calls only reload changed objects
+     */
+    ready(): Promise<void>;
+    /**
+     * Reset scene - clears instance cache but NOT asset cache
+     * RULE: Strong references, cleared ONLY by resetScene()
+     */
+    resetScene(): void;
+    /**
+     * Reload a single object explicitly
+     */
+    reloadObject(id: string): Promise<void>;
+    /**
+     * Get object instance by ID
+     */
+    get(id: string): any;
+}
+declare const Assets: AssetsCore & {
+    [key: string]: any;
+};
+/**
+ * Initialize Assets with config and app
+ * Must be called before Assets.ready()
+ */
+declare function initAssets(config: ObjectCentricConfig$1, app: any): void;
+
+declare class AssetSystem extends BaseSystem {
+    private splashScreen;
+    init(): Promise<void>;
+    onStart(): Promise<void>;
+    onConfigUpdate(): void;
+}
+
+declare let globalResponsiveMultipliers: {
+    scale: number;
+    position: number;
+};
+declare function clearResponsiveElements(): void;
+declare function updateScreenState(width: number, height: number): void;
+type AnchorSpec = string | {
+    x: number;
+    y: number;
+} | [number, number] | null | undefined;
+type RatioSpec = {
+    x: number;
+    y: number;
+} | [number, number] | null | undefined;
+type ScreenInset = {
+    top?: number;
+    right?: number;
+    bottom?: number;
+    left?: number;
+};
+declare function resolveAnchorVec2(anchor: AnchorSpec, fallback?: {
+    x: number;
+    y: number;
+}): {
+    x: number;
+    y: number;
+};
+declare function resolveScreenAnchorPoint(screenWidth: number, screenHeight: number, anchor: AnchorSpec, opts?: {
+    inset?: ScreenInset;
+    padding?: {
+        x: number;
+        y: number;
+    };
+}): {
+    x: number;
+    y: number;
+};
+declare function resolveScreenRatioPoint(screenWidth: number, screenHeight: number, ratio: RatioSpec, opts?: {
+    inset?: ScreenInset;
+    padding?: {
+        x: number;
+        y: number;
+    };
+}): {
+    x: number;
+    y: number;
+};
+declare function applyScreenAnchor(element: any, screenWidth: number, screenHeight: number, options?: {
+    anchor?: AnchorSpec;
+    positionRatio?: RatioSpec;
+    offset?: {
+        x: number;
+        y: number;
+    };
+    inset?: ScreenInset;
+    screenPadding?: {
+        x: number;
+        y: number;
+    };
+    renderAnchor?: {
+        x: number;
+        y: number;
+    };
+    scale?: number;
+    scaleMultiplier?: number;
+}): void;
+/**
+ * Layout Manager
+ * Strategy: ADAPTIVE ANCHOR
+ * - Tall Screens: Show full rope (Anchor Top).
+ * - Short Screens: Prioritize Character (Anchor Character Position).
+ */
+interface LayoutScreen {
+    width: number;
+    height: number;
+}
+interface LayoutElements {
+    mainContainer: any;
+    label: any;
+    background: any;
+    backgroundTexture: any;
+    app: any;
+}
+declare function layout(elements: LayoutElements, config: ObjectCentricConfig, time: number, screen: LayoutScreen, gameObjectManager?: any, options?: {
+    skipInstanceIds?: string[];
+    enableDebugLogs?: boolean;
+    skipMainContainerTransform?: boolean;
+}): void;
+
+interface InitSequenceStates<State = unknown> {
+    showHook: State;
+    waitInput: State;
+}
+interface InitSequenceOptions<State = unknown> {
+    setState: (state: State) => void;
+    updateLabelAlpha: (alpha: number) => void;
+    updateHandAlpha: (alpha: number) => void;
+    config: ObjectCentricConfig;
+    states: InitSequenceStates<State>;
+}
+/**
+ * Shared, config-driven init sequence.
+ *
+ * Keeps the SDK generic by letting the caller pass game-specific state values.
+ */
+declare function runInitSequence<State = unknown>(options: InitSequenceOptions<State>): void;
+
+export { AssetCache, type AssetDefinition, AssetLoader, AssetSystem, Assets, BaseSystem, type EndGamePanelElements, GameEngine, GameObject, GameObjectManager, type ObjectCentricConfig, ObjectFactory, type PixiBaseContext, type PixiTheme, Renderer, RuntimeObjectRegistry, SplashScreen, type SplashScreenConfig, type SystemContext, Transform, animateHandClick, animatePanelEntrance, applyScreenAnchor, basePixi, clearResponsiveElements, createEndGamePanel, createHandTutorial, createPixiBase, createTutorialLabel, getRegisteredFontIds, globalResponsiveMultipliers, initAssets, layout, playLottieOverlay, registerFont, registerType, resolveAnchorVec2, resolveFont, resolveFontWeight, resolveScreenAnchorPoint, resolveScreenRatioPoint, runInitSequence, setLottieInstance, updateHandAnimation, updateScreenState };