@funderforge/ecs 0.1.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/LICENSE +21 -0
- package/README.md +412 -0
- package/dist/component.d.ts +135 -0
- package/dist/component.d.ts.map +1 -0
- package/dist/component.js +176 -0
- package/dist/component.js.map +1 -0
- package/dist/entity.d.ts +222 -0
- package/dist/entity.d.ts.map +1 -0
- package/dist/entity.js +418 -0
- package/dist/entity.js.map +1 -0
- package/dist/index.d.ts +3 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +3 -0
- package/dist/index.js.map +1 -0
- package/package.json +52 -0
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Abstract base class for components that can be attached to entities.
|
|
3
|
+
* Components provide functionality to entities and can respond to lifecycle events through virtual methods.
|
|
4
|
+
*
|
|
5
|
+
* Key features:
|
|
6
|
+
* - Belongs to exactly one entity
|
|
7
|
+
* - Method-based architecture with `onTick` and `onEnabledChanged` virtual methods
|
|
8
|
+
* - Enabled/disabled state that respects entity state
|
|
9
|
+
* - Automatic registration with the entity upon construction
|
|
10
|
+
*
|
|
11
|
+
* @example
|
|
12
|
+
* ```typescript
|
|
13
|
+
* class TransformComponent extends Component {
|
|
14
|
+
* x = 0;
|
|
15
|
+
* y = 0;
|
|
16
|
+
*
|
|
17
|
+
* protected onTick(deltaTime: number): void {
|
|
18
|
+
* // Update position based on deltaTime
|
|
19
|
+
* }
|
|
20
|
+
* }
|
|
21
|
+
*
|
|
22
|
+
* const entity = new Entity({ id: 'player' });
|
|
23
|
+
* const transform = new TransformComponent(entity);
|
|
24
|
+
* ```
|
|
25
|
+
*/
|
|
26
|
+
export default class Component {
|
|
27
|
+
/** The entity this component belongs to. Set automatically during construction and cannot be changed. */
|
|
28
|
+
entity;
|
|
29
|
+
_enabledSelf;
|
|
30
|
+
/**
|
|
31
|
+
* Whether to add this component to the entity's type map for optimized lookups.
|
|
32
|
+
*
|
|
33
|
+
* - `false` (default): Component is NOT added to the type map. Lookups will fall back to iteration, which is slower
|
|
34
|
+
* but avoids the overhead of maintaining the map for components that are rarely looked up by type.
|
|
35
|
+
* - `true`: Component is added to the type map, enabling fast O(1) lookups via `entity.getComponentByType()`.
|
|
36
|
+
*
|
|
37
|
+
* @default false
|
|
38
|
+
*/
|
|
39
|
+
precacheTypeLookup;
|
|
40
|
+
/**
|
|
41
|
+
* Creates a new Component instance and attaches it to the specified entity.
|
|
42
|
+
* The component is automatically registered with the entity and cannot be moved to another entity.
|
|
43
|
+
*
|
|
44
|
+
* @param entity - The entity this component belongs to. Required and cannot be changed after construction.
|
|
45
|
+
* @param preset - Optional configuration object for the component.
|
|
46
|
+
* @param preset.enabledSelf - Whether the component is enabled by default. Defaults to `true`.
|
|
47
|
+
* @param preset.precacheTypeLookup - Whether to add this component to the entity's type map for optimized lookups.
|
|
48
|
+
* Defaults to `false` (component is NOT added to map, uses slower iteration-based lookups). Set to `true` to add
|
|
49
|
+
* the component to the map for fast O(1) lookups via `entity.getComponentByType()`.
|
|
50
|
+
*
|
|
51
|
+
* @example
|
|
52
|
+
* ```typescript
|
|
53
|
+
* class MyComponent extends Component {
|
|
54
|
+
* constructor(entity: Entity) {
|
|
55
|
+
* super(entity, { enabledSelf: true });
|
|
56
|
+
* }
|
|
57
|
+
* }
|
|
58
|
+
*
|
|
59
|
+
* const entity = new Entity({ id: 'entity' });
|
|
60
|
+
* const component = new MyComponent(entity);
|
|
61
|
+
*
|
|
62
|
+
* // Component is NOT added to type map by default (slower lookups)
|
|
63
|
+
* const found = entity.getComponentByType(MyComponent);
|
|
64
|
+
*
|
|
65
|
+
* // Add to type map for components frequently looked up by type (fast lookups)
|
|
66
|
+
* const transform = new TransformComponent(entity, { precacheTypeLookup: true });
|
|
67
|
+
* const foundTransform = entity.getComponentByType(TransformComponent); // Fast O(1) lookup
|
|
68
|
+
* ```
|
|
69
|
+
*/
|
|
70
|
+
constructor(entity, preset = {}) {
|
|
71
|
+
this._enabledSelf = preset.enabledSelf ?? true;
|
|
72
|
+
this.precacheTypeLookup = preset.precacheTypeLookup ?? false;
|
|
73
|
+
this.entity = entity;
|
|
74
|
+
// biome-ignore lint/suspicious/noExplicitAny: Override private guard
|
|
75
|
+
entity._components.push(this);
|
|
76
|
+
// Update component type map for optimized lookups
|
|
77
|
+
if (this.precacheTypeLookup) {
|
|
78
|
+
// biome-ignore lint/suspicious/noExplicitAny: Override private guard
|
|
79
|
+
const map = entity._componentMap;
|
|
80
|
+
const ctor = this.constructor;
|
|
81
|
+
// make sure the component is not already in the map
|
|
82
|
+
if (!map.has(ctor)) {
|
|
83
|
+
map.set(ctor, this);
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Gets whether this component itself is enabled, independent of its entity's state.
|
|
89
|
+
* @returns `true` if this component is enabled, `false` otherwise.
|
|
90
|
+
*/
|
|
91
|
+
get enabledSelf() {
|
|
92
|
+
return this._enabledSelf;
|
|
93
|
+
}
|
|
94
|
+
/**
|
|
95
|
+
* Sets whether this component itself is enabled. When the effective enabled state changes (considering both this value and the entity's enabled state),
|
|
96
|
+
* the `onEnabledChanged` method will be called.
|
|
97
|
+
* @param value - `true` to enable this component, `false` to disable it.
|
|
98
|
+
*/
|
|
99
|
+
set enabledSelf(value) {
|
|
100
|
+
if (value === this._enabledSelf)
|
|
101
|
+
return;
|
|
102
|
+
const oldEnabled = this.enabled;
|
|
103
|
+
this._enabledSelf = value;
|
|
104
|
+
const enabled = this.enabled;
|
|
105
|
+
if (enabled !== oldEnabled) {
|
|
106
|
+
this.onEnabledChanged(enabled);
|
|
107
|
+
}
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Virtual method called when the component is ticked during the entity update cycle.
|
|
111
|
+
* Override this method in derived classes to implement tick-based logic.
|
|
112
|
+
* @param deltaTime - The time elapsed since the last tick in milliseconds.
|
|
113
|
+
*/
|
|
114
|
+
onTick(_deltaTime) { }
|
|
115
|
+
/**
|
|
116
|
+
* Virtual method called when the component's effective enabled state changes.
|
|
117
|
+
* Override this method in derived classes to respond to enabled state changes.
|
|
118
|
+
* @param newValue - The new effective enabled state of the component.
|
|
119
|
+
*/
|
|
120
|
+
onEnabledChanged(_newValue) { }
|
|
121
|
+
/**
|
|
122
|
+
* Gets the effective enabled state of this component, considering both its own `enabledSelf` value and its entity's enabled state.
|
|
123
|
+
* @returns `true` only if both this component's `enabledSelf` is `true` and its entity's `enabled` is `true`.
|
|
124
|
+
*/
|
|
125
|
+
get enabled() {
|
|
126
|
+
return this._enabledSelf && this.entity.enabled;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Destroys this component, removing it from its entity and marking it as "dead".
|
|
130
|
+
*
|
|
131
|
+
* After calling `destroy()`, the component is permanently removed from the entity's component list
|
|
132
|
+
* and its entity reference is cleared. The component should be considered "dead" and must not be
|
|
133
|
+
* accessed or used in any way after destruction.
|
|
134
|
+
*
|
|
135
|
+
* **CRITICAL**: After calling `destroy()`, you must:
|
|
136
|
+
* - Remove all references to this component from your code
|
|
137
|
+
* - Never access the component's properties or methods again
|
|
138
|
+
* - Never call any methods on the component
|
|
139
|
+
*
|
|
140
|
+
* Accessing a destroyed component will result in undefined behavior. In non-production builds,
|
|
141
|
+
* the component object is frozen to help detect misuse.
|
|
142
|
+
*
|
|
143
|
+
* @example
|
|
144
|
+
* ```typescript
|
|
145
|
+
* const component = new MyComponent(entity);
|
|
146
|
+
*
|
|
147
|
+
* // Use the component...
|
|
148
|
+
* component.doSomething();
|
|
149
|
+
*
|
|
150
|
+
* // Destroy the component when no longer needed
|
|
151
|
+
* component.destroy();
|
|
152
|
+
*
|
|
153
|
+
* // IMPORTANT: Remove all references and never access it again
|
|
154
|
+
* // component = null; // or let it go out of scope
|
|
155
|
+
* // DO NOT: component.doSomething(); // ❌ WRONG - component is dead
|
|
156
|
+
* ```
|
|
157
|
+
*/
|
|
158
|
+
destroy() {
|
|
159
|
+
// biome-ignore lint/suspicious/noExplicitAny: override private guard
|
|
160
|
+
const entity = this.entity;
|
|
161
|
+
if (entity === undefined)
|
|
162
|
+
return;
|
|
163
|
+
const idx = entity._components.indexOf(this);
|
|
164
|
+
entity._components.splice(idx, 1);
|
|
165
|
+
const map = entity._componentMap;
|
|
166
|
+
if (map.get(this.constructor) === this) {
|
|
167
|
+
map.delete(this.constructor);
|
|
168
|
+
}
|
|
169
|
+
// biome-ignore lint/suspicious/noExplicitAny: override private guard
|
|
170
|
+
this.entity = undefined;
|
|
171
|
+
if (process.env.NODE_ENV !== "production") {
|
|
172
|
+
Object.freeze(this); // make future misuse obvious
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
//# sourceMappingURL=component.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"component.js","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,OAAO,OAAgB,SAAS;IACtC,yGAAyG;IAChG,MAAM,CAAU;IACjB,YAAY,CAAU;IAE9B;;;;;;;;OAQG;IACM,kBAAkB,CAAU;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,YACC,MAAc,EACd,SAAkE,EAAE;QAEpE,IAAI,CAAC,YAAY,GAAG,MAAM,CAAC,WAAW,IAAI,IAAI,CAAC;QAC/C,IAAI,CAAC,kBAAkB,GAAG,MAAM,CAAC,kBAAkB,IAAI,KAAK,CAAC;QAC7D,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,qEAAqE;QACpE,MAAc,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvC,kDAAkD;QAClD,IAAI,IAAI,CAAC,kBAAkB,EAAE,CAAC;YAC7B,qEAAqE;YACrE,MAAM,GAAG,GAAI,MAAc,CAAC,aAAa,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,WAAW,CAAC;YAE9B,oDAAoD;YACpD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;gBACpB,GAAG,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YACrB,CAAC;QACF,CAAC;IACF,CAAC;IAED;;;OAGG;IACH,IAAI,WAAW;QACd,OAAO,IAAI,CAAC,YAAY,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,IAAI,WAAW,CAAC,KAAc;QAC7B,IAAI,KAAK,KAAK,IAAI,CAAC,YAAY;YAAE,OAAO;QACxC,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC;QAChC,IAAI,CAAC,YAAY,GAAG,KAAK,CAAC;QAC1B,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,OAAO,KAAK,UAAU,EAAE,CAAC;YAC5B,IAAI,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;QAChC,CAAC;IACF,CAAC;IAED;;;;OAIG;IACO,MAAM,CAAC,UAAkB,IAAS,CAAC;IAE7C;;;;OAIG;IACO,gBAAgB,CAAC,SAAkB,IAAS,CAAC;IAEvD;;;OAGG;IACH,IAAI,OAAO;QACV,OAAO,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC;IACjD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO;QACN,qEAAqE;QACrE,MAAM,MAAM,GAAQ,IAAI,CAAC,MAAM,CAAC;QAChC,IAAI,MAAM,KAAK,SAAS;YAAE,OAAO;QAEjC,MAAM,GAAG,GAAG,MAAM,CAAC,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7C,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QAElC,MAAM,GAAG,GAAG,MAAM,CAAC,aAAa,CAAC;QACjC,IAAI,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,WAAW,CAAC,KAAK,IAAI,EAAE,CAAC;YACxC,GAAG,CAAC,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAC9B,CAAC;QAED,qEAAqE;QACpE,IAAY,CAAC,MAAM,GAAG,SAAS,CAAC;QAEjC,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC3C,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,6BAA6B;QACnD,CAAC;IACF,CAAC;CACD"}
|
package/dist/entity.d.ts
ADDED
|
@@ -0,0 +1,222 @@
|
|
|
1
|
+
import type Component from "./component";
|
|
2
|
+
/**
|
|
3
|
+
* Represents an entity in a hierarchical tree structure that can contain child entities and components.
|
|
4
|
+
* Entities form the backbone of the component framework, allowing you to build flexible hierarchies
|
|
5
|
+
* where each entity can have multiple components attached to it.
|
|
6
|
+
*
|
|
7
|
+
* Key features:
|
|
8
|
+
* - Hierarchical parent-child relationships
|
|
9
|
+
* - Cascading enabled/disabled state management with caching
|
|
10
|
+
* - Component attachment and management
|
|
11
|
+
* - Efficient traversal of entities and components
|
|
12
|
+
* - Method-based architecture through component virtual methods
|
|
13
|
+
*
|
|
14
|
+
* @example
|
|
15
|
+
* ```typescript
|
|
16
|
+
* const root = new Entity({ id: 'root' });
|
|
17
|
+
* const child = new Entity({ id: 'child', parent: root });
|
|
18
|
+
* root.addChild(child);
|
|
19
|
+
* ```
|
|
20
|
+
*/
|
|
21
|
+
export default class Entity {
|
|
22
|
+
private _children;
|
|
23
|
+
private _parent;
|
|
24
|
+
private _enabledSelf;
|
|
25
|
+
private _enabledCache;
|
|
26
|
+
/** Unique identifier for this entity. Can be a string or number. If not provided in constructor, an auto-incrementing number is assigned. */
|
|
27
|
+
readonly id: string | number;
|
|
28
|
+
private static _idCounter;
|
|
29
|
+
private readonly _components;
|
|
30
|
+
private readonly _componentMap;
|
|
31
|
+
/**
|
|
32
|
+
* Creates a new Entity instance.
|
|
33
|
+
* @param preset - Optional configuration object for the entity.
|
|
34
|
+
* @param preset.id - Optional unique identifier. If not provided, an auto-incrementing number is assigned.
|
|
35
|
+
* @param preset.enabledSelf - Whether the entity is enabled by default. Defaults to `true`.
|
|
36
|
+
* @param preset.parent - Optional parent entity. If provided, this entity will be added as a child of the parent.
|
|
37
|
+
*
|
|
38
|
+
* @example
|
|
39
|
+
* ```typescript
|
|
40
|
+
* // Create a root entity with a custom ID
|
|
41
|
+
* const root = new Entity({ id: 'scene' });
|
|
42
|
+
*
|
|
43
|
+
* // Create a child entity with a parent
|
|
44
|
+
* const child = new Entity({ id: 'player', parent: root, enabledSelf: true });
|
|
45
|
+
*
|
|
46
|
+
* // Create an entity that will be auto-assigned an ID
|
|
47
|
+
* const entity = new Entity();
|
|
48
|
+
* ```
|
|
49
|
+
*/
|
|
50
|
+
constructor(preset?: {
|
|
51
|
+
id?: string;
|
|
52
|
+
enabledSelf?: boolean;
|
|
53
|
+
parent?: Entity;
|
|
54
|
+
});
|
|
55
|
+
/**
|
|
56
|
+
* Gets whether this entity itself is enabled, independent of its parent's state.
|
|
57
|
+
* @returns `true` if this entity is enabled, `false` otherwise.
|
|
58
|
+
*/
|
|
59
|
+
get enabledSelf(): boolean;
|
|
60
|
+
/**
|
|
61
|
+
* Sets whether this entity itself is enabled. When set to `false`, this entity and all its descendants become disabled.
|
|
62
|
+
* Invalidates the enabled cache for this entity and all descendants, and calls `onEnabledChanged` on affected components.
|
|
63
|
+
* @param value - `true` to enable this entity, `false` to disable it.
|
|
64
|
+
*/
|
|
65
|
+
set enabledSelf(value: boolean);
|
|
66
|
+
/**
|
|
67
|
+
* Gets the effective enabled state of this entity, considering both its own `enabledSelf` value and all parent entities' enabled states.
|
|
68
|
+
* The result is cached for performance and automatically invalidated when necessary.
|
|
69
|
+
* @returns `true` only if this entity's `enabledSelf` is `true` and all parent entities (up to the root) have `enabledSelf` set to `true`.
|
|
70
|
+
*/
|
|
71
|
+
get enabled(): boolean;
|
|
72
|
+
/**
|
|
73
|
+
* Invalidates the enabled cache for this entity and all its descendants.
|
|
74
|
+
* This is called when enabledSelf changes or when parent changes.
|
|
75
|
+
* Uses an iterative approach with a stack to avoid potential stack overflow for deep trees.
|
|
76
|
+
*/
|
|
77
|
+
private _invalidateEnabledCache;
|
|
78
|
+
/**
|
|
79
|
+
* Adds a child entity to this entity. If the child already has a parent, it will be removed from its previous parent first.
|
|
80
|
+
* @param child - The entity to add as a child.
|
|
81
|
+
*/
|
|
82
|
+
addChild(child: Entity): void;
|
|
83
|
+
/**
|
|
84
|
+
* Removes a child entity by its index in the children array. The removed child's parent will be set to `null`.
|
|
85
|
+
* @param index - The index of the child to remove.
|
|
86
|
+
*/
|
|
87
|
+
removeChildByIndex(index: number): void;
|
|
88
|
+
/**
|
|
89
|
+
* Removes a child entity. The removed child's parent will be set to `null`.
|
|
90
|
+
* @param child - The child entity to remove.
|
|
91
|
+
*/
|
|
92
|
+
removeChild(child: Entity): void;
|
|
93
|
+
/**
|
|
94
|
+
* Gets the number of direct child entities.
|
|
95
|
+
* @returns The number of children.
|
|
96
|
+
*/
|
|
97
|
+
childrenLength(): number;
|
|
98
|
+
/**
|
|
99
|
+
* Gets a child entity by its index in the children array.
|
|
100
|
+
* @template T - The type of entity to return. Defaults to `Entity`.
|
|
101
|
+
* @param index - The index of the child to retrieve.
|
|
102
|
+
* @returns The child entity at the specified index, or `undefined` if the index is out of bounds.
|
|
103
|
+
*/
|
|
104
|
+
childByIdx<T extends Entity = Entity>(index: number): T;
|
|
105
|
+
/**
|
|
106
|
+
* Finds the first child entity that matches the given predicate.
|
|
107
|
+
* @template T - The type of entity to return. Defaults to `Entity`.
|
|
108
|
+
* @param predicate - A function that returns `true` for the child to find.
|
|
109
|
+
* @returns The first matching child entity, or `undefined` if no match is found.
|
|
110
|
+
*/
|
|
111
|
+
getChild<T extends Entity = Entity>(predicate: (child: Entity) => boolean): T;
|
|
112
|
+
/**
|
|
113
|
+
* Gets the index of a child entity in the children array.
|
|
114
|
+
* @param child - The child entity to find the index of.
|
|
115
|
+
* @returns The index of the child, or `-1` if not found.
|
|
116
|
+
*/
|
|
117
|
+
indexOfChild(child: Entity): number;
|
|
118
|
+
/**
|
|
119
|
+
* Gets all child entities that match the given filter function.
|
|
120
|
+
* @template T - The type of entity to return. Defaults to `Entity`.
|
|
121
|
+
* @param filter - A function that returns `true` for children to include.
|
|
122
|
+
* @returns An array of matching child entities.
|
|
123
|
+
*/
|
|
124
|
+
getChildren<T extends Entity = Entity>(filter: (child: Entity) => boolean): T[];
|
|
125
|
+
/**
|
|
126
|
+
* Traverses the children of this entity and all its descendants using a depth-first approach.
|
|
127
|
+
* @template T - The type of entity to yield. Defaults to `Entity`.
|
|
128
|
+
* @param predicate - Optional predicate to filter the children. If provided and returns `true`, the child will be yielded and its descendants will be traversed. If omitted, all children are traversed.
|
|
129
|
+
* @returns A generator that yields entities in the traversal order.
|
|
130
|
+
*/
|
|
131
|
+
traverseChildren<T extends Entity = Entity>(predicate?: (child: Entity) => boolean): Generator<T>;
|
|
132
|
+
/**
|
|
133
|
+
* Traverses the components of this entity and all its descendants using a pre-order depth-first approach.
|
|
134
|
+
* Only traverses enabled entities. Components are yielded before their entity's children.
|
|
135
|
+
* @template T - The type of component to yield. Defaults to `Component`.
|
|
136
|
+
* @param predicate - Optional predicate to filter the components. If provided and returns `true`, the component will be yielded. If omitted, all components are traversed.
|
|
137
|
+
* @returns A generator that yields components in the traversal order.
|
|
138
|
+
*/
|
|
139
|
+
traverseComponents<T extends Component = Component>(predicate?: (component: Component) => boolean): Generator<T>;
|
|
140
|
+
/**
|
|
141
|
+
* Sets or clears the parent entity. If setting a new parent, this entity will be removed from its previous parent and added to the new one.
|
|
142
|
+
* Invalidates the enabled cache when the parent changes.
|
|
143
|
+
* @param parent - The new parent entity, or `null` to remove the parent.
|
|
144
|
+
*/
|
|
145
|
+
setParent(parent: Entity | null): void;
|
|
146
|
+
/**
|
|
147
|
+
* Gets the parent entity in the hierarchy.
|
|
148
|
+
* @returns The parent entity, or `null` if this entity has no parent (i.e., it's a root entity).
|
|
149
|
+
*/
|
|
150
|
+
get parent(): Entity | null;
|
|
151
|
+
/**
|
|
152
|
+
* Gets the depth level of this entity in the hierarchy. Root entities have a level of 0.
|
|
153
|
+
* @returns The number of ancestors (parent entities) in the hierarchy chain.
|
|
154
|
+
*/
|
|
155
|
+
hierarchyLevel(): number;
|
|
156
|
+
/**
|
|
157
|
+
* Gets the number of components attached to this entity.
|
|
158
|
+
* @returns The number of components.
|
|
159
|
+
*/
|
|
160
|
+
componentsLength(): number;
|
|
161
|
+
/**
|
|
162
|
+
* Gets a component by its index in the components array.
|
|
163
|
+
* @template T - The type of component to return. Defaults to `Component`.
|
|
164
|
+
* @param index - The index of the component to retrieve.
|
|
165
|
+
* @returns The component at the specified index, or `undefined` if the index is out of bounds.
|
|
166
|
+
*/
|
|
167
|
+
componentByIdx<T extends Component = Component>(index: number): T;
|
|
168
|
+
/**
|
|
169
|
+
* Finds the first component that matches the given predicate.
|
|
170
|
+
* @template T - The type of component to return. Defaults to `Component`.
|
|
171
|
+
* @param predicate - A function that returns `true` for the component to find.
|
|
172
|
+
* @returns The first matching component, or `undefined` if no match is found.
|
|
173
|
+
*/
|
|
174
|
+
getComponent<T extends Component = Component>(predicate: (component: Component) => boolean): T;
|
|
175
|
+
/**
|
|
176
|
+
* Finds the first component of the specified type. Uses an optimized type map for fast lookups when available.
|
|
177
|
+
*
|
|
178
|
+
* **Performance Note:** Components are only added to the internal type map for optimized lookups when they are
|
|
179
|
+
* created with `precacheTypeLookup: true`. If a component is created with `precacheTypeLookup: false` (the default),
|
|
180
|
+
* it will not be in the type map and the lookup will fall back to iterating through all components, which is slower
|
|
181
|
+
* but avoids the overhead of maintaining the map for components that are rarely looked up by type.
|
|
182
|
+
*
|
|
183
|
+
* @template T - The type of component to return.
|
|
184
|
+
* @param type - The constructor function of the component type to find.
|
|
185
|
+
* @returns The first matching component of the specified type, or `undefined` if not found.
|
|
186
|
+
*
|
|
187
|
+
* @example
|
|
188
|
+
* ```typescript
|
|
189
|
+
* class TransformComponent extends Component {}
|
|
190
|
+
* const entity = new Entity();
|
|
191
|
+
* // Component is NOT added to type map by default (precacheTypeLookup defaults to false)
|
|
192
|
+
* const transform = new TransformComponent(entity);
|
|
193
|
+
* const found = entity.getComponentByType(TransformComponent); // Slower, iterates through components
|
|
194
|
+
*
|
|
195
|
+
* // Component is added to type map for fast lookups (precacheTypeLookup: true)
|
|
196
|
+
* const render = new RenderComponent(entity, { precacheTypeLookup: true });
|
|
197
|
+
* const foundRender = entity.getComponentByType(RenderComponent); // Fast O(1) lookup
|
|
198
|
+
* ```
|
|
199
|
+
*/
|
|
200
|
+
getComponentByType<T extends Component>(type: new (...args: any[]) => T): T | undefined;
|
|
201
|
+
/**
|
|
202
|
+
* Gets all components that match the given filter function.
|
|
203
|
+
* @template T - The type of component to return. Defaults to `Component`.
|
|
204
|
+
* @param filter - A function that returns `true` for components to include.
|
|
205
|
+
* @returns An array of matching components.
|
|
206
|
+
*/
|
|
207
|
+
getComponents<T extends Component = Component>(filter: (component: Component) => boolean): T[];
|
|
208
|
+
/**
|
|
209
|
+
* Gets the index of a component in the components array.
|
|
210
|
+
* @param component - The component to find the index of.
|
|
211
|
+
* @returns The index of the component, or `-1` if not found.
|
|
212
|
+
*/
|
|
213
|
+
indexOfComponent(component: Component): number;
|
|
214
|
+
/**
|
|
215
|
+
* Ticks this entity and all its descendants, calling `onTick` on all enabled components.
|
|
216
|
+
* This should ONLY be called from the root of an Entity tree. Will traverse the full depth of the tree.
|
|
217
|
+
* Disabled entity subtrees and disabled components are skipped during traversal.
|
|
218
|
+
* @param deltaTime - The time elapsed since the last tick in milliseconds.
|
|
219
|
+
*/
|
|
220
|
+
protected _tick(deltaTime: number): void;
|
|
221
|
+
}
|
|
222
|
+
//# sourceMappingURL=entity.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"entity.d.ts","sourceRoot":"","sources":["../src/entity.ts"],"names":[],"mappings":"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"}
|