@jgengine/shell 0.10.0 → 0.12.0

package/dist/scene/WaterRenderer.js

@@ -0,0 +1,61 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useMemo } from "react";
+import { resolveWaterObject } from "@jgengine/core/world/waterKind";
+import { Ocean } from "../water/Ocean.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+/** Map the editor-authored water params onto the shell Ocean shader config. */
+function toOceanConfig(rules, size, depthRange) {
+    const maxSpan = Math.max(size[0], size[1]);
+    return {
+        size: size[0],
+        depth: size[1],
+        // ~2 vertices per meter (bounded): the old span/2 gave a 30 m lake a 15×15 grid, which waved
+        // like a blanket instead of water.
+        resolution: Math.min(220, Math.max(48, Math.round(maxSpan * 2))),
+        amplitude: rules.waveHeight,
+        speed: rules.waveSpeed,
+        timeScale: rules.waveSpeed,
+        waveScale: Math.min(300, Math.max(2, 6 / rules.waveScale)),
+        color: {
+            deep: rules.color,
+            shallow: rules.shallowColor,
+            opacity: rules.opacity,
+            // The editor's reflectivity slider stays restrained: full slider ≈ a soft sky sheen at
+            // grazing angles, never the white-out the old fresnel washed the whole sheet with.
+            fresnelStrength: rules.reflectivity * 0.9,
+            depthRange,
+            sparkle: 0.25 + rules.reflectivity * 0.3,
+        },
+        foam: {
+            coverage: Math.min(1, rules.foam / 4),
+            intensity: Math.min(1.2, rules.foam / 3),
+            shoreWidth: Math.min(1.5, rules.foam * 0.35),
+        },
+    };
+}
+/**
+ * One authored water volume → a bounded, animated Ocean sheet at the box top, draped over the live
+ * terrain's depth: the carved lake bed (see `lakebedFromWaterVolumes`) gives every vertex a real
+ * water-column depth, which drives shallow→deep color, shore transparency/foam, and wave damping.
+ */
+function OneWater({ object, context }) {
+    const resolved = useMemo(() => resolveWaterObject(object), [object]);
+    const surfaceY = resolved === null ? 0 : resolved.center[1];
+    const centerX = resolved === null ? 0 : resolved.center[0];
+    const centerZ = resolved === null ? 0 : resolved.center[2];
+    const depthAt = useCallback((x, z) => surfaceY - context.field.sampleHeight(centerX + x, centerZ + z), [context.field, surfaceY, centerX, centerZ]);
+    const config = useMemo(() => {
+        if (resolved === null)
+            return null;
+        // Full deep color roughly where the carved bed bottoms out (box depth + undercut headroom).
+        const boxDepth = Math.max(0.4, resolved.center[1] - (object.center?.y ?? resolved.center[1]) + 0.001) * 2;
+        return toOceanConfig(resolved.rules, resolved.size, Math.max(0.8, boxDepth * 0.9));
+    }, [resolved, object]);
+    if (resolved === null || config === null)
+        return null;
+    return _jsx(Ocean, { config: config, position: [centerX, surfaceY, centerZ], depthAt: depthAt });
+}
+/** Registers the `water` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerWaterRenderer() {
+    registerSceneKindRenderer("water", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneWater, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/builtinSceneKindRenderers.d.ts

@@ -0,0 +1,2 @@
+/** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
+export declare function registerBuiltinSceneKindRenderers(): void;

package/dist/scene/builtinSceneKindRenderers.js

@@ -0,0 +1,26 @@
+/**
+ * Registers the engine's built-in *environment* scene-kind renderers (the shell half of #809) and
+ * ensures the matching core kinds are registered too. Idempotent; `AuthoredScene` calls it at module
+ * load so a document with a `water`/`grass_field`/`soil` volume renders without the game wiring
+ * anything up. Domain studios (poles, …) register their own renderer via the public
+ * `registerSceneKindRenderer` — no edit here.
+ */
+import { registerBuiltinSceneKinds } from "@jgengine/core/scene/builtinSceneKinds";
+import { registerGrassFieldRenderer } from "./GrassFieldRenderer.js";
+import { registerWaterRenderer } from "./WaterRenderer.js";
+import { registerSoilPatchRenderer } from "./SoilPatchRenderer.js";
+import { registerCityRenderer } from "./CityRenderer.js";
+import { registerPoleLineRenderer } from "./PoleLineRenderer.js";
+let registered = false;
+/** Registers the engine's built-in environment scene-kind renderers. Called by `AuthoredScene`. @internal */
+export function registerBuiltinSceneKindRenderers() {
+    if (registered)
+        return;
+    registered = true;
+    registerBuiltinSceneKinds();
+    registerWaterRenderer();
+    registerGrassFieldRenderer();
+    registerSoilPatchRenderer();
+    registerCityRenderer();
+    registerPoleLineRenderer();
+}

