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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.mjsindex 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.mdxnew file mode 100644index 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 animationdiff --git a/docs/astro/src/content/docs/guides/audio.mdx b/docs/astro/src/content/docs/guides/audio.mdxindex 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 ControlControl 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.mdxnew file mode 100644index 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.mdxnew file mode 100644index 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.mdxindex 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.mdxnew file mode 100644index 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>