Skip to content
View esengine's full-sized avatar
🌐
today is a good day
🌐
today is a good day

Block or report esengine

Block user

Prevent this user from interacting with your repositories and sending you notifications. Learn more about blocking users.

You must be logged in to block users.

Maximum 250 characters. Please don't include any personal information such as legal names or email addresses. Markdown supported. This note will be visible to only you.
Report abuse

Contact GitHub support about this user’s behavior. Learn more about reporting abuse.

Report abuse
esengine/README.md

ESEngine
ESEngine

Modular Game Framework for TypeScript

npm build license stars TypeScript

English | 中文

Documentation · API Reference · Examples


What is ESEngine?

ESEngine is a collection of engine-agnostic game development modules for TypeScript. Use them with Cocos Creator, Laya, Phaser, PixiJS, or any JavaScript game engine.

The core is a high-performance ECS (Entity-Component-System) framework, accompanied by optional modules for AI, networking, physics, and more.

npm install @esengine/ecs-framework

Features

Module Description Engine Required
ECS Core Entity-Component-System framework with reactive queries No
Behavior Tree AI behavior trees with visual editor support No
Blueprint Visual scripting system No
FSM Finite state machine No
Timer Timer and cooldown systems No
Spatial Spatial indexing and queries (QuadTree, Grid) No
Pathfinding A* and navigation mesh pathfinding No
Network Client/server networking with TSRPC No

All framework modules can be used standalone with any rendering engine.

Quick Start

Using CLI (Recommended)

The easiest way to add ECS to your existing project:

# In your project directory
npx @esengine/cli init

The CLI automatically detects your project type (Cocos Creator 2.x/3.x, LayaAir 3.x, or Node.js) and generates the necessary integration code.

Manual Setup

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

// Define components (data only)
@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);

// Integrate with your game loop
function gameLoop(currentTime: number) {
    Core.update(currentTime / 1000);
    requestAnimationFrame(gameLoop);
}
requestAnimationFrame(gameLoop);

Using with Other Engines

ESEngine's framework modules are designed to work alongside your preferred rendering engine:

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

        // Add ECS systems
        this.ecsScene.addSystem(new BehaviorTreeExecutionSystem());
        this.ecsScene.addSystem(new MyGameSystem());

        Core.setScene(this.ecsScene);
    }

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

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

Packages

Framework (Engine-Agnostic)

These packages have zero rendering dependencies and work with any engine:

npm install @esengine/ecs-framework      # Core ECS
npm install @esengine/behavior-tree      # AI behavior trees
npm install @esengine/blueprint          # Visual scripting
npm install @esengine/fsm                # State machines
npm install @esengine/timer              # Timers & cooldowns
npm install @esengine/spatial            # Spatial indexing
npm install @esengine/pathfinding        # Pathfinding
npm install @esengine/network            # Networking

ESEngine Runtime (Optional)

If you want a complete engine solution with rendering:

Category Packages
Core engine-core, asset-system, material-system
Rendering sprite, tilemap, particle, camera, mesh-3d
Physics physics-rapier2d
Platform platform-web, platform-wechat

Editor (Optional)

A visual editor built with Tauri for scene management:

  • Download from Releases
  • Supports behavior tree editing, tilemap painting, visual scripting

Project Structure

esengine/
├── packages/
│   ├── framework/          # Engine-agnostic modules (NPM publishable)
│   │   ├── core/          # ECS Framework
│   │   ├── math/          # Math utilities
│   │   ├── behavior-tree/ # AI behavior trees
│   │   ├── blueprint/     # Visual scripting
│   │   ├── fsm/           # Finite state machine
│   │   ├── timer/         # Timer system
│   │   ├── spatial/       # Spatial queries
│   │   ├── pathfinding/   # Pathfinding
│   │   ├── procgen/       # Procedural generation
│   │   └── network/       # Networking
│   │
│   ├── engine/            # ESEngine runtime
│   ├── rendering/         # Rendering modules
│   ├── physics/           # Physics modules
│   ├── editor/            # Visual editor
│   └── rust/              # WASM renderer
│
├── docs/                   # Documentation
└── examples/               # Examples

Building from Source

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

pnpm install
pnpm build

# Type check framework packages
pnpm type-check:framework

# Run tests
pnpm test

Documentation

Community

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

  1. Fork the repository
  2. Create a feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

ESEngine is licensed under the MIT License. Free for personal and commercial use.


Made with care by the ESEngine community

Pinned Loading

  1. esengine esengine Public

    ESEngine - High-performance TypeScript ECS Framework for Game Development

    TypeScript 488 132

  2. BehaviourTree-ai BehaviourTree-ai Public

    一个高性能的TypeScript AI系统库,包含行为树(Behavior Tree)、实用AI(Utility AI)和有限状态机(FSM),适用于Cocos/Laya

    TypeScript 134 50

  3. mvvm-ui-framework mvvm-ui-framework Public

    一个轻量级、高性能的MVVM UI数据管理框架,支持与任何UI库集成

    TypeScript 6 3

  4. ecs-editor-plugins ecs-editor-plugins Public

    Official and community plugins registry for ECS Framework Editor

    JavaScript 1