@codehz/ecs 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 codehz
+
+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,131 @@
+# @codehz/ecs
+
+一个高性能的Entity Component System (ECS) 库，使用 TypeScript 和 Bun 运行时构建。
+
+## 特性
+
+- 🚀 高性能：基于原型的组件存储和高效的查询系统
+- 🔧 类型安全：完整的 TypeScript 支持
+- 🏗️ 模块化：清晰的架构，支持自定义系统和组件
+- 📦 轻量级：零依赖，易于集成
+
+## 安装
+
+```bash
+bun install
+```
+
+## 用法
+
+### 基本示例
+
+```typescript
+import { World } from "@codehz/ecs";
+import { createComponentId } from "@codehz/ecs";
+
+// 定义组件类型
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+
+// 定义组件ID
+const PositionId = createComponentId<Position>(1);
+const VelocityId = createComponentId<Velocity>(2);
+
+// 创建世界
+const world = new World();
+
+// 创建实体
+const entity = world.createEntity();
+world.addComponent(entity, PositionId, { x: 0, y: 0 });
+world.addComponent(entity, VelocityId, { x: 1, y: 0.5 });
+
+// 应用更改
+world.flushCommands();
+
+// 创建查询并更新
+const query = world.createQuery([PositionId, VelocityId]);
+query.forEach([PositionId, VelocityId], (entity, position, velocity) => {
+  position.x += velocity.x * deltaTime;
+  position.y += velocity.y * deltaTime;
+});
+```
+
+### 运行示例
+
+```bash
+bun run examples/simple/demo.ts
+```
+
+## API 概述
+
+### World
+
+- `createEntity()`: 创建新实体
+- `addComponent(entity, componentId, data)`: 向实体添加组件
+- `removeComponent(entity, componentId)`: 从实体移除组件
+- `createQuery(componentIds)`: 创建查询
+- `registerSystem(system)`: 注册系统
+- `update(deltaTime)`: 更新世界
+- `flushCommands()`: 应用命令缓冲区
+
+### Entity
+
+- `createComponentId<T>(id)`: 创建类型安全的组件ID
+
+### Query
+
+- `forEach(componentIds, callback)`: 遍历匹配的实体
+
+### System
+
+实现 `System` 接口来创建自定义系统：
+
+```typescript
+class MySystem implements System {
+  update(world: World, deltaTime: number): void {
+    // 系统逻辑
+  }
+}
+```
+
+## 开发
+
+### 运行测试
+
+```bash
+bun test
+```
+
+### 类型检查
+
+```bash
+bunx tsc --noEmit
+```
+
+## 项目结构
+
+```
+src/
+├── index.ts          # 入口文件
+├── entity.ts         # 实体和组件管理
+├── world.ts          # 世界管理
+├── archetype.ts      # 原型系统
+├── query.ts          # 查询系统
+├── system.ts         # 系统接口
+├── command-buffer.ts # 命令缓冲区
+├── types.ts          # 类型定义
+└── utils.ts          # 工具函数
+
+examples/
+└── simple/
+    ├── demo.ts       # 基本示例
+    └── README.md     # 示例说明
+```
+
+## 许可证
+
+MIT
+
+## 贡献
+
+欢迎提交 Issue 和 Pull Request！

package/archetype.d.ts

