esengine/README_CN.md

ESEngine

TypeScript 模块化游戏框架

English | 中文

文档 · API 参考 · 示例

---

ESEngine 是什么？

ESEngine 是一套引擎无关的游戏开发模块，可与 Cocos Creator、Laya、Phaser、PixiJS 等任何 JavaScript 游戏引擎配合使用。

核心是一个高性能的 ECS（实体-组件-系统） 框架，配套 AI、网络、物理等可选模块。

npm install @esengine/ecs-framework

功能模块

模块	描述	需要渲染引擎
ECS 核心	实体-组件-系统框架，支持响应式查询	否
行为树	AI 行为树，支持可视化编辑	否
蓝图	可视化脚本系统	否
状态机	有限状态机	否
定时器	定时器和冷却系统	否
空间索引	空间查询（四叉树、网格）	否
寻路	A* 和导航网格寻路	否
程序化生成	噪声、随机、采样等生成算法	否
RPC	高性能 RPC 通信框架	否
服务端	游戏服务器框架，支持房间、认证、速率限制	否
网络	客户端网络，支持预测、AOI、增量压缩	否
事务系统	游戏事务系统，支持 Redis/内存存储	否
世界流送	开放世界分块加载和流送	否

所有框架模块都可以独立使用，无需依赖特定渲染引擎。

快速开始

使用 CLI（推荐）

在现有项目中添加 ECS 的最简单方式：

# 在项目目录中运行
npx @esengine/cli init

CLI 会自动检测项目类型（Cocos Creator 2.x/3.x、LayaAir 3.x 或 Node.js）并生成相应的集成代码。

手动配置

import {
    Core, Scene, Entity, Component, EntitySystem,
    Matcher, Time, ECSComponent, ECSSystem
} from '@esengine/ecs-framework';

// 定义组件（纯数据）
@ECSComponent('Position')
class Position extends Component {
    x = 0;
    y = 0;
}

@ECSComponent('Velocity')
class Velocity extends Component {
    dx = 0;
    dy = 0;
}

// 定义系统（逻辑）
@ECSSystem('Movement')
class MovementSystem extends EntitySystem {
    constructor() {
        super(Matcher.all(Position, Velocity));
    }

    protected process(entities: readonly Entity[]): void {
        for (const entity of entities) {
            const pos = entity.getComponent(Position);
            const vel = entity.getComponent(Velocity);
            pos.x += vel.dx * Time.deltaTime;
            pos.y += vel.dy * Time.deltaTime;
        }
    }
}

// 初始化
Core.create();
const scene = new Scene();
scene.addSystem(new MovementSystem());

const player = scene.createEntity('Player');
player.addComponent(new Position());
player.addComponent(new Velocity());

Core.setScene(scene);

// 集成到你的游戏循环
function gameLoop(currentTime: number) {
    Core.update(currentTime / 1000);
    requestAnimationFrame(gameLoop);
}
requestAnimationFrame(gameLoop);

与其他引擎配合使用

ESEngine 的框架模块设计为可与你喜欢的渲染引擎配合使用：

与 Cocos Creator 配合

import { Component as CCComponent, _decorator } from 'cc';
import { Core, Scene, Matcher, EntitySystem } from '@esengine/ecs-framework';
import { BehaviorTreeExecutionSystem } from '@esengine/behavior-tree';

const { ccclass } = _decorator;

@ccclass('GameManager')
export class GameManager extends CCComponent {
    private ecsScene!: Scene;

    start() {
        Core.create();
        this.ecsScene = new Scene();

        // 添加 ECS 系统
        this.ecsScene.addSystem(new BehaviorTreeExecutionSystem());
        this.ecsScene.addSystem(new MyGameSystem());

        Core.setScene(this.ecsScene);
    }

    update(dt: number) {
        Core.update(dt);
    }
}

与 Laya 3.x 配合

import { Core, Scene } from '@esengine/ecs-framework';
import { FSMSystem } from '@esengine/fsm';

const { regClass } = Laya;

@regClass()
export class ECSManager extends Laya.Script {
    private ecsScene = new Scene();

    onAwake(): void {
        Core.create();
        this.ecsScene.addSystem(new FSMSystem());
        Core.setScene(this.ecsScene);
    }

    onUpdate(): void {
        Core.update(Laya.timer.delta / 1000);
    }

    onDestroy(): void {
        Core.destroy();
    }
}

包列表

框架包（引擎无关）

这些包零渲染依赖，可与任何引擎配合使用：

npm install @esengine/ecs-framework      # ECS 核心
npm install @esengine/behavior-tree      # AI 行为树
npm install @esengine/blueprint          # 可视化脚本
npm install @esengine/fsm                # 状态机
npm install @esengine/timer              # 定时器和冷却
npm install @esengine/spatial            # 空间索引
npm install @esengine/pathfinding        # 寻路
npm install @esengine/procgen            # 程序化生成
npm install @esengine/rpc                # RPC 框架
npm install @esengine/server             # 游戏服务器
npm install @esengine/network            # 客户端网络
npm install @esengine/transaction        # 事务系统
npm install @esengine/world-streaming    # 世界流送

ESEngine 运行时（可选）

如果你需要完整的引擎解决方案：

分类	包名
核心	engine-core, asset-system, material-system
渲染	sprite, tilemap, particle, camera, mesh-3d
物理	physics-rapier2d
平台	platform-web, platform-wechat

编辑器（可选）

基于 Tauri 构建的可视化编辑器：

• 从 Releases 下载
• 从源码构建
• 支持行为树编辑、Tilemap 绘制、可视化脚本

项目结构

esengine/
├── packages/
│   ├── framework/          # 引擎无关模块（可发布到 NPM）
│   │   ├── core/          # ECS 框架
│   │   ├── math/          # 数学工具
│   │   ├── behavior-tree/ # AI 行为树
│   │   ├── blueprint/     # 可视化脚本
│   │   ├── fsm/           # 有限状态机
│   │   ├── timer/         # 定时器系统
│   │   ├── spatial/       # 空间查询
│   │   ├── pathfinding/   # 寻路
│   │   ├── procgen/       # 程序化生成
│   │   ├── rpc/           # RPC 框架
│   │   ├── server/        # 游戏服务器
│   │   ├── network/       # 客户端网络
│   │   ├── transaction/   # 事务系统
│   │   └── world-streaming/ # 世界流送
│   │
│   ├── engine/            # ESEngine 运行时
│   ├── rendering/         # 渲染模块
│   ├── physics/           # 物理模块
│   ├── editor/            # 可视化编辑器
│   └── rust/              # WASM 渲染器
│
├── docs/                   # 文档
└── examples/               # 示例

从源码构建

git clone https://github.com/esengine/esengine.git
cd esengine

pnpm install
pnpm build

# 框架包类型检查
pnpm type-check:framework

# 运行测试
pnpm test

文档

• ECS 框架指南
• 行为树指南
• 编辑器启动指南 (English)
• API 参考

社区

• QQ 交流群 - 中文社区
• Discord - 国际社区
• GitHub Issues - Bug 反馈和功能建议
• GitHub Discussions - 问题和想法

贡献

欢迎贡献代码！提交 PR 前请阅读贡献指南。

1. Fork 仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交修改 (git commit -m 'Add amazing feature')
4. 推送分支 (git push origin feature/amazing-feature)
5. 发起 Pull Request

许可证

ESEngine 基于 MIT 协议 开源，个人和商业使用均免费。

---

由 ESEngine 社区用心打造