@jgengine/shell 0.7.0 → 0.8.0

package/dist/environment/EnvironmentScene.js

@@ -1,7 +1,9 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
-import { generateBuildingDistrict } from "@jgengine/core/world/buildings";
-import { resolveTerrainField } from "@jgengine/core/world/terrain";
+import { resolveStructureBuildings } from "@jgengine/core/world/environmentSummary";
+import { resolveTerrainField, resolveTerrainPalette } from "@jgengine/core/world/terrain";
+import { SkyDaylight } from "./Daylight.js";
+import { GroundPad } from "./GroundPad.js";
 import { GeneratedBuilding } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
 import { ProceduralGround } from "../terrain/ProceduralGround.js";
@@ -11,15 +13,21 @@ import { SnowField } from "../weather/SnowField.js";
 import { WeatherUniformProvider } from "../weather/weatherUniforms.js";
 const DEFAULT_TERRAIN_FREQUENCY = 0.03;
 function TerrainGround({ terrain }) {
+    const palette = resolveTerrainPalette(terrain);
     return (_jsx(ProceduralGround, { terrain: {
             size: [terrain.bounds.w, terrain.bounds.d],
+            segments: terrain.segments,
             height: terrain.height,
             seed: terrain.seed,
             moundScale: terrain.frequency ?? DEFAULT_TERRAIN_FREQUENCY,
             octaves: terrain.octaves,
             ridged: terrain.ridged,
             baseOffset: terrain.baseHeight,
-        }, colors: terrain.waterLevel === undefined ? undefined : { waterlineHeight: terrain.waterLevel } }));
+        }, colors: {
+            low: palette.low,
+            high: palette.high,
+            ...(terrain.waterLevel === undefined ? {} : { waterline: palette.waterline, waterlineHeight: terrain.waterLevel }),
+        } }));
 }
 function Vegetation({ grass, field }) {
     return (_jsx(GrassField, { area: [grass.area.w, grass.area.d], density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: field.sampleHeight, colorBase: grass.colors[0], colorTip: grass.colors[grass.colors.length - 1], wind: { strength: grass.windStrength } }));
@@ -37,39 +45,23 @@ function Weather({ weather }) {
     return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
 }
 function Water({ ocean }) {
-    return (_jsx(Ocean, { "position-y": ocean.level, config: {
+    const [x, z] = ocean.position ?? [0, 0];
+    return (_jsx(Ocean, { position: [x, ocean.level, z], config: {
             size: Math.max(ocean.bounds.w, ocean.bounds.d),
             amplitude: ocean.waveHeight,
             speed: ocean.waveSpeed,
             color: { shallow: ocean.color },
         } }));
 }
-function Structures({ structures }) {
-    const buildings = useMemo(() => {
-        const columns = Math.max(1, Math.ceil(Math.sqrt(structures.count)));
-        const rows = Math.max(1, Math.ceil(structures.count / columns));
-        const spacing = structures.spacing;
-        const origin = [
-            -((columns - 1) * (structures.footprint.w + spacing)) / 2,
-            -((rows - 1) * (structures.footprint.d + spacing)) / 2,
-        ];
-        return generateBuildingDistrict({
-            rows,
-            columns,
-            origin,
-            lotSize: structures.footprint,
-            streetWidth: spacing,
-            floorRange: structures.stories,
-            base: { floorHeight: structures.storyHeight },
-            ...(structures.seed === undefined ? {} : { seed: structures.seed }),
-        }).slice(0, structures.count);
-    }, [structures]);
-    return (_jsx(_Fragment, { children: buildings.map((building) => (_jsx(GeneratedBuilding, { building: building }, building.id))) }));
+function Structures({ structures, field }) {
+    const buildings = useMemo(() => resolveStructureBuildings(structures), [structures]);
+    return (_jsx(_Fragment, { children: buildings.map((building) => (_jsx("group", { "position-y": field.sampleHeight(building.center[0], building.center[1]), children: _jsx(GeneratedBuilding, { building: building }) }, building.id))) }));
 }
 export function EnvironmentScene({ feature }) {
     const field = useMemo(() => resolveTerrainField(feature.terrain), [feature.terrain]);
     const vegetation = feature.vegetation ?? [];
     const water = feature.water ?? [];
     const structures = feature.structures ?? [];
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain }) : null, water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry }, `structures-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    const pads = feature.pads ?? [];
+    return (_jsxs(_Fragment, { children: [feature.sky !== undefined && !feature.sky.timeOfDay ? _jsx(SkyDaylight, { sky: feature.sky }) : null, feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain }) : null, water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), structures.map((entry, index) => (_jsx(Structures, { structures: entry, field: field }, `structures-${index}`))), pads.map((entry, index) => (_jsx(GroundPad, { pad: entry, field: field }, `pad-${index}`))), vegetation.map((grass, index) => (_jsx(Vegetation, { grass: grass, field: field }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/GroundPad.d.ts

@@ -0,0 +1,7 @@
+import type { PadEnvironmentDescriptor } from "@jgengine/core/world/features";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+export interface GroundPadProps {
+    pad: PadEnvironmentDescriptor;
+    field: TerrainField;
+}
+export declare function GroundPad({ pad, field }: GroundPadProps): import("react").JSX.Element;

package/dist/environment/GroundPad.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { PAD_THICKNESS, resolvePadMeshY, resolvePadShape } from "./groundPadMath.js";
+export function GroundPad({ pad, field }) {
+    const [x, z] = pad.center;
+    const groundHeight = field.sampleHeight(x, z);
+    const meshY = resolvePadMeshY(groundHeight, pad);
+    const shape = resolvePadShape(pad.size);
+    if (shape.circular) {
+        return (_jsxs("mesh", { position: [x, meshY, z], receiveShadow: true, children: [_jsx("cylinderGeometry", { args: [shape.radius, shape.radius, PAD_THICKNESS, 32] }), _jsx("meshStandardMaterial", { color: pad.color, roughness: 0.9 })] }));
+    }
+    return (_jsxs("mesh", { position: [x, meshY, z], rotation: [0, pad.rotationY ?? 0, 0], receiveShadow: true, children: [_jsx("boxGeometry", { args: [shape.width, PAD_THICKNESS, shape.depth] }), _jsx("meshStandardMaterial", { color: pad.color, roughness: 0.9 })] }));
+}

package/dist/environment/daylightCycle.d.ts

@@ -0,0 +1,26 @@
+export interface DaylightCycleConfig {
+    horizonColor?: string;
+    zenithColor?: string;
+    sunIntensity?: number;
+    ambientIntensity?: number;
+}
+export interface DaylightState {
+    sunPosition: [number, number, number];
+    sunIntensity: number;
+    ambientIntensity: number;
+    skyTop: string;
+    skyBottom: string;
+    background: string;
+}
+export declare const DEFAULT_DAY_SUN_INTENSITY = 1;
+export declare const DEFAULT_DAY_AMBIENT_INTENSITY = 0.6;
+export declare const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
+export declare const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
+export declare const SKY_PRESET_DAY_FRACTION: Record<"day" | "dusk" | "night", number>;
+export declare function lerpHexColor(a: string, b: string, t: number): string;
+/**
+ * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
+ * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
+ * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
+ */
+export declare function daylightStateAt(dayFraction: number, config?: DaylightCycleConfig): DaylightState;

package/dist/environment/daylightCycle.js

@@ -0,0 +1,116 @@
+const NIGHT_SUN_INTENSITY = 0.02;
+const NIGHT_AMBIENT_INTENSITY = 0.08;
+const NIGHT_SKY_TOP = "#02030a";
+const NIGHT_SKY_BOTTOM = "#05070f";
+const DAWN_SUN_INTENSITY = 0.45;
+const DAWN_AMBIENT_INTENSITY = 0.3;
+const DAWN_SKY_TOP = "#3c5a82";
+const DAWN_SKY_BOTTOM = "#ffb37a";
+const DUSK_SUN_INTENSITY = 0.45;
+const DUSK_AMBIENT_INTENSITY = 0.3;
+const DUSK_SKY_TOP = "#4a3a5c";
+const DUSK_SKY_BOTTOM = "#ff8a5c";
+export const DEFAULT_DAY_SUN_INTENSITY = 1;
+export const DEFAULT_DAY_AMBIENT_INTENSITY = 0.6;
+export const DEFAULT_DAY_SKY_TOP = "#3fa4f2";
+export const DEFAULT_DAY_SKY_BOTTOM = "#e3f4ff";
+const SUN_DISTANCE = 200;
+const SUN_DEPTH_RATIO = 0.4;
+export const SKY_PRESET_DAY_FRACTION = {
+    night: 0,
+    day: 0.5,
+    dusk: 0.75,
+};
+function clamp01(value) {
+    return value < 0 ? 0 : value > 1 ? 1 : value;
+}
+function lerp(a, b, t) {
+    return a + (b - a) * t;
+}
+function hexToRgb(hex) {
+    const clean = hex.startsWith("#") ? hex.slice(1) : hex;
+    const value = parseInt(clean, 16);
+    return [(value >> 16) & 255, (value >> 8) & 255, value & 255];
+}
+function clampByte(value) {
+    return Math.max(0, Math.min(255, Math.round(value)));
+}
+function rgbToHex(rgb) {
+    return `#${rgb.map((channel) => clampByte(channel).toString(16).padStart(2, "0")).join("")}`;
+}
+export function lerpHexColor(a, b, t) {
+    const [ar, ag, ab] = hexToRgb(a);
+    const [br, bg, bb] = hexToRgb(b);
+    return rgbToHex([lerp(ar, br, t), lerp(ag, bg, t), lerp(ab, bb, t)]);
+}
+function buildKeyframes(config) {
+    const night = {
+        t: 0,
+        sunIntensity: NIGHT_SUN_INTENSITY,
+        ambientIntensity: NIGHT_AMBIENT_INTENSITY,
+        skyTop: NIGHT_SKY_TOP,
+        skyBottom: NIGHT_SKY_BOTTOM,
+    };
+    const dawn = {
+        t: 0.25,
+        sunIntensity: DAWN_SUN_INTENSITY,
+        ambientIntensity: DAWN_AMBIENT_INTENSITY,
+        skyTop: DAWN_SKY_TOP,
+        skyBottom: DAWN_SKY_BOTTOM,
+    };
+    const day = {
+        t: 0.5,
+        sunIntensity: config.sunIntensity ?? DEFAULT_DAY_SUN_INTENSITY,
+        ambientIntensity: config.ambientIntensity ?? DEFAULT_DAY_AMBIENT_INTENSITY,
+        skyTop: config.zenithColor ?? DEFAULT_DAY_SKY_TOP,
+        skyBottom: config.horizonColor ?? DEFAULT_DAY_SKY_BOTTOM,
+    };
+    const dusk = {
+        t: 0.75,
+        sunIntensity: DUSK_SUN_INTENSITY,
+        ambientIntensity: DUSK_AMBIENT_INTENSITY,
+        skyTop: DUSK_SKY_TOP,
+        skyBottom: DUSK_SKY_BOTTOM,
+    };
+    const midnight = { ...night, t: 1 };
+    return [night, dawn, day, dusk, midnight];
+}
+function wrapFraction(dayFraction) {
+    return ((dayFraction % 1) + 1) % 1;
+}
+function segmentAt(wrapped, keyframes) {
+    for (let index = 0; index < keyframes.length - 1; index += 1) {
+        const from = keyframes[index];
+        const to = keyframes[index + 1];
+        if (wrapped >= from.t && wrapped <= to.t) {
+            const span = to.t - from.t;
+            const localT = span <= 0 ? 0 : clamp01((wrapped - from.t) / span);
+            return { from, to, localT };
+        }
+    }
+    const last = keyframes[keyframes.length - 1];
+    return { from: last, to: last, localT: 0 };
+}
+/**
+ * Samples the daylight cycle at a point in the day (0 = midnight, 0.25 = dawn, 0.5 = noon, 0.75 = dusk),
+ * lerping sun position/intensity, ambient intensity, and sky colors through a dawn/day/dusk/night
+ * keyframe table. `config` overrides the noon (peak-day) colors and intensities only.
+ */
+export function daylightStateAt(dayFraction, config = {}) {
+    const wrapped = wrapFraction(dayFraction);
+    const keyframes = buildKeyframes(config);
+    const { from, to, localT } = segmentAt(wrapped, keyframes);
+    const sunIntensity = lerp(from.sunIntensity, to.sunIntensity, localT);
+    const ambientIntensity = lerp(from.ambientIntensity, to.ambientIntensity, localT);
+    const skyTop = lerpHexColor(from.skyTop, to.skyTop, localT);
+    const skyBottom = lerpHexColor(from.skyBottom, to.skyBottom, localT);
+    const angle = (wrapped - 0.25) * 2 * Math.PI;
+    const elevation = Math.sin(angle);
+    const azimuth = Math.cos(angle);
+    const sunPosition = [
+        azimuth * SUN_DISTANCE,
+        elevation * SUN_DISTANCE,
+        SUN_DISTANCE * SUN_DEPTH_RATIO,
+    ];
+    return { sunPosition, sunIntensity, ambientIntensity, skyTop, skyBottom, background: skyBottom };
+}

package/dist/environment/groundPadMath.d.ts

@@ -0,0 +1,13 @@
+import type { PadEnvironmentDescriptor, PadSize } from "@jgengine/core/world/features";
+export declare const PAD_THICKNESS = 0.1;
+export type PadShape = {
+    circular: true;
+    radius: number;
+} | {
+    circular: false;
+    width: number;
+    depth: number;
+};
+export declare function resolvePadShape(size: PadSize): PadShape;
+export declare function resolvePadSurfaceY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height">): number;
+export declare function resolvePadMeshY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height">): number;

package/dist/environment/groundPadMath.js

@@ -0,0 +1,10 @@
+export const PAD_THICKNESS = 0.1;
+export function resolvePadShape(size) {
+    return "radius" in size ? { circular: true, radius: size.radius } : { circular: false, width: size[0], depth: size[1] };
+}
+export function resolvePadSurfaceY(groundHeight, pad) {
+    return groundHeight + pad.height;
+}
+export function resolvePadMeshY(groundHeight, pad) {
+    return resolvePadSurfaceY(groundHeight, pad) - PAD_THICKNESS / 2;
+}

package/dist/environment/index.d.ts

@@ -1 +1,3 @@
+export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDomeProps, type TimeOfDayDaylightProps, } from "./Daylight.js";
 export { EnvironmentScene, type EnvironmentSceneProps } from "./EnvironmentScene.js";
+export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, type DaylightCycleConfig, type DaylightState, } from "./daylightCycle.js";

package/dist/environment/index.js

@@ -1 +1,3 @@
+export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, } from "./Daylight.js";
 export { EnvironmentScene } from "./EnvironmentScene.js";
