@jgengine/core 0.18.0 → 0.18.1

package/dist/runtime/worldSnapshot.js

@@ -13,6 +13,9 @@ export function composeWorldSnapshot(modules, viewer) {
     const snapshot = {};
     for (const module of modules) {
         const value = raw[module.key];
+        const interval = viewer?.tick === undefined ? 1 : Math.max(1, Math.floor(module.priority?.(value, viewer) ?? 1));
+        if (viewer?.tick !== undefined && interval > 1 && viewer.tick % interval !== 0)
+            continue;
         snapshot[module.key] =
             module.project !== undefined ? module.project(value, viewer, raw) : value;
     }

package/dist/scene/behaviorRuntime.d.ts

@@ -1,8 +1,22 @@
+import type { DecisionAction, DecisionGraphRuntime } from "../ai/decisionGraph.js";
+import { type InterestGateState } from "../ai/interestScheduler.js";
 import { type PathFollowState, type PathProgress, type Waypoint } from "../nav/pathFollow.js";
 import type { GameContext } from "../runtime/gameContext.js";
 /** Whether a behavior instance advances and writes pose (`active`), is temporarily suspended retaining
  * state (`paused`), or is held off until re-enabled (`disabled`). */
 export type BehaviorStatus = "active" | "paused" | "disabled";
+/** Context supplied to a registered decision graph action. */
+export interface BehaviorActionContext {
+    ctx: GameContext;
+    entityId: string;
+    dt: number;
+}
+/** Callback used by a registered decision graph behavior action. */
+export type BehaviorAction = DecisionAction<BehaviorActionContext>;
+/** Register the named actions used by decision graph behavior descriptors.
+ * @capability behavior-actions register named callbacks for decision graph behavior descriptors
+ */
+export declare function registerBehaviorActions(id: string, actions: Record<string, BehaviorAction>): () => void;
 /**
  * Catch-up policy applied when a paused instance resumes. `freeze` (default, deterministic) discards
  * the time spent paused; `advance` silently fast-forwards the instance by the paused duration without
@@ -18,11 +32,15 @@ export type BehaviorSnapshot = {
     readonly kind: "wander";
     readonly origin: Waypoint;
     readonly target: Waypoint | null;
+} | {
+    readonly kind: "decisionGraph";
+    readonly graph: ReturnType<DecisionGraphRuntime["snapshot"]>;
+    readonly gate: InterestGateState;
 };
 /** Inspection readout for editor/debug tooling, from {@link BehaviorControl.inspect}/{@link BehaviorControl.list}. */
 export interface BehaviorInspection {
     id: string;
-    kind: "patrol" | "wander";
+    kind: "patrol" | "wander" | "decisionGraph";
     status: BehaviorStatus;
     reason: string | null;
 }

package/dist/scene/behaviorRuntime.js

@@ -1,4 +1,5 @@
-import { seededRng } from "../random/rng.js";
+import { createDecisionGraphRuntime } from "../ai/decisionGraph.js";
+import { advanceInterestGate, createInterestGateState } from "../ai/interestScheduler.js";
 import { advancePathFollow, createPathFollow, pathFollowSeek, } from "../nav/pathFollow.js";
 import { resolveWalkerStep } from "../movement/solidObstacles.js";
 import { perContext } from "../runtime/perContext.js";
@@ -6,12 +7,27 @@ const DEFAULT_WANDER_SPEED = 1.5;
 const WANDER_ARRIVAL = 0.6;
 /** Below this share of its intended step a wanderer counts as blocked and re-rolls its target. */
 const WANDER_BLOCKED_FRACTION = 0.25;
+const behaviorActions = new Map();
+/** Register the named actions used by decision graph behavior descriptors.
+ * @capability behavior-actions register named callbacks for decision graph behavior descriptors
+ */
+export function registerBehaviorActions(id, actions) {
+    behaviorActions.set(id, actions);
+    return () => {
+        if (behaviorActions.get(id) === actions)
+            behaviorActions.delete(id);
+    };
+}
+const DECISION_GRAPH_CADENCE = { wakeRadius: Number.POSITIVE_INFINITY, activeInterval: 0 };
 function patrolOf(entity) {
     return entity.behaviors.find((b) => b.kind === "patrol") ?? null;
 }
 function wanderOf(entity) {
     return entity.behaviors.find((b) => b.kind === "wander") ?? null;
 }
+function decisionGraphOf(entity) {
+    return entity.behaviors.find((b) => b.kind === "decisionGraph") ?? null;
+}
 const runtimeOf = perContext((ctx) => {
     const nav = new Map();
     const refresh = () => {
@@ -41,7 +57,23 @@ const runtimeOf = perContext((ctx) => {
                     radius: wander.radius,
                     origin: entity.position,
                     target: null,
-                    roll: seededRng(`wander:${entity.id}`),
+                    roll: () => ctx.rng(),
+                    status: "active",
+                    reason: null,
+                    pausedElapsed: 0,
+                });
+                continue;
+            }
+            const decisionGraph = decisionGraphOf(entity);
+            if (decisionGraph !== null) {
+                const actions = behaviorActions.get(decisionGraph.actions);
+                if (actions === undefined)
+                    continue;
+                nav.set(entity.id, {
+                    kind: "decisionGraph",
+                    behavior: decisionGraph,
+                    runtime: createDecisionGraphRuntime(decisionGraph.graph, actions),
+                    gate: createInterestGateState(DECISION_GRAPH_CADENCE, ctx.rng()),
                     status: "active",
                     reason: null,
                     pausedElapsed: 0,
@@ -135,9 +167,21 @@ export function advanceBehaviors(ctx, dt) {
             entry.state = advancePathFollow(entry.config, entry.state, dt);
             posePatrol(ctx, id, entry, dt);
         }
-        else {
+        else if (entry.kind === "wander") {
             stepWander(ctx, id, entry, dt);
         }
+        else {
+            const entity = ctx.scene.entity.get(id);
+            if (entity === null)
+                continue;
+            const step = advanceInterestGate(entry.gate, DECISION_GRAPH_CADENCE, dt, { proximity: 0 });
+            if (!step.active)
+                continue;
+            const blackboard = {};
+            const status = entry.runtime.tick({ ctx, entityId: id, dt }, blackboard, dt);
+            if (status === "done" || status === "failed")
+                entry.runtime.restore({ runningPath: null });
+        }
     }
 }
 /**
@@ -206,7 +250,9 @@ export function behaviorControl(ctx) {
                 return null;
             if (entry.kind === "patrol")
                 return { kind: "patrol", state: { ...entry.state } };
-            return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+            if (entry.kind === "wander")
+                return { kind: "wander", origin: [...entry.origin], target: entry.target === null ? null : [...entry.target] };
+            return { kind: "decisionGraph", graph: entry.runtime.snapshot(), gate: { ...entry.gate } };
         },
         restore: (id, snapshot) => {
             const entry = nav.get(id);
@@ -216,6 +262,11 @@ export function behaviorControl(ctx) {
                 entry.state = { ...snapshot.state };
                 return true;
             }
+            if (entry.kind === "decisionGraph" && snapshot.kind === "decisionGraph") {
+                entry.runtime.restore(snapshot.graph);
+                entry.gate = { ...snapshot.gate };
+                return true;
+            }
             if (entry.kind === "wander" && snapshot.kind === "wander") {
                 entry.origin = [...snapshot.origin];
                 entry.target = snapshot.target === null ? null : [...snapshot.target];

package/dist/scene/behaviors.d.ts

@@ -1,5 +1,6 @@
 import { type ProximityPrompt } from "../interaction/proximityPrompt.js";
 import type { PathProgress, Waypoint } from "../nav/pathFollow.js";
+import type { DecisionGraph } from "../ai/decisionGraph.js";
 export interface WanderBehavior {
     kind: "wander";
     radius: number;
@@ -27,7 +28,13 @@ export interface PromptableBehavior {
 export interface PlayerBehavior {
     kind: "player";
 }
-export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior;
+/** Decision graph behavior descriptor using a named registered action set. */
+export interface DecisionGraphBehavior {
+    kind: "decisionGraph";
+    graph: DecisionGraph;
+    actions: string;
+}
+export type BehaviorDescriptor = WanderBehavior | PatrolBehavior | PromptableBehavior | PlayerBehavior | DecisionGraphBehavior;
 export declare function wander({ radius }: {
     radius: number;
 }): WanderBehavior;

package/dist/scene/builtinSceneKinds.js

@@ -37,6 +37,15 @@ export const SCATTER_SCHEMA = {
         { type: "seed", key: "seed", label: "seed", default: "" },
     ],
 };
+const LIGHT_SCHEMA = {
+    fields: [
+        { type: "select", key: "type", label: "type", options: [{ value: "point", label: "Point" }, { value: "spot", label: "Spot" }], default: "point" },
+        { type: "color", key: "color", label: "color", default: "#ffd6a0" },
+        { type: "number", key: "intensity", label: "intensity", min: 0, step: 0.1, default: 2 },
+        { type: "number", key: "range", label: "range", min: 0, step: 0.5, default: 12 },
+        { type: "bool", key: "castShadow", label: "cast shadow", default: false },
+    ],
+};
 let registered = false;
 /** Idempotently registers the engine's built-in environment scene kinds + generators. @internal */
 export function registerBuiltinSceneKinds() {
@@ -65,6 +74,7 @@ export function registerBuiltinSceneKinds() {
             return describeScatterCoverage(densityCoverage("scatter", area, density));
         },
     });
+    registerSceneKind({ kind: "light", target: "marker", label: "Light", addCategory: "Environment", accent: "#fbbf24", schema: LIGHT_SCHEMA });
     registerWaterKind();
     registerGrassKind();
     registerSoilKind();

package/dist/sensor/perception.d.ts

@@ -0,0 +1,60 @@
+/** A world position used by perception, in `[x, y, z]` order. */
+export type PerceptionPosition = readonly [number, number, number];
+/** The kinds of stimulus the perception service can retain. */
+export type PerceptionStimulusKind = "sight" | "sound" | "damage";
+/** An event that can seed an observer's memory. */
+export interface PerceptionStimulus {
+    kind: PerceptionStimulusKind;
+    sourceId: string;
+    position: PerceptionPosition;
+    loudness?: number;
+    at: number;
+}
+/** The observer pose used for a sight check. */
+export interface PerceptionObserver {
+    id: string;
+    position: PerceptionPosition;
+    yaw: number;
+}
+/** A candidate target considered by a sight check. */
+export interface PerceptionCandidate {
+    id: string;
+    position: PerceptionPosition;
+}
+/** A remembered target and its linearly decaying confidence. */
+export interface PerceptionMemory {
+    targetId: string;
+    lastSeenAt: number;
+    lastKnownPos: PerceptionPosition;
+    confidence: number;
+}
+/** Configuration for sight, hearing, memory decay, and optional occlusion. */
+export interface PerceptionConfig {
+    sightRange: number;
+    sightConeDeg: number;
+    hearingRange: number;
+    memorySeconds: number;
+    occluded?: (from: PerceptionPosition, to: PerceptionPosition) => boolean;
+}
+/** Serializable state for a perception service. */
+export interface PerceptionSnapshot {
+    memories: Array<{
+        observerId: string;
+        memory: PerceptionMemory;
+    }>;
+    stimuli: PerceptionStimulus[];
+    nowMs: number;
+}
+/** Stateful perception API with retuning and save/restore support. */
+export interface PerceptionService {
+    pushStimulus(stimulus: PerceptionStimulus): void;
+    observe(observer: PerceptionObserver, candidates: readonly PerceptionCandidate[], nowMs: number): void;
+    memory(observerId: string): PerceptionMemory[];
+    retune(patch: Partial<PerceptionConfig>): void;
+    snapshot(): PerceptionSnapshot;
+    restore(snapshot: PerceptionSnapshot): void;
+}
+/** Creates a deterministic sight, sound, and damage perception service with expiring target memory.
+ * @capability perception-service retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
+ */
+export declare function createPerception(initial: PerceptionConfig): PerceptionService;

package/dist/sensor/perception.js

@@ -0,0 +1,142 @@
+function distance(a, b) {
+    return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+function confidenceAt(memory, nowMs, memoryMs) {
+    return memory.confidence * Math.max(0, 1 - Math.max(0, nowMs - memory.lastSeenAt) / memoryMs);
+}
+function inSight(observer, target, config) {
+    const dx = target[0] - observer.position[0];
+    const dz = target[2] - observer.position[2];
+    const range = Math.hypot(dx, dz);
+    if (range > config.sightRange)
+        return false;
+    if (range < 1e-9)
+        return true;
+    let delta = Math.atan2(dx, dz) - observer.yaw;
+    while (delta > Math.PI)
+        delta -= Math.PI * 2;
+    while (delta < -Math.PI)
+        delta += Math.PI * 2;
+    return Math.abs(delta) <= (config.sightConeDeg * Math.PI) / 360;
+}
+function validate(config) {
+    if (!Number.isFinite(config.sightRange) || config.sightRange < 0)
+        throw new Error("sightRange must be non-negative.");
+    if (!Number.isFinite(config.sightConeDeg) || config.sightConeDeg < 0 || config.sightConeDeg > 360)
+        throw new Error("sightConeDeg must be between 0 and 360.");
+    if (!Number.isFinite(config.hearingRange) || config.hearingRange < 0)
+        throw new Error("hearingRange must be non-negative.");
+    if (!Number.isFinite(config.memorySeconds) || config.memorySeconds <= 0)
+        throw new Error("memorySeconds must be positive.");
+}
+/** Creates a deterministic sight, sound, and damage perception service with expiring target memory.
+ * @capability perception-service retain sight, sound, and damage observations with range, cone, occlusion, and decay policy
+ */
+export function createPerception(initial) {
+    validate(initial);
+    let config = { ...initial };
+    let nowMs = 0;
+    const stimuli = [];
+    const memories = new Map();
+    function remember(observerId, targetId, position, at, confidence) {
+        if (confidence <= 0)
+            return;
+        let observerMemories = memories.get(observerId);
+        if (observerMemories === undefined) {
+            observerMemories = new Map();
+            memories.set(observerId, observerMemories);
+        }
+        const previous = observerMemories.get(targetId);
+        if (previous === undefined || at >= previous.lastSeenAt) {
+            observerMemories.set(targetId, { targetId, lastSeenAt: at, lastKnownPos: [...position], confidence });
+        }
+    }
+    function prune() {
+        const memoryMs = config.memorySeconds * 1000;
+        for (const [observerId, observerMemories] of memories) {
+            for (const [targetId, memory] of observerMemories) {
+                if (confidenceAt(memory, nowMs, memoryMs) <= 0)
+                    observerMemories.delete(targetId);
+            }
+            if (observerMemories.size === 0)
+                memories.delete(observerId);
+        }
+        const cutoff = nowMs - memoryMs;
+        while (stimuli.length > 0 && stimuli[0].at < cutoff)
+            stimuli.shift();
+    }
+    return {
+        pushStimulus(stimulus) {
+            if (!Number.isFinite(stimulus.at))
+                throw new Error("stimulus.at must be finite.");
+            if (stimulus.kind === "sound" && stimulus.loudness !== undefined && (!Number.isFinite(stimulus.loudness) || stimulus.loudness < 0)) {
+                throw new Error("stimulus.loudness must be non-negative.");
+            }
+            stimuli.push({ ...stimulus, position: [...stimulus.position] });
+            stimuli.sort((a, b) => a.at - b.at);
+            nowMs = Math.max(nowMs, stimulus.at);
+            prune();
+        },
+        observe(observer, candidates, observedAt) {
+            if (!Number.isFinite(observedAt))
+                throw new Error("nowMs must be finite.");
+            nowMs = observedAt;
+            for (const candidate of candidates) {
+                if (!inSight(observer, candidate.position, config))
+                    continue;
+                if (config.occluded?.(observer.position, candidate.position))
+                    continue;
+                remember(observer.id, candidate.id, candidate.position, nowMs, 1);
+            }
+            for (const stimulus of stimuli) {
+                if (stimulus.at > nowMs || stimulus.sourceId === observer.id)
+                    continue;
+                const range = distance(observer.position, stimulus.position);
+                if (stimulus.kind === "sound") {
+                    if (range > config.hearingRange)
+                        continue;
+                    const falloff = 1 - range / Math.max(config.hearingRange, 1e-9);
+                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, falloff * (stimulus.loudness ?? 1));
+                }
+                else if (stimulus.kind === "damage") {
+                    remember(observer.id, stimulus.sourceId, stimulus.position, stimulus.at, 1);
+                }
+            }
+            prune();
+        },
+        memory(observerId) {
+            const observerMemories = memories.get(observerId);
+            if (observerMemories === undefined)
+                return [];
+            const memoryMs = config.memorySeconds * 1000;
+            const result = [];
+            for (const memory of observerMemories.values()) {
+                const confidence = confidenceAt(memory, nowMs, memoryMs);
+                if (confidence > 0)
+                    result.push({ ...memory, lastKnownPos: [...memory.lastKnownPos], confidence });
+            }
+            return result;
+        },
+        retune(patch) {
+            config = { ...config, ...patch };
+            validate(config);
+            prune();
+        },
+        snapshot() {
+            const result = { memories: [], stimuli: stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })), nowMs };
+            for (const [observerId, observerMemories] of memories)
+                for (const memory of observerMemories.values())
+                    result.memories.push({ observerId, memory: { ...memory, lastKnownPos: [...memory.lastKnownPos] } });
+            return result;
+        },
+        restore(snapshot) {
+            memories.clear();
+            stimuli.length = 0;
+            nowMs = snapshot.nowMs;
+            stimuli.push(...snapshot.stimuli.map((stimulus) => ({ ...stimulus, position: [...stimulus.position] })));
+            for (const entry of snapshot.memories)
+                remember(entry.observerId, entry.memory.targetId, entry.memory.lastKnownPos, entry.memory.lastSeenAt, entry.memory.confidence);
+            prune();
+        },
+    };
+}

