@gamedevland/engine 0.0.8 → 0.0.9

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.0.9 — 2026-11-05
+
+- Add opt-in `screen.dpr: 'native'` to target the viewport's physical pixels.
+- Add `screen.render.maxCanvasPixels` to limit the backing canvas area.
+- Apply size and resolution in one renderer resize. Existing numeric and `'auto'` DPR defaults stay the same.
+
 ## 0.0.8 — 2026-11-04
 
 - Publish the SDK source and package under MIT with public repository metadata.
@@ -14,4 +20,21 @@
 
 ## 0.0.7
 
+- Expose runtime activity and native pointer metadata.
 - Dispose spawned prefab logical children idempotently and release their registry entries.
+
+## 0.0.5
+
+- Prepare automated npm publishing.
+
+## 0.0.4
+
+- Update package homepage and issue-tracker metadata.
+
+## 0.0.3
+
+- Update repository metadata.
+
+## 0.0.2
+
+- Add drag-end reasons and renderer-independent local node bounds.

package/README.md

@@ -10,6 +10,12 @@ The npm package intentionally ships a compact public distribution:
 
 Source files are available in [the SDK repository](https://github.com/gamedevland/sdk/tree/main/packages/engine/src); the npm archive contains the compiled distribution.
 
+## Changelog
+
+**0.0.9** adds opt-in viewport-native rendering and a configurable canvas pixel
+budget. Existing DPR defaults stay the same.
+[Full engine changelog](https://github.com/gamedevland/sdk/blob/main/packages/engine/CHANGELOG.md).
+
 ## Install
 
 ```bash
@@ -44,6 +50,20 @@ For `dragend` input events, `InputEventBase.dragEndReason` distinguishes a norma
 
 Layout nodes expose `getLocalBounds()` for renderer-independent local geometry queries.
 
+## Screen resolution
+
+Logical landscape and portrait profiles define the game's coordinate system.
+Set `system.screen.dpr: 'native'` to scale the backing canvas to the physical
+pixels of the viewport, including when the game is embedded in an iframe.
+For this mode, `maxDpr` caps the display density relative to CSS pixels.
+Existing numeric `dpr` values and `'auto'` still multiply the logical canvas size.
+
+Set `system.screen.render.maxCanvasPixels` to a positive integer to limit the
+backing canvas area. The engine scales both axes together and preserves the
+logical layout and pointer coordinates. Extremely small budgets may be exceeded
+when required to keep both axes at least one pixel. This option caps the main
+canvas independently of the optional `render.scaleFactor` pass.
+
 ## TypeScript
 
 ### Platform packaging and boot (0.0.8)

package/dist/sdk.d.ts

@@ -2216,16 +2216,20 @@ export interface ScreenProfile {
 }
 export interface ScreenRenderConfig {
 	scaleFactor?: number;
+	/** Maximum backing canvas area in physical pixels. Independent of scaleFactor. */
+	maxCanvasPixels?: number;
 }
 /**
  * Main configuration for screen behavior.
  * - `land`/`port`: virtual profiles for each orientation.
- * - `dpr`: renderer resolution; 'auto' or a fixed number. Default is 1.
+ * - `dpr`: fixed renderer resolution, 'auto' for browser DPR in virtual units,
+ *   or 'native' to target physical viewport pixels. Default is 1.
+ * - `maxDpr`: caps the browser DPR in 'auto' and 'native' modes.
  */
 export interface ScreenConfig {
 	land: ScreenProfile;
 	port: ScreenProfile;
-	dpr?: "auto" | number;
+	dpr?: "auto" | "native" | number;
 	maxDpr?: number;
 	render?: ScreenRenderConfig;
 }
@@ -2246,7 +2250,7 @@ export interface VirtualSize {
 export interface ScreenStateSnapshot {
 	orientation: Orientation;
 	viewport: ViewportSize;
-	/** Internal canvas size (the <canvas width/height> attributes), px. */
+	/** Logical canvas size, before renderer resolution is applied. */
 	canvas: {
 		width: number;
 		height: number;
@@ -2319,8 +2323,7 @@ export declare class ScreenManager {
 	private applySnapshot;
 	/**
 	 * Applies the current snapshot to the PIXI renderer and stage:
-	 * - Sets device pixel ratio (renderer.resolution)
-	 * - Resizes the internal canvas to the computed virtual size
+	 * - Resizes the renderer using the virtual size and backing canvas resolution
 	 * - Does NOT scale the stage: scaling is expected to be done via CSS size of the canvas
 	 */
 	private applyToStage;
@@ -2331,12 +2334,7 @@ export declare class ScreenManager {
 	onChange(handler: (snapshot: ScreenStateSnapshot) => void): () => void;
 	/** Notifies subscribers with a cloned snapshot to prevent outside mutation. */
 	private notifyChange;
-	/**
-	 * Resolves the device pixel ratio to use for the renderer's resolution.
-	 * - `dpr: 'auto'` uses the browser DPR (retina-aware).
-	 * - numeric `dpr` uses the provided fixed value.
-	 * - missing/invalid values fall back to 1.
-	 */
+	private resolveResolution;
 	private resolveDpr;
 	/**
 	 * Returns the center point of the virtual canvas in virtual coordinates.

package/dist/sdk.js

@@ -37371,7 +37371,10 @@ var eF = class {
   changeHandlers = /* @__PURE__ */ new Set();
   requestRender;
   constructor(e, i) {
-    this.app = e, this.config = i, this.scaler = new WF(i);
+    this.app = e, this.config = i;
+    const s = i.render?.maxCanvasPixels;
+    if (s !== void 0 && (!Number.isSafeInteger(s) || s < 1)) throw new RangeError("ScreenManager: render.maxCanvasPixels must be a positive safe integer");
+    this.scaler = new WF(i);
   }
   async init() {
     const e = await this.awaitInitialSnapshot();
@@ -37387,14 +37390,14 @@ var eF = class {
     e && this.applySnapshot(e);
   }
   applySnapshot(e) {
-    const i = this.hasChanged(this.prev, e);
-    this.snapshot = e, i && (this.applyToStage(), this.prev = { ...e }, this.notifyChange());
+    const i = this.resolveResolution(e), s = this.hasChanged(this.prev, e) || this.app.renderer.resolution !== i;
+    this.snapshot = e, s && (this.applyToStage(i), this.prev = { ...e }, this.notifyChange());
   }
-  applyToStage() {
-    const { canvas: e, viewport: i } = this.snapshot, s = this.resolveDpr();
-    this.app.renderer.resolution = s, this.app.renderer.resize(e.width, e.height);
+  applyToStage(e) {
+    const { canvas: i, viewport: s } = this.snapshot;
+    this.app.renderer.resize(i.width, i.height, e);
     const r = this.app.canvas;
-    r && r.style && (r.style.width = `${i.width}px`, r.style.height = `${i.height}px`), this.app.stage.scale.set(1), this.app.stage.pivot.set(0, 0), this.app.stage.position.set(0, 0), this.requestRender?.();
+    r && r.style && (r.style.width = `${s.width}px`, r.style.height = `${s.height}px`), this.app.stage.scale.set(1), this.app.stage.pivot.set(0, 0), this.app.stage.position.set(0, 0), this.requestRender?.();
   }
   onChange(e) {
     return this.changeHandlers.add(e), () => this.changeHandlers.delete(e);
@@ -37411,14 +37414,25 @@ var eF = class {
     } catch {
     }
   }
-  resolveDpr() {
-    if (this.config.dpr === "auto") {
-      const e = window.devicePixelRatio;
-      if (typeof e != "number" || !Number.isFinite(e) || e <= 0) return 1;
-      const i = this.config.maxDpr;
-      return typeof i == "number" && Number.isFinite(i) && i > 0 ? Math.min(e, i) : e;
-    }
-    return typeof this.config.dpr == "number" && Number.isFinite(this.config.dpr) && this.config.dpr > 0 ? this.config.dpr : 1;
+  resolveResolution(e) {
+    const i = this.config.dpr;
+    let s = this.resolveDpr(i);
+    i === "native" && (s *= e.scale);
+    const r = this.config.render?.maxCanvasPixels;
+    if (r === void 0) return s;
+    const { width: n, height: a } = e.canvas;
+    if (Math.round(n * s) * Math.round(a * s) <= r) return s;
+    const o = 0.5 / Math.min(n, a), l = o * (1 + Number.EPSILON), h = Math.max(l, Math.min(s, Math.sqrt(r / (n * a))));
+    return Math.round(n * h) * Math.round(a * h) <= r ? h : Math.max(l, h - o);
+  }
+  resolveDpr(e) {
+    if (e === "auto" || e === "native") {
+      const i = window.devicePixelRatio;
+      if (!Number.isFinite(i) || i <= 0) return 1;
+      const s = this.config.maxDpr;
+      return typeof s == "number" && Number.isFinite(s) && s > 0 ? Math.min(i, s) : i;
+    }
+    return typeof e == "number" && Number.isFinite(e) && e > 0 ? e : 1;
   }
   get center() {
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gamedevland/engine",
-  "version": "0.0.8",
+  "version": "0.0.9",
   "type": "module",
   "description": "HTML5 game engine SDK for AI-assisted web game development.",
   "license": "MIT",
@@ -115,6 +115,7 @@
     }
   },
   "scripts": {
+    "test:screen": "node scripts/verify-screen.mjs",
     "test:resource-cleanup": "node scripts/verify-resource-cleanup.mjs",
     "clean": "rimraf dist *.tsbuildinfo",
     "typecheck": "tsc --noEmit",