@funderforge/ecs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,412 @@
+# Component Framework
+
+A generic component framework, optimized for performance and simplicity.
+
+## Overview
+
+This framework implements an Entity-Component System (ECS) pattern that allows you to build flexible, hierarchical structures where entities can contain multiple components. The framework is designed with performance in mind, featuring efficient traversal algorithms, cached property access, and method-based architecture.
+
+## How It Works
+
+### Architecture
+
+The framework consists of two main classes:
+
+- **Entity**: A node in a hierarchical tree structure that can have children and components
+- **Component**: Functionality attached to entities that can respond to lifecycle events through virtual methods
+
+### Visual Structure
+
+```text
+Entity Tree Structure:
+═══════════════════════════════════════════════════════════
+
+                    [Root Entity]
+                      ├─ Component A
+                      ├─ Component B
+                      └─ Component C
+                            │
+                    ┌───────┴───────┐
+                    │               │
+            [Child Entity 1]  [Child Entity 2]
+              ├─ Component X    ├─ Component Y
+              └─ Component Z    └─ Component W
+                    │               │
+              [Grandchild]     [Grandchild]
+              ├─ Component      ├─ Component
+
+═══════════════════════════════════════════════════════════
+
+Key Concepts:
+• Entities form a tree hierarchy (parent-child relationships)
+• Each entity can have multiple components
+• Components belong to exactly one entity
+• Enabled/disabled state cascades down the tree
+• Components respond to lifecycle events through virtual methods
+```
+
+### Core Features
+
+- **Hierarchical Entity Tree**: Entities can have parent-child relationships
+- **Component System**: Attach multiple components to entities for modular functionality
+- **Enabled/Disabled State**: Cascading state management with efficient caching
+- **Method-Based Architecture**: Components can override `onTick` and `onEnabledChanged` virtual methods
+- **Efficient Traversal**: Optimized methods to traverse entities and components
+- **Performance Optimized**: Cached property access, minimal allocations
+
+## Installation
+
+```bash
+npm install @funderforge/ecs
+# or
+pnpm install @funderforge/ecs
+# or
+yarn add @funderforge/ecs
+```
+
+## Examples
+
+### Basic Entity Creation
+
+```typescript
+import { Entity } from '@funderforge/ecs';
+
+// Create a root entity
+const root = new Entity({ id: 'root' });
+
+// Create child entities
+const child1 = new Entity({ id: 'child1' });
+const child2 = new Entity({ id: 'child2' });
+
+// Build the hierarchy
+root.addChild(child1);
+root.addChild(child2);
+
+console.log(root.childrenLength()); // 2
+console.log(child1.parent === root); // true
+```
+
+### Creating Components
+
+```typescript
+import { Entity, Component } from '@funderforge/ecs';
+
+// Define a custom component
+class TransformComponent extends Component {
+  x: number = 0;
+  y: number = 0;
+  
+  move(dx: number, dy: number) {
+    this.x += dx;
+    this.y += dy;
+  }
+}
+
+// Create an entity and attach components
+const entity = new Entity({ id: 'player' });
+const transform = new TransformComponent(entity);
+const renderer = new RenderComponent(entity);
+
+console.log(entity.componentsLength()); // 2
+
+// Access components with type safety
+const transformComp = entity.getComponent<TransformComponent>(
+  c => c instanceof TransformComponent
+);
+transformComp?.move(10, 20);
+```
+
+### Entity Hierarchy
+
+```typescript
+// Create a game scene hierarchy
+const scene = new Entity({ id: 'scene' });
+const player = new Entity({ id: 'player', parent: scene });
+const enemy1 = new Entity({ id: 'enemy1', parent: scene });
+const enemy2 = new Entity({ id: 'enemy2', parent: scene });
+
+// Nested hierarchy
+const weapon = new Entity({ id: 'weapon', parent: player });
+const bullet = new Entity({ id: 'bullet', parent: weapon });
+
+// Get hierarchy level
+console.log(bullet.hierarchyLevel()); // 3 (scene -> player -> weapon -> bullet)
+
+// Remove from hierarchy
+scene.removeChild(enemy1);
+console.log(enemy1.parent); // null
+```
+
+### Enabled/Disabled State
+
+```typescript
+// Create entity with initial state
+const entity = new Entity({ id: 'entity', enabledSelf: true });
+const child = new Entity({ id: 'child', parent: entity });
+
+console.log(entity.enabled); // true
+console.log(child.enabled); // true (inherits from parent)
+
+// Disable parent - children are also disabled
+entity.enabledSelf = false;
+console.log(entity.enabled); // false
+console.log(child.enabled); // false
+
+// Re-enable
+entity.enabledSelf = true;
+console.log(child.enabled); // true
+
+// Components respect entity enabled state
+const component = new MyComponent(entity, { enabledSelf: true });
+entity.enabledSelf = false;
+console.log(component.enabled); // false (disabled because entity is disabled)
+```
+
+### Handling Tick Events
+
+```typescript
+class MovementComponent extends Component {
+  velocity: number = 5;
+  position: number = 0;
+
+  // Override the onTick virtual method
+  protected onTick(deltaTime: number): void {
+    // Update position based on deltaTime (in milliseconds)
+    this.position += this.velocity * (deltaTime / 1000);
+  }
+}
+
+// Create entities and components
+const root = new Entity({ id: 'root' });
+const entity = new Entity({ id: 'moving-entity', parent: root });
+const movement = new MovementComponent(entity);
+
+// Tick the root entity (traverses the entire tree)
+// This will call onTick on all enabled components
+(root as any)._tick(16.67); // ~60fps deltaTime
+```
+
+### Handling Enabled State Changes
+
+```typescript
+class AudioComponent extends Component {
+  // Override the onEnabledChanged virtual method
+  protected onEnabledChanged(newValue: boolean): void {
+    if (newValue) {
+      console.log('Component enabled, starting audio');
+      // Start audio playback
+    } else {
+      console.log('Component disabled, stopping audio');
+      // Stop audio playback
+    }
+  }
+}
+
+const entity = new Entity({ id: 'audio-entity' });
+const audio = new AudioComponent(entity);
+
+// Disable the component
+audio.enabledSelf = false; // Calls onEnabledChanged(false)
+
+// Disable the entity (also calls onEnabledChanged for all components)
+entity.enabledSelf = false;
+```
+
+### Destroying Components
+
+```typescript
+const entity = new Entity({ id: 'entity' });
+const component = new MyComponent(entity);
+
+// Use the component...
+component.doSomething();
+
+// Destroy the component when no longer needed
+component.destroy();
+
+// CRITICAL: After destroy(), the component is "dead" and must not be accessed
+// Remove all references and never use it again
+// component = null; // or let it go out of scope
+
+// ❌ WRONG - Never do this after destroy():
+// component.doSomething(); // Undefined behavior - component is dead
+// console.log(component.entity); // Undefined behavior - component is dead
+```
+
+**Important**: After calling `destroy()` on a component, you must remove all references to it and never access it again. The component is permanently removed from its entity and accessing it will result in undefined behavior.
+
+### Traversing Entities and Components
+
+```typescript
+const root = new Entity({ id: 'root' });
+// ... build tree structure ...
+
+// Traverse all children
+for (const child of root.traverseChildren()) {
+  console.log(`Child: ${child.id}`);
+}
+
+// Traverse children with a filter
+for (const enabledChild of root.traverseChildren(child => child.enabledSelf)) {
+  console.log(`Enabled child: ${enabledChild.id}`);
+}
+
+// Traverse all components in the tree
+for (const component of root.traverseComponents()) {
+  console.log(`Component: ${component.constructor.name}`);
+}
+
+// Traverse specific component types with type safety
+for (const transform of root.traverseComponents<TransformComponent>(
+  c => c instanceof TransformComponent
+)) {
+  console.log(`Transform at entity: ${transform.entity.id}`);
+}
+
+// Find specific entities/components with type safety
+const player = root.getChild(e => e.id === 'player');
+const transform = player?.getComponent<TransformComponent>(
+  c => c instanceof TransformComponent
+);
+```
+
+### Complete Example: Simple Game Scene
+
+```typescript
+import { Entity, Component } from '@funderforge/ecs';
+
+// Define components
+class TransformComponent extends Component {
+  x: number = 0;
+  y: number = 0;
+  rotation: number = 0;
+}
+
+class RenderComponent extends Component {
+  color: string = '#ffffff';
+  
+  protected onTick(): void {
+    const transform = this.entity.getComponent<TransformComponent>(
+      c => c instanceof TransformComponent
+    );
+    if (transform) {
+      console.log(`Rendering at (${transform.x}, ${transform.y})`);
+    }
+  }
+}
+
+class PhysicsComponent extends Component {
+  velocityX: number = 0;
+  velocityY: number = 0;
+  
+  protected onTick(deltaTime: number): void {
+    const transform = this.entity.getComponent<TransformComponent>(
+      c => c instanceof TransformComponent
+    );
+    if (transform) {
+      transform.x += this.velocityX * (deltaTime / 1000);
+      transform.y += this.velocityY * (deltaTime / 1000);
+    }
+  }
+}
+
+// Create game scene
+const scene = new Entity({ id: 'scene' });
+
+// Create player entity
+const player = new Entity({ id: 'player', parent: scene });
+new TransformComponent(player);
+new PhysicsComponent(player);
+new RenderComponent(player);
+
+// Create enemy entities
+for (let i = 0; i < 5; i++) {
+  const enemy = new Entity({ id: `enemy-${i}`, parent: scene });
+  new TransformComponent(enemy);
+  new RenderComponent(enemy);
+}
+
+// Game loop
+function gameLoop() {
+  const deltaTime = 16.67; // ~60fps
+  (scene as any)._tick(deltaTime);
+}
+
+// Run game loop
+setInterval(gameLoop, 16.67);
+```
+
+## API Reference
+
+### Entity
+
+#### Entity Constructor
+
+```typescript
+new Entity(preset?: {
+  id?: string | number;
+  enabledSelf?: boolean;
+  parent?: Entity;
+})
+```
+
+#### Entity Methods
+
+- `addChild(child: Entity)`: Add a child entity
+- `removeChild(child: Entity)`: Remove a child entity
+- `setParent(parent: Entity | null)`: Set or clear the parent entity
+- `childByIdx<T extends Entity = Entity>(index: number): T | undefined`: Get a child entity by index
+- `getChild<T extends Entity = Entity>(predicate: (child: Entity) => boolean): T | undefined`: Find a child entity
+- `getChildren<T extends Entity = Entity>(filter: (child: Entity) => boolean): T[]`: Get filtered children
+- `traverseChildren<T extends Entity = Entity>(predicate?: (child: Entity) => boolean): Generator<T>`: Traverse all descendants
+- `componentByIdx<T extends Component = Component>(index: number): T | undefined`: Get a component by index
+- `getComponent<T extends Component = Component>(predicate: (component: Component) => boolean): T | undefined`: Find a component
+- `getComponents<T extends Component = Component>(filter: (component: Component) => boolean): T[]`: Get filtered components
+- `traverseComponents<T extends Component = Component>(predicate?: (component: Component) => boolean): Generator<T>`: Traverse all components in tree
+- `hierarchyLevel()`: Get the depth level in the hierarchy
+
+#### Entity Properties
+
+- `id: string | number`: Unique identifier
+- `enabledSelf: boolean`: Whether this entity is enabled (setter/getter)
+- `enabled: boolean`: Whether this entity is enabled (considering parent state)
+- `parent: Entity | null`: Parent entity reference
+
+### Component
+
+#### Component Constructor
+
+```typescript
+new Component(entity: Entity, preset?: {
+  enabledSelf?: boolean;
+  precacheTypeLookup?: boolean;
+})
+```
+
+#### Component Virtual Methods
+
+- `protected onTick(deltaTime: number): void`: Override this method to handle tick events. Called during entity update cycles.
+- `protected onEnabledChanged(newValue: boolean): void`: Override this method to respond to enabled state changes.
+
+#### Component Methods
+
+- `destroy(): void`: Destroys this component, removing it from its entity. **After calling `destroy()`, the component is considered "dead" and must not be accessed or used in any way. Remove all references to the component and never access its properties or methods again.**
+
+#### Component Properties
+
+- `entity: Entity`: The entity this component belongs to
+- `enabledSelf: boolean`: Whether this component is enabled (setter/getter)
+- `enabled: boolean`: Whether this component is enabled (considering entity state)
+
+## Performance
+
+The framework is optimized for performance:
+
+- **Cached Property Access**: The `enabled` property is cached and only recomputed when necessary
+- **Efficient Traversal**: Uses stack-based traversal algorithms that minimize allocations
+- **Selective Processing**: Disabled entities and components are skipped during traversal
+- **Method-Based Architecture**: Direct method calls instead of event system overhead
+
+## License
+
+MIT

