feat: implement core ECS engine with RxJS observability

Initial implementation of an Entity-Component-System (ECS) featuring:
- Sparse set-based component storage for efficient access.
- Entity lifecycle management with generation-based recycling.
- Reactive query system using RxJS for change tracking.
- Batched event flushing to support frame-based updates.
- Type-safe component definitions via TypeScript inference.
This commit is contained in:
2026-05-31 15:45:20 +08:00
commit 4ede2d7f3b
14 changed files with 2427 additions and 0 deletions
+33
View File
@@ -0,0 +1,33 @@
// ── Component ─────────────────────────────────────────
/**
* A component definition carries both the type shape (via TypeScript inference)
* and a unique key used for storage lookup.
*
* @example
* ```ts
* const Position = defineComponent({ x: 0, y: 0 });
* type Position = typeof Position.type;
* ```
*/
export interface ComponentDef<T extends Record<string, any>> {
/** Unique symbol used as the storage key. */
readonly _key: symbol;
/** Default values applied when a component is first added. */
readonly defaults: T;
/** Phantom type for inference. */
readonly type: T;
}
/**
* Define a component type. The argument provides both default values and the
* TypeScript shape.
*/
export function defineComponent<T extends Record<string, any>>(
defaults: T
): ComponentDef<T> {
return {
_key: Symbol(),
defaults: { ...defaults },
type: undefined as unknown as T, // phantom; never read at runtime
};
}