handler-playable-sdk 0.3.2 → 0.3.4

package/dist/pixi/{index.d.mts → index.d.cts}

@@ -1,6 +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.mjs';
+import { Application, Container, Sprite, Texture, Text } from 'pixi.js';
+import { O as ObjectCentricConfig$1 } from '../loader-object-centric-Ce6MVkQw.cjs';
 
 /**
  * Handler SDK - PixiJS Base Context
@@ -110,7 +110,7 @@ declare class Renderer {
         visible?: boolean;
         tint?: number | null;
     }): void;
-    syncToPixi(pixiObject: Container | any): void;
+    syncToPixi(pixiObject: Container | any, instanceId?: string): void;
 }
 /**
  * Base GameObject class - Unity-style entity with components
@@ -129,11 +129,21 @@ declare class GameObject {
     transform: Transform;
     renderer: Renderer;
     private _config;
+    private _tickerCleanup;
+    onRebuildRequired: ((gameObject: GameObject, nextConfig: any) => void) | null;
     constructor(instanceId: string, objectConfig: string, pixiObject: Container | any, config: any);
     /**
      * Sync all components to PixiJS object
      */
     sync(): void;
+    /**
+     * Sync Text-specific properties (ui.text, fontSize, color, etc.)
+     */
+    private syncTextProperties;
+    /**
+     * Cleanup GameObject and its tickers
+     */
+    destroy(): void;
     /**
      * Update config and sync (for hot-reload)
      */
