esengine/packages/core/README.md

@esengine/ecs-framework

High-performance ECS Framework for JavaScript Game Engines

English | 中文

---

Overview

A standalone, zero-dependency ECS (Entity-Component-System) framework designed for use with any JavaScript game engine:

• Cocos Creator
• Laya
• Egret
• Phaser
• Or your own engine

This package is the core of ESEngine, but can be used completely independently.

Installation

npm / pnpm / yarn

npm install @esengine/ecs-framework

Clone Source Code Only

If you only want the ECS framework source code (not the full ESEngine):

# Step 1: Clone repo skeleton without downloading files (requires Git 2.25+)
git clone --filter=blob:none --sparse https://github.com/esengine/esengine.git

# Step 2: Enter directory
cd esengine

# Step 3: Specify which folder to checkout
git sparse-checkout set packages/core

# Now you only have packages/core/ - other folders are not downloaded

Quick Start

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

// Define components (pure data)
@ECSComponent('Position')
class Position extends Component {
    x = 0;
    y = 0;
}

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

// Define system (logic)
@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;
        }
    }
}

// Initialize
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);

// Game loop (integrate with your engine's loop)
function update(dt: number) {
    Core.update(dt);
}

Integration Examples

With 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();
        // Register your systems...
        Core.setScene(this.scene);
    }

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

With 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);
    }
}

Features

Feature	Description
Zero Dependencies	No external runtime dependencies
Type-Safe Queries	Fluent API with full TypeScript support
Change Detection	Epoch-based dirty tracking for optimization
Serialization	Built-in scene serialization and snapshots
Service Container	Dependency injection for systems
Performance Monitoring	Built-in profiling tools

Documentation

• API Reference
• Architecture Guide
• Full ESEngine Documentation

License

MIT License - Use freely in commercial and open source projects.

---

Part of ESEngine · Can be used standalone