@jgengine/shell 0.8.0 → 0.9.0

package/dist/devtools/collisionDebug.js

@@ -0,0 +1,127 @@
+export const COLLISION_DEBUG_LAYERS = [
+    "hitboxes",
+    "bodies",
+    "projectiles",
+    "muzzles",
+    "aimLaser",
+];
+const DEFAULT_LAYERS = {
+    hitboxes: false,
+    bodies: false,
+    projectiles: false,
+    muzzles: false,
+    aimLaser: false,
+};
+export function createDefaultCollisionDebugState() {
+    return {
+        layers: { ...DEFAULT_LAYERS },
+        aimProbe: null,
+        projectileTraces: [],
+        maxProjectileTraces: 32,
+        projectileTraceLifeMs: 2500,
+    };
+}
+export function anyCollisionLayerOn(layers) {
+    return (layers.hitboxes ||
+        layers.bodies ||
+        layers.projectiles ||
+        layers.muzzles ||
+        layers.aimLaser);
+}
+export function colliderScanNeeded(layers) {
+    return layers.hitboxes || layers.bodies;
+}
+export function projectileListenNeeded(layers) {
+    return layers.projectiles || layers.muzzles;
+}
+export function aimProbeNeeded(layers) {
+    return layers.aimLaser;
+}
+export function createCollisionDebugController(initial = createDefaultCollisionDebugState()) {
+    let state = {
+        ...initial,
+        layers: { ...initial.layers },
+        projectileTraces: [...initial.projectileTraces],
+    };
+    const listeners = new Set();
+    let nextTraceId = 1;
+    function emit() {
+        for (const listener of listeners)
+            listener();
+    }
+    function replace(next) {
+        state = next;
+        emit();
+    }
+    return {
+        getState() {
+            return state;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setLayer(layer, on) {
+            if (state.layers[layer] === on)
+                return;
+            replace({ ...state, layers: { ...state.layers, [layer]: on } });
+        },
+        toggleLayer(layer) {
+            replace({ ...state, layers: { ...state.layers, [layer]: !state.layers[layer] } });
+        },
+        setLayers(partial) {
+            const layers = { ...state.layers, ...partial };
+            replace({ ...state, layers });
+        },
+        setAllLayers(on) {
+            const layers = {
+                hitboxes: on,
+                bodies: on,
+                projectiles: on,
+                muzzles: on,
+                aimLaser: on,
+            };
+            replace({ ...state, layers });
+        },
+        setAimProbe(probe) {
+            state = { ...state, aimProbe: probe };
+        },
+        getAimProbe() {
+            return state.aimProbe;
+        },
+        pushProjectileTrace(input) {
+            if (!projectileListenNeeded(state.layers))
+                return;
+            const trace = {
+                id: nextTraceId++,
+                origin: input.origin,
+                at: input.at,
+                hit: input.hit,
+                bornMs: input.nowMs ?? 0,
+            };
+            const next = [...state.projectileTraces, trace];
+            while (next.length > state.maxProjectileTraces)
+                next.shift();
+            replace({ ...state, projectileTraces: next });
+        },
+        pruneProjectileTraces(nowMs) {
+            if (state.projectileTraces.length === 0)
+                return;
+            const life = state.projectileTraceLifeMs;
+            const next = state.projectileTraces.filter((trace) => nowMs - trace.bornMs <= life);
+            if (next.length === state.projectileTraces.length)
+                return;
+            replace({ ...state, projectileTraces: next });
+        },
+        reset() {
+            nextTraceId = 1;
+            replace(createDefaultCollisionDebugState());
+        },
+        isActive() {
+            return anyCollisionLayerOn(state.layers);
+        },
+    };
+}
+export const collisionDebug = createCollisionDebugController();

package/dist/devtools/collisionDebugMath.d.ts

@@ -0,0 +1,102 @@
+import type { EntityPosition } from "@jgengine/core/scene/entityStore";
+import { type ColliderPurpose, type EntityColliderSet, type ResolvedCollider } from "@jgengine/core/scene/colliders";
+import { type SceneRaycastApi, type SceneRaycastHit } from "@jgengine/core/scene/sceneRaycast";
+import { type ShotOriginPolicy } from "@jgengine/core/combat/shotOrigin";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { CollisionDebugLayers } from "./collisionDebug.js";
+export type AimEndpointKind = "damage" | "solid" | "miss";
+export interface DebugShapeEntry {
+    key: string;
+    targetKind: "entity" | "object";
+    instanceId: string;
+    catalogId?: string;
+    name: string;
+    purpose: ColliderPurpose;
+    damageEligible: boolean;
+    blocks: boolean;
+    position: EntityPosition;
+    rotationY: number;
+    shape: {
+        kind: "sphere";
+        radius: number;
+        center: EntityPosition;
+    } | {
+        kind: "aabb";
+        halfExtents: EntityPosition;
+        center: EntityPosition;
+    };
+    label: string;
+    style: "hitbox" | "body";
+}
+export interface AimLaserDebug {
+    origin: EntityPosition;
+    direction: EntityPosition;
+    end: EntityPosition;
+    maxDistance: number;
+    kind: AimEndpointKind;
+    nearest: SceneRaycastHit | null;
+    firstImpact: SceneRaycastHit | null;
+    /** Counts scene raycast calls performed (0 when skipped). */
+    queryCount: number;
+}
+export interface CollectDebugShapesInput {
+    layers: CollisionDebugLayers;
+    entities: readonly {
+        id: string;
+        position: EntityPosition;
+        rotationY: number;
+        name?: string;
+    }[];
+    objects?: readonly {
+        instanceId: string;
+        catalogId: string;
+        position: EntityPosition;
+        rotationY: number;
+    }[];
+    entityCollidersOf?(instanceId: string): EntityColliderSet | null | undefined;
+    objectCollidersOf?(instanceId: string): EntityColliderSet | null | undefined;
+    objectHalfExtentsOf?(catalogId: string): EntityPosition | null | undefined;
+    /** Mutated when a scene scan runs — tests assert 0 when hidden. */
+    counters?: {
+        scans: number;
+        shapes: number;
+    };
+}
+export declare function classifyAimEndpoint(hit: Pick<SceneRaycastHit, "damageEligible"> | null | undefined): AimEndpointKind;
+export declare function pointAlongRay(origin: EntityPosition, direction: EntityPosition, distance: number): EntityPosition;
+export declare function shapeWorldCenter(collider: ResolvedCollider, position: EntityPosition, rotationY: number): EntityPosition;
+/**
+ * Collects world-space collider wireframe entries for enabled layers.
+ * Returns [] and performs no entity/object iteration when both hitbox/body layers are off.
+ */
+export declare function collectDebugShapes(input: CollectDebugShapesInput): DebugShapeEntry[];
+export interface ComputeAimLaserInput {
+    layers: CollisionDebugLayers;
+    sceneRaycast: SceneRaycastApi;
+    positionOf(instanceId: string): EntityPosition | undefined;
+    rotationYOf?(instanceId: string): number | undefined;
+    from: string;
+    aim: Aim;
+    originPolicy?: ShotOriginPolicy;
+    maxDistance: number;
+    counters?: {
+        queries: number;
+    };
+}
+/**
+ * Builds the authoritative aim-laser segment using resolveShot + scene raycast
+ * (same seam as projectile prediction/settlement). Zero queries when aimLaser is off.
+ */
+export declare function computeAimLaser(input: ComputeAimLaserInput): AimLaserDebug | null;
+export declare function muzzleMarkerFromOrigin(origin: EntityPosition): {
+    center: EntityPosition;
+    radius: number;
+    color: string;
+};
+export declare const HITBOX_WIRE_COLOR = "#f472b6";
+export declare const BODY_WIRE_COLOR = "#38bdf8";
+export declare const PROJECTILE_PATH_COLOR = "#fde68a";
+export declare const AIM_LASER_COLOR = "#a3e635";
+export declare const AIM_DAMAGE_COLOR = "#f87171";
+export declare const AIM_SOLID_COLOR = "#fbbf24";
+export declare const AIM_MISS_COLOR = "#94a3b8";

package/dist/devtools/collisionDebugMath.js

@@ -0,0 +1,128 @@
+import { colliderWorldCenter, defaultEntityColliders, defaultObjectColliders, resolveColliders, } from "@jgengine/core/scene/colliders";
+import { firstImpact, hitsUntilBlocked, } from "@jgengine/core/scene/sceneRaycast";
+import { resolveShot } from "@jgengine/core/combat/shotOrigin";
+import { aimProbeNeeded, colliderScanNeeded } from "./collisionDebug.js";
+export function classifyAimEndpoint(hit) {
+    if (hit === null || hit === undefined)
+        return "miss";
+    return hit.damageEligible ? "damage" : "solid";
+}
+export function pointAlongRay(origin, direction, distance) {
+    return [
+        origin[0] + direction[0] * distance,
+        origin[1] + direction[1] * distance,
+        origin[2] + direction[2] * distance,
+    ];
+}
+export function shapeWorldCenter(collider, position, rotationY) {
+    return colliderWorldCenter(collider, position, rotationY);
+}
+function styleFor(purpose) {
+    return purpose === "damage" ? "hitbox" : "body";
+}
+function labelFor(collider) {
+    return `${collider.purpose}:${collider.name}`;
+}
+function pushResolved(out, targetKind, instanceId, catalogId, position, rotationY, set, layers) {
+    for (const collider of resolveColliders(set)) {
+        const style = styleFor(collider.purpose);
+        if (style === "hitbox" && !layers.hitboxes)
+            continue;
+        if (style === "body" && !layers.bodies)
+            continue;
+        const center = shapeWorldCenter(collider, position, rotationY);
+        const shape = collider.shape.kind === "sphere"
+            ? { kind: "sphere", radius: collider.shape.radius, center }
+            : {
+                kind: "aabb",
+                halfExtents: collider.shape.halfExtents,
+                center,
+            };
+        out.push({
+            key: `${targetKind}:${instanceId}:${collider.purpose}:${collider.name}`,
+            targetKind,
+            instanceId,
+            ...(catalogId !== undefined ? { catalogId } : {}),
+            name: collider.name,
+            purpose: collider.purpose,
+            damageEligible: collider.damageEligible,
+            blocks: collider.blocks,
+            position,
+            rotationY,
+            shape,
+            label: labelFor(collider),
+            style,
+        });
+    }
+}
+/**
+ * Collects world-space collider wireframe entries for enabled layers.
+ * Returns [] and performs no entity/object iteration when both hitbox/body layers are off.
+ */
+export function collectDebugShapes(input) {
+    if (!colliderScanNeeded(input.layers))
+        return [];
+    input.counters !== undefined && (input.counters.scans += 1);
+    const out = [];
+    for (const entity of input.entities) {
+        const set = input.entityCollidersOf?.(entity.id) ?? defaultEntityColliders();
+        pushResolved(out, "entity", entity.id, entity.name, entity.position, entity.rotationY, set, input.layers);
+    }
+    if (input.objects !== undefined) {
+        for (const object of input.objects) {
+            const half = input.objectHalfExtentsOf?.(object.catalogId) ?? undefined;
+            const set = input.objectCollidersOf?.(object.instanceId) ??
+                defaultObjectColliders(half === null || half === undefined ? undefined : half);
+            pushResolved(out, "object", object.instanceId, object.catalogId, object.position, object.rotationY, set, input.layers);
+        }
+    }
+    if (input.counters !== undefined)
+        input.counters.shapes += out.length;
+    return out;
+}
+/**
+ * Builds the authoritative aim-laser segment using resolveShot + scene raycast
+ * (same seam as projectile prediction/settlement). Zero queries when aimLaser is off.
+ */
+export function computeAimLaser(input) {
+    if (!aimProbeNeeded(input.layers)) {
+        return null;
+    }
+    const resolved = resolveShot({
+        positionOf: input.positionOf,
+        rotationYOf: input.rotationYOf,
+    }, input.from, input.aim, input.originPolicy ?? { kind: "legacy" });
+    if (resolved === null)
+        return null;
+    input.counters !== undefined && (input.counters.queries += 1);
+    const all = input.sceneRaycast.raycastAll({
+        origin: resolved.origin,
+        direction: resolved.direction,
+        maxDistance: input.maxDistance,
+        excludeInstanceIds: [input.from],
+    });
+    const until = hitsUntilBlocked(all);
+    const nearest = until[0] ?? null;
+    const impact = firstImpact(until);
+    const end = nearest !== null ? nearest.point : pointAlongRay(resolved.origin, resolved.direction, input.maxDistance);
+    return {
+        origin: resolved.origin,
+        direction: resolved.direction,
+        end,
+        maxDistance: input.maxDistance,
+        kind: classifyAimEndpoint(nearest),
+        nearest,
+        firstImpact: impact,
+        queryCount: 1,
+    };
+}
+export function muzzleMarkerFromOrigin(origin) {
+    return { center: origin, radius: 0.08, color: "#ef4444" };
+}
+export const HITBOX_WIRE_COLOR = "#f472b6";
+export const BODY_WIRE_COLOR = "#38bdf8";
+export const PROJECTILE_PATH_COLOR = "#fde68a";
+export const AIM_LASER_COLOR = "#a3e635";
+export const AIM_DAMAGE_COLOR = "#f87171";
+export const AIM_SOLID_COLOR = "#fbbf24";
+export const AIM_MISS_COLOR = "#94a3b8";

package/dist/environment/Daylight.d.ts

@@ -28,12 +28,16 @@ export interface DaylightProps {
         groundColor?: string;
         intensity?: number;
     };
+    /** When false, only the sky dome and fog mount — use with authored `PlayableGame.lighting`. Default true. */
+    lights?: boolean;
 }
