Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

docs: add v0.8.0 changelog, particle guide, and reorganize sidebar

esenginedfbdfcac5f00
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index 3fb7656b0..5a86d20b8 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -93,22 +93,41 @@ export default defineConfig({
{ label: 'Masking & SafeArea', translations: { 'zh-CN': '遮罩与安全区' }, slug: 'guides/ui-masking' },
],
},
- { label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
- { label: 'Asset Loading', translations: { 'zh-CN': '资源加载' }, slug: 'guides/assets' },
- { label: 'Materials & Shaders', translations: { 'zh-CN': '材质与着色器' }, slug: 'guides/materials' },
- { label: 'Geometry & Meshes', translations: { 'zh-CN': '几何体与网格' }, slug: 'guides/geometry' },
- { label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
- { label: 'Profiler', translations: { 'zh-CN': '性能分析' }, slug: 'guides/profiler' },
- { label: 'Debugging', translations: { 'zh-CN': '调试' }, slug: 'guides/debugging' },
- { label: 'Game View', translations: { 'zh-CN': 'Game View' }, slug: 'guides/game-view' },
- { label: 'Project Settings', translations: { 'zh-CN': '项目设置' }, slug: 'guides/project-settings' },
- { label: 'Editor Extensions', translations: { 'zh-CN': '编辑器扩展' }, slug: 'guides/editor-extensions' },
+ {
+ label: 'Audio & Effects',
+ translations: { 'zh-CN': '音频与特效' },
+ items: [
+ { label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
+ { label: 'Particles', translations: { 'zh-CN': '粒子系统' }, slug: 'guides/particles' },
+ { label: 'Physics', translations: { 'zh-CN': '物理' }, slug: 'guides/physics' },
+ ],
+ },
+ {
+ label: 'Assets & Materials',
+ translations: { 'zh-CN': '资源与材质' },
+ items: [
+ { label: 'Asset Loading', translations: { 'zh-CN': '资源加载' }, slug: 'guides/assets' },
+ { label: 'Materials & Shaders', translations: { 'zh-CN': '材质与着色器' }, slug: 'guides/materials' },
+ { label: 'Geometry & Meshes', translations: { 'zh-CN': '几何体与网格' }, slug: 'guides/geometry' },
+ ],
+ },
+ {
+ label: 'Editor',
+ translations: { 'zh-CN': '编辑器' },
+ items: [
+ { label: 'Game View', translations: { 'zh-CN': 'Game View' }, slug: 'guides/game-view' },
+ { label: 'Project Settings', translations: { 'zh-CN': '项目设置' }, slug: 'guides/project-settings' },
+ { label: 'Editor Extensions', translations: { 'zh-CN': '编辑器扩展' }, slug: 'guides/editor-extensions' },
+ { label: 'Profiler', translations: { 'zh-CN': '性能分析' }, slug: 'guides/profiler' },
+ { label: 'Debugging', translations: { 'zh-CN': '调试' }, slug: 'guides/debugging' },
+ ],
+ },
{ label: 'Plugins', translations: { 'zh-CN': '插件系统' }, slug: 'guides/plugins' },
- { label: 'Building', translations: { 'zh-CN': '构建' }, slug: 'guides/building' },
{
- label: 'Platforms',
- translations: { 'zh-CN': '平台' },
+ label: 'Build & Deploy',
+ translations: { 'zh-CN': '构建与部署' },
items: [
+ { label: 'Building', translations: { 'zh-CN': '构建' }, slug: 'guides/building' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
{ label: 'Playable Ads', translations: { 'zh-CN': '可玩广告' }, slug: 'guides/playable-ads' },
],
@@ -119,6 +138,7 @@ export default defineConfig({
label: 'Changelog',
translations: { 'zh-CN': '更新日志' },
items: [
+ { label: 'v0.8.0', slug: 'changelog-v080' },
{ label: 'v0.7.0', slug: 'changelog-v070' },
{ label: 'v0.6.2', slug: 'changelog-v062' },
{ label: 'v0.6.1', slug: 'changelog-v061' },
diff --git a/docs/astro/src/content/docs/changelog-v080.mdx b/docs/astro/src/content/docs/changelog-v080.mdx
new file mode 100644
index 000000000..823f66749
--- /dev/null
+++ b/docs/astro/src/content/docs/changelog-v080.mdx
@@ -0,0 +1,41 @@
+---
+title: v0.8.0
+description: ESEngine v0.8.0 release notes
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.0 introduces the Particle System — a GPU-instanced 2D particle emitter with full editor integration, custom material support, and UI mask compatibility.
+</Aside>
+
+## Particle System
+
+A flexible 2D particle emitter built on instanced rendering, with a complete C++ simulation backend and TypeScript API.
+
+- **`ParticleEmitter` component** — attach to any entity with 40+ configurable properties covering emission rate, burst, lifetime, shape, velocity, size, color, rotation, forces, sprite sheet animation, and blend mode
+- **4 emission shapes** — Point, Circle, Rectangle, and Cone, each with dedicated editor gizmo visualization showing the emission area in the Scene View
+- **Size & color over lifetime** — start/end ranges with 4 easing modes (Linear, EaseIn, EaseOut, EaseInOut) for smooth transitions
+- **Custom material support** — assign per-emitter materials via `getMaterialDataWithUniforms`, enabling custom shaders on particles
+- **Scissor clip (UIMask) compatibility** — particles respect `UIMask` clipping regions, making them usable inside scrollable UI panels
+- **Simulation space** — choose between World and Local space; local-space particles follow their parent entity's transform
+- **Sprite sheet animation** — configure columns, rows, FPS, and loop for animated particle textures
+- **Runtime API** — `Particle.play(entity)`, `Particle.stop(entity)`, `Particle.reset(entity)`, `Particle.getAliveCount(entity)`
+- **Editor inspector** — properties organized into logical groups (Emission, Lifetime, Shape, Velocity, Size, Color, Rotation, Forces, Texture, Rendering) with constrained inputs
+- **Particle overlay gizmo** — real-time shape visualization in Scene View with zoom-aware rendering, showing Point crosshairs, Circle outlines, Rectangle bounds, or Cone angle spreads
+
+## Bug Fixes
+
+### Editor
+
+- Fix rotation gizmo instability for UIRect entities with non-center pivots — pin entity world position at drag start to prevent feedback loop between rotation and pivot-adjusted position recalculation
+- Fix particles not rendering in editor Game View — add missing `Renderer.submitParticles()` call in `GameViewRenderer.renderAndCapture()`
+
+### Build
+
+- Fix playable (single-HTML) builds failing to preload audio — route audio preload through `RuntimeAssetProvider` to read inline base64 data instead of using `fetch()` on `file://` protocol
+- Include `AudioPlugin` and `ParticlePlugin` in playable builds — add `AudioSource` and `ParticleEmitter` to `COMPONENT_TO_PLUGIN` mapping and always-include both plugins alongside `AnimationPlugin`
+
+## Testing
+
+- Add particle system unit tests covering emitter lifecycle, emission rate, burst mode, shape distribution, size/color interpolation, forces, and sprite sheet animation
diff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdx
index c4c88b988..5f1f8f122 100644
--- a/docs/astro/src/content/docs/guides/audio.mdx
+++ b/docs/astro/src/content/docs/guides/audio.mdx
@@ -97,6 +97,29 @@ Both `playSFX` and entity-based playback return an `AudioHandle`:
| `duration` | Total duration in seconds |
| `onEnd` | Optional callback invoked when playback finishes |
+## Audio Buses
+
+Every sound is routed through a **bus** — a virtual mixing channel. The engine provides 4 built-in buses, all connected to a `master` bus:
+
+| Bus | Default Volume | Typical Usage |
+|-----|---------------|---------------|
+| `sfx` | `1.0` | Sound effects: explosions, footsteps, UI clicks, one-shot sounds |
+| `music` | `0.8` | Background music and ambient loops |
+| `ui` | `1.0` | UI-specific sounds: button hover, panel open/close, notifications |
+| `voice` | `1.0` | Character dialogue, narration, voiceover |
+
+All 4 buses behave identically — they are simply independent volume/mute channels. The separation lets players adjust each category independently (e.g. lower music but keep SFX loud) via a settings menu:
+
+```
+master (1.0)
+├── sfx (1.0)
+├── music (0.8)
+├── ui (1.0)
+└── voice (1.0)
+```
+
+Set the bus on an `AudioSource` component or in `playSFX` config. If not specified, sounds default to the `sfx` bus.
+
## Volume Control
Control volume per bus via the mixer:
diff --git a/docs/astro/src/content/docs/guides/particles.mdx b/docs/astro/src/content/docs/guides/particles.mdx
new file mode 100644
index 000000000..8c3d8055a
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/particles.mdx
@@ -0,0 +1,256 @@
+---
+title: Particles
+description: 2D particle system in ESEngine
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+ESEngine provides a GPU-instanced 2D particle system with a C++ simulation backend. The `ParticlePlugin` is included by the engine by default.
+
+## ParticleEmitter Component
+
+Add `ParticleEmitter` to an entity with `Transform` to emit particles from that position.
+
+### General
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `enabled` | boolean | `true` | Component active |
+| `playOnStart` | boolean | `true` | Auto-play when entity loads |
+| `looping` | boolean | `true` | Restart after duration ends |
+| `duration` | number | `5` | Emission duration in seconds |
+
+### Emission
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rate` | number | `10` | Particles emitted per second |
+| `burstCount` | number | `0` | Particles emitted per burst (0 = disabled) |
+| `burstInterval` | number | `1` | Seconds between bursts |
+| `maxParticles` | number | `1000` | Maximum alive particles |
+
+### Lifetime
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `lifetimeMin` | number | `5` | Minimum particle lifetime (seconds) |
+| `lifetimeMax` | number | `5` | Maximum particle lifetime (seconds) |
+
+### Shape
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `shape` | number | `3` | Emission shape (see below) |
+| `shapeRadius` | number | `100` | Radius for Circle and Cone shapes |
+| `shapeSize` | Vec2 | `{100, 100}` | Width/height for Rectangle shape |
+| `shapeAngle` | number | `25` | Half-angle in degrees for Cone shape (0–360) |
+
+**Emission shapes:**
+
+| Value | Shape | Description |
+|-------|-------|-------------|
+| `0` | Point | Emit from a single point |
+| `1` | Circle | Emit from random positions within a circle |
+| `2` | Rectangle | Emit from random positions within a rectangle |
+| `3` | Cone | Emit in a directed cone from the emitter origin |
+
+### Velocity
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `speedMin` | number | `500` | Minimum initial speed |
+| `speedMax` | number | `500` | Maximum initial speed |
+| `angleSpreadMin` | number | `0` | Minimum emission angle (degrees, 0–360) |
+| `angleSpreadMax` | number | `360` | Maximum emission angle (degrees, 0–360) |
+
+### Size Over Lifetime
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `startSizeMin` | number | `100` | Minimum size at birth |
+| `startSizeMax` | number | `100` | Maximum size at birth |
+| `endSizeMin` | number | `100` | Minimum size at death |
+| `endSizeMax` | number | `100` | Maximum size at death |
+| `sizeEasing` | number | `0` | Interpolation curve (0=Linear, 1=EaseIn, 2=EaseOut, 3=EaseInOut) |
+
+### Color Over Lifetime
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `startColor` | Color | `{1,1,1,1}` | Color at birth (RGBA) |
+| `endColor` | Color | `{1,1,1,0}` | Color at death (RGBA, default fades out) |
+| `colorEasing` | number | `0` | Interpolation curve (0=Linear, 1=EaseIn, 2=EaseOut, 3=EaseInOut) |
+
+### Rotation
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `rotationMin` | number | `0` | Minimum initial rotation (degrees) |
+| `rotationMax` | number | `0` | Maximum initial rotation (degrees) |
+| `angularVelocityMin` | number | `0` | Minimum rotation speed (degrees/sec) |
+| `angularVelocityMax` | number | `0` | Maximum rotation speed (degrees/sec) |
+
+### Forces
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `gravity` | Vec2 | `{0, 0}` | Gravity force applied each frame |
+| `damping` | number | `0` | Velocity damping factor (friction) |
+
+### Texture & Sprite Sheet
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `texture` | TextureHandle | — | Particle texture |
+| `spriteColumns` | number | `1` | Sprite sheet column count |
+| `spriteRows` | number | `1` | Sprite sheet row count |
+| `spriteFPS` | number | `10` | Sprite sheet animation FPS |
+| `spriteLoop` | boolean | `true` | Loop sprite sheet animation |
+
+<Aside type="tip">
+For animated particles, use a sprite sheet texture and set `spriteColumns` and `spriteRows` to match the grid layout. The system automatically cycles through frames at the configured `spriteFPS`.
+</Aside>
+
+### Rendering
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `blendMode` | number | `1` | 0 = Normal, 1 = Additive (default) |
+| `layer` | number | `0` | Render order (-1000 to 1000) |
+| `material` | number | `0` | Custom material ID (0 = default) |
+| `simulationSpace` | number | `0` | 0 = World, 1 = Local |
+
+<Aside type="note">
+**World space** (default): particles are simulated in world coordinates — they stay in place even if the emitter entity moves. **Local space**: particles follow the emitter entity's transform.
+</Aside>
+
+## Runtime API
+
+Use the static `Particle` object to control emitters from code:
+
+```typescript
+import { Particle } from 'esengine';
+
+// Start emitting
+Particle.play(entity);
+
+// Stop emitting (existing particles continue their lifetime)
+Particle.stop(entity);
+
+// Reset emitter state and clear all alive particles
+Particle.reset(entity);
+
+// Query alive particle count
+const count = Particle.getAliveCount(entity);
+```
+
+## Controlling Emitter Properties
+
+Query and modify `ParticleEmitter` in a system:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, ParticleEmitter } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(ParticleEmitter))],
+ (query) => {
+ for (const [entity, emitter] of query) {
+ emitter.rate = 50;
+ emitter.startColor = { r: 1, g: 0.5, b: 0, a: 1 };
+ emitter.endColor = { r: 1, g: 0, b: 0, a: 0 };
+ emitter.gravity = { x: 0, y: -500 };
+ }
+ }
+));
+```
+
+## Custom Materials
+
+Assign a custom material to particles for special rendering effects:
+
+```typescript
+emitter.material = myMaterialHandle;
+```
+
+The particle renderer calls `getMaterialDataWithUniforms` on the assigned material, so any shader uniforms you define will be applied per-emitter.
+
+## UIMask Compatibility
+
+Particles respect `UIMask` scissor clipping. To use particles inside a scrollable UI panel:
+
+1. Add a `UIMask` component (Scissor mode) to the panel entity
+2. Place the `ParticleEmitter` entity as a child of the masked container
+3. Particles will be clipped to the mask region
+
+## Editor Integration
+
+- **Inspector** — properties are organized into collapsible groups (Emission, Lifetime, Shape, Velocity, Size, Color, Rotation, Forces, Texture, Rendering) with constrained numeric inputs
+- **Scene View overlay** — when a `ParticleEmitter` entity is selected, the Scene View draws the emission shape as a gizmo:
+ - **Point**: crosshair marker
+ - **Circle**: dashed circle outline
+ - **Rectangle**: dashed rectangle outline
+ - **Cone**: pie-slice showing the emission angle spread
+- **Hierarchy** — right-click → Create → Particle to add a new particle entity
+
+## Enums
+
+Use the named constants for readability:
+
+```typescript
+import { EmitterShape, SimulationSpace, ParticleEasing } from 'esengine';
+
+emitter.shape = EmitterShape.Circle;
+emitter.simulationSpace = SimulationSpace.Local;
+emitter.sizeEasing = ParticleEasing.EaseOut;
+emitter.colorEasing = ParticleEasing.EaseInOut;
+```
+
+| Enum | Values |
+|------|--------|
+| `EmitterShape` | `Point` (0), `Circle` (1), `Rectangle` (2), `Cone` (3) |
+| `SimulationSpace` | `World` (0), `Local` (1) |
+| `ParticleEasing` | `Linear` (0), `EaseIn` (1), `EaseOut` (2), `EaseInOut` (3) |
+
+## Example: Fire Effect
+
+```typescript
+import {
+ defineSystem, addSystem, Commands, Transform,
+ ParticleEmitter, EmitterShape, ParticleEasing
+} from 'esengine';
+
+addSystem(defineSystem(
+ [Commands],
+ (commands) => {
+ commands.spawn(
+ Transform.bundle({ position: { x: 400, y: 300, z: 0 } }),
+ ParticleEmitter.bundle({
+ rate: 30,
+ lifetimeMin: 0.5,
+ lifetimeMax: 1.5,
+ shape: EmitterShape.Circle,
+ shapeRadius: 20,
+ speedMin: 100,
+ speedMax: 200,
+ angleSpreadMin: 250,
+ angleSpreadMax: 290,
+ startSizeMin: 40,
+ startSizeMax: 60,
+ endSizeMin: 5,
+ endSizeMax: 10,
+ sizeEasing: ParticleEasing.EaseIn,
+ startColor: { r: 1, g: 0.8, b: 0.2, a: 1 },
+ endColor: { r: 1, g: 0.2, b: 0, a: 0 },
+ colorEasing: ParticleEasing.EaseOut,
+ gravity: { x: 0, y: -50 },
+ blendMode: 1,
+ }),
+ );
+ },
+ { runCondition: 'once' }
+));
+```
+
+<Aside type="tip">
+The particle simulation runs in the C++ backend. The TypeScript side only sets component data — the engine handles instanced rendering and per-particle updates automatically.
+</Aside>
diff --git a/docs/astro/src/content/docs/zh/changelog-v080.mdx b/docs/astro/src/content/docs/zh/changelog-v080.mdx
new file mode 100644
index 000000000..f5306261e
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/changelog-v080.mdx
@@ -0,0 +1,41 @@
+---
+title: v0.8.0
+description: ESEngine v0.8.0 更新日志
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside type="tip">
+v0.8.0 引入了粒子系统 — 基于 GPU 实例化渲染的 2D 粒子发射器,支持完整的编辑器集成、自定义材质和 UI 遮罩兼容。
+</Aside>
+
+## 粒子系统
+
+基于实例化渲染的 2D 粒子发射器,C++ 后端模拟 + TypeScript API。
+
+- **`ParticleEmitter` 组件** — 附加到任意实体,提供 40+ 可配置属性,涵盖发射速率、爆发、生命周期、形状、速度、大小、颜色、旋转、作用力、精灵表动画和混合模式
+- **4 种发射形状** — 点、圆形、矩形和锥形,每种形状在 Scene View 中都有专用的编辑器 Gizmo 可视化
+- **大小与颜色生命周期变化** — 起始/结束范围支持 4 种缓动模式(Linear、EaseIn、EaseOut、EaseInOut)
+- **自定义材质支持** — 通过 `getMaterialDataWithUniforms` 为每个发射器指定材质,支持自定义粒子着色器
+- **裁剪区域(UIMask)兼容** — 粒子遵守 `UIMask` 裁剪区域,可在可滚动 UI 面板内使用
+- **模拟空间** — 可选世界空间和本地空间;本地空间粒子跟随父实体变换
+- **精灵表动画** — 可配置列数、行数、FPS 和循环播放
+- **运行时 API** — `Particle.play(entity)`、`Particle.stop(entity)`、`Particle.reset(entity)`、`Particle.getAliveCount(entity)`
+- **编辑器检查器** — 属性按逻辑分组(发射、生命周期、形状、速度、大小、颜色、旋转、作用力、纹理、渲染),带约束输入
+- **粒子叠加 Gizmo** — Scene View 中实时显示形状可视化,自适应缩放,支持点十字、圆形轮廓、矩形边界和锥形角度展示
+
+## Bug 修复
+
+### 编辑器
+
+- 修复非中心锚点 UIRect 实体的旋转 Gizmo 不稳定问题 — 在拖拽开始时锁定实体世界坐标,防止旋转与锚点位置重算之间的反馈循环
+- 修复粒子在编辑器 Game View 中不渲染 — 在 `GameViewRenderer.renderAndCapture()` 中补充 `Renderer.submitParticles()` 调用
+
+### 构建
+
+- 修复 Playable(单 HTML)构建无法预加载音频 — 将音频预加载路由到 `RuntimeAssetProvider`,直接读取内联 base64 数据,避免在 `file://` 协议下使用 `fetch()`
+- Playable 构建中包含 `AudioPlugin` 和 `ParticlePlugin` — 将 `AudioSource` 和 `ParticleEmitter` 添加到 `COMPONENT_TO_PLUGIN` 映射,并始终随 `AnimationPlugin` 一起包含
+
+## 测试
+
+- 添加粒子系统单元测试,覆盖发射器生命周期、发射速率、爆发模式、形状分布、大小/颜色插值、作用力和精灵表动画
diff --git a/docs/astro/src/content/docs/zh/guides/audio.mdx b/docs/astro/src/content/docs/zh/guides/audio.mdx
index 2b5315c0e..dbead10bd 100644
--- a/docs/astro/src/content/docs/zh/guides/audio.mdx
+++ b/docs/astro/src/content/docs/zh/guides/audio.mdx
@@ -97,6 +97,29 @@ Audio.stopAll();
| `currentTime` | 当前播放位置(秒) |
| `duration` | 总时长(秒) |
+## 音频总线
+
+每个音频都通过一个**总线(bus)**路由——即一个虚拟混音通道。引擎提供 4 个内置总线,全部连接到 `master` 总线:
+
+| 总线 | 默认音量 | 典型用途 |
+|------|---------|---------|
+| `sfx` | `1.0` | 音效:爆炸、脚步声、UI 点击、一次性音效 |
+| `music` | `0.8` | 背景音乐和环境循环音 |
+| `ui` | `1.0` | UI 专用音效:按钮悬停、面板开关、通知音 |
+| `voice` | `1.0` | 角色对话、旁白、配音 |
+
+4 个总线行为完全一致——它们只是独立的音量/静音通道。这种分离让玩家可以在设置菜单中独立调节各类别音量(例如降低音乐但保持音效音量):
+
+```
+master (1.0)
+├── sfx (1.0)
+├── music (0.8)
+├── ui (1.0)
+└── voice (1.0)
+```
+
+通过 `AudioSource` 组件的 `bus` 属性或 `playSFX` 配置设置总线。未指定时默认使用 `sfx` 总线。
+
## 音量控制
通过混音器按总线控制音量:
diff --git a/docs/astro/src/content/docs/zh/guides/particles.mdx b/docs/astro/src/content/docs/zh/guides/particles.mdx
new file mode 100644
index 000000000..eae811bce
--- /dev/null
+++ b/docs/astro/src/content/docs/zh/guides/particles.mdx
@@ -0,0 +1,256 @@
+---
+title: 粒子系统
+description: ESEngine 中的 2D 粒子系统
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+ESEngine 提供基于 GPU 实例化渲染的 2D 粒子系统,使用 C++ 后端模拟。`ParticlePlugin` 由引擎默认包含。
+
+## ParticleEmitter 组件
+
+在带有 `Transform` 的实体上添加 `ParticleEmitter` 即可从该位置发射粒子。
+
+### 通用
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `enabled` | boolean | `true` | 组件激活 |
+| `playOnStart` | boolean | `true` | 实体加载时自动播放 |
+| `looping` | boolean | `true` | 持续时间结束后重新开始 |
+| `duration` | number | `5` | 发射持续时间(秒) |
+
+### 发射
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rate` | number | `10` | 每秒发射粒子数 |
+| `burstCount` | number | `0` | 每次爆发发射粒子数(0 = 禁用) |
+| `burstInterval` | number | `1` | 爆发间隔(秒) |
+| `maxParticles` | number | `1000` | 最大存活粒子数 |
+
+### 生命周期
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `lifetimeMin` | number | `5` | 最小粒子寿命(秒) |
+| `lifetimeMax` | number | `5` | 最大粒子寿命(秒) |
+
+### 形状
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `shape` | number | `3` | 发射形状(见下方) |
+| `shapeRadius` | number | `100` | 圆形和锥形的半径 |
+| `shapeSize` | Vec2 | `{100, 100}` | 矩形的宽高 |
+| `shapeAngle` | number | `25` | 锥形的半角(度,0–360) |
+
+**发射形状:**
+
+| 值 | 形状 | 说明 |
+|----|------|------|
+| `0` | 点 | 从单个点发射 |
+| `1` | 圆形 | 从圆形区域内随机位置发射 |
+| `2` | 矩形 | 从矩形区域内随机位置发射 |
+| `3` | 锥形 | 从发射器原点以锥形方向发射 |
+
+### 速度
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `speedMin` | number | `500` | 最小初始速度 |
+| `speedMax` | number | `500` | 最大初始速度 |
+| `angleSpreadMin` | number | `0` | 最小发射角度(度,0–360) |
+| `angleSpreadMax` | number | `360` | 最大发射角度(度,0–360) |
+
+### 大小随生命变化
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `startSizeMin` | number | `100` | 出生时最小尺寸 |
+| `startSizeMax` | number | `100` | 出生时最大尺寸 |
+| `endSizeMin` | number | `100` | 消亡时最小尺寸 |
+| `endSizeMax` | number | `100` | 消亡时最大尺寸 |
+| `sizeEasing` | number | `0` | 插值曲线(0=Linear, 1=EaseIn, 2=EaseOut, 3=EaseInOut) |
+
+### 颜色随生命变化
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `startColor` | Color | `{1,1,1,1}` | 出生时颜色(RGBA) |
+| `endColor` | Color | `{1,1,1,0}` | 消亡时颜色(RGBA,默认淡出) |
+| `colorEasing` | number | `0` | 插值曲线(0=Linear, 1=EaseIn, 2=EaseOut, 3=EaseInOut) |
+
+### 旋转
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `rotationMin` | number | `0` | 最小初始旋转角度(度) |
+| `rotationMax` | number | `0` | 最大初始旋转角度(度) |
+| `angularVelocityMin` | number | `0` | 最小旋转速度(度/秒) |
+| `angularVelocityMax` | number | `0` | 最大旋转速度(度/秒) |
+
+### 作用力
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `gravity` | Vec2 | `{0, 0}` | 每帧施加的重力 |
+| `damping` | number | `0` | 速度阻尼系数(摩擦) |
+
+### 纹理与精灵表
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `texture` | TextureHandle | — | 粒子纹理 |
+| `spriteColumns` | number | `1` | 精灵表列数 |
+| `spriteRows` | number | `1` | 精灵表行数 |
+| `spriteFPS` | number | `10` | 精灵表动画帧率 |
+| `spriteLoop` | boolean | `true` | 循环播放精灵表动画 |
+
+<Aside type="tip">
+使用精灵表纹理实现粒子动画:设置 `spriteColumns` 和 `spriteRows` 匹配网格布局,系统会按照 `spriteFPS` 自动循环帧。
+</Aside>
+
+### 渲染
+
+| 属性 | 类型 | 默认值 | 说明 |
+|------|------|--------|------|
+| `blendMode` | number | `1` | 0 = 正常, 1 = 叠加(默认) |
+| `layer` | number | `0` | 渲染层级(-1000 到 1000) |
+| `material` | number | `0` | 自定义材质 ID(0 = 默认) |
+| `simulationSpace` | number | `0` | 0 = 世界空间, 1 = 本地空间 |
+
+<Aside type="note">
+**世界空间**(默认):粒子在世界坐标中模拟——即使发射器实体移动,已发射的粒子仍保持原位。**本地空间**:粒子跟随发射器实体的变换。
+</Aside>
+
+## 运行时 API
+
+使用静态 `Particle` 对象从代码控制发射器:
+
+```typescript
+import { Particle } from 'esengine';
+
+// 开始发射
+Particle.play(entity);
+
+// 停止发射(已存在的粒子继续其生命周期)
+Particle.stop(entity);
+
+// 重置发射器状态并清除所有存活粒子
+Particle.reset(entity);
+
+// 查询存活粒子数
+const count = Particle.getAliveCount(entity);
+```
+
+## 控制发射器属性
+
+在系统中查询和修改 `ParticleEmitter`:
+
+```typescript
+import { defineSystem, addSystem, Query, Mut, ParticleEmitter } from 'esengine';
+
+addSystem(defineSystem(
+ [Query(Mut(ParticleEmitter))],
+ (query) => {
+ for (const [entity, emitter] of query) {
+ emitter.rate = 50;
+ emitter.startColor = { r: 1, g: 0.5, b: 0, a: 1 };
+ emitter.endColor = { r: 1, g: 0, b: 0, a: 0 };
+ emitter.gravity = { x: 0, y: -500 };
+ }
+ }
+));
+```
+
+## 自定义材质
+
+为粒子指定自定义材质以实现特殊渲染效果:
+
+```typescript
+emitter.material = myMaterialHandle;
+```
+
+粒子渲染器会对指定材质调用 `getMaterialDataWithUniforms`,因此你定义的任何 Shader Uniform 都会按发射器生效。
+
+## UIMask 兼容
+
+粒子遵守 `UIMask` 的裁剪区域。在可滚动 UI 面板中使用粒子:
+
+1. 在面板实体上添加 `UIMask` 组件(Scissor 模式)
+2. 将 `ParticleEmitter` 实体作为遮罩容器的子实体
+3. 粒子将被裁剪到遮罩区域内
+
+## 编辑器集成
+
+- **检查器** — 属性按可折叠分组展示(发射、生命周期、形状、速度、大小、颜色、旋转、作用力、纹理、渲染),数值输入带约束
+- **Scene View 叠加层** — 选中 `ParticleEmitter` 实体时,Scene View 会绘制发射形状的 Gizmo:
+ - **点**:十字标记
+ - **圆形**:虚线圆轮廓
+ - **矩形**:虚线矩形轮廓
+ - **锥形**:扇形展示发射角度范围
+- **Hierarchy** — 右键 → 创建 → Particle 可添加新的粒子实体
+
+## 枚举常量
+
+使用命名常量提高可读性:
+
+```typescript
+import { EmitterShape, SimulationSpace, ParticleEasing } from 'esengine';
+
+emitter.shape = EmitterShape.Circle;
+emitter.simulationSpace = SimulationSpace.Local;
+emitter.sizeEasing = ParticleEasing.EaseOut;
+emitter.colorEasing = ParticleEasing.EaseInOut;
+```
+
+| 枚举 | 值 |
+|------|-----|
+| `EmitterShape` | `Point` (0), `Circle` (1), `Rectangle` (2), `Cone` (3) |
+| `SimulationSpace` | `World` (0), `Local` (1) |
+| `ParticleEasing` | `Linear` (0), `EaseIn` (1), `EaseOut` (2), `EaseInOut` (3) |
+
+## 示例:火焰效果
+
+```typescript
+import {
+ defineSystem, addSystem, Commands, Transform,
+ ParticleEmitter, EmitterShape, ParticleEasing
+} from 'esengine';
+
+addSystem(defineSystem(
+ [Commands],
+ (commands) => {
+ commands.spawn(
+ Transform.bundle({ position: { x: 400, y: 300, z: 0 } }),
+ ParticleEmitter.bundle({
+ rate: 30,
+ lifetimeMin: 0.5,
+ lifetimeMax: 1.5,
+ shape: EmitterShape.Circle,
+ shapeRadius: 20,
+ speedMin: 100,
+ speedMax: 200,
+ angleSpreadMin: 250,
+ angleSpreadMax: 290,
+ startSizeMin: 40,
+ startSizeMax: 60,
+ endSizeMin: 5,
+ endSizeMax: 10,
+ sizeEasing: ParticleEasing.EaseIn,
+ startColor: { r: 1, g: 0.8, b: 0.2, a: 1 },
+ endColor: { r: 1, g: 0.2, b: 0, a: 0 },
+ colorEasing: ParticleEasing.EaseOut,
+ gravity: { x: 0, y: -50 },
+ blendMode: 1,
+ }),
+ );
+ },
+ { runCondition: 'once' }
+));
+```
+
+<Aside type="tip">
+粒子模拟在 C++ 后端运行。TypeScript 侧只需设置组件数据——引擎自动处理实例化渲染和逐粒子更新。
+</Aside>