+ 
+ 
@@ -27,37 +29,47 @@ --- -ESEngine is a cross-platform 2D game engine for creating games from a unified interface. It provides a comprehensive set of common tools so that developers can focus on making games without having to reinvent the wheel. +## Overview -Games can be exported to multiple platforms including Web browsers, WeChat Mini Games, and other mini-game platforms. +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. -## Free and Open Source +Export your games to multiple platforms including web browsers, WeChat Mini Games, and other mini-game platforms from a single codebase. -ESEngine is completely free and open source under the MIT license. No strings attached, no royalties. Your games are yours. +## Key Features -## 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 | -- **Data-Driven Architecture**: Built on Entity-Component-System (ECS) pattern for flexible and performant game logic -- **High-Performance Rendering**: Rust/WebAssembly 2D renderer with sprite batching and WebGL 2.0 backend -- **Visual Editor**: Cross-platform desktop editor with scene management, asset browser, and visual tools -- **Modular Design**: Use only what you need. Each feature is a separate module that can be included independently -- **Multi-Platform**: Deploy to Web, WeChat Mini Games, and more from a single codebase +## Tech Stack -## Getting the Engine +- **Runtime**: TypeScript, Rust, WebAssembly +- **Renderer**: WebGL 2.0, WGPU (planned) +- **Editor**: Tauri, React, Zustand +- **Physics**: Rapier2D +- **Build**: pnpm, Turborepo, Rollup -### Using npm +## License + +ESEngine is **free and open source** under the [MIT License](LICENSE). No royalties, no strings attached. + +## Installation + +### npm ```bash npm install @esengine/ecs-framework ``` -### Building from Source +### Editor -See [Building from Source](#building-from-source) for detailed instructions. - -### Editor Download - -Pre-built editor binaries are available on the [Releases](https://github.com/esengine/esengine/releases) page for Windows and macOS. +Download pre-built binaries from the [Releases](https://github.com/esengine/esengine/releases) page (Windows, macOS). ## Quick Start @@ -95,6 +107,7 @@ class MovementSystem extends EntitySystem { } } +// Initialize Core.create(); const scene = new Scene(); scene.addSystem(new MovementSystem()); @@ -106,20 +119,16 @@ player.addComponent(new Velocity()); Core.setScene(scene); // Game loop -let lastTime = 0; function gameLoop(currentTime: number) { - const deltaTime = (currentTime - lastTime) / 1000; - lastTime = currentTime; - - Core.update(deltaTime); + Core.update(currentTime / 1000); requestAnimationFrame(gameLoop); } requestAnimationFrame(gameLoop); ``` -## Modules +## Packages -ESEngine is organized into modular packages. Each feature has a runtime module and an optional editor extension. +ESEngine is organized as a monorepo with modular packages. ### Core @@ -130,13 +139,13 @@ ESEngine is organized into modular packages. Each feature has a runtime module a | `@esengine/engine` | Rust/WASM 2D renderer | | `@esengine/engine-core` | Engine module system and lifecycle management | -### Runtime Modules +### Runtime | Package | Description | |---------|-------------| | `@esengine/sprite` | 2D sprite rendering and animation | -| `@esengine/tilemap` | Tile-based map rendering with animation support | -| `@esengine/physics-rapier2d` | 2D physics simulation powered by Rapier | +| `@esengine/tilemap` | Tile-based map rendering | +| `@esengine/physics-rapier2d` | 2D physics simulation (Rapier) | | `@esengine/behavior-tree` | Behavior tree AI system | | `@esengine/blueprint` | Visual scripting runtime | | `@esengine/camera` | Camera control and management | @@ -150,12 +159,11 @@ ESEngine is organized into modular packages. Each feature has a runtime module a | Package | Description | |---------|-------------| | `@esengine/sprite-editor` | Sprite inspector and tools | -| `@esengine/tilemap-editor` | Visual tilemap editor with brush tools | -| `@esengine/physics-rapier2d-editor` | Physics collider visualization and editing | +| `@esengine/tilemap-editor` | Visual tilemap editor | +| `@esengine/physics-rapier2d-editor` | Physics collider visualization | | `@esengine/behavior-tree-editor` | Visual behavior tree editor | | `@esengine/blueprint-editor` | Visual scripting editor | -| `@esengine/material-editor` | Material and shader editor | -| `@esengine/shader-editor` | Shader code editor | +| `@esengine/material-editor` | Material editor | ### Platform @@ -167,65 +175,59 @@ ESEngine is organized into modular packages. Each feature has a runtime module a ## Editor -ESEngine Editor is a cross-platform desktop application built with Tauri and React. +The ESEngine Editor is a cross-platform desktop application built with Tauri and React. ### Features - Scene hierarchy and entity management -- Component inspector with custom editors -- Asset browser with drag-and-drop support -- Tilemap editor with paint, fill, and selection tools +- 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 support (English, Chinese) +- Localization (English, Chinese) ### Screenshot  -## Supported Platforms +## Platform Support | Platform | Runtime | Editor | -|----------|---------|--------| -| Web Browser | Yes | - | -| Windows | - | Yes | -| macOS | - | Yes | +|----------|:-------:|:------:| +| Web Browser | ✓ | - | +| Windows | - | ✓ | +| macOS | - | ✓ | | WeChat Mini Game | In Progress | - | | Playable Ads | Planned | - | | Android | Planned | - | | iOS | Planned | - | -| Windows Native | Planned | - | -| Other Platforms | Planned | - | ## Building from Source ### Prerequisites -- Node.js 18 or later -- pnpm 10 or later +- Node.js 18+ +- pnpm 10+ - Rust toolchain (for WASM renderer) - wasm-pack ### Setup ```bash -# Clone repository git clone https://github.com/esengine/esengine.git cd esengine -# Install dependencies pnpm install - -# Build all packages pnpm build -# Build WASM renderer (optional) +# Optional: Build WASM renderer pnpm build:wasm ``` -### Running the Editor +### Run Editor ```bash cd packages/editor-app @@ -236,11 +238,11 @@ pnpm tauri:dev ``` esengine/ -├── packages/ Engine packages (runtime, editor, platform) -├── docs/ Documentation source -├── examples/ Example projects -├── scripts/ Build utilities -└── thirdparty/ Third-party dependencies +├── packages/ # Engine packages (runtime, editor, platform) +├── docs/ # Documentation source +├── examples/ # Example projects +├── scripts/ # Build utilities +└── thirdparty/ # Third-party dependencies ``` ## Documentation @@ -259,10 +261,17 @@ esengine/ Contributions are welcome. Please read the contributing guidelines before submitting a pull request. 1. Fork the repository -2. Create a feature branch -3. Make changes with tests -4. Submit a pull request +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](LICENSE). + +--- + +
+ Made with ❤️ by the ESEngine team +
diff --git a/README_CN.md b/README_CN.md index 94e0f53c..1417657c 100644 --- a/README_CN.md +++ b/README_CN.md @@ -10,8 +10,10 @@
@@ -27,37 +29,47 @@ --- -ESEngine 是一个跨平台 2D 游戏引擎，提供统一的开发界面。它包含完整的常用工具集，让开发者专注于游戏创作本身。 +## 概述 -游戏可以导出到多个平台，包括 Web 浏览器、微信小游戏等小游戏平台。 +ESEngine 是一款基于现代 Web 技术从零构建的跨平台 2D 游戏引擎。它提供完整的工具集，让开发者专注于游戏创作而非基础设施搭建。 -## 免费开源 +一套代码即可导出到 Web 浏览器、微信小游戏等多个平台。 -ESEngine 基于 MIT 协议完全免费开源。无附加条件，无版税。你的游戏完全属于你。 +## 核心特性 -## 特性 +| 特性 | 描述 | +|-----|------| +| **ECS 架构** | 数据驱动的实体-组件-系统模式，提供灵活且缓存友好的游戏逻辑 | +| **高性能渲染** | Rust/WebAssembly 2D 渲染器，支持自动精灵批处理和 WebGL 2.0 | +| **可视化编辑器** | 基于 Tauri 的跨平台桌面编辑器，支持场景管理和资源工作流 | +| **模块化设计** | 按需引入，每个功能都是独立的包 | +| **多平台导出** | 一套代码部署到 Web、微信小游戏等平台 | +| **物理集成** | 基于 Rapier 的 2D 物理，支持编辑器可视化 | +| **可视化脚本** | 行为树和蓝图系统，适合策划使用 | -- **数据驱动架构**：基于 ECS（实体-组件-系统）模式构建，提供灵活高效的游戏逻辑 -- **高性能渲染**：Rust/WebAssembly 2D 渲染器，支持精灵批处理和 WebGL 2.0 -- **可视化编辑器**：跨平台桌面编辑器，包含场景管理、资源浏览器和可视化工具 -- **模块化设计**：按需使用，每个功能都是独立模块，可单独引入 -- **多平台支持**：一套代码部署到 Web、微信小游戏等多个平台 +## 技术栈 -## 获取引擎 +- **运行时**: TypeScript, Rust, WebAssembly +- **渲染器**: WebGL 2.0, WGPU (计划中) +- **编辑器**: Tauri, React, Zustand +- **物理**: Rapier2D +- **构建**: pnpm, Turborepo, Rollup -### 通过 npm 安装 +## 许可证 + +ESEngine **完全免费开源**，采用 [MIT 协议](LICENSE)。无版税，无附加条件。 + +## 安装 + +### npm ```bash npm install @esengine/ecs-framework ``` -### 从源码构建 +### 编辑器 -详见 [从源码构建](#从源码构建) 章节。 - -### 编辑器下载 - -预编译的编辑器可在 [Releases](https://github.com/esengine/esengine/releases) 页面下载，支持 Windows 和 macOS。 +从 [Releases](https://github.com/esengine/esengine/releases) 页面下载预编译版本（支持 Windows、macOS）。 ## 快速开始 @@ -95,6 +107,7 @@ class MovementSystem extends EntitySystem { } } +// 初始化 Core.create(); const scene = new Scene(); scene.addSystem(new MovementSystem()); @@ -106,12 +119,8 @@ player.addComponent(new Velocity()); Core.setScene(scene); // 游戏循环 -let lastTime = 0; function gameLoop(currentTime: number) { - const deltaTime = (currentTime - lastTime) / 1000; - lastTime = currentTime; - - Core.update(deltaTime); + Core.update(currentTime / 1000); requestAnimationFrame(gameLoop); } requestAnimationFrame(gameLoop); @@ -119,7 +128,7 @@ requestAnimationFrame(gameLoop); ## 模块 -ESEngine 采用模块化组织。每个功能都有运行时模块和可选的编辑器扩展。 +ESEngine 采用 Monorepo 组织，包含多个模块化包。 ### 核心 @@ -130,13 +139,13 @@ ESEngine 采用模块化组织。每个功能都有运行时模块和可选的 | `@esengine/engine` | Rust/WASM 2D 渲染器 | | `@esengine/engine-core` | 引擎模块系统和生命周期管理 | -### 运行时模块 +### 运行时 | 包名 | 描述 | |------|------| | `@esengine/sprite` | 2D 精灵渲染和动画 | -| `@esengine/tilemap` | Tilemap 渲染，支持动画 | -| `@esengine/physics-rapier2d` | 基于 Rapier 的 2D 物理模拟 | +| `@esengine/tilemap` | Tilemap 渲染 | +| `@esengine/physics-rapier2d` | 2D 物理模拟 (Rapier) | | `@esengine/behavior-tree` | 行为树 AI 系统 | | `@esengine/blueprint` | 可视化脚本运行时 | | `@esengine/camera` | 相机控制和管理 | @@ -150,12 +159,11 @@ ESEngine 采用模块化组织。每个功能都有运行时模块和可选的 | 包名 | 描述 | |------|------| | `@esengine/sprite-editor` | 精灵检视器和工具 | -| `@esengine/tilemap-editor` | 可视化 Tilemap 编辑器，支持笔刷工具 | -| `@esengine/physics-rapier2d-editor` | 物理碰撞体可视化和编辑 | +| `@esengine/tilemap-editor` | 可视化 Tilemap 编辑器 | +| `@esengine/physics-rapier2d-editor` | 物理碰撞体可视化 | | `@esengine/behavior-tree-editor` | 可视化行为树编辑器 | | `@esengine/blueprint-editor` | 可视化脚本编辑器 | -| `@esengine/material-editor` | 材质和着色器编辑器 | -| `@esengine/shader-editor` | 着色器代码编辑器 | +| `@esengine/material-editor` | 材质编辑器 | ### 平台 @@ -172,9 +180,9 @@ ESEngine 编辑器是基于 Tauri 和 React 构建的跨平台桌面应用。 ### 功能 - 场景层级和实体管理 -- 组件检视器，支持自定义编辑器 +- 组件检视器，支持自定义属性编辑器 - 资源浏览器，支持拖放 -- Tilemap 编辑器，支持绘制、填充、选择工具 +- Tilemap 编辑器，支持绘制和填充工具 - 行为树可视化编辑器 - 蓝图可视化脚本 - 材质和着色器编辑 @@ -185,43 +193,37 @@ ESEngine 编辑器是基于 Tauri 和 React 构建的跨平台桌面应用。  -## 支持的平台 +## 平台支持 | 平台 | 运行时 | 编辑器 | -|------|--------|--------| -| Web 浏览器 | 支持 | - | -| Windows | - | 支持 | -| macOS | - | 支持 | +|------|:------:|:------:| +| Web 浏览器 | ✓ | - | +| Windows | - | ✓ | +| macOS | - | ✓ | | 微信小游戏 | 开发中 | - | | Playable 可玩广告 | 计划中 | - | | Android | 计划中 | - | | iOS | 计划中 | - | -| Windows 原生 | 计划中 | - | -| 其他平台 | 计划中 | - | ## 从源码构建 ### 前置要求 -- Node.js 18 或更高版本 -- pnpm 10 或更高版本 +- Node.js 18+ +- pnpm 10+ - Rust 工具链（用于 WASM 渲染器） - wasm-pack ### 安装 ```bash -# 克隆仓库 git clone https://github.com/esengine/esengine.git cd esengine -# 安装依赖 pnpm install - -# 构建所有包 pnpm build -# 构建 WASM 渲染器（可选） +# 可选：构建 WASM 渲染器 pnpm build:wasm ``` @@ -236,11 +238,11 @@ pnpm tauri:dev ``` esengine/ -├── packages/ 引擎包（运行时、编辑器、平台） -├── docs/ 文档源码 -├── examples/ 示例项目 -├── scripts/ 构建工具 -└── thirdparty/ 第三方依赖 +├── packages/ # 引擎包（运行时、编辑器、平台） +├── docs/ # 文档源码 +├── examples/ # 示例项目 +├── scripts/ # 构建工具 +└── thirdparty/ # 第三方依赖 ``` ## 文档 @@ -260,10 +262,17 @@ esengine/ 欢迎贡献代码。提交 PR 前请阅读贡献指南。 1. Fork 仓库 -2. 创建功能分支 -3. 修改代码并测试 -4. 提交 PR +2. 创建功能分支 (`git checkout -b feature/amazing-feature`) +3. 提交修改 (`git commit -m 'Add amazing feature'`) +4. 推送分支 (`git push origin feature/amazing-feature`) +5. 发起 Pull Request ## 许可证 ESEngine 基于 [MIT 协议](LICENSE) 开源。 + +--- + +
+ 由 ESEngine 团队用 ❤️ 打造 +
diff --git a/docs/guide/hierarchy.md b/docs/guide/hierarchy.md index cd985e4c..79a470d3 100644 --- a/docs/guide/hierarchy.md +++ b/docs/guide/hierarchy.md @@ -6,7 +6,7 @@ ### 为什么不在 Entity 中内置层级？ -传统的游戏对象模型（如 Unity 的 GameObject）将层级关系内置于实体中。ECS Framework 选择组件化方案的原因： +传统的游戏对象模型将层级关系内置于实体中。ECS Framework 选择组件化方案的原因： 1. **ECS 组合原则**：层级是一种"功能"，应该通过组件添加，而非所有实体都具备 2. **按需使用**：只有需要层级关系的实体才添加 `HierarchyComponent` diff --git a/packages/engine-core/src/SortingLayer.ts b/packages/engine-core/src/SortingLayer.ts index f118d9e0..6b894811 100644 --- a/packages/engine-core/src/SortingLayer.ts +++ b/packages/engine-core/src/SortingLayer.ts @@ -2,8 +2,8 @@ * 排序层系统 - 控制渲染顺序 * Sorting Layer System - Controls render order * - * 类似 Unity 的 Sorting Layer + Order in Layer 系统。 - * Similar to Unity's Sorting Layer + Order in Layer system. + * 提供排序层和层内排序功能，用于精确控制 2D 对象的渲染顺序。 + * Provides sorting layer and order-in-layer functionality for precise 2D rendering order control. * * @example * ```typescript diff --git a/packages/particle/src/ClickFxComponent.ts b/packages/particle/src/ClickFxComponent.ts index 9e9d20f1..9b5d8ccc 100644 --- a/packages/particle/src/ClickFxComponent.ts +++ b/packages/particle/src/ClickFxComponent.ts @@ -2,9 +2,6 @@ * 点击特效组件 - 在点击位置播放粒子效果 * Click FX Component - Play particle effects at click position * - * 类似 Unity 的 ShowFxWhenClicked 功能。 - * Similar to Unity's ShowFxWhenClicked functionality. - * * @example * ```typescript * // 在编辑器中添加此组件到相机或空实体上 diff --git a/packages/sdk/package.json b/packages/sdk/package.json index 72f46f1f..ab3bbbdd 100644 --- a/packages/sdk/package.json +++ b/packages/sdk/package.json @@ -1,7 +1,7 @@ { "name": "@esengine/sdk", "version": "1.0.0", - "description": "Unified SDK entry point for ESEngine - like Unity's 'using UnityEngine'", + "description": "Unified SDK entry point for ESEngine - single import for all engine modules", "main": "dist/index.js", "module": "dist/index.js", "types": "dist/index.d.ts",