-export declare function Daylight({ sky, fog, sun, ambient }?: DaylightProps): import("react").JSX.Element;
-/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
-export declare function SkyDaylight({ sky }: {
+export declare function Daylight({ sky, fog, sun, ambient, lights }?: DaylightProps): import("react").JSX.Element;
+export interface SkyDaylightProps {
     sky: SkyEnvironmentDescriptor;
-}): import("react").JSX.Element;
+    lights?: boolean;
+}
+/** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
+export declare function SkyDaylight({ sky, lights }: SkyDaylightProps): import("react").JSX.Element;
 export interface TimeOfDayDaylightProps {
     sky: SkyEnvironmentDescriptor;
     /** The world's `SimClock` (or a stub exposing `calendar().dayFraction`). Absent means static rendering. */
@@ -42,9 +46,11 @@ export interface TimeOfDayDaylightProps {
             dayFraction: number;
         };
     };
+    lights?: boolean;
 }
 /**
- * Drives `Daylight`'s sun/sky/fog from the world clock when `sky.timeOfDay` and `clock` are both present,
- * sampling `daylightStateAt` every frame; otherwise renders the static preset look via `SkyDaylight`.
+ * Drives sky/fog (and optional default lights) from the world clock when `sky.timeOfDay` and `clock`
+ * are both present. Authored `PlayableGame.lighting` is never rewritten — pass `lights={false}` so
+ * only dome colors and fog track the day fraction.
  */
