@oasys/oecs 0.3.1 → 0.5.0

package/dist/core/ecs/observer.d.ts

@@ -0,0 +1,173 @@
+import { ArchetypeView } from './archetype.js';
+import { ComponentHandle } from './component.js';
+import { EntityID } from './entity.js';
+import { FrameTraceSink } from './frame_trace.js';
+import { SystemContext } from './query.js';
+import { StructuralObserverEvents } from './store.js';
+import { SystemAccessDeclaration, SystemDescriptor } from './system.js';
+/** What the observer registry needs from `Store` — the typed seam replacing
+ * bare underscore-convention reach-through (M1). `Store` implements this; the
+ * registry holds only this view, so the compiler bounds what observer dispatch
+ * can touch. Underscore names are kept so `Store`'s members stay one
+ * declaration (they read as "internal" at every other call site). */
+export interface ObserverHost {
+    /** Current change tick — read for onSet baselines. */
+    readonly _tick: number;
+    /** Dev-only frame-trace sink (`null` when unset; always null in prod). */
+    readonly _trace: FrameTraceSink | null;
+    /** Sync a component's observation flags (add/remove/disable/enable/dirty). */
+    _configureComponentObservation(cid: number, hasAdd: boolean, hasRem: boolean, hasDisable: boolean, hasEnable: boolean, trackDirty: boolean): void;
+    /** Drain the per-entity onSet dirty list for `cid` (clears marks). */
+    _takeDirty(cid: number): EntityID[];
+    /** Visit archetypes whose `cid` column changed since `baseline`, in
+     * canonical (creation-id) order. */
+    _forEachChangedArchetype(cid: number, baseline: number, cb: (arch: ArchetypeView) => void): void;
+    /** Every live entity currently holding `cid` (dispose-on-disable sweep). */
+    _collectEntitiesWithComponent(cid: number): EntityID[];
+    isAlive(id: EntityID): boolean;
+    isDisabled(id: EntityID): boolean;
+    hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
+}
+/** Per-entity observer callback (onAdd / onRemove / onDisable / onEnable, and
+ * per-entity onSet). */
+export type ObserverFn = (eid: EntityID, ctx: SystemContext) => void;
+/** Archetype-granular onSet callback — fires once per changed archetype-column;
+ * the consumer iterates `arch.entityCount` rows itself. */
+export type ArchetypeObserverFn = (arch: ArchetypeView, ctx: SystemContext) => void;
+/** Fields common to every observer registration. `access` drives both the
+ * dev-mode `accessCheck` and the access-topological firing order; it is merged
+ * over an all-empty declaration, so a caller spells out only what it touches. */
+interface ObserverConfigBase {
+    onAdd?: ObserverFn;
+    onRemove?: ObserverFn;
+    /** Fires when an entity carrying this component is *disabled* (#577) — at the
+     * deferred toggle drain, once per net transition (ADR-0023). Mirrors `onRemove`:
+     * a disable is a soft remove of the whole mask from default queries. An immediate
+     * host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
+    onDisable?: ObserverFn;
+    /** Fires when an entity carrying this component is *enabled* (#577), symmetric
+     * with `onDisable` / `onAdd`. */
+    onEnable?: ObserverFn;
+    /** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
+     * merged over `_INTERNAL_EMPTY_ACCESS`. Undeclared access throws in `DEV`. */
+    access?: Partial<SystemAccessDeclaration>;
+    /** flecs-style replay of current matches on registration (onAdd only — seeds the
+     * *enabled* members; a disabled entity is simply absent, matching default-query
+     * semantics), for order-independence of register-vs-spawn. */
+    yieldExisting?: boolean;
+    /** Diagnostic label for this observer, surfaced by the frame-trace seam
+     * (ADR-0030) as the `observer_fired.observer` field — the same role a system's
+     * `name` plays. Optional and observe-only: it never touches `stateHash` or
+     * dispatch. Defaults to `observer(<component debug name>)` when the component
+     * was registered with a name, else `observer(<cid>)`. */
+    name?: string;
+}
+/** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
+ * from the opt-in per-row dirty list (registering this enables dirty tracking
+ * for the component — the ADR-0012 list + dedup bit). */
+export interface EntitySetObserverConfig extends ObserverConfigBase {
+    onSet: ObserverFn;
+    granularity: "entity";
+}
+/** Archetype-granular onSet (default): `onSet(arch, ctx)` fires once per
+ * changed archetype-column (the change tick), in canonical archetype order. Free
+ * write path. */
+export interface ArchetypeSetObserverConfig extends ObserverConfigBase {
+    onSet: ArchetypeObserverFn;
+    granularity?: "archetype";
+}
+/** Structural-only observer — no onSet. */
+export interface StructuralObserverConfig extends ObserverConfigBase {
+    onSet?: undefined;
+    granularity?: undefined;
+}
+export type ObserverConfig = StructuralObserverConfig | EntitySetObserverConfig | ArchetypeSetObserverConfig;
+export interface ObserverHandle {
+    dispose(): void;
+    /** `using h = ecs.observe(C, {...})` — explicit-resource-management sugar
+     * over {@link dispose} (TC39 `Symbol.dispose`). */
+    [Symbol.dispose](): void;
+}
+/**
+ * Registry of component observers. Owned by `ECS`; the `Store` calls back into
+ * `dispatchStructural` between fixed-point rounds during `flushStructural`,
+ * and `ECS.update` calls `dispatchSet` at the post-update detection point.
+ */
+export declare class ObserverRegistry {
+    private readonly store;
+    private readonly ctx;
+    private readonly entries;
+    /** ComponentID → its observers (structural + onSet). */
+    private readonly byCid;
+    /** Cached access-topological order; invalidated on register / dispose. */
+    private _topo;
+    private readonly _addBuckets;
+    private readonly _remBuckets;
+    private readonly _disBuckets;
+    private readonly _enaBuckets;
+    private readonly _radixOut;
+    private readonly _radixC0;
+    private readonly _radixC1;
+    private readonly _setDrainCache;
+    constructor(store: ObserverHost, ctx: SystemContext);
+    get count(): number;
+    /** The synthesized `SystemDescriptor`s of every registered observer, in
+     * registration order (`dispose()` splices entries out, so none are stale).
+     * Fed into the `startup()` archetype-prewarm closure so an observer's declared
+     * `spawns` / `transitions` create their target archetypes eagerly, exactly as a
+     * system's do (#768). Without this an observer-spawned/-transitioned archetype
+     * first-touches lazily mid-tick — the one asymmetry left in the otherwise
+     * uniform "no lazy archetypes" prewarm. */
+    descriptors(): SystemDescriptor[];
+    register(def: ComponentHandle, config: ObserverConfig): ObserverHandle;
+    private _dispose;
+    /** Recompute the component's hot-path observation flags from its live
+     * observers and push them to the store (which owns the flags + fast-path
+     * counters). */
+    private _reconfigureComponent;
+    private getTopo;
+    /**
+     * Fire onAdd / onRemove / onDisable / onEnable for one fixed-point round's
+     * effective events, in canonical order: access-topological across observers,
+     * entity-id order (radix) within each observer. Called by
+     * `Store.flushStructural` after the batch commits; observer callbacks may
+     * enqueue further structural ops (or toggles) onto the deferred buffers (the
+     * store loops until quiescent).
+     *
+     * The events arrive as flat `(comp, eid)` parallel arrays collected during the
+     * flush; we bucket by component once (O(K)), then walk observers in topo order
+     * so a producer's writes are visible to a consumer (glitch-free). A round
+     * carries either structural (add/rem) OR toggle (dis/ena) events, never both —
+     * toggles drain only once add/remove/destroy are quiescent (`flushStructural`)
+     * — but we bucket all four uniformly; the empty pairs are no-ops. Within an
+     * observer the fire order is remove, add, disable, enable (the "leaving" edges
+     * before the "entering" edges).
+     */
+    dispatchStructural(ev: StructuralObserverEvents): void;
+    /** Radix-sort `eids` by entity index (canonical within-observer order), then
+     * fire `fn` per entity under the observer's access scope. */
+    private _fireEach;
+    private _bucket;
+    private _clearBuckets;
+    /**
+     * Fire onSet observers for the current tick, in canonical order. Per-entity
+     * onSet drains the opt-in dirty list (once per changed entity); archetype-
+     * granular onSet scans the change tick (once per changed archetype-column).
+     * Called by `ECS.update` after all phases, with `tick === store._tick`.
+     */
+    dispatchSet(tick: number): void;
+    private _dispatchSetEntity;
+    private _dispatchSetArch;
+    private _yieldExisting;
+}
+/**
+ * O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
+ * passes), in place. This is the canonical within-observer order — *never* a
+ * comparator `Array.sort`, which the bench measured at 2–4× the entire flush
+ * (`observer_dispatch_probe.ts`). Distinct live entities have distinct indices,
+ * so index order is a total canonical order. `out` is scratch (grown to length);
+ * `c0` / `c1` are 1024-entry histograms (reused).
+ */
+export declare function radixSortByIndex(eids: number[], out: number[], c0: Int32Array, c1: Int32Array): void;
+export {};
+//# sourceMappingURL=observer.d.ts.map

package/dist/core/ecs/observer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/observer.ts"],"names":[],"mappings":"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"}