@jgengine/shell 0.22.0 → 0.24.0

package/dist/commandSink.js

@@ -11,10 +11,15 @@ export function localCommandSink(ctx) {
 /** Sends commands to the authoritative host over the transport; the result replicates back through world sync.
  * @internal
  */
-export function remoteCommandSink(backend, serverId) {
+export function remoteCommandSink(backend, serverId, events) {
     return {
         run(name, input) {
-            void backend.transport.runCommand({ serverId, command: name, input }).catch(() => undefined);
+            void backend.transport.runCommand({ serverId, command: name, input }).then((result) => {
+                // Host refusals reach the local notice feed the same way local ones do.
+                if (!result.ok && result.message !== undefined) {
+                    events?.emit("command.refused", { command: name, reason: result.reason, message: result.message, actor: null });
+                }
+            }).catch(() => undefined);
         },
     };
 }
@@ -25,7 +30,7 @@ export function remoteCommandSink(backend, serverId) {
   */
 export function resolveCommandSink(ctx, opts) {
     if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
-        return remoteCommandSink(opts.backend, opts.serverId);
+        return remoteCommandSink(opts.backend, opts.serverId, ctx.game.events);
     }
     if (opts.serverAuthoritative)
         return { run() { } };

package/dist/defineGame.js

@@ -55,7 +55,7 @@ const emptyUi = () => null;
  * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
  */
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, sceneFlockModels, scenePathKinds, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, gamepad, localPlayers, viewports, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting: authoredLighting, environmentSource, backdrop, look, postProcessing, shadows, graphics, presentation, settings, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, sceneFlockModels, scenePathKinds, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, gamepad, localPlayers, viewports, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting: authoredLighting, environmentSource, backdrop, look, postProcessing, shadows, graphics, presentation, settings, notices, objectStyles, devtools, capture, platforms, hudFit, hudTheme, ...engineFields } = config;
     const game = defineEngineGame({
         ...engineFields,
         ...(editorLayers === undefined ? {} : { authoredDocument: editorLayers }),
@@ -133,10 +133,12 @@ export function defineGame(config) {
         graphics,
         presentation,
         settings,
+        notices,
         objectStyles,
         devtools,
         capture,
         platforms,
         hudFit,
+        hudTheme,
     };
 }

package/dist/devtools/DevtoolsOverlay.js

@@ -20,6 +20,7 @@ export function DevtoolsRendererProbe() {
     useEffect(() => devtools.probes.register("heavyModels", () => heavyModels()), []);
     const gl = useThree((state) => state.gl);
     const lastSampleAt = useRef(0);
+    useEffect(() => devtools.probes.register("shaderPrograms", () => gl.info.programs?.length ?? 0), [gl]);
     useEffect(() => {
         // three resets gl.info after every render() call, so with a multi-pass
         // composer the counters only ever hold the last fullscreen pass. Own the

package/dist/devtools/agentBridge.d.ts

@@ -1,3 +1,4 @@
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { PlayableGame } from "../registry.js";
 /** One RPC call into the agent bridge: a verb name plus its verb-specific fields. */
 export type AgentBridgeRequest = {
@@ -11,6 +12,24 @@ export type AgentBridgeResponse = {
     ok: false;
     error: string;
 };
+/**
+ * @internal
+ * The local player's live pose for `player_pose` / `debug_snapshot`, so a drive can measure movement
+ * (position deltas between two RPCs) instead of judging it from screenshots. `null` before the game
+ * context exists or before the player entity spawns.
+ */
+export declare function playerPoseReport(ctx: GameContext | null): {
+    userId: string;
+    position: readonly [number, number, number];
+    rotationY: number;
+} | null;
+/**
+ * @internal
+ * `time_scale` verb: sets the game clock's global timescale (`ctx.time.setTimescale`) so a headless
+ * drive can fast-forward timers, economies and day cycles that never finish at capture frame rates.
+ * Large scales take large steps — use it for clocks, not to judge movement. Omit `scale` to read.
+ */
+export declare function applyTimeScale(ctx: Pick<GameContext, "time">, scale: unknown): AgentBridgeResponse;
 type EditorHost = {
     gameId: string;
     handle(request: AgentBridgeRequest): unknown;
@@ -43,5 +62,7 @@ export declare function installAgentBridge(options: {
     devtoolsEnabled: boolean;
     isDevtoolsOpen: () => boolean;
     setDevtoolsOpen: (open: boolean) => void;
+    /** Live game context, once mounted; feeds `player_pose`. */
+    getContext?: () => GameContext | null;
 }): () => void;
 export {};

package/dist/devtools/agentBridge.js

@@ -2,7 +2,39 @@ import { devtools } from "@jgengine/core/devtools/devtools";
 import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { isHudAnchor, listActiveHudLayouts, } from "@jgengine/core/ui/hudLayout";
 import { listHudPanelTypes, resolvePanelResize, resizePanelSize, } from "@jgengine/core/ui/hudDocument";
-import { buildFullReport, buildLeanReport } from "./devtoolsReports.js";
+import { buildFullReport, buildLeanReport, summarizeLeanReport } from "./devtoolsReports.js";
+import { advanceSimulation } from "./simStepper.js";
+/**
+ * @internal
+ * The local player's live pose for `player_pose` / `debug_snapshot`, so a drive can measure movement
+ * (position deltas between two RPCs) instead of judging it from screenshots. `null` before the game
+ * context exists or before the player entity spawns.
+ */
+export function playerPoseReport(ctx) {
+    if (ctx === null)
+        return null;
+    const entity = ctx.scene.entity.get(ctx.player.userId);
+    if (entity === null || entity === undefined)
+        return null;
+    const [x, y, z] = entity.position;
+    const round = (value) => Math.round(value * 1000) / 1000;
+    return { userId: ctx.player.userId, position: [round(x), round(y), round(z)], rotationY: round(entity.rotationY ?? 0) };
+}
+/**
+ * @internal
+ * `time_scale` verb: sets the game clock's global timescale (`ctx.time.setTimescale`) so a headless
+ * drive can fast-forward timers, economies and day cycles that never finish at capture frame rates.
+ * Large scales take large steps — use it for clocks, not to judge movement. Omit `scale` to read.
+ */
+export function applyTimeScale(ctx, scale) {
+    if (scale !== undefined) {
+        if (typeof scale !== "number" || !Number.isFinite(scale) || scale < 0 || scale > 120) {
+            return { ok: false, error: "time_scale needs { scale } between 0 and 120 (1 = normal)" };
+        }
+        ctx.time.setTimescale(scale);
+    }
+    return { ok: true, timescale: ctx.time.timescale(), now: Math.round(ctx.time.now() * 1000) / 1000 };
+}
 /**
  * @internal
  * Resolves true once `isLive()` reports a mounted editor host, polling every `intervalMs` up to
@@ -91,6 +123,7 @@ function panelLayoutSnapshot(placement, extras) {
  */
 export function installAgentBridge(options) {
     const { playable, devtoolsEnabled, isDevtoolsOpen, setDevtoolsOpen } = options;
+    const getContext = options.getContext ?? (() => null);
     const handle = (request) => {
         const method = typeof request?.method === "string" ? request.method : "";
         switch (method) {
@@ -115,8 +148,67 @@ export function installAgentBridge(options) {
                 setDevtoolsOpen(open);
                 return { ok: true, open };
             }
-            case "debug_snapshot":
-                return { ok: true, snapshot: buildLeanReport(playable) };
+            case "debug_summary":
+            case "debug_snapshot": {
+                const ctx = getContext();
+                const lean = buildLeanReport(playable);
+                if (method === "debug_summary" || request.detail === "summary") {
+                    const entities = ctx === null ? null : ctx.scene.entity.ids().length;
+                    return { ok: true, summary: { ...summarizeLeanReport(lean, entities), player: playerPoseReport(ctx) } };
+                }
+                return { ok: true, snapshot: { ...lean, player: playerPoseReport(ctx) } };
+            }
+            case "player_pose": {
+                const pose = playerPoseReport(getContext());
+                return pose === null ? { ok: false, error: "no local player entity yet" } : { ok: true, ...pose };
+            }
+            case "time_scale": {
+                const ctx = getContext();
+                if (ctx === null)
+                    return { ok: false, error: "no game context yet" };
+                return applyTimeScale(ctx, request.scale);
+            }
+            case "sim_advance": {
+                const seconds = request.seconds;
+                if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds <= 0 || seconds > 120) {
+                    return { ok: false, error: "sim_advance needs { seconds } in (0, 120]" };
+                }
+                return advanceSimulation(seconds).then((frames) => {
+                    if (frames === null)
+                        return { ok: false, error: "no sim driver mounted" };
+                    const ctx = getContext();
+                    return { ok: true, frames, now: ctx === null ? null : Math.round(ctx.time.now() * 1000) / 1000 };
+                });
+            }
+            case "notice_push": {
+                const ctx = getContext();
+                if (ctx === null)
+                    return { ok: false, error: "no game context yet" };
+                const tone = request.tone;
+                if (typeof request.text !== "string" || (tone !== undefined && tone !== "info" && tone !== "success" && tone !== "warn" && tone !== "deny")) {
+                    return { ok: false, error: "notice_push needs { text, tone?: info|success|warn|deny, ttlMs? }" };
+                }
+                const ttlMs = typeof request.ttlMs === "number" && request.ttlMs > 0 ? request.ttlMs : undefined;
+                const notice = ctx.game.notices.push({ text: request.text, ...(tone === undefined ? {} : { tone }), ...(ttlMs === undefined ? {} : { ttlMs }) });
+                return { ok: true, id: notice.id, count: notice.count };
+            }
+            case "notice_list": {
+                const ctx = getContext();
+                if (ctx === null)
+                    return { ok: false, error: "no game context yet" };
+                return { ok: true, notices: ctx.game.notices.list(), rendered: document.querySelectorAll("[data-jg-notice]").length, now: Date.now() };
+            }
+            case "run_command": {
+                const ctx = getContext();
+                if (ctx === null)
+                    return { ok: false, error: "no game context yet" };
+                if (typeof request.name !== "string")
+                    return { ok: false, error: "run_command needs { name, input? }" };
+                const result = ctx.game.commands.run(request.name, request.input ?? {});
+                return result.status === "rejected"
+                    ? { ok: true, status: result.status, reason: result.reason, ...(result.message === undefined ? {} : { message: result.message }) }
+                    : { ok: true, status: result.status };
+            }
             case "debug_report":
                 return { ok: true, report: buildFullReport(playable) };
             case "debug_perf_reset":

package/dist/devtools/devtoolsReports.d.ts

@@ -66,3 +66,35 @@ export declare function buildLeanReport(playable: PlayableGame): {
 export declare function buildFullReport(playable: PlayableGame): DevtoolsSnapshot & {
     game: string;
 };
+/** Compact `debug_summary` payload: the numbers an agent needs to judge a run, about 1 KB. */
+export interface DebugSummary {
+    game: string;
+    fps: number | null;
+    frameMs: {
+        avg: number;
+        p95: number;
+    } | null;
+    simMs: number | null;
+    outsideSimMs: number | null;
+    drawCalls: number | null;
+    triangles: number | null;
+    entities: number | null;
+    longFrames: number;
+    topCulprit: {
+        culprit: string;
+        count: number;
+    } | null;
+    topPhase: {
+        name: string;
+        avgMs: number;
+    } | null;
+    warnings: number;
+    lastWarnings: string[];
+    why: string | null;
+}
+/**
+ * Reduce a lean report to {@link DebugSummary}: no per-frame probe arrays, no control lists, at most
+ * three warning lines of 160 characters. `debug_snapshot` with `detail: "full"` keeps everything.
+ * @internal
+ */
+export declare function summarizeLeanReport(lean: ReturnType<typeof buildLeanReport>, entities: number | null): DebugSummary;

package/dist/devtools/devtoolsReports.js

@@ -98,3 +98,29 @@ export function buildLeanReport(playable) {
 export function buildFullReport(playable) {
     return { game: playable.game.name, ...devtools.snapshot() };
 }
+/**
+ * Reduce a lean report to {@link DebugSummary}: no per-frame probe arrays, no control lists, at most
+ * three warning lines of 160 characters. `debug_snapshot` with `detail: "full"` keeps everything.
+ * @internal
+ */
+export function summarizeLeanReport(lean, entities) {
+    const frame = lean.frame;
+    const logs = lean.logs ?? [];
+    const phase = frame?.phases[0];
+    return {
+        game: lean.game,
+        fps: frame?.fps ?? null,
+        frameMs: frame === null ? null : { avg: frame.avgFrameMs, p95: frame.p95FrameMs },
+        simMs: frame?.avgSimMs ?? null,
+        outsideSimMs: frame?.avgOutsideMs ?? null,
+        drawCalls: lean.render?.drawCalls ?? null,
+        triangles: lean.render?.triangles ?? null,
+        entities,
+        longFrames: lean.longFrameSummary?.count ?? 0,
+        topCulprit: lean.longFrameSummary?.culprits[0] ?? null,
+        topPhase: phase === undefined ? null : { name: phase.name, avgMs: phase.avgMs },
+        warnings: logs.length,
+        lastWarnings: logs.slice(-3).map((entry) => `${entry.level}: ${entry.message}`.slice(0, 160)),
+        why: lean.why === null ? null : lean.why.split(/(?<=[.:])\s/)[0].slice(0, 200),
+    };
+}

package/dist/devtools/simStepper.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The mounted sim driver's per-frame step, registered so the agent bridge can fast-forward the
+ * simulation without rendering (`sim_advance`). Headless software rendering runs at well under
+ * 1 fps, so timers, waves and economies otherwise never complete inside a drive capture.
+ * @internal
+ */
+export type SimStep = (rawDt: number) => void;
+/** Register the active driver's step; returns the unregister. Last registration wins. @internal */
+export declare function registerSimStepper(step: SimStep): () => void;
+/**
+ * Step the registered simulation `seconds` of real time in `step`-second frames (each frame runs
+ * the full driver step: input, movement, `onTick`, behaviors, bound actions). Frames run in
+ * batches of {@link FRAMES_PER_YIELD} with a macrotask between batches, so React commits what the
+ * sim spawned along the way — models for entities created mid-advance mount as they would in play,
+ * instead of one burst the renderer never catches up with. Capped at 2400 frames per call.
+ * Resolves to the frames run, or `null` when no driver is mounted.
+ * @internal
+ */
+export declare function advanceSimulation(seconds: number, step?: number, yieldToHost?: () => Promise<void>): Promise<number | null>;
+/** Simulated frames between yields to the host (ten game seconds at 0.05 s frames): each yield can cost a full render frame, which headless software rendering spends seconds on. @internal */
+export declare const FRAMES_PER_YIELD = 200;

package/dist/devtools/simStepper.js

@@ -0,0 +1,37 @@
+let current = null;
+/** Register the active driver's step; returns the unregister. Last registration wins. @internal */
+export function registerSimStepper(step) {
+    current = step;
+    return () => {
+        if (current === step)
+            current = null;
+    };
+}
+/**
+ * Step the registered simulation `seconds` of real time in `step`-second frames (each frame runs
+ * the full driver step: input, movement, `onTick`, behaviors, bound actions). Frames run in
+ * batches of {@link FRAMES_PER_YIELD} with a macrotask between batches, so React commits what the
+ * sim spawned along the way — models for entities created mid-advance mount as they would in play,
+ * instead of one burst the renderer never catches up with. Capped at 2400 frames per call.
+ * Resolves to the frames run, or `null` when no driver is mounted.
+ * @internal
+ */
+export async function advanceSimulation(seconds, step = 0.05, yieldToHost = defaultYield) {
+    if (current === null)
+        return null;
+    const frame = Math.min(0.05, Math.max(0.001, step));
+    const frames = Math.min(2400, Math.max(0, Math.ceil(seconds / frame)));
+    for (let index = 0; index < frames; index += 1) {
+        if (current === null)
+            return index;
+        current(frame);
+        if ((index + 1) % FRAMES_PER_YIELD === 0 && index + 1 < frames)
+            await yieldToHost();
+    }
+    return frames;
+}
+/** Simulated frames between yields to the host (ten game seconds at 0.05 s frames): each yield can cost a full render frame, which headless software rendering spends seconds on. @internal */
+export const FRAMES_PER_YIELD = 200;
+function defaultYield() {
+    return new Promise((resolve) => setTimeout(resolve, 0));
+}

package/dist/drivers/FrameDriver.js

@@ -1,5 +1,5 @@
 import { useFrame } from "@react-three/fiber";
-import { useMemo, useRef } from "react";
+import { useEffect, useMemo, useRef } from "react";
 import { RESERVED_INPUT_ACTIONS, dispatchBoundAction, heldActionsFor, shouldFireBoundAction } from "../boundActionDispatch.js";
 import { executeHotbarSlot, findHotbarSlotActions, hotbarIdFor } from "../hotbarActions.js";
 import { pointerAimFor } from "../shellPointer.js";
@@ -17,6 +17,7 @@ import { DEFAULT_PICKUP_RADIUS } from "@jgengine/core/game/worldItem";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
 import { devtools } from "@jgengine/core/devtools/devtools";
 import { collisionDebug } from "../devtools/collisionDebug.js";
+import { registerSimStepper } from "../devtools/simStepper.js";
 import { GAME_SIM_FRAME_PRIORITY } from "../camera/index.js";
 import { NO_ACTIONS } from "../shellConstants.js";
 import { createPredictionBuffer } from "@jgengine/core/runtime/prediction";
@@ -79,17 +80,10 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
             ctx.scene.entity.setPose(playerId, { position: current });
     }, [ctx]);
     authoritativeFrameRef.current = serverAuthoritative ? predictionHandler : null;
-    useFrame((_state, rawDt) => {
-        if (poster) {
-            if (posterDoneRef.current)
-                return;
-            posterElapsedRef.current += Math.min(rawDt, 0.05);
-            if (posterElapsedRef.current >= POSTER_SETTLE_SECONDS) {
-                posterDoneRef.current = true;
-                onPosterSettled();
-                return;
-            }
-        }
+    // One frame of simulation — input, movement, onTick, behaviors, bound actions — shared by the
+    // render loop and the agent bridge's render-free `sim_advance`.
+    /** Returns false when play is gated (menu, pause) and nothing advanced. */
+    const simulate = (rawDt) => {
         const sendInput = () => {
             if (!serverAuthoritative)
                 return;
@@ -109,9 +103,8 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
             ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS), { reset: true });
             ctx.input.publishAnalog(null);
             sendInput();
-            return;
+            return false;
         }
-        const simStart = performance.now();
         try {
             let endPhase = devtools.profile.begin("time+input");
             const dt = Math.min(rawDt, 0.05);
@@ -280,6 +273,25 @@ export function FrameDriver({ ctx, playable, tracker, yawRef, pitchRef, primaryC
                 onRuntimeError(error, "tick");
             }
         }
+        return true;
+    };
+    const simulateRef = useRef(simulate);
+    simulateRef.current = simulate;
+    useEffect(() => (poster ? undefined : registerSimStepper((rawDt) => simulateRef.current(rawDt))), [poster]);
+    useFrame((_state, rawDt) => {
+        if (poster) {
+            if (posterDoneRef.current)
+                return;
+            posterElapsedRef.current += Math.min(rawDt, 0.05);
+            if (posterElapsedRef.current >= POSTER_SETTLE_SECONDS) {
+                posterDoneRef.current = true;
+                onPosterSettled();
+                return;
+            }
+        }
+        const simStart = performance.now();
+        if (!simulate(rawDt))
+            return;
         devtools.frame.record({ frameMs: rawDt * 1000, simMs: performance.now() - simStart });
     }, GAME_SIM_FRAME_PRIORITY);
     return null;

package/dist/drivers/HudOnlyDriver.js

@@ -7,6 +7,7 @@ import { isServerAuthoritative } from "@jgengine/core/runtime/adapter";
 import { resolveCommandSink } from "../commandSink.js";
 import { inputFramesEqual, resolveInputSink } from "../inputSink.js";
 import { EMPTY_RESERVED, NO_ACTIONS } from "../shellConstants.js";
+import { registerSimStepper } from "../devtools/simStepper.js";
 export function HudOnlyDriver({ ctx, multiplayer, serverIdRef, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, }) {
     const hasReportedTickError = useRef(false);
     const repeatFiredAtRef = useRef(new Map());
@@ -22,6 +23,14 @@ export function HudOnlyDriver({ ctx, multiplayer, serverIdRef, playable, tracker
             lastFrameRef.current = now;
             if (last === null)
                 return;
+            const rawDt = (now - last) / 1000;
+            const simStart = performance.now();
+            if (!simulate(rawDt))
+                return;
+            devtools.frame.record({ frameMs: rawDt * 1000, simMs: performance.now() - simStart });
+        };
+        /** One frame of simulation; false when play is gated and nothing advanced. Shared with `sim_advance`. */
+        const simulate = (rawDt) => {
             const sendInput = () => {
                 if (!serverAuthoritative || serverIdRef.current === null)
                     return;
@@ -35,10 +44,8 @@ export function HudOnlyDriver({ ctx, multiplayer, serverIdRef, playable, tracker
                 ctx.input.publish(heldActionsFor(tracker, NO_ACTIONS), { reset: true });
                 ctx.input.publishAnalog(null);
                 sendInput();
-                return;
+                return false;
             }
-            const rawDt = (now - last) / 1000;
-            const simStart = performance.now();
             try {
                 let endPhase = devtools.profile.begin("time+input");
                 const dt = Math.min(rawDt, 0.05);
@@ -74,10 +81,14 @@ export function HudOnlyDriver({ ctx, multiplayer, serverIdRef, playable, tracker
                     onRuntimeError(error, "tick");
                 }
             }
-            devtools.frame.record({ frameMs: rawDt * 1000, simMs: performance.now() - simStart });
+            return true;
         };
         frameId = requestAnimationFrame(tick);
-        return () => cancelAnimationFrame(frameId);
+        const unregister = registerSimStepper((rawDt) => { simulate(rawDt); });
+        return () => {
+            cancelAnimationFrame(frameId);
+            unregister();
+        };
     }, [ctx, playable, tracker, pointerAxisRef, gateRef, onRuntimeError, inputActions, multiplayer, serverIdRef, serverAuthoritative]);
     return null;
 }

package/dist/environment/EnvironmentScene.js

@@ -20,6 +20,8 @@ import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
 import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
 import { createTerrainDetailMaterial } from "../terrain/terrainDetailMaterial.js";
+import { useTerrainQuality } from "../terrain/terrainQuality.js";
+import { createTerrainPaintTextures, packTerrainPaintWeights } from "../terrain/terrainSurfaces.js";
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 import { SnowField } from "../weather/SnowField.js";
@@ -39,11 +41,20 @@ function TexturedTerrainGround({ detail, layout, }) {
             texture.needsUpdate = true;
         }
     }, [textures]);
-    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures).material, [detail, textures]);
-    return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, paintColorAt: layout.paintColorAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
+    const quality = useTerrainQuality();
+    const material = useDisposable(() => createTerrainDetailMaterial(detail, textures, { paint: layout.paint, quality }).material, [detail, textures, layout.paint, quality]);
+    return (_jsxs(_Fragment, { children: [_jsx(PresentationRecoveredDraw, {}), _jsx(CarvedTerrain, { field: layout.field, size: layout.size, segments: layout.segments, colors: layout.colors, heightRange: layout.heightRange, paletteAt: layout.paletteAt, center: layout.center, roughness: 0.94, surfaceMaterial: material })] }));
 }
 function TerrainGround({ terrain, field, center, sculpt, }) {
-    const paintColorAt = useMemo(() => sculpt === undefined ? undefined : createTerrainPaintColorSampler(editableTerrainFromSnapshot(sculpt)), [sculpt]);
+    const detailEnabled = terrain.detail !== false;
+    const paint = useMemo(() => {
+        if (!detailEnabled || sculpt === undefined)
+            return undefined;
+        const weights = packTerrainPaintWeights(editableTerrainFromSnapshot(sculpt));
+        return weights === undefined ? undefined : createTerrainPaintTextures(weights);
+    }, [detailEnabled, sculpt]);
+    useEffect(() => () => paint?.dispose(), [paint]);
+    const paintColorAt = useMemo(() => detailEnabled || sculpt === undefined ? undefined : createTerrainPaintColorSampler(editableTerrainFromSnapshot(sculpt)), [detailEnabled, sculpt]);
     const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
     const paletteAt = useMemo(() => {
         const hasRegions = terrain.materialRegions !== undefined && terrain.materialRegions.length > 0;
@@ -66,13 +77,14 @@ function TerrainGround({ terrain, field, center, sculpt, }) {
         const swing = terrain.height * 1.2;
         return [base - swing, base + swing];
     }, [terrain.baseHeight, terrain.height]);
-    const resolvedDetail = useMemo(() => (terrain.detail === undefined ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
+    const resolvedDetail = useMemo(() => (terrain.detail === false ? undefined : resolveTerrainDetail(terrain.detail, terrain.waterLevel)), [terrain.detail, terrain.waterLevel]);
+    const quality = useTerrainQuality();
     const proceduralMaterial = useMemo(() => resolvedDetail === undefined || resolvedDetail.material !== undefined
         ? undefined
-        : createTerrainDetailMaterial(resolvedDetail).material, [resolvedDetail]);
+        : createTerrainDetailMaterial(resolvedDetail, undefined, { paint, quality }).material, [resolvedDetail, paint, quality]);
     useEffect(() => () => proceduralMaterial?.dispose(), [proceduralMaterial]);
     if (resolvedDetail?.material !== undefined) {
-        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paintColorAt, center } }) }));
+        return (_jsx(PresentationAssetBoundary, { children: _jsx(TexturedTerrainGround, { detail: resolvedDetail, layout: { field, size, segments: terrain.segments, colors, heightRange, paletteAt, paint, center } }) }));
     }
     return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, paintColorAt: paintColorAt, center: center, roughness: 0.94, surfaceMaterial: proceduralMaterial }));
 }
@@ -163,5 +175,5 @@ export function EnvironmentScene({ feature }) {
     const roads = feature.roads ?? [];
     const junctions = useMemo(() => findRoadJunctions(roads), [roads]);
     const roadNetwork = useMemo(() => buildAuthoredRoadNetwork(roads, junctions, (x, z) => field.sampleHeight(x, z)), [roads, junctions, field]);
-    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field, sculpt: feature.sculpt }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin, sculpt: feature.sculpt }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, paths: roadNetwork.roadPaths[index] ?? [] }, `road-${index}`))), _jsx(RoadJunctions, { surfaces: roadNetwork.junctionSurfaces, junctions: junctions, field: field }), 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, groundColor: vegetationGroundColor(feature.terrain, field, grass, feature.sculpt) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field, sculpt: feature.sculpt }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin, sculpt: feature.sculpt }, `island-${index}`))), water.map((ocean, index) => (_jsx(Water, { ocean: ocean }, `ocean-${index}`))), roads.map((entry, index) => (_jsx(RoadRibbons, { road: entry, field: field, paths: roadNetwork.roadPaths[index] ?? [] }, `road-${index}`))), _jsx(RoadJunctions, { surfaces: roadNetwork.junctionSurfaces, junctions: junctions, field: field, surfaceDetail: roads.some((road) => road.surface !== false) }), 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, groundColor: vegetationGroundColor(feature.terrain, field, grass, feature.sculpt) }, `grass-${index}`))), feature.weather !== undefined && feature.weather.length > 0 ? (_jsx(Weather, { weather: feature.weather })) : null] }));
 }