-export declare function TimeOfDayDaylight({ sky, clock }: TimeOfDayDaylightProps): import("react").JSX.Element;
+export declare function TimeOfDayDaylight({ sky, clock, lights }: TimeOfDayDaylightProps): import("react").JSX.Element;

package/dist/environment/Daylight.js

@@ -53,25 +53,26 @@ export function SkyDome({ topColor = SKY_TOP, horizonColor = SKY_HORIZON, radius
     }, [material, materialRef]);
     return (_jsx("mesh", { material: material, renderOrder: -1, children: _jsx("sphereGeometry", { args: [radius, 32, 16] }) }));
 }
-export function Daylight({ sky, fog, sun, ambient } = {}) {
+export function Daylight({ sky, fog, sun, ambient, lights = true } = {}) {
     const sunPosition = sun?.position ?? [120, 160, 70];
-    return (_jsxs(_Fragment, { children: [sky === false ? null : _jsx(SkyDome, { ...(sky ?? {}) }), fog === false ? null : (_jsx("fog", { attach: "fog", args: [fog?.color ?? FOG_COLOR, fog?.near ?? 70, fog?.far ?? 260] })), _jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx("directionalLight", { position: [sunPosition[0], sunPosition[1], sunPosition[2]], intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR, castShadow: true })] }));
+    return (_jsxs(_Fragment, { children: [sky === false ? null : _jsx(SkyDome, { ...(sky ?? {}) }), fog === false ? null : (_jsx("fog", { attach: "fog", args: [fog?.color ?? FOG_COLOR, fog?.near ?? 70, fog?.far ?? 260] })), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { args: [ambient?.skyColor ?? HEMI_SKY, ambient?.groundColor ?? HEMI_GROUND, ambient?.intensity ?? 0.55] }), _jsx("directionalLight", { position: [sunPosition[0], sunPosition[1], sunPosition[2]], intensity: sun?.intensity ?? 0.85, color: sun?.color ?? SUN_COLOR, castShadow: true })] })) : null] }));
 }
 /** Renders a fixed sky/sun/fog look sampled from `sky`'s preset (or, when `timeOfDay` is on but no clock drives it, its noon look). No per-frame updates. */
