@jgengine/node 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -11,6 +11,42 @@ Agents building on the published SDK can also read this programmatically:
 same data as typed values, so an updater can diff its installed version against
 the latest and surface the migration steps.
 
+## 0.10.0
+
+### Migrate
+
+- **Nothing to change for existing games** — the shared mobile-composition system (viewport allocation, region collision, `--jg-*` viewport vars) is wired automatically by the shell for every game; `HudPanel`s inside a `HudCanvas` register themselves. Legacy `orientation: "landscape" | "portrait"` keeps its advisory dismissible-hint behavior unchanged.
+- **Opt a driving/landscape game into the strict gate**: replace the advisory `orientation` with the contract form — `orientation: { mobile: "landscape-required" }` (rules: `any` · `portrait`/`landscape` advisory · `portrait-required`/`landscape-required` · `unsupported`). In portrait the engine now shows a polished `RotateDeviceScreen`, suppresses input, freezes the sim, and unmounts the HUD/controls until the device is landscape.
+- **Declare HUD intent** where useful: `HudPanel` gains `priority` (`critical`/`secondary`/`tertiary`), `mobileBehavior` (`hidden` unmounts on phones, `transient` softens collision, …), `allowOverlapWith`, and `collisionGroup`. Optional — omitting them keeps prior behavior.
+- **Mobile validation now also fails on overlap**: `bun run shoot <game> --device mobile|mobile-landscape|both` exits non-zero on forbidden inter-element collisions (not just viewport overflow), naming both regions.
+
+### Added
+
+- Shared mobile layout composition — `@jgengine/core/ui/gameLayout` (pure geometry: `resolveLayoutMode`, `intersects`, `overlapArea`, `detectLayoutCollisions`, `computeGameplayRect`, `LayoutRegion`, `GameViewportLayout`) and `@jgengine/core/ui/orientation` (`resolveOrientationRequirement`, `orientationGateActive`, `MobileOrientationRule`). `@jgengine/react` adds `GameViewportProvider` (mounted by the shell), hooks (`useGameViewportLayout`, `useGameLayoutMode`, `useGameOrientation`, `useReservedControlZones`, `useLayoutCollisions`, `useRegisterLayoutRegion`), and a headless `RotateDeviceScreen`. The provider tracks `window.visualViewport`, publishes `--jg-viewport-*` / `--jg-visual-viewport-*` / `--jg-safe-*` CSS vars, resolves the explicit layout mode, and detects forbidden region overlaps (dev `data-jg-layout-collision` + console diagnostic).
+- Mandatory orientation contract — `PlayableGame.orientation` accepts `{ mobile: <rule> }`; `landscape-required`/`portrait-required` render an engine-owned rotate gate that blocks gameplay (input suppressed, simulation frozen, HUD/controls unmounted), self-correcting when the device is turned. Reduced-motion and safe-area respected; `visualViewport`-sized for mobile Safari/PWA.
+- Reserved touch-control zones — the touch dock registers its joystick / action-cluster / utility rectangles (runtime-measured) as `control` regions, so HUD placement and collision validation know exactly where controls sit.
+- HUD placement metadata — `HudPanel` gains `priority`, `mobileBehavior`, `allowOverlapWith`, `collisionGroup`, and registers as a collision-tracked layout region.
+- Mobile-landscape shoot device — `bun run shoot --device mobile-landscape` (844×390) plus collision-gate reads that fail mobile validation on forbidden overlaps.
+- Canyon Chase migrated as the reference landscape-required game — declares `orientation: { mobile: "landscape-required" }`, composes its HUD through coordinated `HudPanel` regions (pursuit distance critical, border secondary, survey map hidden on mobile, radio transient) instead of independent fixed corners.
+
+### Changed
+
+- First-person projectile tracers now originate from the weapon muzzle instead of the camera/eye centerline. Hit detection is unchanged (still crosshair-accurate) — only the drawn tracer's start point moved to the viewmodel muzzle, which tracks full aim yaw and pitch. Non-viewmodel games and enemy tracers are unaffected.
+
+## 0.9.0
+
+### Added
+
+- Mobile HUD fit — design-resolution UI scaling now applies to every game by default: `HudCanvas` measures the live viewport and scales the whole HUD from `PlayableGame.hudFit.designSize` (default 1600×900, clamps `minScale`/`maxScale` 0.4–1) so desktop-authored layouts shrink to fit a phone instead of overflowing it; `hudFit.mobile` overrides tune the phone fit separately. Pure math lives in `@jgengine/core/ui/hudScale` (`hudScaleForViewport`, `resolveHudFit`, `rectOverflow`, `overflowingPanels`); the shell mounts `@jgengine/react`'s `HudViewportProvider` around `GameUI` so games need no wiring.
+- Graphics → UI scale — a player-facing `graphics.uiScale` slider (0.5–1.5, default 1) multiplies the computed HUD scale on every platform; the same resolution system drives desktop preference and mobile shrink.
+- HUD overflow gate — `HudCanvas` measures every `HudPanel` against the viewport at runtime and reports offenders on a `data-hud-overflow` attribute (plus a console warning); `bun run shoot <game> --device mobile|both` now exits non-zero naming the panels that escape the viewport.
+- Automatic visibility & streaming defaults — an engine-level `VisibilitySystem` (exported from `@jgengine/core`) gives every scene renderer-agnostic culling and asset-streaming policy with no per-object wiring: distance culling, preload margins, hysteresis, delayed unloading, multi-camera awareness (including cameras excluded from streaming), and per-object overrides (always-visible, never-unload, disabled culling/streaming, custom render distance and preload margin).
+- Self-hosted asset mirror — `DEFAULT_RELEASE_BASE` now points at this repo's rolling `packs` release instead of the upstream host; a catalog-driven `mirror-assets` workflow (weekly cron + manual dispatch) keeps the mirror in sync with the asset catalog.
+
+### Changed
+
+- Mobile HUD fit is on by default — design-resolution HUD scaling now applies to every game with no config change (previously opt-in via `platforms: ["web", "mobile"]`). A desktop-only game keeps the legacy fixed 0.85 compact zoom by declaring `platforms: ["web"]` (without `"mobile"`).
+
 ## 0.8.0
 
 Transport-agnostic multiplayer (socket.io, WebRTC p2p, LAN/Fly adapters) plus grid/voxel

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./host.js";
+export * from "./persistence.js";
+export * from "./socketIoServer.js";
+export * from "./webHandler.js";
+export * from "./worldServer.js";
+export * from "./wsServer.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export * from "./host.js";
+export * from "./persistence.js";
+export * from "./socketIoServer.js";
+export * from "./webHandler.js";
+export * from "./worldServer.js";
+export * from "./wsServer.js";