package/dist/scene/cityWindowMaterial.d.ts

@@ -0,0 +1,16 @@
+import * as THREE from "three";
+/**
+ * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
+ * paints procedural window strips on the side faces of every instanced unit box — floor bands from
+ * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
+ * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
+ * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
+ * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
+ * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
+ */
+export declare function createCityWindowMaterial(options: {
+    floorHeight: number;
+    windowColor: string;
+    roughness?: number;
+}): THREE.MeshStandardMaterial;

package/dist/scene/cityWindowMaterial.js

@@ -0,0 +1,81 @@
+import * as THREE from "three";
+/**
+ * Instanced facade material for city massing walls: a `MeshStandardMaterial` whose fragment stage
+ * paints procedural window strips on the side faces of every instanced unit box — floor bands from
+ * the district's real `floorHeight`, window columns on a fixed pitch, and a per-cell hash that
+ * dims/lights individual windows so no two facades read identical. Ground floors (plus any buried
+ * foundation, via the `instanceGroundOffset` attribute) stay solid wall so street level reads as
+ * storefront/lobby rather than floating glass. Same `onBeforeCompile` idiom as the grass/terrain
+ * materials; instance colors keep tinting the wall exactly like the plain massing material.
+ * @internal — created by `CityRenderer` for the banded-piece InstancedMesh.
+ */
+export function createCityWindowMaterial(options) {
+    const material = new THREE.MeshStandardMaterial({
+        color: "#ffffff",
+        roughness: options.roughness ?? 0.82,
+        metalness: 0.04,
+    });
+    const uniforms = {
+        uFloorHeight: { value: Math.max(2, options.floorHeight) },
+        uWindowColor: { value: new THREE.Color(options.windowColor) },
+    };
+    material.onBeforeCompile = (shader) => {
+        Object.assign(shader.uniforms, uniforms);
+        shader.vertexShader = shader.vertexShader
+            .replace("#include <common>", `
+#include <common>
+attribute float instanceGroundOffset;
+varying vec3 vCityLocal;
+varying vec3 vCityScale;
+varying vec3 vCityNormal;
+varying float vCityGround;
+`)
+            .replace("#include <begin_vertex>", `
+#include <begin_vertex>
+vCityLocal = position;
+vCityScale = vec3(length(instanceMatrix[0].xyz), length(instanceMatrix[1].xyz), length(instanceMatrix[2].xyz));
+vCityNormal = normal;
+vCityGround = instanceGroundOffset;
+`);
+        shader.fragmentShader = shader.fragmentShader
+            .replace("#include <common>", `
+#include <common>
+uniform float uFloorHeight;
+uniform vec3 uWindowColor;
+varying vec3 vCityLocal;
+varying vec3 vCityScale;
+varying vec3 vCityNormal;
+varying float vCityGround;
+float cityHash(vec2 cell) {
+  return fract(sin(dot(cell, vec2(127.1, 311.7))) * 43758.5453);
+}
+`)
+            .replace("#include <color_fragment>", `
+#include <color_fragment>
+{
+  // Side faces only — roofs and undersides stay plain wall.
+  if (abs(vCityNormal.y) < 0.5) {
+    float along = abs(vCityNormal.x) > 0.5 ? (vCityLocal.z + 0.5) * vCityScale.z : (vCityLocal.x + 0.5) * vCityScale.x;
+    float faceWidth = abs(vCityNormal.x) > 0.5 ? vCityScale.z : vCityScale.x;
+    float up = (vCityLocal.y + 0.5) * vCityScale.y - vCityGround;
+    float pitch = 2.4;
+    float floorT = fract(up / uFloorHeight);
+    float colT = fract(along / pitch);
+    float floorIndex = floor(up / uFloorHeight);
+    float colIndex = floor(along / pitch);
+    bool window = up > uFloorHeight * 1.05 && floorT > 0.32 && floorT < 0.78 && colT > 0.2 && colT < 0.8
+      && along > 0.7 && along < faceWidth - 0.7;
+    if (window) {
+      float cell = cityHash(vec2(floorIndex, colIndex) + vec2(vCityScale.x, vCityScale.z));
+      vec3 pane = uWindowColor * mix(0.55, 1.25, cell);
+      diffuseColor.rgb = mix(diffuseColor.rgb, pane, 0.88);
+    }
+    // A thin darker plinth line right above grade grounds the facade.
+    if (up > 0.0 && up < 0.35) diffuseColor.rgb *= 0.8;
+  }
+}
+`);
+    };
+    material.customProgramCacheKey = () => `jgengine-city-windows`;
+    return material;
+}

