@thewhateverapp/tile-sdk 0.13.34 → 0.13.36

package/dist/react/PixiGame.d.ts

@@ -0,0 +1,156 @@
+/**
+ * PixiGame - A wrapper component that abstracts @pixi/react v7's Stage boilerplate
+ *
+ * @pixi/react v7 uses the Stage component which provides the Application context.
+ * Hooks like useTick must be used INSIDE the Stage tree.
+ *
+ * This component handles all of that setup automatically.
+ *
+ * @example
+ * ```tsx
+ * import { PixiGame, useGameLoop, Container, Graphics } from '@thewhateverapp/tile-sdk';
+ *
+ * function MyGame() {
+ *   return (
+ *     <PixiGame>
+ *       <GameContent />
+ *     </PixiGame>
+ *   );
+ * }
+ *
+ * function GameContent() {
+ *   const playerRef = useRef({ x: 128, y: 400 });
+ *
+ *   useGameLoop((delta) => {
+ *     // Game logic here - runs every frame
+ *     playerRef.current.x += 1 * delta;
+ *   });
+ *
+ *   return (
+ *     <Container>
+ *       <Graphics draw={(g) => {
+ *         g.beginFill(0xff0000);
+ *         g.drawRect(playerRef.current.x, playerRef.current.y, 32, 32);
+ *         g.endFill();
+ *       }} />
+ *     </Container>
+ *   );
+ * }
+ * ```
+ */
+import React, { ReactNode } from 'react';
+import { Container, Sprite, Graphics, Text, AnimatedSprite, TilingSprite, NineSlicePlane, useApp } from '@pixi/react';
+export { Container, Sprite, Graphics, Text, AnimatedSprite, TilingSprite, NineSlicePlane };
+export { useApp };
+/**
+ * Tile dimensions - standard tile size
+ */
+export declare const TILE_WIDTH = 256;
+export declare const TILE_HEIGHT = 554;
+export interface PixiGameProps {
+    children: ReactNode;
+    /** Width in pixels (default: 256 for tile) */
+    width?: number;
+    /** Height in pixels (default: 554 for tile) */
+    height?: number;
+    /** Background color (default: black) */
+    background?: number;
+    /** Stage options */
+    options?: {
+        antialias?: boolean;
+        resolution?: number;
+        autoDensity?: boolean;
+    };
+    /** Whether game is paused */
+    paused?: boolean;
+    /** Callback when Application is ready */
+    onMount?: (app: any) => void;
+}
+/**
+ * PixiGame - Main wrapper component for pixi.js games
+ *
+ * Provides the Stage/Application context that @pixi/react hooks need.
+ * All game content should be rendered as children of this component.
+ *
+ * Use pixi components directly:
+ * - <Container> - Container for grouping elements
+ * - <Sprite texture={...}> - Sprite with texture
+ * - <Graphics draw={...}> - Graphics with draw callback
+ * - <Text text="..." style={...}> - Text element
+ */
+export declare function PixiGame({ children, width, height, background, options, paused, onMount, }: PixiGameProps): React.JSX.Element;
+/**
+ * useGameLoop - A more intuitive name for useTick
+ *
+ * Runs a callback every frame with delta time.
+ * Must be used inside a PixiGame component (or any @pixi/react Stage).
+ *
+ * @param callback - Function called every frame with delta time (in frames, ~1 at 60fps)
+ * @param enabled - Whether the loop is active (default: true)
+ *
+ * @example
+ * ```tsx
+ * function GameContent() {
+ *   const posRef = useRef({ x: 0, y: 0 });
+ *
+ *   useGameLoop((delta) => {
+ *     posRef.current.x += 2 * delta;
+ *     if (posRef.current.x > 256) posRef.current.x = 0;
+ *   });
+ *
+ *   return <Sprite x={posRef.current.x} y={posRef.current.y} texture={...} />;
+ * }
+ * ```
+ */
+export declare function useGameLoop(callback: (delta: number) => void, enabled?: boolean): void;
+/**
+ * useGameState - Helper for managing game state with refs
+ *
+ * Returns a ref and a forceUpdate function for when you need to trigger re-renders.
+ * Use refs for continuous game state (position, velocity) to avoid re-render loops.
+ *
+ * @example
+ * ```tsx
+ * function GameContent() {
+ *   const [state, forceUpdate] = useGameState({
+ *     playerX: 128,
+ *     playerY: 400,
+ *     score: 0,
+ *   });
+ *
+ *   useGameLoop((delta) => {
+ *     state.current.playerX += 1 * delta;
+ *     if (scoreChanged) {
+ *       forceUpdate(); // Only re-render when score changes
+ *     }
+ *   });
+ *
+ *   return <Text text={`Score: ${state.current.score}`} />;
+ * }
+ * ```
+ */
+export declare function useGameState<T extends object>(initialState: T): [React.MutableRefObject<T>, () => void];
+/**
+ * useGameInput - Simple keyboard input hook for games
+ *
+ * Returns a ref with currently pressed keys.
+ * Can be used inside or outside PixiGame component.
+ *
+ * @example
+ * ```tsx
+ * function GameContent() {
+ *   const keys = useGameInput();
+ *   const posRef = useRef({ x: 128, y: 400 });
+ *
+ *   useGameLoop((delta) => {
+ *     if (keys.current.ArrowLeft) posRef.current.x -= 5 * delta;
+ *     if (keys.current.ArrowRight) posRef.current.x += 5 * delta;
+ *     if (keys.current[' ']) jump(); // Space key
+ *   });
+ *
+ *   return <Sprite x={posRef.current.x} y={posRef.current.y} texture={...} />;
+ * }
+ * ```
+ */
+export declare function useGameInput(): React.MutableRefObject<Record<string, boolean>>;
+//# sourceMappingURL=PixiGame.d.ts.map