package/dist/settings/graphicsProfile.d.ts

@@ -0,0 +1,19 @@
+import type { GraphicsQuality } from "./settingsModel.js";
+/** Serializable renderer budget selected by the player's graphics tier. */
+export interface GraphicsProfile {
+    renderScale: number;
+    shadowMapSize: 512 | 1024 | 2048 | 4096;
+    cascades: 1 | 2 | 3 | 4;
+    drawDistance: number;
+    particleCap: number;
+    postStages: {
+        ao: boolean;
+        bloom: boolean;
+        dof: boolean;
+        smaa: boolean;
+    };
+}
+/** Conservative defaults that preserve the existing high-quality shell behavior. */
+export declare const DEFAULT_GRAPHICS_PROFILES: Record<GraphicsQuality, GraphicsProfile>;
+/** Resolve one tier and apply game-authored field and post-stage overrides. */
+export declare function resolveGraphicsProfile(quality: GraphicsQuality, overrides?: Partial<GraphicsProfile>): GraphicsProfile;

package/dist/settings/graphicsProfile.js

@@ -0,0 +1,36 @@
+/** Conservative defaults that preserve the existing high-quality shell behavior. */
+export const DEFAULT_GRAPHICS_PROFILES = {
+    low: {
+        renderScale: 1,
+        shadowMapSize: 512,
+        cascades: 1,
+        drawDistance: 120,
+        particleCap: 128,
+        postStages: { ao: false, bloom: true, dof: false, smaa: true },
+    },
+    medium: {
+        renderScale: 1.5,
+        shadowMapSize: 1024,
+        cascades: 2,
+        drawDistance: 240,
+        particleCap: 256,
+        postStages: { ao: true, bloom: true, dof: true, smaa: true },
+    },
+    high: {
+        renderScale: 2,
+        shadowMapSize: 2048,
+        cascades: 4,
+        drawDistance: 400,
+        particleCap: 512,
+        postStages: { ao: true, bloom: true, dof: true, smaa: true },
+    },
+};
+/** Resolve one tier and apply game-authored field and post-stage overrides. */
+export function resolveGraphicsProfile(quality, overrides) {
+    const base = DEFAULT_GRAPHICS_PROFILES[quality];
+    return {
+        ...base,
+        ...overrides,
+        postStages: { ...base.postStages, ...overrides?.postStages },
+    };
+}

