esengine/packages/framework/core/README_CN.md

@esengine/ecs-framework

适用于 JavaScript 游戏引擎的高性能 ECS 框架

English | 中文

---

概述

一个独立的、零依赖的 ECS（实体-组件-系统）框架，可与任何 JavaScript 游戏引擎配合使用：

• Cocos Creator
• Laya
• Egret
• Phaser
• 或你自己的引擎

这个包是 ESEngine 的核心，但可以完全独立使用。

安装

npm / pnpm / yarn

npm install @esengine/ecs-framework

仅克隆源码

如果你只想要 ECS 框架源码（不需要完整的 ESEngine）：

# 第一步：克隆仓库骨架，不下载文件内容（需要 Git 2.25+）
git clone --filter=blob:none --sparse https://github.com/esengine/esengine.git

# 第二步：进入目录
cd esengine

# 第三步：指定要检出的目录
git sparse-checkout set packages/core

# 完成！现在你只有 packages/core/ 目录，其他文件夹不会下载

快速开始

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 update(dt: number) {
    Core.update(dt);
}

集成示例

Cocos Creator

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

const { ccclass } = _decorator;

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

    onLoad() {
        Core.create();
        this.scene = new Scene();
        // 注册你的系统...
        Core.setScene(this.scene);
    }

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

Laya

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

export class Main {
    private scene: Scene;

    constructor() {
        Core.create();
        this.scene = new Scene();
        Core.setScene(this.scene);

        Laya.timer.frameLoop(1, this, this.onUpdate);
    }

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

特性

特性	描述
零依赖	无外部运行时依赖
类型安全查询	流畅的 API，完整 TypeScript 支持
变更检测	基于 Epoch 的脏标记优化
序列化	内置场景序列化和快照
服务容器	系统的依赖注入
性能监控	内置性能分析工具

文档

• API 参考
• 架构指南
• 完整 ESEngine 文档

许可证

MIT 协议 - 可自由用于商业和开源项目。

---

ESEngine 的一部分 · 可独立使用