@jgengine/core 0.24.0 → 0.26.0

package/dist/visibility/visibilitySystem.js

@@ -6,6 +6,10 @@ import { createSpatialIndex } from "./spatialIndex.js";
 import { DEFAULT_CULLING_SETTINGS, mergeCullingSettings, resolveOverrides } from "./settings.js";
 import { noOcclusion } from "./occlusion.js";
 import { createVisibilityStats, resetCullingStats, nowMs } from "./diagnostics.js";
+import { devtools } from "../devtools/devtools.js";
+function round2(value) {
+    return Math.round(value * 100) / 100;
+}
 export function createVisibilitySystem(options) {
     let settings = mergeCullingSettings(DEFAULT_CULLING_SETTINGS, options.settings ?? {});
     const occlusion = options.occlusion ?? noOcclusion;
@@ -25,6 +29,22 @@ export function createVisibilitySystem(options) {
     const preloadFrustum = createFrustum();
     const hysteresisFrustum = createFrustum();
     let updateCounter = 0;
+    const disposeProbe = devtools.probes.registerSystem("render/culling", {
+        counters: () => ({
+            totalObjects: stats.totalObjects,
+            visible: stats.visible,
+            preloaded: stats.preloaded,
+            culled: stats.drawCallsAvoided,
+            rejectedByFrustum: stats.rejectedByFrustum,
+            rejectedByDistance: stats.rejectedByDistance,
+            rejectedByOcclusion: stats.rejectedByOcclusion,
+        }),
+        timers: () => ({
+            spatialQueryMs: round2(stats.spatialQueryMs),
+            cullingMs: round2(stats.cullingMs),
+        }),
+        state: () => `${stats.visible}/${stats.totalObjects} visible · ${stats.drawCallsAvoided} culled · ${round2(stats.cullingMs)}ms`,
+    });
     function specOf(r, resolved) {
         return resolved.bounds ?? r.bounds ?? DEFAULT_BOUNDS;
     }
@@ -245,6 +265,7 @@ export function createVisibilitySystem(options) {
             return { cameras, bounds: boundsOut, partitions: index.cells(), culled, stats };
         },
         clear() {
+            disposeProbe();
             index.clear();
             bounds.clear();
             records.clear();

package/dist/world/features.d.ts

@@ -330,6 +330,14 @@ export interface SkyEnvironmentConfig {
     zenithColor?: string;
     sunIntensity?: number;
     ambientIntensity?: number;
+    /** Authored noon sun colour; the atmosphere reddens it toward the horizon. Default warm white. */
+    sunColor?: string;
+    /** Authored noon fog colour. Dawn, dusk and night cross-fade to their own haze so fog matches the sky. */
+    fogColor?: string;
+    /** Peak moonlight as a fraction of `sunIntensity`. Default the engine's readable night value. */
+    moonIntensity?: number;
+    /** Moonlight colour. Default cool moonlight blue. */
+    moonColor?: string;
     /**
      * Sun placement for the dome glow and the sky-owned sun light. With a fixed `preset` this is the
      * sun's exact direction; under `timeOfDay` it is where the sun stands at noon and the day arc

package/dist/world.d.ts

@@ -1,9 +1,11 @@
 export { type HeatConfig, type HeatGain, type HeatLevelDef, type HeatState } from "./ai/heatSystem.js";
 export { advanceInterestGate, createInterestCensus, createInterestGateState, interestPhase, type InterestCensus, type InterestCensusAccumulator, type InterestGateInput, type InterestGateState, type InterestGateStep, type InterestSchedulerConfig, type InterestState, type InterestTier, } from "./ai/interestScheduler.js";
 export { type Job, type JobDef, type JobReport } from "./ai/jobBoard.js";
+export { createRvoCrowd, type RvoAgentSpec, type RvoAgentView, type RvoCrowd, type RvoCrowdOptions, type RvoSnapshot, type RvoTunables, } from "./ai/rvo.js";
 export { advanceSpawnDirector, advanceWave, createSpawnDirectorState, pickSpawnPoint, raiseAlert, type SpawnDirectorConfig, type SpawnDirectorState, type SpawnEntry, type SpawnRequest, type WaveManifest, } from "./ai/spawnDirector.js";
 export { acquireTarget, createTargetAcquirer, type AcquisitionEnvelope, type AcquisitionPolicy, type AcquisitionResult, type AcquisitionRetention, type TargetAcquirer, } from "./ai/targetAcquisition.js";
 export { createThreatTable, type ThreatTable } from "./ai/threat.js";
+export { createUtilityBrain, sampleResponseCurve, type ResponseCurve, type UtilityBrain, type UtilityBrainConfig, type UtilityBrainSnapshot, type UtilityCandidate, type UtilityDebugSnapshot, type UtilityDecision, type UtilityInterrupt, type UtilityOption, type UtilityScore, type UtilitySwitchReason, type UtilityTerm, type UtilityTunables, } from "./ai/utilityBrain.js";
 export { createWaveRunner, type WaveRunner, type WaveRunnerConfig, type WaveSpawnSink, type WaveView, } from "./ai/waveRunner.js";
 export { createAreaEffectField, type AreaEffectEvent, type AreaEffectField, type AreaEventKind, type AreaFieldState, type AreaLeaveReason, type AreaMembership, type AreaShape, type AreaSourceSpec, type AreaStepInput, } from "./area/areaEffectField.js";
 export { cappedStacks, extremumStack, independentStacks, sumMagnitude, uniqueByStackKey, type AreaStackPolicy, type MagnitudeOf, } from "./area/stackPolicy.js";
@@ -30,9 +32,11 @@ export { resolvePlayerMovementTuning, stepPlayerMovement } from "./movement/play
 export { POSE_HITBOX, createPoseState, type MovementPose } from "./movement/poseState.js";
 export { steerYaw } from "./movement/steering.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
+export { createNavCrowd, type NavCrowd, type NavCrowdAgentSpec, type NavCrowdAgentView, type NavCrowdOptions, type NavCrowdRevalidate, type NavCrowdSnapshot, type NavCrowdStats, } from "./nav/navCrowd.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
 export { createNavGrid, findPath, slopeStepCost, type NavGrid, type NavPoint } from "./nav/navGrid.js";
 export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, type NavMeshAdjacency, type NavMeshData, type NavMeshLink, type NavMeshPath, type NavMeshQuery, type NavMeshQueryOptions, type NavMeshQuerySnapshot, } from "./nav/navMesh.js";
+export { createNavRuntime, navMeshFromBake, type AuthoredNavLink, type NavLinkKind, type NavRebuildStats, type NavRegion, type NavRuntime, type NavRuntimeOptions, type NavRuntimeSnapshot, type SceneBake, } from "./nav/navRuntime.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, type PathFollowConfig, type PathFollowProgress, type PathFollowState, type PathProgress, type Waypoint, } from "./nav/pathFollow.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, type AttackMoveOrderPayload, type EmptyOrderPayload, type EngagementKindConfig, type EngagementOrderState, type MoveOrderPayload, type OrderKindConfig, type OrderMoveResult, type OrderMover, type OrderTargeting, type PatrolOrderPayload, type PatrolOrderState, type TargetedOrderPayload, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, type Order, type OrderCancelReason, type OrderEvent, type OrderIssueResult, type OrderKind, type OrderOutcome, type OrderPhase, type OrderProgress, type OrderQueue, type OrderQueueOptions, type OrderQueuePolicy, type OrderQueueState, type OrderRegistry, type OrderRejection, type OrderRequest, type OrderStartResult, type OrderTickReport, type OrderVec3, } from "./orders/orderQueue.js";
@@ -82,6 +86,7 @@ export { type ConcealmentSensor } from "./sensor/concealment.js";
 export { type FreezeMonitor, type FreezeViolation } from "./sensor/freezeMonitor.js";
 export { type FramingConfig, type FrustumProjection, type FrustumSample, type FrustumSensor, type FrustumTarget, } from "./sensor/frustumSensor.js";
 export { type HiddenStateSource, type SensorProbeOptions, type SensorReading } from "./sensor/hiddenStateProbe.js";
+export { createPerception, type PerceptionCandidate, type PerceptionConfig, type PerceptionMemory, type PerceptionObserver, type PerceptionPosition, type PerceptionService, type PerceptionSnapshot, type PerceptionStats, type PerceptionStimulus, type PerceptionStimulusKind, } from "./sensor/perception.js";
 export { type RecordingBuffer, type RecordingBufferOptions } from "./sensor/recordingBuffer.js";
 export { type RevealHit, type RevealQuery } from "./sensor/revealQuery.js";
 export { createDayNightCycle, type DayNightCycle, type DayNightCycleOptions, type DayNightKeyframe, type DayNightSample, type DayNightSnapshot, } from "./time/dayNightCycle.js";

package/dist/world.js

@@ -1,9 +1,11 @@
 export {} from "./ai/heatSystem.js";
 export { advanceInterestGate, createInterestCensus, createInterestGateState, interestPhase, } from "./ai/interestScheduler.js";
 export {} from "./ai/jobBoard.js";
+export { createRvoCrowd, } from "./ai/rvo.js";
 export { advanceSpawnDirector, advanceWave, createSpawnDirectorState, pickSpawnPoint, raiseAlert, } from "./ai/spawnDirector.js";
 export { acquireTarget, createTargetAcquirer, } from "./ai/targetAcquisition.js";
 export { createThreatTable } from "./ai/threat.js";
+export { createUtilityBrain, sampleResponseCurve, } from "./ai/utilityBrain.js";
 export { createWaveRunner, } from "./ai/waveRunner.js";
 export { createAreaEffectField, } from "./area/areaEffectField.js";
 export { cappedStacks, extremumStack, independentStacks, sumMagnitude, uniqueByStackKey, } from "./area/stackPolicy.js";
@@ -30,9 +32,11 @@ export { resolvePlayerMovementTuning, stepPlayerMovement } from "./movement/play
 export { POSE_HITBOX, createPoseState } from "./movement/poseState.js";
 export { steerYaw } from "./movement/steering.js";
 export { constrainToNavGrid } from "./nav/navConstrain.js";
+export { createNavCrowd, } from "./nav/navCrowd.js";
 export { populateNavGridFromEnvironment } from "./nav/navFromEnvironment.js";
 export { createNavGrid, findPath, slopeStepCost } from "./nav/navGrid.js";
 export { buildNavAdjacency, closestPoint, createNavMeshQuery, raycastNav, } from "./nav/navMesh.js";
+export { createNavRuntime, navMeshFromBake, } from "./nav/navRuntime.js";
 export { advancePathFollow, createPathFollow, pathFollowProgress, pathFollowSeek, pathFromNav, pathLength, } from "./nav/pathFollow.js";
 export { defineAttackMoveOrder, defineHoldOrder, defineMoveOrder, definePatrolOrder, defineStopOrder, defineTargetedOrder, } from "./orders/orderKinds.js";
 export { createOrderQueue, createOrderRegistry, } from "./orders/orderQueue.js";
@@ -82,6 +86,7 @@ export {} from "./sensor/concealment.js";
 export {} from "./sensor/freezeMonitor.js";
 export {} from "./sensor/frustumSensor.js";
 export {} from "./sensor/hiddenStateProbe.js";
+export { createPerception, } from "./sensor/perception.js";
 export {} from "./sensor/recordingBuffer.js";
 export {} from "./sensor/revealQuery.js";
 export { createDayNightCycle, } from "./time/dayNightCycle.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

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.24.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -82,25 +82,42 @@
 - `Devtools` (interface): interface Devtools — Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes.
 - `DevtoolsControl` (interface): interface DevtoolsControl — Registered tunable control with its resolved schema metadata and read/write/reset accessors.
 - `DevtoolsControlKind` (type): type DevtoolsControlKind = | "slider" | "toggle" | "color" | "select" | "text" | "vec2" | "vec3" | "vec4" | "interval" | "angle" | "enum" — ⚠ undocumented
-- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, and formatted message.
+- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, owning system tag, and formatted message.
 - `DevtoolsLogLevel` (type): type DevtoolsLogLevel = "log" | "info" | "warn" | "error" — Severity level for a captured devtools log entry.
+- `DevtoolsLogs` (interface): interface DevtoolsLogs — Bounded log ring with per-system tags, a warning/error ring, and lifetime counts.
 - `DevtoolsOverrides` (interface): interface DevtoolsOverrides { version: number; enabled: string[]; values: Record<string, unknown>; schemas?: Record<string, {kind: DevtoolsControlKind; schemaVersion?: number}> } — ⚠ undocumented
 - `DevtoolsSnapshot` (interface): interface DevtoolsSnapshot — Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields.
 - `DiscoveredEntry` (interface): interface DiscoveredEntry — A control auto-discovered by scanning an object/table, with its binding metadata and current reader.
 - `DiscoverySkip` (interface): interface DiscoverySkip { readonly path: string; readonly reason: string } — ⚠ undocumented
 - `FrameRecordSample` (interface): interface FrameRecordSample — Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations.
 - `FrameStats` (interface): interface FrameStats — Aggregated frame-timing statistics over the recent sampling window, including per-phase breakdown.
-- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget).
+- `FrameWindow` (interface): interface FrameWindow — Frame timings over the measured window, as the player sees them.
+- `GlReport` (interface): interface GlReport — GPU-object creation counts. `total` is since the page loaded, the named fields since warmup.
+- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — The one perf record shape. `bun run perf` (CDP, out of process) and the in-page telemetry report (`window.__JG.report()`, the dev-server route, `bun run debug`) both produce exactly this object, so a budget check and a diff read either one.
 - `LatencyStats` (interface): interface LatencyStats — Aggregated latency statistics (last/avg/min/max) over recorded latency samples.
+- `LogBusCounts` (interface): interface LogBusCounts — Lifetime totals per level, plus how many lines the ring dropped.
+- `LogBusEntry` (interface): interface LogBusEntry — One captured line: when, how bad, which system said it, and what it said.
+- `LogBusSnapshot` (interface): interface LogBusSnapshot — Read-out of the log bus: newest-window entries, the warning/error ring, totals, and evictions.
 - `LongFrameEvent` (interface): interface LongFrameEvent — Recorded spike event for a frame that exceeded the long-frame threshold, with culprit attribution.
 - `NormalizedColor` (interface): interface NormalizedColor { readonly hex: string; readonly rgb: string; readonly alpha: number; readonly hasAlpha: boolean } — ⚠ undocumented
 - `OVERRIDES_FORMAT_VERSION` (const): const OVERRIDES_FORMAT_VERSION: 1 — ⚠ undocumented
 - `OverrideApplyDiagnostic` (interface): interface OverrideApplyDiagnostic { readonly id: string; readonly reason: string } — ⚠ undocumented
 - `OverrideApplyResult` (interface): interface OverrideApplyResult — Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics.
+- `PerfQuality` (type): type PerfQuality = "full" | "draft" — Graphics tier the record was measured at.
+- `PerfReport` (interface): interface PerfReport — One measured window of one game: the record `bun run perf`, `window.__JG.report()` and `bun run debug` print.
 - `PhaseStats` (interface): interface PhaseStats — Timing summary for a single named profiling phase across the sampling window.
+- `ProfileEntry` (interface): interface ProfileEntry — One sampled stack frame reduced to a readable key and its self time.
+- `ProfileReport` (interface): interface ProfileReport — CPU profile summary; only the CDP harness can produce one.
+- `RenderReport` (interface): interface RenderReport — Renderer-side counts for the measured window; `null` where the source could not read them.
 - `RenderSample` (interface): interface RenderSample — Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame.
+- `ReportLogLine` (interface): interface ReportLogLine — One log line as it appears in the report.
+- `ReportLogs` (interface): interface ReportLogs — Bounded log read-out carried by the report: warn/error lines survive even a flood of info logs.
+- `ReportTelemetry` (interface): interface ReportTelemetry — Who produced the report, and how much producing it cost.
 - `ScanFieldMeta` (interface): interface ScanFieldMeta extends TunableOptions { kind?: DevtoolsControlKind } — ⚠ undocumented
 - `ScanMeta` (type): type ScanMeta = Readonly<Record<string, ScanFieldMeta>> — ⚠ undocumented
+- `SceneNodeSource` (type): type SceneNodeSource = "scene-graph" | "heap-object3d" | "unavailable" — Where the scene-node count came from: the live scene graph, a heap walk, or nowhere.
+- `SystemProbe` (interface): interface SystemProbe — What one system reports about itself: totals it keeps anyway, named timings, and one state line.
+- `SystemProbeReading` (interface): interface SystemProbeReading — One system's probe read out on demand; missing sections stay empty rather than absent.
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 - `TunableChoice` (interface): interface TunableChoice<T = unknown> { readonly value: T; readonly label?: string } — ⚠ undocumented
@@ -139,9 +156,20 @@
 ## @jgengine/core/devtools/frame
 
 - `FrameModule` (interface): interface FrameModule — Frame subsystem exposing the frame-timing, profiling, and render-sample facades.
-- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — Frame duration in milliseconds above which a frame is recorded as a long-frame spike (~30fps budget).
 - `createFrameModule` (const): const createFrameModule: (deps: { readProbes: () => Record<string, unknown>; }) => FrameModule — Create the frame subsystem that records frame/sim/phase timings, computes stats, and captures long-frame events.
 
+## @jgengine/core/devtools/logBus
+
+- `LOG_BUS_CAPACITY` (const): const LOG_BUS_CAPACITY: 200 — Default measured window for the log ring; older lines are evicted, never grown.
+- `LOG_BUS_MESSAGE_MAX` (const): const LOG_BUS_MESSAGE_MAX: 400 — Longest kept message; a longer one is cut once, at write time.
+- `LOG_BUS_SEVERE_CAPACITY` (const): const LOG_BUS_SEVERE_CAPACITY: 64 — Warnings and errors also land in their own ring, so an error is never pushed out by info traffic.
+- `LogBus` (interface): interface LogBus — A fixed-capacity ring of log lines tagged by owning system. `write` reuses a preallocated slot — no array growth, no splice, no per-write object — so a hot path can call it and only the message string (already built by the caller) costs an allocation.
+- `LogBusCounts` (interface): interface LogBusCounts — Lifetime totals per level, plus how many lines the ring dropped.
+- `LogBusEntry` (interface): interface LogBusEntry — One captured line: when, how bad, which system said it, and what it said.
+- `LogBusOptions` (interface): interface LogBusOptions — Tunables for the log ring: capacity, the severity ring's capacity, and the clock.
+- `LogBusSnapshot` (interface): interface LogBusSnapshot — Read-out of the log bus: newest-window entries, the warning/error ring, totals, and evictions.
+- `createLogBus` (function): function createLogBus(options: LogBusOptions = {}): LogBus — Create the bounded log bus the devtools log facade writes through.
+
 ## @jgengine/core/devtools/logs
 
 - `LogsModule` (interface): interface LogsModule — Logs subsystem exposing the log-capture and latency-tracking facades.
@@ -153,6 +181,27 @@
 - `OverridesModule` (interface): interface OverridesModule — Overrides subsystem exposing the export/apply facade for persisting and restoring control values.
 - `createOverridesModule` (const): const createOverridesModule: (deps: { signal: ChangeSignal; controlRecords: Map<string, ControlRecord>; writeControl: (record: ControlRecord, raw: unknown) => boolean; discoveredRecords: Map<string, DiscoveredRecord>; enableDiscovered: (id: string) => void; }) => OverridesModule — Create the overrides subsystem that serializes changed control values and re-applies a saved overrides payload.
 
+## @jgengine/core/devtools/report
+
+- `FrameWindow` (interface): interface FrameWindow — Frame timings over the measured window, as the player sees them.
+- `GlReport` (interface): interface GlReport — GPU-object creation counts. `total` is since the page loaded, the named fields since warmup.
+- `LONG_FRAME_MS` (const): const LONG_FRAME_MS: 33.4 — The one perf record shape. `bun run perf` (CDP, out of process) and the in-page telemetry report (`window.__JG.report()`, the dev-server route, `bun run debug`) both produce exactly this object, so a budget check and a diff read either one.
+- `PerfQuality` (type): type PerfQuality = "full" | "draft" — Graphics tier the record was measured at.
+- `PerfReport` (interface): interface PerfReport — One measured window of one game: the record `bun run perf`, `window.__JG.report()` and `bun run debug` print.
+- `ProfileEntry` (interface): interface ProfileEntry — One sampled stack frame reduced to a readable key and its self time.
+- `ProfileReport` (interface): interface ProfileReport — CPU profile summary; only the CDP harness can produce one.
+- `RenderReport` (interface): interface RenderReport — Renderer-side counts for the measured window; `null` where the source could not read them.
+- `ReportLogLine` (interface): interface ReportLogLine — One log line as it appears in the report.
+- `ReportLogs` (interface): interface ReportLogs — Bounded log read-out carried by the report: warn/error lines survive even a flood of info logs.
+- `ReportTelemetry` (interface): interface ReportTelemetry — Who produced the report, and how much producing it cost.
+- `SceneNodeSource` (type): type SceneNodeSource = "scene-graph" | "heap-object3d" | "unavailable" — Where the scene-node count came from: the live scene graph, a heap walk, or nowhere.
+
+## @jgengine/core/devtools/reportEndpoint
+
+- `REPORT_ENDPOINT_PATH` (const): const REPORT_ENDPOINT_PATH: "/__jgengine/report" — The dev-only route a running game pushes its in-page report to, and that `bun run debug <game>` reads back. One process: the page gathers, the dev server holds the newest record per game, the CLI fetches it. Nothing here ships in a production build — the Vite plugin mounts it under `apply: "serve"`.
+- `ReportPushBody` (interface): interface ReportPushBody — Body the page POSTs: the game it measured and the record itself.
+- `ReportRouteError` (interface): interface ReportRouteError — Body sent when there is nothing to return yet.
+
 ## @jgengine/core/devtools/rewriteTunables
 
 - `TunableDelta` (interface): interface TunableDelta — One changed tunable to write back into game source: which table, key path, and new value.
@@ -203,8 +252,10 @@
 
 - `Devtools` (interface): interface Devtools — Top-level devtools facade aggregating frame, profile, render, logs, latency, controls, discover, overrides, and probes.
 - `DevtoolsControl` (interface): interface DevtoolsControl — Registered tunable control with its resolved schema metadata and read/write/reset accessors.
-- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, and formatted message.
+- `DevtoolsLatency` (interface): interface DevtoolsLatency — Latency samples recorded by instrumented transport methods.
+- `DevtoolsLogEntry` (interface): interface DevtoolsLogEntry — A single captured log line with timestamp, level, owning system tag, and formatted message.
 - `DevtoolsLogLevel` (type): type DevtoolsLogLevel = "log" | "info" | "warn" | "error" — Severity level for a captured devtools log entry.
+- `DevtoolsLogs` (interface): interface DevtoolsLogs — Bounded log ring with per-system tags, a warning/error ring, and lifetime counts.
 - `DevtoolsSnapshot` (interface): interface DevtoolsSnapshot — Serializable point-in-time snapshot of devtools state: frame, render, latency, logs, controls, and discovered fields.
 - `DiscoveredEntry` (interface): interface DiscoveredEntry — A control auto-discovered by scanning an object/table, with its binding metadata and current reader.
 - `FrameRecordSample` (interface): interface FrameRecordSample — Per-frame timing input recorded by callers: total frame time, sim time, and optional named phase durations.
@@ -214,6 +265,8 @@
 - `OverrideApplyResult` (interface): interface OverrideApplyResult — Outcome of applying a devtools overrides payload: counts of applied and skipped entries plus diagnostics.
 - `PhaseStats` (interface): interface PhaseStats — Timing summary for a single named profiling phase across the sampling window.
 - `RenderSample` (interface): interface RenderSample — Snapshot of renderer resource counts (draw calls, triangles, geometries, textures) for a frame.
+- `SystemProbe` (interface): interface SystemProbe — What one system reports about itself: totals it keeps anyway, named timings, and one state line.
+- `SystemProbeReading` (interface): interface SystemProbeReading — One system's probe read out on demand; missing sections stay empty rather than absent.
 - `Tunable` (interface): interface Tunable<T> — Typed handle to a registered control, exposing its live value and subscribe/set/reset operations.
 - `TunableAccessor` (interface): interface TunableAccessor — Get/set accessor pair plus initial value used to bind a discovered field to a control.
 
@@ -232,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.24.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.26.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 

package/skills/jgengine/capabilities.md

@@ -48,6 +48,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineSystem` (function) · `import { defineSystem } from "@jgengine/shell/gameKit"`
 
+## devtools-log-bus — a bounded, per-system-tagged log ring a system writes to and a report reads
+
+- `LogBus` (interface) · `import { LogBus } from "@jgengine/core/devtools/logBus"`
+
 ## editor-catalogs — Export typed gameplay catalogs for in-editor tuning.
 
 - `EditorCatalogDefinition` (interface) · `import { EditorCatalogDefinition } from "@jgengine/shell/gameKit"`

package/skills/jgengine-combat/SKILL.md

@@ -19,6 +19,13 @@ a parallel entity store. To bolt firing onto an existing game, compose
 `resolveDamageHit`) per the
 [portable weapon-plumbing recipe](recipes/portable-weapon-plumbing.md); never add
 a default gun or FPS kit.
+For a weapon that is plain data — fire mode, rate, delivery, magazine, recoil and
+spread, damage — hand the definition to `createWeaponSystem`
+(`combat/weaponSystem`): it runs single/auto/burst, hitscan or ballistic
+projectiles, interrupted reloads and a readable ammo economy, and resolves both
+deliveries through `createDamageRuntime`. Generated guns (rolled parts) are the
+same `WeaponDefinition`; see
+[reference.md](reference.md#weapons-as-data).
 For scene-backed `createProjectileSystem`, inject authoritative `rng`; spread
 samples independent pellet rays and prediction stays on the center ray. The
 weapon-plumbing recipe covers the bounded cone and cover contracts.
@@ -30,9 +37,17 @@ Damage commitment accepts the same structural pool adapter while the matchup,
 receiver, interceptor, and status stages remain pure. Follow the
 [portable damage/effects recipe](recipes/portable-damage-effects.md) to compose
 them over an existing store, clock, RNG, spatial index, and death flow.
+Damage types × resistance, the armor curve, hit-zone crits and carried statuses
+compose through `createDamageRuntime` (`combat/damageRuntime`): a readable table,
+time-to-kill quotes, and status ticks that follow the declared stack rule. It
+snapshots/restores as plain data; see
+[reference.md](reference.md#damage-runtime-armor-crits-and-statuses).
 
 Closure-backed magazines expose snapshot/restore and `retune` for capacity/reload
 changes without reconstructing ammo state; capacity overflow is explicit.
+`pauseReload`/`resumeReload` suspend a reload and keep its progress, so a
+sprint or a weapon swap can interrupt one and continue it; a paused reload is
+not `isReloading()` and does not advance in `tick`.
 Stat modifiers expose snapshot/restore; ability
 kits, shields, and meters expose state/restore for caller-owned saves,
 rollback, replay, and workers. Follow the
@@ -48,6 +63,8 @@ keeps its clock, reserve state, schema, and authority.
 5. Apply damage/healing/status transitions and emit provenance-rich events.
 6. Resolve death/downed and rewards separately from the hit itself.
 
+Enemy squad AI is a consumer of that pipeline, not a parallel one: `createSquadCombat` (`combat/squadCombat`) picks cover from authored geometry by remembered threat, flanks by role, holds fire discipline, pins under suppression and falls back when hurt, while `engage` hands each paced shot to your damage resolution and `underFire` feeds the hit back in. Cover, roles and threat all live in [reference.md](reference.md#enemy-squad-ai).
+
 Compose stages through registration/policy seams; adding a damage type, effect, target policy, or reward strategy must not add a central engine branch.
 
 Weapon feel sits beside the pipeline, not inside it. `createWeaponHandling` (`combat/weaponHandling`) owns recoil pattern, camera kick versus aim kick, recovery, spread bloom, stance and ADS multipliers, and ADS time, all as serializable state. `weaponFire`/`magazine` own cadence and ammo, and call `fire()` on each shot. Sample the shot cone from `fire().spread`, add `tick().aimPitch/aimYaw` to the aim, and send `cameraPitch/cameraYaw` to the view. Two weapons differ by numbers in radians and seconds; assert them with `measureWeapon` (first and tenth shot spread, climb, reset time, ADS time, time-to-kill). To present it, return the frame from `camera.weapon` with a `createWeaponPresentation` tuning (`combat/weaponPresentation`); the first-person and shoulder rigs pose the viewmodel and camera from that one frame, and third-person code reads `aimPitch`/`aimYaw` from the same pose.