@jgengine/shell 0.10.0 → 0.11.0

package/dist/scene/GrassFieldRenderer.js

@@ -0,0 +1,25 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { resolveGrassObject } from "@jgengine/core/world/grassKind";
+import { GrassField } from "../terrain/GrassField.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+function hashSeed(text) {
+    let h = 2166136261 >>> 0;
+    for (let i = 0; i < text.length; i += 1) {
+        h ^= text.charCodeAt(i);
+        h = Math.imul(h, 16777619);
+    }
+    return (h >>> 0) % 100000;
+}
+/** One authored grass volume → an instanced vertex-wind `GrassField` over its footprint. */
+function OneGrass({ object, context }) {
+    const resolved = useMemo(() => resolveGrassObject(object), [object]);
+    if (resolved === null)
+        return null;
+    const { rules, size, center } = resolved;
+    return (_jsx(GrassField, { position: [center[0], center[1], center[2]], area: [size[0], size[1]], density: rules.density, bladeHeight: [rules.bladeHeight * 0.7, rules.bladeHeight], colorBase: rules.colorBase, colorTip: rules.colorTip, colorVariation: rules.colorVariation, roughness: rules.roughness, seed: hashSeed(rules.seed.length > 0 ? rules.seed : object.id), heightAt: (x, z) => context.field.sampleHeight(x, z), wind: { strength: rules.windStrength, speed: rules.windSpeed, gustScale: rules.windGust } }));
+}
+/** Registers the `grass_field` volume renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerGrassFieldRenderer() {
+    registerSceneKindRenderer("grass_field", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneGrass, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/SoilPatchRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the `soil` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerSoilPatchRenderer(): void;

package/dist/scene/SoilPatchRenderer.js

@@ -0,0 +1,21 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo } from "react";
+import { resolveSoilObject } from "@jgengine/core/world/soilKind";
+import { createSoilPatchMaterial } from "../terrain/soilPatchMaterial.js";
+import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
+const SOIL_PATCH_THICKNESS = 0.08;
+/** One authored soil volume → a ground-hugging patch mesh with a crack/moss shader material. */
+function OneSoil({ object, context }) {
+    const resolved = useMemo(() => resolveSoilObject(object), [object]);
+    const material = useMemo(() => (resolved === null ? null : createSoilPatchMaterial(resolved.rules)), [resolved]);
+    useEffect(() => () => material?.dispose(), [material]);
+    if (resolved === null || material === null)
+        return null;
+    const groundY = context.field.sampleHeight(resolved.center[0], resolved.center[2]);
+    const y = groundY + SOIL_PATCH_THICKNESS / 2 + 0.02;
+    return (_jsx("mesh", { position: [resolved.center[0], y, resolved.center[2]], material: material, receiveShadow: true, children: _jsx("boxGeometry", { args: [resolved.size[0], SOIL_PATCH_THICKNESS, resolved.size[1]] }) }));
+}
+/** Registers the `soil` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerSoilPatchRenderer() {
+    registerSceneKindRenderer("soil", ({ objects, context }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneSoil, { object: object, context: context }, object.id))) })));
+}

package/dist/scene/StudioStage.d.ts

@@ -0,0 +1,37 @@
+import { type ReactNode } from "react";
+/** Lighting mood for a {@link StudioStage} — a named 3-point rig + backdrop palette. */
+export type StudioMood = "studio" | "daylight" | "dusk" | "night";
+/** Props for {@link StudioStage}. */
+export interface StudioStageProps {
+    mood?: StudioMood;
+    /** Override the scene background color (hex). Default: the mood's backdrop. */
+    backdrop?: string;
+    /** Turntable spin speed in radians/second (spins the children). 0 disables. Default 0. */
+    turntable?: number;
+    /** Draw the seamless floor + set the scene background. Off for open-world scenes. Default true. */
+    environment?: boolean;
+    /**
+     * Yaw the children every frame so `forward` points at the active camera — frame the declared front
+     * with zero `rotationY` tuning. Overrides `turntable` (the two are mutually exclusive: one spins the
+     * content, the other holds it facing whoever's looking). Default false.
+     */
+    faceCamera?: boolean;
+    /**
+     * The staged content's declared forward axis (`GeneratedAsset.forward`, or a scene kind's own
+     * convention) — the direction `faceCamera` turns to point at the camera. Default `[0, 0, 1]`, the
+     * engine-wide convention (`DEFAULT_FORWARD` in `@jgengine/core/scene/facing`).
+     */
+    forward?: readonly [number, number, number];
+    children: ReactNode;
+}
+/**
+ * A reusable cinematic "product-shot" stage — a 3-point lighting rig (key/fill/rim + ambient), a
+ * seamless backdrop, and an optional turntable — so any parametric studio renders framed and lit like
+ * a hero shot instead of a flat proxy under default light. Pair with `PlayableGame.postProcessing =
+ * STUDIO_STAGE_POST` for the full film grade. Set `environment: false` to keep an open-world sky/ground
+ * and use it purely as a lighting rig. Set `faceCamera` to auto-orient the declared `forward` toward
+ * the camera instead of hand-tuning `rotationY` on the child.
+ *
+ * @capability studio-stage cinematic lighting rig + backdrop + turntable for parametric studios
+ */
+export declare function StudioStage({ mood, backdrop, turntable, environment, faceCamera, forward, children, }: StudioStageProps): import("react").JSX.Element;

