@jgengine/shell 0.25.0 → 0.26.0

package/CHANGELOG.md

@@ -26,6 +26,71 @@ At publish, rename this heading to the new version and mirror the entries into
 `packages/core/src/meta/changelog.ts` (the typed `CHANGELOG` export).
 -->
 
+## 0.26.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.26.0`:** `@jgengine/{core,rapier,react,ws,node,sql,convex,shell,editor,assets,navbake}`. CLI `jgengine` is `0.23.0`; `@jgengine/github` is `0.13.0`.
+
+### Added
+
+- `createLogBus` (`@jgengine/core/devtools/logBus`): a fixed-capacity ring of log lines tagged by owning system, with a separate ring for warnings and errors so a crash line is never pushed out by info traffic. `devtools.logs` now writes through it (`write(level, system, message)`, `snapshot()`, `counts()`, `dropped()`); `DevtoolsLogEntry` gained `system`.
+- `devtools.probes.registerSystem(id, { counters, timers, state })`: a system reports its own counters, named timings and one state line in a few lines, with no shell wiring. Readings surface as `systems` in `devtools.snapshot()`, in `debug_snapshot`, and in every perf record.
+- `PerfReport` (`@jgengine/core/devtools/report`): the one perf record shape shared by `bun run perf` and the in-page report.
+- The shell samples frame telemetry in-page in dev builds: `window.__JG.report()` returns that record, and the page pushes it about once a second to the dev server's `GET/POST /__jgengine/report` route. `bun run debug <game>` prints the record of a game already open and exits non-zero on a budget breach in `scripts/perf-budget.json`.
+- `createNeedSet` (`@jgengine/core/gameplay`) drains named needs on game time and reads them by index — decaying hunger, energy, fun with snapshot/restore and per-need rate retuning.
+- `createUtilityBrain` (`@jgengine/core/world`) picks an action from decaying-need appeal: linear, quadratic, logistic, exponential and threshold response curves, candidate cost (travel, queues, price), a switch margin plus minimum hold (hysteresis), declared interrupts, optional seeded jitter, and a devtools probe string.
+- `createNavRuntime` (`@jgengine/core/world`) consumes an editor-baked nav mesh: reads the `nav` bake off a scene document (`navMeshFromBake`), routes with the mesh query, resolves authored doors, ladders and jumps (`AuthoredNavLink`, priced by kind) onto the current surface, and swaps in a new bake after an edit while matching polygon identity by geometry — `applyMesh` returns a `remap` so only routes over changed polygons need re-planning.
+- `createNavCrowd` (`@jgengine/core/world`) moves many agents across that mesh: plans a corridor, follows the funnel-smoothed waypoints, keeps agents apart with reciprocal velocity obstacle avoidance, bounds path searches per tick by count and milliseconds, fans converging agents out with `spread`, and round-trips through `snapshot`/`restore`.
+- `createRvoCrowd` (`@jgengine/core/world`) is the avoidance solver on its own: RVO/ORCA half-plane solve over a uniform-grid neighbour search capped at `maxNeighbors`, deterministic tie-breaking, overlap relief, retunable `timeHorizon`/`neighborDist`/`maxNeighbors`/`sideBias`/`overlapRelief`, and `snapshot`/`restore` for saves and replays.
+- `resolveRoutine` (`@jgengine/core/gameplay`) resolves an authored day into real arrival and departure times against the world clock. Travel time is injected per stop or as a callback, so a stop departs early enough to walk to the next one and an arrival that runs late slips instead of teleporting; `phaseAt(time)` returns the held place, the walking leg and its progress, and `nextChangeAfter(time)` drives a scheduler. A day whose walks cannot fit its cycle throws at construction.
+- `createOffScreenWorld` (`@jgengine/core/gameplay`) keeps a whole population without simulating it: residents beyond the injected radius are cheap state (position, routine phase, needs) that only moves when the clock crosses a routine boundary, and they spawn into the game's own near simulation through a `NearAgents` interface when they come close. The radius, an optional per-agent cost model, a near budget and a per-tick switch budget are all injected; `snapshot`/`restore` round-trip the whole population, and crossing the boundary preserves identity, schedule progress, need values and position.
+- `createNearAgents` (`@jgengine/core/gameplay`) is the default near half of that seam: a nav crowd with a need set and utility brain per agent, goal-tracking as routines move residents between places, and a decision counter for tests and probes.
+- `createPerception` shares squad knowledge: `squadMates(observerId)` names an observer's roster, and a sighting one member makes is written into every mate's memory with `sourceId` (who saw it) and `sourceTick` (the observe pass it was recorded on). A mate's own sighting at the same instant replaces the hand-off. `maxSharesPerTick` (default 64, per observer pass) bounds a large roster and reports elided shares.
+- Perception memory is auditable without guessing: `memoryOf(observerId, targetId)` returns the one remembered target with its confidence right now or `null` once it has faded, and `stats()` counts pair checks, range prunes, cone tests, line-of-sight calls, sightings, heard stimuli, shares and dropped shares. The check order is range → cone → line of sight, so occlusion work only sees the pruned set. `resetStats()` opens a measurement window; `memories` are pruned per observer so a 200-observer pass does not rescan every memory.
+- `devtoolsName` registers a probe showing observers, remembered targets and the work counters, and `dispose()` removes it.
+- `createCoverField` and `coverPointsFromSolids` (`@jgengine/core/combat`) derive stand-able cover from authored solid boxes instead of a coordinate list: one row of points per vertical face, clear of the corners, filtered by an injected `walkable` test, rebuilt when the world is edited, and queried through a bounded `near(position, radius, limit)`. `CoverSource` is the seam, so a game with its own spatial index can supply cover without the box generator.
+- `selectCover` / `scoreCoverPoint` choose cover by threat: `hidden` is the confidence-weighted share of remembered threats whose line of sight the point (and a body-sized footprint at it) blocks, scored against the role's preferred fighting range, flank angle around the threat, distance, a squadmate's claim on the point, and whether the walk to it is a detour. Fading memories stop steering at `minConfidence`, and a point that hides from only one of two shooters is not cover.
+- `createSquadCombat` (`@jgengine/core/combat`) drives a squad over existing seams: role-driven cover selection, fire discipline (hold, lean out, shoot), suppression from `underFire()`, retreat below a role's health threshold, and relocation under sustained fire. Threat comes only from `threatsFromMemory`, i.e. the perception memory the game already keeps; movement goes through `NavCrowd` with a tighter arrival tolerance so a body actually reaches the stand point. Serializable through `snapshot()`/`restore()` (member decisions, crowd, tuning), retunable, and a `devtoolsName` probe reports pins, peeks, shots and the worst exposure.
+- `assignSquadRoles` and `threatsFromMemory` (`@jgengine/core/combat`): deterministic role assignment over a caller-authored `SquadComposition` (role ids, counts, ranges, flank angles, retreat thresholds and cover weights are all content), and a bounded, confidence-ranked threat list from one observer's memory.
+- A 2v4 arena soak proves the behavior: 90 simulated seconds, 2700 ticks, 4 squad members against 2 scripted raiders, worst exposure 2.33 s (bar 3 s), 0 of 38 exposure spells over 3 s, per-tick cost p50 0.05 ms / p95 0.19 ms.
+- `createDamageRuntime` (`@jgengine/core/combat`) composes a damage table, hit zones, the armor curve and carried statuses into one stateful model: `hit()` returns every stage of the number (`base × zone multiplier × type multiplier × (1 − armor mitigation)`), `tick()` runs status effects through the same table and armor, `timeToKill()` quotes a fight, and `table()` reads the whole chart. `snapshot()`/`restore()` carry registered targets and carried statuses; `retune()` swaps table, zones or status definitions without dropping either; a `devtoolsName` probe reports hits, crits, ticks and the last hit.
+- A damage table (`combat/damageTable`) of damage type × resistance class, with `armor / (armor + halfValue)` mitigation — armor equal to the half value halves the hit — a per-type `bypassArmor`, and `readDamageTable` / `formatDamageTable` to read every row at given armor values. An unknown damage type throws instead of silently dealing 1×.
+- Hit zones and crits (`combat/hitZones`): a zone carries a normal multiplier and an optional crit multiplier, `resolveHitZone` rolls once and returns one multiplier, and a crit replaces the zone multiplier rather than compounding with it. `hitZoneMultiplier` quotes the same number without a roll.
+- `createStatusRuntime` (`combat/statusRuntime`): data-defined statuses with the existing `StatusStackPolicy` (`refresh`, stack to `max`, `replace`, `ignore`) as the only thing that changes stacks, per-tick effects of `{ kind: "damage", channel }` or `{ kind: "stat", stat }`, damage routed through an injected `applyDamage` so resistances and armor still apply, bounded ticks per call, and plain-data state out and back.
+- Numbers from the tests: 25 base kinetic against a 150 HP target, 0.15 s between shots — 8 shots / 1.05 s unarmored, 20 shots / 2.85 s at 60 armor, 36 shots / 5.25 s at 200 armor; two stacked burns of 4 per tick deal 8, not 16; a 1.5× head zone with a 2.5× crit multiplier deals 2.5×, not 3.75×.
+- `createWeaponSystem` (`@jgengine/core/combat`) runs one `WeaponDefinition`: single, automatic or burst fire, hitscan or ballistic projectiles, recoil that moves the aim the shot flies down, spread bloom, interrupted/resumed reloads, a readable ammo economy (`ammo()`, `stats()`), `snapshot()`/`restore()` and a devtools probe. Every hit, hitscan or projectile, resolves through `createDamageRuntime`. Pellet work is bounded per tick (`maxShotsPerTick`, default 4) and per weapon (`maxInFlight`, default 32).
+- `WeaponDefinition` (`@jgengine/core/combat/weaponDefinition`) as plain JSON — rate, fire mode, delivery, magazine, handling, damage, falloff — with `assertWeaponDefinition`, `weaponIntervalMs`, `weaponDamageAt` and `weaponMaxInFlight`. A generated gun is the same shape.
+- `Magazine.pauseReload()` / `resumeReload()` / `isPaused()` suspend a reload and keep its progress; a paused reload is not `isReloading()`, does not advance in `tick`, and round-trips through `snapshot()`/`restore()`.
+- `environment.grading` on the scene document authors a per-game colour grade: shadow/midtone/highlight swatches plus tint, saturation and contrast bake into a small display-space LUT (`lutCubeFromGrading`, `colorGradeFromDocument` in `@jgengine/core/editor/environment`), edited in the Lighting workspace. The shell applies it from `editorLayers`, and a graded game needs no LUT asset or hardcoded pass.
+- Clamped auto-exposure: `postProcessing.autoExposure: { min, max, adaptationSeconds } | false` meters the pre-tone-map frame every four frames toward 18% grey and stays inside the authored range. `WHITE_POINT` and `MID_GREY` in `@jgengine/core/render/colorPipeline` are the single documented calibration the pipeline uses.
+- `GradeConfig.lut` also accepts a baked `{ cube: { size, data } }` LUT, sampled trilinearly after the numeric grade.
+- `MATERIAL_LIBRARY` (`@jgengine/assets/catalogs/materialLibrary`) names 56 PBR surfaces — wet asphalt, painted metal, stucco, brick, wood, foliage with cut-out coverage and sheen, glass, water, sand, concrete and more — each mapping a name to an ambientCG source, a world tile size in metres and a physical response. `libraryMaterialAsset("asphalt/wet")` returns the editable `MaterialAsset` those names resolve to, and `filterLibraryMaterials` backs pickers. `assets pull library` pulls every pinned map set.
+- `TriplanarAssetMaterial` / `useTriplanarAssetMaterial` / `applyTriplanarProjection` (`@jgengine/shell/render/triplanarMaterial`) render a material asset from world position, so world geometry without a `uv` attribute still gets colour, normal, roughness and AO maps. Tile size is world metres; instanced meshes project in instanced space.
+- The editor's Materials workspace browses the library by name and writes the chosen entry into the document's material assets.
+
+### Changed
+
+- `createPerception` (`@jgengine/core/world`, also `@jgengine/core/sensor/perception`) takes `isSegmentClear` instead of `occluded`: the game supplies collision as a "nothing blocks this segment" test, and it is only called for pairs already inside range and cone. **Migration:** flip the predicate — a `occluded: (from, to) => blocked(from, to)` becomes `isSegmentClear: (from, to) => !blocked(from, to)`.
+- `MagazineSnapshot` gains an optional `paused: true` field, present only while a reload is suspended, so existing snapshots and idle shapes are unchanged.
+- AgX is the pipeline's tone map: `postProcessing.toneMapping` defaults to `"agx"`, and the `cinematic`, `photoreal`, `comic`, `retro` and `STUDIO_STAGE_POST` configs now pick it too. `"toon"` keeps `"linear"` on purpose. Games that authored `"aces"` explicitly are unchanged.
+- The grade pass samples LUT tiles at texel centres and blends the blue axis by hand, so a supplied strip LUT no longer bleeds across slices.
+
+### Fixed
+
+- `bun run debug <game>` now finds the server `bun dev` started. The website dev server publishes the same checkout marker the runner does (`scripts/devServerMarker.ts`, written at listen, removed on shutdown, dev builds only), and the marker records the host that answers, since Vite's default `localhost` can be IPv6-only where `127.0.0.1` hangs.
+- The website dev server serves `GET/POST /__jgengine/report` too, so a game opened at `/games/<id>` reports from the `/play` runner it embeds.
+- The in-page sampler installs when the dev report route answers, not on a build-time `PROD` check: the `/play` runner is a production build, so the old check silently disabled the report on `bun dev`.
+- A report taken inside the sampler's warmup is no longer judged on link/framebuffer counts, which only mean something after the warmup baseline exists.
+- `extractMaterialMaps` and `buildMaterialCatalog` now recognise ambientCG's `_Opacity` map, so cut-out foliage and decal scans keep their coverage instead of rendering as solid cards.
+- Capture runs no longer leak a ~150 MB temp Chrome profile each. `shoot`, `drive` and `perf` delete their profile on every exit path — success, throw, watchdog and SIGINT — `bun run shoot` reclaims profiles a killed run left untouched for three hours, the capture guard sweeps the profile of a run it force-kills, and the generated `browser.mjs` harness for game repos removes its own. A capture also refuses to start when the temp drive has less free space than it needs.
+- The post-processing chain, graphics settings and textured terrain material keep a stable identity across renders. Before, every render rebuilt the effect composer and recompiled shaders, which dropped games to single-digit FPS.
+
+### Numbers
+
+- Test fixture at 600 rpm, 30-round magazine: 2.9 s to empty; 17.0° pitch and 3.1° yaw climb over the magazine; back to half climb in 0.37 s and within 5% in 0.6 s; bloom 2.0 → 8.0 → 12.0 mrad (cap) by the tenth shot, settling to base 0.63 s after the last shot.
+- A hitscan and a projectile contact at the same distance return the same damage (20 body, 30 on a 1.5x head zone) through one damage model; a 60 m/s projectile crosses 20 m in 0.33 s and drops 2.45 m in 0.5 s at 9.81 m/s².
+
 ## 0.25.0
 
 ### Migrate

package/dist/Shell3dPresentation.js

@@ -9,9 +9,8 @@ import { CAMERA_FRUSTUM_DEFAULTS } from "@jgengine/core/game/playableGame";
 import { pixelPerfectFrustum, snapPixelPerfectPosition } from "@jgengine/core/game/pixelPerfect";
 import { BUILT_IN_SETTING_CATEGORIES, } from "@jgengine/core/settings/settingsModel";
 import { playControlsActive } from "@jgengine/core/game/controlGate";
-import { sky as resolveSkyDescriptor } from "@jgengine/core/world/features";
-import { resolveGameLook } from "@jgengine/core/render/lookPreset";
 import { balanceLightingForIbl } from "@jgengine/core/render/lightingBalance";
+import { skyNoonKeyframes } from "@jgengine/core/render/skyOwnedLighting";
 import { GameViewportProvider } from "@jgengine/react/gameViewport";
 import { GameProvider } from "@jgengine/react/provider";
 import { SettingsProvider } from "@jgengine/react/settings";
@@ -24,11 +23,14 @@ import { PostProcessing } from "./postfx/PostProcessing.js";
 import { EnvironmentLighting } from "./render/EnvironmentLighting.js";
 import { CollisionDebugWorld } from "./devtools/CollisionDebugWorld.js";
 import { DevtoolsRendererProbe } from "./devtools/DevtoolsOverlay.js";
+import { FrameTelemetry } from "./devtools/FrameTelemetry.js";
 import { CAMERA_TRANSPARENT_USERDATA, GameCameraRig, PlayerFovProvider, PlayerFovSlider, resolveRigKind, rtsPanKeysConflict, } from "./camera/index.js";
 import { CullingProvider } from "./visibility/CullingProvider.js";
 import { BuildingRenderBudget } from "./structures/BuildingRenderBudget.js";
 import { SkyDaylight, TimeOfDayDaylight } from "./environment.js";
+import { AuthoredDaylight } from "./environment/AuthoredDaylight.js";
 import { bearingFromDirection } from "./environment/daylightCycle.js";
+import { colorGradeFromDocument, lightProbesFromDocument } from "@jgengine/core/editor/environment";
 import { resolveSkyLightOwnership, skyEmitsLights } from "./environment/skyLightingPolicy.js";
 import { EnvironmentScene } from "./environment/EnvironmentScene.js";
 import { PointerProbe } from "./pointer/PointerProbe.js";
@@ -47,6 +49,8 @@ import { TextureFiltering } from "./render/TextureFiltering.js";
 import { FrameRateLimiter } from "./drivers/FrameRateLimiter.js";
 import { FpsCounter, FpsProbe } from "./diagnostics/FpsCounter.js";
 import { ConfiguredLighting, BackdropFog } from "./render/SceneLighting.js";
