@penabt/pixi-expo 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Pena Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,202 @@
+# @penabt/pixi-expo
+
+[![npm version](https://img.shields.io/npm/v/@penabt/pixi-expo.svg)](https://www.npmjs.com/package/@penabt/pixi-expo)
+[![license](https://img.shields.io/npm/l/@penabt/pixi-expo.svg)](https://github.com/penabt/pixi-expo/blob/main/LICENSE)
+
+**PixiJS v8 adapter for React Native Expo.** Enables hardware-accelerated 2D graphics in your Expo applications using the expo-gl WebGL context.
+
+## Features
+
+- 🚀 **PixiJS v8 Support** - Full compatibility with the latest PixiJS version
+- 📱 **Expo Integration** - Works seamlessly with Expo managed and bare workflows
+- ⚡ **60 FPS Performance** - Hardware-accelerated WebGL rendering via expo-gl
+- 🎮 **Game Ready** - Perfect for 2D games, animations, and interactive graphics
+- 📦 **Easy Setup** - Drop-in PixiView component with simple API
+- 🔧 **Customizable** - Access to full PixiJS API and expo-gl context
+
+## Installation
+
+```bash
+# Install the package
+npm install @penabt/pixi-expo
+
+# Install peer dependencies
+npx expo install expo-gl expo-asset expo-font pixi.js
+```
+
+## Quick Start
+
+```tsx
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { PixiView, Graphics, Application } from '@penabt/pixi-expo';
+
+export default function GameScreen() {
+  const handleAppCreate = (app: Application) => {
+    // Create a red circle
+    const circle = new Graphics()
+      .circle(0, 0, 50)
+      .fill({ color: 0xff0000 });
+    
+    circle.position.set(200, 300);
+    app.stage.addChild(circle);
+
+    // Animate with the ticker
+    app.ticker.add(() => {
+      circle.rotation += 0.01;
+    });
+  };
+
+  return (
+    <View style={styles.container}>
+      <PixiView
+        style={styles.game}
+        backgroundColor={0x1099bb}
+        onApplicationCreate={handleAppCreate}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { flex: 1 },
+  game: { flex: 1 },
+});
+```
+
+## API Reference
+
+### PixiView Component
+
+The main component for rendering PixiJS content.
+
+```tsx
+<PixiView
+  style={ViewStyle}                         // Container styles
+  backgroundColor={0x000000}                // Background color (hex)
+  resolution={1}                            // Device pixel ratio
+  antialias={true}                          // Enable antialiasing
+  onApplicationCreate={(app) => {}}         // Called when app is ready
+  onContextCreate={(gl) => {}}              // Called when GL context created
+  onError={(error) => {}}                   // Called on initialization error
+/>
+```
+
+### PixiView Ref Handle
+
+Access the PixiJS Application imperatively:
+
+```tsx
+const pixiRef = useRef<PixiViewHandle>(null);
+
+// Get the application
+const app = pixiRef.current?.getApplication();
+
+// Get the stage
+const stage = pixiRef.current?.getStage();
+
+// Force render
+pixiRef.current?.render();
+
+// Take screenshot
+const base64 = await pixiRef.current?.takeSnapshot();
+```
+
+### Re-exported from PixiJS
+
+For convenience, common PixiJS exports are available directly:
+
+```tsx
+import {
+  // Display Objects
+  Application,
+  Container,
+  Sprite,
+  Graphics,
+  Text,
+  TilingSprite,
+  AnimatedSprite,
+  Mesh,
+  NineSliceSprite,
+  
+  // Textures
+  Texture,
+  RenderTexture,
+  Assets,
+  
+  // Geometry
+  Matrix,
+  Point,
+  Rectangle,
+  Circle,
+  Polygon,
+  
+  // Filters
+  Filter,
+  BlurFilter,
+  ColorMatrixFilter,
+  
+  // Animation
+  Ticker,
+  
+  // And more...
+} from '@penabt/pixi-expo';
+```
+
+## Loading Assets
+
+### Bundled Assets (require)
+
+```tsx
+import { loadTexture, Sprite } from '@penabt/pixi-expo';
+
+// Load a bundled image
+const texture = await loadTexture(require('./assets/bunny.png'));
+const sprite = new Sprite(texture);
+```
+
+### Remote Assets (URL)
+
+```tsx
+// Load from URL
+const texture = await Assets.load('https://example.com/sprite.png');
+```
+
+## Performance Tips
+
+1. **Use Shared Ticker** - PixiView enables `sharedTicker` by default for optimal performance
+
+2. **Batch Rendering** - Group similar sprites using `ParticleContainer` for many objects
+
+3. **Texture Atlases** - Use spritesheets instead of individual images
+
+4. **Avoid Text Updates** - Cache text objects, don't create new ones every frame
+
+5. **Production Builds** - Run `npx expo run:ios --configuration Release` for best performance
+
+## Limitations
+
+- **No Canvas 2D** - expo-gl only supports WebGL, not Canvas 2D context
+- **No HTMLText** - HTML-based text rendering is not available
+- **Font Loading** - Use expo-font for loading custom fonts
+
+## Compatibility
+
+| Package | Version |
+|---------|---------|
+| pixi.js | ≥ 8.0.0 |
+| expo | ≥ 50.0.0 |
+| expo-gl | ≥ 14.0.0 |
+| react-native | ≥ 0.73.0 |
+
+## Contributing
+
+Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.
+
+## License
+
+MIT © [Pena Team](https://github.com/penabt)
+
+---
+
+Made with ❤️ by [Pena Team](https://github.com/penabt)

package/package.json

@@ -0,0 +1,98 @@
+{
+    "name": "@penabt/pixi-expo",
+    "version": "0.1.0",
+    "description": "PixiJS v8 adapter for React Native Expo. Enables hardware-accelerated 2D graphics using expo-gl WebGL context.",
+    "main": "src/index.ts",
+    "module": "src/index.ts",
+    "types": "src/index.ts",
+    "source": "src/index.ts",
+    "sideEffects": [
+        "./src/adapter/polyfills.ts",
+        "./lib/adapter/polyfills.js",
+        "./lib/adapter/polyfills.mjs"
+    ],
+    "publishConfig": {
+        "main": "lib/index.js",
+        "module": "lib/index.mjs",
+        "types": "lib/index.d.ts",
+        "exports": {
+            ".": {
+                "import": "./lib/index.mjs",
+                "require": "./lib/index.js",
+                "types": "./lib/index.d.ts"
+            }
+        }
+    },
+    "files": [
+        "lib",
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+        "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+        "prepublishOnly": "npm run build",
+        "clean": "rm -rf lib",
+        "typecheck": "tsc --noEmit",
+        "lint": "eslint src --ext .ts,.tsx"
+    },
+    "keywords": [
+        "pena",
+        "pixi",
+        "pixijs",
+        "pixi.js",
+        "expo",
+        "expo-gl",
+        "react-native",
+        "webgl",
+        "2d",
+        "graphics",
+        "game",
+        "animation",
+        "canvas",
+        "renderer"
+    ],
+    "author": {
+        "name": "Pena Team",
+        "url": "https://github.com/penabt"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/penabt/pixi-expo.git"
+    },
+    "bugs": {
+        "url": "https://github.com/penabt/pixi-expo/issues"
+    },
+    "homepage": "https://github.com/penabt/pixi-expo#readme",
+    "license": "MIT",
+    "engines": {
+        "node": ">=18.0.0"
+    },
+    "peerDependencies": {
+        "expo": ">=50.0.0",
+        "expo-asset": ">=10.0.0",
+        "expo-font": ">=12.0.0",
+        "expo-gl": ">=14.0.0",
+        "pixi.js": ">=8.0.0",
+        "react": ">=18.0.0",
+        "react-native": ">=0.73.0"
+    },
+    "peerDependenciesMeta": {
+        "expo-asset": {
+            "optional": true
+        },
+        "expo-font": {
+            "optional": true
+        }
+    },
+    "dependencies": {
+        "@xmldom/xmldom": "^0.8.10"
+    },
+    "devDependencies": {
+        "@types/react": "^19.2.13",
+        "@types/react-native": "^0.72.8",
+        "tsup": "^8.5.1",
+        "typescript": "^5.9.3"
+    }
+}

package/src/adapter/ExpoAdapter.ts

@@ -0,0 +1,343 @@
+/**
+ * @fileoverview PixiJS DOMAdapter implementation for expo-gl.
+ *
+ * This module provides the core adapter that bridges PixiJS's browser-based
+ * architecture to React Native's expo-gl WebGL implementation.
+ *
+ * @module @penabt/pixi-expo/ExpoAdapter
+ * @author Pena Team
+ * @license MIT
+ *
+ * @description
+ * PixiJS uses a DOMAdapter pattern to abstract browser APIs. This adapter
+ * implements that interface for React Native:
+ *
+ * - createCanvas: Returns ExpoCanvasElement wrapping expo-gl context
+ * - createImage: Returns image-like object for texture loading
+ * - getWebGLRenderingContext: Returns WebGL constructor
+ * - fetch: Handles remote and local asset URLs
+ * - parseXML: Uses @xmldom/xmldom for SVG and other XML parsing
+ *
+ * @example Setting up the adapter
+ * ```ts
+ * import { ExpoAdapter, setActiveGLContext } from '@penabt/pixi-expo';
+ * import { DOMAdapter } from 'pixi.js';
+ *
+ * // Set adapter before creating Application
+ * DOMAdapter.set(ExpoAdapter);
+ *
+ * // In GLView.onContextCreate:
+ * const canvas = setActiveGLContext(gl, width, height);
+ * ```
+ */
+
+import type { ExpoWebGLRenderingContext } from 'expo-gl';
+import { ExpoCanvasElement } from './ExpoCanvasElement';
+import { DOMParser } from '@xmldom/xmldom';
+
+// =============================================================================
+// MODULE STATE
+// Tracks the currently active GL context for PixiJS rendering.
+// =============================================================================
+
+/** Currently active canvas element wrapper */
+let activeCanvas: ExpoCanvasElement | null = null;
+
+/** Currently active expo-gl WebGL context */
+let activeGL: ExpoWebGLRenderingContext | null = null;
+
+// =============================================================================
+// CONTEXT MANAGEMENT FUNCTIONS
+// Public API for managing the active GL context.
+// =============================================================================
+
+/**
+ * Set the active GL context from expo-gl's GLView.
+ *
+ * This function must be called in GLView's onContextCreate callback
+ * before creating any PixiJS Application or renderer.
+ *
+ * @param gl - The WebGL context from expo-gl
+ * @param width - Canvas width in pixels
+ * @param height - Canvas height in pixels
+ * @returns ExpoCanvasElement configured with the GL context
+ *
+ * @example
+ * ```tsx
+ * <GLView
+ *   onContextCreate={(gl) => {
+ *     const canvas = setActiveGLContext(
+ *       gl,
+ *       gl.drawingBufferWidth,
+ *       gl.drawingBufferHeight
+ *     );
+ *     // canvas is now ready for PixiJS
+ *   }}
+ * />
+ * ```
+ */
+export function setActiveGLContext(
+    gl: ExpoWebGLRenderingContext,
+    width: number,
+    height: number
+): ExpoCanvasElement {
+    activeCanvas = new ExpoCanvasElement(width, height);
+    activeCanvas.setGLContext(gl);
+    activeGL = gl;
+    return activeCanvas;
+}
+
+/**
+ * Get the currently active canvas element.
+ *
+ * @returns The active ExpoCanvasElement, or null if none is set
+ */
+export function getActiveCanvas(): ExpoCanvasElement | null {
+    return activeCanvas;
+}
+
+/**
+ * Get the currently active expo-gl WebGL context.
+ *
+ * @returns The active GL context, or null if none is set
+ */
+export function getActiveGL(): ExpoWebGLRenderingContext | null {
+    return activeGL;
+}
+
+/**
+ * Clear the active context.
+ *
+ * Should be called when the GLView unmounts to prevent memory leaks
+ * and stale references.
+ */
+export function clearActiveContext(): void {
+    activeCanvas = null;
+    activeGL = null;
+}
+
+// =============================================================================
+// EXPO ADAPTER
+// Main adapter object implementing PixiJS's Adapter interface.
+// =============================================================================
+
+/**
+ * PixiJS DOMAdapter implementation for React Native Expo.
+ *
+ * This object provides the bridge between PixiJS's browser expectations
+ * and React Native's expo-gl environment. It's set as the active adapter
+ * via `DOMAdapter.set(ExpoAdapter)`.
+ *
+ * @remarks
+ * Key differences from browser adapter:
+ * - Canvas 2D context is not supported (WebGL only)
+ * - FontFaceSet is not available (use expo-font)
+ * - Base URL is empty (use expo-asset for bundled resources)
+ * - XML parsing uses @xmldom/xmldom instead of DOMParser
+ */
+export const ExpoAdapter = {
+    // ===========================================================================
+    // CANVAS CREATION
+    // ===========================================================================
+
+    /**
+     * Create a canvas element for rendering.
+     *
+     * If an active canvas exists (from setActiveGLContext), returns it.
+     * Otherwise creates a new ExpoCanvasElement that will need a GL context.
+     *
+     * @param width - Canvas width in pixels
+     * @param height - Canvas height in pixels
+     * @returns ExpoCanvasElement instance
+     */
+    createCanvas: (width?: number, height?: number): ExpoCanvasElement => {
+        if (activeCanvas) {
+            // Update dimensions if provided
+            if (width !== undefined) activeCanvas.width = width;
+            if (height !== undefined) activeCanvas.height = height;
+            return activeCanvas;
+        }
+
+        // Create placeholder canvas (will need GL context later)
+        return new ExpoCanvasElement(width ?? 1, height ?? 1);
+    },
+
+    // ===========================================================================
+    // IMAGE CREATION
+    // ===========================================================================
+
+    /**
+     * Create an image element for texture loading.
+     *
+     * Returns a minimal HTMLImageElement-like object. For actual texture
+     * loading, use the loadExpoAsset loader extension which integrates
+     * with expo-asset.
+     *
+     * @returns Object mimicking HTMLImageElement interface
+     */
+    createImage: (): any => {
+        const image = {
+            src: '',
+            width: 0,
+            height: 0,
+            naturalWidth: 0,
+            naturalHeight: 0,
+            complete: false,
+            crossOrigin: '' as string | null,
+            onload: null as ((this: any, ev: Event) => any) | null,
+            onerror: null as OnErrorEventHandler | null,
+
+            /**
+             * Setting source would trigger image loading.
+             * Full implementation uses expo-asset or react-native Image.
+             */
+            set source(value: string) {
+                this.src = value;
+            },
+        };
+
+        return image;
+    },
+
+    // ===========================================================================
+    // RENDERING CONTEXT ACCESS
+    // ===========================================================================
+
+    /**
+     * Get the Canvas 2D rendering context constructor.
+     *
+     * @returns null - Canvas 2D is not supported in expo-gl
+     *
+     * @remarks
+     * expo-gl only provides WebGL contexts. For 2D canvas operations,
+     * consider using @shopify/react-native-skia as an alternative.
+     */
+    getCanvasRenderingContext2D: (): any => {
+        console.warn('ExpoAdapter: 2D context is not supported in expo-gl');
+        return null;
+    },
+
+    /**
+     * Get the WebGL rendering context constructor.
+     *
+     * @returns WebGLRenderingContext constructor
+     */
+    getWebGLRenderingContext: (): typeof WebGLRenderingContext => {
+        return WebGLRenderingContext;
+    },
+
+    // ===========================================================================
+    // BROWSER API SHIMS
+    // ===========================================================================
+
+    /**
+     * Get navigator information.
+     *
+     * Returns minimal navigator object for feature detection.
+     * GPU access is not available in React Native.
+     *
+     * @returns Navigator-like object
+     */
+    getNavigator: (): { userAgent: string; gpu: GPU | null } => {
+        return {
+            userAgent: 'expo-gl/react-native',
+            gpu: null,
+        };
+    },
+
+    /**
+     * Get the base URL for relative resource loading.
+     *
+     * @returns Empty string - React Native has no traditional base URL
+     *
+     * @remarks
+     * For bundled assets, use expo-asset's Asset.fromModule(require('./file'))
+     * instead of relative URLs.
+     */
+    getBaseUrl: (): string => {
+        return '';
+    },
+
+    /**
+     * Get the FontFaceSet for CSS font loading.
+     *
+     * @returns null - FontFaceSet is not available in React Native
+     *
+     * @remarks
+     * Use expo-font's Font.loadAsync() for font loading in Expo apps.
+     * The loadExpoFont loader extension provides PixiJS integration.
+     */
+    getFontFaceSet: (): FontFaceSet | null => {
+        return null;
+    },
+
+    // ===========================================================================
+    // NETWORK REQUESTS
+    // ===========================================================================
+
+    /**
+     * Fetch a resource from network or local storage.
+     *
+     * Handles different URL schemes:
+     * - http:// / https:// - Standard network fetch
+     * - file:// - Local file (requires expo-file-system)
+     * - asset:// - Bundled asset (requires expo-asset)
+     *
+     * @param url - Resource URL or Request object
+     * @param options - Fetch options
+     * @returns Promise resolving to Response
+     *
+     * @example
+     * ```ts
+     * const response = await ExpoAdapter.fetch('https://example.com/data.json');
+     * const json = await response.json();
+     * ```
+     */
+    fetch: async (url: RequestInfo, options?: RequestInit): Promise<Response> => {
+        const requestUrl = typeof url === 'string' ? url : (url as Request).url;
+
+        // Remote URL - use standard fetch
+        if (requestUrl.startsWith('http://') || requestUrl.startsWith('https://')) {
+            return fetch(requestUrl, options);
+        }
+
+        // Local file URL
+        if (requestUrl.startsWith('file://')) {
+            console.warn('ExpoAdapter: Local file loading requires expo-file-system');
+            return fetch(requestUrl, options);
+        }
+
+        // Asset URL or require() number
+        if (requestUrl.startsWith('asset://') || typeof url === 'number') {
+            console.warn('ExpoAdapter: Asset loading requires expo-asset');
+            throw new Error('Asset loading not implemented');
+        }
+
+        // Default - try standard fetch
+        return fetch(requestUrl, options);
+    },
+
+    // ===========================================================================
+    // XML PARSING
+    // ===========================================================================
+
+    /**
+     * Parse an XML string into a Document.
+     *
+     * Uses @xmldom/xmldom since native DOMParser is not available
+     * in React Native. Required for SVG and other XML asset parsing.
+     *
+     * @param xml - XML string to parse
+     * @returns Parsed Document object
+     *
+     * @example
+     * ```ts
+     * const svg = '<svg>...</svg>';
+     * const doc = ExpoAdapter.parseXML(svg);
+     * ```
+     */
+    parseXML: (xml: string): Document => {
+        const parser = new DOMParser();
+        return parser.parseFromString(xml, 'text/xml') as unknown as Document;
+    },
+};