@jgengine/shell 0.10.0 → 0.12.0

package/dist/camera/shakeChannelMath.d.ts

@@ -5,4 +5,5 @@ export interface CameraShakeChannel {
     sample(config?: Parameters<typeof shakeOffset>[1]): ShakeOffset;
     trauma(): number;
 }
+/** @internal */
 export declare function createCameraShakeChannel(defaultDecayPerSecond?: number): CameraShakeChannel;

package/dist/camera/shakeChannelMath.js

@@ -1,4 +1,5 @@
 import { addTrauma, createTrauma, shakeOffset, stepTrauma } from "./rigMath.js";
+/** @internal */
 export function createCameraShakeChannel(defaultDecayPerSecond = 1.6) {
     const state = createTrauma();
     let decay = defaultDecayPerSecond;

package/dist/commandSink.d.ts

@@ -4,15 +4,20 @@ import type { LiveGameBackend } from "@jgengine/core/runtime/transport";
 export interface CommandSink {
     run(name: string, input: unknown): void;
 }
-/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+/** Runs commands on the local `ctx` — the default, client-authoritative path.
+ * @internal
+ */
 export declare function localCommandSink(ctx: GameContext): CommandSink;
-/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync.
+ * @internal
+ */
 export declare function remoteCommandSink(backend: Pick<LiveGameBackend, "transport">, serverId: string): CommandSink;
 /**
  * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
  * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
  * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
- */
+  * @internal
+  */
 export declare function resolveCommandSink(ctx: GameContext, opts: {
     serverAuthoritative: boolean;
     backend: Pick<LiveGameBackend, "transport"> | null;

package/dist/commandSink.js

@@ -1,4 +1,6 @@
-/** Runs commands on the local `ctx` — the default, client-authoritative path. */
+/** Runs commands on the local `ctx` — the default, client-authoritative path.
+ * @internal
+ */
 export function localCommandSink(ctx) {
     return {
         run(name, input) {
@@ -6,7 +8,9 @@ export function localCommandSink(ctx) {
         },
     };
 }
-/** Sends commands to the authoritative host over the transport; the result replicates back through world sync. */
+/** Sends commands to the authoritative host over the transport; the result replicates back through world sync.
+ * @internal
+ */
 export function remoteCommandSink(backend, serverId) {
     return {
         run(name, input) {
@@ -18,7 +22,8 @@ export function remoteCommandSink(backend, serverId) {
  * The sink a server-authoritative shell should dispatch gameplay commands through: remote when the game opts into
  * `authority: "server"` and a server is joined, local otherwise. Client-only UI commands (targeting, hotbar
  * scroll) keep calling `ctx.game.commands.run` directly — only authoritative gameplay verbs route to the host.
- */
+  * @internal
+  */
 export function resolveCommandSink(ctx, opts) {
     if (opts.serverAuthoritative && opts.backend !== null && opts.serverId !== null) {
         return remoteCommandSink(opts.backend, opts.serverId);

package/dist/defineGame.d.ts

@@ -1,7 +1,8 @@
-import type { ComponentType } from "react";
+import { type ComponentType } from "react";
 import { type GameDefinitionConfig, type GameLoop } from "@jgengine/core/game/defineGame";
 import type { GameContext, GameContextContent } from "@jgengine/core/runtime/gameContext";
 import type { ModelAssetRef } from "@jgengine/core/scene/assetCatalog";
+import type { ModelConfig } from "@jgengine/core/game/playableGame";
 import type { PlayableGame } from "./registry.js";
 type EngineFields<TAssetRef extends ModelAssetRef> = Omit<GameDefinitionConfig<TAssetRef>, "loop" | "ui" | "multiplayer"> & {
     multiplayer?: GameDefinitionConfig<TAssetRef>["multiplayer"];
@@ -10,7 +11,20 @@ type PresentationFields = Omit<PlayableGame, "game" | "content" | "loop" | "Game
     content?: GameContextContent;
     loop?: Partial<GameLoop<GameContext>>;
     GameUI?: ComponentType;
+    /** Tunes how the auto-mounted `AuthoredScene` places the document's catalog-id markers into the object store. Default `true`; pass `false` when the game spawns its placed content as entities itself (`placeAuthoredObjects`) to avoid a double render. */
+    scenePlacement?: boolean | {
+        verticalOffset?: number;
+    };
+    /** GLB models for the auto-mounted scene's scatter palette items, keyed by palette item id; string ids resolve through the game's asset catalog. Unmatched items keep the built-in proxy meshes. */
+    sceneScatterModels?: Record<string, string | ModelConfig>;
 };
 export type GameConfig<TAssetRef extends ModelAssetRef = ModelAssetRef> = EngineFields<TAssetRef> & PresentationFields;
+/**
+ * The one public authoring entry point: compose engine fields (systems, world, physics, input) and
+ * presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`.
+ * Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
+ *
+ * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
+ */
 export declare function defineGame<TAssetRef extends ModelAssetRef = ModelAssetRef>(config: GameConfig<TAssetRef>): PlayableGame;
 export {};

package/dist/defineGame.js

@@ -1,31 +1,67 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { defineGame as defineEngineGame, } from "@jgengine/core/game/defineGame";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { defineGameDefinition as defineEngineGame, } from "@jgengine/core/game/defineGame";
+import { syncLifecyclePhase } from "@jgengine/core/game/gamePhase";
 import { offline } from "@jgengine/core/runtime/adapter";
 import { EnvironmentScene } from "./environment.js";
+import { terrainGroundColorSampler } from "./environment/terrainGroundColor.js";
+import { AuthoredScene } from "./scene/AuthoredScene.js";
 const noop = () => { };
 function worldBackdrop(feature) {
     return function WorldBackdrop() {
         return _jsx(EnvironmentScene, { feature: feature });
     };
 }
+function authoredSceneOverlay(document, placement, scatterModels, assets, world, Vfx) {
+    const terrain = world !== undefined && world.kind === "environment" ? world.terrain : undefined;
+    return function AuthoredSceneOverlay(props) {
+        const groundColorAt = useMemo(() => terrainGroundColorSampler(terrain, props.ctx.world.ground), [props.ctx.world.ground]);
+        return (_jsxs(_Fragment, { children: [_jsx(AuthoredScene, { document: document, field: props.ctx.world.ground, placeObjects: placement, ...(scatterModels === undefined ? {} : { scatterModels, assets }), ...(groundColorAt === undefined ? {} : { groundColorAt }) }), Vfx === undefined ? null : _jsx(Vfx, { ...props })] }));
+    };
+}
 const emptyUi = () => null;
+/**
+ * The one public authoring entry point: compose engine fields (systems, world, physics, input) and
+ * presentation fields (camera, HUD, audio, authored scene) into a `PlayableGame` ready for `GameHost`.
+ * Defaults to solo/offline multiplayer; `editorLayers` auto-mounts the authored scene document.
+ *
+ * @capability define-game single public game-authoring path — compose systems, world, presentation, and authored scene in one definition
+ */
 export function defineGame(config) {
-    const { content, loop, GameUI, environment, camera, multiplayer, WorldOverlay, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, ...engineFields } = config;
-    const game = defineEngineGame({ ...engineFields, multiplayer: multiplayer ?? offline() });
+    const { content, loop, GameUI, environment, camera, multiplayer, editorLayers, editorCatalogs, scenePlacement, sceneScatterModels, WorldOverlay, viewmodel, renderEntity, renderObject, entitySprites, entityModels, objectModels, hotbarSelection, prompts, pointer, touch, orientation, worldHealthBars, nameplates, presentationEffects, audio, entitySounds, objectSounds, worldItem, collision, movement, lighting, backdrop, postProcessing, shadows, presentation, objectStyles, devtools, capture, platforms, hudFit, ...engineFields } = config;
+    const game = defineEngineGame({
+        ...engineFields,
+        multiplayer: multiplayer ?? offline(),
+        loop,
+    });
+    function withPhaseSync(inner) {
+        return (ctx, ...args) => {
+            inner?.(ctx, ...args);
+            syncLifecyclePhase(ctx, game.lifecycle);
+        };
+    }
+    const composed = game.loop;
     return {
         game,
         content: content ?? {},
         loop: {
-            onInit: loop?.onInit ?? noop,
-            onNewPlayer: loop?.onNewPlayer ?? noop,
-            onTick: loop?.onTick ?? noop,
-            onPlayerLeave: loop?.onPlayerLeave ?? noop,
+            onInit: withPhaseSync(composed?.onInit),
+            onNewPlayer: withPhaseSync(composed?.onNewPlayer),
+            onTick: withPhaseSync(composed?.onTick),
+            onPlayerLeave: composed?.onPlayerLeave ?? noop,
+            onReset: composed?.onReset?.bind(composed) ?? noop,
+            onDispose: composed?.onDispose?.bind(composed) ?? noop,
         },
         GameUI: GameUI ?? emptyUi,
         environment: environment ??
             (game.world?.kind === "environment" ? worldBackdrop(game.world) : undefined),
         camera: camera ?? { perspective: "third" },
-        WorldOverlay,
+        editorLayers,
+        editorCatalogs,
+        WorldOverlay: editorLayers === undefined
+            ? WorldOverlay
+            : authoredSceneOverlay(editorLayers, scenePlacement ?? true, sceneScatterModels, game.assets, game.world, WorldOverlay),
+        viewmodel,
         renderEntity,
         renderObject,
         entitySprites,
@@ -37,6 +73,8 @@ export function defineGame(config) {
         touch,
         orientation,
         worldHealthBars,
+        nameplates,
+        presentationEffects,
         audio,
         entitySounds,
         objectSounds,
@@ -50,5 +88,8 @@ export function defineGame(config) {
         presentation,
         objectStyles,
         devtools,
+        capture,
+        platforms,
+        hudFit,
     };
 }

package/dist/devtools/ColPanel.d.ts

@@ -0,0 +1 @@
+export declare function ColPanel(): import("react").JSX.Element;

package/dist/devtools/ColPanel.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSyncExternalStore } from "react";
+import { COLLISION_DEBUG_LAYERS, collisionDebug } from "./collisionDebug.js";
+const LAYER_LABELS = {
+    hitboxes: "Damage hitboxes",
+    bodies: "Physical bodies",
+    projectiles: "Projectile paths",
+    muzzles: "Muzzle / shot origins",
+    aimLaser: "Aim laser (authoritative)",
+};
+export function ColPanel() {
+    const state = useSyncExternalStore(collisionDebug.subscribe, () => collisionDebug.getState(), () => collisionDebug.getState());
+    return (_jsxs("div", { className: "space-y-2", children: [_jsx("div", { className: "text-[10px] text-neutral-500", children: "F2+D world collision debugger \u00B7 layers stay on when panel closes \u00B7 zero cost when all off" }), _jsxs("div", { className: "flex gap-1", children: [_jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-0.5 text-neutral-300 ring-1 ring-inset ring-white/[0.08] transition-colors hover:bg-white/10", onClick: () => collisionDebug.setAllLayers(true), children: "All on" }), _jsx("button", { type: "button", className: "rounded-md bg-white/[0.04] px-2 py-0.5 text-neutral-300 ring-1 ring-inset ring-white/[0.08] transition-colors hover:bg-white/10", onClick: () => collisionDebug.setAllLayers(false), children: "All off" })] }), _jsx("div", { className: "space-y-1", children: COLLISION_DEBUG_LAYERS.map((layer) => (_jsxs("label", { className: "flex cursor-pointer items-center gap-2 text-neutral-200", children: [_jsx("input", { type: "checkbox", checked: state.layers[layer], onChange: (event) => collisionDebug.setLayer(layer, event.target.checked) }), _jsx("span", { children: LAYER_LABELS[layer] })] }, layer))) }), _jsx("div", { className: "border-t border-neutral-800 pt-1.5 font-mono text-[9px] text-neutral-500", children: "hitbox pink \u00B7 body cyan \u00B7 muzzle red \u00B7 laser lime \u00B7 X damage \u00B7 \u25CB solid \u00B7 \u00B7 miss" })] }));
+}

package/dist/devtools/DevtoolsOverlay.d.ts

@@ -1,11 +1,13 @@
-import { type DevtoolsOverrides, type DevtoolsSnapshot } from "@jgengine/core/devtools/devtools";
+import { type DevtoolsSnapshot } from "@jgengine/core/devtools/devtools";
 import type { GameContext } from "@jgengine/core/runtime/gameContext";
 import type { ShellMultiplayer } from "../multiplayer.js";
 import type { PlayableGame } from "../registry.js";
-export declare function persistDevtoolsOverrides(gameName: string): DevtoolsOverrides;
-export declare function applyStoredDevtoolsOverrides(gameName: string): void;
+export { applyStoredDevtoolsOverrides, persistDevtoolsOverrides } from "./devtoolsOverrides.js";
+/** @internal */
 export declare function withDevtoolsLatency(multiplayer: ShellMultiplayer): ShellMultiplayer;
+/** @internal */
 export declare function DevtoolsRendererProbe(): null;
+/** @internal */
 export declare function buildLeanReport(playable: PlayableGame): {
     game: string;
     at: number;
@@ -28,8 +30,8 @@ export declare function buildLeanReport(playable: PlayableGame): {
             pctOfSim: number;
         }[];
     } | null;
-    render: import("@jgengine/core/devtools/devtools").RenderSample | null;
-    latency: import("@jgengine/core/devtools/devtools").LatencyStats | null;
+    render: import("@jgengine/core/devtools/types").RenderSample | null;
+    latency: import("@jgengine/core/devtools/types").LatencyStats | null;
     longFrameSummary: {
         count: number;
         culprits: {
@@ -52,10 +54,10 @@ export declare function buildLeanReport(playable: PlayableGame): {
             ms: number;
         }[];
         probes: Record<string, unknown>;
-        render: import("@jgengine/core/devtools/devtools").RenderSample | null;
+        render: import("@jgengine/core/devtools/types").RenderSample | null;
     }[];
     probes: Record<string, unknown>;
-    logs: import("@jgengine/core/devtools/devtools").DevtoolsLogEntry[] | undefined;
+    logs: import("@jgengine/core/devtools/types").DevtoolsLogEntry[] | undefined;
     controls: {
         name: string;
         value: unknown;
@@ -67,9 +69,11 @@ export declare function buildLeanReport(playable: PlayableGame): {
     }[] | undefined;
     discoveredCount: number;
 };
+/** @internal */
 export declare function buildFullReport(playable: PlayableGame): DevtoolsSnapshot & {
     game: string;
 };
+/** @internal */
 export declare function DevtoolsOverlay({ open, ctx, playable, multiplayer, }: {
     open: boolean;
     ctx: GameContext;