package/dist/component.d.ts

@@ -0,0 +1,135 @@
+import type Entity from "./entity";
+/**
+ * Abstract base class for components that can be attached to entities.
+ * Components provide functionality to entities and can respond to lifecycle events through virtual methods.
+ *
+ * Key features:
+ * - Belongs to exactly one entity
+ * - Method-based architecture with `onTick` and `onEnabledChanged` virtual methods
+ * - Enabled/disabled state that respects entity state
+ * - Automatic registration with the entity upon construction
+ *
+ * @example
+ * ```typescript
+ * class TransformComponent extends Component {
+ *   x = 0;
+ *   y = 0;
+ *
+ *   protected onTick(deltaTime: number): void {
+ *     // Update position based on deltaTime
+ *   }
+ * }
+ *
+ * const entity = new Entity({ id: 'player' });
+ * const transform = new TransformComponent(entity);
+ * ```
+ */
+export default abstract class Component {
+    /** The entity this component belongs to. Set automatically during construction and cannot be changed. */
+    readonly entity: Entity;
+    private _enabledSelf;
+    /**
+     * Whether to add this component to the entity's type map for optimized lookups.
+     *
+     * - `false` (default): Component is NOT added to the type map. Lookups will fall back to iteration, which is slower
+     *   but avoids the overhead of maintaining the map for components that are rarely looked up by type.
+     * - `true`: Component is added to the type map, enabling fast O(1) lookups via `entity.getComponentByType()`.
+     *
+     * @default false
+     */
+    readonly precacheTypeLookup: boolean;
+    /**
+     * Creates a new Component instance and attaches it to the specified entity.
+     * The component is automatically registered with the entity and cannot be moved to another entity.
+     *
+     * @param entity - The entity this component belongs to. Required and cannot be changed after construction.
+     * @param preset - Optional configuration object for the component.
+     * @param preset.enabledSelf - Whether the component is enabled by default. Defaults to `true`.
+     * @param preset.precacheTypeLookup - Whether to add this component to the entity's type map for optimized lookups.
+     *   Defaults to `false` (component is NOT added to map, uses slower iteration-based lookups). Set to `true` to add
+     *   the component to the map for fast O(1) lookups via `entity.getComponentByType()`.
+     *
+     * @example
+     * ```typescript
+     * class MyComponent extends Component {
+     *   constructor(entity: Entity) {
+     *     super(entity, { enabledSelf: true });
+     *   }
+     * }
+     *
+     * const entity = new Entity({ id: 'entity' });
+     * const component = new MyComponent(entity);
+     *
+     * // Component is NOT added to type map by default (slower lookups)
+     * const found = entity.getComponentByType(MyComponent);
+     *
+     * // Add to type map for components frequently looked up by type (fast lookups)
+     * const transform = new TransformComponent(entity, { precacheTypeLookup: true });
+     * const foundTransform = entity.getComponentByType(TransformComponent); // Fast O(1) lookup
+     * ```
+     */
+    constructor(entity: Entity, preset?: {
+        enabledSelf?: boolean;
+        precacheTypeLookup?: boolean;
+    });
+    /**
+     * Gets whether this component itself is enabled, independent of its entity's state.
+     * @returns `true` if this component is enabled, `false` otherwise.
+     */
+    get enabledSelf(): boolean;
+    /**
+     * Sets whether this component itself is enabled. When the effective enabled state changes (considering both this value and the entity's enabled state),
+     * the `onEnabledChanged` method will be called.
+     * @param value - `true` to enable this component, `false` to disable it.
+     */
+    set enabledSelf(value: boolean);
+    /**
+     * Virtual method called when the component is ticked during the entity update cycle.
+     * Override this method in derived classes to implement tick-based logic.
+     * @param deltaTime - The time elapsed since the last tick in milliseconds.
+     */
+    protected onTick(_deltaTime: number): void;
+    /**
+     * Virtual method called when the component's effective enabled state changes.
+     * Override this method in derived classes to respond to enabled state changes.
+     * @param newValue - The new effective enabled state of the component.
+     */
+    protected onEnabledChanged(_newValue: boolean): void;
+    /**
+     * Gets the effective enabled state of this component, considering both its own `enabledSelf` value and its entity's enabled state.
+     * @returns `true` only if both this component's `enabledSelf` is `true` and its entity's `enabled` is `true`.
+     */
+    get enabled(): boolean;
+    /**
+     * Destroys this component, removing it from its entity and marking it as "dead".
+     *
+     * After calling `destroy()`, the component is permanently removed from the entity's component list
+     * and its entity reference is cleared. The component should be considered "dead" and must not be
+     * accessed or used in any way after destruction.
+     *
+     * **CRITICAL**: After calling `destroy()`, you must:
+     * - Remove all references to this component from your code
+     * - Never access the component's properties or methods again
+     * - Never call any methods on the component
+     *
+     * Accessing a destroyed component will result in undefined behavior. In non-production builds,
+     * the component object is frozen to help detect misuse.
+     *
+     * @example
+     * ```typescript
+     * const component = new MyComponent(entity);
+     *
+     * // Use the component...
+     * component.doSomething();
+     *
+     * // Destroy the component when no longer needed
+     * component.destroy();
+     *
+     * // IMPORTANT: Remove all references and never access it again
+     * // component = null; // or let it go out of scope
+     * // DO NOT: component.doSomething(); // ❌ WRONG - component is dead
+     * ```
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=component.d.ts.map

package/dist/component.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component.d.ts","sourceRoot":"","sources":["../src/component.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,OAAO,CAAC,QAAQ,OAAO,SAAS;IACtC,yGAAyG;IACzG,QAAQ,CAAC,MAAM,EAAG,MAAM,CAAC;IACzB,OAAO,CAAC,YAAY,CAAU;IAE9B;;;;;;;;OAQG;IACH,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IAErC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;gBAEF,MAAM,EAAE,MAAM,EACd,MAAM,GAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAC;QAAC,kBAAkB,CAAC,EAAE,OAAO,CAAA;KAAO;IAoBrE;;;OAGG;IACH,IAAI,WAAW,IASQ,OAAO,CAP7B;IAED;;;;OAIG;IACH,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,EAQ7B;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAE1C;;;;OAIG;IACH,SAAS,CAAC,gBAAgB,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAEpD;;;OAGG;IACH,IAAI,OAAO,YAEV;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,IAAI,IAAI;CAoBf"}