package/dist/scene/StudioStage.js

@@ -0,0 +1,42 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useRef } from "react";
+import { useFrame, useThree } from "@react-three/fiber";
+import * as THREE from "three";
+import { DEFAULT_FORWARD, yawToFace } from "@jgengine/core/scene/facing";
+const MOODS = {
+    studio: { key: 3.1, keyColor: "#fff4e6", fill: 0.9, fillColor: "#cdd8ff", rim: 2.6, rimColor: "#ffe9c7", ambient: 0.35, ambientColor: "#5b6472", backdrop: "#14161c", floor: "#1b1e26" },
+    daylight: { key: 3.4, keyColor: "#fff6ea", fill: 1.2, fillColor: "#d6e6ff", rim: 1.6, rimColor: "#ffffff", ambient: 0.6, ambientColor: "#8fa2bf", backdrop: "#cdd7e4", floor: "#aeb7c4" },
+    dusk: { key: 2.6, keyColor: "#ffcf9e", fill: 0.7, fillColor: "#7c8fd8", rim: 3.0, rimColor: "#ff9d6b", ambient: 0.4, ambientColor: "#4a4668", backdrop: "#221a26", floor: "#241d2a" },
+    night: { key: 1.6, keyColor: "#bcd0ff", fill: 0.4, fillColor: "#38507e", rim: 2.4, rimColor: "#9fd0ff", ambient: 0.22, ambientColor: "#1e2740", backdrop: "#0a0c12", floor: "#0e1119" },
+};
+/**
+ * A reusable cinematic "product-shot" stage — a 3-point lighting rig (key/fill/rim + ambient), a
+ * seamless backdrop, and an optional turntable — so any parametric studio renders framed and lit like
+ * a hero shot instead of a flat proxy under default light. Pair with `PlayableGame.postProcessing =
+ * STUDIO_STAGE_POST` for the full film grade. Set `environment: false` to keep an open-world sky/ground
+ * and use it purely as a lighting rig. Set `faceCamera` to auto-orient the declared `forward` toward
+ * the camera instead of hand-tuning `rotationY` on the child.
+ *
+ * @capability studio-stage cinematic lighting rig + backdrop + turntable for parametric studios
+ */
+export function StudioStage({ mood = "studio", backdrop, turntable = 0, environment = true, faceCamera = false, forward = DEFAULT_FORWARD, children, }) {
+    const spin = useRef(null);
+    const camera = useThree((state) => state.camera);
+    const groupWorld = useRef(new THREE.Vector3()).current;
+    const cameraWorld = useRef(new THREE.Vector3()).current;
+    useFrame((_, delta) => {
+        const group = spin.current;
+        if (group === null)
+            return;
+        if (faceCamera) {
+            group.getWorldPosition(groupWorld);
+            camera.getWorldPosition(cameraWorld);
+            group.rotation.y = yawToFace(forward, [groupWorld.x, groupWorld.z], [cameraWorld.x, cameraWorld.z]);
+            return;
+        }
+        if (turntable !== 0)
+            group.rotation.y += turntable * delta;
+    });
+    const rig = MOODS[mood];
+    return (_jsxs(_Fragment, { children: [environment ? _jsx("color", { attach: "background", args: [backdrop ?? rig.backdrop] }) : null, _jsx("ambientLight", { intensity: rig.ambient, color: rig.ambientColor }), _jsx("directionalLight", { position: [7, 9, 5], intensity: rig.key, color: rig.keyColor, castShadow: true, "shadow-mapSize": [2048, 2048], "shadow-bias": -0.0004, children: _jsx("orthographicCamera", { attach: "shadow-camera", args: [-24, 24, 24, -24, 0.5, 80] }) }), _jsx("directionalLight", { position: [-8, 5, 3], intensity: rig.fill, color: rig.fillColor }), _jsx("directionalLight", { position: [0, 6, -10], intensity: rig.rim, color: rig.rimColor }), environment ? (_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": -0.01, receiveShadow: true, children: [_jsx("planeGeometry", { args: [400, 400] }), _jsx("meshStandardMaterial", { color: rig.floor, roughness: 0.95, metalness: 0 })] })) : null, _jsx("group", { ref: spin, children: children })] }));
+}

package/dist/scene/WaterRenderer.d.ts

@@ -0,0 +1,2 @@
+/** Registers the `water` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export declare function registerWaterRenderer(): void;

package/dist/scene/WaterRenderer.js

@@ -0,0 +1,37 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { 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) {
+    const maxSpan = Math.max(size[0], size[1]);
+    return {
+        size: size[0],
+        depth: size[1],
+        resolution: Math.min(160, Math.max(16, 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,
+            fresnelStrength: rules.reflectivity,
+        },
+        foam: { coverage: Math.min(1, rules.foam / 4), intensity: Math.min(1.5, rules.foam / 3) },
+    };
+}
+/** One authored water volume → a bounded, animated Ocean plane at the box top. */
+function OneWater({ object }) {
+    const resolved = useMemo(() => resolveWaterObject(object), [object]);
+    const config = useMemo(() => (resolved === null ? null : toOceanConfig(resolved.rules, resolved.size)), [resolved]);
+    if (resolved === null || config === null)
+        return null;
+    return _jsx(Ocean, { config: config, position: [resolved.center[0], resolved.center[1], resolved.center[2]] });
+}
+/** Registers the `water` volume runtime renderer. Called by `registerBuiltinSceneKindRenderers`. @internal */
+export function registerWaterRenderer() {
+    registerSceneKindRenderer("water", ({ objects }) => (_jsx(_Fragment, { children: objects.map((object) => (_jsx(OneWater, { object: object }, 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,22 @@
+/**
+ * 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";
+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();
+}

package/dist/scene/sceneKindRenderers.d.ts

@@ -0,0 +1,28 @@
+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;
+}
+/** 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,6 +1,11 @@
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
 import { 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;

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]);

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,43 @@
+/** 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";
+/** 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;
+    /** 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, lift, size, groundSnap, onDraggingChange, onRelease, }: TransformGizmoProps) => import("react").JSX.Element>;

package/dist/structures/TransformGizmo.js

@@ -0,0 +1,55 @@
+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";
+/**
+ * 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, 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 = snapMode === "grid"
+        ? { translationSnap: gridSize, rotationSnap: Math.PI / 12 }
+        : { rotationSnap: Math.PI / 12 };
+    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, ...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.js

@@ -23,7 +23,7 @@ export function GrassField({ count = DEFAULT_GRASS_COUNT, density = DEFAULT_GRAS
         wind,
         roughness,
     }), [colorBase, colorTip, colorVariation, roughness, wind]);
-    geometry.instanceCount = resolveGrassInstanceBudget(count, density, budget);
+    geometry.instanceCount = resolveGrassInstanceBudget(count, density, area, budget);
     useFrame((state) => {
         handle.uniforms.uTime.value = state.clock.elapsedTime;
     });

package/dist/terrain/TerraformBrushCursor.js

@@ -2,7 +2,10 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 const MODE_COLOR = {
     raise: "#38bdf8",
     lower: "#fb923c",
+    smooth: "#c084fc",
     flatten: "#a3e635",
+    noise: "#facc15",
+    ramp: "#2dd4bf",
     paint: "#e879f9",
 };
 export function TerraformBrushCursor({ center, y = 0.05, radius, mode }) {

package/dist/terrain/grassBudget.d.ts

@@ -1,3 +1,12 @@
+import { type TerrainArea } from "./terrainMath.js";
 export declare const DEFAULT_GRASS_COUNT = 1500;
-export declare const DEFAULT_GRASS_DENSITY = 1;
-export declare function resolveGrassInstanceBudget(count: number, density: number, budget?: number): number;
+/** Blades per square meter — matches `@jgengine/core/world/vegetation`'s `VEGETATION_DEFAULTS.density`, so an editor-placed grass volume and a bare `<GrassField>` agree on what "4" means. */
+export declare const DEFAULT_GRASS_DENSITY = 4;
+/**
+ * Blade instance count for a patch: `density` (blades/m²) times the patch's
+ * `area`, capped at `budget` (defaulting to `count`, the buffer's allocated
+ * capacity) so a big field never exceeds the perf ceiling — it just renders
+ * sparser than requested and logs a devtools warning when that happens.
+  * @internal
+  */
+export declare function resolveGrassInstanceBudget(count: number, density: number, area: TerrainArea, budget?: number): number;

package/dist/terrain/grassBudget.js

@@ -1,6 +1,22 @@
+import { devtools } from "@jgengine/core/devtools/devtools";
+import { resolveTerrainSize } from "./terrainMath.js";
 export const DEFAULT_GRASS_COUNT = 1500;
-export const DEFAULT_GRASS_DENSITY = 1;
-export function resolveGrassInstanceBudget(count, density, budget) {
-    const capped = budget === undefined ? count : Math.min(count, Math.max(0, Math.floor(budget)));
-    return Math.floor(Math.max(0, Math.min(1, density)) * capped);
+/** Blades per square meter — matches `@jgengine/core/world/vegetation`'s `VEGETATION_DEFAULTS.density`, so an editor-placed grass volume and a bare `<GrassField>` agree on what "4" means. */
+export const DEFAULT_GRASS_DENSITY = 4;
+/**
+ * Blade instance count for a patch: `density` (blades/m²) times the patch's
+ * `area`, capped at `budget` (defaulting to `count`, the buffer's allocated
+ * capacity) so a big field never exceeds the perf ceiling — it just renders
+ * sparser than requested and logs a devtools warning when that happens.
+  * @internal
+  */
+export function resolveGrassInstanceBudget(count, density, area, budget) {
+    const size = resolveTerrainSize(area);
+    const areaSqMeters = Math.max(0, size.width) * Math.max(0, size.depth);
+    const requested = Math.max(0, density) * areaSqMeters;
+    const cap = budget === undefined ? count : Math.min(count, Math.max(0, Math.floor(budget)));
+    if (requested > cap) {
+        devtools.logs.push("warn", `[jgengine:grass] density ${density} blades/m² over ${areaSqMeters.toFixed(0)}m² wants ${Math.floor(requested)} blades — clamped to budget ${cap}`);
+    }
+    return Math.floor(Math.min(Math.max(0, cap), requested));
 }