package/dist/time/accrueSince.d.ts

@@ -0,0 +1,10 @@
+/** Elapsed duration and the next anchor to persist with accrued effects. */
+export interface Accrual {
+    elapsedMs: number;
+    elapsedSeconds: number;
+    anchorMs: number;
+}
+/** Elapsed time since a persisted anchor, capped once; persist anchorMs with the accrued result. */
+export declare function accrueSince(anchorMs: number, nowMs: number, options?: {
+    capMs?: number;
+}): Accrual;

package/dist/time/accrueSince.js

@@ -0,0 +1,9 @@
+/** Elapsed time since a persisted anchor, capped once; persist anchorMs with the accrued result. */
+export function accrueSince(anchorMs, nowMs, options = {}) {
+    const cap = options.capMs ?? Infinity;
+    if (!Number.isFinite(anchorMs) || !Number.isFinite(nowMs) || Number.isNaN(cap) || cap < 0) {
+        throw new RangeError("Accrual requires finite anchors and a nonnegative cap");
+    }
+    const elapsedMs = Math.min(cap, Math.max(0, nowMs - anchorMs));
+    return { elapsedMs, elapsedSeconds: elapsedMs / 1000, anchorMs: Math.max(anchorMs, nowMs) };
+}

package/dist/time/rateWindow.d.ts