+export { daylightStateAt, lerpHexColor, SKY_PRESET_DAY_FRACTION, } from "./daylightCycle.js";

package/dist/materialOverride.d.ts

@@ -0,0 +1,8 @@
+import * as THREE from "three";
+import type { ModelMaterialOverride } from "@jgengine/core/game/playableGame";
+/**
+ * Clones each `MeshStandardMaterial` under `root` and applies `override`'s
+ * color/finish onto the clone, so shared GLTF-cache scenes are never mutated
+ * in place (#151.3).
+ */
+export declare function applyMaterialOverride(root: THREE.Object3D, override: ModelMaterialOverride): void;

package/dist/materialOverride.js

@@ -0,0 +1,32 @@
+import * as THREE from "three";
+/**
+ * Clones each `MeshStandardMaterial` under `root` and applies `override`'s
+ * color/finish onto the clone, so shared GLTF-cache scenes are never mutated
+ * in place (#151.3).
+ */
+export function applyMaterialOverride(root, override) {
+    root.traverse((node) => {
+        const mesh = node;
+        if (!mesh.isMesh)
+            return;
+        mesh.material = Array.isArray(mesh.material)
+            ? mesh.material.map((material) => overrideOne(material, override))
+            : overrideOne(mesh.material, override);
+    });
+}
+function overrideOne(material, override) {
+    if (!(material instanceof THREE.MeshStandardMaterial))
+        return material;
+    const clone = material.clone();
+    if (override.color !== undefined)
+        clone.color.set(override.color);
+    if (override.metalness !== undefined)
+        clone.metalness = override.metalness;
+    if (override.roughness !== undefined)
+        clone.roughness = override.roughness;
+    if (override.emissive !== undefined)
+        clone.emissive.set(override.emissive);
+    if (override.emissiveIntensity !== undefined)
+        clone.emissiveIntensity = override.emissiveIntensity;
+    return clone;
+}

