@penabt/pixi-expo 0.6.0 → 0.6.2

package/README.md

@@ -292,7 +292,7 @@ module.exports = config;
 
 ## Design Resolution
 
-Cocos2d-style fixed coordinate system for your game. Define a virtual resolution and the library automatically scales the stage to fit any device screen.
+fFixed coordinate system for your game. Define a virtual resolution and the library renders at native device quality — no GPU texture stretching.
 
 ```tsx
 <PixiView
@@ -319,11 +319,11 @@ Cocos2d-style fixed coordinate system for your game. Define a virtual resolution
 
 ### How It Works
 
-The renderer runs at the device's real screen size for full quality. The stage is transformed (scaled + positioned) so your game logic always works in the design coordinate space.
+The renderer operates directly in design coordinates and uses PixiJS's `resolution` property to bridge to physical pixels. Textures render at native device resolution with no GPU upscaling artifacts.
 
-- **NO_BORDER**: `scale = max(screenW/designW, screenH/designH)` — uniform scale, no gaps, edges cropped
-- **SHOW_ALL**: `scale = min(screenW/designW, screenH/designH)` — uniform scale, no crop, bars on short axis
-- **EXACT_FIT**: `scaleX = screenW/designW, scaleY = screenH/designH` — non-uniform, fills exactly
+- **NO_BORDER**: `resolution = max(physicalW/designW, physicalH/designH)` — viewport smaller than design, edges cropped
+- **SHOW_ALL**: `resolution = min(physicalW/designW, physicalH/designH)` — viewport larger than design, letterbox bars
+- **EXACT_FIT**: `resolution = max(resX, resY)` with per-axis stage scale compensation for the non-uniform axis
 
 ### Design Tips
 
@@ -337,8 +337,8 @@ The renderer runs at the device's real screen size for full quality. The stage i
 ```tsx
 import { calculateDesignScale } from '@penabt/pixi-expo';
 
-const scale = calculateDesignScale(720, 1280, screenWidth, screenHeight, 'NO_BORDER');
-// scale.scaleX, scale.scaleY, scale.offsetX, scale.offsetY
+const scale = calculateDesignScale(720, 1280, physicalWidth, physicalHeight, 'NO_BORDER');
+// scale.resolution, scale.viewportWidth, scale.viewportHeight, scale.offsetX, scale.offsetY
 ```
 
 ## Safe Area
@@ -397,10 +397,11 @@ export default function App() {
 
 ### How It Works
 
-`getSafeArea()` converts physical screen insets to your design coordinate space using the current stage transform:
+`getSafeArea()` converts physical screen insets to your design coordinate space through the resolution pipeline:
 
 ```
-designInset = (physicalInset - stageOffset) / stageScale
+viewport_coord = physicalInset × pixelRatio / resolution
+design_coord   = (viewport_coord - stageOffset) / stageScale
 ```
 
 - **NO_BORDER**: Insets are larger because the cropped edges are accounted for
@@ -413,9 +414,10 @@ Use `calculateDesignSafeArea()` outside of `PixiView` for custom setups:
 
 ```tsx
 import { calculateDesignScale, calculateDesignSafeArea } from '@penabt/pixi-expo';
+import { PixelRatio } from 'react-native';
 