+import { IrradianceVolumeLighting } from "./render/IrradianceVolumeLighting.js";
+import { usePresentationLook } from "./render/presentationLook.js";
 import { WorldView, RemotePlayers } from "./world/WorldScene.js";
 import { FrameDriver } from "./drivers/FrameDriver.js";
 import { GamepadSource } from "./input/gamepadSource.js";
@@ -115,24 +119,38 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                 : world?.kind === "biomes" || world?.kind === "voxel" || world?.kind === "plots" || world?.kind === "tilemap"
                     ? () => _jsx(GridWorldScene, { feature: world })
                     : undefined);
-    const resolvedLook = resolveGameLook({
+    // The post chain and sky rebuild on identity change; a fresh look object per render recompiled every pass each frame.
+    const hasWorldSky = worldSky !== undefined;
+    const authoredGrade = useMemo(() => (playable.editorLayers === undefined ? undefined : colorGradeFromDocument(playable.editorLayers)), [playable.editorLayers]);
+    const { look: resolvedLook, backdropSky } = usePresentationLook({
         look: playable.look,
         lighting: playable.lighting,
         backdrop: playable.backdrop,
         postProcessing: playable.postProcessing,
-        hasWorldSky: worldSky !== undefined,
-    });
+        hasWorldSky,
+    }, authoredGrade);
     const cinematicLook = (playable.look ?? "cinematic") !== "flat";
     const backdrop = resolvedLook.backdrop;
-    const backdropSky = backdrop?.sky !== undefined ? resolveSkyDescriptor(backdrop.sky) : undefined;
     const authoredSky = backdropSky ?? worldSky;
     const lighting = resolvedLook.lighting;
     const sunFromLighting = lighting?.directional?.[0]?.position;
     const sceneLighting = useMemo(() => (cinematicLook ? balanceLightingForIbl(lighting) : lighting), [cinematicLook, lighting]);