package/dist/environment/RoadJunctions.d.ts

@@ -9,8 +9,10 @@ import type { JunctionSurface } from "./RoadRibbons.js";
  * `polygonOffset`/`renderOrder` so they win the depth test on sloped ground.
  * @internal
  */
-export declare function RoadJunctions({ surfaces, junctions, field, }: {
+export declare function RoadJunctions({ surfaces, junctions, field, surfaceDetail, }: {
     surfaces: readonly JunctionSurface[];
     junctions: readonly RoadJunction[];
     field: TerrainField;
+    /** Shade the welded surfaces with the asphalt procedural surface, matching the ribbons. Default true. */
+    surfaceDetail?: boolean;
 }): import("react").JSX.Element | null;

package/dist/environment/RoadJunctions.js

@@ -3,6 +3,13 @@ import { useMemo } from "react";
 import { BufferAttribute, BufferGeometry, DoubleSide } from "three";
 import { buildRoadRibbon, GROUND_DECAL_LAYERS } from "@jgengine/core/world/roads";
 import { junctionMarkings } from "@jgengine/core/world/streets";
+import { useSurfaceRibbonMaterial } from "../terrain/surfaceRibbonMaterial.js";
+import { useTerrainQuality } from "../terrain/terrainQuality.js";
+function JunctionPatch({ geometry, color, surfaceDetail }) {
+    const quality = useTerrainQuality();
+    const material = useSurfaceRibbonMaterial(surfaceDetail ? { surface: "road", color, halfWidth: 1, quality } : null);
+    return (_jsx("mesh", { geometry: geometry, receiveShadow: true, ...(material === null ? {} : { material }), children: material === null ? _jsx("meshStandardMaterial", { color: color, roughness: 0.95, metalness: 0, side: DoubleSide }) : null }));
+}
 /** Lane paint sits the table's road→marking gap above the welded junction surface (also polygonOffset). */
 const MARKING_LIFT = GROUND_DECAL_LAYERS.marking - GROUND_DECAL_LAYERS.road;
 function toGeometry(positions, indices) {
@@ -43,7 +50,7 @@ function mergedBars(bars, width, field, elevation) {
  * `polygonOffset`/`renderOrder` so they win the depth test on sloped ground.
  * @internal
  */
-export function RoadJunctions({ surfaces, junctions, field, }) {
+export function RoadJunctions({ surfaces, junctions, field, surfaceDetail = true, }) {
     const patches = useMemo(() => surfaces
         .map((surface) => ({ color: surface.color, geometry: toGeometry(surface.ribbon.positions, surface.ribbon.indices) }))
         .filter((entry) => entry.geometry !== null), [surfaces]);
@@ -66,5 +73,5 @@ export function RoadJunctions({ surfaces, junctions, field, }) {
     }, [junctions, field]);
     if (patches.length === 0 && markings.stops === null && markings.crosswalks === null)
         return null;
-    return (_jsxs("group", { children: [patches.map((patch, index) => (_jsx("mesh", { geometry: patch.geometry, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: patch.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }, `junction-${index}`))), markings.stops !== null ? (_jsx("mesh", { geometry: markings.stops, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, markings.crosswalks !== null ? (_jsx("mesh", { geometry: markings.crosswalks, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null] }));
+    return (_jsxs("group", { children: [patches.map((patch, index) => (_jsx(JunctionPatch, { geometry: patch.geometry, color: patch.color, surfaceDetail: surfaceDetail }, `junction-${index}`))), markings.stops !== null ? (_jsx("mesh", { geometry: markings.stops, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, markings.crosswalks !== null ? (_jsx("mesh", { geometry: markings.crosswalks, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: "#e6e9ee", roughness: 0.85, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null] }));
 }

package/dist/environment/RoadRibbons.d.ts

@@ -40,7 +40,9 @@ export declare function buildAuthoredRoadNetwork(roads: readonly RoadEnvironment
  * by {@link buildAuthoredRoadNetwork}): an asphalt ribbon, a curb/edge strip along each border, an
  * optional dashed centerline, and optional sidewalks. Because the sub-paths already stop at the
  * junction boundary, every layer naturally ends there — no ribbon ploughs through the crossing and
- * the dashed line no longer needs exclusion circles to skip intersections.
+ * the dashed line no longer needs exclusion circles to skip intersections. The carriageway, curbs and
+ * sidewalks shade with the terrain's procedural surfaces (`road.surface`, default asphalt with tyre
+ * wear); `surface: false` keeps them flat.
  */
 export declare function RoadRibbons({ road, field, paths, }: {
     road: RoadEnvironmentDescriptor;

package/dist/environment/RoadRibbons.js

@@ -3,6 +3,8 @@ import { useMemo } from "react";
 import { BufferAttribute, BufferGeometry, Color, DoubleSide } from "three";
 import { buildJunctionSurface, buildRoadRibbon, dashSegments, GROUND_DECAL_LAYERS, trimPathAtJunctions, } from "@jgengine/core/world/roads";
 import { offsetPath, sidewalkWidthOf } from "@jgengine/core/world/streets";
+import { resolvePathSurface, RIBBON_FRAME_ATTRIBUTE, ribbonSurfaceFrame, useSurfaceRibbonMaterial, } from "../terrain/surfaceRibbonMaterial.js";
+import { useTerrainQuality } from "../terrain/terrainQuality.js";
 /**
  * Decal sub-layers as small lifts above each road's authored base `elevation`, spaced by the
  * single-owner {@link GROUND_DECAL_LAYERS} table so the edge strip and lane paint never z-fight the
@@ -47,7 +49,9 @@ function mergeRibbons(ribbons) {
         vertexOffset += ribbon.positions.length;
         indexOffset += ribbon.indices.length;
     }
-    return toGeometry(positions, indices);
+    const geometry = toGeometry(positions, indices);
+    geometry?.setAttribute(RIBBON_FRAME_ATTRIBUTE, new BufferAttribute(ribbonSurfaceFrame(ribbons.map((r) => r.positions)), 3));
+    return geometry;
 }
 /** Convert a detected {@link RoadJunction} into the structural {@link RoadJunctionInput} the trimmer wants. @internal */
 export function roadJunctionInput(junction) {
@@ -150,7 +154,9 @@ export function buildAuthoredRoadNetwork(roads, junctions, sampleHeight) {
  * by {@link buildAuthoredRoadNetwork}): an asphalt ribbon, a curb/edge strip along each border, an
  * optional dashed centerline, and optional sidewalks. Because the sub-paths already stop at the
  * junction boundary, every layer naturally ends there — no ribbon ploughs through the crossing and
- * the dashed line no longer needs exclusion circles to skip intersections.
+ * the dashed line no longer needs exclusion circles to skip intersections. The carriageway, curbs and
+ * sidewalks shade with the terrain's procedural surfaces (`road.surface`, default asphalt with tyre
+ * wear); `surface: false` keeps them flat.
  */
 export function RoadRibbons({ road, field, paths, }) {
     const asphalt = useMemo(() => mergeRibbons(paths.map((path) => buildRoadRibbon(path, road.width, (x, z) => field.sampleHeight(x, z), { elevation: road.elevation }))), [paths, road.width, road.elevation, field]);
@@ -192,7 +198,14 @@ export function RoadRibbons({ road, field, paths, }) {
         }
         return mergeRibbons(ribbons);
     }, [paths, road, field]);
+    const quality = useTerrainQuality();
+    const detailed = road.surface !== false;
+    const style = detailed ? resolvePathSurface("road", road.width, { surface: road.surface ?? "road" }) : null;
+    const asphaltMaterial = useSurfaceRibbonMaterial(style === null ? null : { surface: style.surface, wear: style.wear, color: road.color, halfWidth: road.width / 2, quality });
+    const curbMaterial = useSurfaceRibbonMaterial(detailed ? { surface: "concrete", color: curbColor, halfWidth: road.width / 2, roughness: 0.9, quality } : null);
+    const sidewalkColor = road.sidewalk === false ? "#a7adb8" : road.sidewalk.color;
+    const sidewalkMaterial = useSurfaceRibbonMaterial(detailed && sidewalks !== null ? { surface: "pavement", color: sidewalkColor, halfWidth: road.width / 2, roughness: 0.9, scale: 1.6, quality } : null);
     if (asphalt === null)
         return null;
-    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) }), curbs !== null ? (_jsx("mesh", { geometry: curbs, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: curbColor, roughness: 0.9, metalness: 0, side: DoubleSide }) })) : null, dashes !== null ? (_jsx("mesh", { geometry: dashes, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: road.markingColor, roughness: 0.8, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, sidewalks !== null ? (_jsx("mesh", { geometry: sidewalks, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: road.sidewalk === false ? "#a7adb8" : road.sidewalk.color, roughness: 0.9, metalness: 0, side: DoubleSide }) })) : null] }));
+    return (_jsxs("group", { children: [_jsx("mesh", { geometry: asphalt, receiveShadow: true, ...(asphaltMaterial === null ? {} : { material: asphaltMaterial }), children: asphaltMaterial === null ? _jsx("meshStandardMaterial", { color: road.color, roughness: 0.95, metalness: 0, side: DoubleSide }) : null }), curbs !== null ? (_jsx("mesh", { geometry: curbs, receiveShadow: true, ...(curbMaterial === null ? {} : { material: curbMaterial }), children: curbMaterial === null ? _jsx("meshStandardMaterial", { color: curbColor, roughness: 0.9, metalness: 0, side: DoubleSide }) : null })) : null, dashes !== null ? (_jsx("mesh", { geometry: dashes, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: road.markingColor, roughness: 0.8, metalness: 0, side: DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, sidewalks !== null ? (_jsx("mesh", { geometry: sidewalks, receiveShadow: true, ...(sidewalkMaterial === null ? {} : { material: sidewalkMaterial }), children: sidewalkMaterial === null ? _jsx("meshStandardMaterial", { color: sidewalkColor, roughness: 0.9, metalness: 0, side: DoubleSide }) : null })) : null] }));
 }