-const scale = calculateDesignScale(720, 1280, screenW, screenH, 'NO_BORDER');
-const safe = calculateDesignSafeArea(physicalInsets, scale, 720, 1280, screenW, screenH);
+const scale = calculateDesignScale(720, 1280, physicalW, physicalH, 'NO_BORDER');
+const safe = calculateDesignSafeArea(insets, scale, 720, 1280, PixelRatio.get());
 // safe.top, safe.bottom, safe.left, safe.right — all in 720x1280 space
 ```
 
@@ -425,7 +427,7 @@ const safe = calculateDesignSafeArea(physicalInsets, scale, 720, 1280, screenW,
 | --- | --- | --- |
 | `safeAreaInsets` | `SafeAreaInsets` | Physical insets `{ top, bottom, left, right }` in screen points |
 | `getSafeArea()` | `() => DesignSafeArea \| null` | Returns insets in design coordinates (ref handle method) |
-| `calculateDesignSafeArea()` | `(insets, scale, dw, dh, sw, sh) => DesignSafeArea` | Standalone conversion utility |
+| `calculateDesignSafeArea()` | `(insets, scale, dw, dh, pixelRatio) => DesignSafeArea` | Standalone conversion utility |
 
 ## Performance Tips
 

package/dist/index.d.mts

@@ -543,13 +543,6 @@ declare const loadExpoFont: LoaderParser<string>;
  * ```
  */
 declare function registerBitmapFont(xmlModuleId: number, pageModuleIds: number[]): string;
-/**
- * Expo Bitmap Font Loader
- *
- * A PixiJS LoadParser that handles local bitmap fonts registered via
- * registerBitmapFont(). Runs at High priority to intercept before
- * PixiJS's built-in loadBitmapFont (which can't handle module IDs).
- */
 declare const loadExpoBitmapFont: LoaderParser;
 
 /**
@@ -625,11 +618,15 @@ declare function createExpoBundle(assets: ExpoAssetsBundle['assets']): AssetsBun
 declare function createExpoManifest(manifest: ExpoAssetsManifest): AssetsManifest;
 
 /**
- * Design resolution scaling utilities.
+ * Design resolution utilities (Cocos2d-style).
+ *
+ * Instead of scaling the PixiJS stage, we set the renderer to operate in
+ * design coordinates and use PixiJS's `resolution` property to bridge
+ * the gap to physical pixels. This means:
  *
- * Provides Cocos2d-style design resolution support: define a fixed logical
- * size (e.g. 768×1024) and the library automatically scales the PixiJS stage
- * to fit the device screen.
+ * - Textures render at native device resolution (no GPU upscaling)
+ * - Game code works in a fixed coordinate space (e.g. 720×1280)
+ * - The stage has no scale transform — only a position offset for centering
  */
 /** How the design resolution maps to the physical screen. */
 type DesignScaleMode = 
@@ -657,25 +654,41 @@ interface DesignSafeArea {
     /** Inset from the right edge of the design coordinate space */
     right: number;
 }
-/** Result of the design-to-screen scale calculation. */
+/**
+ * Result of the design-to-screen scale calculation.
+ *
+ * The renderer is initialised at `viewportWidth × viewportHeight` with the
+ * returned `resolution`.  Physical backing = viewport × resolution = screen.
+ * The stage receives only a position offset (and stageScale for EXACT_FIT).
+ */
 interface DesignScaleResult {
-    /** Scale factor applied to stage X axis */
-    scaleX: number;
-    /** Scale factor applied to stage Y axis */
-    scaleY: number;
-    /** X offset for centering the stage (positive = letterbox, negative = crop) */
+    /** PixiJS resolution: physical pixels per logical (design) unit */
+    resolution: number;
+    /** Logical viewport width for the PixiJS renderer */
+    viewportWidth: number;
+    /** Logical viewport height for the PixiJS renderer */
+    viewportHeight: number;
+    /** Stage X position to centre the design area inside the viewport */
     offsetX: number;
-    /** Y offset for centering the stage */
+    /** Stage Y position to centre the design area inside the viewport */
     offsetY: number;
+    /** Stage scale X — 1.0 for SHOW_ALL / NO_BORDER, may differ for EXACT_FIT */
+    stageScaleX: number;
+    /** Stage scale Y — 1.0 for SHOW_ALL / NO_BORDER, may differ for EXACT_FIT */
+    stageScaleY: number;
 }
 /**
- * Calculate how to transform the PixiJS stage so that a fixed design
- * resolution maps onto the actual screen dimensions.
+ * Calculate how to set up the PixiJS renderer so that game code can work in
+ * a fixed design coordinate space while rendering at native device resolution.
  *
- * The renderer stays at the real screen size for full-quality rendering;
- * the returned values are applied to `app.stage.scale` and `app.stage.position`.
+ * @param designWidth  - Fixed design width  (e.g. 720)
+ * @param designHeight - Fixed design height (e.g. 1280)
+ * @param physicalWidth  - Physical screen width in pixels
+ * @param physicalHeight - Physical screen height in pixels
+ * @param scaleMode - How to handle aspect-ratio mismatch
+ * @returns Values to feed into PixiJS app.init() and stage transform
  */