@@ -0,0 +1,16 @@
+/** Maximum accepted operations in a sliding duration. */
+export interface RateWindowPolicy {
+    windowMs: number;
+    max: number;
+}
+/** Admission result, next stored timestamps, and wait before retrying. */
+export interface RateWindowDecision {
+    allowed: boolean;
+    timestamps: number[];
+    retryAfterMs: number;
+}
+/**
+ * A sliding rate window; persist timestamps only alongside the accepted operation.
+ * @capability rate-window-policy Evaluate deterministic request windows with retry timing.
+ */
+export declare function decideRateWindow(timestamps: readonly number[], nowMs: number, policy: RateWindowPolicy): RateWindowDecision;

package/dist/time/rateWindow.js

@@ -0,0 +1,14 @@
+/**
+ * A sliding rate window; persist timestamps only alongside the accepted operation.
+ * @capability rate-window-policy Evaluate deterministic request windows with retry timing.
+ */
+export function decideRateWindow(timestamps, nowMs, policy) {
+    if (!Number.isFinite(nowMs) || !Number.isFinite(policy.windowMs) || policy.windowMs <= 0 ||
+        !Number.isSafeInteger(policy.max) || policy.max < 1)
+        throw new RangeError("Invalid rate window policy");
+    const active = timestamps.filter((at) => Number.isFinite(at) && at > nowMs - policy.windowMs).sort((a, b) => a - b);
+    if (active.length >= policy.max) {
+        return { allowed: false, timestamps: active, retryAfterMs: Math.max(0, active[active.length - policy.max] + policy.windowMs - nowMs) };
+    }
+    return { allowed: true, timestamps: [...active, nowMs], retryAfterMs: 0 };
+}

