@jgengine/shell 0.32.0 → 0.33.0

package/dist/settings/settingsController.d.ts

@@ -1,8 +1,9 @@
 import { bindingLabel, type ActionCodesMap } from "@jgengine/core/input/actionBindings";
 import type { BindingOverrides } from "@jgengine/core/input/bindingOverrides";
 import type { AudioBusDef } from "@jgengine/core/audio/audioFalloff";
-import { type GameSettingDef, type SettingCategory, type SettingCategoryDef } from "@jgengine/core/settings/settingsModel";
+import { type GameSettingDef, type SettingCategory, type SettingCategoryDef, type SettingsStore } from "@jgengine/core/settings/settingsModel";
 import { type GraphicsProfileOverrides } from "@jgengine/core/settings/graphicsSettings";
+import type { PostProcessingConfig } from "@jgengine/core/render/postProcessing";
 import { type SettingsActionView, type SettingsKeybindRow, type SettingsCategoryView, type SettingsController, type SettingsRow } from "@jgengine/react/settings";
 export type { SettingsActionView, SettingsKeybindRow, SettingsCategoryView, SettingsController, SettingsRow };
 export interface SettingsControllerInput {
@@ -14,6 +15,8 @@ export interface SettingsControllerInput {
     fovEnabled: boolean;
     /** The game's per-tier profile overrides (`defineGame({ graphics })`), so tier defaults match what renders. */
     graphics?: GraphicsProfileOverrides;
+    /** The post chain this game actually runs, so a stage row never outlives its pass. */
+    postProcessing?: PostProcessingConfig;
     hideBindings: readonly string[];
     /** Show the touch-controls skin selector in Controls (touch device with a dock). */
     touchStyle: boolean;
@@ -22,4 +25,10 @@ export interface SettingsControllerInput {
     resetBinding: (action: string) => void;
 }
 export declare function useSettingsCategories(config: SettingsControllerInput): SettingsCategoryView[];
+/**
+ * The built-in Graphics rows: tier, scale, filtering, shadows, one toggle per postfx stage this
+ * game's chain can build, then UI scale and FPS.
+ * @internal
+ */
+export declare function graphicsSettingRows(store: SettingsStore, overrides: GraphicsProfileOverrides | undefined, postProcessing: PostProcessingConfig | undefined): SettingsRow[];
 export { bindingLabel };

package/dist/settings/settingsController.js

@@ -1,9 +1,10 @@
 import { actionLabel, bindingLabel } from "@jgengine/core/input/actionBindings";
 import { BUILT_IN_SETTING_CATEGORIES, busVolumeSettingId, 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 { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, GRAPHICS_POST_STAGES, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
+import { ANISOTROPY_OPTIONS, applyGraphicsQuality, GRAPHICS_POST_STAGE_LABELS, graphicsPostStageSettingId, readGraphicsSettings, RENDER_SCALE_MAX, RENDER_SCALE_MIN, RENDER_SCALE_STEP, } from "@jgengine/core/settings/graphicsSettings";
 import { FRAME_RATE_LIMIT_DISPLAY, FRAME_RATE_LIMIT_OPTIONS } from "@jgengine/core/settings/frameRateLimit";
 import { accessibilitySettingRows } from "@jgengine/core/settings/accessibilitySettings";
 import { busMuteSettingId, MASTER_MUTE_SETTING_ID } from "../audio/busMix.js";
+import { availablePostfxStages } from "../postfx/PostProcessing.js";
 import { DEFAULT_TOUCH_JOYSTICK_VARIANT, TOUCH_JOYSTICK_VARIANT_OPTIONS, TOUCH_STYLE_OPTIONS, } from "@jgengine/core/input/touchScheme";
 import { TOUCH_STYLE_AUTO, useSettingsRevision } from "./appliedSettings.js";
 import { useSettingsStore, } from "@jgengine/react/settings";
@@ -80,75 +81,8 @@ export function useSettingsCategories(config) {
         },
         ...extrasFor("sound"),
     ];
-    const graphics = readGraphicsSettings(store, config.graphics);
     const graphicsRows = [
-        {
-            id: SETTING_IDS.graphicsQuality,
-            label: "Quality",
-            kind: "select",
-            value: graphics.quality,
-            options: GRAPHICS_QUALITY_OPTIONS,
-            set: (value) => applyGraphicsQuality(store, String(value), config.graphics),
-        },
-        {
-            id: SETTING_IDS.graphicsRenderScale,
-            label: "Render scale",
-            kind: "slider",
-            value: graphics.profile.renderScale,
-            min: RENDER_SCALE_MIN,
-            max: RENDER_SCALE_MAX,
-            step: RENDER_SCALE_STEP,
-            format: percent,
-            set: (value) => store.set(SETTING_IDS.graphicsRenderScale, value),
-        },
-        {
-            id: SETTING_IDS.graphicsFrameRateLimit,
-            label: "Frame rate limit",
-            kind: "select",
-            value: store.get(SETTING_IDS.graphicsFrameRateLimit, FRAME_RATE_LIMIT_DISPLAY),
-            options: FRAME_RATE_LIMIT_OPTIONS,
-            set: (value) => store.set(SETTING_IDS.graphicsFrameRateLimit, String(value)),
-        },
-        {
-            id: SETTING_IDS.graphicsAnisotropy,
-            label: "Texture filtering",
-            kind: "select",
-            value: String(graphics.profile.anisotropy),
-            options: ANISOTROPY_OPTIONS,
-            set: (value) => store.set(SETTING_IDS.graphicsAnisotropy, String(value)),
-        },
-        {
-            id: SETTING_IDS.graphicsShadows,
-            label: "Shadows",
-            kind: "toggle",
-            value: store.get(SETTING_IDS.graphicsShadows, DEFAULT_GRAPHICS_SHADOWS),
-            set: (value) => store.set(SETTING_IDS.graphicsShadows, value),
-        },
-        ...GRAPHICS_POST_STAGES.map((stage) => ({
-            id: graphicsPostStageSettingId(stage),
-            label: GRAPHICS_POST_STAGE_LABELS[stage],
-            kind: "toggle",
-            value: graphics.profile.postStages[stage],
-            set: (value) => store.set(graphicsPostStageSettingId(stage), value),
-        })),
-        {
-            id: SETTING_IDS.graphicsUiScale,
-            label: "UI scale",
-            kind: "slider",
-            value: store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE),
-            min: UI_SCALE_MIN,
-            max: UI_SCALE_MAX,
-            step: 0.05,
-            format: percent,
-            set: (value) => store.set(SETTING_IDS.graphicsUiScale, value),
-        },
-        {
-            id: SETTING_IDS.graphicsShowFps,
-            label: "Show FPS",
-            kind: "toggle",
-            value: store.get(SETTING_IDS.graphicsShowFps, false),
-            set: (value) => store.set(SETTING_IDS.graphicsShowFps, value),
-        },
+        ...graphicsSettingRows(store, config.graphics, config.postProcessing),
         ...extrasFor("graphics"),
     ];
     const gameplayRows = [
@@ -240,6 +174,84 @@ export function useSettingsCategories(config) {
     views.sort((a, b) => (declaredOrder.get(a.id) ?? indexOrder(order, a.id)) - (declaredOrder.get(b.id) ?? indexOrder(order, b.id)));
     return views;
 }
+/**
+ * The built-in Graphics rows: tier, scale, filtering, shadows, one toggle per postfx stage this
+ * game's chain can build, then UI scale and FPS.
+ * @internal
+ */
+export function graphicsSettingRows(store, overrides, postProcessing) {
+    const graphics = readGraphicsSettings(store, overrides);
+    const stages = postProcessing === undefined || postProcessing.enabled === false ? [] : availablePostfxStages(postProcessing);
+    return [
+        {
+            id: SETTING_IDS.graphicsQuality,
+            label: "Quality",
+            kind: "select",
+            value: graphics.quality,
+            options: GRAPHICS_QUALITY_OPTIONS,
+            set: (value) => applyGraphicsQuality(store, String(value), overrides),
+        },
+        {
+            id: SETTING_IDS.graphicsRenderScale,
+            label: "Render scale",
+            kind: "slider",
+            value: graphics.profile.renderScale,
+            min: RENDER_SCALE_MIN,
+            max: RENDER_SCALE_MAX,
+            step: RENDER_SCALE_STEP,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.graphicsRenderScale, value),
+        },
+        {
+            id: SETTING_IDS.graphicsFrameRateLimit,
+            label: "Frame rate limit",
+            kind: "select",
+            value: store.get(SETTING_IDS.graphicsFrameRateLimit, FRAME_RATE_LIMIT_DISPLAY),
+            options: FRAME_RATE_LIMIT_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsFrameRateLimit, String(value)),
+        },
+        {
+            id: SETTING_IDS.graphicsAnisotropy,
+            label: "Texture filtering",
+            kind: "select",
+            value: String(graphics.profile.anisotropy),
+            options: ANISOTROPY_OPTIONS,
+            set: (value) => store.set(SETTING_IDS.graphicsAnisotropy, String(value)),
+        },
+        {
+            id: SETTING_IDS.graphicsShadows,
+            label: "Shadows",
+            kind: "toggle",
+            value: store.get(SETTING_IDS.graphicsShadows, DEFAULT_GRAPHICS_SHADOWS),
+            set: (value) => store.set(SETTING_IDS.graphicsShadows, value),
+        },
+        ...stages.map((stage) => ({
+            id: graphicsPostStageSettingId(stage),
+            label: GRAPHICS_POST_STAGE_LABELS[stage],
+            kind: "toggle",
+            value: graphics.profile.postStages[stage],
+            set: (value) => store.set(graphicsPostStageSettingId(stage), value),
+        })),
+        {
+            id: SETTING_IDS.graphicsUiScale,
+            label: "UI scale",
+            kind: "slider",
+            value: store.get(SETTING_IDS.graphicsUiScale, DEFAULT_UI_SCALE),
+            min: UI_SCALE_MIN,
+            max: UI_SCALE_MAX,
+            step: 0.05,
+            format: percent,
+            set: (value) => store.set(SETTING_IDS.graphicsUiScale, value),
+        },
+        {
+            id: SETTING_IDS.graphicsShowFps,
+            label: "Show FPS",
+            kind: "toggle",
+            value: store.get(SETTING_IDS.graphicsShowFps, false),
+            set: (value) => store.set(SETTING_IDS.graphicsShowFps, value),
+        },
+    ];
+}
 function indexOrder(order, id) {
     const index = order.indexOf(id);
     return index === -1 ? 999 : index;

package/dist/vision/RevealVision.d.ts

@@ -6,7 +6,7 @@ export interface RevealVisionOptions {
     tags: readonly string[];
     resolveTags: (entity: SceneEntity) => readonly string[];
 }
-/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene. */
+/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene and refreshed on render. */
 export declare function useRevealHits(options: RevealVisionOptions): readonly RevealHit[];
 export interface RevealHighlightsProps extends RevealVisionOptions {
     enabled: boolean;
@@ -17,6 +17,8 @@ export interface RevealHighlightsProps extends RevealVisionOptions {
  * occluders (Dark Sight / detective-vision / wallhack style). Renders with
  * `depthTest: false` so the highlight draws over any wall standing between
  * the origin and the revealed entity, rather than the usual depth-sorted scene.
+ * Highlights track the origin and their targets every frame while enabled, so
+ * a disabled mode costs no renders.
  */
 export declare function RevealHighlights(props: RevealHighlightsProps): import("react").JSX.Element | null;
 export interface RevealScreenTintProps {

package/dist/vision/RevealVision.js

@@ -1,37 +1,56 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useMemo } from "react";
+import { useMemo, useState } from "react";
+import { useFrame } from "@react-three/fiber";
 import { DoubleSide } from "three";
 import { createRevealQuery } from "@jgengine/core/sensor/revealQuery";
 import { usePlayer, useSceneEntities } from "@jgengine/react/hooks";
-/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene. */
+function revealHits(entities, originId, options) {
+    const byId = new Map(entities.map((entity) => [entity.id, entity]));
+    const query = createRevealQuery({
+        resolvePosition: (id) => byId.get(id)?.position,
+        resolveTags: (id) => {
+            const entity = byId.get(id);
+            return entity === undefined ? [] : options.resolveTags(entity);
+        },
+        candidates: () => entities.map((entity) => entity.id),
+    });
+    return query.inRadius(originId, options.radius, options.tags);
+}
+/** Occlusion-ignoring tagged-entity radius query (#115), bound to the live scene and refreshed on render. */
 export function useRevealHits(options) {
     const entities = useSceneEntities();
     const player = usePlayer();
     const originId = options.originEntityId ?? player.userId;
     const tagsKey = options.tags.join("|");
-    return useMemo(() => {
-        const byId = new Map(entities.map((entity) => [entity.id, entity]));
-        const query = createRevealQuery({
-            resolvePosition: (id) => byId.get(id)?.position,
-            resolveTags: (id) => {
-                const entity = byId.get(id);
-                return entity === undefined ? [] : options.resolveTags(entity);
-            },
-            candidates: () => entities.map((entity) => entity.id),
-        });
-        return query.inRadius(originId, options.radius, options.tags);
-    }, [entities, originId, options.radius, tagsKey, options.tags, options.resolveTags]);
+    return useMemo(() => revealHits(entities, originId, options), [entities, originId, options.radius, tagsKey, options.tags, options.resolveTags]);
+}
+/** Frames on a counter while `active`: the hook lists only change on membership, so a live overlay drives its own re-render. */
+function useFrameRefresh(active) {
+    const [frame, setFrame] = useState(0);
+    useFrame(() => {
+        if (active)
+            setFrame((value) => (value + 1) % 1_000_000);
+    });
+    return frame;
 }
 /**
  * Screen-space reveal effect (#115) — highlights tagged entities through
  * occluders (Dark Sight / detective-vision / wallhack style). Renders with
  * `depthTest: false` so the highlight draws over any wall standing between
  * the origin and the revealed entity, rather than the usual depth-sorted scene.
+ * Highlights track the origin and their targets every frame while enabled, so
+ * a disabled mode costs no renders.
  */
 export function RevealHighlights(props) {
     const { enabled, color = "#7dd3fc" } = props;
-    const hits = useRevealHits(props);
+    const frame = useFrameRefresh(enabled);
     const entities = useSceneEntities();
+    const player = usePlayer();
+    const originId = props.originEntityId ?? player.userId;
+    const tagsKey = props.tags.join("|");
+    const hits = useMemo(() => (enabled ? revealHits(entities, originId, props) : []), 
+    // `frame` is the refresh: the list identity says nothing about where the origin or the targets moved.
+    [enabled, frame, entities, originId, props.radius, tagsKey, props.tags, props.resolveTags]);
     if (!enabled)
         return null;
     return (_jsx(_Fragment, { children: hits.map((hit) => {

package/dist/world/WorldItems.js

@@ -5,12 +5,16 @@ import { useFrame } from "@react-three/fiber";
 import { resolveWorldItemPresentation } from "@jgengine/core/game/worldItem";
 import { useGameContext } from "@jgengine/react/provider";
 import { useWorldItems } from "@jgengine/react/hooks";
+import { emptyPoseMemo, writePoseIfChanged } from "./entityPose.js";
 import { POINTER_ENTITY_KEY } from "../pointer/pointerService.js";
 const DEFAULT_BEAM_HEIGHT = 2.5;
 const FALLBACK_COLOR = "#e5e7eb";
 const REST_HEIGHT = 0.32;
 const SPAWN_DURATION = 0.4;
-function WorldItemMarker({ instanceId, position, color, beam, label, beamHeight, }) {
+function WorldItemMarker({ instanceId, color, beam, label, beamHeight, }) {
+    const ctx = useGameContext();
+    const groupRef = useRef(null);
+    const poseRef = useRef(emptyPoseMemo());
     const beamPoints = useMemo(() => [
         [0, 0, 0],
         [0, beamHeight, 0],
@@ -21,6 +25,10 @@ function WorldItemMarker({ instanceId, position, color, beam, label, beamHeight,
     const gemRef = useRef(null);
     const ageRef = useRef(0);
     useFrame((_state, delta) => {
+        const group = groupRef.current;
+        const live = ctx.scene.entity.get(instanceId);
+        if (group !== null && live !== null)
+            writePoseIfChanged(group, live, poseRef.current);
         const gem = gemRef.current;
         if (gem === null)
             return;
@@ -31,7 +39,7 @@ function WorldItemMarker({ instanceId, position, color, beam, label, beamHeight,
         gem.position.y = REST_HEIGHT + bob + spawn;
         gem.rotation.y = age * 1.6;
     });
-    return (_jsxs("group", { position: [position[0], position[1], position[2]], userData: { [POINTER_ENTITY_KEY]: instanceId }, children: [_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.26, 0.4, 24] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85 })] }), _jsx("group", { ref: gemRef, "position-y": REST_HEIGHT, children: _jsxs("mesh", { children: [_jsx("octahedronGeometry", { args: [0.22, 0] }), _jsx("meshStandardMaterial", { color: color, emissive: color, emissiveIntensity: 0.6 })] }) }), beam ? _jsx(Line, { points: beamPoints, color: color, lineWidth: 2, transparent: true, opacity: 0.55 }) : null, label !== undefined && label.length > 0 ? (_jsx(Html, { position: [0, beamHeight + 0.2, 0], center: true, distanceFactor: 12, zIndexRange: [15, 0], children: _jsx("div", { className: "whitespace-nowrap rounded-sm border px-1.5 py-0.5 text-[11px] font-bold shadow", style: { borderColor: color, color, backgroundColor: "rgba(10,10,14,0.75)" }, children: label }) })) : null] }));
+    return (_jsxs("group", { ref: groupRef, matrixAutoUpdate: false, userData: { [POINTER_ENTITY_KEY]: instanceId }, children: [_jsxs("mesh", { "rotation-x": -Math.PI / 2, "position-y": 0.03, children: [_jsx("ringGeometry", { args: [0.26, 0.4, 24] }), _jsx("meshBasicMaterial", { color: color, transparent: true, opacity: 0.85 })] }), _jsx("group", { ref: gemRef, "position-y": REST_HEIGHT, children: _jsxs("mesh", { children: [_jsx("octahedronGeometry", { args: [0.22, 0] }), _jsx("meshStandardMaterial", { color: color, emissive: color, emissiveIntensity: 0.6 })] }) }), beam ? _jsx(Line, { points: beamPoints, color: color, lineWidth: 2, transparent: true, opacity: 0.55 }) : null, label !== undefined && label.length > 0 ? (_jsx(Html, { position: [0, beamHeight + 0.2, 0], center: true, distanceFactor: 12, zIndexRange: [15, 0], children: _jsx("div", { className: "whitespace-nowrap rounded-sm border px-1.5 py-0.5 text-[11px] font-bold shadow", style: { borderColor: color, color, backgroundColor: "rgba(10,10,14,0.75)" }, children: label }) })) : null] }));
 }
 /** Rarity→beam/color/label render binding + loot-filter overlay (#32/#33) for every dropped `worldItem`. */
 export function WorldItems({ config }) {
@@ -45,6 +53,6 @@ export function WorldItems({ config }) {
             const presentation = resolveWorldItemPresentation(item, config?.rarityStyle, config?.filter);
             if (presentation.hidden)
                 return null;
-            return (_jsx(WorldItemMarker, { instanceId: item.instanceId, position: entity.position, color: presentation.color ?? FALLBACK_COLOR, beam: presentation.beam, label: presentation.label, beamHeight: beamHeight }, item.instanceId));
+            return (_jsx(WorldItemMarker, { instanceId: item.instanceId, color: presentation.color ?? FALLBACK_COLOR, beam: presentation.beam, label: presentation.label, beamHeight: beamHeight }, item.instanceId));
         }) }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/shell",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Game player shell for JGengine: React Three Fiber canvas, orbit camera, input tracking, HUD mounting, GameUiPreview, and a demo game. Consumers supply a GameRegistry.",
   "license": "Apache-2.0",
   "type": "module",
@@ -35,9 +35,9 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@jgengine/core": "^0.32.0",
-    "@jgengine/react": "^0.32.0",
-    "@jgengine/ws": "^0.32.0"
+    "@jgengine/core": "^0.33.0",
+    "@jgengine/react": "^0.33.0",
+    "@jgengine/ws": "^0.33.0"
   },
   "peerDependencies": {
     "@react-three/drei": "^10.0.0",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.33.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -285,7 +285,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.32.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.33.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter