# zero-ecs-lib

**Repository Path**: wuchunlin_admin/zero-ecs-lib

## Basic Information

- **Project Name**: zero-ecs-lib
- **Description**: 一个轻量级ECS架构库，专注于高性能游戏与仿真系统开发，提供简洁易用的实体组件系统，助力开发者构建高效可扩展的应用。
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-14
- **Last Updated**: 2026-07-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Zero ECS

Zero ECS 是一个面向游戏数据层的 TypeScript ECS workspace，由三个可独立安装的库组成：

- `@zero-ecs/world`：实体、组件、Archetype、Table、Query 与单实体事务；
- `@zero-ecs/scheduler`：不知道 ECS 的通用静态调度器；
- `@zero-ecs/game`：组合 World、Scheduler、依赖注入、生命周期与标准功能模块。

依赖方向固定为 `game -> world + scheduler`，World 与 Scheduler 之间互不依赖。

## 快速开始

```ts
import {
    Commands,
    DefaultCoreModule,
    GameBuilder,
    Types,
    type Component,
} from "@zero-ecs/game";

const enum Position { x, y }
class PositionType implements Component<Position> {
    readonly [Position.x] = Types.F32;
    readonly [Position.y] = Types.F32;
}

const game = new GameBuilder()
    .addModule(new DefaultCoreModule())
    .build();
game.init();
game.start();

const commands = game.service(Commands);
const command = commands.spawn()
    .set(PositionType, Position.x, 10)
    .set(PositionType, Position.y, 20);
const entity = command.entity;
command.submit();
game.update();

console.log(game.world.get(entity, PositionType, Position.x)); // 10
game.dispose();
```

`DefaultCoreModule` 一次安装 Commands、Time、Timer、Event 与 Random。需要减小运行时组成时，
仍可只注册 `CommandModule`、`TimeModule` 等独立模块。

World 也可以完全脱离 Game 使用：

```ts
import { Allocator, World } from "@zero-ecs/world";

const allocator = new Allocator();
const world = new World(allocator);
const entity = world.reserveEntity();
const ref = world.ref(entity); // 低频只读便利对象
const command = world.createEntityCommand(entity);
world.applyEntityCommand(command);
world.dispose();
allocator.clear();
```

## 开发命令

- `npm run typecheck`：分别检查三个包；
- `npm test`：运行源码行为测试；
- `npm run build`：按 world → scheduler → game 生成三个包；
- `npm run verify:release`：运行类型、行为、声明、包边界、no-JIT 与示例验证。

架构说明见 [三库架构](./docs/three-library-architecture.md)，公共 API 见
[API 参考](./docs/api.md)。