package/dist/multiplayer.d.ts

@@ -1,16 +1,23 @@
 import type { GameDefinition } from "@jgengine/core/game/defineGame";
-import { type WsBackend } from "@jgengine/ws/createWsBackend";
-export type ShellMultiplayer = {
-    gameId: string;
-    userId: string;
-    backend: WsBackend;
-    feedActions: string[];
-};
-export declare function resolveShellMultiplayer(args: {
+import type { MultiplayerSession } from "@jgengine/core/runtime/transport";
+export type ShellMultiplayer = MultiplayerSession;
+export declare const DEFAULT_FEED_ACTIONS: string[];
+export declare function randomPlayerId(): string;
+export type ResolveShellMultiplayerArgs = {
     game: GameDefinition;
     gameId: string;
     url?: string;
     userId?: string;
     force?: boolean;
     feedActions?: string[];
-}): ShellMultiplayer | null;
+};
+export declare function resolveShellMultiplayer(args: ResolveShellMultiplayerArgs): ShellMultiplayer | null;
+export declare function resolvePeerShellMultiplayer(args: {
+    gameId: string;
+    role: "host" | "join";
+    room?: string;
+    userId?: string;
+    feedActions?: string[];
+}): Promise<ShellMultiplayer & {
+    close: () => void;
+}>;