-    const effectiveSky = useMemo(() => authoredSky === undefined || authoredSky.sun !== undefined || authoredSky.timeOfDay || sunFromLighting === undefined
-        ? authoredSky
-        : { ...authoredSky, sun: bearingFromDirection(sunFromLighting) }, [authoredSky, sunFromLighting]);
+    const effectiveSky = useMemo(() => {
+        if (authoredSky === undefined)
+            return undefined;
+        const bearing = authoredSky.sun ??
+            (!authoredSky.timeOfDay && sunFromLighting !== undefined ? bearingFromDirection(sunFromLighting) : undefined);
+        const sky = bearing === undefined ? authoredSky : { ...authoredSky, sun: bearing };
+        return authoredSky.timeOfDay ? skyNoonKeyframes(sky, sceneLighting, backdrop?.fog?.color) : sky;
+    }, [authoredSky, sunFromLighting, sceneLighting, backdrop?.fog?.color]);
+    /**
+     * Under a day cycle the sky scales the game's authored sun and ambient fill; without this a
+     * time-of-day sky only repaints the dome and the world stays lit like noon after dark.
+     */
+    const authoredDaylight = effectiveSky?.timeOfDay === true && sceneLighting?.directional !== undefined;
+    const daylightModulation = useMemo(() => ({ sunFactor: 1, sunColor: effectiveSky?.sunColor ?? "#fff1c9", ambientFactor: 1 }), [effectiveSky?.sunColor]);
     const backgroundColor = backdrop?.background ?? (effectiveSky === undefined ? DEFAULT_BACKGROUND_COLOR : undefined);
+    const irradianceVolumes = useMemo(() => (playable.editorLayers === undefined ? [] : lightProbesFromDocument(playable.editorLayers)), [playable.editorLayers]);
     const orthographic = playable.camera?.projection === "orthographic";
     const pointerDownRef = useRef(null);
     const marqueeStartRef = useRef(null);
@@ -378,7 +396,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                             fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
                                             far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }, shadows: graphics.shadows ? "percentage" : false, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true, powerPreference: "high-performance" }, style: { touchAction: "none" }, children: [_jsx(TextureFiltering, { anisotropy: graphics.profile.anisotropy }), graphics.frameRateLimit > 0 && !poster ? _jsx(FrameRateLimiter, { fps: graphics.frameRateLimit }) : null, graphics.showFps ? _jsx(FpsProbe, { tally: frameTally }) : null, orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: sceneLighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: sceneLighting?.hemisphere?.groundColor ?? "#3d4a38", horizonTint: sceneLighting?.ambient?.color, sunDirection: sceneLighting?.directional?.[0]?.position, sunColor: sceneLighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, sceneLighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: sceneLighting, profile: graphics.profile })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: cinematicLook ? 0.3 : 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsx(GameProvider, { context: ctx, children: _jsx(TerrainQualityContext.Provider, { value: graphics.quality, children: _jsxs(BuildingRenderBudget, { drawDistance: graphics.profile.drawDistance, visibility: playable.visibility, cullingDisabled: splitScreen, children: [_jsxs(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson, editorLayers: playable.editorLayers }), bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxSamples === undefined ? {} : { maxSamples: bars.maxSamples }), ...(bars.tickMs === undefined ? {} : { tickMs: bars.tickMs }), ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxSamples === undefined ? {} : { maxSamples: nameplates.maxSamples }), ...(nameplates.tickMs === undefined ? {} : { tickMs: nameplates.tickMs }), ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), occlude: nameplates.occlude, ...(nameplates.resolveName === undefined ? {} : { resolveName: nameplates.resolveName }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null] }), _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap, diagnostics: devtoolsEnabled }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine, anchor: playable.camera?.rig === "rts" || playable.camera?.rig === "topDown" ? "ground" : "camera" }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