package/dist/react/PixiGame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PixiGame.d.ts","sourceRoot":"","sources":["../../src/react/PixiGame.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,KAAK,EAAE,EAAE,SAAS,EAAkC,MAAM,OAAO,CAAC;AACzE,OAAO,EAEL,SAAS,EACT,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,cAAc,EACd,YAAY,EACZ,cAAc,EAEd,MAAM,EACP,MAAM,aAAa,CAAC;AAGrB,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,cAAc,EAAE,CAAC;AAG3F,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB;;GAEG;AACH,eAAO,MAAM,UAAU,MAAM,CAAC;AAC9B,eAAO,MAAM,WAAW,MAAM,CAAC;AAE/B,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,SAAS,CAAC;IACpB,8CAA8C;IAC9C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+CAA+C;IAC/C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB;IACpB,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,WAAW,CAAC,EAAE,OAAO,CAAC;KACvB,CAAC;IACF,6BAA6B;IAC7B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,yCAAyC;IACzC,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,IAAI,CAAC;CAC9B;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,QAAQ,CAAC,EACvB,QAAQ,EACR,KAAkB,EAClB,MAAoB,EACpB,UAAqB,EACrB,OAAY,EACZ,MAAc,EACd,OAAO,GACR,EAAE,aAAa,qBAkBf;AA2BD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EACjC,OAAO,GAAE,OAAc,QAGxB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,YAAY,EAAE,CAAC,GACd,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,MAAM,IAAI,CAAC,CASzC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,YAAY,oDAwB3B"}

package/dist/react/PixiGame.js

@@ -0,0 +1,193 @@
+'use client';
+/**
+ * PixiGame - A wrapper component that abstracts @pixi/react v7's Stage boilerplate
+ *
+ * @pixi/react v7 uses the Stage component which provides the Application context.
+ * Hooks like useTick must be used INSIDE the Stage tree.
+ *
+ * This component handles all of that setup automatically.
+ *
+ * @example
+ * ```tsx
+ * import { PixiGame, useGameLoop, Container, Graphics } from '@thewhateverapp/tile-sdk';
+ *
+ * function MyGame() {
+ *   return (
+ *     <PixiGame>
+ *       <GameContent />
+ *     </PixiGame>
+ *   );
+ * }
+ *
+ * function GameContent() {
+ *   const playerRef = useRef({ x: 128, y: 400 });
+ *
+ *   useGameLoop((delta) => {
+ *     // Game logic here - runs every frame
+ *     playerRef.current.x += 1 * delta;
+ *   });
+ *
+ *   return (
+ *     <Container>
+ *       <Graphics draw={(g) => {
+ *         g.beginFill(0xff0000);
+ *         g.drawRect(playerRef.current.x, playerRef.current.y, 32, 32);
+ *         g.endFill();
+ *       }} />
+ *     </Container>
+ *   );
+ * }
+ * ```
+ */
+import React, { useCallback, useRef, useEffect } from 'react';
+import { Stage, Container, Sprite, Graphics, Text, AnimatedSprite, TilingSprite, NineSlicePlane, useTick, useApp, } from '@pixi/react';
+// Re-export @pixi/react components for convenience
+export { Container, Sprite, Graphics, Text, AnimatedSprite, TilingSprite, NineSlicePlane };
+// Re-export useApp for advanced use cases
+export { useApp };
+/**
+ * Tile dimensions - standard tile size
+ */
+export const TILE_WIDTH = 256;
+export const TILE_HEIGHT = 554;
+/**
+ * PixiGame - Main wrapper component for pixi.js games
+ *
+ * Provides the Stage/Application context that @pixi/react hooks need.
+ * All game content should be rendered as children of this component.
+ *
+ * Use pixi components directly:
+ * - <Container> - Container for grouping elements
+ * - <Sprite texture={...}> - Sprite with texture
+ * - <Graphics draw={...}> - Graphics with draw callback
+ * - <Text text="..." style={...}> - Text element
+ */
+export function PixiGame({ children, width = TILE_WIDTH, height = TILE_HEIGHT, background = 0x000000, options = {}, paused = false, onMount, }) {
+    const stageOptions = {
+        antialias: options.antialias ?? true,
+        resolution: options.resolution ?? (typeof window !== 'undefined' ? window.devicePixelRatio : 1),
+        autoDensity: options.autoDensity ?? true,
+        backgroundColor: background,
+    };
+    return (React.createElement(Stage, { width: width, height: height, options: stageOptions, onMount: onMount },
+        React.createElement(GameWrapper, { paused: paused }, children)));
+}
+/**
+ * Internal wrapper that provides pause functionality
+ */
+function GameWrapper({ children, paused, }) {
+    const app = useApp();
+    useEffect(() => {
+        if (app?.ticker) {
+            if (paused) {
+                app.ticker.stop();
+            }
+            else {
+                app.ticker.start();
+            }
+        }
+    }, [app, paused]);
+    return React.createElement(React.Fragment, null, children);
+}
+/**
+ * useGameLoop - A more intuitive name for useTick
+ *
+ * Runs a callback every frame with delta time.
+ * Must be used inside a PixiGame component (or any @pixi/react Stage).
+ *
+ * @param callback - Function called every frame with delta time (in frames, ~1 at 60fps)
+ * @param enabled - Whether the loop is active (default: true)
+ *
+ * @example
+ * ```tsx
+ * function GameContent() {
+ *   const posRef = useRef({ x: 0, y: 0 });
+ *
+ *   useGameLoop((delta) => {
+ *     posRef.current.x += 2 * delta;
+ *     if (posRef.current.x > 256) posRef.current.x = 0;
+ *   });
+ *
+ *   return <Sprite x={posRef.current.x} y={posRef.current.y} texture={...} />;
+ * }
+ * ```
+ */
+export function useGameLoop(callback, enabled = true) {
+    useTick(callback, enabled);
+}
+/**
+ * useGameState - Helper for managing game state with refs
+ *
+ * Returns a ref and a forceUpdate function for when you need to trigger re-renders.
+ * Use refs for continuous game state (position, velocity) to avoid re-render loops.
+ *
+ * @example
+ * ```tsx
+ * function GameContent() {
+ *   const [state, forceUpdate] = useGameState({
+ *     playerX: 128,
+ *     playerY: 400,
+ *     score: 0,
+ *   });
+ *
+ *   useGameLoop((delta) => {
+ *     state.current.playerX += 1 * delta;
+ *     if (scoreChanged) {
+ *       forceUpdate(); // Only re-render when score changes
+ *     }
+ *   });
+ *
+ *   return <Text text={`Score: ${state.current.score}`} />;
+ * }
+ * ```
+ */
+export function useGameState(initialState) {
+    const stateRef = useRef(initialState);
+    const [, setTick] = React.useState(0);
+    const forceUpdate = useCallback(() => {
+        setTick((t) => t + 1);
+    }, []);
+    return [stateRef, forceUpdate];
+}
+/**
+ * useGameInput - Simple keyboard input hook for games
+ *
+ * Returns a ref with currently pressed keys.
+ * Can be used inside or outside PixiGame component.
+ *
+ * @example
+ * ```tsx
+ * function GameContent() {
+ *   const keys = useGameInput();
+ *   const posRef = useRef({ x: 128, y: 400 });
+ *
+ *   useGameLoop((delta) => {
+ *     if (keys.current.ArrowLeft) posRef.current.x -= 5 * delta;
+ *     if (keys.current.ArrowRight) posRef.current.x += 5 * delta;
+ *     if (keys.current[' ']) jump(); // Space key
+ *   });
+ *
+ *   return <Sprite x={posRef.current.x} y={posRef.current.y} texture={...} />;
+ * }
+ * ```
+ */
+export function useGameInput() {
+    const keysRef = useRef({});
+    useEffect(() => {
+        const handleKeyDown = (e) => {
+            keysRef.current[e.key] = true;
+            keysRef.current[e.code] = true;
+        };
+        const handleKeyUp = (e) => {
+            keysRef.current[e.key] = false;
+            keysRef.current[e.code] = false;
+        };
+        window.addEventListener('keydown', handleKeyDown);
+        window.addEventListener('keyup', handleKeyUp);
+        return () => {
+            window.removeEventListener('keydown', handleKeyDown);
+            window.removeEventListener('keyup', handleKeyUp);
+        };
+    }, []);
+    return keysRef;
+}

