@waica/engine 0.29.0 → 0.30.0

package/README.md

@@ -25,6 +25,13 @@ A `Game` draws through three's `WebGPURenderer` (ADR 0025): WebGPU when the brow
 - **Tests under happy-dom.** happy-dom has no GPU: a project test that builds a `Game` replaces `WebGPURenderer` from `three/webgpu` with a fake (it previously replaced `WebGLRenderer` from `three`), whose `init()` resolves.
 - **Run Sessions.** A Run Session waits for the Render Backend before it reports ready, steps or screenshots, and its snapshots carry `backend`. A renderer that cannot initialize ends `start_project` with a runtime error that names the failure.
 
+## Migrating to 0.29.1: checkpoint banners on the walls
+
+A fix release for the third-person demo, whose checkpoint banners stood free in the yard: KayKit's banner is single-sided and modelled to hang on a wall, so it floated and vanished from behind. Every existing scene file loads as it did; what changes:
+
+- **`Checkpoint.spawnOffset`** (new, a `vector3`, default `[0, 0, 0]`: unchanged) moves where the player respawns from the checkpoint's position. In a 3D scene it is in the entity's local frame, turned and scaled with it like a `Collider`'s `offset`; in 2D it is in world units, like a `Hitbox`'s or a `Solid`'s offset, whatever the node's scale or rotation. `validate_project` reports a `spawnOffset` that is not three finite numbers as `invalid-checkpoint-param`.
+- **`@waica/archetype-third-person`'s `objects/checkpoint` prefab is a wall banner.** Its origin goes 0.35 inside a wall's inner face (the cloth's back then lies flush on it), turned so its local +z faces away from the wall. Its sensor `Collider` moves to `offset: [0, 1.5, 1.35]` (same 2 × 3 × 2 size) and its `Checkpoint` gets `spawnOffset: [0, 0, 1.35]`, so the sensor starts at the wall's face and the player respawns standing on the floor 1 in front of it. A project created earlier keeps its own `src/objects/checkpoint.object.json` and behaves as before; one that takes the new prefab should hang its checkpoints on walls. The demo's checkpoints are now `Checkpoint West` at `(-9.85, 0, 4)` turned `[0, 90, 0]` and `Checkpoint East` at `(9.85, 0, 4)` turned `[0, -90, 0]`.
+
 ## Migrating to 0.29.0: third-person archetype
 
 The release adds `@waica/archetype-third-person` (issue #181, ADR 0031) and the engine and behavior pieces it needs. Every existing scene file loads as it did; what changes:
@@ -480,3 +487,19 @@ game.assets.status // { pending, loaded, failed } — a fresh object on every re
 - **Models.** `game.assets.model(uri)` is the glTF half of the same cache (see [3D scenes](#3d-scenes)): one load per URL, `status` and `ready()` count it, `preload` routes `.glb` and `.gltf` to it.
 - **`GameOptions.textures`.** Replaces the real `THREE.TextureLoader` backend for that Game (ADR 0013's seam, applied to textures): `happy-dom` decodes no images, so a project's own tests inject a backend that resolves at once. The Runtime Bridge reports `assets` in its metadata under the `'assets'` capability, and a Run Session waits for `pending === 0` at readiness, after a `scene` operation and before every screenshot.
 
+## The host platform: quit, fullscreen and achievements
+
+Every `Game` talks to the host it runs in through a replaceable platform seam (ADR 0032): the browser, or the desktop shell that `waica export desktop` packages the game into. A game asks the same questions on both and gets an honest answer:
+
+```ts
+if (game.canQuit) menu.add('Quit', () => game.quit())
+await game.setFullscreen(!game.isFullscreen())
+game.achievements.unlock('first-kill')
+game.achievements.setStat('kills', 3)
+const kills = await game.achievements.getStat('kills') // number | undefined
+```
+
+- **`game.canQuit` and `game.quit()`.** `canQuit` is `true` in the desktop shell, where `quit()` closes the app, and `false` on the web, where a page cannot close itself: there `quit()` does nothing (the loop keeps running and nothing throws), so a game hides its Quit button instead.
+- **`game.setFullscreen(on)` and `game.isFullscreen()`.** On the web, the browser's Fullscreen API: `setFullscreen(true)` requests it for the page and `setFullscreen(false)` leaves it; `isFullscreen()` is `document.fullscreenElement !== null`. A browser refuses a request made without a user gesture: the promise still resolves, never rejects, and `isFullscreen()` stays `false`, so call it from a key or click handler. In the desktop shell both go to the window, and F11 and Alt+Enter toggle it too. There `isFullscreen()` is a synchronous round trip to the main process that blocks the page until it answers, so read it when a key is pressed or a menu opens, not in every `update`.
+- **`game.achievements`.** Store-agnostic: `unlock(id)`, `setStat(id, value)`, `getStat(id): Promise<number | undefined>` and `available`. On the web, and in a desktop build exported without Steam, `available` is `false`, `unlock` and `setStat` do nothing and `getStat` resolves `undefined`. In a desktop build with Steam (`game.json`'s `desktop.steam`) and a running Steam client, `available` is `true` and each call reaches Steamworks; declare every id in `desktop.steam.achievements` or `desktop.steam.stats`.
+- **`GameOptions.platform`.** Absent, the Game picks the desktop backend when `window.waicaDesktop` (the shell's preload bridge, `DesktopBridge`) exists, and `WebPlatformBackend` otherwise. A `window.waicaDesktop` of another shape (an engine and a shell whose versions disagree) falls back to the web backend with a console warning that names what it lacks. A project's own tests pass a fake `PlatformBackend` to observe every call. `new WebPlatformBackend(() => element)` fullscreens that element instead of the whole page: the editor's Play passes its Viewport's surface.

package/dist/game.d.ts

@@ -16,6 +16,7 @@ import { GameTime } from './game-time.js';
 import { Input, type InputBindings } from './input.js';
 import { PhysicsHost } from './physics-3d/physics-host.js';
 import type { PhysicsBackend } from './physics-3d/rapier-module.js';
+import type { PlatformAchievements, PlatformBackend } from './platform/platform-backend.js';
 import { Pointer } from './pointer.js';
 import { GamePost } from './post-effects.js';
 import { type RenderBackend } from './render-readiness.js';
@@ -70,6 +71,13 @@ export interface GameOptions {
      * pass the module they initialized once, or a rejecting stub.
      */
     physics?: PhysicsBackend;
+    /**
+     * The host platform behind `quit`, `setFullscreen` and `achievements`
+     * (ADR 0032, the seam ADR 0013 describes): the desktop shell's bridge when
+     * `window.waicaDesktop` exists, otherwise the browser. A project's own
+     * tests pass a fake.
+     */
+    platform?: PlatformBackend;
 }
 export type UpdateFn = (dt: number) => void;
 export interface SpawnPrefabOptions {
@@ -126,6 +134,8 @@ export declare class Game {
      * or collisions — the editor's edit mode.
      */
     simulate: boolean;
+    /** The browser or the desktop shell (ADR 0032). */
+    private readonly platform;
     /** WebGPU when the browser offers it, else three's WebGL2 fallback (ADR 0025). */
     private readonly renderer;
     private readonly readiness;
@@ -182,6 +192,20 @@ export declare class Game {
     ready(): Promise<void>;
     /** The Render Backend the renderer settled on; null until ready() resolved. */
     get backend(): RenderBackend | null;
+    /** Whether `quit()` closes the game: true in the desktop shell, false on the web (ADR 0032). */
+    get canQuit(): boolean;
+    /** Store achievements and stats (ADR 0032): unavailable on the web, where every call is a no-op. */
+    get achievements(): PlatformAchievements;
+    /** Closes the desktop app; on the web, where a page cannot close itself, it does nothing. */
+    quit(): void;
+    /** Enters or leaves fullscreen. Never rejects: a browser refuses without a user gesture. */
+    setFullscreen(on: boolean): Promise<void>;
+    /**
+     * Whether the game is fullscreen now. In the desktop shell it asks the main
+     * process synchronously: read it on a key press or when a menu opens, not
+     * every frame.
+     */
+    isFullscreen(): boolean;
     /** Creates a live entity in the scene. */
     spawn(name: string): Entity;
     /** Instantiates a registered prefab after a scene has supplied the registry. */

package/dist/game.js

@@ -14,6 +14,7 @@ import { consumeSimulationSteps, MAX_CHAINED_HOPS, SIMULATION_STEP, snapElapsedT
 import { advanceGameTime, GameTime } from './game-time.js';
 import { Input } from './input.js';
 import { PhysicsHost } from './physics-3d/physics-host.js';
+import { defaultPlatformBackend } from './platform/desktop-platform-backend.js';
 import { Pointer } from './pointer.js';
 import { GamePost } from './post-effects.js';
 import { activeRuntimeBridgeHook, EngineRuntimeBridge, } from './runtime-bridge.js';
@@ -78,6 +79,8 @@ export class Game {
      * or collisions — the editor's edit mode.
      */
     simulate = true;
+    /** The browser or the desktop shell (ADR 0032). */
+    platform;
     /** WebGPU when the browser offers it, else three's WebGL2 fallback (ADR 0025). */
     renderer;
     readiness;
@@ -168,6 +171,7 @@ export class Game {
         });
         this.spriteBatches = createSpriteBatches(this, this.assets);
         this.physics = new PhysicsHost(this, options.physics);
+        this.platform = options.platform ?? defaultPlatformBackend();
         this.cameraEffects = new CameraEffects({
             host: () => canvas.parentElement ?? document.body,
             // One screen pixel in world units: the shake snaps to it (never the base).
@@ -213,6 +217,30 @@ export class Game {
     get backend() {
         return this.readiness.backend;
     }
+    /** Whether `quit()` closes the game: true in the desktop shell, false on the web (ADR 0032). */
+    get canQuit() {
+        return this.platform.canQuit;
+    }
+    /** Store achievements and stats (ADR 0032): unavailable on the web, where every call is a no-op. */
+    get achievements() {
+        return this.platform.achievements;
+    }
+    /** Closes the desktop app; on the web, where a page cannot close itself, it does nothing. */
+    quit() {
+        this.platform.quit();
+    }
+    /** Enters or leaves fullscreen. Never rejects: a browser refuses without a user gesture. */
+    setFullscreen(on) {
+        return this.platform.setFullscreen(on);
+    }
+    /**
+     * Whether the game is fullscreen now. In the desktop shell it asks the main
+     * process synchronously: read it on a key press or when a menu opens, not
+     * every frame.
+     */
+    isFullscreen() {
+        return this.platform.isFullscreen();
+    }
     /** Creates a live entity in the scene. */
     spawn(name) {
         const entity = new Entity(this, name);

package/dist/index.d.ts

@@ -11,6 +11,7 @@ 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';
 export type { AudioChannelState, AudioPlayOptions, LiveSoundInfo, SoundHandle } from './audio/types.js';
+export { WebPlatformBackend, type DesktopBridge, type PlatformAchievements, type PlatformBackend } from './platform/platform-backend.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export type { AnimationFacingProvider, DirectionalAnimation, DirectionalFallback, ResolvedDirectionalClip, } from './animation/directional.js';
 export { isClipTarget } from './animation/clip-target.js';

package/dist/index.js

@@ -3,6 +3,7 @@ export { AssetLoader } from './assets/asset-loader.js';
 export { GltfModelBackend } from './assets/model-backend.js';
 export { glbClipNames } from './assets/glb-clip-names.js';
 export { AudioSubsystem } from './audio/audio-subsystem.js';
+export { WebPlatformBackend } from './platform/platform-backend.js';
 export { installDirectionalAnimation, installedDirectionalAnimation, isAnimationFacingProvider, resolveDirectionalClip, } from './animation/directional.js';
 export { isClipTarget } from './animation/clip-target.js';
 export { isYSortBatchParticipant, isYSortParticipant, ySortZ } from './render-sort.js';

package/dist/platform/desktop-platform-backend.d.ts

@@ -0,0 +1,20 @@
+import { type DesktopBridge, type PlatformAchievements, type PlatformBackend } from './platform-backend.js';
+/** `window.waicaDesktop` is page-reachable data: only the shape the shell exposes counts as the bridge. */
+export declare function isDesktopBridge(value: unknown): value is DesktopBridge;
+/** The packaged desktop app as a platform: every call goes to the shell's main process. */
+export declare class DesktopPlatformBackend implements PlatformBackend {
+    private readonly bridge;
+    readonly canQuit = true;
+    readonly achievements: PlatformAchievements;
+    constructor(bridge: DesktopBridge);
+    quit(): void;
+    setFullscreen(on: boolean): Promise<void>;
+    isFullscreen(): boolean;
+}
+/**
+ * The desktop backend inside the shell (`window.waicaDesktop` exists), the
+ * web one everywhere else. A `window.waicaDesktop` of another shape (an
+ * engine and a shell from versions that disagree) falls back to the web
+ * backend and says what it lacks, so a missing Quit has a cause in the console.
+ */
+export declare function defaultPlatformBackend(): PlatformBackend;

package/dist/platform/desktop-platform-backend.js

@@ -0,0 +1,101 @@
+import { NO_ACHIEVEMENTS, WebPlatformBackend, } from './platform-backend.js';
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function isAchievements(value) {
+    return (isObject(value) &&
+        typeof value['available'] === 'boolean' &&
+        typeof value['unlock'] === 'function' &&
+        typeof value['setStat'] === 'function' &&
+        typeof value['getStat'] === 'function');
+}
+const BRIDGE_METHODS = ['quit', 'setFullscreen', 'isFullscreen'];
+/** The members a `window.waicaDesktop` lacks (or has with the wrong type) to be the shell's bridge. */
+function bridgeGaps(value) {
+    if (!isObject(value))
+        return ['every member'];
+    const gaps = BRIDGE_METHODS.filter((name) => typeof value[name] !== 'function');
+    if (value['achievements'] !== undefined && !isAchievements(value['achievements']))
+        gaps.push('achievements');
+    return gaps;
+}
+/** `window.waicaDesktop` is page-reachable data: only the shape the shell exposes counts as the bridge. */
+export function isDesktopBridge(value) {
+    return bridgeGaps(value).length === 0;
+}
+/** A throw from the bridge (say, the window closing after `quit()`) stays here instead of reaching the game's script. */
+function callShell(call) {
+    try {
+        call();
+    }
+    catch {
+        // The shell is gone or refused: an achievement call is fire-and-forget.
+    }
+}
+/**
+ * The shell's achievements, held to the contract the engine documents: no
+ * call throws, and `getStat` resolves a number or `undefined`, whatever the
+ * bridge does.
+ */
+function forwardedAchievements(shell) {
+    return {
+        available: true,
+        unlock: (id) => callShell(() => shell.unlock(id)),
+        setStat: (id, value) => callShell(() => shell.setStat(id, value)),
+        getStat: async (id) => {
+            try {
+                const value = await shell.getStat(id);
+                return typeof value === 'number' ? value : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        },
+    };
+}
+/** The packaged desktop app as a platform: every call goes to the shell's main process. */
+export class DesktopPlatformBackend {
+    bridge;
+    canQuit = true;
+    achievements;
+    constructor(bridge) {
+        this.bridge = bridge;
+        const shell = bridge.achievements;
+        this.achievements = shell?.available === true ? forwardedAchievements(shell) : NO_ACHIEVEMENTS;
+    }
+    quit() {
+        this.bridge.quit();
+    }
+    async setFullscreen(on) {
+        try {
+            await this.bridge.setFullscreen(on);
+        }
+        catch {
+            // The window is gone or the shell refused: the state stays what isFullscreen() reports.
+        }
+    }
+    isFullscreen() {
+        try {
+            return this.bridge.isFullscreen() === true;
+        }
+        catch {
+            // The window is gone: it is not fullscreen.
+            return false;
+        }
+    }
+}
+/**
+ * The desktop backend inside the shell (`window.waicaDesktop` exists), the
+ * web one everywhere else. A `window.waicaDesktop` of another shape (an
+ * engine and a shell from versions that disagree) falls back to the web
+ * backend and says what it lacks, so a missing Quit has a cause in the console.
+ */
+export function defaultPlatformBackend() {
+    const candidate = Reflect.get(globalThis, 'waicaDesktop');
+    if (isDesktopBridge(candidate))
+        return new DesktopPlatformBackend(candidate);
+    if (candidate !== undefined) {
+        console.warn(`[waica] window.waicaDesktop is not the desktop shell's bridge (${bridgeGaps(candidate).join(', ')} missing or wrong): the game runs without quit, native fullscreen or achievements`);
+    }
+    return new WebPlatformBackend();
+}

package/dist/platform/platform-backend.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Store achievements and stats, whichever store the game ships on (issue #200).
+ * Unavailable on the web and in a desktop build without a store client, where
+ * every call is a no-op and `getStat` resolves `undefined`.
+ */
+export interface PlatformAchievements {
+    /** True only while a store client is connected (the desktop shell with Steam). */
+    readonly available: boolean;
+    /** Activates an achievement by its store id. */
+    unlock(id: string): void;
+    /** Sets an integer stat by its store id and stores it. */
+    setStat(id: string, value: number): void;
+    /** A stat's stored value; `undefined` where none can be read. */
+    getStat(id: string): Promise<number | undefined>;
+}
+/**
+ * Everything Game needs from the host it runs in (ADR 0032): the browser, or
+ * the desktop shell's preload bridge. The web implementation is the default;
+ * the desktop one is picked when `window.waicaDesktop` exists; a project's
+ * own tests replace either through `GameOptions.platform`.
+ */
+export interface PlatformBackend {
+    /** Whether `quit()` can close the game: false where a page cannot close itself. */
+    readonly canQuit: boolean;
+    /** Closes the game where `canQuit` is true; a no-op elsewhere. */
+    quit(): void;
+    /** Enters or leaves fullscreen. Never rejects: a refused request leaves `isFullscreen()` as it was. */
+    setFullscreen(on: boolean): Promise<void>;
+    /**
+     * Whether the game is fullscreen now. In the desktop shell this is a
+     * synchronous round trip to the main process, which blocks the page until
+     * it answers: read it when a key is pressed or a menu opens, not every frame.
+     */
+    isFullscreen(): boolean;
+    readonly achievements: PlatformAchievements;
+}
+/** Achievements where no store client is connected: unavailable, and every call a no-op. */
+export declare const NO_ACHIEVEMENTS: PlatformAchievements;
+/**
+ * What the desktop shell's preload exposes as `window.waicaDesktop` through
+ * `contextBridge` (ADR 0032). `achievements` is absent or unavailable without
+ * Steam.
+ */
+export interface DesktopBridge {
+    quit(): void;
+    setFullscreen(on: boolean): Promise<void>;
+    isFullscreen(): boolean;
+    achievements?: PlatformAchievements;
+}
+/**
+ * The browser as a platform (ADR 0032): a page cannot close itself, fullscreen
+ * is the Fullscreen API, and there is no store, so no achievements.
+ */
+export declare class WebPlatformBackend implements PlatformBackend {
+    private readonly fullscreenTarget;
+    readonly canQuit = false;
+    readonly achievements: PlatformAchievements;
+    /**
+     * @param fullscreenTarget The element `setFullscreen(true)` asks to fill the
+     * screen: the whole page by default. A host that shows the game inside a
+     * larger page, like the editor's Viewport, passes the game's own surface.
+     */
+    constructor(fullscreenTarget?: () => Element);
+    quit(): void;
+    setFullscreen(on: boolean): Promise<void>;
+    isFullscreen(): boolean;
+}

package/dist/platform/platform-backend.js

@@ -0,0 +1,42 @@
+/** Achievements where no store client is connected: unavailable, and every call a no-op. */
+export const NO_ACHIEVEMENTS = Object.freeze({
+    available: false,
+    unlock: () => { },
+    setStat: () => { },
+    getStat: () => Promise.resolve(undefined),
+});
+/**
+ * The browser as a platform (ADR 0032): a page cannot close itself, fullscreen
+ * is the Fullscreen API, and there is no store, so no achievements.
+ */
+export class WebPlatformBackend {
+    fullscreenTarget;
+    canQuit = false;
+    achievements = NO_ACHIEVEMENTS;
+    /**
+     * @param fullscreenTarget The element `setFullscreen(true)` asks to fill the
+     * screen: the whole page by default. A host that shows the game inside a
+     * larger page, like the editor's Viewport, passes the game's own surface.
+     */
+    constructor(fullscreenTarget = () => document.documentElement) {
+        this.fullscreenTarget = fullscreenTarget;
+    }
+    quit() {
+        // A page cannot close its own tab; canQuit tells the game not to offer it.
+    }
+    async setFullscreen(on) {
+        try {
+            if (on)
+                await this.fullscreenTarget().requestFullscreen();
+            else
+                await document.exitFullscreen();
+        }
+        catch {
+            // Refused (no user gesture, an iframe without permission) or no Fullscreen API at all.
+        }
+    }
+    isFullscreen() {
+        // `undefined` where the page has no Fullscreen API: never fullscreen there.
+        return Boolean(document.fullscreenElement);
+    }
+}

package/package.json

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