package/dist/time/serverTick.d.ts

@@ -2,11 +2,26 @@ export interface TickSystemDefinition<TSystemId extends string = string> {
     id: TSystemId;
     /** Minimum real time between runs; the heartbeat fires the system on the first tick at or past it. */
     intervalMs: number;
+    scope?: "onlinePlayers" | "allServers";
+    batchSize?: number;
 }
 /** Last-run timestamp per system id. */
 export type TickAnchors = Record<string, number>;
+/** One due system and how many times this heartbeat owes it. */
+export interface TickSystemRun<TSystemId extends string = string> {
+    id: TSystemId;
+    /** Times to run the system now; above 1 when wall time stalled past several intervals. */
+    runs: number;
+    scope?: "onlinePlayers" | "allServers";
+    batchSize?: number;
+}
 export interface ServerTickPlan<TSystemId extends string = string> {
-    due: TSystemId[];
+    /**
+     * Due systems, at most one entry per id. `runs` carries catch-up multiplicity — the anchors were
+     * advanced by that many intervals, so a host that runs the handler once per entry silently drops
+     * the rest.
+     */
+    due: TickSystemRun<TSystemId>[];
     anchors: TickAnchors;
 }
 export type PlanServerTickOptions = {
@@ -15,8 +30,11 @@ export type PlanServerTickOptions = {
 };
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
- * When wall time stalls past multiple intervals, the system id is repeated (bounded by
- * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
+ * When wall time stalls past multiple intervals the system's `runs` climbs (bounded by
+ * maxCatchUp), and the returned anchor moves by that many intervals — so a host that ignores
+ * `runs` loses the catch-up work. Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
 export declare function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number, options?: PlanServerTickOptions): ServerTickPlan<TSystemId>;