package/dist/react/index.d.ts

@@ -4,5 +4,7 @@ export { useTile } from './useTile';
 export { useKeyboard } from './useKeyboard';
 export { TileContainer } from './TileContainer';
 export { withTile } from './withTile';
+export { PixiGame, useGameLoop, useGameState, useGameInput, Container, Sprite, Graphics, Text, AnimatedSprite, TilingSprite, NineSlicePlane, useApp, TILE_WIDTH, TILE_HEIGHT, } from './PixiGame';
+export type { PixiGameProps } from './PixiGame';
 export * from './overlay';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAC3D,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACpC,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAItC,OAAO,EACL,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,YAAY,EAEZ,SAAS,EACT,MAAM,EACN,QAAQ,EACR,IAAI,EACJ,cAAc,EACd,YAAY,EACZ,cAAc,EACd,MAAM,EAEN,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,YAAY,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAGhD,cAAc,WAAW,CAAC"}

package/dist/react/index.js

@@ -5,5 +5,11 @@ export { useKeyboard } from './useKeyboard';
 export { TileContainer } from './TileContainer';
 export { withTile } from './withTile';
 // TileInitializer removed - router should be injected directly into TileProvider
+// PixiGame wrapper for @pixi/react games - abstracts Stage context boilerplate
+export { PixiGame, useGameLoop, useGameState, useGameInput, 
+// Re-exported @pixi/react components
+Container, Sprite, Graphics, Text, AnimatedSprite, TilingSprite, NineSlicePlane, useApp, 
+// Constants
+TILE_WIDTH, TILE_HEIGHT, } from './PixiGame';
 // Overlay components for hybrid tiles (video/image with interactive overlays)
 export * from './overlay';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thewhateverapp/tile-sdk",
-  "version": "0.13.34",
+  "version": "0.13.36",
   "description": "SDK for building interactive tiles on The Whatever App platform",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -59,13 +59,25 @@
     "zod": "^3.22.0"
   },
   "peerDependencies": {
-    "react": "^18.0.0"
+    "react": "^18.0.0",
+    "@pixi/react": "^7.0.0",
+    "pixi.js": "^7.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@pixi/react": {
+      "optional": true
+    },
+    "pixi.js": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@pixi/react": "^7.1.2",
     "@types/node": "^20.0.0",
     "@types/react": "^18.2.48",
     "eslint": "^9.39.1",
     "next": "^14.2.0",
+    "pixi.js": "^7.4.2",
     "typescript": "^5.3.3"
   }
 }