@@ -146,6 +156,22 @@ declare class GameObject {
      * Apply optional non-uniform scale from effects (if provided)
      */
     private applyEffectsScale;
+    /**
+     * Apply visual effects (shadow, glow, blur, stroke, distortion)
+     *
+     * NOTE: Full-quality effects (drop shadow with offset, crisp outline stroke, distortion)
+     * require the optional `pixi-filters` package. Current implementation uses built-in
+     * PixiJS filters with some visual limitations.
+     */
+    private applyEffects;
+    /**
+     * Apply intro animation
+     */
+    private applyIntro;
+    /**
+     * Apply motion and animations (pulse, swing)
+     */
+    private applyMotion;
     /**
      * Get component value
      */
@@ -190,6 +216,7 @@ declare class GameObject {
 declare class GameObjectManager {
     private objects;
     private config;
+    onObjectRebuildRequired: ((instanceId: string, nextConfig: any) => Promise<GameObject>) | null;
     constructor(config: any);
     /**
      * Create a GameObject from config
@@ -264,139 +291,6 @@ declare function getRegisteredFontIds(): string[];
  */
 type ObjectCentricConfig = ObjectCentricConfig$1;
 
-/**
- * Handler SDK - EndGame UI Panel
- *
- * Success screen with logo, text, CTA button, and tutorial hand.
- * Fully configurable via UI config system.
- *
- * DO NOT EDIT - Handler SDK Core
- */
-
-interface EndGamePanelElements {
-    panel: Container;
-    logo: Sprite;
-    title: Text;
-    subtitle: Text;
-    footer: Text;
-    ctaButton: Graphics;
-    ctaText: Text;
-    ctaHint: Text;
-    hand: Sprite;
-}
-/**
- * Create EndGame success panel with all UI elements
- */
-declare function createEndGamePanel(config: ObjectCentricConfig, handTexture: Texture | null, logoTexture: Texture | null): EndGamePanelElements;
-/**
- * Animate panel entrance with staggered animations
- */
-declare function animatePanelEntrance(elements: EndGamePanelElements, config: ObjectCentricConfig, onComplete?: () => void): void;
-/**
- * Animate tutorial hand clicking CTA button
- */
-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
- *
- * Tutorial hand and label components for game tutorials.
- * Config requirement: All UI properties from object-centric config.
- *
- * DO NOT EDIT - Handler SDK Core
- */
-
-/**
- * Create hand tutorial sprite
- * Hand properties from object-centric config (hand_tutorial_1)
- *
- * @param handTexture - Texture for the hand sprite
- * @param config - Object-centric configuration
- * @param baseCharacterPos - Base position of the character for animation reference
- */
-declare function createHandTutorial(handTexture: Texture, config: ObjectCentricConfig, baseCharacterPos: Point): Sprite;
-/**
- * Create tutorial label text
- * Uses ui.tutorial config object with UI component schema
- *
- * @param config - Object-centric configuration
- */
-declare function createTutorialLabel(config: ObjectCentricConfig): Text;
-/**
- * Update hand animation
- * Animation parameters from object-centric config (hand_tutorial_1)
- *
- * @param hand - The hand sprite
- * @param baseCharacterPos - Base character position
- * @param time - Current time for animation
- * @param isDragging - Whether the user is currently dragging
- * @param config - Object-centric configuration
- */
-declare function updateHandAnimation(hand: Sprite, baseCharacterPos: Point, time: number, isDragging: boolean, config: ObjectCentricConfig): void;
-
 /**
  * Handler SDK - Lottie Overlay Helper
  *
@@ -452,7 +346,7 @@ type BuildSettings = {
 };
 declare global {
     interface Window {
-        INLINE_ASSETS?: Record<string, string>;
+        INLINE_ASSETS?: Record<string, any>;
         __BUILD_SETTINGS__?: BuildSettings;
     }
 }
@@ -460,10 +354,10 @@ type AssetDefinition = {
     type: string;
     path: string;
 };
-type TypeLoader = (path: string, inlineData: string | undefined, objectId: string, app: any) => Promise<any>;
+type TypeLoader = (path: string, inlineData: any | undefined, objectId: string, app: any) => Promise<any>;
 declare function registerType(type: string, loader: TypeLoader): void;
 declare class AssetLoader {
-    static load(objectId: string, assetDef: AssetDefinition, app: any): Promise<any>;
+    static load(objectId: string, assetDef: AssetDefinition, app: any, configId?: string): Promise<any>;
     private static loadImage;
     private static loadJSON;
     private static handleFailure;
@@ -677,6 +571,125 @@ declare class RuntimeObjectRegistry {
 
 declare const basePixi: typeof PixiJS;
 
+/**
+ * Handler SDK - Asset Texture Registry
+ *
+ * Clean texture-only registry for object-centric asset loading.
+ *
+ * RULES:
+ * - Stores ONLY Texture instances, not display objects
+ * - Keys are instance IDs from scene (e.g., 'key_1', 'background_1')
+ * - Used by spawnScene and game code to create sprites
+ * - Library panel updates textures here, onConfigUpdate propagates
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+
+/**
+ * Asset Texture Registry Implementation
+ */
+declare class AssetTextureRegistry {
+    private textures;
+    private readyPromise;
+    private config;
+    private app;
+    /**
+     * Initialize with config and app instance
+     * CRITICAL: Clears previous state for Preview Restart support
+     */
+    init(config: ObjectCentricConfig, app: any): void;
+    /**
+     * Preload all image textures from config
+     * RULE: Resolves when all textures are loaded and ready for sprite creation
+     */
+    ready(): Promise<void>;
+    /**
+     * Get texture by instance ID
+     */
+    get(instanceId: string): Texture | undefined;
+    /**
+     * Set texture for instance ID (used by library panel)
+     */
+    set(instanceId: string, texture: Texture): void;
+    /**
+     * Clear all textures (for scene reset)
+     */
+    clear(): void;
+    /**
+     * Get all loaded texture IDs
+     */
+    getAllIds(): string[];
+}
+/**
+ * AssetTextures - Texture Registry
+ *
+ * Access textures by instance ID:
+ * @example
+ * // After AssetTextures.ready():
+ * const texture = AssetTextures.character_1;
+ * const sprite = new Sprite(texture);
+ *
+ * // Or explicit get:
+ * const texture = AssetTextures.get('character_1');
+ */
+declare const AssetTextures: AssetTextureRegistry & {
+    [key: string]: Texture;
+};
+/**
+ * Initialize AssetTextures with config and app
+ * Must be called before AssetTextures.ready()
+ */
+declare function initAssetTextures(config: ObjectCentricConfig, app: any): void;
+
+/**
+ * Handler SDK - Scene Spawning Utility
+ *
+ * Automatically spawns PixiJS objects from ObjectCentricConfig.
+ * Uses AssetTextures for texture data, creates sprites/text objects.
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+
+type SpawnOptions = {
+    stage: Container;
+    mainContainer: Container;
+    activeConfig: ObjectCentricConfig;
+    gameObjectManager: any;
+    /**
+     * Optional: spawn only specific instance IDs
+     */
+    allowList?: Set<string>;
+    /**
+     * Optional: skip some instance IDs (for special handling)
+     */
+    denyList?: Set<string>;
+};
+type SpawnResult = {
+    objects: Record<string, any>;
+    sprites: Record<string, Sprite>;
+    texts: Record<string, Text>;
+};
+/**
+ * Spawn scene objects from config
+ *
+ * Uses AssetTextures to create sprites from texture data.
+ * Applies all transform and render properties from config.
+ *
+ * @param opts - Spawn options
+ * @returns Map of spawned objects organized by type
+ *
+ * @example
+ * // After AssetTextures.ready():
+ * const { objects, sprites, texts } = spawnSceneFromConfig({
+ *   stage,
+ *   mainContainer,
+ *   activeConfig,
+ *   gameObjectManager,
+ *   denyList: new Set(['background_1', 'label_1'])
+ * });
+ */
+declare function spawnSceneFromConfig(opts: SpawnOptions): SpawnResult;
+
 /**
  * Assets Proxy - Student-Facing API
  *
@@ -740,7 +753,6 @@ declare const Assets: AssetsCore & {
 declare function initAssets(config: ObjectCentricConfig$1, app: any): void;
 
 declare class AssetSystem extends BaseSystem {
-    private splashScreen;
     init(): Promise<void>;
     onStart(): Promise<void>;
     onConfigUpdate(): void;
@@ -814,9 +826,9 @@ declare function applyScreenAnchor(element: any, screenWidth: number, screenHeig
 }): void;
 /**
  * Layout Manager
- * Strategy: ADAPTIVE ANCHOR
- * - Tall Screens: Show full rope (Anchor Top).
- * - Short Screens: Prioritize Character (Anchor Character Position).
+ * Generic layout system for all games.
+ * Positions objects based on their config transform.anchor and transform.position_ratio.
+ * Game-specific positioning (like rope physics) should be handled in game systems.
  */
 interface LayoutScreen {
     width: number;
@@ -853,4 +865,4 @@ interface InitSequenceOptions<State = unknown> {
  */
 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 };
+export { AssetCache, type AssetDefinition, AssetLoader, AssetSystem, AssetTextures, Assets, BaseSystem, GameEngine, GameObject, GameObjectManager, type ObjectCentricConfig, ObjectFactory, type PixiBaseContext, type PixiTheme, Renderer, RuntimeObjectRegistry, type SpawnOptions, type SpawnResult, type SystemContext, Transform, applyScreenAnchor, basePixi, clearResponsiveElements, createPixiBase, getRegisteredFontIds, globalResponsiveMultipliers, initAssetTextures, initAssets, layout, playLottieOverlay, registerFont, registerType, resolveAnchorVec2, resolveFont, resolveFontWeight, resolveScreenAnchorPoint, resolveScreenRatioPoint, runInitSequence, setLottieInstance, spawnSceneFromConfig, updateScreenState };