package/dist/scene/sceneKindRenderers.d.ts

@@ -0,0 +1,30 @@
+import type { ReactElement } from "react";
+import type { EditorDocument } from "@jgengine/core/editor/index";
+import type { AssetCatalog } from "@jgengine/core/scene/assetCatalog";
+import type { SceneKindObject } from "@jgengine/core/scene/sceneKinds";
+import type { TerrainField } from "@jgengine/core/world/terrain";
+/** Context a scene-kind renderer receives alongside the matching document objects. */
+export interface SceneKindRenderContext {
+    document: EditorDocument;
+    /** Ground field to drape/ground kind geometry on. */
+    field: TerrainField;
+    /** Catalog for kinds that instance real GLBs (pole assets, etc.). */
+    assets?: AssetCatalog;
+    /** Terrain surface color at a world XZ — lets kind geometry (grass roots, soil borders) blend into the ground it sits on. */
+    groundColorAt?: (x: number, z: number) => string;
+}
+/** A registered renderer: given every document object of its kind, returns the render tree for them. */
+export type SceneKindRenderer = (props: {
+    objects: readonly SceneKindObject[];
+    context: SceneKindRenderContext;
+}) => ReactElement | null;
+/**
+ * Register the runtime renderer for a scene kind — the shell half of the #809 seam. `AuthoredScene`
+ * groups a document's objects by kind and mounts the registered renderer for each, so a new studio
+ * renders from the document with no fork of `AuthoredScene`. Idempotent per kind (last wins).
+ */
+export declare function registerSceneKindRenderer(kind: string, renderer: SceneKindRenderer): void;
+/** The renderer registered for a kind, or undefined. @internal — `AuthoredScene` uses it internally. */
+export declare function getSceneKindRenderer(kind: string): SceneKindRenderer | undefined;
+/** Every kind that has a registered renderer. @internal */
+export declare function renderedSceneKinds(): string[];

package/dist/scene/sceneKindRenderers.js

@@ -0,0 +1,17 @@
+const renderers = new Map();
+/**
+ * Register the runtime renderer for a scene kind — the shell half of the #809 seam. `AuthoredScene`
+ * groups a document's objects by kind and mounts the registered renderer for each, so a new studio
+ * renders from the document with no fork of `AuthoredScene`. Idempotent per kind (last wins).
+ */
+export function registerSceneKindRenderer(kind, renderer) {
+    renderers.set(kind, renderer);
+}
+/** The renderer registered for a kind, or undefined. @internal — `AuthoredScene` uses it internally. */
+export function getSceneKindRenderer(kind) {
+    return renderers.get(kind);
+}
+/** Every kind that has a registered renderer. @internal */
+export function renderedSceneKinds() {
+    return [...renderers.keys()];
+}

package/dist/scene.d.ts