-export function SkyDaylight({ sky }) {
+export function SkyDaylight({ sky, lights = true }) {
     const state = useMemo(() => daylightStateAt(SKY_PRESET_DAY_FRACTION[sky.preset], sky), [sky]);
-    return (_jsx(Daylight, { sky: { topColor: state.skyTop, horizonColor: state.skyBottom }, fog: { color: sky.fog?.color ?? state.background, near: sky.fog?.near, far: sky.fog?.far }, sun: { position: state.sunPosition, intensity: state.sunIntensity }, ambient: { intensity: state.ambientIntensity } }));
+    return (_jsx(Daylight, { sky: { topColor: state.skyTop, horizonColor: state.skyBottom }, fog: { color: sky.fog?.color ?? state.background, near: sky.fog?.near, far: sky.fog?.far }, sun: { position: state.sunPosition, intensity: state.sunIntensity }, ambient: { intensity: state.ambientIntensity }, lights: lights }));
 }
 /**
- * Drives `Daylight`'s sun/sky/fog from the world clock when `sky.timeOfDay` and `clock` are both present,
- * sampling `daylightStateAt` every frame; otherwise renders the static preset look via `SkyDaylight`.
+ * Drives sky/fog (and optional default lights) from the world clock when `sky.timeOfDay` and `clock`
+ * are both present. Authored `PlayableGame.lighting` is never rewritten — pass `lights={false}` so
+ * only dome colors and fog track the day fraction.
  */
-export function TimeOfDayDaylight({ sky, clock }) {
+export function TimeOfDayDaylight({ sky, clock, lights = true }) {
     if (!sky.timeOfDay || clock === undefined)
-        return _jsx(SkyDaylight, { sky: sky });
-    return _jsx(DrivenDaylight, { sky: sky, clock: clock });
+        return _jsx(SkyDaylight, { sky: sky, lights: lights });
+    return _jsx(DrivenDaylight, { sky: sky, clock: clock, lights: lights });
 }
-function DrivenDaylight({ sky, clock, }) {
+function DrivenDaylight({ sky, clock, lights, }) {
     const initial = useMemo(() => daylightStateAt(clock.calendar().dayFraction, sky), [clock, sky]);
     const sunRef = useRef(null);
     const hemiRef = useRef(null);
@@ -96,5 +97,5 @@ function DrivenDaylight({ sky, clock, }) {
             skyMaterial.uniforms.bottomColor.value.set(state.skyBottom);
         }
     });
-    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, materialRef: skyMaterialRef }), _jsx("fog", { attach: "fog", ref: fogRef, args: [sky.fog?.color ?? initial.background, sky.fog?.near ?? 70, sky.fog?.far ?? 260] }), _jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx("directionalLight", { ref: sunRef, position: initial.sunPosition, intensity: initial.sunIntensity, color: SUN_COLOR, castShadow: true })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(SkyDome, { topColor: initial.skyTop, horizonColor: initial.skyBottom, materialRef: skyMaterialRef }), _jsx("fog", { attach: "fog", ref: fogRef, args: [sky.fog?.color ?? initial.background, sky.fog?.near ?? 70, sky.fog?.far ?? 260] }), lights ? (_jsxs(_Fragment, { children: [_jsx("hemisphereLight", { ref: hemiRef, args: [HEMI_SKY, HEMI_GROUND, initial.ambientIntensity] }), _jsx("directionalLight", { ref: sunRef, position: initial.sunPosition, intensity: initial.sunIntensity, color: SUN_COLOR, castShadow: true })] })) : null] }));
 }

package/dist/environment/EnvironmentScene.js

@@ -1,67 +1,114 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import { useGameContext } from "@jgengine/react/provider";
+import { resolveBuildingPalette } from "@jgengine/core/world/buildings";
 import { resolveStructureBuildings } from "@jgengine/core/world/environmentSummary";
-import { resolveTerrainField, resolveTerrainPalette } from "@jgengine/core/world/terrain";
-import { SkyDaylight } from "./Daylight.js";
+import { createTerrainPaletteSampler, resolveEnvironmentField, resolveTerrainPalette, } from "@jgengine/core/world/terrain";
 import { GroundPad } from "./GroundPad.js";
-import { GeneratedBuilding } from "../structures/GeneratedBuilding.js";
+import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
 import { GrassField } from "../terrain/GrassField.js";
-import { ProceduralGround } from "../terrain/ProceduralGround.js";
+import { CarvedTerrain } from "../terrain/CarvedTerrain.js";
 import { Ocean } from "../water/Ocean.js";
 import { RainField } from "../weather/RainField.js";
 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: {
-            low: palette.low,
-            high: palette.high,
-            ...(terrain.waterLevel === undefined ? {} : { waterline: palette.waterline, waterlineHeight: terrain.waterLevel }),
-        } }));
+function TerrainGround({ terrain, field, center, }) {
+    const palette = useMemo(() => resolveTerrainPalette(terrain), [terrain]);
+    const paletteAt = useMemo(() => {
+        if (terrain.materialRegions === undefined || terrain.materialRegions.length === 0)
+            return undefined;
+        const sampler = createTerrainPaletteSampler(terrain);
+        if (center === undefined)
+            return sampler;
+        return (x, z) => sampler(x - center[0], z - center[1]);
+    }, [terrain, center]);
+    const colors = useMemo(() => ({
+        low: palette.low,
+        high: palette.high,
+        ...(terrain.waterLevel === undefined ? {} : { waterline: palette.waterline, waterlineHeight: terrain.waterLevel }),
+    }), [palette, terrain.waterLevel]);
+    const size = useMemo(() => [terrain.bounds.w, terrain.bounds.d], [terrain.bounds]);
+    const heightRange = useMemo(() => {
+        const base = terrain.baseHeight ?? 0;
+        const swing = terrain.height * 1.2;
+        return [base - swing, base + swing];
+    }, [terrain.baseHeight, terrain.height]);
+    return (_jsx(CarvedTerrain, { field: field, size: size, segments: terrain.segments, colors: colors, heightRange: heightRange, paletteAt: paletteAt, center: center, roughness: 0.94 }));
+}
+function areaCenter(area) {
+    return area.position ?? [0, 0];
 }
 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 } }));
