@oasys/oecs 0.4.0 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +553 -0
- package/README.md +42 -31
- package/dist/core/ecs/access_check.d.cts +77 -0
- package/dist/core/ecs/access_check.d.ts +8 -8
- package/dist/core/ecs/access_check.d.ts.map +1 -1
- package/dist/core/ecs/archetype.d.cts +486 -0
- package/dist/core/ecs/archetype.d.ts +23 -11
- package/dist/core/ecs/archetype.d.ts.map +1 -1
- package/dist/core/ecs/archetype_graph.d.cts +96 -0
- package/dist/core/ecs/archetype_graph.d.ts +96 -0
- package/dist/core/ecs/archetype_graph.d.ts.map +1 -0
- package/dist/core/ecs/builtin_relations.d.cts +43 -0
- package/dist/core/ecs/builtin_relations.d.ts +8 -8
- package/dist/core/ecs/builtin_relations.d.ts.map +1 -1
- package/dist/core/ecs/command_log.d.cts +116 -0
- package/dist/core/ecs/command_log.d.ts +13 -10
- package/dist/core/ecs/command_log.d.ts.map +1 -1
- package/dist/core/ecs/component.d.cts +176 -0
- package/dist/core/ecs/component.d.ts +75 -5
- package/dist/core/ecs/component.d.ts.map +1 -1
- package/dist/core/ecs/compute_backend.d.cts +37 -0
- package/dist/core/ecs/compute_backend.d.ts +2 -2
- package/dist/core/ecs/debug_names.d.cts +7 -0
- package/dist/core/ecs/debug_names.d.ts +7 -0
- package/dist/core/ecs/debug_names.d.ts.map +1 -0
- package/dist/core/ecs/deferred_commands.d.cts +55 -0
- package/dist/core/ecs/deferred_commands.d.ts +55 -0
- package/dist/core/ecs/deferred_commands.d.ts.map +1 -0
- package/dist/core/ecs/dispatch_trace.d.cts +93 -0
- package/dist/core/ecs/dispatch_trace.d.ts +3 -3
- package/dist/core/ecs/ecs.d.cts +562 -0
- package/dist/core/ecs/ecs.d.ts +314 -285
- package/dist/core/ecs/ecs.d.ts.map +1 -1
- package/dist/core/ecs/ecs_memory.d.cts +179 -0
- package/dist/core/ecs/ecs_memory.d.ts +1 -1
- package/dist/core/ecs/entity.d.cts +34 -0
- package/dist/core/ecs/entity.d.ts +7 -1
- package/dist/core/ecs/entity.d.ts.map +1 -1
- package/dist/core/ecs/entity_allocator.d.cts +59 -0
- package/dist/core/ecs/entity_allocator.d.ts +59 -0
- package/dist/core/ecs/entity_allocator.d.ts.map +1 -0
- package/dist/core/ecs/event.d.cts +79 -0
- package/dist/core/ecs/event.d.ts +36 -11
- package/dist/core/ecs/event.d.ts.map +1 -1
- package/dist/core/ecs/event_registry.d.cts +22 -0
- package/dist/core/ecs/event_registry.d.ts +22 -0
- package/dist/core/ecs/event_registry.d.ts.map +1 -0
- package/dist/core/ecs/facades.d.cts +158 -0
- package/dist/core/ecs/facades.d.ts +158 -0
- package/dist/core/ecs/facades.d.ts.map +1 -0
- package/dist/core/ecs/frame_stepper.d.cts +58 -0
- package/dist/core/ecs/frame_stepper.d.ts +58 -0
- package/dist/core/ecs/frame_stepper.d.ts.map +1 -0
- package/dist/core/ecs/frame_trace.d.cts +133 -0
- package/dist/core/ecs/frame_trace.d.ts +5 -5
- package/dist/core/ecs/frame_trace.d.ts.map +1 -1
- package/dist/core/ecs/host_commands.d.cts +274 -0
- package/dist/core/ecs/host_commands.d.ts +53 -31
- package/dist/core/ecs/host_commands.d.ts.map +1 -1
- package/dist/core/ecs/index.d.cts +46 -0
- package/dist/core/ecs/index.d.ts +45 -40
- package/dist/core/ecs/index.d.ts.map +1 -1
- package/dist/core/ecs/observer.d.cts +173 -0
- package/dist/core/ecs/observer.d.ts +43 -12
- package/dist/core/ecs/observer.d.ts.map +1 -1
- package/dist/core/ecs/query.d.cts +718 -0
- package/dist/core/ecs/query.d.ts +251 -90
- package/dist/core/ecs/query.d.ts.map +1 -1
- package/dist/core/ecs/ref.d.cts +31 -0
- package/dist/core/ecs/ref.d.ts +3 -3
- package/dist/core/ecs/relation.d.cts +243 -0
- package/dist/core/ecs/relation.d.ts +26 -14
- package/dist/core/ecs/relation.d.ts.map +1 -1
- package/dist/core/ecs/relation_service.d.cts +235 -0
- package/dist/core/ecs/relation_service.d.ts +235 -0
- package/dist/core/ecs/relation_service.d.ts.map +1 -0
- package/dist/core/ecs/resource.d.cts +53 -0
- package/dist/core/ecs/resource.d.ts +25 -5
- package/dist/core/ecs/resource.d.ts.map +1 -1
- package/dist/core/ecs/resource_registry.d.cts +20 -0
- package/dist/core/ecs/resource_registry.d.ts +20 -0
- package/dist/core/ecs/resource_registry.d.ts.map +1 -0
- package/dist/core/ecs/resume.d.cts +85 -0
- package/dist/core/ecs/resume.d.ts +6 -6
- package/dist/core/ecs/resume.d.ts.map +1 -1
- package/dist/core/ecs/run_condition.d.cts +81 -0
- package/dist/core/ecs/run_condition.d.ts +15 -9
- package/dist/core/ecs/run_condition.d.ts.map +1 -1
- package/dist/core/ecs/schedule.d.cts +142 -0
- package/dist/core/ecs/schedule.d.ts +15 -6
- package/dist/core/ecs/schedule.d.ts.map +1 -1
- package/dist/core/ecs/snapshot_service.d.cts +94 -0
- package/dist/core/ecs/snapshot_service.d.ts +94 -0
- package/dist/core/ecs/snapshot_service.d.ts.map +1 -0
- package/dist/core/ecs/sparse_store.d.cts +110 -0
- package/dist/core/ecs/sparse_store.d.ts +5 -2
- package/dist/core/ecs/sparse_store.d.ts.map +1 -1
- package/dist/core/ecs/store.d.cts +950 -0
- package/dist/core/ecs/store.d.ts +143 -342
- package/dist/core/ecs/store.d.ts.map +1 -1
- package/dist/core/ecs/store_layout_listener.d.cts +23 -0
- package/dist/core/ecs/system.d.cts +250 -0
- package/dist/core/ecs/system.d.ts +138 -22
- package/dist/core/ecs/system.d.ts.map +1 -1
- package/dist/{utils/arrays.d.ts → core/ecs/utils/arrays.d.cts} +1 -0
- package/dist/core/ecs/utils/error.d.cts +61 -0
- package/dist/core/ecs/utils/error.d.ts +12 -2
- package/dist/core/ecs/utils/error.d.ts.map +1 -1
- package/dist/core/store/action_ring.d.cts +136 -0
- package/dist/core/store/allocator.d.cts +238 -0
- package/dist/core/store/allocator.d.ts.map +1 -1
- package/dist/core/store/buffer_backed_column.d.cts +69 -0
- package/dist/core/store/buffer_backed_column.d.ts +2 -2
- package/dist/core/store/column_store.d.cts +273 -0
- package/dist/core/store/column_store.d.ts +18 -10
- package/dist/core/store/column_store.d.ts.map +1 -1
- package/dist/core/store/command_dispatch.d.cts +52 -0
- package/dist/core/store/command_ring.d.cts +107 -0
- package/dist/core/store/descriptor.d.cts +80 -0
- package/dist/core/store/descriptor.d.ts +1 -1
- package/dist/core/store/descriptor.d.ts.map +1 -1
- package/dist/core/store/entity_index.d.cts +108 -0
- package/dist/core/store/event_ring.d.cts +95 -0
- package/dist/core/store/extend.d.cts +39 -0
- package/dist/core/store/extend.d.ts +3 -73
- package/dist/core/store/extend.d.ts.map +1 -1
- package/dist/core/store/grow.d.cts +34 -0
- package/dist/core/store/grow.d.ts +4 -9
- package/dist/core/store/grow.d.ts.map +1 -1
- package/dist/core/store/header.d.cts +64 -0
- package/dist/core/store/header.d.ts +1 -1
- package/dist/core/store/header.d.ts.map +1 -1
- package/dist/core/store/index.d.cts +17 -0
- package/dist/core/store/index.d.ts +16 -15
- package/dist/core/store/index.d.ts.map +1 -1
- package/dist/core/store/layout_ops.d.cts +152 -0
- package/dist/core/store/layout_ops.d.ts +152 -0
- package/dist/core/store/layout_ops.d.ts.map +1 -0
- package/dist/core/store/region_table.d.cts +74 -0
- package/dist/core/store/region_table.d.ts +1 -1
- package/dist/core/store/region_table.d.ts.map +1 -1
- package/dist/core/store/snapshot.d.cts +43 -0
- package/dist/core/store/snapshot.d.ts +2 -2
- package/dist/core/store/state_hash.d.cts +38 -0
- package/dist/core/store/state_hash.d.ts +1 -1
- package/dist/core/store/store_regions.d.cts +38 -0
- package/dist/core/store/store_regions.d.ts +1 -1
- package/dist/core/store/vendored_abi/abi.d.ts +43 -0
- package/dist/core/store/{__generated__ → vendored_abi}/abi.d.ts.map +1 -1
- package/dist/dev_flag.d.cts +17 -0
- package/dist/dev_flag.d.ts +17 -0
- package/dist/dev_flag.d.ts.map +1 -0
- package/dist/extensions/editor/editor.d.cts +170 -0
- package/dist/extensions/editor/editor.d.ts +43 -22
- package/dist/extensions/editor/editor.d.ts.map +1 -1
- package/dist/extensions/editor/field_handle.d.cts +40 -0
- package/dist/extensions/editor/field_handle.d.ts +8 -3
- package/dist/extensions/editor/field_handle.d.ts.map +1 -1
- package/dist/extensions/editor/index.cjs +1 -1
- package/dist/extensions/editor/index.d.cts +21 -0
- package/dist/extensions/editor/index.d.ts +2 -2
- package/dist/extensions/editor/index.js +116 -88
- package/dist/extensions/reactive/ecs_sync.d.cts +214 -0
- package/dist/extensions/reactive/ecs_sync.d.ts +26 -22
- package/dist/extensions/reactive/ecs_sync.d.ts.map +1 -1
- package/dist/extensions/reactive/index.cjs +1 -1
- package/dist/extensions/reactive/index.d.cts +23 -0
- package/dist/extensions/reactive/index.d.ts +1 -1
- package/dist/extensions/reactive/index.js +106 -116
- package/dist/extensions/solid/index.cjs +1 -1
- package/dist/extensions/solid/index.d.cts +6 -0
- package/dist/extensions/solid/index.d.ts +2 -2
- package/dist/extensions/solid/index.js +8 -4
- package/dist/extensions/solid/kernel_solid.d.cts +45 -0
- package/dist/extensions/solid/kernel_solid.d.ts +6 -3
- package/dist/extensions/solid/kernel_solid.d.ts.map +1 -1
- package/dist/host_commands-BF8QMi3c.cjs +1 -0
- package/dist/host_commands-i4cAeyL5.js +2318 -0
- package/dist/index.cjs +1 -2
- package/dist/index.d.cts +66 -0
- package/dist/index.d.ts +50 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4469 -5933
- package/dist/internal.cjs +2 -0
- package/dist/internal.d.cts +20 -0
- package/dist/internal.d.ts +20 -0
- package/dist/internal.d.ts.map +1 -0
- package/dist/internal.js +141 -0
- package/dist/primitives.cjs +1 -1
- package/dist/primitives.d.cts +18 -0
- package/dist/primitives.d.ts +6 -6
- package/dist/primitives.js +24 -23
- package/dist/reactive/array.d.ts +24 -0
- package/dist/reactive/array.d.ts.map +1 -0
- package/dist/reactive/index.cjs +1 -0
- package/dist/reactive/index.d.cts +11 -0
- package/dist/reactive/index.d.ts +11 -0
- package/dist/reactive/index.d.ts.map +1 -0
- package/dist/reactive/index.js +18 -0
- package/dist/reactive/interop.d.cts +19 -0
- package/dist/{core/reactive → reactive}/interop.d.ts +1 -1
- package/dist/reactive/interop.d.ts.map +1 -0
- package/dist/reactive/kernel.d.cts +73 -0
- package/dist/{core/reactive → reactive}/kernel.d.ts +5 -3
- package/dist/reactive/kernel.d.ts.map +1 -0
- package/dist/reactive/map.d.ts +16 -0
- package/dist/reactive/map.d.ts.map +1 -0
- package/dist/reactive/shallow.d.cts +11 -0
- package/dist/reactive/shallow.d.ts +11 -0
- package/dist/reactive/shallow.d.ts.map +1 -0
- package/dist/reactive/struct.d.cts +10 -0
- package/dist/{core/reactive → reactive}/struct.d.ts +1 -1
- package/dist/reactive/struct.d.ts.map +1 -0
- package/dist/shallow-DQ8aG51_.cjs +1 -0
- package/dist/shallow-DfnAm9vG.js +150 -0
- package/dist/shared-BU1Cd40h.js +103 -0
- package/dist/shared-BymrGTyR.cjs +1 -0
- package/dist/shared.cjs +1 -1
- package/dist/shared.d.cts +22 -0
- package/dist/shared.d.ts +2 -2
- package/dist/shared.js +1 -1
- package/dist/topological_sort-BDvEyb9W.cjs +1 -0
- package/dist/topological_sort-DK6EjpWa.js +135 -0
- package/dist/type_primitives/assertions.d.cts +32 -0
- package/dist/type_primitives/assertions.d.ts +13 -1
- package/dist/type_primitives/assertions.d.ts.map +1 -1
- package/dist/type_primitives/binary_heap/binary_heap.d.cts +37 -0
- package/dist/type_primitives/bitset/bitset.d.cts +54 -0
- package/dist/type_primitives/brand.d.cts +23 -0
- package/dist/type_primitives/error.d.cts +16 -0
- package/dist/type_primitives/error.d.ts +4 -3
- package/dist/type_primitives/error.d.ts.map +1 -1
- package/dist/type_primitives/index.d.cts +13 -0
- package/dist/type_primitives/index.d.ts +9 -9
- package/dist/type_primitives/sparse_map/sparse_map.d.cts +30 -0
- package/dist/type_primitives/sparse_set/sparse_set.d.cts +28 -0
- package/dist/type_primitives/topological_sort/topological_sort.d.cts +29 -0
- package/dist/type_primitives/typed_arrays/typed_arrays.d.cts +127 -0
- package/dist/typed_arrays-BcXcnzB4.js +258 -0
- package/dist/typed_arrays-D3NmwtCG.cjs +1 -0
- package/dist/utils/error.d.cts +6 -0
- package/dist/version.d.cts +10 -0
- package/dist/version.d.ts +10 -0
- package/dist/version.d.ts.map +1 -0
- package/package.json +102 -19
- package/dist/array-CxbPyiHO.cjs +0 -1
- package/dist/array-uFR7Q8fU.js +0 -132
- package/dist/core/reactive/array.d.ts.map +0 -1
- package/dist/core/reactive/index.cjs +0 -1
- package/dist/core/reactive/index.d.ts +0 -10
- package/dist/core/reactive/index.d.ts.map +0 -1
- package/dist/core/reactive/index.js +0 -17
- package/dist/core/reactive/interop.d.ts.map +0 -1
- package/dist/core/reactive/kernel.d.ts.map +0 -1
- package/dist/core/reactive/map.d.ts.map +0 -1
- package/dist/core/reactive/struct.d.ts.map +0 -1
- package/dist/log/console_sink.d.ts +0 -4
- package/dist/log/console_sink.d.ts.map +0 -1
- package/dist/log/index.d.ts +0 -3
- package/dist/log/index.d.ts.map +0 -1
- package/dist/log/logger.d.ts +0 -27
- package/dist/log/logger.d.ts.map +0 -1
- package/dist/shared-BXSZnxx4.cjs +0 -1
- package/dist/shared-C678TAPY.js +0 -99
- package/dist/topological_sort-DlRpSrxu.js +0 -391
- package/dist/topological_sort-WAT-VHb-.cjs +0 -1
- package/dist/utils/arrays.d.ts.map +0 -1
- package/dist/utils/constants.d.ts.map +0 -1
- /package/dist/{utils/constants.d.ts → core/ecs/utils/constants.d.cts} +0 -0
- /package/dist/core/store/{__generated__/abi.d.ts → vendored_abi/abi.d.cts} +0 -0
- /package/dist/{core/reactive/array.d.ts → reactive/array.d.cts} +0 -0
- /package/dist/{core/reactive/map.d.ts → reactive/map.d.cts} +0 -0
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
import { ArchetypeView } from './archetype.cjs';
|
|
2
|
+
import { ComponentHandle } from './component.cjs';
|
|
3
|
+
import { EntityID } from './entity.cjs';
|
|
4
|
+
import { FrameTraceSink } from './frame_trace.cjs';
|
|
5
|
+
import { SystemContext } from './query.cjs';
|
|
6
|
+
import { StructuralObserverEvents } from './store.cjs';
|
|
7
|
+
import { SystemAccessDeclaration, SystemDescriptor } from './system.cjs';
|
|
8
|
+
/** What the observer registry needs from `Store` — the typed seam replacing
|
|
9
|
+
* bare underscore-convention reach-through (M1). `Store` implements this; the
|
|
10
|
+
* registry holds only this view, so the compiler bounds what observer dispatch
|
|
11
|
+
* can touch. Underscore names are kept so `Store`'s members stay one
|
|
12
|
+
* declaration (they read as "internal" at every other call site). */
|
|
13
|
+
export interface ObserverHost {
|
|
14
|
+
/** Current change tick — read for onSet baselines. */
|
|
15
|
+
readonly _tick: number;
|
|
16
|
+
/** Dev-only frame-trace sink (`null` when unset; always null in prod). */
|
|
17
|
+
readonly _trace: FrameTraceSink | null;
|
|
18
|
+
/** Sync a component's observation flags (add/remove/disable/enable/dirty). */
|
|
19
|
+
_configureComponentObservation(cid: number, hasAdd: boolean, hasRem: boolean, hasDisable: boolean, hasEnable: boolean, trackDirty: boolean): void;
|
|
20
|
+
/** Drain the per-entity onSet dirty list for `cid` (clears marks). */
|
|
21
|
+
_takeDirty(cid: number): EntityID[];
|
|
22
|
+
/** Visit archetypes whose `cid` column changed since `baseline`, in
|
|
23
|
+
* canonical (creation-id) order. */
|
|
24
|
+
_forEachChangedArchetype(cid: number, baseline: number, cb: (arch: ArchetypeView) => void): void;
|
|
25
|
+
/** Every live entity currently holding `cid` (dispose-on-disable sweep). */
|
|
26
|
+
_collectEntitiesWithComponent(cid: number): EntityID[];
|
|
27
|
+
isAlive(id: EntityID): boolean;
|
|
28
|
+
isDisabled(id: EntityID): boolean;
|
|
29
|
+
hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
|
|
30
|
+
}
|
|
31
|
+
/** Per-entity observer callback (onAdd / onRemove / onDisable / onEnable, and
|
|
32
|
+
* per-entity onSet). */
|
|
33
|
+
export type ObserverFn = (eid: EntityID, ctx: SystemContext) => void;
|
|
34
|
+
/** Archetype-granular onSet callback — fires once per changed archetype-column;
|
|
35
|
+
* the consumer iterates `arch.entityCount` rows itself. */
|
|
36
|
+
export type ArchetypeObserverFn = (arch: ArchetypeView, ctx: SystemContext) => void;
|
|
37
|
+
/** Fields common to every observer registration. `access` drives both the
|
|
38
|
+
* dev-mode `accessCheck` and the access-topological firing order; it is merged
|
|
39
|
+
* over an all-empty declaration, so a caller spells out only what it touches. */
|
|
40
|
+
interface ObserverConfigBase {
|
|
41
|
+
onAdd?: ObserverFn;
|
|
42
|
+
onRemove?: ObserverFn;
|
|
43
|
+
/** Fires when an entity carrying this component is *disabled* (#577) — at the
|
|
44
|
+
* deferred toggle drain, once per net transition (ADR-0023). Mirrors `onRemove`:
|
|
45
|
+
* a disable is a soft remove of the whole mask from default queries. An immediate
|
|
46
|
+
* host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
|
|
47
|
+
onDisable?: ObserverFn;
|
|
48
|
+
/** Fires when an entity carrying this component is *enabled* (#577), symmetric
|
|
49
|
+
* with `onDisable` / `onAdd`. */
|
|
50
|
+
onEnable?: ObserverFn;
|
|
51
|
+
/** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
|
|
52
|
+
* merged over `_INTERNAL_EMPTY_ACCESS`. Undeclared access throws in `DEV`. */
|
|
53
|
+
access?: Partial<SystemAccessDeclaration>;
|
|
54
|
+
/** flecs-style replay of current matches on registration (onAdd only — seeds the
|
|
55
|
+
* *enabled* members; a disabled entity is simply absent, matching default-query
|
|
56
|
+
* semantics), for order-independence of register-vs-spawn. */
|
|
57
|
+
yieldExisting?: boolean;
|
|
58
|
+
/** Diagnostic label for this observer, surfaced by the frame-trace seam
|
|
59
|
+
* (ADR-0030) as the `observer_fired.observer` field — the same role a system's
|
|
60
|
+
* `name` plays. Optional and observe-only: it never touches `stateHash` or
|
|
61
|
+
* dispatch. Defaults to `observer(<component debug name>)` when the component
|
|
62
|
+
* was registered with a name, else `observer(<cid>)`. */
|
|
63
|
+
name?: string;
|
|
64
|
+
}
|
|
65
|
+
/** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
|
|
66
|
+
* from the opt-in per-row dirty list (registering this enables dirty tracking
|
|
67
|
+
* for the component — the ADR-0012 list + dedup bit). */
|
|
68
|
+
export interface EntitySetObserverConfig extends ObserverConfigBase {
|
|
69
|
+
onSet: ObserverFn;
|
|
70
|
+
granularity: "entity";
|
|
71
|
+
}
|
|
72
|
+
/** Archetype-granular onSet (default): `onSet(arch, ctx)` fires once per
|
|
73
|
+
* changed archetype-column (the change tick), in canonical archetype order. Free
|
|
74
|
+
* write path. */
|
|
75
|
+
export interface ArchetypeSetObserverConfig extends ObserverConfigBase {
|
|
76
|
+
onSet: ArchetypeObserverFn;
|
|
77
|
+
granularity?: "archetype";
|
|
78
|
+
}
|
|
79
|
+
/** Structural-only observer — no onSet. */
|
|
80
|
+
export interface StructuralObserverConfig extends ObserverConfigBase {
|
|
81
|
+
onSet?: undefined;
|
|
82
|
+
granularity?: undefined;
|
|
83
|
+
}
|
|
84
|
+
export type ObserverConfig = StructuralObserverConfig | EntitySetObserverConfig | ArchetypeSetObserverConfig;
|
|
85
|
+
export interface ObserverHandle {
|
|
86
|
+
dispose(): void;
|
|
87
|
+
/** `using h = ecs.observe(C, {...})` — explicit-resource-management sugar
|
|
88
|
+
* over {@link dispose} (TC39 `Symbol.dispose`). */
|
|
89
|
+
[Symbol.dispose](): void;
|
|
90
|
+
}
|
|
91
|
+
/**
|
|
92
|
+
* Registry of component observers. Owned by `ECS`; the `Store` calls back into
|
|
93
|
+
* `dispatchStructural` between fixed-point rounds during `flushStructural`,
|
|
94
|
+
* and `ECS.update` calls `dispatchSet` at the post-update detection point.
|
|
95
|
+
*/
|
|
96
|
+
export declare class ObserverRegistry {
|
|
97
|
+
private readonly store;
|
|
98
|
+
private readonly ctx;
|
|
99
|
+
private readonly entries;
|
|
100
|
+
/** ComponentID → its observers (structural + onSet). */
|
|
101
|
+
private readonly byCid;
|
|
102
|
+
/** Cached access-topological order; invalidated on register / dispose. */
|
|
103
|
+
private _topo;
|
|
104
|
+
private readonly _addBuckets;
|
|
105
|
+
private readonly _remBuckets;
|
|
106
|
+
private readonly _disBuckets;
|
|
107
|
+
private readonly _enaBuckets;
|
|
108
|
+
private readonly _radixOut;
|
|
109
|
+
private readonly _radixC0;
|
|
110
|
+
private readonly _radixC1;
|
|
111
|
+
private readonly _setDrainCache;
|
|
112
|
+
constructor(store: ObserverHost, ctx: SystemContext);
|
|
113
|
+
get count(): number;
|
|
114
|
+
/** The synthesized `SystemDescriptor`s of every registered observer, in
|
|
115
|
+
* registration order (`dispose()` splices entries out, so none are stale).
|
|
116
|
+
* Fed into the `startup()` archetype-prewarm closure so an observer's declared
|
|
117
|
+
* `spawns` / `transitions` create their target archetypes eagerly, exactly as a
|
|
118
|
+
* system's do (#768). Without this an observer-spawned/-transitioned archetype
|
|
119
|
+
* first-touches lazily mid-tick — the one asymmetry left in the otherwise
|
|
120
|
+
* uniform "no lazy archetypes" prewarm. */
|
|
121
|
+
descriptors(): SystemDescriptor[];
|
|
122
|
+
register(def: ComponentHandle, config: ObserverConfig): ObserverHandle;
|
|
123
|
+
private _dispose;
|
|
124
|
+
/** Recompute the component's hot-path observation flags from its live
|
|
125
|
+
* observers and push them to the store (which owns the flags + fast-path
|
|
126
|
+
* counters). */
|
|
127
|
+
private _reconfigureComponent;
|
|
128
|
+
private getTopo;
|
|
129
|
+
/**
|
|
130
|
+
* Fire onAdd / onRemove / onDisable / onEnable for one fixed-point round's
|
|
131
|
+
* effective events, in canonical order: access-topological across observers,
|
|
132
|
+
* entity-id order (radix) within each observer. Called by
|
|
133
|
+
* `Store.flushStructural` after the batch commits; observer callbacks may
|
|
134
|
+
* enqueue further structural ops (or toggles) onto the deferred buffers (the
|
|
135
|
+
* store loops until quiescent).
|
|
136
|
+
*
|
|
137
|
+
* The events arrive as flat `(comp, eid)` parallel arrays collected during the
|
|
138
|
+
* flush; we bucket by component once (O(K)), then walk observers in topo order
|
|
139
|
+
* so a producer's writes are visible to a consumer (glitch-free). A round
|
|
140
|
+
* carries either structural (add/rem) OR toggle (dis/ena) events, never both —
|
|
141
|
+
* toggles drain only once add/remove/destroy are quiescent (`flushStructural`)
|
|
142
|
+
* — but we bucket all four uniformly; the empty pairs are no-ops. Within an
|
|
143
|
+
* observer the fire order is remove, add, disable, enable (the "leaving" edges
|
|
144
|
+
* before the "entering" edges).
|
|
145
|
+
*/
|
|
146
|
+
dispatchStructural(ev: StructuralObserverEvents): void;
|
|
147
|
+
/** Radix-sort `eids` by entity index (canonical within-observer order), then
|
|
148
|
+
* fire `fn` per entity under the observer's access scope. */
|
|
149
|
+
private _fireEach;
|
|
150
|
+
private _bucket;
|
|
151
|
+
private _clearBuckets;
|
|
152
|
+
/**
|
|
153
|
+
* Fire onSet observers for the current tick, in canonical order. Per-entity
|
|
154
|
+
* onSet drains the opt-in dirty list (once per changed entity); archetype-
|
|
155
|
+
* granular onSet scans the change tick (once per changed archetype-column).
|
|
156
|
+
* Called by `ECS.update` after all phases, with `tick === store._tick`.
|
|
157
|
+
*/
|
|
158
|
+
dispatchSet(tick: number): void;
|
|
159
|
+
private _dispatchSetEntity;
|
|
160
|
+
private _dispatchSetArch;
|
|
161
|
+
private _yieldExisting;
|
|
162
|
+
}
|
|
163
|
+
/**
|
|
164
|
+
* O(K) LSD radix sort of entity ids by their 20-bit dense index (two 10-bit
|
|
165
|
+
* passes), in place. This is the canonical within-observer order — *never* a
|
|
166
|
+
* comparator `Array.sort`, which the bench measured at 2–4× the entire flush
|
|
167
|
+
* (`observer_dispatch_probe.ts`). Distinct live entities have distinct indices,
|
|
168
|
+
* so index order is a total canonical order. `out` is scratch (grown to length);
|
|
169
|
+
* `c0` / `c1` are 1024-entry histograms (reused).
|
|
170
|
+
*/
|
|
171
|
+
export declare function radixSortByIndex(eids: number[], out: number[], c0: Int32Array, c1: Int32Array): void;
|
|
172
|
+
export {};
|
|
173
|
+
//# sourceMappingURL=observer.d.ts.map
|
|
@@ -1,9 +1,33 @@
|
|
|
1
|
-
import { ArchetypeView } from './archetype';
|
|
2
|
-
import {
|
|
3
|
-
import { EntityID } from './entity';
|
|
4
|
-
import {
|
|
5
|
-
import {
|
|
6
|
-
import {
|
|
1
|
+
import { ArchetypeView } from './archetype.js';
|
|
2
|
+
import { ComponentHandle } from './component.js';
|
|
3
|
+
import { EntityID } from './entity.js';
|
|
4
|
+
import { FrameTraceSink } from './frame_trace.js';
|
|
5
|
+
import { SystemContext } from './query.js';
|
|
6
|
+
import { StructuralObserverEvents } from './store.js';
|
|
7
|
+
import { SystemAccessDeclaration, SystemDescriptor } from './system.js';
|
|
8
|
+
/** What the observer registry needs from `Store` — the typed seam replacing
|
|
9
|
+
* bare underscore-convention reach-through (M1). `Store` implements this; the
|
|
10
|
+
* registry holds only this view, so the compiler bounds what observer dispatch
|
|
11
|
+
* can touch. Underscore names are kept so `Store`'s members stay one
|
|
12
|
+
* declaration (they read as "internal" at every other call site). */
|
|
13
|
+
export interface ObserverHost {
|
|
14
|
+
/** Current change tick — read for onSet baselines. */
|
|
15
|
+
readonly _tick: number;
|
|
16
|
+
/** Dev-only frame-trace sink (`null` when unset; always null in prod). */
|
|
17
|
+
readonly _trace: FrameTraceSink | null;
|
|
18
|
+
/** Sync a component's observation flags (add/remove/disable/enable/dirty). */
|
|
19
|
+
_configureComponentObservation(cid: number, hasAdd: boolean, hasRem: boolean, hasDisable: boolean, hasEnable: boolean, trackDirty: boolean): void;
|
|
20
|
+
/** Drain the per-entity onSet dirty list for `cid` (clears marks). */
|
|
21
|
+
_takeDirty(cid: number): EntityID[];
|
|
22
|
+
/** Visit archetypes whose `cid` column changed since `baseline`, in
|
|
23
|
+
* canonical (creation-id) order. */
|
|
24
|
+
_forEachChangedArchetype(cid: number, baseline: number, cb: (arch: ArchetypeView) => void): void;
|
|
25
|
+
/** Every live entity currently holding `cid` (dispose-on-disable sweep). */
|
|
26
|
+
_collectEntitiesWithComponent(cid: number): EntityID[];
|
|
27
|
+
isAlive(id: EntityID): boolean;
|
|
28
|
+
isDisabled(id: EntityID): boolean;
|
|
29
|
+
hasComponent(entityId: EntityID, def: ComponentHandle): boolean;
|
|
30
|
+
}
|
|
7
31
|
/** Per-entity observer callback (onAdd / onRemove / onDisable / onEnable, and
|
|
8
32
|
* per-entity onSet). */
|
|
9
33
|
export type ObserverFn = (eid: EntityID, ctx: SystemContext) => void;
|
|
@@ -19,18 +43,24 @@ interface ObserverConfigBase {
|
|
|
19
43
|
/** Fires when an entity carrying this component is *disabled* (#577) — at the
|
|
20
44
|
* deferred toggle drain, once per net transition (ADR-0023). Mirrors `onRemove`:
|
|
21
45
|
* a disable is a soft remove of the whole mask from default queries. An immediate
|
|
22
|
-
* host-side `
|
|
46
|
+
* host-side `ecs.disable()` does not fire (like immediate `addComponent`). */
|
|
23
47
|
onDisable?: ObserverFn;
|
|
24
48
|
/** Fires when an entity carrying this component is *enabled* (#577), symmetric
|
|
25
49
|
* with `onDisable` / `onAdd`. */
|
|
26
50
|
onEnable?: ObserverFn;
|
|
27
51
|
/** Access surface the callbacks touch (reads / writes / spawns / …). Partial:
|
|
28
|
-
* merged over `_INTERNAL_EMPTY_ACCESS`. Undeclared access throws in `
|
|
52
|
+
* merged over `_INTERNAL_EMPTY_ACCESS`. Undeclared access throws in `DEV`. */
|
|
29
53
|
access?: Partial<SystemAccessDeclaration>;
|
|
30
54
|
/** flecs-style replay of current matches on registration (onAdd only — seeds the
|
|
31
55
|
* *enabled* members; a disabled entity is simply absent, matching default-query
|
|
32
56
|
* semantics), for order-independence of register-vs-spawn. */
|
|
33
57
|
yieldExisting?: boolean;
|
|
58
|
+
/** Diagnostic label for this observer, surfaced by the frame-trace seam
|
|
59
|
+
* (ADR-0030) as the `observer_fired.observer` field — the same role a system's
|
|
60
|
+
* `name` plays. Optional and observe-only: it never touches `stateHash` or
|
|
61
|
+
* dispatch. Defaults to `observer(<component debug name>)` when the component
|
|
62
|
+
* was registered with a name, else `observer(<cid>)`. */
|
|
63
|
+
name?: string;
|
|
34
64
|
}
|
|
35
65
|
/** Per-entity onSet: `onSet(eid, ctx)` fires once per changed entity, drained
|
|
36
66
|
* from the opt-in per-row dirty list (registering this enables dirty tracking
|
|
@@ -52,10 +82,11 @@ export interface StructuralObserverConfig extends ObserverConfigBase {
|
|
|
52
82
|
granularity?: undefined;
|
|
53
83
|
}
|
|
54
84
|
export type ObserverConfig = StructuralObserverConfig | EntitySetObserverConfig | ArchetypeSetObserverConfig;
|
|
55
|
-
/** Handle returned by `world.observe(...)`. `dispose()` unregisters; safe to
|
|
56
|
-
* call more than once. */
|
|
57
85
|
export interface ObserverHandle {
|
|
58
86
|
dispose(): void;
|
|
87
|
+
/** `using h = ecs.observe(C, {...})` — explicit-resource-management sugar
|
|
88
|
+
* over {@link dispose} (TC39 `Symbol.dispose`). */
|
|
89
|
+
[Symbol.dispose](): void;
|
|
59
90
|
}
|
|
60
91
|
/**
|
|
61
92
|
* Registry of component observers. Owned by `ECS`; the `Store` calls back into
|
|
@@ -78,7 +109,7 @@ export declare class ObserverRegistry {
|
|
|
78
109
|
private readonly _radixC0;
|
|
79
110
|
private readonly _radixC1;
|
|
80
111
|
private readonly _setDrainCache;
|
|
81
|
-
constructor(store:
|
|
112
|
+
constructor(store: ObserverHost, ctx: SystemContext);
|
|
82
113
|
get count(): number;
|
|
83
114
|
/** The synthesized `SystemDescriptor`s of every registered observer, in
|
|
84
115
|
* registration order (`dispose()` splices entries out, so none are stale).
|
|
@@ -88,7 +119,7 @@ export declare class ObserverRegistry {
|
|
|
88
119
|
* first-touches lazily mid-tick — the one asymmetry left in the otherwise
|
|
89
120
|
* uniform "no lazy archetypes" prewarm. */
|
|
90
121
|
descriptors(): SystemDescriptor[];
|
|
91
|
-
register(def:
|
|
122
|
+
register(def: ComponentHandle, config: ObserverConfig): ObserverHandle;
|
|
92
123
|
private _dispose;
|
|
93
124
|
/** Recompute the component's hot-path observation flags from its live
|
|
94
125
|
* observers and push them to the store (which owns the flags + fast-path
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/observer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAkDK;AAGL,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,
|
|
1
|
+
{"version":3,"file":"observer.d.ts","sourceRoot":"","sources":["../../../src/core/ecs/observer.ts"],"names":[],"mappings":"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"}
|