+                                        }, shadows: graphics.shadows ? "percentage" : false, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true, powerPreference: "high-performance" }, style: { touchAction: "none" }, children: [_jsx(TextureFiltering, { anisotropy: graphics.profile.anisotropy }), graphics.frameRateLimit > 0 && !poster ? _jsx(FrameRateLimiter, { fps: graphics.frameRateLimit }) : null, graphics.showFps ? _jsx(FpsProbe, { tally: frameTally }) : null, orthographic && playable.camera?.pixelPerfect !== undefined ? (_jsx(PixelPerfectCamera, { ...playable.camera.pixelPerfect })) : null, backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { source: playable.environmentSource, skyColor: sceneLighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: sceneLighting?.hemisphere?.groundColor ?? "#3d4a38", horizonTint: sceneLighting?.ambient?.color, sunDirection: sceneLighting?.directional?.[0]?.position, sunColor: sceneLighting?.directional?.[0]?.color ?? "#fff2d6", ...(authoredDaylight ? { daylight: daylightModulation } : {}) })) : null, sceneLighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: sceneLighting, profile: graphics.profile, ...(authoredDaylight ? { modulation: daylightModulation } : {}) })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: cinematicLook ? 0.3 : 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, authoredDaylight && effectiveSky !== undefined ? (_jsx(AuthoredDaylight, { sky: effectiveSky, clock: ctx.time, modulation: daylightModulation })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)), fogRange: backdrop?.fog })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)), fogRange: backdrop?.fog }))) : null, irradianceVolumes.length > 0 ? _jsx(IrradianceVolumeLighting, { volumes: irradianceVolumes }) : null, effectiveSky === undefined ? _jsx(BackdropFog, { fog: backdrop?.fog }) : null, _jsx(GameProvider, { context: ctx, children: _jsx(TerrainQualityContext.Provider, { value: graphics.quality, children: _jsxs(BuildingRenderBudget, { drawDistance: graphics.profile.drawDistance, visibility: playable.visibility, cullingDisabled: splitScreen, children: [_jsxs(CullingProvider, { config: playable.visibility, drawDistance: graphics.profile.drawDistance, children: [_jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson, editorLayers: playable.editorLayers }), bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxSamples === undefined ? {} : { maxSamples: bars.maxSamples }), ...(bars.tickMs === undefined ? {} : { tickMs: bars.tickMs }), ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxSamples === undefined ? {} : { maxSamples: nameplates.maxSamples }), ...(nameplates.tickMs === undefined ? {} : { tickMs: nameplates.tickMs }), ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), occlude: nameplates.occlude, ...(nameplates.resolveName === undefined ? {} : { resolveName: nameplates.resolveName }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null] }), _jsx(WorldItems, { config: playable.worldItem }), _jsx(WorldParticles, { quality: graphics.quality, particleCap: graphics.profile.particleCap, diagnostics: devtoolsEnabled }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine, anchor: playable.camera?.rig === "rts" || playable.camera?.rig === "topDown" ? "ground" : "camera" }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
                                                                 cameraDraggingRef.current = dragging;
                                                             } }), _jsx(PointerProbe, { service: pointerService })] }) }) }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled, authoritativeFrameRef: authoritativeFrameRef }), _jsx(GamepadSource, { tracker: tracker, bindings: inputBindings ?? {}, analogRef: analogRef, input: ctx.input, feel: playable.gamepad, seats: localPlayers(ctx), onSeatJoin: (slot) => {
                                                 try {
@@ -387,7 +405,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                                 catch (error) {
                                                     reportRuntimeError(error, "tick");
                                                 }
-                                            }, seatsActive: () => !gateRef.current && playControlsActive(ctx) }), _jsx(DevtoolsRendererProbe, {}), splitScreen ? (_jsx(SplitScreenRenderer, { ctx: ctx, viewports: seatViewports, config: playable.viewports, mainCamera: playable.camera })) : null, !splitScreen && resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality, stages: graphics.profile.postStages })) : null] }), graphics.showFps && !poster ? _jsx(FpsCounter, { tally: frameTally }) : null, !poster &&
+                                            }, seatsActive: () => !gateRef.current && playControlsActive(ctx) }), _jsx(DevtoolsRendererProbe, {}), devtoolsEnabled ? (_jsx(FrameTelemetry, { game: playable.game.name, quality: graphics.quality === "low" ? "draft" : "full" })) : null, splitScreen ? (_jsx(SplitScreenRenderer, { ctx: ctx, viewports: seatViewports, config: playable.viewports, mainCamera: playable.camera })) : null, !splitScreen && resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality, stages: graphics.profile.postStages })) : null] }), graphics.showFps && !poster ? _jsx(FpsCounter, { tally: frameTally }) : null, !poster &&
                                     !orientationGate &&
                                     coarsePointer &&
                                     controlsActive &&

package/dist/devtools/FrameTelemetry.d.ts

@@ -0,0 +1,12 @@
+import type { PerfQuality } from "@jgengine/core/devtools/devtools";
+/**
+ * Mounts the in-page frame sampler for the live 3D scene: it wraps this renderer's
+ * context for GPU-object counts, reads renderer and scene numbers on demand, and
+ * publishes `window.__JG.report()`. It installs only when the dev server answers its
+ * report route, so a shipped game pays for one probe request and nothing else.
+ * @internal
+ */
+export declare function FrameTelemetry({ game, quality }: {
+    game: string;
+    quality: PerfQuality;
+}): null;

package/dist/devtools/FrameTelemetry.js