+/** Times this plan owes `id`, or 0 when it is not due. Saves a host a lookup over {@link ServerTickPlan.due}. */
+export declare function tickRunCount<TSystemId extends string>(plan: ServerTickPlan<TSystemId>, id: TSystemId): number;

package/dist/time/serverTick.js

@@ -1,8 +1,9 @@
 const DEFAULT_MAX_CATCH_UP = 3;
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
- * When wall time stalls past multiple intervals, the system id is repeated (bounded by
- * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
+ * When wall time stalls past multiple intervals the system's `runs` climbs (bounded by
+ * maxCatchUp), and the returned anchor moves by that many intervals — so a host that ignores
+ * `runs` loses the catch-up work. Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
 export function planServerTick(systems, anchors, now, options) {
@@ -10,14 +11,12 @@ export function planServerTick(systems, anchors, now, options) {
     const due = [];
     const nextAnchors = {};
     for (const system of systems) {
+        if (system.batchSize !== undefined && (!Number.isSafeInteger(system.batchSize) || system.batchSize < 1 || system.batchSize > 1000))
+            throw new RangeError("batchSize must be an integer from 1 to 1000");
+        const dispatch = { ...(system.scope === undefined ? {} : { scope: system.scope }), ...(system.batchSize === undefined ? {} : { batchSize: system.batchSize }) };
         const lastRunAt = anchors[system.id];
-        if (lastRunAt === undefined) {
-            due.push(system.id);
-            nextAnchors[system.id] = now;
-            continue;
-        }
-        if (system.intervalMs <= 0) {
-            due.push(system.id);
+        if (lastRunAt === undefined || system.intervalMs <= 0) {
+            due.push({ id: system.id, runs: 1, ...dispatch });
             nextAnchors[system.id] = now;
             continue;
         }
@@ -28,14 +27,16 @@ export function planServerTick(systems, anchors, now, options) {
         }
         const missed = Math.floor(elapsed / system.intervalMs);
         if (missed > maxCatchUp) {
-            for (let i = 0; i < maxCatchUp; i += 1)
-                due.push(system.id);
+            due.push({ id: system.id, runs: maxCatchUp, ...dispatch });
             nextAnchors[system.id] = now;
             continue;
         }
-        for (let i = 0; i < missed; i += 1)
-            due.push(system.id);
+        due.push({ id: system.id, runs: missed, ...dispatch });
         nextAnchors[system.id] = lastRunAt + missed * system.intervalMs;
     }
     return { due, anchors: nextAnchors };
 }
+/** Times this plan owes `id`, or 0 when it is not due. Saves a host a lookup over {@link ServerTickPlan.due}. */
+export function tickRunCount(plan, id) {
+    return plan.due.find((entry) => entry.id === id)?.runs ?? 0;
+}