handler-playable-sdk 0.1.0 → 0.1.2

package/dist/three/index.d.mts

@@ -0,0 +1,493 @@
+import * as THREE from 'three';
+
+/**
+ * Handler SDK - Three.js Base Context
+ *
+ * Creates the base Three.js scene with Handler SDK lifecycle integration.
+ * Handles resize, pause/resume, and provides the overlay for UI elements.
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+
+/**
+ * Theme configuration for Three.js base
+ */
+type ThreeTheme = {
+    background?: string;
+    text?: string;
+    text_muted?: string;
+    primary?: string;
+    cta_text?: string;
+    surface_shadow?: string;
+};
+/**
+ * Context returned by createThreeBase
+ */
+type ThreeBaseContext = {
+    scene: THREE.Scene;
+    camera: THREE.OrthographicCamera;
+    renderer: THREE.WebGLRenderer;
+    overlay: HTMLElement;
+    applySize: (size?: {
+        width?: number;
+        height?: number;
+    }) => void;
+};
+/**
+ * Create the base Three.js context with Handler SDK integration
+ *
+ * @param root - The root HTML element to render into (from Handler.getRoot())
+ * @param theme - Optional theme configuration
+ * @returns Three.js scene context with overlay
+ *
+ * @example
+ * ```typescript
+ * const root = Handler.getRoot();
+ * const { scene, camera, renderer, overlay } = await createThreeBase(root, {
+ *   background: '#160a17',
+ *   text: '#fef4dd',
+ *   primary: '#ffb43b'
+ * });
+ * ```
+ */
+declare function createThreeBase(root: HTMLElement, theme?: ThreeTheme): Promise<ThreeBaseContext>;
+
+/**
+ * Handler SDK - GameObject System for Three.js
+ *
+ * Unity-style component-based architecture for Three.js objects.
+ * Automatically syncs config values to Three.js objects and enables hot-reload.
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+
+/**
+ * Transform Component - Position, scale, rotation
+ */
+declare class Transform {
+    position: {
+        x: number;
+        y: number;
+    };
+    scale: number;
+    rotation: number;
+    constructor(config?: {
+        position?: {
+            x: number;
+            y: number;
+        };
+        scale?: number;
+        rotation?: number;
+    });
+    update(config: {
+        position?: {
+            x: number;
+            y: number;
+        };
+        scale?: number;
+        rotation?: number;
+    }): void;
+    syncToThree(threeObject: THREE.Object3D): void;
+}
+/**
+ * Renderer Component - Visual properties
+ */
+declare class Renderer {
+    z_index: number;
+    alpha: number;
+    visible: boolean;
+    tint: number | null;
+    constructor(config?: {
+        z_index?: number;
+        alpha?: number;
+        visible?: boolean;
+        tint?: number | null;
+    });
+    update(config: {
+        z_index?: number;
+        alpha?: number;
+        visible?: boolean;
+        tint?: number | null;
+    }): void;
+    syncToThree(threeObject: THREE.Object3D): void;
+}
+/**
+ * Base GameObject class - Unity-style entity with components
+ *
+ * @example
+ * ```typescript
+ * const characterGO = gameObjectManager.create('character_1', characterMesh);
+ * characterGO.setPosition(100, 200);
+ * characterGO.setAlpha(0.8);
+ * ```
+ */
+declare class GameObject {
+    instanceId: string;
+    objectConfig: string;
+    threeObject: THREE.Object3D;
+    transform: Transform;
+    renderer: Renderer;
+    private _config;
+    constructor(instanceId: string, objectConfig: string, threeObject: THREE.Object3D, config: any);
+    /**
+     * Sync all components to Three.js object
+     */
+    sync(): void;
+    /**
+     * Update config and sync (for hot-reload)
+     */
+    updateConfig(newConfig: any): void;
+    /**
+     * Get component value
+     */
+    getComponent<T>(componentName: string): T | undefined;
+    /**
+     * Get transform position
+     */
+    getPosition(): {
+        x: number;
+        y: number;
+    };
+    /**
+     * Set transform position
+     */
+    setPosition(x: number, y: number): void;
+    /**
+     * Get renderer alpha
+     */
+    getAlpha(): number;
+    /**
+     * Set renderer alpha
+     */
+    setAlpha(alpha: number): void;
+    /**
+     * Get renderer visible
+     */
+    getVisible(): boolean;
+    /**
+     * Set renderer visible
+     */
+    setVisible(visible: boolean): void;
+}
+/**
+ * GameObject Manager - Manages all game objects and enables hot-reload
+ *
+ * @example
+ * ```typescript
+ * const gameObjectManager = new GameObjectManager(config);
+ * const characterGO = gameObjectManager.create('character_1', characterMesh);
+ * ```
+ */
+declare class GameObjectManager {
+    private objects;
+    private config;
+    constructor(config: any);
+    /**
+     * Create a GameObject from config
+     */
+    create(instanceId: string, threeObject: THREE.Object3D): GameObject;
+    /**
+     * Get GameObject by instance ID
+     */
+    get(instanceId: string): GameObject | undefined;
+    /**
+     * Update config and sync all objects (for hot-reload)
+     */
+    updateConfig(newConfig: any): void;
+    /**
+     * Get all GameObjects
+     */
+    getAll(): GameObject[];
+    /**
+     * Remove GameObject
+     */
+    remove(instanceId: string): void;
+    /**
+     * Clear all GameObjects
+     */
+    clear(): void;
+}
+
+/**
+ * Handler SDK - Font Registry
+ *
+ * Maps font IDs to actual font families/paths.
+ * UI config references fonts by ID only (e.g., "brand.primary").
+ * This registry resolves IDs to actual font values.
+ *
+ * Font paths and platform differences are handled here, NOT in config.
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+type FontDefinition = {
+    family: string;
+    weight?: string | number;
+    style?: string;
+};
+/**
+ * Resolve font ID to font family string
+ * @param fontId Font ID from UI config (e.g., "brand.primary")
+ * @returns CSS font-family string
+ */
+declare function resolveFont(fontId: string): string;
+/**
+ * Resolve font ID to font weight
+ * @param fontId Font ID from UI config
+ * @returns Font weight (string or number)
+ */
+declare function resolveFontWeight(fontId: string): string | number;
+/**
+ * Register a new font (for engine initialization)
+ * @param fontId Font ID
+ * @param definition Font definition
+ */
+declare function registerFont(fontId: string, definition: FontDefinition): void;
+/**
+ * Get all registered font IDs
+ */
+declare function getRegisteredFontIds(): string[];
+
+/**
+ * Handler SDK - Type Definitions for Three.js Integration
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+/**
+ * Object configuration from JSON files
+ */
+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;
+    };
+    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;
+}
+
+/**
+ * Handler SDK - EndGame UI Panel for Three.js
+ *
+ * Success screen with logo, text, CTA button, and tutorial hand.
+ * Fully configurable via UI config system.
+ * Uses HTML overlay elements for UI, Three.js sprites for images.
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+
+declare function createHTMLElementWrapper(element: HTMLElement): {
+    element: HTMLElement;
+    alpha: number;
+    visible: boolean;
+    position: {
+        set(x: number, y: number): void;
+        readonly x: number;
+        readonly y: number;
+    };
+    scale: {
+        set(x: number, y?: number): void;
+        readonly x: number;
+    };
+};
+interface EndGamePanelElements {
+    panel: ReturnType<typeof createHTMLElementWrapper> & {
+        element: HTMLElement;
+    };
+    logo: THREE.Sprite;
+    title: ReturnType<typeof createHTMLElementWrapper> & {
+        element: HTMLElement;
+    };
+    subtitle: ReturnType<typeof createHTMLElementWrapper> & {
+        element: HTMLElement;
+    };
+    footer: ReturnType<typeof createHTMLElementWrapper> & {
+        element: HTMLElement;
+    };
+    ctaButton: ReturnType<typeof createHTMLElementWrapper> & {
+        element: HTMLElement;
+        addEventListener: HTMLElement['addEventListener'];
+    };
+    ctaText: ReturnType<typeof createHTMLElementWrapper> & {
+        element: HTMLElement;
+    };
+    ctaHint: ReturnType<typeof createHTMLElementWrapper> & {
+        element: HTMLElement;
+    };
+    hand: THREE.Sprite;
+}
+/**
+ * Create EndGame success panel with all UI elements
+ */
+declare function createEndGamePanel(config: ObjectCentricConfig, handTexture: THREE.Texture | null, logoTexture: THREE.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: THREE.Sprite, ctaButton: ReturnType<typeof createHTMLElementWrapper> & {
+    element: HTMLElement;
+}, config: ObjectCentricConfig, onClick: () => void): void;
+
+/**
+ * Handler SDK - Tutorial UI Components for Three.js
+ *
+ * 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 (Three.js 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: THREE.Texture | null, config: ObjectCentricConfig, baseCharacterPos: {
+    x: number;
+    y: number;
+}): THREE.Sprite;
+/**
+ * Create tutorial label text (HTML overlay)
+ * Uses ui.tutorial config object with UI component schema
+ *
+ * @param config - Object-centric configuration
+ */
+declare function createTutorialLabel(config: ObjectCentricConfig): HTMLElement;
+/**
+ * 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: THREE.Sprite, baseCharacterPos: {
+    x: number;
+    y: number;
+}, time: number, isDragging: boolean, config: ObjectCentricConfig): void;
+
+/**
+ * Handler SDK - Asset Loader Utilities for Three.js
+ *
+ * Asset loading and texture creation utilities for Three.js.
+ * Config requirement: All asset paths from config.assets, colors from config.theme.
+ *
+ * DO NOT EDIT - Handler SDK Core
+ */
+
+/**
+ * Load an asset with fallback placeholder
+ * Asset path comes from config.assets
+ *
+ * @param path - Asset path
+ * @param renderer - Three.js renderer instance (for context if needed)
+ * @param fallbackColor - Color for fallback placeholder
+ * @param isChar - Whether this is a character sprite (affects placeholder shape)
+ */
+declare function loadAsset(path: string, renderer: THREE.WebGLRenderer, fallbackColor?: number, isChar?: boolean): Promise<THREE.Texture | null>;
+/**
+ * Load character frames from sprite sheet
+ * Uses config.assets.character_sprite for path
+ * Character sheet dimensions come from config (cols: 3, rows: 2)
+ *
+ * @param path - Path to the sprite sheet
+ * @param renderer - Three.js renderer instance
+ * @param config - Object-centric configuration
+ */
+declare function loadCharacterFrames(path: string, renderer: THREE.WebGLRenderer, config: ObjectCentricConfig): Promise<THREE.Texture[]>;
+/**
+ * Create brush texture
+ * Uses config.theme.brush_color for color
+ * Brush size comes from config.gameplay.brush
+ *
+ * @param renderer - Three.js renderer instance
+ * @param config - Object-centric configuration
+ */
+declare function createBrushTexture(renderer: THREE.WebGLRenderer, config: ObjectCentricConfig): THREE.Texture;
+
+export { type EndGamePanelElements, GameObject, GameObjectManager, type ObjectCentricConfig, Renderer, type ThreeBaseContext, type ThreeTheme, Transform, animateHandClick, animatePanelEntrance, createBrushTexture, createEndGamePanel, createHandTutorial, createThreeBase, createTutorialLabel, getRegisteredFontIds, loadAsset, loadCharacterFrames, registerFont, resolveFont, resolveFontWeight, updateHandAnimation };