CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor: reorganize package structure and decouple framework packages (#338)

Browse Source 
* refactor: reorganize package structure and decouple framework packages

## Package Structure Reorganization
- Reorganized 55 packages into categorized subdirectories:
  - packages/framework/ - Generic framework (Laya/Cocos compatible)
  - packages/engine/ - ESEngine core modules
  - packages/rendering/ - Rendering modules (WASM dependent)
  - packages/physics/ - Physics modules
  - packages/streaming/ - World streaming
  - packages/network-ext/ - Network extensions
  - packages/editor/ - Editor framework and plugins
  - packages/rust/ - Rust WASM engine
  - packages/tools/ - Build tools and SDK

## Framework Package Decoupling
- Decoupled behavior-tree and blueprint packages from ESEngine dependencies
- Created abstracted interfaces (IBTAssetManager, IBehaviorTreeAssetContent)
- ESEngine-specific code moved to esengine/ subpath exports
- Framework packages now usable with Cocos/Laya without ESEngine

## CI Configuration
- Updated CI to only type-check and lint framework packages
- Added type-check:framework and lint:framework scripts

## Breaking Changes
- Package import paths changed due to directory reorganization
- ESEngine integrations now use subpath imports (e.g., '@esengine/behavior-tree/esengine')

* fix: update es-engine file path after directory reorganization

* docs: update README to focus on framework over engine

* ci: only build framework packages, remove Rust/WASM dependencies

* fix: remove esengine subpath from behavior-tree and blueprint builds

ESEngine integration code will only be available in full engine builds.
Framework packages are now purely engine-agnostic.

* fix: move network-protocols to framework, build both in CI

* fix: update workflow paths from packages/core to packages/framework/core

* fix: exclude esengine folder from type-check in behavior-tree and blueprint

* fix: update network tsconfig references to new paths

* fix: add test:ci:framework to only test framework packages in CI

* fix: only build core and math npm packages in CI

* fix: exclude test files from CodeQL and fix string escaping security issue
This commit is contained in:
YHH
2025-12-26 14:50:35 +08:00
committed by GitHub
parent a84ff902e4
commit 155411e743
1936 changed files with 4147 additions and 11578 deletions
Download Patch File Download Diff File Expand all files Collapse all files

293
README.md
View File

@@ -5,7 +5,7 @@
</h1>
<p align="center">
<strong>Cross-platform 2D Game Engine</strong>
<strong>Modular Game Framework for TypeScript</strong>
</p>
<p align="center">
@@ -23,55 +23,35 @@
<p align="center">
<a href="https://esengine.cn/">Documentation</a> ·
<a href="https://esengine.cn/api/README">API Reference</a> ·
<a href="https://github.com/esengine/esengine/releases">Download Editor</a> ·
<a href="./examples/">Examples</a>
</p>
---
> **Just need ECS?** The core ECS framework [`@esengine/ecs-framework`](./packages/core/) can be used standalone with Cocos Creator, Laya, or any JS engine. [View ECS Documentation](./packages/core/README.md)
## What is ESEngine?
## Overview
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.
ESEngine is a cross-platform 2D game engine built from the ground up with modern web technologies. It provides a comprehensive toolset that enables developers to focus on creating games rather than building infrastructure.
Export your games to multiple platforms including web browsers, WeChat Mini Games, and other mini-game platforms from a single codebase.
## Key Features
| Feature | Description |
|---------|-------------|
| **ECS Architecture** | Data-driven Entity-Component-System pattern for flexible and cache-friendly game logic |
| **High-Performance Rendering** | Rust/WebAssembly 2D renderer with automatic sprite batching and WebGL 2.0 backend |
| **Visual Editor** | Cross-platform desktop editor built with Tauri for scene management and asset workflows |
| **Modular Design** | Import only what you need - each feature is a standalone package |
| **Multi-Platform Export** | Deploy to Web, WeChat Mini Games, and more from one codebase |
| **Physics Integration** | 2D physics powered by Rapier with editor visualization |
| **Visual Scripting** | Behavior trees and blueprint system for designers |
## Tech Stack
- **Runtime**: TypeScript, Rust, WebAssembly
- **Renderer**: WebGL 2.0, WGPU (planned)
- **Editor**: Tauri, React, Zustand
- **Physics**: Rapier2D
- **Build**: pnpm, Turborepo, Rollup
## License
ESEngine is **free and open source** under the [MIT License](LICENSE). No royalties, no strings attached.
## Installation
### npm
The core is a high-performance **ECS (Entity-Component-System)** framework, accompanied by optional modules for AI, networking, physics, and more.
```bash
npm install @esengine/ecs-framework
```
### Editor
## Features
Download pre-built binaries from the [Releases](https://github.com/esengine/esengine/releases) page (Windows, macOS).
| 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
@@ -81,6 +61,7 @@ import {
Matcher, Time, ECSComponent, ECSSystem
} from '@esengine/ecs-framework';
// Define components (data only)
@ECSComponent('Position')
class Position extends Component {
x = 0;
@@ -93,6 +74,7 @@ class Velocity extends Component {
dy = 0;
}
// Define system (logic)
@ECSSystem('Movement')
class MovementSystem extends EntitySystem {
constructor() {
@@ -120,7 +102,7 @@ player.addComponent(new Velocity());
Core.setScene(scene);
// Game loop
// Integrate with your game loop
function gameLoop(currentTime: number) {
Core.update(currentTime / 1000);
requestAnimationFrame(gameLoop);
@@ -128,109 +110,126 @@ function gameLoop(currentTime: number) {
requestAnimationFrame(gameLoop);
```
## Packages
## Using with Other Engines
ESEngine is organized as a monorepo with 50+ modular packages. Install only what you need.
ESEngine's framework modules are designed to work alongside your preferred rendering engine:
### Essential
### With Cocos Creator
```bash
npm install @esengine/ecs-framework # Core ECS (can be used standalone)
npm install @esengine/engine-core # Full engine with module system
```typescript
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);
}
}
```
### Popular Modules
### With Laya
```typescript
import { Core, Scene } from '@esengine/ecs-framework';
import { FSMSystem } from '@esengine/fsm';
class Main {
constructor() {
Core.create();
const scene = new Scene();
scene.addSystem(new FSMSystem());
Core.setScene(scene);
Laya.timer.frameLoop(1, this, this.update);
}
update() {
Core.update(Laya.timer.delta / 1000);
}
}
```
## Packages
### Framework (Engine-Agnostic)
These packages have **zero rendering dependencies** and work with any engine:
```bash
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 |
|----------|----------|
| **Rendering** | `sprite`, `tilemap`, `particle`, `mesh-3d`, `fairygui` |
| **Core** | `engine-core`, `asset-system`, `material-system` |
| **Rendering** | `sprite`, `tilemap`, `particle`, `camera`, `mesh-3d` |
| **Physics** | `physics-rapier2d` |
| **AI & Logic** | `behavior-tree`, `blueprint` |
| **Network** | `network`, `network-server` |
| **Platform** | `platform-web`, `platform-wechat` |
<details>
<summary><b>View all 50+ packages</b></summary>
### Editor (Optional)
#### Core
- `@esengine/ecs-framework` - ECS framework core
- `@esengine/math` - Vector, matrix utilities
- `@esengine/engine` - Rust/WASM renderer
- `@esengine/engine-core` - Module lifecycle
A visual editor built with Tauri for scene management:
#### Runtime
- `@esengine/sprite` - 2D sprites & animation
- `@esengine/tilemap` - Tile-based maps
- `@esengine/particle` - Particle effects
- `@esengine/physics-rapier2d` - 2D physics
- `@esengine/behavior-tree` - AI behavior trees
- `@esengine/blueprint` - Visual scripting
- `@esengine/camera` - Camera system
- `@esengine/audio` - Audio playback
- `@esengine/fairygui` - FairyGUI integration
- `@esengine/mesh-3d` - 3D mesh (FBX/GLTF/OBJ)
- `@esengine/material-system` - Materials & shaders
- `@esengine/asset-system` - Asset management
- `@esengine/world-streaming` - Large world streaming
- Download from [Releases](https://github.com/esengine/esengine/releases)
- Supports behavior tree editing, tilemap painting, visual scripting
#### Network
- `@esengine/network` - Client (TSRPC)
- `@esengine/network-server` - Server runtime
- `@esengine/network-protocols` - Shared protocols
## Project Structure
#### Editor Extensions
All runtime modules have corresponding `-editor` packages for visual editing.
#### Platform
- `@esengine/platform-common` - Platform abstraction
- `@esengine/platform-web` - Web runtime
- `@esengine/platform-wechat` - WeChat Mini Game
</details>
## Editor
The ESEngine Editor is a cross-platform desktop application built with Tauri and React.
### Features
- Scene hierarchy and entity management
- Component inspector with custom property editors
- Asset browser with drag-and-drop
- Tilemap editor with paint and fill tools
- Behavior tree visual editor
- Blueprint visual scripting
- Material and shader editing
- Built-in performance profiler
- Localization (English, Chinese)
### Screenshot
![ESEngine Editor](screenshots/main_screetshot.png)
## Platform Support
| Platform | Runtime | Editor |
|----------|:-------:|:------:|
| Web Browser | ✓ | - |
| Windows | - | ✓ |
| macOS | - | ✓ |
| WeChat Mini Game | In Progress | - |
| Playable Ads | Planned | - |
| Android | Planned | - |
| iOS | Planned | - |
```
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
### Prerequisites
- Node.js 18+
- pnpm 10+
- Rust toolchain (for WASM renderer)
- wasm-pack
### Setup
```bash
git clone https://github.com/esengine/esengine.git
cd esengine
@@ -238,54 +237,28 @@ cd esengine
pnpm install
pnpm build
# Optional: Build WASM renderer
pnpm build:wasm
# Type check framework packages
pnpm type-check:framework
# Run tests
pnpm test
```
### Run Editor
```bash
cd packages/editor-app
pnpm tauri:dev
```
### Project Structure
```
esengine/
├── packages/
│ ├── core/ # ECS Framework (@esengine/ecs-framework)
│ ├── math/ # Math library (@esengine/math)
│ ├── engine-core/ # Engine lifecycle management
│ ├── sprite/ # 2D sprite rendering
│ ├── tilemap/ # Tilemap system
│ ├── physics-rapier2d/ # Physics engine
│ ├── behavior-tree/ # AI behavior trees
│ ├── editor-app/ # Desktop editor (Tauri)
│ └── ... # Other modules
├── docs/ # Documentation source
├── examples/ # Example projects
├── scripts/ # Build utilities
└── thirdparty/ # Third-party dependencies
```
> **Looking for ECS source code?** The ECS framework is in `packages/core/`
## Documentation
- [Getting Started](https://esengine.cn/guide/getting-started.html)
- [Architecture Guide](https://esengine.cn/guide/)
- [ECS Framework Guide](./packages/framework/core/README.md)
- [Behavior Tree Guide](./packages/framework/behavior-tree/README.md)
- [API Reference](https://esengine.cn/api/README)
## Community
- [Discord](https://discord.gg/gCAgzXFW) - Chat with the community
- [GitHub Issues](https://github.com/esengine/esengine/issues) - Bug reports and feature requests
- [GitHub Discussions](https://github.com/esengine/esengine/discussions) - Questions and ideas
- [Discord](https://discord.gg/gCAgzXFW) - Chat with the community
## Contributing
Contributions are welcome. Please read the contributing guidelines before submitting a pull request.
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`)
@@ -295,10 +268,10 @@ Contributions are welcome. Please read the contributing guidelines before submit
## License
ESEngine is licensed under the [MIT License](LICENSE).
ESEngine is licensed under the [MIT License](LICENSE). Free for personal and commercial use.
---
<p align="center">
Made with ❤️ by the ESEngine team
Made with care by the ESEngine community
</p>