@@ -0,0 +1,68 @@
+import { useEffect } from "react";
+import { useThree } from "@react-three/fiber";
+import { readUrlParam } from "@jgengine/core/devtools/urlFlags";
+import { attachGlCounters, installFrameTelemetry, probeReportRoute, reportGameId, TELEMETRY_FLAG, } from "./frameSampler.js";
+/**
+ * Mounts the in-page frame sampler for the live 3D scene: it wraps this renderer's
+ * context for GPU-object counts, reads renderer and scene numbers on demand, and
+ * publishes `window.__JG.report()`. It installs only when the dev server answers its
+ * report route, so a shipped game pays for one probe request and nothing else.
+ * @internal
+ */
+export function FrameTelemetry({ game, quality }) {
+    const gl = useThree((state) => state.gl);
+    const scene = useThree((state) => state.scene);
+    useEffect(() => {
+        if ((readUrlParam(TELEMETRY_FLAG) ?? "").toLowerCase() === "off")
+            return;
+        let active = true;
+        let telemetry = null;
+        void probeReportRoute(undefined, reportGameId(game)).then((available) => {
+            if (!active || !available)
+                return;
+            let counters = {
+                totals: { programsLinked: 0, framebuffers: 0, buffers: 0, textures: 0, vertexArrays: 0 },
+                attached: false,
+            };
+            try {
+                counters = attachGlCounters(gl.getContext());
+            }
+            catch {
+                counters.attached = false;
+            }
+            telemetry = installFrameTelemetry({
+                game,
+                quality: () => quality,
+                viewport: () => `${window.innerWidth}x${window.innerHeight}`,
+                gpu: () => readGpuLabel(gl.getContext()),
+                render: () => ({
+                    drawCalls: gl.info.render.calls,
+                    triangles: gl.info.render.triangles,
+                    geometries: gl.info.memory.geometries,
+                    textures: gl.info.memory.textures,
+                }),
+                scene: () => scene,
+                gl: () => counters,
+                residentPrograms: () => gl.info.programs?.length ?? null,
+            });
+        });
+        return () => {
+            active = false;
+            telemetry?.dispose();
+        };
+    }, [game, quality, gl, scene]);
+    return null;
+}
+function readGpuLabel(context) {
+    const info = context.getExtension("WEBGL_debug_renderer_info");
+    try {
+        if (info === null)
+            return String(context.getParameter(0x1f01));
+        const vendor = String(context.getParameter(info.UNMASKED_VENDOR_WEBGL));
+        const renderer = String(context.getParameter(info.UNMASKED_RENDERER_WEBGL));
+        return vendor.length > 0 ? `${vendor} ${renderer}` : renderer;
+    }
+    catch {
+        return "unknown";
+    }
+}

package/dist/devtools/agentBridge.js

@@ -3,6 +3,7 @@ import { getSaveEndpoint } from "@jgengine/core/devtools/saveEndpoint";
 import { isHudAnchor, listActiveHudLayouts, } from "@jgengine/core/ui/hudLayout";
 import { listHudPanelTypes, resolvePanelResize, resizePanelSize, } from "@jgengine/core/ui/hudDocument";
 import { buildFullReport, buildLeanReport, summarizeLeanReport } from "./devtoolsReports.js";
