@waica/engine 0.17.0 → 0.19.0

package/dist/game.d.ts

@@ -1,7 +1,10 @@
 import * as THREE from 'three';
+import { AssetLoader } from './assets/asset-loader.js';
+import type { TextureBackend } from './assets/texture-backend.js';
 import type { AudioBackend } from './audio/backend.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { type SceneCameraJson } from './camera.js';
+import { CameraEffects } from './camera-effects.js';
 import type { Component } from './component.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
@@ -38,6 +41,13 @@ export interface GameOptions {
      * first unlock (CA-6), never eagerly here.
      */
     audio?: AudioBackend;
+    /**
+     * Replaces the real `THREE.TextureLoader` implementation behind
+     * `game.assets` (ADR 0013's seam, applied to textures — ADR 0019), mainly
+     * for a project's own tests: `happy-dom` decodes no images. Defaults to
+     * the real backend either way; `game.assets` always exists.
+     */
+    textures?: TextureBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
@@ -68,6 +78,17 @@ export declare class Game {
     readonly ui: GameUi;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     readonly audio: AudioSubsystem;
+    /**
+     * The texture cache: keep-all for the Game's life, `preload`, `status`
+     * and the Assets Ready promise `ready()`. Session-scoped by construction
+     * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
+     */
+    readonly assets: AssetLoader;
+    /**
+     * Shake, Fade and Flash, beside `camera` and never written into it
+     * (ADR 0020). A Fade survives `unloadScene()`; a Shake or Flash does not.
+     */
+    readonly cameraEffects: CameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     readonly time: GameTime;
     /** Registry retained by loadScene for runtime prefab spawning. */

package/dist/game.js

@@ -1,8 +1,10 @@
 import * as THREE from 'three';
 import { gameViewport } from './anchored-pieces.js';
+import { AssetLoader } from './assets/asset-loader.js';
 import { AudioSubsystem } from './audio/audio-subsystem.js';
 import { dispatchCollisions as dispatchHitboxCollisions } from './collision-dispatch.js';
 import { isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera, } from './camera.js';
+import { advanceCameraEffects, CameraEffects, layoutCameraEffects } from './camera-effects.js';
 import { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 import { Entity } from './entity.js';
 import { Emitter } from './events.js';
@@ -35,6 +37,17 @@ export class Game {
     ui;
     /** The audio mixer: channels, master, playback. See ADR 0012, ADR 0013. */
     audio;
+    /**
+     * The texture cache: keep-all for the Game's life, `preload`, `status`
+     * and the Assets Ready promise `ready()`. Session-scoped by construction
+     * (ADR 0011): `unloadScene()` never touches it. See ADR 0019.
+     */
+    assets;
+    /**
+     * Shake, Fade and Flash, beside `camera` and never written into it
+     * (ADR 0020). A Fade survives `unloadScene()`; a Shake or Flash does not.
+     */
+    cameraEffects;
     /** Simulated scheduling: `after`, `every`, `tween`, `now`. See ADR 0017. */
     time = new GameTime();
     /** Registry retained by loadScene for runtime prefab spawning. */
@@ -103,6 +116,17 @@ export class Game {
             // music bed needs across a scene swap.
             resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
         });
+        this.assets = new AssetLoader({
+            backend: options.textures,
+            // Same late lookup as audio's: preload() resolves through whatever
+            // catalog is registered at call time, which outlives every scene.
+            resolveAsset: (uri) => this.sceneCatalog?.registry.resolveAsset?.(uri) ?? uri,
+        });
+        this.cameraEffects = new CameraEffects({
+            host: () => canvas.parentElement ?? document.body,
+            // One screen pixel in world units: the shake snaps to it (never the base).
+            pixel: () => (this.resolution ? this.viewHeight / this.resolution.height : null),
+        });
         this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
         this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
         this.scene.background = new THREE.Color(background);
@@ -160,6 +184,7 @@ export class Game {
         // Scene-scoped timers/tweens die here too (ADR 0017): before entities are
         // destroyed below, so an owner's own destroy() cancellation is a no-op.
         this.time.cancelSceneScoped();
+        this.cameraEffects.unloadScene();
         // An explicit unload means "no scene": a swap queued earlier this frame
         // would otherwise flush next frame and resurrect one.
         this.pendingSceneLoad = null;
@@ -310,6 +335,7 @@ export class Game {
                     },
                     loadScene: (name) => this.loadSceneByName(name),
                     availableScenes: () => this.availableScenes,
+                    assets: () => this.assets.status,
                 });
                 activation.register(this.runtimeBridge);
                 this.audio.setSilenced(true);
@@ -352,11 +378,15 @@ export class Game {
         this.resizeObserver.disconnect();
         this.ui.dispose();
         this.audio.dispose();
+        this.cameraEffects.dispose();
         // Cancels both scopes, including session-scoped work no entity owns
         // (entity.destroy() below only ever reaches owned work) — ADR 0017.
         this.time.cancelAll();
         for (const entity of [...this.entities])
             entity.destroy();
+        // After the entities: their clones go with the cascade above, the
+        // cached bases go here, exactly once (ADR 0019).
+        this.assets.dispose();
         this.renderer.dispose();
     }
     /**
@@ -461,6 +491,7 @@ export class Game {
         }
         this.dispatchCollisions();
         this.updateSceneCamera(SIMULATION_STEP);
+        advanceCameraEffects(this.cameraEffects);
         this.finishStep();
     }
     /** Closes a step (real or the non-simulating stand-in): host callbacks, then the input frame. */
@@ -518,15 +549,28 @@ export class Game {
         if (this.renderSort === 'y')
             this.applyYSort();
         this.ui.setActive(this.simulate);
-        anchoredPiecesOf(this.ui).place();
-        if (this.resolution) {
-            // Letterbox bars: clear the whole canvas, then render inside the scissor.
-            this.renderer.setScissorTest(false);
-            this.renderer.setClearColor(0x000000, 1);
-            this.renderer.clear(true, false, false);
-            this.renderer.setScissorTest(true);
+        // The shake offset exists only while drawing (ADR 0020): Anchored Pieces
+        // and the render see the drawn center, then the base comes back exactly,
+        // so follow smoothing never starts from its own jitter.
+        const { x, y } = this.camera.position;
+        const { shake } = this.cameraEffects.state;
+        this.camera.position.x = x + shake.x;
+        this.camera.position.y = y + shake.y;
+        try {
+            anchoredPiecesOf(this.ui).place();
+            if (this.resolution) {
+                // Letterbox bars: clear the whole canvas, then render inside the scissor.
+                this.renderer.setScissorTest(false);
+                this.renderer.setClearColor(0x000000, 1);
+                this.renderer.clear(true, false, false);
+                this.renderer.setScissorTest(true);
+            }
+            this.renderer.render(this.scene, this.camera);
+        }
+        finally {
+            this.camera.position.x = x;
+            this.camera.position.y = y;
         }
-        this.renderer.render(this.scene, this.camera);
     }
     componentUpdateSchedule(entity) {
         const components = [...entity.components];
@@ -638,5 +682,6 @@ export class Game {
         this.camera.top = halfH;
         this.camera.bottom = -halfH;
         this.camera.updateProjectionMatrix();
+        layoutCameraEffects(this.cameraEffects, gameViewport(w, h, this.resolution));
     }
 }

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { Game } from './game.js';
 export type { GameOptions, GameResolution, SceneCatalog, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export { AssetLoader } from './assets/asset-loader.js';
+export type { AssetStatus } from './assets/asset-loader.js';
+export type { TextureBackend } from './assets/texture-backend.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export type { AudioSubsystemOptions } from './audio/audio-subsystem.js';
 export type { AudioBackend, AudioResource, BackendPlayHandle, BackendPlayOptions } from './audio/backend.js';
@@ -14,6 +17,8 @@ export { spritePlacement } from './sprite-placement.js';
 export type { SpritePlacement, SpritePlacementInput } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+export { CameraEffects } from './camera-effects.js';
+export type { CameraEffectColor, CameraEffectHandle, CameraEffectsOptions, CameraEffectsState, FadeOptions, FlashOptions, ShakeOptions, } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
 export type { EasingName, TimerHandle, TimerOptions, TweenOptions } from './game-time.js';
 export type { SceneCameraJson, CameraLimitsJson, CameraVelocity, CameraVelocityProvider, ResolvedSceneCamera, } from './camera.js';
@@ -32,7 +37,7 @@ export type { PointerCamera, PointerDeps, PointerPick, PointerResolution } from
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export type { RuntimeBridge, RuntimeBridgeActivation, RuntimeControlRequest, RuntimeControlResult, RuntimeMetadata, RuntimeMode, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';
-export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.js';
+export type { ProjectedValue, ProjectionIssue, ProjectionMarker, ProjectionMarkerKind, RuntimeComponentSnapshot, RuntimeEntitySnapshot, RuntimeSnapshot, RuntimeSnapshotAudio, RuntimeSnapshotCamera, RuntimeSnapshotFilters, RuntimeSnapshotTime, RuntimeSnapshotUi, RuntimeTransformSnapshot, } from './runtime-inspection.js';
 export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
 export { Stats } from './stats.js';
 export type { StatValue } from './stats.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { Game } from './game.js';
+export { AssetLoader } from './assets/asset-loader.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isYSortParticipant, ySortZ } from './render-sort.js';
@@ -6,6 +7,7 @@ export { projectIsometric, screenInputToLogical, unprojectIsometric } from './pr
 export { spritePlacement } from './sprite-placement.js';
 export { CAMERA_DEFAULTS, isCameraVelocityProvider, resolveSceneCamera, stepSceneCamera } from './camera.js';
 export { SIMULATION_STEP, SIMULATION_TIME_EPSILON } from './fixed-step.js';
+export { CameraEffects } from './camera-effects.js';
 export { GameTime, advanceGameTime } from './game-time.js';
 export { Entity } from './entity.js';
 export { Component } from './component.js';

package/dist/runtime-bridge.d.ts

@@ -1,3 +1,4 @@
+import type { AssetStatus } from './assets/asset-loader.js';
 import type { RuntimeSnapshot, RuntimeSnapshotFilters } from './runtime-inspection.js';
 export declare const RUNTIME_BRIDGE_PROTOCOL_VERSION: 1;
 export declare const RUNTIME_BRIDGE_SYMBOL: unique symbol;
@@ -10,9 +11,15 @@ export type RuntimeMode = 'paused' | 'real-time';
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
- * advances whole 1/60 s Simulation Steps and takes no `dt`.
+ * advances whole 1/60 s Simulation Steps and takes no `dt`. `assets`
+ * (ADR 0019) announces that every metadata carries `assets: { pending,
+ * loaded, failed }` from `game.assets.status`, so a Run Session can wait
+ * for Assets Ready (`pending === 0`) at readiness, after a `scene`
+ * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
+ * announces that every snapshot carries `camera: { shake, fade, flash }`
+ * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -20,6 +27,8 @@ export interface RuntimeMetadata {
     frame: number;
     simulationTime: number;
     capabilities: readonly string[];
+    /** `game.assets.status` at the moment of the read — reading it never advances `frame`. */
+    assets: AssetStatus;
 }
 export type RuntimeControlRequest = {
     operation: 'press' | 'hold' | 'release';
@@ -81,6 +90,8 @@ export interface RuntimeBridgeHost {
     /** Resolves `name` through the registered catalog and loads it. */
     loadScene(name: string): boolean;
     availableScenes(): string[];
+    /** A fresh `game.assets.status`. */
+    assets(): AssetStatus;
 }
 export declare class EngineRuntimeBridge implements RuntimeBridge {
     readonly surface: HTMLCanvasElement;

package/dist/runtime-bridge.js

@@ -10,9 +10,21 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * gating on capabilities check for (review finding #4) — protocol 1 alone
  * doesn't distinguish an engine that silently no-ops an unknown operation
  * from one that runs it. `fixed-step` (ADR 0014) announces that `step`
- * advances whole 1/60 s Simulation Steps and takes no `dt`.
+ * advances whole 1/60 s Simulation Steps and takes no `dt`. `assets`
+ * (ADR 0019) announces that every metadata carries `assets: { pending,
+ * loaded, failed }` from `game.assets.status`, so a Run Session can wait
+ * for Assets Ready (`pending === 0`) at readiness, after a `scene`
+ * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
+ * announces that every snapshot carries `camera: { shake, fade, flash }`
+ * from `game.cameraEffects`; the `scene` operation stays a hard cut.
  */
-export const RUNTIME_BRIDGE_CAPABILITIES = ['click', 'scene', 'fixed-step'];
+export const RUNTIME_BRIDGE_CAPABILITIES = [
+    'click',
+    'scene',
+    'fixed-step',
+    'assets',
+    'camera-effects',
+];
 export class RuntimeBridgeOperationError extends Error {
     code;
     availableActions;
@@ -61,6 +73,7 @@ export class EngineRuntimeBridge {
             // Derived, never summed: 60 steps are exactly 1 s, with no float drift.
             simulationTime: this.frame * SIMULATION_STEP,
             capabilities: RUNTIME_BRIDGE_CAPABILITIES,
+            assets: this.host.assets(),
         };
     }
     inspect(filters = {}) {

package/dist/runtime-inspection.d.ts

@@ -1,4 +1,5 @@
 import type { AudioChannelState, LiveSoundInfo } from './audio/types.js';
+import type { CameraEffectsState } from './camera-effects.js';
 import type { Game } from './game.js';
 import type { RuntimeMetadata } from './runtime-bridge.js';
 import type { StatValue } from './stats.js';
@@ -106,6 +107,13 @@ export interface RuntimeSnapshotUi {
         values: Record<string, StatValue | ProjectionMarker> | ProjectionMarker;
     }>;
 }
+/**
+ * `game.cameraEffects.state` (issue #74 CA-17), beside `time` and `ui`: the
+ * shake offset (world units, added to the camera only while drawing) and
+ * the Fade and Flash layers' `#rrggbb` color and opacity, all from the
+ * last completed Simulation Step. Emitted unconditionally — never filtered.
+ */
+export type RuntimeSnapshotCamera = CameraEffectsState;
 export interface RuntimeSnapshot extends RuntimeMetadata {
     stats: Record<string, StatValue>;
     /** The live scene's name (its catalog key), or null with no scene loaded. */
@@ -115,6 +123,7 @@ export interface RuntimeSnapshot extends RuntimeMetadata {
     audio: RuntimeSnapshotAudio;
     time: RuntimeSnapshotTime;
     ui: RuntimeSnapshotUi;
+    camera: RuntimeSnapshotCamera;
 }
 export declare const RUNTIME_PROJECTION_LIMITS: {
     readonly depth: 5;

package/dist/runtime-inspection.js

@@ -272,6 +272,7 @@ export class RuntimeInspector {
             audio: this.audioSnapshot(),
             time: this.timeSnapshot(),
             ui: this.uiSnapshot(projectionIssues),
+            camera: this.game.cameraEffects.state,
         });
     }
     audioSnapshot() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waica/engine",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "description": "Waica game engine core — archetype-driven, web-first, 2D & 3D",
   "license": "MIT",
   "type": "module",