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: flesh out the Particles guide with a complete emitter example

yhh270752285149
diff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/guides/particle.mdx
index fb4c518cb..968c7c91e 100644
--- a/docs/astro/src/content/docs/guides/particle.mdx
+++ b/docs/astro/src/content/docs/guides/particle.mdx
@@ -4,12 +4,42 @@ description: Configure effects with the ParticleEmitter component and Res(Partic
---
Estella simulates particles on the CPU and renders them GPU-instanced. Add a
-`ParticleEmitter` component to an entity — usually in the editor — and control
-playback from a system with the `Particle` resource.
+`ParticleEmitter` component to an entity — in the editor or in code — configure
+the emission, and control playback with the `Particle` resource.
-## The `ParticleEmitter` component
+## Create an emitter
-Everything is data-driven; tune it in the inspector. Key fields:
+This spawns a one-shot burst — a little puff of embers that fade from yellow to
+red and fall:
+
+```typescript
+import { defineSystem, Commands, Transform, ParticleEmitter } from 'esengine';
+
+const spawnBurst = defineSystem([Commands()], (cmds) => {
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ParticleEmitter, {
+ playOnStart: true,
+ looping: false,
+ burstCount: 60, // emit 60 particles at once
+ maxParticles: 128,
+ lifetimeMin: 0.4, lifetimeMax: 0.9,
+ speedMin: 120, speedMax: 260, // world units / second
+ startSizeMin: 6, startSizeMax: 12,
+ endSizeMin: 0, endSizeMax: 0, // shrink to nothing
+ startColor: { r: 1, g: 0.8, b: 0.2, a: 1 },
+ endColor: { r: 1, g: 0.2, b: 0.0, a: 0 }, // fade to transparent red
+ gravity: { x: 0, y: -200 },
+ });
+});
+```
+
+For a **continuous** effect (smoke, a fountain), set `looping: true` and drive it
+with `rate` (particles per second) instead of `burstCount`.
+
+## Key fields
+
+Everything is data-driven; tune it in the inspector or in the insert above:
- **Emission** — `rate`, `burstCount`, `burstInterval`, `duration`, `looping`,
`playOnStart`, `maxParticles`.
@@ -22,12 +52,10 @@ Everything is data-driven; tune it in the inspector. Key fields:
- **Texture / sprite sheet** — `texture`, `spriteColumns`, `spriteRows`,
`spriteFPS`, `spriteLoop`.
-With `playOnStart` set, the emitter runs as soon as the entity is active.
-
## Control playback
-Read the `Particle` resource to start, stop, or clear an emitter, and to read
-its live particle count:
+Read the `Particle` resource to start, stop, or clear an emitter, and to read its
+live particle count:
```typescript
import { defineSystem, Query, Res, ParticleEmitter, Particle } from 'esengine';
diff --git a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
index e1cef52e2..62d3c0c36 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
@@ -4,11 +4,40 @@ description: 用 ParticleEmitter 组件和 Res(Particle) 配置特效。
---
Estella 在 CPU 上模拟粒子,并用 GPU 实例化渲染。给实体加一个 `ParticleEmitter`
-组件——通常在编辑器里——再用 `Particle` 资源从系统里控制播放。
+组件——在编辑器里或用代码——配置发射,再用 `Particle` 资源控制播放。
-## `ParticleEmitter` 组件
+## 创建一个发射器
-一切都是数据驱动的,在检视面板里调。关键字段:
+下面生成一次性爆发——一小簇火星,从黄色渐变到红色并下落:
+
+```typescript
+import { defineSystem, Commands, Transform, ParticleEmitter } from 'esengine';
+
+const spawnBurst = defineSystem([Commands()], (cmds) => {
+ cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: 0, z: 0 } })
+ .insert(ParticleEmitter, {
+ playOnStart: true,
+ looping: false,
+ burstCount: 60, // 一次性发射 60 个粒子
+ maxParticles: 128,
+ lifetimeMin: 0.4, lifetimeMax: 0.9,
+ speedMin: 120, speedMax: 260, // 世界单位 / 秒
+ startSizeMin: 6, startSizeMax: 12,
+ endSizeMin: 0, endSizeMax: 0, // 收缩到消失
+ startColor: { r: 1, g: 0.8, b: 0.2, a: 1 },
+ endColor: { r: 1, g: 0.2, b: 0.0, a: 0 }, // 渐隐为透明红
+ gravity: { x: 0, y: -200 },
+ });
+});
+```
+
+要做**持续**效果(烟雾、喷泉),把 `looping` 设为 `true`,并用 `rate`(每秒粒子数)
+驱动它,而不是 `burstCount`。
+
+## 关键字段
+
+一切都是数据驱动的,在检视面板里或上面的 insert 里调:
- **发射** —— `rate`、`burstCount`、`burstInterval`、`duration`、`looping`、
`playOnStart`、`maxParticles`。
@@ -20,8 +49,6 @@ Estella 在 CPU 上模拟粒子,并用 GPU 实例化渲染。给实体加一个
- **贴图 / 精灵表** —— `texture`、`spriteColumns`、`spriteRows`、`spriteFPS`、
`spriteLoop`。
-设了 `playOnStart` 后,实体一激活发射器就运行。
-
## 控制播放
读取 `Particle` 资源来启动、停止或清空一个发射器,并读取它的存活粒子数: