@thewhateverapp/tile-sdk 0.13.37 → 0.14.1

package/dist/scene/SceneContext.d.ts

@@ -0,0 +1,167 @@
+import { type MutableRefObject } from 'react';
+import type { SceneSpecV1, Entity, CameraConfig } from '@thewhateverapp/scene-sdk';
+import type { Engine, Body } from 'matter-js';
+/**
+ * Runtime entity state - mutable for performance
+ */
+export interface EntityState {
+    /** Entity definition from spec */
+    entity: Entity;
+    /** Current position (updated by physics/components) */
+    x: number;
+    y: number;
+    /** Current rotation in radians */
+    rotation: number;
+    /** Current scale */
+    scaleX: number;
+    scaleY: number;
+    /** Current velocity (for physics/movement) */
+    velocityX: number;
+    velocityY: number;
+    /** Whether entity is visible */
+    visible: boolean;
+    /** Current fill color (can be animated) */
+    fill?: string;
+    /** Current alpha (can be animated) */
+    alpha: number;
+    /** Matter.js body (if entity has physics) */
+    body?: Body;
+    /** Whether entity is destroyed */
+    destroyed: boolean;
+    /** Custom component state */
+    componentState: Record<string, unknown>;
+}
+/**
+ * Player-specific state for dash games
+ */
+export interface PlayerState {
+    /** Is player on ground */
+    grounded: boolean;
+    /** Is player dead */
+    dead: boolean;
+    /** Current jump count (for double jump) */
+    jumpCount: number;
+    /** Last checkpoint position */
+    checkpointX: number;
+    checkpointY: number;
+    /** Is touching a jump orb */
+    touchingOrb: string | null;
+    /** Gravity direction (1 = down, -1 = up) */
+    gravityDir: number;
+    /** Current speed multiplier */
+    speedMultiplier: number;
+    /** Death count */
+    deaths: number;
+    /** Level complete */
+    complete: boolean;
+}
+/**
+ * Camera state
+ */
+export interface CameraState {
+    x: number;
+    y: number;
+    zoom: number;
+    shakeIntensity: number;
+    shakeTimeRemaining: number;
+}
+/**
+ * Input state
+ */
+export interface InputState {
+    /** Is jump/action pressed (space, tap, or up arrow) */
+    jumpPressed: boolean;
+    /** Is currently touching (for hold detection) */
+    touching: boolean;
+    /** Keys currently held */
+    keys: Record<string, boolean>;
+}
+/**
+ * Timeline state
+ */
+export interface TimelineState {
+    /** Elapsed time in ms */
+    elapsedMs: number;
+    /** Current beat (based on BPM) */
+    currentBeat: number;
+    /** Index of next event to process */
+    nextEventIndex: number;
+    /** Active tweens */
+    activeTweens: ActiveTween[];
+}
+/**
+ * Active tween animation
+ */
+export interface ActiveTween {
+    targetId: string;
+    property: string;
+    startValue: number;
+    endValue: number;
+    startTime: number;
+    duration: number;
+    easing: string;
+}
+/**
+ * Scene context value - all scene runtime state
+ */
+export interface SceneContextValue {
+    /** Compiled scene spec */
+    spec: SceneSpecV1;
+    /** Entity states by ID */
+    entities: MutableRefObject<Map<string, EntityState>>;
+    /** Layer order (front to back) */
+    layers: string[];
+    /** Player state (for dash games) */
+    player: MutableRefObject<PlayerState>;
+    /** Camera state */
+    camera: MutableRefObject<CameraState>;
+    /** Input state */
+    input: MutableRefObject<InputState>;
+    /** Timeline state */
+    timeline: MutableRefObject<TimelineState>;
+    /** Matter.js engine */
+    engine: MutableRefObject<Engine | null>;
+    /** Emit an event to parent */
+    emitEvent: (event: string, data?: unknown) => void;
+    /** Get entity state by ID */
+    getEntity: (id: string) => EntityState | undefined;
+    /** Spawn an entity from prefab */
+    spawnEntity: (prefabId: string, x: number, y: number) => void;
+    /** Destroy an entity */
+    destroyEntity: (id: string) => void;
+    /** Respawn player at checkpoint */
+    respawnPlayer: () => void;
+    /** BPM for beat calculations */
+    bpm: number;
+    /** Start time for timeline */
+    startTime: number;
+}
+/**
+ * Scene context
+ */
+export declare const SceneContext: import("react").Context<SceneContextValue | null>;
+/**
+ * Hook to access scene context
+ */
+export declare function useScene(): SceneContextValue;
+/**
+ * Create initial entity state from entity definition
+ */
+export declare function createEntityState(entity: Entity): EntityState;
+/**
+ * Create initial player state
+ */
+export declare function createPlayerState(): PlayerState;
+/**
+ * Create initial camera state from config
+ */
+export declare function createCameraState(config?: CameraConfig): CameraState;
+/**
+ * Create initial input state
+ */
+export declare function createInputState(): InputState;
+/**
+ * Create initial timeline state
+ */
+export declare function createTimelineState(): TimelineState;
+//# sourceMappingURL=SceneContext.d.ts.map

package/dist/scene/SceneContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneContext.d.ts","sourceRoot":"","sources":["../../src/scene/SceneContext.tsx"],"names":[],"mappings":"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"}

package/dist/scene/SceneContext.js

@@ -0,0 +1,86 @@
+'use client';
+import { createContext, useContext } from 'react';
+/**
+ * Scene context
+ */
+export const SceneContext = createContext(null);
+/**
+ * Hook to access scene context
+ */
+export function useScene() {
+    const context = useContext(SceneContext);
+    if (!context) {
+        throw new Error('useScene must be used within a SceneRenderer');
+    }
+    return context;
+}
+/**
+ * Create initial entity state from entity definition
+ */
+export function createEntityState(entity) {
+    return {
+        entity,
+        x: entity.transform.x,
+        y: entity.transform.y,
+        rotation: (entity.transform.rotation ?? 0) * (Math.PI / 180), // Convert to radians
+        scaleX: entity.transform.scaleX ?? 1,
+        scaleY: entity.transform.scaleY ?? 1,
+        velocityX: 0,
+        velocityY: 0,
+        visible: entity.render?.visible ?? true,
+        fill: entity.render?.fill,
+        alpha: entity.render?.alpha ?? 1,
+        destroyed: false,
+        componentState: {},
+    };
+}
+/**
+ * Create initial player state
+ */
+export function createPlayerState() {
+    return {
+        grounded: false,
+        dead: false,
+        jumpCount: 0,
+        checkpointX: 0,
+        checkpointY: 0,
+        touchingOrb: null,
+        gravityDir: 1,
+        speedMultiplier: 1,
+        deaths: 0,
+        complete: false,
+    };
+}
+/**
+ * Create initial camera state from config
+ */
+export function createCameraState(config) {
+    return {
+        x: config?.initialX ?? 0,
+        y: config?.initialY ?? 0,
+        zoom: config?.zoom ?? 1,
+        shakeIntensity: 0,
+        shakeTimeRemaining: 0,
+    };
+}
+/**
+ * Create initial input state
+ */
+export function createInputState() {
+    return {
+        jumpPressed: false,
+        touching: false,
+        keys: {},
+    };
+}
+/**
+ * Create initial timeline state
+ */
+export function createTimelineState() {
+    return {
+        elapsedMs: 0,
+        currentBeat: 0,
+        nextEventIndex: 0,
+        activeTweens: [],
+    };
+}

package/dist/scene/SceneFromJson.d.ts