@@ -0,0 +1,107 @@
+import type { EntityId } from "./entity";
+import type { ComponentTuple } from "./types";
+/**
+ * Archetype class for ECS architecture
+ * Represents a group of entities that share the same set of components
+ * Optimized for fast iteration and component access
+ */
+export declare class Archetype {
+    /**
+     * The component types that define this archetype
+     */
+    readonly componentTypes: EntityId<any>[];
+    /**
+     * List of entities in this archetype
+     */
+    private entities;
+    /**
+     * Component data storage - maps component type to array of component data
+     * Each array index corresponds to the entity index in the entities array
+     */
+    private componentData;
+    /**
+     * Reverse mapping from entity to its index in this archetype
+     */
+    private entityToIndex;
+    /**
+     * Cache for pre-computed component data sources to avoid repeated calculations
+     * For regular components: data array
+     * For wildcards: matching relation types array
+     */
+    private componentDataSourcesCache;
+    /**
+     * Create a new archetype with the specified component types
+     * @param componentTypes The component types that define this archetype
+     */
+    constructor(componentTypes: EntityId<any>[]);
+    /**
+     * Get the number of entities in this archetype
+     */
+    get size(): number;
+    /**
+     * Check if this archetype matches the given component types
+     * @param componentTypes The component types to check
+     */
+    matches(componentTypes: EntityId<any>[]): boolean;
+    /**
+     * Add an entity to this archetype with initial component data
+     * @param entityId The entity to add
+     * @param componentData Map of component type to component data
+     */
+    addEntity(entityId: EntityId, componentData: Map<EntityId<any>, any>): void;
+    /**
+     * Remove an entity from this archetype
+     * @param entityId The entity to remove
+     * @returns The component data of the removed entity
+     */
+    removeEntity(entityId: EntityId): Map<EntityId<any>, any> | undefined;
+    /**
+     * Check if an entity is in this archetype
+     * @param entityId The entity to check
+     */
+    hasEntity(entityId: EntityId): boolean;
+    /**
+     * Get component data for a specific entity and component type
+     * @param entityId The entity
+     * @param componentType The component type
+     */
+    getComponent<T>(entityId: EntityId, componentType: EntityId<T>): T | undefined;
+    /**
+     * Set component data for a specific entity and component type
+     * @param entityId The entity
+     * @param componentType The component type
+     * @param data The component data
+     */
+    setComponent<T>(entityId: EntityId, componentType: EntityId<T>, data: T): void;
+    /**
+     * Get all entities in this archetype
+     */
+    getEntities(): EntityId[];
+    /**
+     * Get component data for all entities of a specific component type
+     * @param componentType The component type
+     */
+    getComponentData<T>(componentType: EntityId<T>): T[];
+    /**
+     * Get entities with their component data for specified component types
+     * Optimized for bulk component access with pre-computed indices
+     * @param componentTypes Array of component types to retrieve
+     * @returns Array of objects with entity and component data
+     */
+    getEntitiesWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T): Array<{
+        entity: EntityId;
+        components: ComponentTuple<T>;
+    }>;
+    /**
+     * Iterate over entities with their component data for specified component types
+     * Optimized for bulk component access
+     * @param componentTypes Array of component types to retrieve
+     * @param callback Function called for each entity with its components
+     */
+    forEachWithComponents<const T extends readonly EntityId<any>[]>(componentTypes: T, callback: (entity: EntityId, ...components: ComponentTuple<T>) => void): void;
+    /**
+     * Iterate over all entities with their component data
+     * @param callback Function called for each entity with its component data
+     */
+    forEach(callback: (entityId: EntityId, components: Map<EntityId<any>, any>) => void): void;
+}

package/command-buffer.d.ts

@@ -0,0 +1,45 @@
+import type { EntityId } from "./entity";
+/**
+ * Command for deferred execution
+ */
+export interface Command {
+    type: "addComponent" | "removeComponent" | "destroyEntity";
+    entityId: EntityId;
+    componentType?: EntityId<any>;
+    component?: any;
+}
+/**
+ * Command buffer for deferred structural changes
+ */
+export declare class CommandBuffer {
+    private commands;
+    private executeEntityCommands;
+    /**
+     * Create a command buffer with an executor function
+     */
+    constructor(executeEntityCommands: (entityId: EntityId, commands: Command[]) => void);
+    /**
+     * Add a component to an entity (deferred)
+     */
+    addComponent<T>(entityId: EntityId, componentType: EntityId<T>, component: T): void;
+    /**
+     * Remove a component from an entity (deferred)
+     */
+    removeComponent<T>(entityId: EntityId, componentType: EntityId<T>): void;
+    /**
+     * Destroy an entity (deferred)
+     */
+    destroyEntity(entityId: EntityId): void;
+    /**
+     * Execute all commands and clear the buffer
+     */
+    execute(): void;
+    /**
+     * Get current commands (for testing)
+     */
+    getCommands(): Command[];
+    /**
+     * Clear all commands
+     */
+    clear(): void;
+}

