@gamedevland/engine 0.0.7 → 0.0.9

package/CHANGELOG.md

@@ -0,0 +1,40 @@
+# 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.
+- Preserve the consumer Vite platform define in the compiled runtime.
+- Signal loading completion after initial scene entry; support explicit completion for loading scenes.
+- Add `AssetManager.loadRequiredBundle()` for mandatory bundle validation.
+- Route unpressed mouse hover through the public input events.
+- Release audio listeners and owned displacement filters on terminal lifecycle paths.
+- Make particle component cleanup tolerate earlier scene subtree disposal.
+- Keep GameDistribution video pause/resume under engine ownership and stop the loading watchdog
+  after a video starts; ignore stale request continuations.
+
+## 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,8 +50,48 @@ 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)
+
+The packaged runtime preserves `import.meta.env.VITE_PLATFORM` for the consuming
+game's Vite build. Loading completion is reported after the initial scene and its
+assets are ready. Consumers remain responsible for gameplay start/stop signals.
+
+For an initial loading scene, set `system.boot.autoLoadingFinished: false`.
+Call `engine.platform.loadingFinished()` after the gameplay scene and all required
+assets are ready. The default remains automatic completion after the initial scene.
+
+`assets.loadRequiredBundle(name)` loads with the usual cache/retries and rejects
+if any resource remains unavailable. Use it for mandatory loading-screen bundles;
+the existing `loadBundle(name)` behavior is unchanged.
+
+`particles.hasEmitter(handle)` reports whether scene cleanup has already released
+a handle. `ParticleEmitterComponent` tolerates prior subtree cleanup on disable/detach
+and recreates a removed emitter when enabled again; invalid direct manager calls still fail fast.
+
+### Resource cleanup (0.0.8)
+
+Audio handles release their end/stop/playerror subscriptions on every terminal path,
+including explicit stop, channel stop, source unload and disposal. Loop boundaries
+and pause keep subscriptions until playback actually terminates.
+Displacement components destroy their owned filters on disable/detach while keeping
+asset-owned textures and shared shader programs alive. No consumer API changes are required.
+
 ### Runtime activity and pointer metadata (0.0.6)
 
 Version 0.0.7 makes spawned prefab disposal idempotent and removes the logical

package/dist/sdk.d.ts

@@ -169,6 +169,8 @@ export declare class AssetManager {
 	 * @param name Bundle name.
 	 */
 	loadBundle(name: string): Promise<void>;
+	/** Loads a bundle and rejects if any required resource failed, including after loader retries. */
+	loadRequiredBundle(name: string): Promise<void>;
 	/**
 	 * Core loading routine that resolves descriptors and loads them with bounded concurrency.
 	 * Uses an internal queue and a dynamic pool of running promises.
@@ -1507,6 +1509,8 @@ export declare class ParticlesManager {
 	destroyAll(): void;
 	destroyInSubtree(rootView: PixiContainer): void;
 	getActiveEmitterCount(): number;
+	/** Whether a handle still belongs to this manager, including after scene subtree cleanup. */
+	hasEmitter(handle: ParticleHandle): boolean;
 	tick(dt: number): void;
 	private createHandle;
 	private getRequiredEmitter;
@@ -1995,6 +1999,7 @@ export declare class InputManager {
 	private onPointerDown;
 	/**
 	 * Native pointermove handler: updates pointer state and emits dragstart/drag/pointermove depending on thresholds.
+	 * Unpressed mouse movement emits hover pointermove without allocating tracked pointer state.
 	 * Drag recognition starts when movement exceeds `dragStartDistance`.
 	 */
 	private onPointerMove;
@@ -2211,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;
 }
@@ -2241,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;
@@ -2314,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;
@@ -2326,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.
@@ -3913,6 +3916,8 @@ export interface GameConfig {
 		};
 		/** Deterministic engine boot preload plan for JSON configs. */
 		boot?: {
+			/** Defaults to true. Set false for a loading scene; signal platform.loadingFinished() when gameplay is ready. */
+			autoLoadingFinished?: boolean;
 			configs?: {
 				/** Bundle names preloaded into ConfigStore once at engine start. */
 				engineStartBundles?: readonly string[];