@@ -0,0 +1,27 @@
+import React from 'react';
+import { type SceneRendererProps } from './SceneRenderer';
+/**
+ * Props for SceneFromJson
+ */
+export interface SceneFromJsonProps extends Omit<SceneRendererProps, 'spec'> {
+    /** The scene spec JSON object (imported from scene.json) */
+    json: unknown;
+    /** Show validation errors in UI instead of throwing */
+    showErrors?: boolean;
+}
+/**
+ * SceneFromJson - Renders a scene from a JSON object with validation
+ *
+ * @example
+ * ```tsx
+ * // In your tile page:
+ * import { SceneFromJson } from '@thewhateverapp/tile-sdk/scene';
+ * import sceneJson from './scene.json';
+ *
+ * export default function TilePage() {
+ *   return <SceneFromJson json={sceneJson} />;
+ * }
+ * ```
+ */
+export declare function SceneFromJson({ json, showErrors, onEvent, ...props }: SceneFromJsonProps): React.JSX.Element;
+//# sourceMappingURL=SceneFromJson.d.ts.map

package/dist/scene/SceneFromJson.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneFromJson.d.ts","sourceRoot":"","sources":["../../src/scene/SceneFromJson.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,MAAM,OAAO,CAAC;AAG1B,OAAO,EAAiB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAEzE;;GAEG;AACH,MAAM,WAAW,kBAAmB,SAAQ,IAAI,CAAC,kBAAkB,EAAE,MAAM,CAAC;IAC1E,4DAA4D;IAC5D,IAAI,EAAE,OAAO,CAAC;IACd,uDAAuD;IACvD,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EACJ,UAAiB,EACjB,OAAO,EACP,GAAG,KAAK,EACT,EAAE,kBAAkB,qBAuEpB"}

package/dist/scene/SceneFromJson.js

@@ -0,0 +1,74 @@
+'use client';
+import React from 'react';
+import { validateScene } from '@thewhateverapp/scene-sdk';
+import { SceneRenderer } from './SceneRenderer';
+/**
+ * SceneFromJson - Renders a scene from a JSON object with validation
+ *
+ * @example
+ * ```tsx
+ * // In your tile page:
+ * import { SceneFromJson } from '@thewhateverapp/tile-sdk/scene';
+ * import sceneJson from './scene.json';
+ *
+ * export default function TilePage() {
+ *   return <SceneFromJson json={sceneJson} />;
+ * }
+ * ```
+ */
+export function SceneFromJson({ json, showErrors = true, onEvent, ...props }) {
+    // Validate the JSON
+    const validationResult = React.useMemo(() => {
+        try {
+            return validateScene(json);
+        }
+        catch (error) {
+            return {
+                valid: false,
+                errors: [{ path: 'root', message: String(error), code: 'PARSE_ERROR' }],
+                warnings: [],
+            };
+        }
+    }, [json]);
+    // Report validation errors to agent for correction
+    React.useEffect(() => {
+        if (!validationResult.valid) {
+            const errorMessage = `Scene Validation Errors:\n${validationResult.errors
+                .map((e) => `${e.path}: ${e.message}`)
+                .join('\n')}`;
+            // Report to agent via preview error reporting mechanism
+            if (typeof window !== 'undefined' && window.__PREVIEW_REPORT_ERROR__) {
+                window.__PREVIEW_REPORT_ERROR__(errorMessage, null, null);
+            }
+        }
+    }, [validationResult]);
+    // Show errors if validation failed
+    if (!validationResult.valid) {
+        if (showErrors) {
+            return (React.createElement("div", { style: {
+                    width: '100%',
+                    height: '100%',
+                    backgroundColor: '#1a0a0a',
+                    color: '#ff4444',
+                    padding: 16,
+                    fontFamily: 'monospace',
+                    fontSize: 12,
+                    overflow: 'auto',
+                } },
+                React.createElement("div", { style: { fontWeight: 'bold', marginBottom: 8 } }, "Scene Validation Errors:"),
+                validationResult.errors.map((error, i) => (React.createElement("div", { key: i, style: { marginBottom: 4 } },
+                    React.createElement("span", { style: { color: '#ff8888' } },
+                        error.path,
+                        ":"),
+                    " ",
+                    error.message)))));
+        }
+        // Throw if not showing errors
+        throw new Error(`Scene validation failed: ${validationResult.errors.map((e) => e.message).join(', ')}`);
+    }
+    // Show warnings in console
+    if (validationResult.warnings.length > 0) {
+        console.warn('Scene validation warnings:', validationResult.warnings);
+    }
+    return (React.createElement(SceneRenderer, { spec: json, onEvent: onEvent, ...props }));
+}