package/entity.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Brand for EntityId to create nominal typing with component type information
+ */
+declare const __entityIdBrand: unique symbol;
+/**
+ * Brand for wildcard relation IDs
+ */
+declare const __wildcardRelationBrand: unique symbol;
+/**
+ * Entity ID type for ECS architecture
+ * Based on 52-bit integers within safe integer range
+ * - Component IDs: 1-1023
+ * - Entity IDs: 1024+
+ * - Relation IDs: negative numbers encoding component and entity associations
+ */
+export type EntityId<T = void> = number & {
+    readonly [__entityIdBrand]: T;
+};
+export type WildcardRelationId<T = void> = EntityId<T> & {
+    readonly [__wildcardRelationBrand]: true;
+};
+/**
+ * Constants for ID ranges
+ */
+export declare const INVALID_COMPONENT_ID = 0;
+export declare const COMPONENT_ID_MAX = 1023;
+export declare const ENTITY_ID_START = 1024;
+/**
+ * Constants for relation ID encoding
+ */
+export declare const RELATION_SHIFT: number;
+export declare const WILDCARD_TARGET_ID = 0;
+/**
+ * Create a component ID
+ * @param id Component identifier (1-1023)
+ */
+export declare function createComponentId<T = void>(id: number): EntityId<T>;
+/**
+ * Create an entity ID
+ * @param id Entity identifier (starting from 1024)
+ */
+export declare function createEntityId(id: number): EntityId;
+/**
+ * Type for relation ID based on component and target types
+ */
+type RelationIdType<T, U> = U extends void ? EntityId<T> : T extends void ? EntityId<U> : EntityId<never>;
+/**
+ * Create a relation ID by associating a component with another ID (entity or component)
+ * @param componentId The component ID (0-1023)
+ * @param targetId The target ID (entity, component, or '*' for wildcard)
+ */
+export declare function createRelationId<T>(componentId: EntityId<T>, targetId: "*"): WildcardRelationId<T>;
+export declare function createRelationId<T, U>(componentId: EntityId<T>, targetId: EntityId<U>): RelationIdType<T, U>;
+/**
+ * Check if an ID is a component ID
+ */
+export declare function isComponentId(id: EntityId<any>): boolean;
+/**
+ * Check if an ID is an entity ID
+ */
+export declare function isEntityId(id: EntityId<any>): boolean;
+/**
+ * Check if an ID is a relation ID
+ */
+export declare function isRelationId(id: EntityId): boolean;
+/**
+ * Decode a relation ID into component and target IDs
+ * @param relationId The relation ID (must be negative)
+ * @returns Object with componentId, targetId, and relation type
+ */
+export declare function decodeRelationId(relationId: EntityId<any>): {
+    componentId: EntityId<any>;
+    targetId: EntityId<any>;
+    type: "entity" | "component" | "wildcard";
+};
+/**
+ * Get the string representation of an ID type
+ */
+export declare function getIdType(id: EntityId<any>): "component" | "entity" | "entity-relation" | "component-relation" | "wildcard-relation" | "invalid";
+/**
+ * Get detailed type information for an EntityId
+ * @param id The EntityId to analyze
+ * @returns Detailed type information including relation subtypes
+ */
+export declare function getDetailedIdType(id: EntityId<any>): {
+    type: "component" | "entity" | "entity-relation" | "component-relation" | "wildcard-relation" | "invalid";
+    componentId?: EntityId<any>;
+    targetId?: EntityId<any>;
+};
+/**
+ * Inspect an EntityId and return a human-readable string representation
+ * @param id The EntityId to inspect
+ * @returns A friendly string representation of the ID
+ */
+export declare function inspectEntityId(id: EntityId<any>): string;
+/**
+ * Entity ID Manager for automatic allocation and freelist recycling
+ */
+export declare class EntityIdManager {
+    private nextId;
+    private freelist;
+    /**
+     * Allocate a new entity ID
+     * Uses freelist if available, otherwise increments counter
+     */
+    allocate(): EntityId;
+    /**
+     * Deallocate an entity ID, adding it to the freelist for reuse
+     * @param id The entity ID to deallocate
+     */
+    deallocate(id: EntityId<any>): void;
+    /**
+     * Get the current freelist size (for debugging/monitoring)
+     */
+    getFreelistSize(): number;
+    /**
+     * Get the next ID that would be allocated (for debugging)
+     */
+    getNextId(): number;
+}
+/**
+ * Component ID Manager for automatic allocation
+ * Components are typically registered once and not recycled
+ */
+export declare class ComponentIdManager {
+    private nextId;
+    /**
+     * Allocate a new component ID
+     * Increments counter sequentially from 1
+     */
+    allocate<T = void>(): EntityId<T>;
+    /**
+     * Get the next ID that would be allocated (for debugging)
+     */
+    getNextId(): number;
+    /**
+     * Check if more component IDs are available
+     */
+    hasAvailableIds(): boolean;
+}
+export {};

package/index.d.ts

@@ -0,0 +1,5 @@
+export * from "./entity";
+export * from "./world";
+export * from "./archetype";
+export * from "./query";
+export * from "./system";