package/dist/multiplayer.js

@@ -1,21 +1,71 @@
+import { adapterOf } from "@jgengine/core/runtime/adapter";
 import { createWsBackend } from "@jgengine/ws/createWsBackend";
-function adapterKind(multiplayer) {
-    if (typeof multiplayer !== "object" || multiplayer === null)
-        return null;
-    const direct = multiplayer.kind;
-    if (typeof direct === "string")
-        return direct;
-    const nested = multiplayer.adapter?.kind;
-    return typeof nested === "string" ? nested : null;
+import { announcePeerHost, broadcastChannelSignaling, createPeerGuest, createPeerHost, joinPeerSession, } from "@jgengine/ws/peer";
+export const DEFAULT_FEED_ACTIONS = ["entity.died"];
+const DEFAULT_WS_URL = "ws://localhost:8080/ws";
+export function randomPlayerId() {
+    return `player-${Math.random().toString(36).slice(2, 10)}`;
+}
+function lanUrl(adapter) {
+    const hasWindow = typeof window !== "undefined";
+    const scheme = hasWindow && window.location.protocol === "https:" ? "wss" : "ws";
+    const hostname = hasWindow ? window.location.hostname : "localhost";
+    const port = adapter.port ?? 8080;
+    const path = adapter.path ?? "/ws";
+    return `${scheme}://${hostname}:${port}${path}`;
+}
+function buildWsMultiplayer(args) {
+    return {
+        gameId: args.gameId,
+        userId: args.userId,
+        backend: createWsBackend({ url: args.url, userId: args.userId }),
+        feedActions: args.feedActions,
+    };
 }
 export function resolveShellMultiplayer(args) {
-    if (args.force !== true && adapterKind(args.game.multiplayer) !== "ws")
+    const userId = args.userId ?? randomPlayerId();
+    const feedActions = args.feedActions ?? DEFAULT_FEED_ACTIONS;
+    const build = (url) => buildWsMultiplayer({ gameId: args.gameId, userId, feedActions, url });
+    if (args.force === true)
+        return build(args.url ?? DEFAULT_WS_URL);
+    const adapter = adapterOf(args.game.multiplayer);
+    if (adapter === null)
         return null;
-    const userId = args.userId ?? `player-${Math.random().toString(36).slice(2, 10)}`;
+    if (adapter.kind === "ws")
+        return build(args.url ?? adapter.url ?? DEFAULT_WS_URL);
+    if (adapter.kind === "lan")
+        return build(args.url ?? lanUrl(adapter));
+    return null;
+}
+export async function resolvePeerShellMultiplayer(args) {
+    const userId = args.userId ?? randomPlayerId();
+    const feedActions = args.feedActions ?? DEFAULT_FEED_ACTIONS;
+    const signaling = broadcastChannelSignaling(args.room ?? `jg-p2p-${args.gameId}`);
+    if (args.role === "host") {
+        const peerHost = createPeerHost({ userId });
+        const stopAnnouncing = announcePeerHost(peerHost, signaling);
+        return {
+            gameId: args.gameId,
+            userId,
+            backend: peerHost.backend,
+            feedActions,
+            close: () => {
+                stopAnnouncing();
+                signaling.close();
+                peerHost.close();
+            },
+        };
+    }
+    const guest = createPeerGuest({ userId });
+    const backend = await joinPeerSession(guest, signaling);
     return {
         gameId: args.gameId,
         userId,
-        backend: createWsBackend({ url: args.url ?? "ws://localhost:8080/ws", userId }),
-        feedActions: args.feedActions ?? ["entity.died"],
+        backend,
+        feedActions,
+        close: () => {
+            signaling.close();
+            guest.close();
+        },
     };
 }

package/dist/pointer/PointerProbe.js

@@ -8,18 +8,31 @@ export function PointerProbe({ service }) {
     service.bind({ camera, scene, width: size.width, height: size.height });
     useEffect(() => {
         const el = gl.domElement;
+        let locked = false;
         const onMove = (event) => {
+            if (locked)
+                return;
             const rect = el.getBoundingClientRect();
             const x = ((event.clientX - rect.left) / rect.width) * 2 - 1;
             const y = -(((event.clientY - rect.top) / rect.height) * 2 - 1);
             service.setCursor(x, y, true);
         };
-        const onLeave = () => service.setCursor(0, 0, false);
+        const onLeave = () => {
+            if (!locked)
+                service.setCursor(0, 0, false);
+        };
+        const onLockChange = () => {
+            locked = document.pointerLockElement === el;
+            if (locked)
+                service.setCursor(0, 0, true);
+        };
         el.addEventListener("pointermove", onMove);
         el.addEventListener("pointerleave", onLeave);
+        document.addEventListener("pointerlockchange", onLockChange);
         return () => {
             el.removeEventListener("pointermove", onMove);
             el.removeEventListener("pointerleave", onLeave);
+            document.removeEventListener("pointerlockchange", onLockChange);
             service.bind(null);
         };
     }, [gl, service]);

package/dist/pointer/pointerService.d.ts

@@ -11,6 +11,8 @@ interface PointerDeps {
 export interface PointerService {
     /** Cast the current cursor into the world; null when the cursor is off-canvas. */
     worldHit(): PointerHit | null;
+    /** Cast from the viewport center regardless of cursor presence (pointer-lock aim); null before the probe binds. */
+    worldHitCenter(): PointerHit | null;
     /** Project a world point to CSS pixels for the marquee / HUD; null before the probe binds. */
     screenOf(world: PointerVec3): {
         x: number;

package/dist/pointer/pointerService.js

@@ -11,14 +11,54 @@ function tagOf(object, key) {
     }
     return null;
 }
+function standardMaterialSample(material) {
+    const candidates = Array.isArray(material) ? material : [material];
+    const standard = candidates.find((entry) => entry instanceof THREE.MeshStandardMaterial);
+    if (standard === undefined)
+        return null;
+    return { color: `#${standard.color.getHexString()}`, metalness: standard.metalness, roughness: standard.roughness };
+}
 export function createPointerService() {
     const raycaster = new THREE.Raycaster();
     const ndc = new THREE.Vector2();
+    const centerNdc = new THREE.Vector2(0, 0);
     const scratch = new THREE.Vector3();
     const normalMatrix = new THREE.Matrix3();
     const groundPlane = new THREE.Plane(new THREE.Vector3(0, 1, 0), 0);
     let deps = null;
     let cursorPresent = false;
+    function hitAtNdc(target) {
+        if (deps === null)
+            return null;
+        raycaster.setFromCamera(target, deps.camera);
+        const intersects = raycaster.intersectObjects(deps.scene.children, true);
+        for (const hit of intersects) {
+            const mesh = hit.object;
+            if (!mesh.isMesh)
+                continue;
+            const point = [hit.point.x, hit.point.y, hit.point.z];
+            let normal = [0, 1, 0];
+            if (hit.face !== null && hit.face !== undefined) {
+                normalMatrix.getNormalMatrix(hit.object.matrixWorld);
+                scratch.copy(hit.face.normal).applyMatrix3(normalMatrix).normalize();
+                normal = [scratch.x, scratch.y, scratch.z];
+            }
+            const uv = hit.uv !== undefined ? { u: hit.uv.x, v: hit.uv.y } : undefined;
+            return {
+                point,
+                normal,
+                entity: tagOf(hit.object, POINTER_ENTITY_KEY),
+                object: tagOf(hit.object, POINTER_OBJECT_KEY),
+                ...(uv !== undefined ? { uv } : {}),
+                material: standardMaterialSample(mesh.material),
+                ...(hit.instanceId !== undefined ? { instanceId: hit.instanceId } : {}),
+            };
+        }
+        const grounded = raycaster.ray.intersectPlane(groundPlane, scratch);
+        if (grounded === null)
+            return null;
+        return { point: [grounded.x, grounded.y, grounded.z], normal: [0, 1, 0], entity: null, object: null };
+    }
     return {
         hasCursor: () => cursorPresent,
         bind: (next) => {
@@ -29,31 +69,12 @@ export function createPointerService() {
             cursorPresent = present;
         },
         worldHit() {
-            if (deps === null || !cursorPresent)
-                return null;
-            raycaster.setFromCamera(ndc, deps.camera);
-            const intersects = raycaster.intersectObjects(deps.scene.children, true);
-            for (const hit of intersects) {
-                if (!hit.object.isMesh)
-                    continue;
-                const point = [hit.point.x, hit.point.y, hit.point.z];
-                let normal = [0, 1, 0];
-                if (hit.face !== null && hit.face !== undefined) {
-                    normalMatrix.getNormalMatrix(hit.object.matrixWorld);
-                    scratch.copy(hit.face.normal).applyMatrix3(normalMatrix).normalize();
-                    normal = [scratch.x, scratch.y, scratch.z];
-                }
-                return {
-                    point,
-                    normal,
-                    entity: tagOf(hit.object, POINTER_ENTITY_KEY),
-                    object: tagOf(hit.object, POINTER_OBJECT_KEY),
-                };
-            }
-            const grounded = raycaster.ray.intersectPlane(groundPlane, scratch);
-            if (grounded === null)
+            if (!cursorPresent)
                 return null;
-            return { point: [grounded.x, grounded.y, grounded.z], normal: [0, 1, 0], entity: null, object: null };
+            return hitAtNdc(ndc);
+        },
+        worldHitCenter() {
+            return hitAtNdc(centerNdc);
         },
         screenOf(world) {
             if (deps === null)

package/dist/registry.d.ts

@@ -1,6 +1,9 @@
 import type { ComponentType, ReactNode } from "react";
 import type { PlayableGame as EnginePlayableGame } from "@jgengine/core/game/playableGame";
 import type { SceneEntity } from "@jgengine/core/scene/entityStore";
+import type { SceneObject } from "@jgengine/core/scene/objectStore";
 export type RenderEntity = (entity: SceneEntity) => ReactNode;
-export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity>;
+export type RenderObject = (object: SceneObject) => ReactNode;
+export type PlayableGame = EnginePlayableGame<ComponentType, ComponentType, RenderEntity, RenderObject>;
 export type GameRegistry = Record<string, () => Promise<PlayableGame>>;
+export declare function resolveGameLoader(registry: GameRegistry, gameId: string, fallbackGameId?: string): (() => Promise<PlayableGame>) | undefined;

package/dist/registry.js

@@ -1 +1,3 @@
-export {};
+export function resolveGameLoader(registry, gameId, fallbackGameId) {
+    return registry[gameId] ?? (fallbackGameId === undefined ? undefined : registry[fallbackGameId]);
+}

package/dist/render/modelRender.d.ts

@@ -0,0 +1,14 @@
+import * as THREE from "three";
+import type { PaintStroke } from "@jgengine/core/scene/paintLayer";
+export declare const PAINT_TEXTURE_SIZE = 512;
+export declare function cloneModelScene(source: THREE.Object3D): THREE.Object3D;
+export declare function standardMaterialsOf(root: THREE.Object3D): THREE.MeshStandardMaterial[];
+export interface PaintCanvas {
+    canvas: HTMLCanvasElement;
+    context: CanvasRenderingContext2D;
+    texture: THREE.CanvasTexture;
+}
+export declare function createPaintCanvas(seed: THREE.MeshStandardMaterial, size?: number): PaintCanvas;
+export declare function drawPaintStrokes(paint: PaintCanvas, strokes: readonly PaintStroke[]): void;
+export declare function applyPaintTexture(root: THREE.Object3D, paint: PaintCanvas): void;
+export declare function syncPaintCanvas(paint: PaintCanvas, seedColor: THREE.Color, strokes: readonly PaintStroke[], drawnCount: number): number;