+    const [cx, cz] = areaCenter(grass.area);
+    const heightAt = useMemo(() => cx === 0 && cz === 0
+        ? field.sampleHeight
+        : (x, z) => field.sampleHeight(x + cx, z + cz), [cx, cz, field]);
+    const area = useMemo(() => [grass.area.w, grass.area.d], [grass.area.w, grass.area.d]);
+    const wind = useMemo(() => ({ strength: grass.windStrength }), [grass.windStrength]);
+    const colorBase = grass.colors[0];
+    const colorTip = grass.colors[grass.colors.length - 1];
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(GrassField, { area: area, density: grass.density, seed: grass.seed, bladeHeight: grass.bladeHeight, bladeWidth: grass.bladeWidth, heightAt: heightAt, colorBase: colorBase, colorTip: colorTip, wind: wind, frustumCulled: true }) }));
 }
 function weatherVolume(area) {
     return [area.w, area.h ?? 60, area.d];
 }
 function Precipitation({ weather }) {
+    const [cx, cz] = areaCenter(weather.area);
     if (weather.kind === "rain") {
-        return (_jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }));
+        return (_jsx("group", { position: [cx, 0, cz], children: _jsx(RainField, { density: weather.density, speed: weather.speed, length: weather.dropLength, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
     }
-    return (_jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }));
+    return (_jsx("group", { position: [cx, 0, cz], children: _jsx(SnowField, { density: weather.density, speed: weather.speed, size: weather.flakeSize, sway: weather.drift, color: weather.color, wind: [weather.wind[0], 0, weather.wind[1]], volume: weatherVolume(weather.area) }) }));
 }
 function Weather({ weather }) {
     return (_jsx(WeatherUniformProvider, { children: weather.map((entry, index) => (_jsx(Precipitation, { weather: entry, index: index }, `${entry.kind}-${index}`))) }));
 }
+function oceanConfig(ocean) {
+    return {
+        size: ocean.bounds.w,
+        depth: ocean.bounds.d,
+        amplitude: ocean.waveHeight,
+        speed: ocean.waveSpeed,
+        waveScale: ocean.waveScale,
+        color: { shallow: ocean.color },
+    };
+}
+function useOceanConfig(ocean) {
+    return useMemo(() => oceanConfig(ocean), [ocean.bounds.w, ocean.bounds.d, ocean.waveHeight, ocean.waveSpeed, ocean.color]);
+}
+function DynamicWater({ ocean }) {
+    const ctx = useGameContext();
+    const groupRef = useRef(null);
+    const [x, z] = ocean.position ?? [0, 0];
+    const config = useOceanConfig(ocean);
+    useFrame(() => {
+        if (groupRef.current !== null)
+            groupRef.current.position.y = ocean.levelAt(ctx.time.now());
+    });
+    return (_jsx("group", { ref: groupRef, position: [0, ocean.level, 0], children: _jsx(Ocean, { position: [x, 0, z], config: config }) }));
+}
 function Water({ ocean }) {
     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 },
-        } }));
+    const config = useOceanConfig(ocean);
+    if (ocean.levelAt !== undefined) {
+        return _jsx(DynamicWater, { ocean: ocean });
+    }
+    return _jsx(Ocean, { position: [x, ocean.level, z], config: config });
 }
 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))) }));