package/dist/persistence.js

@@ -1,19 +1,30 @@
-import { mkdir, readdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, readdir, readFile, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { applyLeaderboardRows, leaderboardRowKey, profileLeaderboardStats, topLeaderboardRows, trimFeedEntries, } from "@jgengine/core/runtime/hostPersistence";
 export { memoryPersistence } from "@jgengine/ws/host";
+function isMissing(error) {
+    return error?.code === "ENOENT";
+}
 async function readJson(path) {
+    let text;
     try {
-        return JSON.parse(await readFile(path, "utf8"));
+        text = await readFile(path, "utf8");
     }
-    catch {
-        return null;
+    catch (error) {
+        if (isMissing(error))
+            return null;
+        throw error;
     }
+    return JSON.parse(text);
 }
-async function writeJson(path, value) {
-    const temp = `${path}.tmp`;
+async function stageJson(path, value) {
+    const temp = `${path}.${randomUUID()}.tmp`;
     await writeFile(temp, JSON.stringify(value), "utf8");
-    await rename(temp, path);
+    return temp;
+}
+async function writeJson(path, value) {
+    await rename(await stageJson(path, value), path);
 }
 const enc = encodeURIComponent;
 export function filePersistence(dir, now = Date.now) {
@@ -32,6 +43,7 @@ export function filePersistence(dir, now = Date.now) {
         return new Map(rows.map((row) => [leaderboardRowKey(row), row]));
     };
     let leaderboardLock = Promise.resolve();
+    const feedLocks = new Map();
     return {
         async loadServer(serverId) {
             await ensureDirs();
@@ -86,9 +98,24 @@ export function filePersistence(dir, now = Date.now) {
             await ensureDirs();
             const serverDir = join(chunksDir, enc(serverId));
             await mkdir(serverDir, { recursive: true });
-            for (const record of records) {
-                await writeJson(join(serverDir, `${enc(record.chunkKey)}.json`), record);
-            }
+            const staged = await Promise.all(records.map(async (record) => {
+                const final = join(serverDir, `${enc(record.chunkKey)}.json`);
+                return { temp: await stageJson(final, record), final };
+            }));
+            await Promise.all(staged.map(({ temp, final }) => rename(temp, final)));
+        },
+        async deleteChunks(serverId, chunkKeys) {
+            await ensureDirs();
+            const serverDir = join(chunksDir, enc(serverId));
+            await Promise.all(chunkKeys.map(async (chunkKey) => {
+                try {
+                    await unlink(join(serverDir, `${enc(chunkKey)}.json`));
+                }
+                catch (error) {
+                    if (!isMissing(error))
+                        throw error;
+                }
+            }));
         },
         async loadFeed({ serverId, action }) {
             await ensureDirs();
@@ -97,9 +124,14 @@ export function filePersistence(dir, now = Date.now) {
         async appendFeed({ serverId, action, entry }) {
             await ensureDirs();
             const path = join(feedsDir, `${enc(serverId)}__${enc(action)}.json`);
-            const entries = trimFeedEntries([...((await readJson(path)) ?? []), entry]);
-            await writeJson(path, entries);
-            return entries;
+            const prev = feedLocks.get(path) ?? Promise.resolve();
+            const run = prev.then(async () => {
+                const entries = trimFeedEntries([...((await readJson(path)) ?? []), entry]);
+                await writeJson(path, entries);
+                return entries;
+            });
+            feedLocks.set(path, run.catch(() => undefined));
+            return run;
         },
         async applyLeaderboardIncrements(gameId, entries) {
             const run = leaderboardLock.then(async () => {

package/dist/webHandler.d.ts

@@ -1,5 +1,5 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 export type WebHandler = (request: Request) => Promise<Response>;
 export type NodeHandler = (req: IncomingMessage, res: ServerResponse) => void;
-export declare function toWebRequest(req: IncomingMessage): Request;
+export declare function toWebRequest(req: IncomingMessage): Promise<Request>;
 export declare function toNodeHandler(handler: WebHandler): NodeHandler;

package/dist/webHandler.js

@@ -1,4 +1,4 @@
-export function toWebRequest(req) {
+export async function toWebRequest(req) {
     const host = req.headers.host ?? "localhost";
     const headers = new Headers();
     for (const [key, value] of Object.entries(req.headers)) {
@@ -8,11 +8,24 @@ export function toWebRequest(req) {
             for (const entry of value)
                 headers.append(key, entry);
     }
-    return new Request(`http://${host}${req.url ?? "/"}`, { method: req.method, headers });
+    const method = req.method ?? "GET";
+    let body;
+    if (method !== "GET" && method !== "HEAD") {
+        const chunks = [];
+        for await (const chunk of req)
+            chunks.push(chunk);
+        if (chunks.length > 0) {
+            const buffer = Buffer.concat(chunks);
+            if (buffer.byteLength > 0)
+                body = Uint8Array.from(buffer);
+        }
+    }
+    return new Request(`http://${host}${req.url ?? "/"}`, { method, headers, body });
 }
 export function toNodeHandler(handler) {
     return (req, res) => {
-        void handler(toWebRequest(req))
+        void toWebRequest(req)
+            .then(handler)
             .then(async (response) => {
             res.statusCode = response.status;
             response.headers.forEach((value, key) => res.setHeader(key, value));

package/dist/worldServer.d.ts

@@ -0,0 +1,34 @@
+import type { GameDefinition } from "@jgengine/core/game/defineGame";
+import type { GameContextContent } from "@jgengine/core/runtime/gameContext";
+import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
+import { type WorldGameHost } from "@jgengine/ws/worldHost";
+import { type GameWsServer, type GameWsServerOptions } from "./wsServer.js";
+/** A game the world server can host — its authoritative {@link GameDefinition} and the content lookup a `GameContext` reads. */
+export interface HostedGameDefinition {
+    game: GameDefinition<ModelAssetRef, unknown>;
+    content: GameContextContent;
+}
+/** Config for {@link createWorldGameServer}: how to resolve a game by id, the tick cadence, and the underlying ws-server/router options (minus `host`, which the server builds). */
+export interface WorldGameServerOptions extends Omit<GameWsServerOptions, "host"> {
+    /** Resolve a game to host by id — `null` for an unknown id, which rejects the join. */
+    resolveGame(gameId: string): HostedGameDefinition | null;
+    /** Ticks per second for the real-clock loop {@link WorldGameServer.start} drives; default 30. Tests call {@link WorldGameServer.tick} manually instead. */
+    tickHz?: number;
+}
+/** A runnable ws host for GameContext worlds: {@link createWorldGameHost} + {@link createGameWsServer} + a tick loop, with a manual `tick(dt)` seam so a fake clock can drive it in tests. */
+export interface WorldGameServer {
+    host: WorldGameHost;
+    ws: GameWsServer;
+    /** Advance every live world by `dtSeconds` — the manual/test drive point; {@link start} calls it on a real-clock interval. */
+    tick(dtSeconds: number): void;
+    /** Begin driving {@link tick} on a real-clock interval at `tickHz` (idempotent). */
+    start(): void;
+    /** Stop the tick interval (idempotent). */
+    stop(): void;
+    /** Stop the tick loop and tear down the ws server. */
+    close(): Promise<void>;
+    /** The bound ws port. */
+    port(): number;
+}
+/** Build a {@link WorldGameServer} — one process hosting authoritative GameContext worlds over ws, ready for two-client play once {@link WorldGameServer.start} runs. */
+export declare function createWorldGameServer(options: WorldGameServerOptions): WorldGameServer;

package/dist/worldServer.js

@@ -0,0 +1,51 @@
+import { createHostedWorldSession } from "@jgengine/core/runtime/hostedWorldSession";
+import { createWorldGameHost } from "@jgengine/ws/worldHost";
+import { createGameWsServer } from "./wsServer.js";
+const DEFAULT_TICK_HZ = 30;
+/** Build a {@link WorldGameServer} — one process hosting authoritative GameContext worlds over ws, ready for two-client play once {@link WorldGameServer.start} runs. */
+export function createWorldGameServer(options) {
+    const { resolveGame, tickHz = DEFAULT_TICK_HZ, ...serverOptions } = options;
+    const clock = options.now ?? (() => Date.now());
+    const host = createWorldGameHost({
+        now: clock,
+        session: ({ gameId }) => {
+            const resolved = resolveGame(gameId);
+            if (resolved === null)
+                return null;
+            return createHostedWorldSession({ definition: resolved.game, content: resolved.content, now: clock });
+        },
+    });
+    const ws = createGameWsServer({ ...serverOptions, host });
+    let interval = null;
+    let last = clock();
+    function tick(dtSeconds) {
+        host.tick(dtSeconds);
+    }
+    function stop() {
+        if (interval !== null) {
+            clearInterval(interval);
+            interval = null;
+        }
+    }
+    return {
+        host,
+        ws,
+        tick,
+        stop,
+        port: ws.port,
+        start() {
+            if (interval !== null)
+                return;
+            last = clock();
+            interval = setInterval(() => {
+                const current = clock();
+                tick((current - last) / 1000);
+                last = current;
+            }, 1000 / tickHz);
+        },
+        async close() {
+            stop();
+            await ws.close();
+        },
+    };
+}