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 Particles guide (ParticleEmitter + Res(Particle))

yhh5ad147160a51
diff --git a/docs/astro/astro.config.mjs b/docs/astro/astro.config.mjs
index f51558e33..249420e18 100644
--- a/docs/astro/astro.config.mjs
+++ b/docs/astro/astro.config.mjs
@@ -54,6 +54,7 @@ export default defineConfig({
{ label: 'Tilemaps', translations: { 'zh-CN': '瓦片地图' }, slug: 'guides/tilemap' },
{ label: 'UI', translations: { 'zh-CN': 'UI' }, slug: 'guides/ui' },
{ label: 'Audio', translations: { 'zh-CN': '音频' }, slug: 'guides/audio' },
+ { label: 'Particles', translations: { 'zh-CN': '粒子' }, slug: 'guides/particle' },
{ label: 'Assets', translations: { 'zh-CN': '资源' }, slug: 'guides/assets' },
{ label: 'WeChat MiniGame', translations: { 'zh-CN': '微信小游戏' }, slug: 'guides/wechat' },
],
diff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/guides/particle.mdx
new file mode 100644
index 000000000..edc70a9b3
--- /dev/null
+++ b/docs/astro/src/content/docs/guides/particle.mdx
@@ -0,0 +1,41 @@
+---
+title: Particles
+description: Configure effects with the ParticleEmitter component and Res(Particle).
+---
+
+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.
+
+## The `ParticleEmitter` component
+
+Everything is data-driven; tune it in the inspector. Key fields:
+
+- **Emission** — `rate`, `burstCount`, `burstInterval`, `duration`, `looping`,
+ `playOnStart`, `maxParticles`.
+- **Lifetime & motion** — `lifetimeMin` / `lifetimeMax`, `speedMin` / `speedMax`,
+ `gravity`, `damping`, `angleSpreadMin` / `angleSpreadMax`.
+- **Appearance** — `startSize*` / `endSize*` (+ `sizeEasing`), `startColor` /
+ `endColor` (+ `colorEasing`), `blendMode`, `layer`.
+- **Shape** — `shape`, `shapeRadius`, `shapeSize`, `shapeAngle` (where particles
+ spawn from).
+- **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:
+
+```typescript
+import { defineSystem, Res, Particle } from 'esengine';
+
+const control = defineSystem([Res(Particle)], (particle) => {
+ particle.play(entity); // start emitting
+ particle.stop(entity); // stop emitting; existing particles finish out
+ particle.reset(entity); // clear all particles immediately
+ const alive = particle.getAliveCount(entity);
+});
+```
diff --git a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
new file mode 100644
index 000000000..79cea93b6
--- /dev/null
+++ b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
@@ -0,0 +1,38 @@
+---
+title: 粒子
+description: 用 ParticleEmitter 组件和 Res(Particle) 配置特效。
+---
+
+Estella 在 CPU 上模拟粒子,并用 GPU 实例化渲染。给实体加一个 `ParticleEmitter`
+组件——通常在编辑器里——再用 `Particle` 资源从系统里控制播放。
+
+## `ParticleEmitter` 组件
+
+一切都是数据驱动的,在检视面板里调。关键字段:
+
+- **发射** —— `rate`、`burstCount`、`burstInterval`、`duration`、`looping`、
+ `playOnStart`、`maxParticles`。
+- **生命周期与运动** —— `lifetimeMin` / `lifetimeMax`、`speedMin` / `speedMax`、
+ `gravity`、`damping`、`angleSpreadMin` / `angleSpreadMax`。
+- **外观** —— `startSize*` / `endSize*`(+ `sizeEasing`)、`startColor` /
+ `endColor`(+ `colorEasing`)、`blendMode`、`layer`。
+- **形状** —— `shape`、`shapeRadius`、`shapeSize`、`shapeAngle`(粒子从哪里生成)。
+- **贴图 / 精灵表** —— `texture`、`spriteColumns`、`spriteRows`、`spriteFPS`、
+ `spriteLoop`。
+
+设了 `playOnStart` 后,实体一激活发射器就运行。
+
+## 控制播放
+
+读取 `Particle` 资源来启动、停止或清空一个发射器,并读取它的存活粒子数:
+
+```typescript
+import { defineSystem, Res, Particle } from 'esengine';
+
+const control = defineSystem([Res(Particle)], (particle) => {
+ particle.play(entity); // 开始发射
+ particle.stop(entity); // 停止发射;已有粒子自然消亡
+ particle.reset(entity); // 立即清空所有粒子
+ const alive = particle.getAliveCount(entity);
+});
+```