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.

feat(particle): add Noise/Turbulence and Sub-emitter modules

yhh0deb57e78c93
diff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/guides/particle.mdx
index ef6f0701b..20fac03e4 100644
--- a/docs/astro/src/content/docs/guides/particle.mdx
+++ b/docs/astro/src/content/docs/guides/particle.mdx
@@ -124,6 +124,17 @@ Where particles spawn and their initial direction. See [Emitter shapes](#emitter
| `gravity` | Vec2 | `{0, 0}` | Constant acceleration applied to every particle. |
| `damping` | number | `0` | Velocity drag per second (`0` = none). |
+### Noise & turbulence
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `noiseStrength` | number | `0` | Peak flow speed (px/s) the turbulence pushes particles at. `0` = module off. |
+| `noiseFrequency` | number | `0.01` | Spatial scale of the field — larger = tighter, busier swirls. |
+| `noiseScrollSpeed` | number | `0` | How fast the field drifts over time (`0` = a static field). |
+| `noiseOctaves` | number | `1` | Fractal detail layers. `1` = smooth flow; more = finer turbulence. |
+
+See [Noise & turbulence](#noise--turbulence-1) below.
+
### Size over life
| Property | Type | Default | Description |
@@ -173,6 +184,17 @@ Where particles spawn and their initial direction. See [Emitter shapes](#emitter
| `simulationSpace` | `SimulationSpace` | `World` | `World` or `Local` (see [below](#simulation-space)). |
| `enabled` | boolean | `true` | Disable to freeze and hide without removing the component. |
+### Sub-emitter
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `subEmitter` | entity | none | Child emitter entity fired when a particle triggers. `0`/unset = off. |
+| `subEmitterTrigger` | `SubEmitterTrigger` | `Death` | Fire on each particle's `Death` or `Birth`. |
+| `subEmitterChance` | number | `1` | Probability (0..1) a triggering particle fires the child. |
+| `subEmitterInheritVelocity` | number | `0` | Fraction of the parent particle's velocity passed to the sub-burst. |
+
+See [Sub-emitters](#sub-emitters) below.
+
## Emitter shapes
`EmitterShape` sets the spawn region and initial direction:
@@ -238,6 +260,85 @@ over each particle's life:
});
```
+## Noise & turbulence
+
+Straight-line particles look mechanical. The noise module layers a **curl-noise
+flow field** on top of velocity and gravity, so particles wander along smooth,
+swirling currents — smoke that curls, embers that flutter, magic that drifts.
+
+The field is *divergence-free* (it's the curl of a noise potential), which means
+particles never bunch into clumps or thin out into gaps the way a raw random jitter
+would — the motion stays even and organic. It's pure CPU math, identical on every
+platform (WeChat included), and completely free when `noiseStrength` is `0`.
+
+```typescript
+.insert(ParticleEmitter, {
+ // …emission, lifetime, color…
+ noiseStrength: 120, // how hard the current pushes (px/s)
+ noiseFrequency: 0.01, // smaller = broad, lazy swirls; larger = tight eddies
+ noiseScrollSpeed: 0.5, // let the field drift so the flow keeps evolving
+ noiseOctaves: 2, // 1 = smooth; more = finer, busier turbulence
+});
+```
+
+Tuning tips:
+
+- **`noiseStrength`** is the headline dial — start around a fraction of your
+ particles' `speed` and push up until the wander reads.
+- **`noiseFrequency`** sets the swirl size. Rising smoke likes small values
+ (`~0.005`); sparky, chaotic bursts like larger ones (`~0.03`).
+- **`noiseScrollSpeed` > 0** keeps a slow, static-looking plume alive; leave it `0`
+ for a fixed field that particles simply flow through.
+- **`noiseOctaves`** trades cost for detail — `1`–`2` covers most effects.
+
+## Sub-emitters
+
+A sub-emitter lets one emitter spawn *another* emitter's burst at a particle's
+position — the classic firework shell that rises and explodes, a rocket trailing
+smoke puffs, a spark that splits into embers. No per-frame code: you wire a
+reference and the sim fires the burst on the chosen event.
+
+The child is an **ordinary `ParticleEmitter` entity used as a template** — set
+`rate: 0` and `playOnStart: false` so it never emits on its own; it only fires when
+the parent triggers it. Its `burstCount` sets how many particles each sub-burst
+spawns. Point the parent's `subEmitter` at that child entity:
+
+```typescript
+import { SubEmitterTrigger } from 'esengine';
+
+// The burst template — a normal emitter that only fires when triggered.
+const shell = cmds.spawn()
+ .insert(Transform, {})
+ .insert(ParticleEmitter, {
+ rate: 0, playOnStart: false, burstCount: 44, // 44 sparks per burst
+ lifetimeMin: 0.6, lifetimeMax: 1.1, speedMin: 160, speedMax: 340,
+ startColor: { r: 1, g: 0.85, b: 0.35, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.1, a: 0 },
+ gravity: { x: 0, y: -150 },
+ }).id();
+
+// The rocket — on each particle's death, fire the shell burst at that spot.
+cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: -230, z: 0 } })
+ .insert(ParticleEmitter, {
+ rate: 2.5, lifetimeMin: 1.4, lifetimeMax: 1.8, speedMin: 560, speedMax: 660,
+ angleSpreadMin: 84, angleSpreadMax: 96,
+ subEmitter: shell,
+ subEmitterTrigger: SubEmitterTrigger.Death, // or Birth
+ subEmitterInheritVelocity: 0.15, // carry a little of the rocket's motion
+ });
+```
+
+- **`subEmitterTrigger`** — `Death` fires as each parent particle expires (shell
+ explosions, debris); `Birth` fires as each is born (a continuous shower of
+ sub-bursts along a stream).
+- **`subEmitterChance`** — set below `1` so only some particles fire the child,
+ thinning out a dense effect.
+- **`subEmitterInheritVelocity`** — pass a fraction of the parent particle's
+ velocity into the burst so the sparks fly *with* the rocket, not just outward.
+
+In the editor, `subEmitter` is an entity picker — drop in any emitter entity from
+the scene; the reference is remapped automatically when the scene loads.
+
## Simulation space
| Value | Particles follow the emitter? | Use for |
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 2490a4ca0..f67dd884b 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
@@ -115,6 +115,17 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {
| `gravity` | Vec2 | `{0, 0}` | 施加到每个粒子的恒定加速度。 |
| `damping` | number | `0` | 每秒速度阻尼(`0` = 无)。 |
+### 噪声与湍流 (Noise & turbulence)
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `noiseStrength` | number | `0` | 湍流推动粒子的峰值流速(px/s)。`0` = 关闭该模块。 |
+| `noiseFrequency` | number | `0.01` | 场的空间尺度 —— 越大漩涡越紧、越繁密。 |
+| `noiseScrollSpeed` | number | `0` | 场随时间漂移的速度(`0` = 静止场)。 |
+| `noiseOctaves` | number | `1` | 分形细节层数。`1` = 平滑流动;越多越细碎的湍流。 |
+
+见下文[噪声与湍流](#噪声与湍流-1)。
+
### 随生命的尺寸 (Size over life)
| 属性 | 类型 | 默认 | 说明 |
@@ -164,6 +175,17 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {
| `simulationSpace` | `SimulationSpace` | `World` | `World` 或 `Local`(见[下](#模拟空间))。 |
| `enabled` | boolean | `true` | 关掉即冻结并隐藏,而不移除组件。 |
+### 子发射器 (Sub-emitter)
+
+| 属性 | 类型 | 默认 | 说明 |
+|---|---|---|---|
+| `subEmitter` | entity | 无 | 粒子触发时发射的子发射器实体。`0`/未设 = 关闭。 |
+| `subEmitterTrigger` | `SubEmitterTrigger` | `Death` | 在每个粒子的 `Death`(死亡)或 `Birth`(出生)时触发。 |
+| `subEmitterChance` | number | `1` | 触发粒子发射子爆发的概率(0..1)。 |
+| `subEmitterInheritVelocity` | number | `0` | 传给子爆发的父粒子速度比例。 |
+
+见下文[子发射器](#子发射器-1)。
+
## 发射器形状
`EmitterShape` 设定生成区域与初始方向:
@@ -225,6 +247,75 @@ const recolor = defineSystem([Res(Particle)], (particles) => {
});
```
+## 噪声与湍流
+
+直线运动的粒子显得机械。噪声模块在速度和重力之上叠加一层 **curl 噪声流场**,
+让粒子沿着平滑、旋绕的气流游走 —— 卷曲的烟、飘动的火星、漂移的魔法。
+
+这个流场是*无散度*的(它是噪声势场的旋度),意味着粒子不会像原始随机抖动那样
+挤成一团或散出空洞 —— 运动始终均匀而自然。它是纯 CPU 数学,在每个平台
+(含微信)上逐字节一致,并且当 `noiseStrength` 为 `0` 时完全零开销。
+
+```typescript
+.insert(ParticleEmitter, {
+ // …发射、生命周期、颜色…
+ noiseStrength: 120, // 气流推力有多强(px/s)
+ noiseFrequency: 0.01, // 越小越是宽缓的漩涡;越大越是细密的涡流
+ noiseScrollSpeed: 0.5, // 让场漂移,使流动持续演化
+ noiseOctaves: 2, // 1 = 平滑;越多越细碎的湍流
+});
+```
+
+调参建议:
+
+- **`noiseStrength`** 是主旋钮 —— 从粒子 `speed` 的一小部分起调,逐步加大到游走感明显。
+- **`noiseFrequency`** 决定漩涡大小。上升的烟喜欢小值(`~0.005`);火花四溅的迸发喜欢大值(`~0.03`)。
+- **`noiseScrollSpeed` > 0** 能让看似静止的烟柱保持缓慢的活气;设 `0` 则是粒子穿流而过的固定场。
+- **`noiseOctaves`** 以开销换细节 —— `1`–`2` 已覆盖多数特效。
+
+## 子发射器
+
+子发射器让一个发射器在粒子所在位置生成*另一个*发射器的爆发 —— 经典的升空后爆炸的
+烟花弹、拖着烟雾的火箭、裂成火星的火花。无需逐帧代码:你连好一个引用,模拟就会在
+选定事件上触发爆发。
+
+子发射器是一个**当作模板用的普通 `ParticleEmitter` 实体** —— 设 `rate: 0` 和
+`playOnStart: false`,它就不会自己发射,只在父级触发时爆发。它的 `burstCount`
+决定每次子爆发生成多少粒子。把父级的 `subEmitter` 指向那个子实体:
+
+```typescript
+import { SubEmitterTrigger } from 'esengine';
+
+// 爆发模板 —— 一个只在被触发时才发射的普通发射器。
+const shell = cmds.spawn()
+ .insert(Transform, {})
+ .insert(ParticleEmitter, {
+ rate: 0, playOnStart: false, burstCount: 44, // 每次爆发 44 颗火星
+ lifetimeMin: 0.6, lifetimeMax: 1.1, speedMin: 160, speedMax: 340,
+ startColor: { r: 1, g: 0.85, b: 0.35, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.1, a: 0 },
+ gravity: { x: 0, y: -150 },
+ }).id();
+
+// 火箭 —— 每个粒子死亡时,在该处触发爆发。
+cmds.spawn()
+ .insert(Transform, { position: { x: 0, y: -230, z: 0 } })
+ .insert(ParticleEmitter, {
+ rate: 2.5, lifetimeMin: 1.4, lifetimeMax: 1.8, speedMin: 560, speedMax: 660,
+ angleSpreadMin: 84, angleSpreadMax: 96,
+ subEmitter: shell,
+ subEmitterTrigger: SubEmitterTrigger.Death, // 或 Birth
+ subEmitterInheritVelocity: 0.15, // 让火星带上一点火箭的运动
+ });
+```
+
+- **`subEmitterTrigger`** —— `Death` 在每个父粒子消亡时触发(炮弹爆炸、碎片);
+ `Birth` 在每个粒子出生时触发(沿着一道粒子流持续洒下子爆发)。
+- **`subEmitterChance`** —— 设为小于 `1`,只让部分粒子触发子级,稀释过密的效果。
+- **`subEmitterInheritVelocity`** —— 把父粒子速度的一部分带进爆发,让火星*随着*火箭飞,而不只是四散。
+
+在编辑器里,`subEmitter` 是一个实体选择器 —— 拖入场景中任意发射器实体即可;引用会在
+场景加载时自动重映射。
+
## 模拟空间
| 取值 | 粒子跟随发射器吗? | 用于 |
diff --git a/examples/particle-demo/README.md b/examples/particle-demo/README.md
index 23fe8e357..634821f5c 100644
--- a/examples/particle-demo/README.md
+++ b/examples/particle-demo/README.md
@@ -1,6 +1,6 @@
# Particle Effects
-A gallery of the engine's `ParticleEmitter`. Page through six composed effects
+A gallery of the engine's `ParticleEmitter`. Page through eight composed effects
with on-screen buttons, and click empty space to throw fireworks.
## Controls
@@ -15,9 +15,11 @@ with on-screen buttons, and click empty space to throw fireworks.
`Campfire` (fire + smoke + embers) · `Fireworks` (staggered colored bursts) ·
`Magic Portal` (a swirling ring) · `Fountain` (ballistic jet + mist) ·
-`Snowfall` (a wide, slow drift) · `Sparkles` (a twinkling field). Each mixes
-shape, velocity, colour/size-over-life, gravity, spin and blend mode — see
-`src/config.ts`.
+`Snowfall` (a wide, slow drift) · `Sparkles` (a twinkling field) ·
+`Bursting Rockets` (**sub-emitter** — rockets that explode into a shell burst on
+death) · `Turbulent Smoke` (curl-**noise** flow — smoke that rolls, embers that
+weave). Each mixes shape, velocity, colour/size-over-life, gravity, spin, blend
+mode, and now noise and sub-emitters — see `src/config.ts`.
## How it works
@@ -52,7 +54,7 @@ assets/
textures/particle.png # soft radial particle sprite
src/
main.ts # registers the systems
- config.ts # the six showcases, the firework, spawnShowcase()
+ config.ts # the eight showcases, the firework, spawnShowcase()
components.ts # tags (buttons, TexHolder, ShowcaseEmitter) + Burst
state.ts # the current showcase index
systems/
diff --git a/examples/particle-demo/src/config.ts b/examples/particle-demo/src/config.ts
index b3fd1dee0..c1381e2c8 100644
--- a/examples/particle-demo/src/config.ts
+++ b/examples/particle-demo/src/config.ts
@@ -1,5 +1,5 @@
import {
- EmitterShape, BlendMode, ParticleEasing,
+ EmitterShape, BlendMode, ParticleEasing, SubEmitterTrigger,
Transform, ParticleEmitter,
} from 'esengine';
import type { ParticleEmitterData, CommandsInstance } from 'esengine';
@@ -12,10 +12,16 @@ export interface EmitterSpec {
x: number;
y: number;
data: Partial<ParticleEmitterData>;
+ // Wire this emitter's `subEmitter` to the showcase's `child` template (so its
+ // particles fire the child's burst on the configured trigger).
+ sub?: boolean;
}
export interface Showcase {
name: string;
emitters: EmitterSpec[];
+ // Optional sub-emitter template: spawned once, its entity injected as the
+ // `subEmitter` of every emitter flagged `sub: true`.
+ child?: EmitterSpec;
}
export const SHOWCASES: Showcase[] = [
@@ -116,6 +122,50 @@ export const SHOWCASES: Showcase[] = [
angularVelocityMin: -90, angularVelocityMax: 90 } },
],
},
+ {
+ // Shows off the Sub-emitter module: rockets rise and, on death near their
+ // apex, fire the `child` template's burst at that spot — a shell explosion
+ // without a line of imperative spawn code.
+ name: 'Bursting Rockets',
+ child: { x: 0, y: 0, data: {
+ rate: 0, playOnStart: false, burstCount: 44, maxParticles: 1000,
+ lifetimeMin: 0.6, lifetimeMax: 1.1, shape: EmitterShape.Point,
+ speedMin: 160, speedMax: 340, startSizeMin: 5, startSizeMax: 9,
+ endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseOut,
+ startColor: { r: 1, g: 0.85, b: 0.35, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.08, a: 0 },
+ gravity: { x: 0, y: -150 }, damping: 0.4 } },
+ emitters: [
+ { x: 0, y: -230, sub: true, data: {
+ rate: 2.5, maxParticles: 40, lifetimeMin: 1.4, lifetimeMax: 1.8,
+ shape: EmitterShape.Point, speedMin: 560, speedMax: 660,
+ angleSpreadMin: 84, angleSpreadMax: 96, startSizeMin: 8, startSizeMax: 12,
+ endSizeMin: 5, endSizeMax: 7, startColor: { r: 1, g: 0.95, b: 0.75, a: 1 },
+ endColor: { r: 1, g: 0.6, b: 0.25, a: 0.7 }, gravity: { x: 0, y: -230 },
+ subEmitterTrigger: SubEmitterTrigger.Death, subEmitterInheritVelocity: 0.15 } },
+ ],
+ },
+ {
+ // Shows off the Noise/Turbulence module: a curl-noise flow field makes the
+ // smoke roll and the embers weave instead of drifting in straight lines.
+ name: 'Turbulent Smoke',
+ emitters: [
+ { x: 0, y: -220, data: {
+ rate: 60, maxParticles: 380, lifetimeMin: 2.5, lifetimeMax: 4.0,
+ shape: EmitterShape.Circle, shapeRadius: 24, speedMin: 40, speedMax: 80,
+ angleSpreadMin: 80, angleSpreadMax: 100, startSizeMin: 30, startSizeMax: 50,
+ endSizeMin: 120, endSizeMax: 180, sizeEasing: ParticleEasing.EaseOut,
+ startColor: { r: 0.55, g: 0.6, b: 0.7, a: 0.5 }, endColor: { r: 0.2, g: 0.22, b: 0.3, a: 0 },
+ gravity: { x: 0, y: 30 }, damping: 0.2, blendMode: BlendMode.Normal,
+ noiseStrength: 140, noiseFrequency: 0.006, noiseScrollSpeed: 0.4, noiseOctaves: 2 } },
+ { x: 0, y: -220, data: {
+ rate: 34, maxParticles: 200, lifetimeMin: 1.8, lifetimeMax: 3.0,
+ shape: EmitterShape.Circle, shapeRadius: 16, speedMin: 60, speedMax: 120,
+ angleSpreadMin: 78, angleSpreadMax: 102, startSizeMin: 4, startSizeMax: 8,
+ endSizeMin: 0, endSizeMax: 0, startColor: { r: 1, g: 0.7, b: 0.3, a: 1 },
+ endColor: { r: 1, g: 0.3, b: 0.1, a: 0 }, gravity: { x: 0, y: 20 },
+ noiseStrength: 220, noiseFrequency: 0.012, noiseScrollSpeed: 0.6, noiseOctaves: 3 } },
+ ],
+ },
];
export const SHOWCASE_COUNT = SHOWCASES.length;
@@ -137,10 +187,27 @@ export const BURST: Partial<ParticleEmitterData> = {
// `layer: 5` keeps particles above the backdrop; `texture` is the handle read
// from the scene's TexHolder sprite.
export function spawnShowcase(cmds: CommandsInstance, index: number, texture: number): void {
- for (const emitter of SHOWCASES[index].emitters) {
+ const showcase = SHOWCASES[index];
+
+ // Spawn the sub-emitter template first (if any) so its live entity id can be
+ // handed to the emitters that trigger it. It's tagged like the rest, so a
+ // showcase switch despawns it too.
+ let childId = 0;
+ if (showcase.child) {
+ const c = showcase.child;
+ childId = cmds.spawn()
+ .insert(Transform, { position: { x: c.x, y: c.y, z: 0 } })
+ .insert(ParticleEmitter, { layer: 5, texture, ...c.data })
+ .insert(ShowcaseEmitter, {})
+ .id();
+ }
+
+ for (const emitter of showcase.emitters) {
+ const data: Partial<ParticleEmitterData> = { layer: 5, texture, ...emitter.data };
+ if (emitter.sub && childId) data.subEmitter = childId;
cmds.spawn()
.insert(Transform, { position: { x: emitter.x, y: emitter.y, z: 0 } })
- .insert(ParticleEmitter, { layer: 5, texture, ...emitter.data })
+ .insert(ParticleEmitter, data)
.insert(ShowcaseEmitter, {});
}
}
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index 656510add..f40cebfdb 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from './wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '4e0613ea05e766a3';
+export const ABI_LAYOUT_HASH = '5577bd3e60fc7bd7';
export interface AssetFieldMeta {
field: string;
@@ -323,6 +323,10 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
angularVelocityMax: 0,
gravity: { x: 0, y: 0 },
damping: 0,
+ noiseStrength: 0,
+ noiseFrequency: 0.01,
+ noiseScrollSpeed: 0,
+ noiseOctaves: 1,
texture: 0,
spriteColumns: 1,
spriteRows: 1,
@@ -333,9 +337,13 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
material: 0,
simulationSpace: 0,
enabled: true,
+ subEmitterTrigger: 0,
+ subEmitterChance: 1,
+ subEmitterInheritVelocity: 0,
+ subEmitter: 0,
},
assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
- entityFields: [],
+ entityFields: ['subEmitter'],
colorFields: ['startColor', 'endColor'],
animatableFields: [],
fields: {
@@ -370,6 +378,10 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
angularVelocityMax: { category: "Rotation" },
gravity: { category: "Velocity" },
damping: { min: 0, category: "Velocity" },
+ noiseStrength: { min: 0, category: "Noise" },
+ noiseFrequency: { min: 0, category: "Noise" },
+ noiseScrollSpeed: { category: "Noise" },
+ noiseOctaves: { min: 1, max: 8, step: 1, category: "Noise" },
texture: { category: "Texture" },
spriteColumns: { min: 1, step: 1, category: "Texture" },
spriteRows: { min: 1, step: 1, category: "Texture" },
@@ -379,6 +391,10 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
layer: { step: 1, category: "Rendering", enumSource: "sortingLayers" },
material: { category: "Rendering" },
simulationSpace: { enum: [{ label: 'World', value: 0 }, { label: 'Local', value: 1 }], category: "Rendering" },
+ subEmitterTrigger: { enum: [{ label: 'Death', value: 0 }, { label: 'Birth', value: 1 }], category: "SubEmitter" },
+ subEmitterChance: { min: 0, max: 1, category: "SubEmitter" },
+ subEmitterInheritVelocity: { min: 0, max: 1, category: "SubEmitter" },
+ subEmitter: { category: "SubEmitter" },
},
},
RigidBody: {
@@ -852,6 +868,10 @@ export interface ParticleEmitterData {
angularVelocityMax: number;
gravity: Vec2;
damping: number;
+ noiseStrength: number;
+ noiseFrequency: number;
+ noiseScrollSpeed: number;
+ noiseOctaves: number;
texture: number;
spriteColumns: number;
spriteRows: number;
@@ -862,6 +882,10 @@ export interface ParticleEmitterData {
material: number;
simulationSpace: number;
enabled: boolean;
+ subEmitterTrigger: number;
+ subEmitterChance: number;
+ subEmitterInheritVelocity: number;
+ subEmitter: Entity;
}
export interface RigidBodyData {
diff --git a/sdk/src/component.ts b/sdk/src/component.ts
index 22eaa3366..6b14458c1 100644
--- a/sdk/src/component.ts
+++ b/sdk/src/component.ts
@@ -24,7 +24,7 @@ import type {
// C++ enum and the editor dropdowns derive from the same values. ScaleMode's
// canonical values come from CanvasScaleMode (only its Cocos-compat aliases
// ShowAll/NoBorder are TS-side).
-import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, Light2DType, CanvasScaleMode, ShapeType, ParticleEasing } from './wasm.generated';
+import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, Light2DType, CanvasScaleMode, ShapeType, ParticleEasing } from './wasm.generated';
import { BlendMode } from './blend';
import { getDefaultContext } from './context';
import type {
@@ -560,7 +560,7 @@ export function ensureBuiltinComponentsRegistered(): void {
// EmitterShape, SimulationSpace, Light2DType and ShapeType are re-exported from the
// generated module; their values and the editor dropdowns built from them now have
// one source.
-export { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, Light2DType, ShapeType };
+export { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, Light2DType, ShapeType };
// Canonical values single-sourced from the C++ CanvasScaleMode enum (generated);
// ShowAll/NoBorder are Cocos-compat aliases with no C++ member.
diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.ts
index f66b3fab1..84ed4a989 100644
--- a/sdk/src/core-runtime.ts
+++ b/sdk/src/core-runtime.ts
@@ -131,6 +131,7 @@ export {
ParticleEmitter,
EmitterShape,
SimulationSpace,
+ SubEmitterTrigger,
ParticleEasing,
type ParticleEmitterData,
PostProcessVolume,
diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.ts
index a47620656..6ba63da86 100644
--- a/sdk/src/ecs/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/ptrAccessors.generated.ts
@@ -553,6 +553,10 @@ export interface ParticleEmitterPtrData {
angularVelocityMax: number;
gravity: Vec2;
damping: number;
+ noiseStrength: number;
+ noiseFrequency: number;
+ noiseScrollSpeed: number;
+ noiseOctaves: number;
texture: number;
spriteColumns: number;
spriteRows: number;
@@ -563,6 +567,10 @@ export interface ParticleEmitterPtrData {
material: number;
simulationSpace: number;
enabled: boolean;
+ subEmitterTrigger: number;
+ subEmitterChance: number;
+ subEmitterInheritVelocity: number;
+ subEmitter: number;
}
export function fillParticleEmitter(
@@ -600,16 +608,24 @@ export function fillParticleEmitter(
out.angularVelocityMax = f32[(ptr + 136) >> 2];
const gravity_ = out.gravity; gravity_.x = f32[(ptr + 140) >> 2]; gravity_.y = f32[((ptr + 140) >> 2) + 1];
out.damping = f32[(ptr + 148) >> 2];
- out.texture = u32[(ptr + 152) >> 2];
- out.spriteColumns = u32[(ptr + 156) >> 2] | 0;
- out.spriteRows = u32[(ptr + 160) >> 2] | 0;
- out.spriteFPS = f32[(ptr + 164) >> 2];
- out.spriteLoop = u8[ptr + 168] !== 0;
- out.blendMode = u32[(ptr + 172) >> 2] | 0;
- out.layer = u32[(ptr + 176) >> 2] | 0;
- out.material = u32[(ptr + 180) >> 2];
- out.simulationSpace = u32[(ptr + 184) >> 2] | 0;
- out.enabled = u8[ptr + 188] !== 0;
+ out.noiseStrength = f32[(ptr + 152) >> 2];
+ out.noiseFrequency = f32[(ptr + 156) >> 2];
+ out.noiseScrollSpeed = f32[(ptr + 160) >> 2];
+ out.noiseOctaves = u32[(ptr + 164) >> 2] | 0;
+ out.texture = u32[(ptr + 168) >> 2];
+ out.spriteColumns = u32[(ptr + 172) >> 2] | 0;
+ out.spriteRows = u32[(ptr + 176) >> 2] | 0;
+ out.spriteFPS = f32[(ptr + 180) >> 2];
+ out.spriteLoop = u8[ptr + 184] !== 0;
+ out.blendMode = u32[(ptr + 188) >> 2] | 0;
+ out.layer = u32[(ptr + 192) >> 2] | 0;
+ out.material = u32[(ptr + 196) >> 2];
+ out.simulationSpace = u32[(ptr + 200) >> 2] | 0;
+ out.enabled = u8[ptr + 204] !== 0;
+ out.subEmitterTrigger = u32[(ptr + 208) >> 2] | 0;
+ out.subEmitterChance = f32[(ptr + 212) >> 2];
+ out.subEmitterInheritVelocity = f32[(ptr + 216) >> 2];
+ out.subEmitter = u32[(ptr + 220) >> 2];
}
export function writeParticleEmitter(
@@ -647,16 +663,24 @@ export function writeParticleEmitter(
f32[(ptr + 136) >> 2] = data.angularVelocityMax;
f32[(ptr + 140) >> 2] = data.gravity.x; f32[((ptr + 140) >> 2) + 1] = data.gravity.y;
f32[(ptr + 148) >> 2] = data.damping;
- u32[(ptr + 152) >> 2] = data.texture;
- u32[(ptr + 156) >> 2] = data.spriteColumns | 0;
- u32[(ptr + 160) >> 2] = data.spriteRows | 0;
- f32[(ptr + 164) >> 2] = data.spriteFPS;
- u8[ptr + 168] = data.spriteLoop ? 1 : 0;
- u32[(ptr + 172) >> 2] = data.blendMode | 0;
- u32[(ptr + 176) >> 2] = data.layer | 0;
- u32[(ptr + 180) >> 2] = data.material;
- u32[(ptr + 184) >> 2] = data.simulationSpace | 0;
- u8[ptr + 188] = data.enabled ? 1 : 0;
+ f32[(ptr + 152) >> 2] = data.noiseStrength;
+ f32[(ptr + 156) >> 2] = data.noiseFrequency;
+ f32[(ptr + 160) >> 2] = data.noiseScrollSpeed;
+ u32[(ptr + 164) >> 2] = data.noiseOctaves | 0;
+ u32[(ptr + 168) >> 2] = data.texture;
+ u32[(ptr + 172) >> 2] = data.spriteColumns | 0;
+ u32[(ptr + 176) >> 2] = data.spriteRows | 0;
+ f32[(ptr + 180) >> 2] = data.spriteFPS;
+ u8[ptr + 184] = data.spriteLoop ? 1 : 0;
+ u32[(ptr + 188) >> 2] = data.blendMode | 0;
+ u32[(ptr + 192) >> 2] = data.layer | 0;
+ u32[(ptr + 196) >> 2] = data.material;
+ u32[(ptr + 200) >> 2] = data.simulationSpace | 0;
+ u8[ptr + 204] = data.enabled ? 1 : 0;
+ u32[(ptr + 208) >> 2] = data.subEmitterTrigger | 0;
+ f32[(ptr + 212) >> 2] = data.subEmitterChance;
+ f32[(ptr + 216) >> 2] = data.subEmitterInheritVelocity;
+ u32[(ptr + 220) >> 2] = data.subEmitter;
}
export function createParticleEmitterData(): ParticleEmitterPtrData {
@@ -692,6 +716,10 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {
angularVelocityMax: 0,
gravity: { x: 0, y: 0 },
damping: 0,
+ noiseStrength: 0,
+ noiseFrequency: 0,
+ noiseScrollSpeed: 0,
+ noiseOctaves: 0,
texture: 0,
spriteColumns: 0,
spriteRows: 0,
@@ -702,6 +730,10 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {
material: 0,
simulationSpace: 0,
enabled: false,
+ subEmitterTrigger: 0,
+ subEmitterChance: 0,
+ subEmitterInheritVelocity: 0,
+ subEmitter: 0,
};
}
diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.ts
index 13a6eeead..0738d5b32 100644
--- a/sdk/src/ptrLayouts.generated.ts
+++ b/sdk/src/ptrLayouts.generated.ts
@@ -180,16 +180,24 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'angularVelocityMax', type: 'f32', offset: 136 },
{ name: 'gravity', type: 'vec2', offset: 140 },
{ name: 'damping', type: 'f32', offset: 148 },
- { name: 'texture', type: 'u32', offset: 152 },
- { name: 'spriteColumns', type: 'i32', offset: 156 },
- { name: 'spriteRows', type: 'i32', offset: 160 },
- { name: 'spriteFPS', type: 'f32', offset: 164 },
- { name: 'spriteLoop', type: 'bool', offset: 168 },
- { name: 'blendMode', type: 'i32', offset: 172 },
- { name: 'layer', type: 'i32', offset: 176 },
- { name: 'material', type: 'u32', offset: 180 },
- { name: 'simulationSpace', type: 'i32', offset: 184 },
- { name: 'enabled', type: 'bool', offset: 188 },
+ { name: 'noiseStrength', type: 'f32', offset: 152 },
+ { name: 'noiseFrequency', type: 'f32', offset: 156 },
+ { name: 'noiseScrollSpeed', type: 'f32', offset: 160 },
+ { name: 'noiseOctaves', type: 'i32', offset: 164 },
+ { name: 'texture', type: 'u32', offset: 168 },
+ { name: 'spriteColumns', type: 'i32', offset: 172 },
+ { name: 'spriteRows', type: 'i32', offset: 176 },
+ { name: 'spriteFPS', type: 'f32', offset: 180 },
+ { name: 'spriteLoop', type: 'bool', offset: 184 },
+ { name: 'blendMode', type: 'i32', offset: 188 },
+ { name: 'layer', type: 'i32', offset: 192 },
+ { name: 'material', type: 'u32', offset: 196 },
+ { name: 'simulationSpace', type: 'i32', offset: 200 },
+ { name: 'enabled', type: 'bool', offset: 204 },
+ { name: 'subEmitterTrigger', type: 'i32', offset: 208 },
+ { name: 'subEmitterChance', type: 'f32', offset: 212 },
+ { name: 'subEmitterInheritVelocity', type: 'f32', offset: 216 },
+ { name: 'subEmitter', type: 'u32', offset: 220 },
],
},
RigidBody: {
diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.ts
index 28f4fd4da..268df4a6e 100644
--- a/sdk/src/wasm.generated.ts
+++ b/sdk/src/wasm.generated.ts
@@ -131,6 +131,11 @@ export enum SimulationSpace {
Local = 1,
}
+export enum SubEmitterTrigger {
+ Death = 0,
+ Birth = 1,
+}
+
export enum TextAlign {
Left = 0,
Center = 1,
@@ -340,6 +345,10 @@ export interface ParticleEmitter {
angularVelocityMax: number;
gravity: Vec2;
damping: number;
+ noiseStrength: number;
+ noiseFrequency: number;
+ noiseScrollSpeed: number;
+ noiseOctaves: number;
texture: number;
spriteColumns: number;
spriteRows: number;
@@ -350,6 +359,10 @@ export interface ParticleEmitter {
material: number;
simulationSpace: number;
enabled: boolean;
+ subEmitterTrigger: number;
+ subEmitterChance: number;
+ subEmitterInheritVelocity: number;
+ subEmitter: number;
}
export interface RigidBody {
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 488cccf3b..6e4fd01be 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -322,6 +322,23 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"min": 1,
"step": 1,
},
+ "noiseFrequency": {
+ "category": "Noise",
+ "min": 0,
+ },
+ "noiseOctaves": {
+ "category": "Noise",
+ "max": 8,
+ "min": 1,
+ "step": 1,
+ },
+ "noiseScrollSpeed": {
+ "category": "Noise",
+ },
+ "noiseStrength": {
+ "category": "Noise",
+ "min": 0,
+ },
"playOnStart": {
"category": "Emission",
},
@@ -441,6 +458,32 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"category": "Size",
"min": 0,
},
+ "subEmitter": {
+ "category": "SubEmitter",
+ },
+ "subEmitterChance": {
+ "category": "SubEmitter",
+ "max": 1,
+ "min": 0,
+ },
+ "subEmitterInheritVelocity": {
+ "category": "SubEmitter",
+ "max": 1,
+ "min": 0,
+ },
+ "subEmitterTrigger": {
+ "category": "SubEmitter",
+ "enum": [
+ {
+ "label": "Death",
+ "value": 0,
+ },
+ {
+ "label": "Birth",
+ "value": 1,
+ },
+ ],
+ },
"texture": {
"category": "Texture",
},
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 4bf0629db..9c4e203bb 100644
--- a/src/esengine/bindings/EditorAPI.generated.cpp
+++ b/src/esengine/bindings/EditorAPI.generated.cpp
@@ -2,10 +2,10 @@
* @file EditorAPI.generated.cpp
* @brief Auto-generated editor API with string-dispatched component access
* @details Generated by EHT - DO NOT EDIT
- * @schema_hash 2544ca6f23aa33a5
+ * @schema_hash c17d68a2673d20af
*/
-#define ES_EDITOR_API_SCHEMA_HASH "2544ca6f23aa33a5"
+#define ES_EDITOR_API_SCHEMA_HASH "c17d68a2673d20af"
#include <emscripten/bind.h>
#include <string>
@@ -272,6 +272,10 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"gravity.x","type":"float","group":"ParticleEmitter"},
{"key":"gravity.y","type":"float","group":"ParticleEmitter"},
{"key":"damping","type":"float","group":"ParticleEmitter"},
+ {"key":"noiseStrength","type":"float","group":"ParticleEmitter"},
+ {"key":"noiseFrequency","type":"float","group":"ParticleEmitter"},
+ {"key":"noiseScrollSpeed","type":"float","group":"ParticleEmitter"},
+ {"key":"noiseOctaves","type":"int","group":"ParticleEmitter"},
{"key":"texture","type":"asset","group":"ParticleEmitter"},
{"key":"spriteColumns","type":"int","group":"ParticleEmitter"},
{"key":"spriteRows","type":"int","group":"ParticleEmitter"},
@@ -281,7 +285,11 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"layer","type":"int","group":"ParticleEmitter"},
{"key":"material","type":"asset","group":"ParticleEmitter"},
{"key":"simulationSpace","type":"int","group":"ParticleEmitter"},
- {"key":"enabled","type":"bool","group":"ParticleEmitter"}
+ {"key":"enabled","type":"bool","group":"ParticleEmitter"},
+ {"key":"subEmitterTrigger","type":"int","group":"ParticleEmitter"},
+ {"key":"subEmitterChance","type":"float","group":"ParticleEmitter"},
+ {"key":"subEmitterInheritVelocity","type":"float","group":"ParticleEmitter"},
+ {"key":"subEmitter","type":"entity","group":"ParticleEmitter"}
])JSON";
} else if (name == "RigidBody") {
return R"JSON([
@@ -891,7 +899,12 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "gravity.x") { c.gravity.x = value; }
else if (field == "gravity.y") { c.gravity.y = value; }
else if (field == "damping") { c.damping = value; }
+ else if (field == "noiseStrength") { c.noiseStrength = value; }
+ else if (field == "noiseFrequency") { c.noiseFrequency = value; }
+ else if (field == "noiseScrollSpeed") { c.noiseScrollSpeed = value; }
else if (field == "spriteFPS") { c.spriteFPS = value; }
+ else if (field == "subEmitterChance") { c.subEmitterChance = value; }
+ else if (field == "subEmitterInheritVelocity") { c.subEmitterInheritVelocity = value; }
else { return false; }
return true;
} else if (comp == "RigidBody") {
@@ -1235,7 +1248,12 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "gravity.x") { return c.gravity.x; }
else if (field == "gravity.y") { return c.gravity.y; }
else if (field == "damping") { return c.damping; }
+ else if (field == "noiseStrength") { return c.noiseStrength; }
+ else if (field == "noiseFrequency") { return c.noiseFrequency; }
+ else if (field == "noiseScrollSpeed") { return c.noiseScrollSpeed; }
else if (field == "spriteFPS") { return c.spriteFPS; }
+ else if (field == "subEmitterChance") { return c.subEmitterChance; }
+ else if (field == "subEmitterInheritVelocity") { return c.subEmitterInheritVelocity; }
} else if (comp == "RigidBody") {
if (!reg.has<esengine::ecs::RigidBody>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::RigidBody>(entity);
@@ -1493,6 +1511,7 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
else if (field == "shape") { c.shape = static_cast<i32>(value); }
else if (field == "sizeEasing") { c.sizeEasing = static_cast<i32>(value); }
else if (field == "colorEasing") { c.colorEasing = static_cast<i32>(value); }
+ else if (field == "noiseOctaves") { c.noiseOctaves = static_cast<i32>(value); }
else if (field == "texture") { c.texture = resource::TextureHandle(static_cast<u32>(value)); }
else if (field == "spriteColumns") { c.spriteColumns = static_cast<i32>(value); }
else if (field == "spriteRows") { c.spriteRows = static_cast<i32>(value); }
@@ -1500,6 +1519,8 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::str
else if (field == "layer") { c.layer = static_cast<i32>(value); }
else if (field == "material") { c.material = static_cast<u32>(value); }
else if (field == "simulationSpace") { c.simulationSpace = static_cast<i32>(value); }
+ else if (field == "subEmitterTrigger") { c.subEmitterTrigger = static_cast<i32>(value); }
+ else if (field == "subEmitter") { c.subEmitter = static_cast<u32>(value); }
else { return false; }
return true;
} else if (comp == "RigidBody") {
@@ -1652,6 +1673,7 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
else if (field == "shape") { return static_cast<i32>(c.shape); }
else if (field == "sizeEasing") { return static_cast<i32>(c.sizeEasing); }
else if (field == "colorEasing") { return static_cast<i32>(c.colorEasing); }
+ else if (field == "noiseOctaves") { return static_cast<i32>(c.noiseOctaves); }
else if (field == "texture") { return static_cast<i32>(c.texture.id()); }
else if (field == "spriteColumns") { return static_cast<i32>(c.spriteColumns); }
else if (field == "spriteRows") { return static_cast<i32>(c.spriteRows); }
@@ -1659,6 +1681,8 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::stri
else if (field == "layer") { return static_cast<i32>(c.layer); }
else if (field == "material") { return static_cast<i32>(c.material); }
else if (field == "simulationSpace") { return static_cast<i32>(c.simulationSpace); }
+ else if (field == "subEmitterTrigger") { return static_cast<i32>(c.subEmitterTrigger); }
+ else if (field == "subEmitter") { return static_cast<i32>(c.subEmitter); }
} else if (comp == "RigidBody") {
if (!reg.has<esengine::ecs::RigidBody>(entity)) return 0;
const auto& c = reg.get<esengine::ecs::RigidBody>(entity);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 55619359c..88b948bbd 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -177,6 +177,10 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {
.value("World", esengine::ecs::SimulationSpace::World)
.value("Local", esengine::ecs::SimulationSpace::Local);
+ enum_<esengine::ecs::SubEmitterTrigger>("SubEmitterTrigger")
+ .value("Death", esengine::ecs::SubEmitterTrigger::Death)
+ .value("Birth", esengine::ecs::SubEmitterTrigger::Birth);
+
enum_<esengine::ecs::TextAlign>("TextAlign")
.value("Left", esengine::ecs::TextAlign::Left)
.value("Center", esengine::ecs::TextAlign::Center)
@@ -479,6 +483,10 @@ struct ParticleEmitterJS {
f32 angularVelocityMax;
glm::vec2 gravity;
f32 damping;
+ f32 noiseStrength;
+ f32 noiseFrequency;
+ f32 noiseScrollSpeed;
+ i32 noiseOctaves;
u32 texture;
i32 spriteColumns;
i32 spriteRows;
@@ -489,6 +497,10 @@ struct ParticleEmitterJS {
u32 material;
i32 simulationSpace;
bool enabled;
+ i32 subEmitterTrigger;
+ f32 subEmitterChance;
+ f32 subEmitterInheritVelocity;
+ u32 subEmitter;
};
esengine::ecs::ParticleEmitter particleemitterFromJS(const ParticleEmitterJS& js) {
@@ -524,6 +536,10 @@ esengine::ecs::ParticleEmitter particleemitterFromJS(const ParticleEmitterJS& js
c.angularVelocityMax = js.angularVelocityMax;
c.gravity = js.gravity;
c.damping = js.damping;
+ c.noiseStrength = js.noiseStrength;
+ c.noiseFrequency = js.noiseFrequency;
+ c.noiseScrollSpeed = js.noiseScrollSpeed;
+ c.noiseOctaves = js.noiseOctaves;
c.texture = resource::TextureHandle(js.texture);
c.spriteColumns = js.spriteColumns;
c.spriteRows = js.spriteRows;
@@ -534,6 +550,10 @@ esengine::ecs::ParticleEmitter particleemitterFromJS(const ParticleEmitterJS& js
c.material = js.material;
c.simulationSpace = js.simulationSpace;
c.enabled = js.enabled;
+ c.subEmitterTrigger = js.subEmitterTrigger;
+ c.subEmitterChance = js.subEmitterChance;
+ c.subEmitterInheritVelocity = js.subEmitterInheritVelocity;
+ c.subEmitter = js.subEmitter;
return c;
}
@@ -570,6 +590,10 @@ ParticleEmitterJS particleemitterToJS(const esengine::ecs::ParticleEmitter& c) {
js.angularVelocityMax = c.angularVelocityMax;
js.gravity = c.gravity;
js.damping = c.damping;
+ js.noiseStrength = c.noiseStrength;
+ js.noiseFrequency = c.noiseFrequency;
+ js.noiseScrollSpeed = c.noiseScrollSpeed;
+ js.noiseOctaves = c.noiseOctaves;
js.texture = c.texture.id();
js.spriteColumns = c.spriteColumns;
js.spriteRows = c.spriteRows;
@@ -580,6 +604,10 @@ ParticleEmitterJS particleemitterToJS(const esengine::ecs::ParticleEmitter& c) {
js.material = c.material;
js.simulationSpace = c.simulationSpace;
js.enabled = c.enabled;
+ js.subEmitterTrigger = c.subEmitterTrigger;
+ js.subEmitterChance = c.subEmitterChance;
+ js.subEmitterInheritVelocity = c.subEmitterInheritVelocity;
+ js.subEmitter = c.subEmitter;
return js;
}
@@ -1061,6 +1089,10 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("angularVelocityMax", &ParticleEmitterJS::angularVelocityMax)
.field("gravity", &ParticleEmitterJS::gravity)
.field("damping", &ParticleEmitterJS::damping)
+ .field("noiseStrength", &ParticleEmitterJS::noiseStrength)
+ .field("noiseFrequency", &ParticleEmitterJS::noiseFrequency)
+ .field("noiseScrollSpeed", &ParticleEmitterJS::noiseScrollSpeed)
+ .field("noiseOctaves", &ParticleEmitterJS::noiseOctaves)
.field("texture", &ParticleEmitterJS::texture)
.field("spriteColumns", &ParticleEmitterJS::spriteColumns)
.field("spriteRows", &ParticleEmitterJS::spriteRows)
@@ -1070,7 +1102,11 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("layer", &ParticleEmitterJS::layer)
.field("material", &ParticleEmitterJS::material)
.field("simulationSpace", &ParticleEmitterJS::simulationSpace)
- .field("enabled", &ParticleEmitterJS::enabled);
+ .field("enabled", &ParticleEmitterJS::enabled)
+ .field("subEmitterTrigger", &ParticleEmitterJS::subEmitterTrigger)
+ .field("subEmitterChance", &ParticleEmitterJS::subEmitterChance)
+ .field("subEmitterInheritVelocity", &ParticleEmitterJS::subEmitterInheritVelocity)
+ .field("subEmitter", &ParticleEmitterJS::subEmitter);
value_object<RigidBodyJS>("RigidBody")
.field("bodyType", &RigidBodyJS::bodyType)
@@ -1966,16 +2002,24 @@ static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMin) == 13
static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMax) == 136, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMax (EHT expected 136)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, gravity) == 140, "ABI offset drift: esengine::ecs::ParticleEmitter.gravity (EHT expected 140)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, damping) == 148, "ABI offset drift: esengine::ecs::ParticleEmitter.damping (EHT expected 148)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 152, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 152)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 156, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 156)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 160)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 164)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 168)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 172)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 176)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 180)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 184)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 188)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseStrength) == 152, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseStrength (EHT expected 152)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseFrequency) == 156, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseFrequency (EHT expected 156)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseScrollSpeed) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseScrollSpeed (EHT expected 160)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseOctaves) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseOctaves (EHT expected 164)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 168)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 172)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 176)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 180)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 184)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 188)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 192, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 192)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 196, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 196)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 200, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 200)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 204, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 204)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterTrigger) == 208, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterTrigger (EHT expected 208)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterChance) == 212, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterChance (EHT expected 212)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterInheritVelocity) == 216, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterInheritVelocity (EHT expected 216)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitter) == 220, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitter (EHT expected 220)");
static_assert(offsetof(esengine::ecs::RigidBody, bodyType) == 0, "ABI offset drift: esengine::ecs::RigidBody.bodyType (EHT expected 0)");
static_assert(offsetof(esengine::ecs::RigidBody, gravityScale) == 4, "ABI offset drift: esengine::ecs::RigidBody.gravityScale (EHT expected 4)");
static_assert(offsetof(esengine::ecs::RigidBody, linearDamping) == 8, "ABI offset drift: esengine::ecs::RigidBody.linearDamping (EHT expected 8)");
@@ -2089,7 +2133,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "4e0613ea05e766a3";
+static const char* kEsAbiLayoutHash = "5577bd3e60fc7bd7";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hpp
index c2333ea15..20f2f9403 100644
--- a/src/esengine/ecs/components/ParticleEmitter.hpp
+++ b/src/esengine/ecs/components/ParticleEmitter.hpp
@@ -34,6 +34,15 @@ enum class SimulationSpace : i32 {
Local = 1,
};
+// When a sub-emitter fires the referenced child emitter's burst: as each parent
+// particle is born, or as it dies. (Collision joins this list once particle
+// collision lands.)
+ES_ENUM()
+enum class SubEmitterTrigger : i32 {
+ Death = 0,
+ Birth = 1,
+};
+
ES_COMPONENT()
struct ParticleEmitter {
// Emission
@@ -138,6 +147,21 @@ struct ParticleEmitter {
ES_PROPERTY(min=0, category=Velocity)
f32 damping{0.0f};
+ // Noise / Turbulence — a divergence-free curl-noise flow field advects each
+ // particle, layered on top of velocity/gravity. Strength 0 disables it (no
+ // field is sampled), so the module is free when unused.
+ ES_PROPERTY(min=0, category=Noise)
+ f32 noiseStrength{0.0f};
+
+ ES_PROPERTY(min=0, category=Noise)
+ f32 noiseFrequency{0.01f};
+
+ ES_PROPERTY(category=Noise)
+ f32 noiseScrollSpeed{0.0f};
+
+ ES_PROPERTY(min=1, max=8, step=1, category=Noise)
+ i32 noiseOctaves{1};
+
// Texture
ES_PROPERTY(asset = texture, category=Texture)
resource::TextureHandle texture;
@@ -173,6 +197,26 @@ struct ParticleEmitter {
ES_PROPERTY()
bool enabled{true};
+ // Sub-emitter — on each parent particle's birth or death, fire the referenced
+ // child emitter's burst at that particle's position. The child is an ordinary
+ // ParticleEmitter entity used as a template (typically rate=0, playOnStart=false
+ // so it only emits when triggered); its burstCount sets the sub-burst size.
+ // `subEmitter` is the child entity's raw id (0 = none). It is stored as u32
+ // rather than Entity so the pointer layout keeps a heap accessor (Entity is
+ // truncated out of the layout); the entity_ref tag still drives the editor
+ // picker and the scene/prefab editor→runtime id remapping.
+ ES_PROPERTY(enum=SubEmitterTrigger, category=SubEmitter)
+ i32 subEmitterTrigger{static_cast<i32>(SubEmitterTrigger::Death)};
+
+ ES_PROPERTY(min=0, max=1, category=SubEmitter)
+ f32 subEmitterChance{1.0f};
+
+ ES_PROPERTY(min=0, max=1, category=SubEmitter)
+ f32 subEmitterInheritVelocity{0.0f};
+
+ ES_PROPERTY(entity_ref, category=SubEmitter)
+ u32 subEmitter{0};
+
ParticleEmitter() = default;
};
diff --git a/src/esengine/particle/ParticleNoise.hpp b/src/esengine/particle/ParticleNoise.hpp
new file mode 100644
index 000000000..d52a79b61
--- /dev/null
+++ b/src/esengine/particle/ParticleNoise.hpp
@@ -0,0 +1,91 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file ParticleNoise.hpp
+ * @brief Deterministic curl-noise flow field for the particle Noise/Turbulence
+ * module — a pure-CPU, header-only vector field the sim advects particles
+ * along, exactly like gravity is a force in the same loop. No GPU path,
+ * no external tables, so it runs byte-identically on every platform
+ * (WeChat mini-game included).
+ * @details The field is the 2D curl of a fractal-Brownian scalar potential, i.e.
+ * `flow = (∂ψ/∂y, -∂ψ/∂x)`. A curl field is divergence-free, so particles
+ * never pile up in sinks or thin out at sources the way a raw noise vector
+ * field does — the classic "swirly but even" turbulence look.
+ */
+#pragma once
+
+#include "../core/Types.hpp"
+#include "../math/Math.hpp"
+
+#include <cmath>
+
+namespace esengine::particle::noise {
+
+// A cheap integer hash → [0,1). Self-contained (no 256-entry permutation table)
+// so the field is fully determined by the lattice coordinate and nothing else.
+inline f32 hash2(i32 x, i32 y) {
+ u32 h = static_cast<u32>(x) * 374761393u + static_cast<u32>(y) * 668265263u;
+ h = (h ^ (h >> 13)) * 1274126177u;
+ h ^= h >> 16;
+ return static_cast<f32>(h) * (1.0f / 4294967295.0f);
+}
+
+// Pseudo-random unit gradient at a lattice point (angle picked from the hash).
+inline glm::vec2 grad2(i32 x, i32 y) {
+ f32 a = hash2(x, y) * math::TWO_PI;
+ return glm::vec2(std::cos(a), std::sin(a));
+}
+
+// Perlin quintic fade — C² continuous, so the finite-difference curl below is smooth.
+inline f32 fade(f32 t) { return t * t * t * (t * (t * 6.0f - 15.0f) + 10.0f); }
+
+// Classic 2D gradient (Perlin) noise, output ~[-1, 1].
+inline f32 perlin2(glm::vec2 p) {
+ glm::vec2 pi = glm::floor(p);
+ glm::vec2 pf = p - pi;
+ auto x0 = static_cast<i32>(pi.x);
+ auto y0 = static_cast<i32>(pi.y);
+
+ f32 n00 = glm::dot(grad2(x0, y0), pf - glm::vec2(0.0f, 0.0f));
+ f32 n10 = glm::dot(grad2(x0 + 1, y0), pf - glm::vec2(1.0f, 0.0f));
+ f32 n01 = glm::dot(grad2(x0, y0 + 1), pf - glm::vec2(0.0f, 1.0f));
+ f32 n11 = glm::dot(grad2(x0 + 1, y0 + 1), pf - glm::vec2(1.0f, 1.0f));
+
+ f32 ux = fade(pf.x);
+ f32 uy = fade(pf.y);
+ f32 nx0 = math::lerp(n00, n10, ux);
+ f32 nx1 = math::lerp(n01, n11, ux);
+ return math::lerp(nx0, nx1, uy);
+}
+
+// Fractal-Brownian sum: `octaves` layers at doubling frequency / halving amplitude.
+// octaves == 1 is plain Perlin; more octaves add the fine detail that reads as
+// "turbulence". Normalised so the result stays ~[-1, 1] regardless of octave count.
+inline f32 fbm2(glm::vec2 p, i32 octaves) {
+ f32 sum = 0.0f, amp = 1.0f, freq = 1.0f, norm = 0.0f;
+ i32 n = octaves < 1 ? 1 : (octaves > 8 ? 8 : octaves);
+ for (i32 i = 0; i < n; ++i) {
+ sum += amp * perlin2(p * freq);
+ norm += amp;
+ freq *= 2.0f;
+ amp *= 0.5f;
+ }
+ return norm > 0.0f ? sum / norm : 0.0f;
+}
+
+// Divergence-free 2D flow: curl of the fbm scalar potential via central differences.
+// The result is a ~unit-scale velocity direction+magnitude the sim scales by the
+// emitter's noiseStrength. `sample` is already in noise space (position × frequency,
+// plus the scroll offset), so callers fold frequency/scroll in before calling.
+inline glm::vec2 curl(glm::vec2 sample, i32 octaves) {
+ constexpr f32 e = 0.1f; // finite-difference epsilon, a fraction of a lattice cell
+ f32 dpdx = fbm2(sample + glm::vec2(e, 0.0f), octaves) -
+ fbm2(sample - glm::vec2(e, 0.0f), octaves);
+ f32 dpdy = fbm2(sample + glm::vec2(0.0f, e), octaves) -
+ fbm2(sample - glm::vec2(0.0f, e), octaves);
+ // curl(ψ) = (∂ψ/∂y, -∂ψ/∂x); the 0.25 tames the /(2e) gain so noiseStrength
+ // reads roughly as a peak advection speed in px/s.
+ return glm::vec2(dpdy, -dpdx) * (0.25f / (2.0f * e));
+}
+
+} // namespace esengine::particle::noise
diff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cpp
index b673647cf..65984a2aa 100644
--- a/src/esengine/particle/ParticleSystem.cpp
+++ b/src/esengine/particle/ParticleSystem.cpp
@@ -1,6 +1,7 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#include "ParticleSystem.hpp"
+#include "ParticleNoise.hpp"
#include <algorithm>
#include <chrono>
@@ -87,11 +88,27 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
}
}
+ glm::vec2 emitterPos(transform.worldPosition.x, transform.worldPosition.y);
+ f32 emitterAngle = 0.0f;
+ if (transform.worldRotation.w != 1.0f || transform.worldRotation.z != 0.0f) {
+ emitterAngle = 2.0f * std::atan2(transform.worldRotation.z,
+ transform.worldRotation.w);
+ }
+ bool isWorldSpace = emitter.simulationSpace ==
+ static_cast<i32>(ecs::SimulationSpace::World);
+
auto lutIt = colorLuts_.find(entity);
auto sizeIt = sizeLuts_.find(entity);
updateParticles(emitter, state, dt,
lutIt != colorLuts_.end() ? &lutIt->second : nullptr,
- sizeIt != sizeLuts_.end() ? &sizeIt->second : nullptr);
+ sizeIt != sizeLuts_.end() ? &sizeIt->second : nullptr,
+ emitterPos, emitterAngle, isWorldSpace);
+
+ // Fire the child sub-emitter's burst at every birth/death queued this frame.
+ if (emitter.subEmitter != 0 && !subemit_requests_.empty()) {
+ drainSubEmitters(registry, Entity::fromRaw(emitter.subEmitter),
+ emitter.subEmitterInheritVelocity, emitter.subEmitterChance);
+ }
}
}
@@ -181,6 +198,11 @@ const EmitterState* ParticleSystem::getState(Entity entity) const {
return it != states_.end() ? &it->second : nullptr;
}
+// Rotate a 2D vector by a precomputed cos/sin.
+static inline glm::vec2 rotate2(glm::vec2 v, f32 cosA, f32 sinA) {
+ return glm::vec2(v.x * cosA - v.y * sinA, v.x * sinA + v.y * cosA);
+}
+
void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,
const ecs::Transform& transform,
EmitterState& state, u32 count) {
@@ -190,6 +212,23 @@ void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,
emitterAngle = 2.0f * std::atan2(transform.worldRotation.z,
transform.worldRotation.w);
}
+ bool isWorldSpace = emitter.simulationSpace ==
+ static_cast<i32>(ecs::SimulationSpace::World);
+ emitInto(emitter, state, emitterPos, emitterAngle, isWorldSpace, glm::vec2(0.0f), count,
+ /*allowBirthTrigger=*/true);
+}
+
+void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState& state,
+ glm::vec2 emitterPos, f32 emitterAngle, bool isWorldSpace,
+ glm::vec2 velocityBias, u32 count, bool allowBirthTrigger) {
+ // Record each spawned particle for a Birth-triggered sub-emitter (in world
+ // space, since a sub-burst is a world event).
+ bool recordBirth = allowBirthTrigger &&
+ emitter.subEmitter != 0 &&
+ emitter.subEmitterTrigger ==
+ static_cast<i32>(ecs::SubEmitterTrigger::Birth);
+ f32 cosA = std::cos(emitterAngle);
+ f32 sinA = std::sin(emitterAngle);
for (u32 i = 0; i < count; ++i) {
Particle* p = state.pool.allocate();
@@ -213,22 +252,13 @@ void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,
emitter.angularVelocityMax);
glm::vec2 offset = randomShapeOffset(emitter);
- bool isWorldSpace = emitter.simulationSpace ==
- static_cast<i32>(ecs::SimulationSpace::World);
if (isWorldSpace) {
// Rotate the spawn footprint by the emitter angle so the emission
// shape agrees with the (already-rotated) velocity below; otherwise a
// rotated world-space cone/box spawns along its unrotated axis while
// the flow points elsewhere. `offset` itself stays unrotated — the
// Circle aim reads it and gets the same rotation applied once, below.
- glm::vec2 worldOffset = offset;
- if (std::abs(emitterAngle) > 0.001f) {
- f32 cosA = std::cos(emitterAngle);
- f32 sinA = std::sin(emitterAngle);
- worldOffset = glm::vec2(offset.x * cosA - offset.y * sinA,
- offset.x * sinA + offset.y * cosA);
- }
- p->position = emitterPos + worldOffset;
+ p->position = emitterPos + rotate2(offset, cosA, sinA);
} else {
p->position = offset;
}
@@ -262,15 +292,54 @@ void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,
dir = randomDirection(emitter.angleSpreadMin, emitter.angleSpreadMax);
break;
}
- if (isWorldSpace && std::abs(emitterAngle) > 0.001f) {
- f32 cosA = std::cos(emitterAngle);
- f32 sinA = std::sin(emitterAngle);
- dir = glm::vec2(dir.x * cosA - dir.y * sinA,
- dir.x * sinA + dir.y * cosA);
+ if (isWorldSpace) {
+ dir = rotate2(dir, cosA, sinA);
}
- p->velocity = dir * speed;
+ p->velocity = dir * speed + velocityBias;
p->sprite_frame = 0;
+
+ if (recordBirth) {
+ glm::vec2 worldPos = isWorldSpace ? p->position
+ : emitterPos + rotate2(p->position, cosA, sinA);
+ glm::vec2 worldVel = isWorldSpace ? p->velocity : rotate2(p->velocity, cosA, sinA);
+ subemit_requests_.push_back({worldPos, worldVel});
+ }
+ }
+}
+
+void ParticleSystem::drainSubEmitters(ecs::Registry& registry, Entity child,
+ f32 inheritVelocity, f32 chance) {
+ // Take ownership of the queue up front: emitInto below spawns into the child
+ // with allowBirthTrigger=false, so it never re-enters this buffer, but swapping
+ // also leaves the member clean if the child reference is stale.
+ std::vector<SubEmitRequest> requests;
+ requests.swap(subemit_requests_);
+
+ if (!registry.valid(child) || !registry.has<ecs::ParticleEmitter>(child)) {
+ return; // a deleted/retargeted child just drops its bursts
+ }
+ const auto& childEmitter = registry.get<ecs::ParticleEmitter>(child);
+
+ // The child's own state may not exist yet (it's created lazily when the main
+ // loop reaches it); make it on demand so a burst is never lost.
+ auto it = states_.find(child);
+ if (it == states_.end()) {
+ auto [insertIt, _] = states_.emplace(
+ child, EmitterState(static_cast<u32>(std::clamp(childEmitter.maxParticles, 0, 1'000'000))));
+ it = insertIt;
+ }
+ EmitterState& childState = it->second;
+
+ // The child's burstCount sizes each sub-burst (fall back to 1 so a misconfigured
+ // template still shows something).
+ u32 count = childEmitter.burstCount > 0 ? static_cast<u32>(childEmitter.burstCount) : 1;
+ for (const auto& req : requests) {
+ if (chance < 1.0f && randomRange(0.0f, 1.0f) >= chance) {
+ continue;
+ }
+ emitInto(childEmitter, childState, req.position, 0.0f, /*isWorldSpace=*/true,
+ req.velocity * inheritVelocity, count, /*allowBirthTrigger=*/false);
}
}
@@ -292,17 +361,41 @@ static f32 sampleSizeLut(const SizeLut& lut, f32 t) {
void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
EmitterState& state, f32 dt,
- const ColorLut* colorLut, const SizeLut* sizeLut) {
+ const ColorLut* colorLut, const SizeLut* sizeLut,
+ glm::vec2 emitterPos, f32 emitterAngle,
+ bool isWorldSpace) {
auto sizeEasing = static_cast<EasingType>(emitter.sizeEasing);
auto colorEasing = static_cast<EasingType>(emitter.colorEasing);
i32 totalFrames = emitter.spriteColumns * emitter.spriteRows;
+ // Record dying particles for a Death-triggered sub-emitter (world space — a
+ // sub-burst is a world event). cos/sin convert a local-space death to world.
+ bool recordDeath = emitter.subEmitter != 0 &&
+ emitter.subEmitterTrigger ==
+ static_cast<i32>(ecs::SubEmitterTrigger::Death);
+ f32 cosA = std::cos(emitterAngle);
+ f32 sinA = std::sin(emitterAngle);
+
+ // Noise/Turbulence: a curl-noise flow field advected onto position. Strength 0
+ // samples nothing (the whole module is free when unused). The scroll offset
+ // drifts the field over a monotonic clock so pausing emission never snaps it.
+ state.noise_time += dt;
+ bool noiseOn = emitter.noiseStrength > 0.0f && emitter.noiseFrequency > 0.0f;
+ glm::vec2 noiseScroll(emitter.noiseScrollSpeed * state.noise_time *
+ emitter.noiseFrequency);
+
dead_particle_indices_.clear();
state.pool.forEachAlive([&](Particle& p) {
p.age += dt;
if (p.age >= p.lifetime) {
+ if (recordDeath) {
+ glm::vec2 worldPos = isWorldSpace ? p.position
+ : emitterPos + rotate2(p.position, cosA, sinA);
+ glm::vec2 worldVel = isWorldSpace ? p.velocity : rotate2(p.velocity, cosA, sinA);
+ subemit_requests_.push_back({worldPos, worldVel});
+ }
u32 idx = static_cast<u32>(&p - &state.pool.particles()[0]);
dead_particle_indices_.push_back(idx);
return;
@@ -316,6 +409,12 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
}
p.position += p.velocity * dt;
+ if (noiseOn) {
+ glm::vec2 sample = p.position * emitter.noiseFrequency + noiseScroll;
+ p.position += noise::curl(sample, emitter.noiseOctaves) *
+ emitter.noiseStrength * dt;
+ }
+
p.rotation += p.angular_velocity * dt;
if (sizeLut) {
diff --git a/src/esengine/particle/ParticleSystem.hpp b/src/esengine/particle/ParticleSystem.hpp
index b3a0af703..be94b236a 100644
--- a/src/esengine/particle/ParticleSystem.hpp
+++ b/src/esengine/particle/ParticleSystem.hpp
@@ -30,6 +30,9 @@ struct EmitterState {
f32 emission_accumulator = 0.0f;
f32 elapsed_time = 0.0f;
f32 burst_timer = 0.0f;
+ // Monotonic clock for the noise field's scroll — advances every update
+ // regardless of play/stop so the turbulence never snaps when emission pauses.
+ f32 noise_time = 0.0f;
bool playing = false;
bool first_update = true;
@@ -65,12 +68,31 @@ private:
const ecs::Transform& transform,
EmitterState& state, u32 count);
+ // Shared spawn core: seed `count` particles into `state` from `emitter`'s config,
+ // originating at world `emitterPos`/`emitterAngle`, adding `velocityBias` to each
+ // (used by sub-emitter bursts to inherit the parent particle's motion).
+ // `allowBirthTrigger` records Birth events for a nested sub-emitter; false for a
+ // sub-burst's own spawn so a drain can't re-enter the request buffer it's reading.
+ void emitInto(const ecs::ParticleEmitter& emitter, EmitterState& state,
+ glm::vec2 emitterPos, f32 emitterAngle, bool isWorldSpace,
+ glm::vec2 velocityBias, u32 count, bool allowBirthTrigger);
+
+ // Fire the referenced child emitter's burst at each pending sub-emit request.
+ void drainSubEmitters(ecs::Registry& registry, Entity child,
+ f32 inheritVelocity, f32 chance);
+
void updateParticles(const ecs::ParticleEmitter& emitter, EmitterState& state, f32 dt,
- const ColorLut* colorLut, const SizeLut* sizeLut);
+ const ColorLut* colorLut, const SizeLut* sizeLut,
+ glm::vec2 emitterPos, f32 emitterAngle, bool isWorldSpace);
f32 randomRange(f32 min, f32 max);
glm::vec2 randomDirection(f32 angleMin, f32 angleMax);
glm::vec2 randomShapeOffset(const ecs::ParticleEmitter& emitter);
+ // A parent particle's birth/death position + velocity, queued during a parent's
+ // update and drained into its child sub-emitter right after.
+ struct SubEmitRequest { glm::vec2 position; glm::vec2 velocity; };
+ std::vector<SubEmitRequest> subemit_requests_;
+
std::unordered_map<Entity, EmitterState> states_;
// A play() that arrives before the emitter's first update (its state isn't
// created yet) is remembered here and applied on state creation, not dropped.
diff --git a/tests/particle/test_particle.cpp b/tests/particle/test_particle.cpp
index ad16545d7..71e54f6cf 100644
--- a/tests/particle/test_particle.cpp
+++ b/tests/particle/test_particle.cpp
@@ -309,6 +309,139 @@ TEST_CASE("system_gravity_affects_velocity") {
CHECK(hasDownwardVelocity);
}
+TEST_CASE("system_noise_off_leaves_ballistic_motion_untouched") {
+ // With noiseStrength 0 the field is never sampled: a zero-velocity, zero-gravity
+ // particle must stay exactly where it spawned, proving the module is truly inert
+ // when off (no accidental jitter).
+ ecs::Registry registry;
+ ParticleSystem system;
+
+ Entity e = registry.create();
+ registry.emplace<ecs::Transform>(e);
+ auto& emitter = registry.emplace<ecs::ParticleEmitter>(e);
+ emitter.rate = 1000.0f;
+ emitter.lifetimeMin = emitter.lifetimeMax = 10.0f;
+ emitter.maxParticles = 100;
+ emitter.speedMin = emitter.speedMax = 0.0f;
+ emitter.gravity = glm::vec2(0.0f, 0.0f);
+ emitter.shape = static_cast<i32>(ecs::EmitterShape::Point);
+ emitter.noiseStrength = 0.0f;
+ emitter.enabled = true;
+ emitter.playOnStart = true;
+
+ system.update(registry, 0.01f); // spawn at the origin
+ for (int i = 0; i < 10; ++i) system.update(registry, 0.05f);
+
+ bool allStill = true;
+ system.forEachParticle(e, [&](const Particle& p) {
+ if (glm::length(p.position) > 1e-4f) allStill = false;
+ });
+ CHECK(allStill);
+}
+
+TEST_CASE("system_noise_advects_otherwise_static_particles") {
+ // Zero velocity + zero gravity: the ONLY thing that can move a particle is the
+ // noise flow field, so any displacement proves the curl advection is wired in.
+ ecs::Registry registry;
+ ParticleSystem system;
+
+ Entity e = registry.create();
+ registry.emplace<ecs::Transform>(e);
+ auto& emitter = registry.emplace<ecs::ParticleEmitter>(e);
+ emitter.rate = 1000.0f;
+ emitter.lifetimeMin = emitter.lifetimeMax = 10.0f;
+ emitter.maxParticles = 200;
+ emitter.speedMin = emitter.speedMax = 0.0f;
+ emitter.gravity = glm::vec2(0.0f, 0.0f);
+ // Spread the spawn across the field so particles sample varied, non-zero curl.
+ emitter.shape = static_cast<i32>(ecs::EmitterShape::Rectangle);
+ emitter.shapeSize = glm::vec2(800.0f, 800.0f);
+ emitter.noiseStrength = 500.0f;
+ emitter.noiseFrequency = 0.01f;
+ emitter.noiseOctaves = 2;
+ emitter.enabled = true;
+ emitter.playOnStart = true;
+
+ system.update(registry, 0.01f); // spawn spread across the rectangle
+
+ std::vector<glm::vec2> spawnPos;
+ system.forEachParticle(e, [&](const Particle& p) { spawnPos.push_back(p.position); });
+
+ for (int i = 0; i < 20; ++i) system.update(registry, 0.05f);
+
+ // At least one particle must have drifted well beyond its spawn footprint.
+ bool anyMoved = false;
+ std::size_t idx = 0;
+ system.forEachParticle(e, [&](const Particle& p) {
+ if (idx < spawnPos.size() && glm::length(p.position - spawnPos[idx]) > 5.0f) {
+ anyMoved = true;
+ }
+ ++idx;
+ });
+ CHECK(anyMoved);
+}
+
+// Build a child "template" emitter that only fires when a sub-emitter triggers it
+// (rate 0, no play-on-start), plus a parent wired to it. Returns {parent, child}.
+static std::pair<Entity, Entity> makeSubEmitterPair(ecs::Registry& registry,
+ ecs::SubEmitterTrigger trigger,
+ f32 parentLifetime) {
+ Entity child = registry.create();
+ registry.emplace<ecs::Transform>(child);
+ auto& childEmitter = registry.emplace<ecs::ParticleEmitter>(child);
+ childEmitter.rate = 0.0f;
+ childEmitter.playOnStart = false;
+ childEmitter.burstCount = 8;
+ childEmitter.lifetimeMin = childEmitter.lifetimeMax = 5.0f;
+ childEmitter.maxParticles = 400;
+
+ Entity parent = registry.create();
+ registry.emplace<ecs::Transform>(parent);
+ auto& parentEmitter = registry.emplace<ecs::ParticleEmitter>(parent);
+ parentEmitter.rate = 80.0f;
+ parentEmitter.lifetimeMin = parentEmitter.lifetimeMax = parentLifetime;
+ parentEmitter.maxParticles = 60;
+ parentEmitter.speedMin = parentEmitter.speedMax = 0.0f;
+ parentEmitter.playOnStart = true;
+ parentEmitter.subEmitter = child.id();
+ parentEmitter.subEmitterTrigger = static_cast<i32>(trigger);
+ return {parent, child};
+}
+
+TEST_CASE("system_subemitter_death_fires_child_burst") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ auto [parent, child] = makeSubEmitterPair(registry, ecs::SubEmitterTrigger::Death, 0.05f);
+
+ system.update(registry, 0.02f); // spawn parents; none have died yet
+ CHECK_EQ(system.aliveCount(child), 0u);
+
+ system.update(registry, 0.1f); // parents age past 0.05 s → die → child bursts
+ CHECK(system.aliveCount(child) > 0u);
+}
+
+TEST_CASE("system_subemitter_birth_fires_child_burst") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ // Long-lived parents so nothing dies — only births drive the child.
+ auto [parent, child] = makeSubEmitterPair(registry, ecs::SubEmitterTrigger::Birth, 5.0f);
+
+ system.update(registry, 0.1f); // parents are born → child bursts on each birth
+ CHECK(system.aliveCount(child) > 0u);
+}
+
+TEST_CASE("system_subemitter_none_leaves_child_empty") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ auto [parent, child] = makeSubEmitterPair(registry, ecs::SubEmitterTrigger::Death, 0.05f);
+ // Detach the sub-emitter: the child must never receive a burst.
+ registry.get<ecs::ParticleEmitter>(parent).subEmitter = 0;
+
+ system.update(registry, 0.02f);
+ system.update(registry, 0.2f);
+ CHECK_EQ(system.aliveCount(child), 0u);
+}
+
TEST_CASE("system_size_interpolation") {
ecs::Registry registry;
ParticleSystem system;