@@ -0,0 +1 @@
+export * from "./scene/AuthoredScene.js";

package/dist/scene.js

@@ -0,0 +1 @@
+export * from "./scene/AuthoredScene.js";

package/dist/settings/appliedSettings.d.ts

@@ -1,11 +1,17 @@
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
-import { type SettingsStore } from "@jgengine/core/settings/settingsModel";
+import { type GraphicsQuality, type SettingsStore } from "@jgengine/core/settings/settingsModel";
+import { type TouchStyle } from "@jgengine/core/input/touchScheme";
 import type { AudioEngine } from "../audio/audioEngine.js";
+/** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
+export declare const TOUCH_STYLE_AUTO = "auto";
+/** Shell-internal: binds the SettingsStore touch-style choice to the touch renderer. @internal */
+export declare function useTouchStyle(store: SettingsStore, fallback: TouchStyle): TouchStyle;
 export declare function useSettingsRevision(store: SettingsStore): number;
 export declare function useGraphicsSettings(store: SettingsStore, shadowsDefault: boolean): {
     shadows: boolean;
     dpr: number;
     uiScale: number;
+    quality: GraphicsQuality;
 };
 export declare function AudioSettingsBridge({ store, engine, buses, }: {
     store: SettingsStore;

package/dist/settings/appliedSettings.js

@@ -1,5 +1,14 @@
 import { useEffect, useReducer } from "react";
 import { busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_DPR, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { TOUCH_STYLES } from "@jgengine/core/input/touchScheme";
+/** Sentinel Controls value meaning "defer to the game's suggested touch skin". */
+export const TOUCH_STYLE_AUTO = "auto";
+/** Shell-internal: binds the SettingsStore touch-style choice to the touch renderer. @internal */
+export function useTouchStyle(store, fallback) {
+    useSettingsRevision(store);
+    const raw = store.get(SETTING_IDS.touchStyle, TOUCH_STYLE_AUTO);
+    return TOUCH_STYLES.includes(raw) ? raw : fallback;
+}
 export function useSettingsRevision(store) {
     const [rev, bump] = useReducer((n) => n + 1, 0);
     useEffect(() => store.subscribe(() => bump()), [store]);
@@ -7,12 +16,14 @@ export function useSettingsRevision(store) {
 }
 export function useGraphicsSettings(store, shadowsDefault) {
     useSettingsRevision(store);
-    const quality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
+    const rawQuality = store.get(SETTING_IDS.graphicsQuality, DEFAULT_GRAPHICS_QUALITY);
+    const quality = GRAPHICS_QUALITY_DPR[rawQuality] !== undefined ? rawQuality : "high";
     const rawUiScale = store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE);
     return {
         shadows: store.get(SETTING_IDS.graphicsShadows, shadowsDefault),
-        dpr: GRAPHICS_QUALITY_DPR[quality] ?? GRAPHICS_QUALITY_DPR.high,
+        dpr: GRAPHICS_QUALITY_DPR[quality],
         uiScale: Math.min(UI_SCALE_MAX, Math.max(UI_SCALE_MIN, rawUiScale)),
+        quality,
     };
 }
 export function AudioSettingsBridge({ store, engine, buses, }) {

package/dist/settings/settingsController.d.ts

@@ -12,6 +12,8 @@ export interface SettingsControllerInput {
     hide: readonly SettingCategory[];
     fovEnabled: boolean;
     hideBindings: readonly string[];
+    /** Show the touch-controls skin selector in Controls (touch device with a dock). */
+    touchStyle: boolean;
     overrides: BindingOverrides;
     rebind: (action: string, code: string) => void;
     resetBinding: (action: string) => void;

package/dist/settings/settingsController.js

@@ -1,6 +1,8 @@
 import { useEffect, useReducer } from "react";
 import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
 import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, DEFAULT_GRAPHICS_QUALITY, DEFAULT_GRAPHICS_SHADOWS, DEFAULT_MASTER_VOLUME, DEFAULT_UI_SCALE, GRAPHICS_QUALITY_OPTIONS, SETTING_IDS, UI_SCALE_MAX, UI_SCALE_MIN, } from "@jgengine/core/settings/settingsModel";
+import { TOUCH_STYLE_OPTIONS } from "@jgengine/core/input/touchScheme";
+import { TOUCH_STYLE_AUTO } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
 import { usePlayerFov } from "../camera/PlayerFov.js";
 const DEFAULT_CATEGORY_LABELS = {
@@ -10,6 +12,10 @@ const DEFAULT_CATEGORY_LABELS = {
     controls: "Controls",
 };
 const percent = (value) => `${Math.round(value * 100)}%`;
+const TOUCH_STYLE_SELECT_OPTIONS = [
+    { value: TOUCH_STYLE_AUTO, label: "Auto (game default)" },
+    ...TOUCH_STYLE_OPTIONS.map((option) => ({ value: option.value, label: option.label })),
+];
 export function useSettingsCategories(config) {
     const store = useSettingsStore();
     const fov = usePlayerFov();
@@ -119,11 +125,26 @@ export function useSettingsCategories(config) {
             reset: () => config.resetBinding(action),
         };
     });
+    const controlsRows = [
+        ...(config.touchStyle
+            ? [
+                {
+                    id: SETTING_IDS.touchStyle,
+                    label: "Touch controls",
+                    kind: "select",
+                    value: store.get(SETTING_IDS.touchStyle, TOUCH_STYLE_AUTO),
+                    options: TOUCH_STYLE_SELECT_OPTIONS,
+                    set: (value) => store.set(SETTING_IDS.touchStyle, value),
+                },
+            ]
+            : []),
+        ...extrasFor("controls"),
+    ];
     const builtInRows = {
         sound: soundRows,
         graphics: graphicsRows,
         gameplay: gameplayRows,
-        controls: extrasFor("controls"),
+        controls: controlsRows,
     };
     const builtInKeybinds = { controls: keybinds };
     const declaredLabels = new Map(config.categories.map((c) => [c.id, c.label]));

package/dist/shellConstants.d.ts

@@ -0,0 +1,4 @@
+/** No action names are reserved when no camera rig is active (hud/none presentation): games may bind `turnLeft`/`interact`/etc. as their own. */
+export declare const EMPTY_RESERVED: ReadonlySet<string>;
+/** Empty action list — published while the orientation gate is up to suppress all held input without touching the tracker. */
+export declare const NO_ACTIONS: string[];

package/dist/shellConstants.js

@@ -0,0 +1,4 @@
+/** No action names are reserved when no camera rig is active (hud/none presentation): games may bind `turnLeft`/`interact`/etc. as their own. */
+export const EMPTY_RESERVED = new Set();
+/** Empty action list — published while the orientation gate is up to suppress all held input without touching the tracker. */
+export const NO_ACTIONS = [];

package/dist/shellMovement.d.ts

@@ -0,0 +1,8 @@
+/** Movement action names the shell drives via the walk controller. @internal */
+export declare const SHELL_MOVEMENT_ACTIONS: readonly ["moveForward", "moveBack", "moveLeft", "moveRight", "jump"];
+/**
+ * True when the game's input map binds any walk-controller action — the shell owns pose
+ * for those games. Games that omit all five drive pose themselves.
+ * @internal
+ */
+export declare function shellDrivesPlayerPose(input: Record<string, unknown> | undefined): boolean;

package/dist/shellMovement.js

@@ -0,0 +1,11 @@
+/** Movement action names the shell drives via the walk controller. @internal */
+export const SHELL_MOVEMENT_ACTIONS = ["moveForward", "moveBack", "moveLeft", "moveRight", "jump"];
+/**
+ * True when the game's input map binds any walk-controller action — the shell owns pose
+ * for those games. Games that omit all five drive pose themselves.
+ * @internal
+ */
+export function shellDrivesPlayerPose(input) {
+    const bound = input ?? {};
+    return SHELL_MOVEMENT_ACTIONS.some((action) => action in bound);
+}

package/dist/shellPointer.d.ts

@@ -0,0 +1,20 @@
+import { type ContextMenu } from "@jgengine/core/interaction/contextMenu";
+import type { Aim } from "@jgengine/core/scene/spatial";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { PointerService } from "./pointer/pointerService.js";
+/** Minimal playable slice for context-menu verb lookup. @internal */
+export type PointerPlayable = {
+    content: {
+        entityById?: (name: string) => {
+            verbs?: ContextMenu["verbs"];
+        } | null | undefined;
+    };
+};
+/** Aim from the possessed/local player eye toward the current pointer world hit. @internal */
+export declare function pointerAimFor(ctx: GameContext, service: PointerService): Aim | undefined;
+/** Context menu for an entity/object pointer hit, or null for empty ground. @internal */
+export declare function pointerContextMenu(ctx: GameContext, playable: PointerPlayable, hit: {
+    point: readonly [number, number, number];
+    entity: string | null;
+    object: string | null;
+}): ContextMenu | null;

package/dist/shellPointer.js

@@ -0,0 +1,28 @@
+import { buildContextMenu, } from "@jgengine/core/interaction/contextMenu";
+import { aimToPoint } from "@jgengine/core/input/pointer";
+import { eyeHeightFromColliders } from "@jgengine/core/combat/shotOrigin";
+/** Aim from the possessed/local player eye toward the current pointer world hit. @internal */
+export function pointerAimFor(ctx, service) {
+    const hit = service.worldHit();
+    if (hit === null)
+        return undefined;
+    const shooter = ctx.scene.entity.get(ctx.player.possession.active(ctx.player.userId)) ??
+        ctx.scene.entity.get(ctx.player.userId);
+    if (shooter === null)
+        return undefined;
+    const eye = eyeHeightFromColliders(ctx.scene.entity.collidersOf(shooter.id));
+    return aimToPoint([shooter.position[0], shooter.position[1] + eye, shooter.position[2]], hit.point);
+}
+/** Context menu for an entity/object pointer hit, or null for empty ground. @internal */
+export function pointerContextMenu(ctx, playable, hit) {
+    if (hit.entity !== null) {
+        const entity = ctx.scene.entity.get(hit.entity);
+        const verbs = entity === null ? undefined : playable.content.entityById?.(entity.name)?.verbs;
+        return buildContextMenu({ kind: "entity", targetId: hit.entity, verbs, point: hit.point });
+    }
+    if (hit.object !== null) {
+        const verbs = ctx.scene.object.catalog(hit.object)?.verbs;
+        return buildContextMenu({ kind: "object", targetId: hit.object, verbs, point: hit.point });
+    }
+    return null;
+}

package/dist/structures/PlacementGhost.d.ts

@@ -5,4 +5,8 @@ export interface PlacementGhostProps {
     validColor?: string;
     invalidColor?: string;
 }
+/**
+ * Cursor-following build ghost: valid/invalid tint from a placement controller preview.
+ * @capability placement-ghost render valid/invalid placement preview mesh
+ */
 export declare function PlacementGhost({ preview, height, validColor, invalidColor, }: PlacementGhostProps): import("react").JSX.Element | null;

package/dist/structures/PlacementGhost.js

@@ -1,6 +1,10 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { quarterTurnsToRotationY } from "@jgengine/core/world/placementController";
+/**
+ * Cursor-following build ghost: valid/invalid tint from a placement controller preview.
+ * @capability placement-ghost render valid/invalid placement preview mesh
+ */
 export function PlacementGhost({ preview, height = 1, validColor = "#34d399", invalidColor = "#f87171", }) {
     const footprint = preview?.footprint;
     const size = useMemo(() => [footprint?.w ?? 1, height, footprint?.d ?? 1], [footprint?.w, footprint?.d, height]);

package/dist/structures/TransformGizmo.d.ts

@@ -0,0 +1,53 @@
+/** Active TransformControls mode for the runtime selection gizmo. */
+export type TransformGizmoMode = "translate" | "rotate" | "scale";
+/** Snap policy: grid quantize, free drag, or ground-height sample on release. */
+export type TransformGizmoSnap = "grid" | "free" | "ground";
+/** Gizmo handle orientation: world axes, or the target's local (yaw-rotated) axes. */
+export type TransformGizmoSpace = "world" | "local";
+/** Default rotation snap increment (radians) when callers don't configure one. */
+export declare const DEFAULT_ROTATION_SNAP: number;
+/** Pose reported by {@link TransformGizmo} when the user releases a drag. */
+export interface TransformGizmoPose {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY: number;
+    scale: {
+        x: number;
+        y: number;
+        z: number;
+    };
+}
+/** Props for the shared runtime/editor selection gizmo. */
+export interface TransformGizmoProps {
+    position: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    rotationY?: number;
+    mode?: TransformGizmoMode;
+    snapMode?: TransformGizmoSnap;
+    gridSize?: number;
+    /** Handle orientation; `"local"` aligns handles to the target's yaw. */
+    space?: TransformGizmoSpace;
+    /** Rotation snap increment in radians; `null` rotates freely. */
+    rotationSnap?: number | null;
+    /** Scale snap increment; `null` (default) scales freely. */
+    scaleSnap?: number | null;
+    /** Vertical offset so the gizmo sits above ground markers. */
+    lift?: number;
+    size?: number;
+    groundSnap?: (x: number, z: number) => number;
+    /** Disable orbit/pan while dragging (shell/editor cameras). */
+    onDraggingChange?: (dragging: boolean) => void;
+    onRelease: (pose: TransformGizmoPose) => void;
+}
+/**
+ * Runtime selection/move gizmo shared by games and the editor.
+ * Wraps TransformControls; callers own selection and commit side-effects.
+ * @capability transform-gizmo in-game select/move/rotate/scale gizmo
+ */
+export declare const TransformGizmo: import("react").MemoExoticComponent<({ position, rotationY, mode, snapMode, gridSize, space, rotationSnap, scaleSnap, lift, size, groundSnap, onDraggingChange, onRelease, }: TransformGizmoProps) => import("react").JSX.Element>;

package/dist/structures/TransformGizmo.js

@@ -0,0 +1,59 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { TransformControls } from "@react-three/drei";
+import { useThree } from "@react-three/fiber";
+import { memo, useEffect, useRef, useState } from "react";
+/** Default rotation snap increment (radians) when callers don't configure one. */
+export const DEFAULT_ROTATION_SNAP = Math.PI / 12;
+/**
+ * Runtime selection/move gizmo shared by games and the editor.
+ * Wraps TransformControls; callers own selection and commit side-effects.
+ * @capability transform-gizmo in-game select/move/rotate/scale gizmo
+ */
+export const TransformGizmo = memo(function TransformGizmo({ position, rotationY = 0, mode = "translate", snapMode = "free", gridSize = 1, space = "world", rotationSnap = DEFAULT_ROTATION_SNAP, scaleSnap = null, lift = 0, size = 0.85, groundSnap, onDraggingChange, onRelease, }) {
+    const groupRef = useRef(null);
+    const [object, setObject] = useState(null);
+    const draggingRef = useRef(false);
+    const controls = useThree((state) => state.controls);
+    const anchorKey = `${position.x}:${position.y}:${position.z}:${rotationY}:${mode}`;
+    useEffect(() => {
+        setObject(groupRef.current);
+    }, [anchorKey]);
+    useEffect(() => {
+        const group = groupRef.current;
+        if (group === null || draggingRef.current)
+            return;
+        group.position.set(position.x, position.y + lift, position.z);
+        group.rotation.set(0, rotationY, 0);
+        group.scale.set(1, 1, 1);
+    }, [position.x, position.y, position.z, rotationY, lift, anchorKey, mode]);
+    const snapProps = {
+        translationSnap: snapMode === "grid" ? gridSize : null,
+        rotationSnap,
+        scaleSnap,
+    };
+    const handleRelease = () => {
+        draggingRef.current = false;
+        if (controls !== null && "enabled" in controls)
+            controls.enabled = true;
+        onDraggingChange?.(false);
+        const current = groupRef.current;
+        if (current === null)
+            return;
+        let y = current.position.y - lift;
+        if (snapMode === "ground" && groundSnap !== undefined) {
+            y = groundSnap(current.position.x, current.position.z);
+            current.position.y = y + lift;
+        }
+        onRelease({
+            position: { x: current.position.x, y, z: current.position.z },
+            rotationY: current.rotation.y,
+            scale: { x: current.scale.x, y: current.scale.y, z: current.scale.z },
+        });
+    };
+    return (_jsxs(_Fragment, { children: [_jsx("group", { ref: groupRef }), object !== null ? (_jsx(TransformControls, { object: object, mode: mode, size: size, space: space, ...snapProps, onMouseDown: () => {
+                    draggingRef.current = true;
+                    if (controls !== null && "enabled" in controls)
+                        controls.enabled = false;
+                    onDraggingChange?.(true);
+                }, onMouseUp: handleRelease })) : null] }));
+});

package/dist/structures/index.d.ts

@@ -1,2 +1,3 @@
 export { BuildingBlock, GeneratedBuilding, InstancedBuildings, type BuildingBlockProps, type GeneratedBuildingProps, type InstancedBuildingPlacement, type InstancedBuildingsProps, } from "./GeneratedBuilding.js";
 export { PlacementGhost, type PlacementGhostProps } from "./PlacementGhost.js";
+export { TransformGizmo, type TransformGizmoMode, type TransformGizmoPose, type TransformGizmoProps, type TransformGizmoSnap, } from "./TransformGizmo.js";

package/dist/structures/index.js

@@ -1,2 +1,3 @@
 export { BuildingBlock, GeneratedBuilding, InstancedBuildings, } from "./GeneratedBuilding.js";
 export { PlacementGhost } from "./PlacementGhost.js";
+export { TransformGizmo, } from "./TransformGizmo.js";

package/dist/terrain/GrassField.d.ts

@@ -1,8 +1,9 @@
 import { type ThreeElements } from "@react-three/fiber";
-import { type GrassBladeGeometryOptions, type GrassRange } from "./grassGeometry.js";
-import { type GrassMaterialOptions, type GrassWindOptions } from "./grassMaterial.js";
+import { type GrassBladeGeometryOptions, type GrassExclusion, type GrassRange } from "./grassGeometry.js";
+import { type GrassDistanceFadeOptions, type GrassMaterialOptions, type GrassWindOptions } from "./grassMaterial.js";
 import type { TerrainArea, TerrainHeightSampler } from "./terrainMath.js";
 export { DEFAULT_GRASS_COUNT, DEFAULT_GRASS_DENSITY, resolveGrassInstanceBudget } from "./grassBudget.js";
+export { GRASS_TUFT_BLADES } from "./grassGeometry.js";
 export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "children" | "geometry" | "material"> {
     count?: number;
     density?: number;
@@ -13,11 +14,18 @@ export interface GrassFieldProps extends Omit<ThreeElements["mesh"], "args" | "c
     bladeHeight?: GrassRange;
     bladeWidth?: GrassRange;
     bladeBend?: GrassRange;
+    tuftBlades?: number;
+    tuftRadius?: number;
+    edgeFeather?: number;
+    exclude?: readonly GrassExclusion[];
     heightAt?: TerrainHeightSampler;
     colorBase?: GrassMaterialOptions["colorBase"];
     colorTip?: GrassMaterialOptions["colorTip"];
+    colorGround?: GrassMaterialOptions["colorGround"];
     colorVariation?: number;
     wind?: GrassWindOptions | false;
+    distanceFade?: GrassDistanceFadeOptions | false;
+    normalLift?: number;
     roughness?: number;
 }
-export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, heightAt, colorBase, colorTip, colorVariation, wind, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;
+export declare function GrassField({ count, density, budget, area, seed, segments, bladeHeight, bladeWidth, bladeBend, tuftBlades, tuftRadius, edgeFeather, exclude, heightAt, colorBase, colorTip, colorGround, colorVariation, wind, distanceFade, normalLift, roughness, castShadow, receiveShadow, frustumCulled, ...meshProps }: GrassFieldProps): import("react").JSX.Element;