initial commit

Author: codehz

.github/copilot-instructions.md

@@ -0,0 +1,29 @@
+# @codehz/ecs - AI Coding Guidelines
+
+## Project Overview
+This is an Entity Component System (ECS) library built with TypeScript and Bun runtime. The project follows modern TypeScript practices with strict type checking and ESNext features.
+
+## Runtime & Environment
+- **Runtime**: Bun (not Node.js) - use `bun` commands instead of `npm`/`yarn`
+- **Language**: TypeScript with ESNext target and strict mode enabled
+- **Module System**: ES modules with `"module": "Preserve"` and bundler resolution
+
+## Development Workflow
+- **Install**: `bun install` (not `npm install`)
+- **Run**: `bun run src/index.ts` (direct execution, no build step)
+- **TypeScript**: `bunx tsc --noEmit` (Configured for modern features with strict checking - noEmit mode for bundler compatibility)
+- **Testing**: `bun test` (set up tests as needed)
+
+## Code Patterns
+- **Imports**: Use ES module syntax with `.ts` extensions allowed due to `"allowImportingTsExtensions": true`
+- **Type Checking**: Strict mode with additional checks like `noUncheckedIndexedAccess` and `noImplicitOverride`
+
+## Architecture Notes
+- **Entry Point**: `src/index.ts` - single file currently, expand with ECS components/systems
+- **Dependencies**: Minimal setup - add peer dependencies for TypeScript integration
+
+## Key Files
+- `tsconfig.json`: Modern TypeScript config with bundler mode
+- `package.json`: Module configuration with Bun-specific settings
+- `src/index.ts`: Main entry point (currently minimal)</content>
+<parameter name="filePath">d:\Developer\ecs\.github\copilot-instructions.md

.gitignore

@@ -0,0 +1,34 @@
+# dependencies (bun install)
+node_modules
+
+# output
+out
+dist
+*.tgz
+
+# code coverage
+coverage
+*.lcov
+
+# logs
+logs
+_.log
+report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
+
+# dotenv environment variable files
+.env
+.env.development.local
+.env.test.local
+.env.production.local
+.env.local
+
+# caches
+.eslintcache
+.cache
+*.tsbuildinfo
+
+# IntelliJ based IDEs
+.idea
+
+# Finder (MacOS) folder config
+.DS_Store

.prettierrc

@@ -0,0 +1,3 @@
+{
+  "printWidth": 120
+}

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！

bun.lock

@@ -0,0 +1,48 @@
+# ECS Simple Demo
+
+这是一个简单的Entity Component System (ECS) 演示，展示了基本的ECS概念：
+
+- **实体 (Entities)**: 游戏对象的基本单位
+- **组件 (Components)**: 实体的属性数据
+- **系统 (Systems)**: 处理组件数据的逻辑
+- **世界 (World)**: 管理所有实体、组件和系统的容器
+
+## 演示内容
+
+这个demo创建了两个实体，每个实体都有位置(Position)和速度(Velocity)组件：
+
+- 实体1: 从 (0, 0) 开始，以 (1, 0.5) 的速度移动
+- 实体2: 从 (10, 10) 开始，以 (-0.5, 1) 的速度移动
+
+移动系统每帧更新实体的位置，并打印当前位置。
+
+## 运行方法
+
+确保你已经安装了Bun运行时，然后在项目根目录运行：
+
+```bash
+bun run examples/simple/demo.ts
+```
+
+## 优化说明
+
+为了提高性能和代码简洁性，demo使用了以下优化：
+
+- **预先缓存Query**: 在系统初始化时创建查询并缓存，而不是在每次update中重新创建。这避免了重复的查询创建开销。
+- **使用forEach接口**: 使用Query的`forEach`方法直接获取组件数据，避免手动调用`world.getComponent()`，减少函数调用开销并提高代码可读性。
+
+## 输出示例
+
+```
+ECS Simple Demo
+
+Update 1:
+Entity 1024: Position (1.00, 0.50)
+Entity 1025: Position (9.50, 11.00)
+
+Update 2:
+Entity 1024: Position (2.00, 1.00)
+Entity 1025: Position (9.00, 12.00)
+
+...
+```

examples/simple/README.md

@@ -0,0 +1,68 @@
+import { World } from "../../src/world";
+import { createComponentId } from "../../src/entity";
+import type { System } from "../../src/system";
+import type { Query } from "../../src/query";
+
+// 定义组件类型
+type Position = { x: number; y: number };
+type Velocity = { x: number; y: number };
+
+// 定义组件ID
+const PositionId = createComponentId<Position>(1);
+const VelocityId = createComponentId<Velocity>(2);
+
+// 移动系统
+class MovementSystem implements System {
+  private query: Query; // 缓存查询
+
+  constructor(world: World) {
+    // 在构造函数中预先创建并缓存查询
+    this.query = world.createQuery([PositionId, VelocityId]);
+  }
+
+  update(world: World, deltaTime: number): void {
+    // 使用缓存的查询的forEach方法，直接获取组件数据
+    this.query.forEach([PositionId, VelocityId], (entity, position, velocity) => {
+      // 更新位置
+      position.x += velocity.x * deltaTime;
+      position.y += velocity.y * deltaTime;
+
+      console.log(`Entity ${entity}: Position (${position.x.toFixed(2)}, ${position.y.toFixed(2)})`);
+    });
+  }
+}
+
+function main() {
+  console.log("ECS Simple Demo");
+
+  // 创建世界
+  const world = new World();
+
+  // 注册系统（传递world参数）
+  world.registerSystem(new MovementSystem(world));
+
+  // 创建实体1
+  const entity1 = world.createEntity();
+  world.addComponent(entity1, PositionId, { x: 0, y: 0 });
+  world.addComponent(entity1, VelocityId, { x: 1, y: 0.5 });
+
+  // 创建实体2
+  const entity2 = world.createEntity();
+  world.addComponent(entity2, PositionId, { x: 10, y: 10 });
+  world.addComponent(entity2, VelocityId, { x: -0.5, y: 1 });
+
+  // 执行命令以应用组件添加
+  world.flushCommands();
+
+  // 运行几个更新循环
+  const deltaTime = 1.0; // 1秒
+  for (let i = 0; i < 5; i++) {
+    console.log(`\nUpdate ${i + 1}:`);
+    world.update(deltaTime);
+  }
+
+  console.log("\nDemo completed!");
+}
+
+// 运行demo
+main();

examples/simple/demo.ts

@@ -0,0 +1,11 @@
+{
+  "name": "@codehz/ecs",
+  "module": "src/index.ts",
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "~5.9.2"
+  }
+}