Files

YHH 58f70a5783 refactor(core): 代码结构优化 & 添加独立 ECS 框架文档 (#316 )

Core 库优化:
- Scene.ts: 提取 _runSystemPhase() 消除 update/lateUpdate 重复代码
- World.ts: 可选链简化、提取 _isSceneCleanupCandidate() 消除重复条件
- Entity.ts: 移除过度设计的 EntityComparer
- 清理方法内部冗余注释，保持代码自解释

文档改进:
- 为 core 包创建独立 README (中英文)
- 明确 ECS 框架可独立用于 Cocos/Laya 等引擎
- 添加 sparse-checkout 命令说明，支持只克隆 core 源码
- 主 README 添加 ECS 独立使用提示

2025-12-23 18:00:21 +08:00

4.4 KiB

Raw Blame History

@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 的脏标记优化
序列化	内置场景序列化和快照
服务容器	系统的依赖注入
性能监控	内置性能分析工具

文档

许可证

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

ESEngine 的一部分 · 可独立使用

4.4 KiB Raw Blame History Unescape Escape