+    const placements = useMemo(() => resolveStructureBuildings(structures).map((building) => ({
+        building,
+        position: [0, field.sampleHeight(building.center[0], building.center[1]), 0],
+    })), [structures, field]);
+    const palette = useMemo(() => resolveBuildingPalette(structures.style, structures.palette), [structures.style, structures.palette]);
+    return _jsx(InstancedBuildings, { buildings: placements, palette: palette });
 }
 export function EnvironmentScene({ feature }) {
-    const field = useMemo(() => resolveTerrainField(feature.terrain), [feature.terrain]);
+    const field = useMemo(() => resolveEnvironmentField(feature), [feature]);
     const vegetation = feature.vegetation ?? [];
     const water = feature.water ?? [];
     const structures = feature.structures ?? [];
     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] }));
+    const islands = feature.islands ?? [];
+    return (_jsxs(_Fragment, { children: [feature.terrain !== undefined ? _jsx(TerrainGround, { terrain: feature.terrain, field: field }) : null, islands.map((entry, index) => (_jsx(TerrainGround, { terrain: entry, field: field, center: entry.origin }, `island-${index}`))), 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/groundPadMath.d.ts

@@ -9,5 +9,5 @@ export type PadShape = {
     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;
+export declare function resolvePadSurfaceY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height" | "elevation">): number;
+export declare function resolvePadMeshY(groundHeight: number, pad: Pick<PadEnvironmentDescriptor, "height" | "elevation">): number;

package/dist/environment/groundPadMath.js

@@ -3,7 +3,7 @@ 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;
+    return pad.elevation ?? groundHeight + pad.height;
 }
 export function resolvePadMeshY(groundHeight, pad) {
     return resolvePadSurfaceY(groundHeight, pad) - PAD_THICKNESS / 2;

package/dist/environment/index.d.ts

@@ -1,3 +1,4 @@
-export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDomeProps, type TimeOfDayDaylightProps, } from "./Daylight.js";
+export { Daylight, SkyDaylight, SkyDome, TimeOfDayDaylight, type DaylightProps, type SkyDaylightProps, 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";
+export { resolveSkyLightOwnership, skyEmitsLights, type SkyLightOwnership, } from "./skyLightingPolicy.js";

package/dist/environment/index.js

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

package/dist/environment/skyLightingPolicy.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Policy for composing sky backdrops with `PlayableGame.lighting`:
+ * - authored lighting present → sky renders dome + fog only; lights stay game-owned
+ * - no authored lighting → sky may emit its default sun/hemisphere with the dome
+ * Time-of-day never rewrites configured lights; it only drives sky colors/fog (and
+ * sky-owned lights when the game did not author lighting).
+ */
+export type SkyLightOwnership = "authored" | "sky-default";
+export declare function resolveSkyLightOwnership(hasAuthoredLighting: boolean): SkyLightOwnership;
+export declare function skyEmitsLights(ownership: SkyLightOwnership): boolean;

package/dist/environment/skyLightingPolicy.js

@@ -0,0 +1,6 @@
+export function resolveSkyLightOwnership(hasAuthoredLighting) {
+    return hasAuthoredLighting ? "authored" : "sky-default";
+}
+export function skyEmitsLights(ownership) {
+    return ownership === "sky-default";
+}