+import { resetFrameTelemetry } from "./frameSampler.js";
 import { advanceSimulation } from "./simStepper.js";
 /**
  * @internal
@@ -213,6 +214,7 @@ export function installAgentBridge(options) {
                 return { ok: true, report: buildFullReport(playable) };
             case "debug_perf_reset":
                 devtools.frame.reset();
+                resetFrameTelemetry();
                 return { ok: true };
             case "canvas_state":
                 return { ok: true, layouts: canvasPanels() };

package/dist/devtools/devtoolsReports.d.ts

@@ -50,6 +50,8 @@ export declare function buildLeanReport(playable: PlayableGame): {
         render: import("@jgengine/core/devtools/types").RenderSample | null;
     }[];
     probes: Record<string, unknown>;
+    systems: Record<string, import("@jgengine/core/devtools/types").SystemProbeReading>;
+    logSummary: import("@jgengine/core/devtools/report").ReportLogs;
     logs: import("@jgengine/core/devtools/types").DevtoolsLogEntry[] | undefined;
     controls: {
         name: string;

package/dist/devtools/devtoolsReports.js

@@ -1,4 +1,5 @@
 import { devtools } from "@jgengine/core/devtools/devtools";
+import { toReportLogs } from "@jgengine/core/devtools/report";
 import { diagnose } from "./perfDiagnose.js";
 function roundMs(value, digits = 1) {
     const scale = 10 ** digits;
@@ -88,6 +89,8 @@ export function buildLeanReport(playable) {
         longFrameSummary: summarizeLongFrames(longs),
         longFrames: longs.slice(-6).map(compactLongFrame),
         probes: snap.probes,
+        systems: snap.systems,
+        logSummary: toReportLogs(devtools.logs.snapshot()),
         logs: hotLogs.length > 0 ? hotLogs : undefined,
         controls: changedControls.length > 0 ? changedControls : undefined,
         discovered: enabledDiscovered.length > 0 ? enabledDiscovered : undefined,

package/dist/devtools/frameSampler.d.ts

@@ -0,0 +1,127 @@
+import { type PerfQuality, type PerfReport, type ReportLogs } from "@jgengine/core/devtools/report";
+import type { FrameStats, RenderSample, SystemProbeReading } from "@jgengine/core/devtools/types";
+/**
+ * In-page frame telemetry: the game reports on itself instead of needing a second
+ * process to attach a profiler. Frame timings come from the devtools frame ring,
+ * renderer counts from the live renderer, GPU-object creation from wrapped GL calls,
+ * and per-system numbers from `devtools.probes` — all read on demand, so nothing
+ * here runs on the hot path.
+ */
+/** Query flag that turns the sampler off for an A/B frame-time comparison. */
+export declare const TELEMETRY_FLAG = "telemetry";
+/** How long after the sampler starts the GL counters get their post-warmup baseline. */
+export declare const TELEMETRY_WARMUP_MS = 5000;
+/** Cadence of the push to the dev server, in milliseconds. */
+export declare const REPORT_PUSH_MS = 1000;
+/** GPU-object creation counts, the fields the budget gate compares. */
+export interface GlCounterTotals {
+    programsLinked: number;
+    framebuffers: number;
+    buffers: number;
+    textures: number;
+    vertexArrays: number;
+}
+/**
+ * Wrap the live context's creation calls so a leak shows up as a non-zero counter.
+ * Only object creation is wrapped — never a draw call — so a steady-state frame
+ * pays nothing. Returns whether any call was actually wrapped, since a zero is only
+ * evidence when it was.
+ * @internal
+ */
+export declare function attachGlCounters(context: object): {
+    totals: GlCounterTotals;
+    attached: boolean;
+};
+/**
+ * Count live three.js nodes from the scene the game is drawing; `null` when it cannot be walked.
+ * @internal
+ */
+export declare function countSceneNodes(scene: unknown): {
+    nodes: number | null;
+    scenes: number;
+};
+/** Everything the report needs, gathered by whichever producer is asking. */
+export interface FrameReportInputs {
+    game: string;
+    gpu: string;
+    quality: PerfQuality;
+    viewport: string;
+    at: number;
+    /** Frame stats from the devtools ring; `null` before the first frame. */
+    frame: FrameStats | null;
+    render: RenderSample | null;
+    scene: {
+        nodes: number | null;
+        scenes: number;
+    };
+    gl: {
+        totals: GlCounterTotals;
+        since: GlCounterTotals;
+        residentPrograms: number | null;
+        attached: boolean;
+    };
+    systems: Record<string, SystemProbeReading>;
+    logs: ReportLogs | null;
+    heapBytes: number | null;
+    ageMs: number;
+    warmedUp: boolean;
+    buildMs: number;
+}
+/**
+ * Assemble the shared report shape from live sources. Pure: every number arrives as
+ * an argument, so a test can assert the shape without a renderer or a browser.
+ * @internal
+ */
+export declare function buildFrameReport(inputs: FrameReportInputs): PerfReport;
+/** What the shell hands the sampler: live getters, called only when a report is built. */
+export interface FrameTelemetrySources {
+    game: string;
+    quality: () => PerfQuality;
+    viewport: () => string;
+    gpu: () => string;
+    render: () => RenderSample | null;
+    scene: () => unknown;
+    gl: () => {
+        totals: GlCounterTotals;
+        attached: boolean;
+    };
+    residentPrograms: () => number | null;
+    heapBytes?: () => number | null;
+    endpoint?: string;
+    push?: boolean;
+}
+/** The installed sampler: ask it for a report, reset its window, or tear it down. */
+export interface FrameTelemetry {
+    report(): PerfReport;
+    resetWindow(): void;
+    dispose(): void;
+}
+/**
+ * `Harbor Heat` -> `harbor-heat`, unless the dev runner's `?game=` says otherwise. The
+ * report is keyed by this, so it matches `bun run perf` and the budget file.
+ * @internal
+ */
+export declare function reportGameId(displayName: string): string;
+/**
+ * Ask the dev server whether its report route exists. This is the sampler's only
+ * production guard and it is behaviour, not a build flag: the route is mounted by the
+ * dev Vite configs only, so a shipped game answers this one request and installs
+ * nothing — no timers, no GL wrapping, no `window.__JG`. The website dev server serves
+ * the /play runner as a production build, which is why a build-time `PROD` check would
+ * wrongly disable the report there.
+ * @internal
+ */
+export declare function probeReportRoute(endpoint?: string, game?: string, fetchImpl?: typeof fetch | null, timeoutMs?: number): Promise<boolean>;
+/**
+ * Reset the sampler's warmup baseline, so a fresh measurement starts from zero.
+ * @internal
+ */
+export declare function resetFrameTelemetry(): void;
+/**
+ * Install the sampler for the page: publishes `window.__JG.report()` and pushes the
+ * same record to the dev server's report route every second. Returns `null` when
+ * `?telemetry=off` asks for the comparison run; callers gate installation on
+ * {@link probeReportRoute}, so a shipped game never starts the sampler.
+ * @internal
+ */
+export declare function installFrameTelemetry(sources: FrameTelemetrySources): FrameTelemetry | null;