package/dist/scene/SceneRenderer.d.ts

@@ -0,0 +1,26 @@
+import React from 'react';
+import type { SceneSpecV1 } from '@thewhateverapp/scene-sdk';
+/**
+ * Props for SceneRenderer
+ */
+export interface SceneRendererProps {
+    /** Scene specification to render */
+    spec: SceneSpecV1;
+    /** Callback for scene events (player.death, level.complete, etc.) */
+    onEvent?: (event: string, data?: unknown) => void;
+    /** Whether the scene is paused */
+    paused?: boolean;
+    /** Width override (default: TILE_WIDTH) */
+    width?: number;
+    /** Height override (default: TILE_HEIGHT) */
+    height?: number;
+    /** Enable debug rendering */
+    debug?: boolean;
+}
+/**
+ * SceneRenderer - Renders a SceneSpecV1 with physics, components, and timeline
+ */
+export declare function SceneRenderer({ spec: inputSpec, onEvent, paused, width, height, debug, }: SceneRendererProps): React.JSX.Element;
+import { useScene } from './SceneContext';
+export { useScene };
+//# sourceMappingURL=SceneRenderer.d.ts.map

package/dist/scene/SceneRenderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SceneRenderer.d.ts","sourceRoot":"","sources":["../../src/scene/SceneRenderer.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAkD,MAAM,OAAO,CAAC;AACvE,OAAO,KAAK,EAAE,WAAW,EAAU,MAAM,2BAA2B,CAAC;AAqBrE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,oCAAoC;IACpC,IAAI,EAAE,WAAW,CAAC;IAClB,qEAAqE;IACrE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAClD,kCAAkC;IAClC,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,2CAA2C;IAC3C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6BAA6B;IAC7B,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,aAAa,CAAC,EAC5B,IAAI,EAAE,SAAS,EACf,OAAO,EACP,MAAc,EACd,KAAkB,EAClB,MAAoB,EACpB,KAAa,GACd,EAAE,kBAAkB,qBA8BpB;AAuOD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/scene/SceneRenderer.js

@@ -0,0 +1,201 @@
+'use client';
+import React, { useEffect, useRef, useCallback, useMemo } from 'react';
+import { compileScene } from '@thewhateverapp/scene-sdk';
+import { PixiGame, useGameLoop, Container } from '../pixi';
+import { SceneContext, createEntityState, createPlayerState, createCameraState, createInputState, createTimelineState, } from './SceneContext';
+import { EntityRenderer } from './entities/EntityRenderer';
+import { usePhysicsEngine } from './physics/PhysicsEngine';
+import { useInputManager } from './input/InputManager';
+import { useComponentRunner } from './components/ComponentRunner';
+import { useTimelineExecutor } from './timeline/TimelineExecutor';
+import { useCameraController } from './camera/CameraController';
+import { TILE_WIDTH, TILE_HEIGHT } from '../react/PixiGame';
+/**
+ * SceneRenderer - Renders a SceneSpecV1 with physics, components, and timeline
+ */
+export function SceneRenderer({ spec: inputSpec, onEvent, paused = false, width = TILE_WIDTH, height = TILE_HEIGHT, debug = false, }) {
+    // Compile patterns once on mount
+    const compiledSpec = useMemo(() => compileScene(inputSpec), [inputSpec]);
+    // Get background color from spec
+    const backgroundColor = useMemo(() => {
+        const bg = compiledSpec.style?.background?.color;
+        if (bg) {
+            return parseInt(bg.replace('#', ''), 16);
+        }
+        return 0x0a0a1a; // Default dark background
+    }, [compiledSpec]);
+    return (React.createElement(PixiGame, { width: width, height: height, background: backgroundColor, paused: paused },
+        React.createElement(SceneContent, { spec: compiledSpec, onEvent: onEvent, paused: paused, width: width, height: height, debug: debug })));
+}
+/**
+ * Inner component that runs inside PixiGame context
+ */
+function SceneContent({ spec, onEvent, paused, width, height, debug, }) {
+    // Initialize refs for all state
+    const entitiesRef = useRef(new Map());
+    const playerRef = useRef(createPlayerState());
+    const cameraRef = useRef(createCameraState(spec.camera));
+    const inputRef = useRef(createInputState());
+    const timelineRef = useRef(createTimelineState());
+    const engineRef = useRef(null);
+    const startTimeRef = useRef(Date.now());
+    // Get layers from spec or use defaults
+    const layers = useMemo(() => {
+        if (spec.layers && spec.layers.length > 0) {
+            return spec.layers;
+        }
+        // Default dash layers
+        return ['bg', 'deco', 'solids', 'hazards', 'orbs', 'player', 'fx', 'ui'];
+    }, [spec.layers]);
+    // Get BPM from spec
+    const bpm = spec.meta?.bpm ?? 120;
+    // Event emitter callback
+    const emitEvent = useCallback((event, data) => {
+        onEvent?.(event, data);
+    }, [onEvent]);
+    // Get entity by ID
+    const getEntity = useCallback((id) => {
+        return entitiesRef.current.get(id);
+    }, []);
+    // Spawn entity from prefab
+    const spawnEntity = useCallback((prefabId, x, y) => {
+        const prefab = spec.prefabs?.[prefabId];
+        if (!prefab) {
+            console.warn(`Prefab not found: ${prefabId}`);
+            return;
+        }
+        const id = `${prefabId}_${Date.now()}`;
+        const entity = {
+            id,
+            kind: prefab.kind ?? 'rect',
+            layer: prefab.layer ?? 'fx',
+            transform: {
+                x,
+                y,
+                ...prefab.transform,
+            },
+            geom: prefab.geom ?? { w: 20, h: 20 },
+            render: prefab.render,
+            body: prefab.body,
+            tags: prefab.tags,
+            components: prefab.components,
+        };
+        entitiesRef.current.set(id, createEntityState(entity));
+    }, [spec.prefabs]);
+    // Destroy entity
+    const destroyEntity = useCallback((id) => {
+        const entity = entitiesRef.current.get(id);
+        if (entity) {
+            entity.destroyed = true;
+            // Body cleanup happens in physics engine
+        }
+    }, []);
+    // Respawn player at checkpoint
+    const respawnPlayer = useCallback(() => {
+        const player = playerRef.current;
+        player.dead = false;
+        player.jumpCount = 0;
+        player.gravityDir = 1;
+        // Find player entity and reset position
+        for (const [, state] of entitiesRef.current) {
+            if (state.entity.tags?.includes('player')) {
+                state.x = player.checkpointX || 128;
+                state.y = player.checkpointY || (height - 100);
+                state.velocityX = 0;
+                state.velocityY = 0;
+                state.rotation = 0;
+                break;
+            }
+        }
+        emitEvent('player.respawn', { x: player.checkpointX, y: player.checkpointY });
+    }, [height, emitEvent]);
+    // Build context value
+    const contextValue = useMemo(() => ({
+        spec,
+        entities: entitiesRef,
+        layers,
+        player: playerRef,
+        camera: cameraRef,
+        input: inputRef,
+        timeline: timelineRef,
+        engine: engineRef,
+        emitEvent,
+        getEntity,
+        spawnEntity,
+        destroyEntity,
+        respawnPlayer,
+        bpm,
+        startTime: startTimeRef.current,
+    }), [spec, layers, bpm, emitEvent, getEntity, spawnEntity, destroyEntity, respawnPlayer]);
+    // Initialize entities from spec
+    useEffect(() => {
+        const entityMap = new Map();
+        for (const entity of spec.entities) {
+            entityMap.set(entity.id, createEntityState(entity));
+        }
+        entitiesRef.current = entityMap;
+        // Find player and set initial checkpoint
+        for (const entity of spec.entities) {
+            if (entity.tags?.includes('player')) {
+                playerRef.current.checkpointX = entity.transform.x;
+                playerRef.current.checkpointY = entity.transform.y;
+                break;
+            }
+        }
+        // Reset start time
+        startTimeRef.current = Date.now();
+        timelineRef.current = createTimelineState();
+    }, [spec]);
+    // Initialize physics engine
+    usePhysicsEngine(contextValue, width, height);
+    // Initialize input handling
+    useInputManager(contextValue);
+    // Run component logic
+    useComponentRunner(contextValue);
+    // Run timeline
+    useTimelineExecutor(contextValue);
+    // Update camera
+    useCameraController(contextValue, width, height);
+    // Main game loop
+    useGameLoop((delta) => {
+        if (paused)
+            return;
+        // Update timeline elapsed time
+        const now = Date.now();
+        timelineRef.current.elapsedMs = now - startTimeRef.current;
+        timelineRef.current.currentBeat = (timelineRef.current.elapsedMs / 1000) * (bpm / 60);
+    }, !paused);
+    // Render entities grouped by layer
+    const renderLayers = useMemo(() => {
+        return layers.map((layer, layerIndex) => (React.createElement(Container, { key: layer, zIndex: layerIndex },
+            React.createElement(LayerRenderer, { layer: layer, debug: debug }))));
+    }, [layers, debug]);
+    return (React.createElement(SceneContext.Provider, { value: contextValue },
+        React.createElement(Container, { x: -cameraRef.current.x + width / 2, y: -cameraRef.current.y + height / 2, scale: cameraRef.current.zoom }, renderLayers)));
+}
+/**
+ * Renders all entities in a layer
+ */
+function LayerRenderer({ layer, debug }) {
+    const { entities } = useScene();
+    // Filter and sort entities for this layer
+    const layerEntities = useMemo(() => {
+        const result = [];
+        for (const [, state] of entities.current) {
+            if (state.entity.layer === layer && !state.destroyed && state.visible) {
+                result.push(state);
+            }
+        }
+        // Sort by zIndex within layer
+        result.sort((a, b) => {
+            const zA = a.entity.render?.zIndex ?? 0;
+            const zB = b.entity.render?.zIndex ?? 0;
+            return zA - zB;
+        });
+        return result;
+    }, [entities, layer]);
+    return (React.createElement(React.Fragment, null, layerEntities.map((state) => (React.createElement(EntityRenderer, { key: state.entity.id, state: state, debug: debug })))));
+}
+// Re-export useScene for convenience
+import { useScene } from './SceneContext';
+export { useScene };

package/dist/scene/camera/CameraController.d.ts

@@ -0,0 +1,6 @@
+import type { SceneContextValue } from '../SceneContext';
+/**
+ * Hook to control the camera
+ */
+export declare function useCameraController(context: SceneContextValue, width: number, height: number): void;
+//# sourceMappingURL=CameraController.d.ts.map

package/dist/scene/camera/CameraController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CameraController.d.ts","sourceRoot":"","sources":["../../../src/scene/camera/CameraController.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,iBAAiB,EAC1B,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,QAsFf"}