-declare function calculateDesignScale(designWidth: number, designHeight: number, screenWidth: number, screenHeight: number, scaleMode: DesignScaleMode): DesignScaleResult;
+declare function calculateDesignScale(designWidth: number, designHeight: number, physicalWidth: number, physicalHeight: number, scaleMode: DesignScaleMode): DesignScaleResult;
 /**
  * Convert physical safe area insets (screen points) to design resolution coordinates.
  *
@@ -687,15 +700,14 @@ declare function calculateDesignScale(designWidth: number, designHeight: number,
  * In SHOW_ALL mode with letterboxing, insets may be zero if the bars
  * already cover the unsafe region.
  *
- * @param insets - Physical safe area insets in screen points
+ * @param insets - Physical safe area insets in logical screen points
  * @param scale - The current design scale result from calculateDesignScale()
  * @param designWidth - The design resolution width
  * @param designHeight - The design resolution height
- * @param screenWidth - The physical screen width in points
- * @param screenHeight - The physical screen height in points
+ * @param pixelRatio - Device pixel ratio (PixelRatio.get())
  * @returns Safe area insets in design resolution coordinates
  */
-declare function calculateDesignSafeArea(insets: SafeAreaInsets, scale: DesignScaleResult, designWidth: number, designHeight: number, screenWidth: number, screenHeight: number): DesignSafeArea;
+declare function calculateDesignSafeArea(insets: SafeAreaInsets, scale: DesignScaleResult, designWidth: number, designHeight: number, pixelRatio: number): DesignSafeArea;
 
 /**
  * Props for the PixiView component.

package/dist/index.d.ts

@@ -543,13 +543,6 @@ declare const loadExpoFont: LoaderParser<string>;
  * ```
  */
 declare function registerBitmapFont(xmlModuleId: number, pageModuleIds: number[]): string;
-/**
- * Expo Bitmap Font Loader
- *
- * A PixiJS LoadParser that handles local bitmap fonts registered via
- * registerBitmapFont(). Runs at High priority to intercept before
- * PixiJS's built-in loadBitmapFont (which can't handle module IDs).
- */
 declare const loadExpoBitmapFont: LoaderParser;
 
 /**
@@ -625,11 +618,15 @@ declare function createExpoBundle(assets: ExpoAssetsBundle['assets']): AssetsBun
 declare function createExpoManifest(manifest: ExpoAssetsManifest): AssetsManifest;
 
 /**
- * Design resolution scaling utilities.
+ * Design resolution utilities (Cocos2d-style).
+ *
+ * Instead of scaling the PixiJS stage, we set the renderer to operate in
+ * design coordinates and use PixiJS's `resolution` property to bridge
+ * the gap to physical pixels. This means:
  *
- * Provides Cocos2d-style design resolution support: define a fixed logical
- * size (e.g. 768×1024) and the library automatically scales the PixiJS stage
- * to fit the device screen.
+ * - Textures render at native device resolution (no GPU upscaling)
+ * - Game code works in a fixed coordinate space (e.g. 720×1280)
+ * - The stage has no scale transform — only a position offset for centering
  */
 /** How the design resolution maps to the physical screen. */
 type DesignScaleMode = 
@@ -657,25 +654,41 @@ interface DesignSafeArea {
     /** Inset from the right edge of the design coordinate space */
     right: number;
 }
-/** Result of the design-to-screen scale calculation. */
+/**
+ * Result of the design-to-screen scale calculation.
+ *
+ * The renderer is initialised at `viewportWidth × viewportHeight` with the
+ * returned `resolution`.  Physical backing = viewport × resolution = screen.
+ * The stage receives only a position offset (and stageScale for EXACT_FIT).
+ */
 interface DesignScaleResult {
-    /** Scale factor applied to stage X axis */
-    scaleX: number;
-    /** Scale factor applied to stage Y axis */
-    scaleY: number;
-    /** X offset for centering the stage (positive = letterbox, negative = crop) */
+    /** PixiJS resolution: physical pixels per logical (design) unit */
+    resolution: number;
+    /** Logical viewport width for the PixiJS renderer */
+    viewportWidth: number;
+    /** Logical viewport height for the PixiJS renderer */
+    viewportHeight: number;
+    /** Stage X position to centre the design area inside the viewport */
     offsetX: number;
-    /** Y offset for centering the stage */
+    /** Stage Y position to centre the design area inside the viewport */
     offsetY: number;
+    /** Stage scale X — 1.0 for SHOW_ALL / NO_BORDER, may differ for EXACT_FIT */
+    stageScaleX: number;
+    /** Stage scale Y — 1.0 for SHOW_ALL / NO_BORDER, may differ for EXACT_FIT */
+    stageScaleY: number;
 }
 /**
- * Calculate how to transform the PixiJS stage so that a fixed design
- * resolution maps onto the actual screen dimensions.
+ * Calculate how to set up the PixiJS renderer so that game code can work in
+ * a fixed design coordinate space while rendering at native device resolution.
  *
- * The renderer stays at the real screen size for full-quality rendering;
- * the returned values are applied to `app.stage.scale` and `app.stage.position`.
+ * @param designWidth  - Fixed design width  (e.g. 720)
+ * @param designHeight - Fixed design height (e.g. 1280)
+ * @param physicalWidth  - Physical screen width in pixels
+ * @param physicalHeight - Physical screen height in pixels
+ * @param scaleMode - How to handle aspect-ratio mismatch
+ * @returns Values to feed into PixiJS app.init() and stage transform
  */
-declare function calculateDesignScale(designWidth: number, designHeight: number, screenWidth: number, screenHeight: number, scaleMode: DesignScaleMode): DesignScaleResult;
+declare function calculateDesignScale(designWidth: number, designHeight: number, physicalWidth: number, physicalHeight: number, scaleMode: DesignScaleMode): DesignScaleResult;
 /**
  * Convert physical safe area insets (screen points) to design resolution coordinates.
  *
@@ -687,15 +700,14 @@ declare function calculateDesignScale(designWidth: number, designHeight: number,
  * In SHOW_ALL mode with letterboxing, insets may be zero if the bars
  * already cover the unsafe region.
  *
- * @param insets - Physical safe area insets in screen points
+ * @param insets - Physical safe area insets in logical screen points
  * @param scale - The current design scale result from calculateDesignScale()
  * @param designWidth - The design resolution width
  * @param designHeight - The design resolution height
- * @param screenWidth - The physical screen width in points
- * @param screenHeight - The physical screen height in points
+ * @param pixelRatio - Device pixel ratio (PixelRatio.get())
  * @returns Safe area insets in design resolution coordinates
  */
-declare function calculateDesignSafeArea(insets: SafeAreaInsets, scale: DesignScaleResult, designWidth: number, designHeight: number, screenWidth: number, screenHeight: number): DesignSafeArea;
+declare function calculateDesignSafeArea(insets: SafeAreaInsets, scale: DesignScaleResult, designWidth: number, designHeight: number, pixelRatio: number): DesignSafeArea;
 
 /**
  * Props for the PixiView component.