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(particles): emitters can simulate on the GPU

yhh4f297ebc2748
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9f2e70d81..3e453db77 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,7 @@ published separately; it ships inside the editor.
### Added
+- **GPU particles.** Particle emitters can now simulate on the GPU: turn on gpuSimulation and a compute kernel advances every particle, so an emitter of a hundred thousand or a million particles costs a dispatch instead of a loop. The kernel runs the same emitter: shapes, curl noise, force fields, gravity, damping, a floor plane, colour, size and speed over life and sprite sheets, up to 2,000,000 particles. Sub-emitters, trails and physics collision stay on the CPU, the particles are not sorted, and it needs WebGPU: on WebGL2 and mini-games the same emitter runs on the CPU, capped at 20,000 particles.
- **Contact shadows and screen-space bounce light.** Contact Shadows and Screen Space GI effects add small sharp shadows at contacts and one bounce of colour between surfaces, and the weather softens the sun's shadows. `contactShadows` marches a short ray toward the scene's sun in the depth buffer; `ssgi` gathers eight rays a pixel over the G-buffer's normals at half size into a float target and averages the neighbours on the same surface before laying the light, times the receiver's colour, over the picture. The Weather component raises the sun's `sourceAngle` and lowers its `shadowStrength` as the sky clouds over.
- **Terrain and Foliage.** A Terrain component makes ground from a heightmap or noise, paints it with grass, dirt, snow and rock layers and draws it in chunks that coarsen with distance; a Foliage component scatters grass or a mesh over it, swaying in the wind and thinning out with distance.
- **Separate material maps packed on import.** Importing an FBX with separate metalness, roughness and occlusion images now packs them into the one map the Model shader samples, instead of dropping them. Occlusion goes in red, roughness in green and metal in blue, each from its image's red channel (a glossiness map is inverted); a channel with no image stays at full so the material's own value speaks. Only PNG and DDS can be read.
diff --git a/cmake/ESEngineSources.cmake b/cmake/ESEngineSources.cmake
index c53586d52..141f2765e 100644
--- a/cmake/ESEngineSources.cmake
+++ b/cmake/ESEngineSources.cmake
@@ -116,6 +116,7 @@ endif()
if(ES_ENABLE_PARTICLES)
list(APPEND ESENGINE_SOURCES
${ESENGINE_ROOT}/src/esengine/renderer/plugins/ParticlePlugin.cpp
+ ${ESENGINE_ROOT}/src/esengine/renderer/frame/GpuParticles.cpp
${ESENGINE_ROOT}/src/esengine/particle/Particle.cpp
${ESENGINE_ROOT}/src/esengine/particle/ParticleSystem.cpp)
endif()
diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdx
index d30bde103..75eed9ab6 100644
--- a/docs/astro/src/content/docs/world/particles.mdx
+++ b/docs/astro/src/content/docs/world/particles.mdx
@@ -94,6 +94,7 @@ in degrees.
| `looping` | boolean | `true` | Restart after `duration` instead of stopping. |
| `playOnStart` | boolean | `true` | Begin emitting as soon as the entity exists. |
| `maxParticles` | number | `1000` | Pool size — the hard cap on live particles. |
+| `gpuSimulation` | boolean | `false` | Simulate on the GPU. See [GPU simulation](#gpu-simulation). |
### Lifetime
@@ -535,10 +536,47 @@ The Details panel shows these counters and transient hit normals. Normal display
is not saved to the scene. The sample `particle-demo/assets/scenes/scene-collisions.esscene`
demonstrates 2D and 3D walls, impact bursts and project-owned event counters.
+## GPU simulation
+
+Turn on `gpuSimulation` and the particles live on the GPU: a compute kernel advances every one of them each frame, and the
+draw reads what it wrote. The CPU only decides how many are born, so an emitter of a hundred thousand or a million particles
+costs a dispatch, not a loop. `maxParticles` is then the size of the ring the GPU keeps (up to 2,000,000); a new particle takes
+the next slot, and a slot whose particle has died is drawn as nothing.
+
+```ts
+world.insert(entity, ParticleEmitter, {
+ gpuSimulation: true,
+ maxParticles: 500_000,
+ rate: 200_000,
+ lifetimeMin: 2, lifetimeMax: 3,
+ shape: EmitterShape.Cone, shapeAngle: 40,
+ speedMin: 200, speedMax: 400,
+ gravity: { x: 0, y: -300, z: 0 },
+ noiseStrength: 40, noiseFrequency: 0.01,
+ collisionEnabled: true, collisionFloor: 0, collisionBounce: 0.4,
+});
+```
+
+It runs the same emitter, with the same shapes, curl noise, force fields (the first eight), gravity, damping, floor plane,
+color / size / speed over life and sprite sheets. Each emitter draws from a fixed seed of its own, so a scene replays the same
+particles. What it does not do:
+
+- **No sub-emitters, no per-particle trails, no scene-query collision** (`Physics2D` / `Physics3D`). A GPU emitter collides
+ with the floor plane only.
+- **Not sorted.** An `Additive` or cut-out look is exact; a deep pile of `Normal`-blended particles draws in slot order.
+- **Not in a UI tree.** An emitter under a `Canvas` draws through the screen overlay, which the kernel does not feed; leave it
+ on the CPU.
+- **`Particle.aliveCount` is an upper bound.** The GPU keeps the truth and nothing is read back.
+
+It needs a device with compute — WebGPU. On WebGL2 and in mini-game runtimes the same emitter runs on the CPU, **capped at
+20,000 particles**, so a scene built for a million still plays, thinner. Design the look to survive the cap if a platform
+without WebGPU matters to you.
+
## Performance & best practices
- **Budget `maxParticles`.** It's a fixed pool; size it to the worst case, not
- higher. Many small emitters beat one huge one for culling.
+ higher. Many small emitters beat one huge one for culling. Past a few thousand
+ particles, use [GPU simulation](#gpu-simulation).
- **Prefer `Additive` for light** (fire, sparks, magic) — it hides overdraw and
needs no sorting. Reserve `Normal`/`Multiply` for opaque smoke/dust.
- **Atlas particle textures** and share one `material` so emitters batch.
diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
index eff367ff3..312b91302 100644
--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx
+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
@@ -85,6 +85,7 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {
| `looping` | boolean | `true` | 到 `duration` 后重新开始,而不是停止。 |
| `playOnStart` | boolean | `true` | 实体一存在就开始发射。 |
| `maxParticles` | number | `1000` | 池大小——存活粒子的硬上限。 |
+| `gpuSimulation` | boolean | `false` | 在 GPU 上模拟。见 [GPU 模拟](#gpu-模拟)。 |
### 生命周期 (Lifetime)
@@ -487,10 +488,41 @@ const control = defineSystem([Res(Particle)], (particles) => {
Details 支持查看计数与临时碰撞法线,法线开关不写入场景。
`particle-demo/assets/scenes/scene-collisions.esscene` 示例包含 2D / 3D 墙面、撞击爆发与项目事件计数。
+## GPU 模拟
+
+打开 `gpuSimulation`,粒子就住在 GPU 上:每一帧由一个 compute kernel 推进全部粒子,绘制直接读它写出的结果。CPU 只决定
+这一帧诞生多少个,所以十万或百万粒子的发射器花的是一次 dispatch 而不是一个循环。这时 `maxParticles` 是 GPU 保存的环的大小
+(最多 2,000,000);新粒子占下一个槽位,粒子死亡后的槽位绘制为空。
+
+```ts
+world.insert(entity, ParticleEmitter, {
+ gpuSimulation: true,
+ maxParticles: 500_000,
+ rate: 200_000,
+ lifetimeMin: 2, lifetimeMax: 3,
+ shape: EmitterShape.Cone, shapeAngle: 40,
+ speedMin: 200, speedMax: 400,
+ gravity: { x: 0, y: -300, z: 0 },
+ noiseStrength: 40, noiseFrequency: 0.01,
+ collisionEnabled: true, collisionFloor: 0, collisionBounce: 0.4,
+});
+```
+
+它跑的是同一个发射器:形状、旋度噪声、力场(前八个)、重力、阻尼、地面平面、颜色 / 尺寸 / 速度随生命曲线和精灵表都一样。
+每个发射器用自己固定的种子,所以场景每次回放的粒子相同。它不做的事:
+
+- **没有子发射器、逐粒子拖尾和场景查询碰撞**(`Physics2D` / `Physics3D`)。GPU 发射器只和地面平面碰撞。
+- **不排序。** `Additive` 或镂空的效果是精确的;一大堆 `Normal` 混合的粒子按槽位顺序绘制。
+- **不能放在 UI 树里。** `Canvas` 下的发射器走屏幕叠加层绘制,kernel 不会喂给它;请留在 CPU 上。
+- **`Particle.aliveCount` 是上界。** 真实状态在 GPU 里,不做回读。
+
+它需要支持 compute 的设备——WebGPU。在 WebGL2 和小游戏运行时里,同一个发射器改在 CPU 上跑,**上限 20,000 个粒子**,
+所以为百万粒子做的场景仍能播放,只是更稀。如果在意没有 WebGPU 的平台,请让效果在这个上限下仍然成立。
+
## 性能与最佳实践
- **控制 `maxParticles`。** 它是固定池;按最坏情况定大小,别更高。多个小发射器比一个巨大的
- 更利于剔除。
+ 更利于剔除。超过几千个粒子时,改用 [GPU 模拟](#gpu-模拟)。
- **辉光优先用 `Additive`**(火焰、火花、魔法)——它掩盖 overdraw 且无需排序。不透明的
烟尘留给 `Normal`/`Multiply`。
- **把粒子贴图打成图集**并共享一个 `material`,让发射器合批。
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index babd426ed..2ddf1cd61 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -3042,6 +3042,12 @@
"default": "1000",
"range": "≥ 1, step 1"
},
+ {
+ "key": "gpuSimulation",
+ "type": "boolean",
+ "default": "false",
+ "doc": "Simulate on the GPU (WebGPU compute). Falls back to a capped CPU simulation elsewhere. Sub-emitters, trails and physics collision are CPU-only."
+ },
{
"key": "lifetimeMin",
"type": "number",
diff --git a/fixtures/scenes/particle-gpu-fountain.esscene b/fixtures/scenes/particle-gpu-fountain.esscene
new file mode 100644
index 000000000..bc0af8e65
--- /dev/null
+++ b/fixtures/scenes/particle-gpu-fountain.esscene
@@ -0,0 +1,108 @@
+{
+ "version": 4,
+ "name": "ParticleGpuFountain",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 100,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Emitter",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "ParticleEmitter",
+ "data": {
+ "rate": 40000,
+ "burstCount": 0,
+ "burstInterval": 1000,
+ "maxParticles": 100000,
+ "lifetimeMin": 2,
+ "lifetimeMax": 3,
+ "shape": 3,
+ "shapeSize": {
+ "x": 120,
+ "y": 120,
+ "z": 0
+ },
+ "speedMin": 80,
+ "speedMax": 160,
+ "startSizeMin": 2,
+ "startSizeMax": 3,
+ "endSizeMin": 1,
+ "endSizeMax": 1,
+ "gravity": {
+ "x": 0,
+ "y": -120,
+ "z": 0
+ },
+ "damping": 0,
+ "simulationSpace": 0,
+ "looping": true,
+ "playOnStart": true,
+ "startColor": {
+ "r": 1,
+ "g": 0.8,
+ "b": 0.3,
+ "a": 1
+ },
+ "endColor": {
+ "r": 1,
+ "g": 0.1,
+ "b": 0,
+ "a": 0
+ },
+ "gpuSimulation": true,
+ "shapeRadius": 10,
+ "shapeAngle": 60,
+ "noiseStrength": 30,
+ "noiseFrequency": 0.05,
+ "noiseOctaves": 2,
+ "collisionEnabled": true,
+ "collisionFloor": -80,
+ "collisionBounce": 0.5,
+ "collisionFriction": 0.1,
+ "blendMode": 1
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/scenes/particle-gpu-fountain.textures.json b/fixtures/scenes/particle-gpu-fountain.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/fixtures/scenes/particle-gpu-fountain.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/fixtures/scenes/particle-gpu-gradient.esscene b/fixtures/scenes/particle-gpu-gradient.esscene
new file mode 100644
index 000000000..bf065f0e1
--- /dev/null
+++ b/fixtures/scenes/particle-gpu-gradient.esscene
@@ -0,0 +1,116 @@
+{
+ "version": 4,
+ "name": "ParticleGpuGradient",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 100,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Grad",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "ParticleEmitter",
+ "data": {
+ "rate": 0,
+ "burstCount": 1,
+ "burstInterval": 1000,
+ "maxParticles": 1,
+ "lifetimeMin": 10,
+ "lifetimeMax": 10,
+ "shape": 0,
+ "speedMin": 0,
+ "speedMax": 0,
+ "startSizeMin": 120,
+ "startSizeMax": 120,
+ "endSizeMin": 120,
+ "endSizeMax": 120,
+ "gravity": {
+ "x": 0,
+ "y": 0
+ },
+ "damping": 0,
+ "simulationSpace": 0,
+ "looping": false,
+ "playOnStart": true,
+ "startColor": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "endColor": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "colorEasing": 1,
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",
+ "colorGradient": {
+ "stops": [
+ {
+ "t": 0,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ },
+ {
+ "t": 1,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ }
+ ]
+ },
+ "gpuSimulation": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/scenes/particle-gpu-gradient.textures.json b/fixtures/scenes/particle-gpu-gradient.textures.json
new file mode 100644
index 000000000..0acb647eb
--- /dev/null
+++ b/fixtures/scenes/particle-gpu-gradient.textures.json
@@ -0,0 +1,3 @@
+{
+ "24cb4e0f-7c75-4df4-9a4d-58480ee405c0": "/scenes/particle-demo/textures/particle.png"
+}
diff --git a/fixtures/scenes/particle-gpu-sizecurve.esscene b/fixtures/scenes/particle-gpu-sizecurve.esscene
new file mode 100644
index 000000000..9d9b5d4e6
--- /dev/null
+++ b/fixtures/scenes/particle-gpu-sizecurve.esscene
@@ -0,0 +1,133 @@
+{
+ "version": 4,
+ "name": "ParticleGpuSizeCurve",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 100,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "SizeGrad",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "ParticleEmitter",
+ "data": {
+ "rate": 0,
+ "burstCount": 1,
+ "burstInterval": 1000,
+ "maxParticles": 1,
+ "lifetimeMin": 10,
+ "lifetimeMax": 10,
+ "shape": 0,
+ "speedMin": 0,
+ "speedMax": 0,
+ "startSizeMin": 120,
+ "startSizeMax": 120,
+ "endSizeMin": 120,
+ "endSizeMax": 120,
+ "gravity": {
+ "x": 0,
+ "y": 0
+ },
+ "damping": 0,
+ "simulationSpace": 0,
+ "looping": false,
+ "playOnStart": true,
+ "startColor": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "endColor": {
+ "r": 1,
+ "g": 0,
+ "b": 0,
+ "a": 1
+ },
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",
+ "colorGradient": {
+ "stops": [
+ {
+ "t": 0,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ },
+ {
+ "t": 1,
+ "color": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ }
+ }
+ ]
+ },
+ "sizeCurve": {
+ "keys": [
+ {
+ "time": 0,
+ "value": 0.4,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ },
+ {
+ "time": 1,
+ "value": 0.4,
+ "inTangent": 0,
+ "outTangent": 0,
+ "interpolation": "linear"
+ }
+ ]
+ },
+ "gpuSimulation": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/scenes/particle-gpu-sizecurve.textures.json b/fixtures/scenes/particle-gpu-sizecurve.textures.json
new file mode 100644
index 000000000..0acb647eb
--- /dev/null
+++ b/fixtures/scenes/particle-gpu-sizecurve.textures.json
@@ -0,0 +1,3 @@
+{
+ "24cb4e0f-7c75-4df4-9a4d-58480ee405c0": "/scenes/particle-demo/textures/particle.png"
+}
diff --git a/fixtures/scenes/particle-gpu.esscene b/fixtures/scenes/particle-gpu.esscene
new file mode 100644
index 000000000..fcfe05200
--- /dev/null
+++ b/fixtures/scenes/particle-gpu.esscene
@@ -0,0 +1,98 @@
+{
+ "version": 4,
+ "name": "ParticleGpu",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 100,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Emitter",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "ParticleEmitter",
+ "data": {
+ "rate": 0,
+ "burstCount": 4000,
+ "burstInterval": 1000,
+ "maxParticles": 4000,
+ "lifetimeMin": 10,
+ "lifetimeMax": 10,
+ "shape": 2,
+ "shapeSize": {
+ "x": 120,
+ "y": 120,
+ "z": 0
+ },
+ "speedMin": 0,
+ "speedMax": 0,
+ "startSizeMin": 30,
+ "startSizeMax": 30,
+ "endSizeMin": 30,
+ "endSizeMax": 30,
+ "gravity": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "damping": 0,
+ "simulationSpace": 0,
+ "looping": false,
+ "playOnStart": true,
+ "startColor": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ },
+ "endColor": {
+ "r": 0,
+ "g": 1,
+ "b": 0,
+ "a": 1
+ },
+ "gpuSimulation": true
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/scenes/particle-gpu.textures.json b/fixtures/scenes/particle-gpu.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/fixtures/scenes/particle-gpu.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 169d452ba..1c87e0dc5 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 115 public · 159 beta · 1706 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"8eba82ff470da2d6"
+"0161363c22733817"
```
## ANCHOR_AXES — const @experimental
@@ -5963,6 +5963,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
+gpuSimulation: boolean
gravity: Vec3
layer: number
lifetimeMax: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 97806178e..a1333ff3b 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 115 public · 164 beta · 1725 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"8eba82ff470da2d6"
+"0161363c22733817"
```
## ANCHOR_AXES — const @experimental
@@ -6166,6 +6166,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
+gpuSimulation: boolean
gravity: Vec3
layer: number
lifetimeMax: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 0b7d9a5c8..ff267e6d3 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -5958,6 +5958,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
+gpuSimulation: boolean
gravity: Vec3
layer: number
lifetimeMax: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 25f33a6cc..cd2ecd6c7 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -6251,6 +6251,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
+gpuSimulation: boolean
gravity: Vec3
layer: number
lifetimeMax: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 6d8feb08e..af6c3ebf8 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5965,6 +5965,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
+gpuSimulation: boolean
gravity: Vec3
layer: number
lifetimeMax: number
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index f061238fe..79018f45a 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -1121,6 +1121,7 @@ export interface ParticleEmitterPtrData {
looping: boolean;
playOnStart: boolean;
maxParticles: number;
+ gpuSimulation: boolean;
lifetimeMin: number;
lifetimeMax: number;
shape: number;
@@ -1192,64 +1193,65 @@ export function fillParticleEmitter(
out.looping = u8[ptr + 16] !== 0;
out.playOnStart = u8[ptr + 17] !== 0;
out.maxParticles = u32[(ptr + 20) >> 2] | 0;
- out.lifetimeMin = f32[(ptr + 24) >> 2];
- out.lifetimeMax = f32[(ptr + 28) >> 2];
- out.shape = u32[(ptr + 32) >> 2] | 0;
- out.shapeRadius = f32[(ptr + 36) >> 2];
- const shapeSize_ = out.shapeSize; shapeSize_.x = f32[(ptr + 40) >> 2]; shapeSize_.y = f32[((ptr + 40) >> 2) + 1]; shapeSize_.z = f32[((ptr + 40) >> 2) + 2];
- out.shapeAngle = f32[(ptr + 52) >> 2];
- out.speedMin = f32[(ptr + 56) >> 2];
- out.speedMax = f32[(ptr + 60) >> 2];
- out.angleSpreadMin = f32[(ptr + 64) >> 2];
- out.angleSpreadMax = f32[(ptr + 68) >> 2];
- out.startSizeMin = f32[(ptr + 72) >> 2];
- out.startSizeMax = f32[(ptr + 76) >> 2];
- out.endSizeMin = f32[(ptr + 80) >> 2];
- out.endSizeMax = f32[(ptr + 84) >> 2];
- out.sizeEasing = u32[(ptr + 88) >> 2] | 0;
- const startColor_ = out.startColor; startColor_.r = f32[(ptr + 92) >> 2]; startColor_.g = f32[((ptr + 92) >> 2) + 1]; startColor_.b = f32[((ptr + 92) >> 2) + 2]; startColor_.a = f32[((ptr + 92) >> 2) + 3];
- const endColor_ = out.endColor; endColor_.r = f32[(ptr + 108) >> 2]; endColor_.g = f32[((ptr + 108) >> 2) + 1]; endColor_.b = f32[((ptr + 108) >> 2) + 2]; endColor_.a = f32[((ptr + 108) >> 2) + 3];
- out.colorEasing = u32[(ptr + 124) >> 2] | 0;
- out.rotationMin = f32[(ptr + 128) >> 2];
- out.rotationMax = f32[(ptr + 132) >> 2];
- out.angularVelocityMin = f32[(ptr + 136) >> 2];
- out.angularVelocityMax = f32[(ptr + 140) >> 2];
- const gravity_ = out.gravity; gravity_.x = f32[(ptr + 144) >> 2]; gravity_.y = f32[((ptr + 144) >> 2) + 1]; gravity_.z = f32[((ptr + 144) >> 2) + 2];
- out.damping = f32[(ptr + 156) >> 2];
- out.noiseStrength = f32[(ptr + 160) >> 2];
- out.noiseFrequency = f32[(ptr + 164) >> 2];
- out.noiseScrollSpeed = f32[(ptr + 168) >> 2];
- out.noiseOctaves = u32[(ptr + 172) >> 2] | 0;
- out.texture = u32[(ptr + 176) >> 2];
- out.spriteColumns = u32[(ptr + 180) >> 2] | 0;
- out.spriteRows = u32[(ptr + 184) >> 2] | 0;
- out.spriteFPS = f32[(ptr + 188) >> 2];
- out.spriteLoop = u8[ptr + 192] !== 0;
- out.blendMode = u32[(ptr + 196) >> 2] | 0;
- out.layer = u32[(ptr + 200) >> 2] | 0;
- out.material = u32[(ptr + 204) >> 2];
- out.simulationSpace = u32[(ptr + 208) >> 2] | 0;
- out.enabled = u8[ptr + 212] !== 0;
- out.subEmitterTrigger = u32[(ptr + 216) >> 2] | 0;
- out.subEmitterChance = f32[(ptr + 220) >> 2];
- out.subEmitterInheritVelocity = f32[(ptr + 224) >> 2];
- out.subEmitter = u32[(ptr + 228) >> 2];
- out.trailEnabled = u8[ptr + 232] !== 0;
- out.trailWidth = f32[(ptr + 236) >> 2];
- out.trailPoints = u32[(ptr + 240) >> 2] | 0;
- out.trailMinDistance = f32[(ptr + 244) >> 2];
- out.collisionEnabled = u8[ptr + 248] !== 0;
- out.collisionFloor = f32[(ptr + 252) >> 2];
- out.collisionMode = u32[(ptr + 256) >> 2] | 0;
- out.collisionMask = u32[(ptr + 260) >> 2];
- out.collisionQueryBudget = u32[(ptr + 264) >> 2] | 0;
- out.collisionMaxDistance = f32[(ptr + 268) >> 2];
- out.collisionFallback = u32[(ptr + 272) >> 2] | 0;
- out.collisionEvents = u8[ptr + 276] !== 0;
- out.collisionEventBudget = u32[(ptr + 280) >> 2] | 0;
- out.collisionBounce = f32[(ptr + 284) >> 2];
- out.collisionFriction = f32[(ptr + 288) >> 2];
- out.collisionLifetimeLoss = f32[(ptr + 292) >> 2];
+ out.gpuSimulation = u8[ptr + 24] !== 0;
+ out.lifetimeMin = f32[(ptr + 28) >> 2];
+ out.lifetimeMax = f32[(ptr + 32) >> 2];
+ out.shape = u32[(ptr + 36) >> 2] | 0;
+ out.shapeRadius = f32[(ptr + 40) >> 2];
+ const shapeSize_ = out.shapeSize; shapeSize_.x = f32[(ptr + 44) >> 2]; shapeSize_.y = f32[((ptr + 44) >> 2) + 1]; shapeSize_.z = f32[((ptr + 44) >> 2) + 2];
+ out.shapeAngle = f32[(ptr + 56) >> 2];
+ out.speedMin = f32[(ptr + 60) >> 2];
+ out.speedMax = f32[(ptr + 64) >> 2];
+ out.angleSpreadMin = f32[(ptr + 68) >> 2];
+ out.angleSpreadMax = f32[(ptr + 72) >> 2];
+ out.startSizeMin = f32[(ptr + 76) >> 2];
+ out.startSizeMax = f32[(ptr + 80) >> 2];
+ out.endSizeMin = f32[(ptr + 84) >> 2];
+ out.endSizeMax = f32[(ptr + 88) >> 2];
+ out.sizeEasing = u32[(ptr + 92) >> 2] | 0;
+ const startColor_ = out.startColor; startColor_.r = f32[(ptr + 96) >> 2]; startColor_.g = f32[((ptr + 96) >> 2) + 1]; startColor_.b = f32[((ptr + 96) >> 2) + 2]; startColor_.a = f32[((ptr + 96) >> 2) + 3];
+ const endColor_ = out.endColor; endColor_.r = f32[(ptr + 112) >> 2]; endColor_.g = f32[((ptr + 112) >> 2) + 1]; endColor_.b = f32[((ptr + 112) >> 2) + 2]; endColor_.a = f32[((ptr + 112) >> 2) + 3];
+ out.colorEasing = u32[(ptr + 128) >> 2] | 0;
+ out.rotationMin = f32[(ptr + 132) >> 2];
+ out.rotationMax = f32[(ptr + 136) >> 2];
+ out.angularVelocityMin = f32[(ptr + 140) >> 2];
+ out.angularVelocityMax = f32[(ptr + 144) >> 2];
+ const gravity_ = out.gravity; gravity_.x = f32[(ptr + 148) >> 2]; gravity_.y = f32[((ptr + 148) >> 2) + 1]; gravity_.z = f32[((ptr + 148) >> 2) + 2];
+ out.damping = f32[(ptr + 160) >> 2];
+ out.noiseStrength = f32[(ptr + 164) >> 2];
+ out.noiseFrequency = f32[(ptr + 168) >> 2];
+ out.noiseScrollSpeed = f32[(ptr + 172) >> 2];
+ out.noiseOctaves = u32[(ptr + 176) >> 2] | 0;
+ out.texture = u32[(ptr + 180) >> 2];
+ out.spriteColumns = u32[(ptr + 184) >> 2] | 0;
+ out.spriteRows = u32[(ptr + 188) >> 2] | 0;
+ out.spriteFPS = f32[(ptr + 192) >> 2];
+ out.spriteLoop = u8[ptr + 196] !== 0;
+ out.blendMode = u32[(ptr + 200) >> 2] | 0;
+ out.layer = u32[(ptr + 204) >> 2] | 0;
+ out.material = u32[(ptr + 208) >> 2];
+ out.simulationSpace = u32[(ptr + 212) >> 2] | 0;
+ out.enabled = u8[ptr + 216] !== 0;
+ out.subEmitterTrigger = u32[(ptr + 220) >> 2] | 0;
+ out.subEmitterChance = f32[(ptr + 224) >> 2];
+ out.subEmitterInheritVelocity = f32[(ptr + 228) >> 2];
+ out.subEmitter = u32[(ptr + 232) >> 2];
+ out.trailEnabled = u8[ptr + 236] !== 0;
+ out.trailWidth = f32[(ptr + 240) >> 2];
+ out.trailPoints = u32[(ptr + 244) >> 2] | 0;
+ out.trailMinDistance = f32[(ptr + 248) >> 2];
+ out.collisionEnabled = u8[ptr + 252] !== 0;
+ out.collisionFloor = f32[(ptr + 256) >> 2];
+ out.collisionMode = u32[(ptr + 260) >> 2] | 0;
+ out.collisionMask = u32[(ptr + 264) >> 2];
+ out.collisionQueryBudget = u32[(ptr + 268) >> 2] | 0;
+ out.collisionMaxDistance = f32[(ptr + 272) >> 2];
+ out.collisionFallback = u32[(ptr + 276) >> 2] | 0;
+ out.collisionEvents = u8[ptr + 280] !== 0;
+ out.collisionEventBudget = u32[(ptr + 284) >> 2] | 0;
+ out.collisionBounce = f32[(ptr + 288) >> 2];
+ out.collisionFriction = f32[(ptr + 292) >> 2];
+ out.collisionLifetimeLoss = f32[(ptr + 296) >> 2];
}
export function writeParticleEmitter(
@@ -1263,64 +1265,65 @@ export function writeParticleEmitter(
u8[ptr + 16] = data.looping ? 1 : 0;
u8[ptr + 17] = data.playOnStart ? 1 : 0;
u32[(ptr + 20) >> 2] = data.maxParticles | 0;
- f32[(ptr + 24) >> 2] = data.lifetimeMin;
- f32[(ptr + 28) >> 2] = data.lifetimeMax;
- u32[(ptr + 32) >> 2] = data.shape | 0;
- f32[(ptr + 36) >> 2] = data.shapeRadius;
- f32[(ptr + 40) >> 2] = data.shapeSize.x; f32[((ptr + 40) >> 2) + 1] = data.shapeSize.y; f32[((ptr + 40) >> 2) + 2] = data.shapeSize.z;
- f32[(ptr + 52) >> 2] = data.shapeAngle;
- f32[(ptr + 56) >> 2] = data.speedMin;
- f32[(ptr + 60) >> 2] = data.speedMax;
- f32[(ptr + 64) >> 2] = data.angleSpreadMin;
- f32[(ptr + 68) >> 2] = data.angleSpreadMax;
- f32[(ptr + 72) >> 2] = data.startSizeMin;
- f32[(ptr + 76) >> 2] = data.startSizeMax;
- f32[(ptr + 80) >> 2] = data.endSizeMin;
- f32[(ptr + 84) >> 2] = data.endSizeMax;
- u32[(ptr + 88) >> 2] = data.sizeEasing | 0;
- f32[(ptr + 92) >> 2] = data.startColor.r; f32[((ptr + 92) >> 2) + 1] = data.startColor.g; f32[((ptr + 92) >> 2) + 2] = data.startColor.b; f32[((ptr + 92) >> 2) + 3] = data.startColor.a;
- f32[(ptr + 108) >> 2] = data.endColor.r; f32[((ptr + 108) >> 2) + 1] = data.endColor.g; f32[((ptr + 108) >> 2) + 2] = data.endColor.b; f32[((ptr + 108) >> 2) + 3] = data.endColor.a;
- u32[(ptr + 124) >> 2] = data.colorEasing | 0;
- f32[(ptr + 128) >> 2] = data.rotationMin;
- f32[(ptr + 132) >> 2] = data.rotationMax;
- f32[(ptr + 136) >> 2] = data.angularVelocityMin;
- f32[(ptr + 140) >> 2] = data.angularVelocityMax;
- f32[(ptr + 144) >> 2] = data.gravity.x; f32[((ptr + 144) >> 2) + 1] = data.gravity.y; f32[((ptr + 144) >> 2) + 2] = data.gravity.z;
- f32[(ptr + 156) >> 2] = data.damping;
- f32[(ptr + 160) >> 2] = data.noiseStrength;
- f32[(ptr + 164) >> 2] = data.noiseFrequency;
- f32[(ptr + 168) >> 2] = data.noiseScrollSpeed;
- u32[(ptr + 172) >> 2] = data.noiseOctaves | 0;
- u32[(ptr + 176) >> 2] = data.texture;
- u32[(ptr + 180) >> 2] = data.spriteColumns | 0;
- u32[(ptr + 184) >> 2] = data.spriteRows | 0;
- f32[(ptr + 188) >> 2] = data.spriteFPS;
- u8[ptr + 192] = data.spriteLoop ? 1 : 0;
- u32[(ptr + 196) >> 2] = data.blendMode | 0;
- u32[(ptr + 200) >> 2] = data.layer | 0;
- u32[(ptr + 204) >> 2] = data.material;
- u32[(ptr + 208) >> 2] = data.simulationSpace | 0;
- u8[ptr + 212] = data.enabled ? 1 : 0;
- u32[(ptr + 216) >> 2] = data.subEmitterTrigger | 0;
- f32[(ptr + 220) >> 2] = data.subEmitterChance;
- f32[(ptr + 224) >> 2] = data.subEmitterInheritVelocity;
- u32[(ptr + 228) >> 2] = data.subEmitter;
- u8[ptr + 232] = data.trailEnabled ? 1 : 0;
- f32[(ptr + 236) >> 2] = data.trailWidth;
- u32[(ptr + 240) >> 2] = data.trailPoints | 0;
- f32[(ptr + 244) >> 2] = data.trailMinDistance;
- u8[ptr + 248] = data.collisionEnabled ? 1 : 0;
- f32[(ptr + 252) >> 2] = data.collisionFloor;
- u32[(ptr + 256) >> 2] = data.collisionMode | 0;
- u32[(ptr + 260) >> 2] = data.collisionMask;
- u32[(ptr + 264) >> 2] = data.collisionQueryBudget | 0;
- f32[(ptr + 268) >> 2] = data.collisionMaxDistance;
- u32[(ptr + 272) >> 2] = data.collisionFallback | 0;
- u8[ptr + 276] = data.collisionEvents ? 1 : 0;
- u32[(ptr + 280) >> 2] = data.collisionEventBudget | 0;
- f32[(ptr + 284) >> 2] = data.collisionBounce;
- f32[(ptr + 288) >> 2] = data.collisionFriction;
- f32[(ptr + 292) >> 2] = data.collisionLifetimeLoss;
+ u8[ptr + 24] = data.gpuSimulation ? 1 : 0;
+ f32[(ptr + 28) >> 2] = data.lifetimeMin;
+ f32[(ptr + 32) >> 2] = data.lifetimeMax;
+ u32[(ptr + 36) >> 2] = data.shape | 0;
+ f32[(ptr + 40) >> 2] = data.shapeRadius;
+ f32[(ptr + 44) >> 2] = data.shapeSize.x; f32[((ptr + 44) >> 2) + 1] = data.shapeSize.y; f32[((ptr + 44) >> 2) + 2] = data.shapeSize.z;
+ f32[(ptr + 56) >> 2] = data.shapeAngle;
+ f32[(ptr + 60) >> 2] = data.speedMin;
+ f32[(ptr + 64) >> 2] = data.speedMax;
+ f32[(ptr + 68) >> 2] = data.angleSpreadMin;
+ f32[(ptr + 72) >> 2] = data.angleSpreadMax;
+ f32[(ptr + 76) >> 2] = data.startSizeMin;
+ f32[(ptr + 80) >> 2] = data.startSizeMax;
+ f32[(ptr + 84) >> 2] = data.endSizeMin;
+ f32[(ptr + 88) >> 2] = data.endSizeMax;
+ u32[(ptr + 92) >> 2] = data.sizeEasing | 0;
+ f32[(ptr + 96) >> 2] = data.startColor.r; f32[((ptr + 96) >> 2) + 1] = data.startColor.g; f32[((ptr + 96) >> 2) + 2] = data.startColor.b; f32[((ptr + 96) >> 2) + 3] = data.startColor.a;
+ f32[(ptr + 112) >> 2] = data.endColor.r; f32[((ptr + 112) >> 2) + 1] = data.endColor.g; f32[((ptr + 112) >> 2) + 2] = data.endColor.b; f32[((ptr + 112) >> 2) + 3] = data.endColor.a;
+ u32[(ptr + 128) >> 2] = data.colorEasing | 0;
+ f32[(ptr + 132) >> 2] = data.rotationMin;
+ f32[(ptr + 136) >> 2] = data.rotationMax;
+ f32[(ptr + 140) >> 2] = data.angularVelocityMin;
+ f32[(ptr + 144) >> 2] = data.angularVelocityMax;
+ f32[(ptr + 148) >> 2] = data.gravity.x; f32[((ptr + 148) >> 2) + 1] = data.gravity.y; f32[((ptr + 148) >> 2) + 2] = data.gravity.z;
+ f32[(ptr + 160) >> 2] = data.damping;
+ f32[(ptr + 164) >> 2] = data.noiseStrength;
+ f32[(ptr + 168) >> 2] = data.noiseFrequency;
+ f32[(ptr + 172) >> 2] = data.noiseScrollSpeed;
+ u32[(ptr + 176) >> 2] = data.noiseOctaves | 0;
+ u32[(ptr + 180) >> 2] = data.texture;
+ u32[(ptr + 184) >> 2] = data.spriteColumns | 0;
+ u32[(ptr + 188) >> 2] = data.spriteRows | 0;
+ f32[(ptr + 192) >> 2] = data.spriteFPS;
+ u8[ptr + 196] = data.spriteLoop ? 1 : 0;
+ u32[(ptr + 200) >> 2] = data.blendMode | 0;
+ u32[(ptr + 204) >> 2] = data.layer | 0;
+ u32[(ptr + 208) >> 2] = data.material;
+ u32[(ptr + 212) >> 2] = data.simulationSpace | 0;
+ u8[ptr + 216] = data.enabled ? 1 : 0;
+ u32[(ptr + 220) >> 2] = data.subEmitterTrigger | 0;
+ f32[(ptr + 224) >> 2] = data.subEmitterChance;
+ f32[(ptr + 228) >> 2] = data.subEmitterInheritVelocity;
+ u32[(ptr + 232) >> 2] = data.subEmitter;
+ u8[ptr + 236] = data.trailEnabled ? 1 : 0;
+ f32[(ptr + 240) >> 2] = data.trailWidth;
+ u32[(ptr + 244) >> 2] = data.trailPoints | 0;
+ f32[(ptr + 248) >> 2] = data.trailMinDistance;
+ u8[ptr + 252] = data.collisionEnabled ? 1 : 0;
+ f32[(ptr + 256) >> 2] = data.collisionFloor;
+ u32[(ptr + 260) >> 2] = data.collisionMode | 0;
+ u32[(ptr + 264) >> 2] = data.collisionMask;
+ u32[(ptr + 268) >> 2] = data.collisionQueryBudget | 0;
+ f32[(ptr + 272) >> 2] = data.collisionMaxDistance;
+ u32[(ptr + 276) >> 2] = data.collisionFallback | 0;
+ u8[ptr + 280] = data.collisionEvents ? 1 : 0;
+ u32[(ptr + 284) >> 2] = data.collisionEventBudget | 0;
+ f32[(ptr + 288) >> 2] = data.collisionBounce;
+ f32[(ptr + 292) >> 2] = data.collisionFriction;
+ f32[(ptr + 296) >> 2] = data.collisionLifetimeLoss;
}
export function createParticleEmitterData(): ParticleEmitterPtrData {
@@ -1332,6 +1335,7 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {
looping: false,
playOnStart: false,
maxParticles: 0,
+ gpuSimulation: false,
lifetimeMin: 0,
lifetimeMax: 0,
shape: 0,
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 6e0e78a85..7584a7d07 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '8eba82ff470da2d6';
+export const ABI_LAYOUT_HASH = '0161363c22733817';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -654,6 +654,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
looping: true,
playOnStart: true,
maxParticles: 1000,
+ gpuSimulation: false,
lifetimeMin: 5,
lifetimeMax: 5,
shape: 3,
@@ -726,6 +727,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
looping: { category: "Emission" },
playOnStart: { category: "Emission" },
maxParticles: { min: 1, step: 1, category: "Emission" },
+ gpuSimulation: { tooltip: "Simulate on the GPU (WebGPU compute). Falls back to a capped CPU simulation elsewhere. Sub-emitters, trails and physics collision are CPU-only.", category: "Emission" },
lifetimeMin: { min: 0, category: "Lifetime" },
lifetimeMax: { min: 0, category: "Lifetime" },
shape: { enum: [{ label: 'Point', value: 0 }, { label: 'Circle', value: 1 }, { label: 'Box', value: 2 }, { label: 'Cone', value: 3 }, { label: 'Sphere', value: 4 }, { label: 'Hemisphere', value: 5 }], category: "Shape" },
@@ -1590,6 +1592,7 @@ export interface ParticleEmitterData {
looping: boolean;
playOnStart: boolean;
maxParticles: number;
+ gpuSimulation: boolean;
lifetimeMin: number;
lifetimeMax: number;
shape: EmitterShape;
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index 334f55887..29bba6842 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -313,64 +313,65 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'looping', type: 'bool', offset: 16 },
{ name: 'playOnStart', type: 'bool', offset: 17 },
{ name: 'maxParticles', type: 'i32', offset: 20 },
- { name: 'lifetimeMin', type: 'f32', offset: 24 },
- { name: 'lifetimeMax', type: 'f32', offset: 28 },
- { name: 'shape', type: 'i32', offset: 32 },
- { name: 'shapeRadius', type: 'f32', offset: 36 },
- { name: 'shapeSize', type: 'vec3', offset: 40 },
- { name: 'shapeAngle', type: 'f32', offset: 52 },
- { name: 'speedMin', type: 'f32', offset: 56 },
- { name: 'speedMax', type: 'f32', offset: 60 },
- { name: 'angleSpreadMin', type: 'f32', offset: 64 },
- { name: 'angleSpreadMax', type: 'f32', offset: 68 },
- { name: 'startSizeMin', type: 'f32', offset: 72 },
- { name: 'startSizeMax', type: 'f32', offset: 76 },
- { name: 'endSizeMin', type: 'f32', offset: 80 },
- { name: 'endSizeMax', type: 'f32', offset: 84 },
- { name: 'sizeEasing', type: 'i32', offset: 88 },
- { name: 'startColor', type: 'color', offset: 92 },
- { name: 'endColor', type: 'color', offset: 108 },
- { name: 'colorEasing', type: 'i32', offset: 124 },
- { name: 'rotationMin', type: 'f32', offset: 128 },
- { name: 'rotationMax', type: 'f32', offset: 132 },
- { name: 'angularVelocityMin', type: 'f32', offset: 136 },
- { name: 'angularVelocityMax', type: 'f32', offset: 140 },
- { name: 'gravity', type: 'vec3', offset: 144 },
- { name: 'damping', type: 'f32', offset: 156 },
- { name: 'noiseStrength', type: 'f32', offset: 160 },
- { name: 'noiseFrequency', type: 'f32', offset: 164 },
- { name: 'noiseScrollSpeed', type: 'f32', offset: 168 },
- { name: 'noiseOctaves', type: 'i32', offset: 172 },
- { name: 'texture', type: 'u32', offset: 176 },
- { name: 'spriteColumns', type: 'i32', offset: 180 },
- { name: 'spriteRows', type: 'i32', offset: 184 },
- { name: 'spriteFPS', type: 'f32', offset: 188 },
- { name: 'spriteLoop', type: 'bool', offset: 192 },
- { name: 'blendMode', type: 'i32', offset: 196 },
- { name: 'layer', type: 'i32', offset: 200 },
- { name: 'material', type: 'u32', offset: 204 },
- { name: 'simulationSpace', type: 'i32', offset: 208 },
- { name: 'enabled', type: 'bool', offset: 212 },
- { name: 'subEmitterTrigger', type: 'i32', offset: 216 },
- { name: 'subEmitterChance', type: 'f32', offset: 220 },
- { name: 'subEmitterInheritVelocity', type: 'f32', offset: 224 },
- { name: 'subEmitter', type: 'u32', offset: 228 },
- { name: 'trailEnabled', type: 'bool', offset: 232 },
- { name: 'trailWidth', type: 'f32', offset: 236 },
- { name: 'trailPoints', type: 'i32', offset: 240 },
- { name: 'trailMinDistance', type: 'f32', offset: 244 },
- { name: 'collisionEnabled', type: 'bool', offset: 248 },
- { name: 'collisionFloor', type: 'f32', offset: 252 },
- { name: 'collisionMode', type: 'i32', offset: 256 },
- { name: 'collisionMask', type: 'u32', offset: 260 },
- { name: 'collisionQueryBudget', type: 'i32', offset: 264 },
- { name: 'collisionMaxDistance', type: 'f32', offset: 268 },
- { name: 'collisionFallback', type: 'i32', offset: 272 },
- { name: 'collisionEvents', type: 'bool', offset: 276 },
- { name: 'collisionEventBudget', type: 'i32', offset: 280 },
- { name: 'collisionBounce', type: 'f32', offset: 284 },
- { name: 'collisionFriction', type: 'f32', offset: 288 },
- { name: 'collisionLifetimeLoss', type: 'f32', offset: 292 },
+ { name: 'gpuSimulation', type: 'bool', offset: 24 },
+ { name: 'lifetimeMin', type: 'f32', offset: 28 },
+ { name: 'lifetimeMax', type: 'f32', offset: 32 },
+ { name: 'shape', type: 'i32', offset: 36 },
+ { name: 'shapeRadius', type: 'f32', offset: 40 },
+ { name: 'shapeSize', type: 'vec3', offset: 44 },
+ { name: 'shapeAngle', type: 'f32', offset: 56 },
+ { name: 'speedMin', type: 'f32', offset: 60 },
+ { name: 'speedMax', type: 'f32', offset: 64 },
+ { name: 'angleSpreadMin', type: 'f32', offset: 68 },
+ { name: 'angleSpreadMax', type: 'f32', offset: 72 },
+ { name: 'startSizeMin', type: 'f32', offset: 76 },
+ { name: 'startSizeMax', type: 'f32', offset: 80 },
+ { name: 'endSizeMin', type: 'f32', offset: 84 },
+ { name: 'endSizeMax', type: 'f32', offset: 88 },
+ { name: 'sizeEasing', type: 'i32', offset: 92 },
+ { name: 'startColor', type: 'color', offset: 96 },
+ { name: 'endColor', type: 'color', offset: 112 },
+ { name: 'colorEasing', type: 'i32', offset: 128 },
+ { name: 'rotationMin', type: 'f32', offset: 132 },
+ { name: 'rotationMax', type: 'f32', offset: 136 },
+ { name: 'angularVelocityMin', type: 'f32', offset: 140 },
+ { name: 'angularVelocityMax', type: 'f32', offset: 144 },
+ { name: 'gravity', type: 'vec3', offset: 148 },
+ { name: 'damping', type: 'f32', offset: 160 },
+ { name: 'noiseStrength', type: 'f32', offset: 164 },
+ { name: 'noiseFrequency', type: 'f32', offset: 168 },
+ { name: 'noiseScrollSpeed', type: 'f32', offset: 172 },
+ { name: 'noiseOctaves', type: 'i32', offset: 176 },
+ { name: 'texture', type: 'u32', offset: 180 },
+ { name: 'spriteColumns', type: 'i32', offset: 184 },
+ { name: 'spriteRows', type: 'i32', offset: 188 },
+ { name: 'spriteFPS', type: 'f32', offset: 192 },
+ { name: 'spriteLoop', type: 'bool', offset: 196 },
+ { name: 'blendMode', type: 'i32', offset: 200 },
+ { name: 'layer', type: 'i32', offset: 204 },
+ { name: 'material', type: 'u32', offset: 208 },
+ { name: 'simulationSpace', type: 'i32', offset: 212 },
+ { name: 'enabled', type: 'bool', offset: 216 },
+ { name: 'subEmitterTrigger', type: 'i32', offset: 220 },
+ { name: 'subEmitterChance', type: 'f32', offset: 224 },
+ { name: 'subEmitterInheritVelocity', type: 'f32', offset: 228 },
+ { name: 'subEmitter', type: 'u32', offset: 232 },
+ { name: 'trailEnabled', type: 'bool', offset: 236 },
+ { name: 'trailWidth', type: 'f32', offset: 240 },
+ { name: 'trailPoints', type: 'i32', offset: 244 },
+ { name: 'trailMinDistance', type: 'f32', offset: 248 },
+ { name: 'collisionEnabled', type: 'bool', offset: 252 },
+ { name: 'collisionFloor', type: 'f32', offset: 256 },
+ { name: 'collisionMode', type: 'i32', offset: 260 },
+ { name: 'collisionMask', type: 'u32', offset: 264 },
+ { name: 'collisionQueryBudget', type: 'i32', offset: 268 },
+ { name: 'collisionMaxDistance', type: 'f32', offset: 272 },
+ { name: 'collisionFallback', type: 'i32', offset: 276 },
+ { name: 'collisionEvents', type: 'bool', offset: 280 },
+ { name: 'collisionEventBudget', type: 'i32', offset: 284 },
+ { name: 'collisionBounce', type: 'f32', offset: 288 },
+ { name: 'collisionFriction', type: 'f32', offset: 292 },
+ { name: 'collisionLifetimeLoss', type: 'f32', offset: 296 },
],
},
ParticleForceField: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index bfeae31a5..c4e6e9f5a 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -686,6 +686,7 @@ export interface ParticleEmitter {
looping: boolean;
playOnStart: boolean;
maxParticles: number;
+ gpuSimulation: boolean;
lifetimeMin: number;
lifetimeMax: number;
shape: number;
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 92e70807f..68f998deb 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -802,6 +802,10 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"category": "Size",
"min": 0,
},
+ "gpuSimulation": {
+ "category": "Emission",
+ "tooltip": "Simulate on the GPU (WebGPU compute). Falls back to a capped CPU simulation elsewhere. Sub-emitters, trails and physics collision are CPU-only.",
+ },
"gravity": {
"category": "Velocity",
},
diff --git a/src/esengine/aot/EngineDigest.generated.h b/src/esengine/aot/EngineDigest.generated.h
index d650d0992..e7221071f 100644
--- a/src/esengine/aot/EngineDigest.generated.h
+++ b/src/esengine/aot/EngineDigest.generated.h
@@ -6,7 +6,7 @@
/* One per address width, because the width is IN the digest: a host that
took the other one would refuse every module built for it. */
-#define ES_ENGINE_ABI_DIGEST_32 0x2442b4c2fa79d124ULL
-#define ES_ENGINE_ABI_DIGEST_64 0x83e8a5bdeea599a8ULL
+#define ES_ENGINE_ABI_DIGEST_32 0x05bd8752447266c5ULL
+#define ES_ENGINE_ABI_DIGEST_64 0x8ecf13a182e11801ULL
#define ES_ENGINE_ABI_DIGEST \
(sizeof(es_addr_t) == 8 ? ES_ENGINE_ABI_DIGEST_64 : ES_ENGINE_ABI_DIGEST_32)
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 1b6e5eaf8..0e8e29edd 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 1d33842a5824a059
+ * @schema_hash 4f90a13f387495ca
*/
-#define ES_EDITOR_API_SCHEMA_HASH "1d33842a5824a059"
+#define ES_EDITOR_API_SCHEMA_HASH "4f90a13f387495ca"
#include <emscripten/bind.h>
#include <string>
@@ -434,6 +434,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"looping","type":"bool","group":"ParticleEmitter"},
{"key":"playOnStart","type":"bool","group":"ParticleEmitter"},
{"key":"maxParticles","type":"int","group":"ParticleEmitter"},
+ {"key":"gpuSimulation","type":"bool","group":"ParticleEmitter"},
{"key":"lifetimeMin","type":"float","group":"ParticleEmitter"},
{"key":"lifetimeMax","type":"float","group":"ParticleEmitter"},
{"key":"shape","type":"int","group":"ParticleEmitter"},
@@ -2887,6 +2888,7 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
if (field == "looping") { c.looping = value; }
else if (field == "playOnStart") { c.playOnStart = value; }
+ else if (field == "gpuSimulation") { c.gpuSimulation = value; }
else if (field == "spriteLoop") { c.spriteLoop = value; }
else if (field == "enabled") { c.enabled = value; }
else if (field == "trailEnabled") { c.trailEnabled = value; }
@@ -3141,6 +3143,7 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
const auto& c = reg.get<esengine::ecs::ParticleEmitter>(entity);
if (field == "looping") { return c.looping; }
else if (field == "playOnStart") { return c.playOnStart; }
+ else if (field == "gpuSimulation") { return c.gpuSimulation; }
else if (field == "spriteLoop") { return c.spriteLoop; }
else if (field == "enabled") { return c.enabled; }
else if (field == "trailEnabled") { return c.trailEnabled; }
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index 1902f0778..98d3c9674 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -874,6 +874,7 @@ struct ParticleEmitterJS {
bool looping;
bool playOnStart;
i32 maxParticles;
+ bool gpuSimulation;
f32 lifetimeMin;
f32 lifetimeMax;
i32 shape;
@@ -942,6 +943,7 @@ void particleemitterApplyJS(esengine::ecs::ParticleEmitter& c, const ParticleEmi
c.looping = js.looping;
c.playOnStart = js.playOnStart;
c.maxParticles = js.maxParticles;
+ c.gpuSimulation = js.gpuSimulation;
c.lifetimeMin = js.lifetimeMin;
c.lifetimeMax = js.lifetimeMax;
c.shape = js.shape;
@@ -1017,6 +1019,7 @@ ParticleEmitterJS particleemitterToJS(const esengine::ecs::ParticleEmitter& c) {
js.looping = c.looping;
js.playOnStart = c.playOnStart;
js.maxParticles = c.maxParticles;
+ js.gpuSimulation = c.gpuSimulation;
js.lifetimeMin = c.lifetimeMin;
js.lifetimeMax = c.lifetimeMax;
js.shape = c.shape;
@@ -1891,6 +1894,7 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("looping", &ParticleEmitterJS::looping)
.field("playOnStart", &ParticleEmitterJS::playOnStart)
.field("maxParticles", &ParticleEmitterJS::maxParticles)
+ .field("gpuSimulation", &ParticleEmitterJS::gpuSimulation)
.field("lifetimeMin", &ParticleEmitterJS::lifetimeMin)
.field("lifetimeMax", &ParticleEmitterJS::lifetimeMax)
.field("shape", &ParticleEmitterJS::shape)
@@ -3660,64 +3664,65 @@ static_assert(offsetof(esengine::ecs::ParticleEmitter, duration) == 12, "ABI off
static_assert(offsetof(esengine::ecs::ParticleEmitter, looping) == 16, "ABI offset drift: esengine::ecs::ParticleEmitter.looping (EHT expected 16)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, playOnStart) == 17, "ABI offset drift: esengine::ecs::ParticleEmitter.playOnStart (EHT expected 17)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, maxParticles) == 20, "ABI offset drift: esengine::ecs::ParticleEmitter.maxParticles (EHT expected 20)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMin) == 24, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMin (EHT expected 24)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMax) == 28, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMax (EHT expected 28)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, shape) == 32, "ABI offset drift: esengine::ecs::ParticleEmitter.shape (EHT expected 32)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeRadius) == 36, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeRadius (EHT expected 36)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeSize) == 40, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeSize (EHT expected 40)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeAngle) == 52, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeAngle (EHT expected 52)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMin) == 56, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMin (EHT expected 56)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMax) == 60, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMax (EHT expected 60)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMin) == 64, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMin (EHT expected 64)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMax) == 68, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMax (EHT expected 68)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMin) == 72, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMin (EHT expected 72)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMax) == 76, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMax (EHT expected 76)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMin) == 80, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMin (EHT expected 80)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMax) == 84, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMax (EHT expected 84)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, sizeEasing) == 88, "ABI offset drift: esengine::ecs::ParticleEmitter.sizeEasing (EHT expected 88)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, startColor) == 92, "ABI offset drift: esengine::ecs::ParticleEmitter.startColor (EHT expected 92)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, endColor) == 108, "ABI offset drift: esengine::ecs::ParticleEmitter.endColor (EHT expected 108)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, colorEasing) == 124, "ABI offset drift: esengine::ecs::ParticleEmitter.colorEasing (EHT expected 124)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMin) == 128, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMin (EHT expected 128)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMax) == 132, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMax (EHT expected 132)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMin) == 136, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMin (EHT expected 136)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMax) == 140, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMax (EHT expected 140)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, gravity) == 144, "ABI offset drift: esengine::ecs::ParticleEmitter.gravity (EHT expected 144)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, damping) == 156, "ABI offset drift: esengine::ecs::ParticleEmitter.damping (EHT expected 156)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseStrength) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseStrength (EHT expected 160)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseFrequency) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseFrequency (EHT expected 164)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseScrollSpeed) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseScrollSpeed (EHT expected 168)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseOctaves) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseOctaves (EHT expected 172)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 176)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 180)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 184)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 188)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 192, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 192)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 196, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 196)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 200, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 200)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 204, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 204)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 208, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 208)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 212, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 212)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterTrigger) == 216, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterTrigger (EHT expected 216)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterChance) == 220, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterChance (EHT expected 220)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterInheritVelocity) == 224, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterInheritVelocity (EHT expected 224)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitter) == 228, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitter (EHT expected 228)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailEnabled) == 232, "ABI offset drift: esengine::ecs::ParticleEmitter.trailEnabled (EHT expected 232)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailWidth) == 236, "ABI offset drift: esengine::ecs::ParticleEmitter.trailWidth (EHT expected 236)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 240, "ABI offset drift: esengine::ecs::ParticleEmitter.trailPoints (EHT expected 240)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 244)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 248)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 252)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMode) == 256, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMode (EHT expected 256)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMask) == 260, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMask (EHT expected 260)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionQueryBudget) == 264, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionQueryBudget (EHT expected 264)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMaxDistance) == 268, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMaxDistance (EHT expected 268)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFallback) == 272, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFallback (EHT expected 272)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEvents) == 276, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEvents (EHT expected 276)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEventBudget) == 280, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEventBudget (EHT expected 280)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionBounce) == 284, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionBounce (EHT expected 284)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFriction) == 288, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFriction (EHT expected 288)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionLifetimeLoss) == 292, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionLifetimeLoss (EHT expected 292)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, gpuSimulation) == 24, "ABI offset drift: esengine::ecs::ParticleEmitter.gpuSimulation (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMin) == 28, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMin (EHT expected 28)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMax) == 32, "ABI offset drift: esengine::ecs::ParticleEmitter.lifetimeMax (EHT expected 32)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shape) == 36, "ABI offset drift: esengine::ecs::ParticleEmitter.shape (EHT expected 36)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeRadius) == 40, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeRadius (EHT expected 40)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeSize) == 44, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeSize (EHT expected 44)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeAngle) == 56, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeAngle (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMin) == 60, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMin (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMax) == 64, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMax (EHT expected 64)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMin) == 68, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMin (EHT expected 68)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMax) == 72, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMax (EHT expected 72)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMin) == 76, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMin (EHT expected 76)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMax) == 80, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMax (EHT expected 80)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMin) == 84, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMin (EHT expected 84)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMax) == 88, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMax (EHT expected 88)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, sizeEasing) == 92, "ABI offset drift: esengine::ecs::ParticleEmitter.sizeEasing (EHT expected 92)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startColor) == 96, "ABI offset drift: esengine::ecs::ParticleEmitter.startColor (EHT expected 96)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endColor) == 112, "ABI offset drift: esengine::ecs::ParticleEmitter.endColor (EHT expected 112)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, colorEasing) == 128, "ABI offset drift: esengine::ecs::ParticleEmitter.colorEasing (EHT expected 128)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMin) == 132, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMin (EHT expected 132)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMax) == 136, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMax (EHT expected 136)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMin) == 140, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMin (EHT expected 140)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMax) == 144, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMax (EHT expected 144)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, gravity) == 148, "ABI offset drift: esengine::ecs::ParticleEmitter.gravity (EHT expected 148)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, damping) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.damping (EHT expected 160)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseStrength) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseStrength (EHT expected 164)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseFrequency) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseFrequency (EHT expected 168)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseScrollSpeed) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseScrollSpeed (EHT expected 172)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseOctaves) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseOctaves (EHT expected 176)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 180)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 184)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 188)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 192, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 192)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 196, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 196)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 200, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 200)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 204, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 204)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 208, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 208)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 212, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 212)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 216, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 216)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterTrigger) == 220, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterTrigger (EHT expected 220)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterChance) == 224, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterChance (EHT expected 224)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterInheritVelocity) == 228, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterInheritVelocity (EHT expected 228)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitter) == 232, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitter (EHT expected 232)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailEnabled) == 236, "ABI offset drift: esengine::ecs::ParticleEmitter.trailEnabled (EHT expected 236)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailWidth) == 240, "ABI offset drift: esengine::ecs::ParticleEmitter.trailWidth (EHT expected 240)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.trailPoints (EHT expected 244)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 248)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 252)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 256, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 256)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMode) == 260, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMode (EHT expected 260)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMask) == 264, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMask (EHT expected 264)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionQueryBudget) == 268, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionQueryBudget (EHT expected 268)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMaxDistance) == 272, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMaxDistance (EHT expected 272)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFallback) == 276, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFallback (EHT expected 276)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEvents) == 280, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEvents (EHT expected 280)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEventBudget) == 284, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEventBudget (EHT expected 284)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionBounce) == 288, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionBounce (EHT expected 288)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFriction) == 292, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFriction (EHT expected 292)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionLifetimeLoss) == 296, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionLifetimeLoss (EHT expected 296)");
static_assert(offsetof(esengine::ecs::ParticleForceField, type) == 0, "ABI offset drift: esengine::ecs::ParticleForceField.type (EHT expected 0)");
static_assert(offsetof(esengine::ecs::ParticleForceField, strength) == 4, "ABI offset drift: esengine::ecs::ParticleForceField.strength (EHT expected 4)");
static_assert(offsetof(esengine::ecs::ParticleForceField, radius) == 8, "ABI offset drift: esengine::ecs::ParticleForceField.radius (EHT expected 8)");
@@ -3901,7 +3906,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "8eba82ff470da2d6";
+static const char* kEsAbiLayoutHash = "0161363c22733817";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hpp
index 6b896ede8..e1e7d7928 100644
--- a/src/esengine/ecs/components/ParticleEmitter.hpp
+++ b/src/esengine/ecs/components/ParticleEmitter.hpp
@@ -84,6 +84,12 @@ struct ParticleEmitter {
ES_PROPERTY(min=1, step=1, category=Emission)
i32 maxParticles{1000};
+ // Simulated by a compute kernel (WebGPU); elsewhere the emitter runs on the CPU, capped. Gravity, damping,
+ // noise, force fields, the floor plane and over-life curves apply; sub-emitters, trails and
+ // scene-query collision are CPU-only.
+ ES_PROPERTY(category=Emission, tooltip="Simulate on the GPU (WebGPU compute). Falls back to a capped CPU simulation elsewhere. Sub-emitters, trails and physics collision are CPU-only.")
+ bool gpuSimulation{false};
+
// Lifetime
ES_PROPERTY(min=0, category=Lifetime)
f32 lifetimeMin{5.0f};
diff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cpp
index f03f86194..a2969db26 100644
--- a/src/esengine/particle/ParticleSystem.cpp
+++ b/src/esengine/particle/ParticleSystem.cpp
@@ -86,7 +86,33 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
continue;
}
+ // A GPU emitter keeps no pool: its particles live in a GPU ring. Where the device cannot compute it
+ // is an ordinary emitter, capped so a million-particle setup cannot take the CPU down with it.
+ const bool useGpu = emitter.gpuSimulation && gpu_available_;
+ u32 capacity = static_cast<u32>(std::clamp(emitter.maxParticles, 0, 1'000'000));
+ if (emitter.gpuSimulation && !gpu_available_) capacity = std::min(capacity, kGpuFallbackCapacity);
+ if (useGpu) capacity = static_cast<u32>(std::clamp(emitter.maxParticles, 0, static_cast<i32>(kGpuMaxCapacity)));
+
auto it = states_.find(entity);
+ if (it != states_.end() && (it->second.gpu != useGpu || (useGpu && it->second.gpuCapacity != capacity))) {
+ // Changed how it simulates (or how big): the schedule carries over, so a burst already spent is not spent
+ // twice. The device is only known once the renderer has run, a frame after the first update, so an emitter
+ // that began on the CPU is moved to the GPU with as many particles as it had alive.
+ EmitterState old = std::move(it->second);
+ states_.erase(it);
+ auto [moved, _] = states_.emplace(entity, EmitterState(useGpu ? 0u : capacity));
+ EmitterState& next = moved->second;
+ next.emission_accumulator = old.emission_accumulator;
+ next.elapsed_time = old.elapsed_time;
+ next.burst_timer = old.burst_timer;
+ next.noise_time = old.noise_time;
+ next.playing = old.playing;
+ next.first_update = old.first_update;
+ next.gpu = useGpu;
+ next.gpuCapacity = useGpu ? capacity : 0;
+ if (useGpu) next.gpuBurst = std::min(old.pool.aliveCount(), capacity);
+ it = moved;
+ }
if (it == states_.end()) {
auto [insertIt, _] = states_.emplace(
entity,
@@ -94,9 +120,11 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
// but a script, scene file, or replicated value bypasses that — a
// negative cast to u32 (or a multi-billion count) would resize the
// pool into a bad_alloc.
- EmitterState(static_cast<u32>(std::clamp(emitter.maxParticles, 0, 1'000'000)))
+ EmitterState(useGpu ? 0u : capacity)
);
it = insertIt;
+ it->second.gpu = useGpu;
+ it->second.gpuCapacity = useGpu ? capacity : 0;
if (emitter.playOnStart) {
it->second.playing = true;
}
@@ -129,6 +157,13 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
emitting = false;
}
+ // The schedule is one thing whoever runs the particles: a GPU emitter only counts what is born.
+ auto emit = [&](u32 count, bool burst) {
+ if (!state.gpu) { emitParticles(emitter, transform, state, count); return; }
+ u32& pending = burst ? state.gpuBurst : state.gpuSmooth;
+ pending = std::min(pending + count, state.gpuCapacity);
+ };
+
if (emitting) {
state.elapsed_time += dt;
@@ -137,20 +172,26 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
u32 toEmit = static_cast<u32>(state.emission_accumulator);
if (toEmit > 0) {
state.emission_accumulator -= static_cast<f32>(toEmit);
- emitParticles(emitter, transform, state, toEmit);
+ emit(toEmit, false);
}
}
if (emitter.burstCount > 0) {
if (state.burst_timer <= 0.0f) {
- emitParticles(emitter, transform, state,
- static_cast<u32>(emitter.burstCount));
+ emit(static_cast<u32>(emitter.burstCount), true);
state.burst_timer = emitter.burstInterval;
}
state.burst_timer -= dt;
}
}
+ if (state.gpu) {
+ // The kernel does what updateParticles would; this side only keeps the clocks it needs.
+ state.noise_time += dt;
+ state.gpuDt += dt;
+ continue;
+ }
+
const EmitterFrame frame{transform.worldPosition, transform.worldRotation,
transform.worldScale};
bool isWorldSpace = emitter.simulationSpace ==
@@ -210,6 +251,11 @@ void ParticleSystem::reset(Entity entity) {
auto it = states_.find(entity);
if (it != states_.end()) {
it->second.pool.clear();
+ if (it->second.gpu) {
+ it->second.gpuSmooth = it->second.gpuBurst = it->second.gpuSpawned = 0;
+ it->second.gpuDt = 0.0f;
+ it->second.gpuReset = true;
+ }
it->second.emission_accumulator = 0.0f;
it->second.elapsed_time = 0.0f;
it->second.burst_timer = 0.0f;
@@ -249,11 +295,41 @@ void ParticleSystem::setSpeedLut(Entity entity, const f32* values, i32 count) {
u32 ParticleSystem::aliveCount(Entity entity) const {
auto it = states_.find(entity);
if (it != states_.end()) {
+ // The GPU keeps the truth; what this side can say is how many slots have ever held one, an upper bound.
+ if (it->second.gpu) return std::min(it->second.gpuSpawned, it->second.gpuCapacity);
return it->second.pool.aliveCount();
}
return 0;
}
+bool ParticleSystem::peekGpuStep(Entity entity, GpuStep& out) const {
+ auto it = states_.find(entity);
+ if (it == states_.end() || !it->second.gpu) return false;
+ const EmitterState& state = it->second;
+ out = {};
+ out.capacity = state.gpuCapacity;
+ // A frame that went long (a stall, a hidden tab) is not simulated as one huge step.
+ out.dt = std::min(state.gpuDt, 0.1f);
+ out.noiseTime = state.noise_time;
+ out.reset = state.gpuReset;
+ out.smoothCount = std::min(state.gpuSmooth, state.gpuCapacity);
+ out.spawnCount = std::min(out.smoothCount + state.gpuBurst, state.gpuCapacity);
+ out.firstIndex = state.gpuSpawned;
+ out.drawCount = std::min(state.gpuSpawned + out.spawnCount, state.gpuCapacity);
+ return true;
+}
+
+void ParticleSystem::commitGpuStep(Entity entity, const GpuStep& step) {
+ auto it = states_.find(entity);
+ if (it == states_.end() || !it->second.gpu) return;
+ EmitterState& state = it->second;
+ // A stall longer than a step is not replayed, and births past the ring's size were never going to be seen.
+ state.gpuDt = 0.0f;
+ state.gpuSmooth = state.gpuBurst = 0;
+ state.gpuSpawned += step.spawnCount;
+ if (step.reset) state.gpuReset = false;
+}
+
u32 ParticleSystem::totalAliveParticles() const {
u32 total = 0;
for (const auto& [_, state] : states_) {
diff --git a/src/esengine/particle/ParticleSystem.hpp b/src/esengine/particle/ParticleSystem.hpp
index f8aba8976..4bdcd4c1b 100644
--- a/src/esengine/particle/ParticleSystem.hpp
+++ b/src/esengine/particle/ParticleSystem.hpp
@@ -71,6 +71,18 @@ struct CollisionStats {
static_assert(sizeof(CollisionQuery) == 40 && sizeof(CollisionReply) == 32);
static_assert(sizeof(CollisionEvent) == 56 && sizeof(CollisionStats) == 40);
+/// What one frame asks of a GPU-simulated emitter: how long to advance, how many to spawn and where in the ring they go.
+struct GpuStep {
+ f32 dt = 0.0f;
+ f32 noiseTime = 0.0f;
+ u32 capacity = 0;
+ u32 firstIndex = 0; ///< Absolute index of the first particle born this step (slot = index % capacity).
+ u32 spawnCount = 0; ///< Born this step: `smoothCount` spread across dt, then the rest as one burst.
+ u32 smoothCount = 0;
+ u32 drawCount = 0; ///< Slots that may hold a live particle once this step has run.
+ bool reset = false; ///< Kill everything first (a reset() since the last step).
+};
+
struct EmitterState {
ParticlePool pool;
f32 emission_accumulator = 0.0f;
@@ -91,6 +103,15 @@ struct EmitterState {
u32 collisionCursor = 0, collisionOrdinal = 0;
+ // GPU simulation: the emitter keeps its schedule here (rate, bursts, duration) and the particles live in
+ // a GPU ring this state only counts. The pool stays empty, so a million-particle emitter costs no heap.
+ bool gpu = false;
+ u32 gpuCapacity = 0;
+ f32 gpuDt = 0.0f;
+ u32 gpuSmooth = 0, gpuBurst = 0;
+ u32 gpuSpawned = 0;
+ bool gpuReset = false;
+
explicit EmitterState(u32 capacity) : pool(capacity) {}
};
@@ -107,6 +128,21 @@ public:
void update(ecs::Registry& registry, f32 dt);
+ /// Whether emitters that ask for GPU simulation get it. Set by the renderer, which knows the device; false
+ /// means they run on the CPU, capped at kGpuFallbackCapacity.
+ void setGpuAvailable(bool available) { gpu_available_ = available; }
+ bool gpuAvailable() const { return gpu_available_; }
+ static constexpr u32 kGpuMaxCapacity = 2'000'000;
+ static constexpr u32 kGpuFallbackCapacity = 20'000;
+
+ /// What a GPU emitter has to do to catch up: the time, the births, where in the ring they go. False when the entity
+ /// is not simulated on the GPU. Nothing is consumed until commitGpuStep, so a step that was asked for and never run
+ /// (a collect whose frame did not reach the graph) is asked for again next time rather than lost.
+ bool peekGpuStep(Entity entity, GpuStep& out) const;
+ /// The kernel ran this step: the time and births it covered are spent.
+ void commitGpuStep(Entity entity, const GpuStep& step);
+ const std::vector<ForceFieldInstance>& forceFields() const { return force_fields_; }
+
// update() integrates; resolveCollisions() completes all queries in this same
// frame before rendering. No reply survives into the next update.
const std::vector<CollisionQuery>& collisionQueries() const { return collision_queries_; }
@@ -142,6 +178,11 @@ public:
* and gravity, damping and noise still accumulate into velocity as before. */
void setSpeedLut(Entity entity, const f32* values, i32 count);
+ /// The over-life curves an entity was given, for the GPU kernel to read; null where none was set.
+ const ColorLut* colorLut(Entity entity) const { auto it = colorLuts_.find(entity); return it == colorLuts_.end() ? nullptr : &it->second; }
+ const SizeLut* sizeLut(Entity entity) const { auto it = sizeLuts_.find(entity); return it == sizeLuts_.end() ? nullptr : &it->second; }
+ const SizeLut* speedLut(Entity entity) const { auto it = speedLuts_.find(entity); return it == speedLuts_.end() ? nullptr : &it->second; }
+
private:
void emitParticles(const ecs::ParticleEmitter& emitter,
const ecs::Transform& transform,
@@ -200,6 +241,7 @@ private:
std::unordered_map<Entity, SizeLut> sizeLuts_;
std::unordered_map<Entity, SizeLut> speedLuts_;
std::mt19937 rng_;
+ bool gpu_available_ = false;
u32 particle_limit_ = 0xffffffffu;
std::vector<u32> dead_particle_indices_;
// Active scene force fields, rebuilt each update() and applied to world-space
diff --git a/src/esengine/renderer/draw/BatchBuilder.cpp b/src/esengine/renderer/draw/BatchBuilder.cpp
index ee3d586ad..e811f3759 100644
--- a/src/esengine/renderer/draw/BatchBuilder.cpp
+++ b/src/esengine/renderer/draw/BatchBuilder.cpp
@@ -112,6 +112,7 @@ void pushBatchDraw(DrawList& drawList, const ClipState& clips,
cmd.vertex_count = vertexCount;
cmd.instance_count = key.instanceCount;
cmd.instance_stride = key.instanceStride;
+ cmd.instance_buffer = key.instanceBuffer;
cmd.vertex_buffer = key.vertexBuffer;
cmd.index_buffer = key.indexBuffer;
cmd.vertex_layout = key.vertexLayout;
diff --git a/src/esengine/renderer/draw/BatchBuilder.hpp b/src/esengine/renderer/draw/BatchBuilder.hpp
index c4cf9e31e..42a7b1404 100644
--- a/src/esengine/renderer/draw/BatchBuilder.hpp
+++ b/src/esengine/renderer/draw/BatchBuilder.hpp
@@ -126,6 +126,9 @@ struct BatchDrawKey {
// Bytes one instance record occupies. Needed to coalesce two such draws into
// one: the merge relocates their records so they sit next to each other.
u32 instanceStride = 0;
+ // Instance records a compute kernel already wrote to the GPU (ParticleInstance layout): drawn from there instead
+ // of from the stream, so the draw's vertexByteOffset means nothing.
+ BufferHandle instanceBuffer = BufferHandle::Invalid;
// Geometry the GPU already holds. Set together with a MeshInstance stream, whose
// offset is the draw's vertexByteOffset: the mesh supplies the vertices and the
// frame supplies only the transforms.
diff --git a/src/esengine/renderer/draw/DrawCommand.hpp b/src/esengine/renderer/draw/DrawCommand.hpp
index 1ad7b2cc7..24ec3417a 100644
--- a/src/esengine/renderer/draw/DrawCommand.hpp
+++ b/src/esengine/renderer/draw/DrawCommand.hpp
@@ -145,6 +145,9 @@ struct DrawCommand {
// Bytes one of those records occupies; 0 = the stream's own stride, which the
// merge would have to guess. Set by whoever wrote them.
u32 instance_stride = 0;
+ // The instance records already sit in a GPU buffer (a compute kernel wrote them): bound whole in place of the
+ // stream's slice. Never merged; instance_count says how many to draw.
+ BufferHandle instance_buffer = BufferHandle::Invalid;
// Geometry on the GPU rather than in this frame's pool. Set together or not
// at all; index_offset/index_count then index INTO these. Sorting, material and
diff --git a/src/esengine/renderer/draw/DrawList.cpp b/src/esengine/renderer/draw/DrawList.cpp
index ca2a56cb9..9c5c73731 100644
--- a/src/esengine/renderer/draw/DrawList.cpp
+++ b/src/esengine/renderer/draw/DrawList.cpp
@@ -485,7 +485,11 @@ void DrawList::execute(GfxDevice& device, TransientBufferPool& buffers,
} else if (cmd.instance_count > 0) {
// Instanced: static geometry (index_count indices from offset 0) drawn
// instance_count times, instance attributes rebased at vertex_byte_offset.
- buffers.bindInstanceLayout(cmd.layout_id, cmd.vertex_byte_offset);
+ if (cmd.instance_buffer != BufferHandle::Invalid) {
+ buffers.bindInstanceBuffer(cmd.layout_id, cmd.instance_buffer);
+ } else {
+ buffers.bindInstanceLayout(cmd.layout_id, cmd.vertex_byte_offset);
+ }
device.drawElementsInstanced(cmd.index_count, GfxDataType::UnsignedInt, 0, cmd.instance_count);
} else {
buffers.bindLayout(cmd.layout_id);
diff --git a/src/esengine/renderer/frame/GpuParticles.cpp b/src/esengine/renderer/frame/GpuParticles.cpp
new file mode 100644
index 000000000..ec8041198
--- /dev/null
+++ b/src/esengine/renderer/frame/GpuParticles.cpp
@@ -0,0 +1,629 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+#include "./GpuParticles.hpp"
+#include "../rhi/GfxDevice.hpp"
+#include "../../core/Log.hpp"
+#include "../../ecs/components/ParticleEmitter.hpp"
+#include "../../ecs/components/Transform.hpp"
+#include "../../particle/ParticleSystem.hpp"
+
+#include <algorithm>
+#include <cmath>
+#include <cstring>
+
+namespace esengine {
+
+namespace {
+
+// One record per live particle, exactly what the particle draw's instance attributes read (44 bytes).
+constexpr u32 kInstanceBytes = 44;
+// Position + age, velocity + lifetime, then start size, end size, rotation, angular velocity.
+constexpr u32 kStateBytes = 48;
+
+constexpr u32 kMaxFields = 8;
+constexpr u32 kLutSize = particle::kColorLutSize;
+static_assert(kLutSize == 32, "the kernel's LUT arrays are sized for 32 entries");
+
+enum Flags : u32 {
+ kReset = 1u << 0,
+ kLocal = 1u << 1,
+ kNoise = 1u << 2,
+ kSizeLut = 1u << 3,
+ kColorLut = 1u << 4,
+ kSpeedLut = 1u << 5,
+ kFloor = 1u << 6,
+};
+
+// Mirrors the kernel's `Params`: vec4s only, so the layout is the same in both languages with no padding to get wrong.
+struct ParamsBlock {
+ u32 p0[4]; // capacity, firstIndex, spawnCount, smoothCount
+ u32 p1[4]; // seed, flags, shape, octaves
+ f32 p2[4]; // dt, noiseTime, lifetimeMin, lifetimeMax
+ f32 p3[4]; // speedMin, speedMax, startSizeMin, startSizeMax
+ f32 p4[4]; // endSizeMin, endSizeMax, rotationMin, rotationMax
+ f32 p5[4]; // angularVelocityMin, angularVelocityMax, gravity.x, gravity.y
+ f32 p6[4]; // gravity.z, damping, noiseStrength, noiseFrequency
+ f32 p7[4]; // noiseScroll.x, noiseScroll.y, shapeRadius, shapeHalfAngle
+ f32 p8[4]; // shapeSize.xyz, sizeEasing
+ f32 p9[4]; // aimMin, aimMax (radians), colorEasing, floorY
+ f32 p10[4]; // bounce, friction, lifetimeLoss, spriteFPS
+ u32 p11[4]; // spriteColumns, spriteRows, spriteLoop, fieldCount
+ f32 startColor[4];
+ f32 endColor[4];
+ f32 origin[4]; // emitter position
+ f32 scale[4]; // emitter scale
+ f32 rot0[4], rot1[4], rot2[4]; // emitter rotation, one column each
+ f32 local[4]; // cos, sin of the emitter's turn about Z; scale.x, scale.y
+ f32 fields[kMaxFields * 3][4];
+ f32 colorLut[kLutSize][4];
+ f32 sizeLut[kLutSize / 4][4];
+ f32 speedLut[kLutSize / 4][4];
+};
+static_assert(sizeof(ParamsBlock) == 92 * 16, "the kernel's Params is 92 vec4s");
+constexpr u32 kJobStride = 2048; // a uniform binding starts on a multiple of 256
+static_assert(sizeof(ParamsBlock) <= kJobStride && kJobStride % 256 == 0);
+constexpr u32 kMaxJobs = 64;
+
+const char* const kKernel = R"WGSL(
+struct State { pa: vec4<f32>, vl: vec4<f32>, ms: vec4<f32> };
+struct Inst { px: f32, py: f32, pz: f32, sx: f32, sy: f32, rot: f32, color: u32, u0: f32, v0: f32, us: f32, vs: f32 };
+struct Params {
+ p0: vec4<u32>, p1: vec4<u32>,
+ p2: vec4<f32>, p3: vec4<f32>, p4: vec4<f32>, p5: vec4<f32>, p6: vec4<f32>, p7: vec4<f32>,
+ p8: vec4<f32>, p9: vec4<f32>, p10: vec4<f32>,
+ p11: vec4<u32>,
+ startColor: vec4<f32>, endColor: vec4<f32>,
+ origin: vec4<f32>, scale: vec4<f32>,
+ rot0: vec4<f32>, rot1: vec4<f32>, rot2: vec4<f32>,
+ local: vec4<f32>,
+ fields: array<vec4<f32>, 24>,
+ colorLut: array<vec4<f32>, 32>,
+ sizeLut: array<vec4<f32>, 8>,
+ speedLut: array<vec4<f32>, 8>,
+};
+@group(0) @binding(0) var<uniform> P: Params;
+@group(0) @binding(1) var<storage, read_write> states: array<State>;
+@group(0) @binding(2) var<storage, read_write> insts: array<Inst>;
+
+var<private> rng: u32;
+
+fn pcg(v: u32) -> u32 {
+ let s = v * 747796405u + 2891336453u;
+ let w = ((s >> ((s >> 28u) + 4u)) ^ s) * 277803737u;
+ return (w >> 22u) ^ w;
+}
+fn rand() -> f32 {
+ rng = pcg(rng);
+ return f32(rng) * 2.3283064365386963e-10;
+}
+fn rr(a: f32, b: f32) -> f32 {
+ if (a >= b) { return a; }
+ return a + (b - a) * rand();
+}
+
+// --- the shapes: where a particle is born and which way it leaves (ParticleShapes.hpp) ---
+fn coneDir(halfAngle: f32) -> vec3<f32> {
+ let cosT = rr(cos(halfAngle), 1.0);
+ let sinT = sqrt(max(0.0, 1.0 - cosT * cosT));
+ let phi = rr(0.0, 6.283185307179586);
+ return vec3<f32>(sinT * cos(phi), cosT, sinT * sin(phi));
+}
+fn planarAim() -> vec3<f32> {
+ let a = rr(P.p9.x, P.p9.y);
+ return vec3<f32>(cos(a), sin(a), 0.0);
+}
+
+// --- curl noise (ParticleNoise.hpp): the same field the CPU sim advects along ---
+fn hash2(x: i32, y: i32) -> f32 {
+ var h = u32(x) * 374761393u + u32(y) * 668265263u;
+ h = (h ^ (h >> 13u)) * 1274126177u;
+ h = h ^ (h >> 16u);
+ return f32(h) * (1.0 / 4294967295.0);
+}
+fn grad2(x: i32, y: i32) -> vec2<f32> {
+ let a = hash2(x, y) * 6.283185307179586;
+ return vec2<f32>(cos(a), sin(a));
+}
+fn fade(t: f32) -> f32 { return t * t * t * (t * (t * 6.0 - 15.0) + 10.0); }
+fn perlin2(p: vec2<f32>) -> f32 {
+ let pi = floor(p);
+ let pf = p - pi;
+ let x0 = i32(pi.x);
+ let y0 = i32(pi.y);
+ let n00 = dot(grad2(x0, y0), pf - vec2<f32>(0.0, 0.0));
+ let n10 = dot(grad2(x0 + 1, y0), pf - vec2<f32>(1.0, 0.0));
+ let n01 = dot(grad2(x0, y0 + 1), pf - vec2<f32>(0.0, 1.0));
+ let n11 = dot(grad2(x0 + 1, y0 + 1), pf - vec2<f32>(1.0, 1.0));
+ let ux = fade(pf.x);
+ let uy = fade(pf.y);
+ return mix(mix(n00, n10, ux), mix(n01, n11, ux), uy);
+}
+fn fbm2(p: vec2<f32>, octaves: u32) -> f32 {
+ var sum = 0.0;
+ var amp = 1.0;
+ var freq = 1.0;
+ var norm = 0.0;
+ let n = clamp(octaves, 1u, 8u);
+ for (var i = 0u; i < n; i = i + 1u) {
+ sum = sum + amp * perlin2(p * freq);
+ norm = norm + amp;
+ freq = freq * 2.0;
+ amp = amp * 0.5;
+ }
+ if (norm > 0.0) { return sum / norm; }
+ return 0.0;
+}
+fn curl(p: vec2<f32>, octaves: u32) -> vec2<f32> {
+ let e = 0.1;
+ let dpdx = fbm2(p + vec2<f32>(e, 0.0), octaves) - fbm2(p - vec2<f32>(e, 0.0), octaves);
+ let dpdy = fbm2(p + vec2<f32>(0.0, e), octaves) - fbm2(p - vec2<f32>(0.0, e), octaves);
+ return vec2<f32>(dpdy, -dpdx) * (0.25 / (2.0 * e));
+}
+
+fn ease(kind: f32, t: f32) -> f32 {
+ if (kind > 2.5) { return select(-1.0 + (4.0 - 2.0 * t) * t, 2.0 * t * t, t < 0.5); }
+ if (kind > 1.5) { return t * (2.0 - t); }
+ if (kind > 0.5) { return t * t; }
+ return t;
+}
+
+fn lutF(which: u32, t: f32) -> f32 {
+ let f = clamp(t, 0.0, 1.0) * 31.0;
+ let i = u32(f);
+ let j = min(i + 1u, 31u);
+ var a: f32;
+ var b: f32;
+ if (which == 0u) {
+ a = P.sizeLut[i >> 2u][i & 3u];
+ b = P.sizeLut[j >> 2u][j & 3u];
+ } else {
+ a = P.speedLut[i >> 2u][i & 3u];
+ b = P.speedLut[j >> 2u][j & 3u];
+ }
+ return mix(a, b, f - f32(i));
+}
+fn lutC(t: f32) -> vec4<f32> {
+ let f = clamp(t, 0.0, 1.0) * 31.0;
+ let i = u32(f);
+ let j = min(i + 1u, 31u);
+ return mix(P.colorLut[i], P.colorLut[j], f - f32(i));
+}
+
+// A scene force field folded into a world-space particle's velocity (ParticleSystem.cpp applyForceField).
+fn applyField(k: u32, pos: vec3<f32>, vel: vec3<f32>, dt: f32) -> vec3<f32> {
+ let a = P.fields[k * 3u];
+ let b = P.fields[k * 3u + 1u];
+ let c = P.fields[k * 3u + 2u];
+ let toField = a.xyz - pos;
+ let distSq = dot(toField, toField);
+ var factor = 1.0;
+ if (c.x > 0.0) {
+ if (distSq > c.x * c.x) { return vel; }
+ if (c.y > 0.5) { factor = 1.0 - sqrt(distSq) / c.x; }
+ }
+ let strength = b.w;
+ var v = vel;
+ let kind = u32(a.w + 0.5);
+ if (kind == 0u) {
+ v = v + b.xyz * (strength * factor * dt);
+ } else if (kind == 1u) {
+ let d = sqrt(distSq);
+ if (d > 1e-4) { v = v + (toField / d) * (strength * factor * dt); }
+ } else if (kind == 2u) {
+ let d = sqrt(distSq);
+ if (d > 1e-4) {
+ let radial = -toField / d;
+ var axis = vec3<f32>(0.0, 0.0, 1.0);
+ if (length(b.xyz) > 1e-6) { axis = normalize(b.xyz); }
+ let perp = cross(axis, radial);
+ let pl = length(perp);
+ if (pl > 1e-6) { v = v + (perp / pl) * (strength * factor * dt); }
+ }
+ } else {
+ v = v * (1.0 - min(strength * factor * dt, 1.0));
+ }
+ return v;
+}
+
+fn hide(i: u32) {
+ insts[i] = Inst(0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0u, 0.0, 0.0, 1.0, 1.0);
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3<u32>) {
+ let cap = P.p0.x;
+ let i = gid.x;
+ if (i >= cap) { return; }
+ let flags = P.p1.y;
+ if ((flags & 1u) != 0u) {
+ states[i] = State(vec4<f32>(0.0), vec4<f32>(0.0), vec4<f32>(0.0));
+ hide(i);
+ return;
+ }
+ let local = (flags & 2u) != 0u;
+ let R = mat3x3<f32>(P.rot0.xyz, P.rot1.xyz, P.rot2.xyz);
+ let dt = P.p2.x;
+
+ var st = states[i];
+ var stepDt = dt;
+
+ // Born this step? Slot i holds the particle whose absolute index lands on it.
+ let first = P.p0.y % cap;
+ let rel = (i + cap - first) % cap;
+ if (rel < P.p0.z) {
+ rng = pcg(P.p1.x ^ ((P.p0.y + rel) * 2654435761u));
+ let life = rr(P.p2.z, P.p2.w);
+ let startSize = rr(P.p3.z, P.p3.w);
+ let endSize = rr(P.p4.x, P.p4.y);
+ let rot = rr(P.p4.z, P.p4.w);
+ let angVel = rr(P.p5.x, P.p5.y);
+
+ var pos = vec3<f32>(0.0);
+ var dir = vec3<f32>(0.0, 1.0, 0.0);
+ let shape = P.p1.z;
+ if (shape == 1u) {
+ let angle = rr(0.0, 6.283185307179586);
+ let radius = rr(0.0, P.p7.z);
+ pos = vec3<f32>(cos(angle) * radius, sin(angle) * radius, 0.0);
+ if (radius > 0.001) { dir = pos / radius; } else { dir = planarAim(); }
+ } else if (shape == 2u) {
+ let h = P.p8.xyz * 0.5;
+ let x = rr(-h.x, h.x);
+ let y = rr(-h.y, h.y);
+ var z = 0.0;
+ if (P.p8.z > 0.0) { z = rr(-h.z, h.z); }
+ pos = vec3<f32>(x, y, z);
+ dir = planarAim();
+ } else if (shape == 3u) {
+ dir = coneDir(P.p7.w);
+ pos = coneDir(P.p7.w) * rr(0.0, P.p7.z);
+ } else if (shape == 4u || shape == 5u) {
+ var cap2 = 3.141592653589793;
+ if (shape == 5u) { cap2 = 1.5707963267948966; }
+ dir = coneDir(cap2);
+ pos = coneDir(cap2) * (P.p7.z * pow(rr(0.0, 1.0), 1.0 / 3.0));
+ } else {
+ dir = planarAim();
+ }
+ let speed = rr(P.p3.x, P.p3.y);
+ var wpos: vec3<f32>;
+ var wdir: vec3<f32>;
+ if (local) {
+ wpos = pos * P.scale.xyz;
+ wdir = dir;
+ } else {
+ wpos = P.origin.xyz + R * (pos * P.scale.xyz);
+ wdir = R * dir;
+ }
+ st = State(vec4<f32>(wpos, 0.0), vec4<f32>(wdir * speed, max(life, 1e-4)), vec4<f32>(startSize, endSize, rot, angVel));
+ // Rate-born particles are spread across the step they were born in, so a fast emitter draws a line, not a row of clumps.
+ if (rel < P.p0.w) { stepDt = dt * (1.0 - (f32(rel) + 0.5) / f32(P.p0.w)); }
+ } else if (st.pa.w >= st.vl.w) {
+ hide(i);
+ return;
+ }
+
+ let life = st.vl.w;
+ var age = st.pa.w + stepDt;
+ if (age >= life) {
+ st.pa.w = life;
+ states[i] = st;
+ hide(i);
+ return;
+ }
+ var pos = st.pa.xyz;
+ var vel = st.vl.xyz;
+ let t = age / life;
+
+ vel = vel + vec3<f32>(P.p5.z, P.p5.w, P.p6.x) * stepDt;
+ if (!local) {
+ for (var k = 0u; k < P.p11.w; k = k + 1u) { vel = applyField(k, pos, vel, stepDt); }
+ }
+ if (P.p6.y > 0.0) { vel = vel * max(0.0, 1.0 - P.p6.y * stepDt); }
+ var speedMul = 1.0;
+ if ((flags & 32u) != 0u) { speedMul = lutF(1u, t); }
+ pos = pos + vel * speedMul * stepDt;
+
+ if ((flags & 4u) != 0u) {
+ let flow = curl(pos.xy * P.p6.w + P.p7.xy, P.p1.w);
+ pos = pos + vec3<f32>(flow, 0.0) * P.p6.z * stepDt;
+ }
+
+ if ((flags & 64u) != 0u) {
+ var point = pos;
+ var velW = vel;
+ if (local) { point = P.origin.xyz + R * pos; velW = R * vel; }
+ if (point.y < P.p9.w && velW.y < 0.0) {
+ let approach = velW.y;
+ let fr = clamp(P.p10.y, 0.0, 1.0);
+ let bounce = clamp(P.p10.x, 0.0, 1.0);
+ velW = vec3<f32>(velW.x, 0.0, velW.z) * (1.0 - fr) - vec3<f32>(0.0, approach * bounce, 0.0);
+ point = vec3<f32>(point.x, P.p9.w, point.z);
+ if (local) {
+ pos = transpose(R) * (point - P.origin.xyz);
+ vel = transpose(R) * velW;
+ } else {
+ pos = point;
+ vel = velW;
+ }
+ age = age + clamp(P.p10.z, 0.0, 1.0) * life;
+ if (age >= life) {
+ st.pa.w = life;
+ states[i] = st;
+ hide(i);
+ return;
+ }
+ }
+ }
+
+ let rotation = st.ms.z + st.ms.w * stepDt;
+ st = State(vec4<f32>(pos, age), vec4<f32>(vel, life), vec4<f32>(st.ms.x, st.ms.y, rotation, st.ms.w));
+ states[i] = st;
+
+ var size = mix(st.ms.x, st.ms.y, ease(P.p8.w, t));
+ if ((flags & 8u) != 0u) { size = st.ms.x * lutF(0u, t); }
+ var color = mix(P.startColor, P.endColor, ease(P.p9.z, t));
+ if ((flags & 16u) != 0u) { color = lutC(t); }
+
+ var u0 = 0.0;
+ var v0 = 0.0;
+ var us = 1.0;
+ var vs = 1.0;
+ let cols = max(P.p11.x, 1u);
+ let rows = max(P.p11.y, 1u);
+ let total = f32(cols * rows);
+ if (total > 1.0) {
+ us = 1.0 / f32(cols);
+ vs = 1.0 / f32(rows);
+ if (P.p10.w > 0.0) {
+ let raw = age * P.p10.w;
+ var frameF = min(raw, total - 1.0);
+ if (P.p11.z != 0u) { frameF = raw - total * floor(raw / total); }
+ let fi = u32(frameF);
+ u0 = f32(fi % cols) * us;
+ v0 = f32(fi / cols) * vs;
+ }
+ }
+
+ var worldPos = pos;
+ var worldSize = vec2<f32>(size);
+ if (local) {
+ let rel3 = pos * vec3<f32>(P.local.z, P.local.w, 1.0);
+ worldPos = P.origin.xyz + vec3<f32>(rel3.x * P.local.x - rel3.y * P.local.y, rel3.x * P.local.y + rel3.y * P.local.x, rel3.z);
+ worldSize = worldSize * vec2<f32>(P.local.z, P.local.w);
+ }
+ insts[i] = Inst(worldPos.x, worldPos.y, worldPos.z, worldSize.x, worldSize.y, rotation, pack4x8unorm(color), u0, v0, us, vs);
+}
+)WGSL";
+
+void set4(f32 (&dst)[4], f32 a, f32 b, f32 c, f32 d) { dst[0] = a; dst[1] = b; dst[2] = c; dst[3] = d; }
+void set4(u32 (&dst)[4], u32 a, u32 b, u32 c, u32 d) { dst[0] = a; dst[1] = b; dst[2] = c; dst[3] = d; }
+
+// A finite, non-negative range: a bad value reaching a kernel is a hung or poisoned buffer, and nothing reads it back.
+f32 finite(f32 v, f32 fallback = 0.0f) { return std::isfinite(v) ? v : fallback; }
+
+} // namespace
+
+struct GpuParticles::Job {
+ Entity entity;
+ ParamsBlock block;
+ Slot* slot;
+ particle::ParticleSystem* system;
+ particle::GpuStep step;
+};
+
+GpuParticles::GpuParticles(GfxDevice& device) : device_(device) {}
+
+GpuParticles::~GpuParticles() {
+ release();
+}
+
+bool GpuParticles::available() const {
+ return !failed_ && device_.supportsCompute();
+}
+
+void GpuParticles::freeSlot(Slot& slot) {
+ if (slot.state != BufferHandle::Invalid) device_.deleteBuffer(slot.state);
+ if (slot.instances != BufferHandle::Invalid) device_.deleteBuffer(slot.instances);
+ slot = {};
+}
+
+void GpuParticles::release() {
+ for (auto& [id, slot] : slots_) freeSlot(slot);
+ slots_.clear();
+ jobs_.clear();
+ if (params_ != BufferHandle::Invalid) device_.deleteBuffer(params_);
+ params_ = BufferHandle::Invalid;
+ paramsCapacity_ = 0;
+ if (kernel_ != ComputeHandle::Invalid) device_.deleteCompute(kernel_);
+ kernel_ = ComputeHandle::Invalid;
+ failed_ = false;
+}
+
+void GpuParticles::beginFrame() {
+ ++frame_;
+ jobs_.clear();
+ lastDispatches_ = 0;
+ drawn_ = 0;
+ // Given back after a few seconds unseen: an emitter off screen keeps its particles for a moment, not for ever.
+ for (auto it = slots_.begin(); it != slots_.end();) {
+ if (frame_ > it->second.lastUsed + 300) {
+ freeSlot(it->second);
+ it = slots_.erase(it);
+ } else {
+ ++it;
+ }
+ }
+}
+
+bool GpuParticles::ensureKernel() {
+ if (kernel_ != ComputeHandle::Invalid) return true;
+ if (failed_ || !device_.supportsCompute()) return false;
+ std::string log;
+ kernel_ = device_.createCompute(GfxComputeSource{GfxShaderLanguage::WGSL, kKernel, "main"}, &log);
+ if (kernel_ == ComputeHandle::Invalid) {
+ ES_LOG_ERROR("GpuParticles: the kernel did not compile: {}", log);
+ failed_ = true;
+ return false;
+ }
+ return true;
+}
+
+GpuParticles::Slot* GpuParticles::ensureSlot(Entity entity, u32 capacity) {
+ Slot& slot = slots_[entity.raw];
+ slot.lastUsed = frame_;
+ if (slot.state != BufferHandle::Invalid && slot.capacity == capacity) return &slot;
+ freeSlot(slot);
+ // Zeroed by the device: age 0 of lifetime 0 is a dead particle, and a zero instance has no size to draw.
+ slot.state = device_.createBuffer({GfxBufferUsage::Storage, capacity * kStateBytes, false}, GfxContent::transient(), nullptr);
+ slot.instances = device_.createBuffer({GfxBufferUsage::Storage, capacity * kInstanceBytes, false}, GfxContent::transient(), nullptr);
+ if (slot.state == BufferHandle::Invalid || slot.instances == BufferHandle::Invalid) {
+ ES_LOG_ERROR("GpuParticles: could not allocate {} particles", capacity);
+ freeSlot(slot);
+ slots_.erase(entity.raw);
+ return nullptr;
+ }
+ slot.capacity = capacity;
+ slot.lastUsed = frame_;
+ return &slot;
+}
+
+bool GpuParticles::submit(Entity entity, const ecs::ParticleEmitter& emitter, const ecs::Transform& transform,
+ particle::ParticleSystem& system, const particle::GpuStep& step, BufferHandle& instances) {
+ if (!ensureKernel() || step.capacity == 0) return false;
+ Slot* slot = ensureSlot(entity, step.capacity);
+ if (!slot) return false;
+ instances = slot->instances;
+ drawn_ += step.drawCount;
+
+ // A second camera's collect asks for the same step until the first has run it.
+ for (const Job& queued : jobs_) {
+ if (queued.entity == entity) return true;
+ }
+ const bool local = emitter.simulationSpace == static_cast<i32>(ecs::SimulationSpace::Local);
+ // Nothing to advance and nowhere it could have moved to: the buffer already says what is true.
+ if (step.dt <= 0.0f && step.spawnCount == 0 && !step.reset && !local) return true;
+ if (jobs_.size() >= kMaxJobs) return true;
+
+ Job job{entity, {}, slot, &system, step};
+ ParamsBlock& b = job.block;
+ std::memset(&b, 0, sizeof(b));
+
+ u32 flags = 0;
+ if (step.reset) flags |= kReset;
+ if (local) flags |= kLocal;
+ const bool noiseOn = emitter.noiseStrength > 0.0f && emitter.noiseFrequency > 0.0f;
+ if (noiseOn) flags |= kNoise;
+ if (emitter.collisionEnabled) flags |= kFloor;
+
+ const auto* colorLut = system.colorLut(entity);
+ const auto* sizeLut = system.sizeLut(entity);
+ const auto* speedLut = system.speedLut(entity);
+ if (colorLut) flags |= kColorLut;
+ if (sizeLut) flags |= kSizeLut;
+ if (speedLut) flags |= kSpeedLut;
+
+ // A scene's own draw of randomness, fixed per emitter: the same emitter replays the same particles.
+ const u32 seed = entity.raw * 2246822519u + 3266489917u;
+ set4(b.p0, step.capacity, step.firstIndex, step.spawnCount, step.smoothCount);
+ set4(b.p1, seed, flags, static_cast<u32>(std::clamp(emitter.shape, 0, 5)), static_cast<u32>(std::clamp(emitter.noiseOctaves, 1, 8)));
+ set4(b.p2, step.dt, step.noiseTime, finite(emitter.lifetimeMin), finite(emitter.lifetimeMax));
+ set4(b.p3, finite(emitter.speedMin), finite(emitter.speedMax), finite(emitter.startSizeMin), finite(emitter.startSizeMax));
+ set4(b.p4, finite(emitter.endSizeMin), finite(emitter.endSizeMax), finite(emitter.rotationMin), finite(emitter.rotationMax));
+ set4(b.p5, finite(emitter.angularVelocityMin), finite(emitter.angularVelocityMax), finite(emitter.gravity.x), finite(emitter.gravity.y));
+ set4(b.p6, finite(emitter.gravity.z), finite(emitter.damping), finite(emitter.noiseStrength), finite(emitter.noiseFrequency));
+ const f32 scroll = emitter.noiseScrollSpeed * step.noiseTime * emitter.noiseFrequency;
+ set4(b.p7, finite(scroll), finite(scroll), finite(emitter.shapeRadius), finite(emitter.shapeAngle * 0.5f * math::DEG_TO_RAD));
+ set4(b.p8, finite(emitter.shapeSize.x), finite(emitter.shapeSize.y), finite(emitter.shapeSize.z), static_cast<f32>(emitter.sizeEasing));
+ set4(b.p9, finite(emitter.angleSpreadMin * math::DEG_TO_RAD), finite(emitter.angleSpreadMax * math::DEG_TO_RAD),
+ static_cast<f32>(emitter.colorEasing), finite(emitter.collisionFloor));
+ set4(b.p10, finite(emitter.collisionBounce), finite(emitter.collisionFriction), finite(emitter.collisionLifetimeLoss), finite(emitter.spriteFPS));
+ const std::vector<particle::ForceFieldInstance>& fields = system.forceFields();
+ const u32 fieldCount = local ? 0u : static_cast<u32>(std::min<std::size_t>(fields.size(), kMaxFields));
+ set4(b.p11, static_cast<u32>(std::max(emitter.spriteColumns, 1)), static_cast<u32>(std::max(emitter.spriteRows, 1)),
+ emitter.spriteLoop ? 1u : 0u, fieldCount);
+ set4(b.startColor, emitter.startColor.r, emitter.startColor.g, emitter.startColor.b, emitter.startColor.a);
+ set4(b.endColor, emitter.endColor.r, emitter.endColor.g, emitter.endColor.b, emitter.endColor.a);
+
+ const glm::vec3 position = transform.worldPosition;
+ const glm::vec3 scale = transform.worldScale;
+ set4(b.origin, position.x, position.y, position.z, 0.0f);
+ set4(b.scale, scale.x, scale.y, scale.z, 0.0f);
+ const glm::mat3 rot = glm::mat3_cast(transform.worldRotation);
+ set4(b.rot0, rot[0].x, rot[0].y, rot[0].z, 0.0f);
+ set4(b.rot1, rot[1].x, rot[1].y, rot[1].z, 0.0f);
+ set4(b.rot2, rot[2].x, rot[2].y, rot[2].z, 0.0f);
+ f32 angle = 2.0f * std::atan2(transform.worldRotation.z, transform.worldRotation.w);
+ if (std::abs(angle) <= 0.001f) angle = 0.0f;
+ set4(b.local, std::cos(angle), std::sin(angle), scale.x, scale.y);
+
+ for (u32 k = 0; k < fieldCount; ++k) {
+ const particle::ForceFieldInstance& f = fields[k];
+ set4(b.fields[k * 3], f.position.x, f.position.y, f.position.z, static_cast<f32>(f.type));
+ set4(b.fields[k * 3 + 1], f.direction.x, f.direction.y, f.direction.z, f.strength);
+ set4(b.fields[k * 3 + 2], f.radius, f.falloff ? 1.0f : 0.0f, 0.0f, 0.0f);
+ }
+ if (colorLut) {
+ for (u32 k = 0; k < kLutSize; ++k) set4(b.colorLut[k], (*colorLut)[k].r, (*colorLut)[k].g, (*colorLut)[k].b, (*colorLut)[k].a);
+ }
+ for (u32 k = 0; k < kLutSize; ++k) {
+ if (sizeLut) b.sizeLut[k >> 2][k & 3] = (*sizeLut)[k];
+ if (speedLut) b.speedLut[k >> 2][k & 3] = (*speedLut)[k];
+ }
+
+ jobs_.push_back(job);
+ return true;
+}
+
+rg::ResourceId GpuParticles::declare(rg::RenderGraph& graph) {
+ if (jobs_.empty()) return rg::kNoResource;
+ // The pass is tied to the scene by what it writes, the way the other compute passes are: a single texel nobody samples.
+ rg::TargetDesc token;
+ token.width = 1;
+ token.height = 1;
+ token.format = GfxPixelFormat::RGBA8;
+ token.storage = true;
+ token.linearFilter = false;
+ const rg::ResourceId done = graph.createTarget(token);
+ rg::PassDesc pass;
+ pass.name = "gpu_particles";
+ pass.compute = true;
+ pass.write = done;
+ pass.execute = [this](const rg::PassContext&) { run(); };
+ graph.addPass(std::move(pass));
+ return done;
+}
+
+void GpuParticles::run() {
+ if (jobs_.empty() || kernel_ == ComputeHandle::Invalid) return;
+ const u32 needed = static_cast<u32>(jobs_.size()) * kJobStride;
+ if (params_ == BufferHandle::Invalid || paramsCapacity_ < needed) {
+ if (params_ != BufferHandle::Invalid) device_.deleteBuffer(params_);
+ paramsCapacity_ = std::max(needed, kJobStride * 8u);
+ params_ = device_.createBuffer({GfxBufferUsage::Uniform, paramsCapacity_, true}, GfxContent::transient(), nullptr);
+ if (params_ == BufferHandle::Invalid) {
+ paramsCapacity_ = 0;
+ return;
+ }
+ }
+ std::vector<u8> staging(needed, 0);
+ for (std::size_t i = 0; i < jobs_.size(); ++i) {
+ std::memcpy(staging.data() + i * kJobStride, &jobs_[i].block, sizeof(ParamsBlock));
+ }
+ device_.updateBuffer(params_, 0, staging.data(), needed);
+ for (std::size_t i = 0; i < jobs_.size(); ++i) {
+ const Job& job = jobs_[i];
+ const GfxComputeBinding bindings[3] = {
+ GfxComputeBinding::uniform(0, params_, static_cast<u32>(i) * kJobStride, sizeof(ParamsBlock)),
+ GfxComputeBinding::storage(1, job.slot->state),
+ GfxComputeBinding::storage(2, job.slot->instances),
+ };
+ if (device_.dispatchCompute(kernel_, bindings, 3, (job.slot->capacity + 63) / 64)) {
+ ++lastDispatches_;
+ job.system->commitGpuStep(job.entity, job.step);
+ }
+ }
+ jobs_.clear();
+}
+
+} // namespace esengine
diff --git a/src/esengine/renderer/frame/GpuParticles.hpp b/src/esengine/renderer/frame/GpuParticles.hpp
new file mode 100644
index 000000000..177a701f0
--- /dev/null
+++ b/src/esengine/renderer/frame/GpuParticles.hpp
@@ -0,0 +1,98 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file GpuParticles.hpp
+ * @brief Particles simulated by a compute kernel, drawn from the buffer the kernel wrote (WebGPU).
+ *
+ * @details An emitter that asks for it keeps its particles in a ring of GPU slots: a state buffer the kernel advances and an
+ * instance buffer it writes in the layout the particle draw already reads. The CPU decides only how many are born
+ * and how long the step is, so what costs a CPU emitter per particle per frame costs this one a dispatch: hundreds
+ * of thousands of particles are an ordinary emitter. Nothing is read back; the draw binds the instance buffer as it
+ * lies, which is why a storage buffer here is also a vertex buffer.
+ *
+ * One compute pass per frame, declared into the render graph ahead of the scene pass it feeds. It carries every
+ * emitter the frame's collect asked to step, each with its own block of parameters.
+ *
+ * What it is not: the particles are not sorted (an additive or cut-out look is exact, a deep alpha-blended pile
+ * draws in slot order), do not spawn sub-emitters or trails, and collide only with the floor plane. Where the device
+ * cannot compute, ParticleSystem simulates the same emitter on the CPU, capped.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+
+#include "../graph/RenderGraph.hpp"
+#include "../rhi/GfxEnums.hpp"
+
+#include <unordered_map>
+#include <vector>
+
+namespace esengine {
+
+class GfxDevice;
+
+namespace ecs { struct ParticleEmitter; struct Transform; }
+namespace particle { class ParticleSystem; struct GpuStep; }
+
+class GpuParticles {
+public:
+ explicit GpuParticles(GfxDevice& device);
+ ~GpuParticles();
+
+ GpuParticles(const GpuParticles&) = delete;
+ GpuParticles& operator=(const GpuParticles&) = delete;
+
+ /// Whether the device can run the kernel at all.
+ bool available() const;
+
+ /// A new frame: the previous frame's jobs are gone, and a slot nobody asked for in a while is given back.
+ void beginFrame();
+
+ /**
+ * @brief Queues the step an emitter needs and says where its particles are. The step is committed to the emitter only
+ * once the kernel has run it; an emitter already queued this frame is not queued twice.
+ * @param drawCount How many slots may hold a live particle once the step has run.
+ * @param instances The buffer to draw them from.
+ * @return false when there is nothing to draw (no compute, no memory).
+ */
+ bool submit(Entity entity, const ecs::ParticleEmitter& emitter, const ecs::Transform& transform,
+ particle::ParticleSystem& system, const particle::GpuStep& step, BufferHandle& instances);
+
+ /// Adds the compute pass for what was submitted. The resource it writes must be named by the pass that draws the result.
+ rg::ResourceId declare(rg::RenderGraph& graph);
+
+ void release();
+
+ /// Slots live right now, for the stats.
+ u32 slotCount() const { return static_cast<u32>(slots_.size()); }
+ u32 lastDispatches() const { return lastDispatches_; }
+ /// Particle slots handed to a draw this frame, over every emitter and camera: what the GPU is asked to draw.
+ u32 drawnSlots() const { return drawn_; }
+
+private:
+ struct Slot {
+ BufferHandle state = BufferHandle::Invalid;
+ BufferHandle instances = BufferHandle::Invalid;
+ u32 capacity = 0;
+ u64 lastUsed = 0;
+ };
+ struct Job;
+
+ bool ensureKernel();
+ Slot* ensureSlot(Entity entity, u32 capacity);
+ void freeSlot(Slot& slot);
+ void run();
+
+ GfxDevice& device_;
+ ComputeHandle kernel_ = ComputeHandle::Invalid;
+ BufferHandle params_ = BufferHandle::Invalid;
+ u32 paramsCapacity_ = 0;
+ bool failed_ = false;
+ u64 frame_ = 0;
+ u32 lastDispatches_ = 0;
+ u32 drawn_ = 0;
+ std::unordered_map<u32, Slot> slots_;
+ std::vector<Job> jobs_;
+};
+
+} // namespace esengine
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 65b17eb7c..2311f7d5f 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -1,6 +1,9 @@
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#include "./RenderFrame.hpp"
+#ifdef ES_ENABLE_PARTICLES
+#include "./GpuParticles.hpp"
+#endif
#include "../rhi/Shader.hpp"
#include "../rhi/ShaderEmbeds.generated.hpp"
#include "../store/LightStore.hpp"
@@ -163,6 +166,9 @@ void RenderFrame::init(u32 width, u32 height) {
post_process_->init(width, height);
#endif
+#ifdef ES_ENABLE_PARTICLES
+ gpu_particles_ = makeUnique<GpuParticles>(device_);
+#endif
pool_.init();
shadow_pool_.init();
velocity_pool_.init();
@@ -190,6 +196,12 @@ void RenderFrame::shutdown() {
plugin->shutdown();
}
plugins_.clear();
+#ifdef ES_ENABLE_PARTICLES
+ if (gpu_particles_) {
+ gpu_particles_->release();
+ gpu_particles_.reset();
+ }
+#endif
pool_.shutdown();
shadow_pool_.shutdown();
velocity_pool_.shutdown();
@@ -299,6 +311,9 @@ void RenderFrame::releaseFrameTargets() {
void RenderFrame::beginFrame() {
++planar_frame_;
+#ifdef ES_ENABLE_PARTICLES
+ if (gpu_particles_) gpu_particles_->beginFrame();
+#endif
for (auto it = planar_captures_.begin(); it != planar_captures_.end();) {
if (frame_collected_ && it->second.lastSeen + 1 < planar_frame_) {
if (it->second.frameUbo != BufferHandle::Invalid) device_.deleteBuffer(it->second.frameUbo);
@@ -602,6 +617,8 @@ void RenderFrame::publishFrameCounters() {
ES_PROFILE_COUNTER("render.shapes", stats_.shapes);
#ifdef ES_ENABLE_PARTICLES
ES_PROFILE_COUNTER("render.particles", stats_.particles);
+ // What the compute-simulated emitters asked of the GPU: a scene whose emitters fell back to the CPU reads zero here.
+ ES_PROFILE_COUNTER("render.particles.gpuSlots", gpu_particles_ ? gpu_particles_->drawnSlots() : 0u);
#endif
}
@@ -644,6 +661,13 @@ void RenderFrame::end() {
scene.dependencies.push_back(shadow_2d_resource_);
}
if (planar_resource_ != rg::kNoResource) scene.dependencies.push_back(planar_resource_);
+#ifdef ES_ENABLE_PARTICLES
+ // The particles a kernel advances this frame are drawn by the scene, so it runs first.
+ if (gpu_particles_) {
+ const rg::ResourceId simulated = gpu_particles_->declare(graph_);
+ if (simulated != rg::kNoResource) scene.dependencies.push_back(simulated);
+ }
+#endif
// A surface that refracts has to see what stands behind it, and what stands behind it is the opaque scene: the pass is
// drawn in two, with a copy of the picture taken between. Only where the scene is a texture a pass can read (a chain is
// engaged) and a draw in the list asks for the copy.
@@ -755,6 +779,11 @@ void RenderFrame::end() {
gpu_timer_.end(device_);
FrameProfiler::get().gpuScope("graph", gpu_timer_.lastMs());
}
+#ifdef ES_ENABLE_PARTICLES
+ // After the graph, which is where the kernels run: a frame that dispatched none (its emitters fell back to the CPU, or
+ // nothing moved) says so.
+ ES_PROFILE_COUNTER("render.particles.gpuDispatches", gpu_particles_ ? gpu_particles_->lastDispatches() : 0u);
+#endif
scene_resource_ = rg::kNoResource;
shadow_resource_ = rg::kNoResource;
shadow_views_.clear();
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 6f6a499a8..8d11f9719 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -38,6 +38,8 @@
namespace esengine {
+class GpuParticles;
+
namespace ecs { struct Light; }
class ImmediateDraw;
@@ -519,6 +521,11 @@ public:
static constexpr u32 STAGE_COUNT = 4;
+#ifdef ES_ENABLE_PARTICLES
+ /** Where emitters that simulate on the GPU queue their step, and find the buffer to draw (null before init). */
+ GpuParticles* gpuParticles() { return gpu_particles_.get(); }
+#endif
+
private:
GfxDevice& device_;
RenderContext& context_;
@@ -527,6 +534,10 @@ private:
#ifdef ES_ENABLE_POSTPROCESS
Unique<PostProcessPipeline> post_process_;
+#endif
+#ifdef ES_ENABLE_PARTICLES
+ /// The compute-simulated particles' buffers live here, across frames: their state is the point of them.
+ Unique<GpuParticles> gpu_particles_;
#endif
RenderTargetManager target_manager_;
diff --git a/src/esengine/renderer/plugins/ParticlePlugin.cpp b/src/esengine/renderer/plugins/ParticlePlugin.cpp
index f65b7e9d7..a986fedff 100644
--- a/src/esengine/renderer/plugins/ParticlePlugin.cpp
+++ b/src/esengine/renderer/plugins/ParticlePlugin.cpp
@@ -4,6 +4,7 @@
#include "../draw/BatchBuilder.hpp"
#include "../frame/RenderContext.hpp"
#include "../frame/RenderFrame.hpp"
+#include "../frame/GpuParticles.hpp"
#include "../rhi/Shader.hpp"
#include "../rhi/ShaderEmbeds.generated.hpp"
#include "../rhi/Texture.hpp"
@@ -36,6 +37,10 @@ static_assert(sizeof(ParticleInstanceData) == 44, "instance stride must match th
} // namespace
void ParticlePlugin::init(RenderFrameContext& ctx) {
+ // Whether emitters that ask to simulate on the GPU can: the device says, and the CPU sim falls back where it cannot.
+ if (particle_system_ && ctx.frame && ctx.frame->gpuParticles()) {
+ particle_system_->setGpuAvailable(ctx.frame->gpuParticles()->available());
+ }
// Particle instancing shader, authored as particle.esshader (single source,
// WGSL twin included) and embedded for the web build. Attribute locations
// are explicit, so no name bindings.
@@ -84,7 +89,25 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
transform.ensureDecomposed();
const auto* state = particle_system_->getState(entity);
- if (!state || state->pool.aliveCount() == 0) continue;
+ if (!state) continue;
+
+ // A GPU emitter's particles are in a buffer a kernel writes: this frame's step is queued, and the draw is told
+ // where to read them. The CPU has nothing per particle to do.
+ BufferHandle gpuInstances = BufferHandle::Invalid;
+ u32 particleCount = 0;
+ if (state->gpu) {
+ GpuParticles* gpu = ctx.frame ? ctx.frame->gpuParticles() : nullptr;
+ // The screen's overlay is not drawn through the graph the kernel runs in.
+ if (!gpu || collect_ctx.isOverlay()) continue;
+ buffers.reserveStream(LayoutId::ParticleInstance);
+ particle::GpuStep step;
+ if (!particle_system_->peekGpuStep(entity, step)) continue;
+ if (!gpu->submit(entity, emitter, transform, *particle_system_, step, gpuInstances)) continue;
+ particleCount = step.drawCount;
+ } else {
+ particleCount = state->pool.aliveCount();
+ }
+ if (particleCount == 0) continue;
u32 textureId = ctx.white_texture_id;
if (emitter.texture.isValid()) {
@@ -115,14 +138,17 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
BlendMode blendMode = static_cast<BlendMode>(emitter.blendMode);
- u32 particleCount = state->pool.aliveCount();
- u32 instByteOffset = buffers.allocVertices(LayoutId::ParticleInstance,
+ u32 instByteOffset = 0;
+ ParticleInstanceData* inst = nullptr;
+ if (!state->gpu) {
+ instByteOffset = buffers.allocVertices(LayoutId::ParticleInstance,
particleCount * sizeof(ParticleInstanceData));
- auto* inst = reinterpret_cast<ParticleInstanceData*>(
- buffers.vertexData(LayoutId::ParticleInstance) + instByteOffset);
+ inst = reinterpret_cast<ParticleInstanceData*>(
+ buffers.vertexData(LayoutId::ParticleInstance) + instByteOffset);
+ }
u32 i = 0;
- state->pool.forEachAlive([&](const particle::Particle& p) {
+ if (!state->gpu) state->pool.forEachAlive([&](const particle::Particle& p) {
glm::vec3 worldPos;
glm::vec2 size;
if (isLocalSpace) {
@@ -192,6 +218,7 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
.materialId = materialId,
.layoutId = LayoutId::ParticleInstance,
.instanceCount = particleCount,
+ .instanceBuffer = gpuInstances,
};
// The stream's static unit-quad indices (offset 0) drawn once per particle,
// with the instance slice based at instByteOffset.
@@ -201,7 +228,7 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
// Each live particle drags a tapering ribbon along its recorded path. Built on
// the CPU and streamed through the Batch face (triangle strip), exactly like the
// standalone TrailRenderer — no new GPU path. Off unless the emitter opts in.
- if (emitter.trailEnabled && emitter.trailWidth > 0.0f &&
+ if (!state->gpu && emitter.trailEnabled && emitter.trailWidth > 0.0f &&
state->trail_count.size() == state->pool.particles().size()) {
BatchDrawKey trailKey{
.stage = ctx.current_stage,
diff --git a/src/esengine/renderer/rhi/TransientBufferPool.cpp b/src/esengine/renderer/rhi/TransientBufferPool.cpp
index 5d04796cf..f91facf82 100644
--- a/src/esengine/renderer/rhi/TransientBufferPool.cpp
+++ b/src/esengine/renderer/rhi/TransientBufferPool.cpp
@@ -222,6 +222,13 @@ void TransientBufferPool::bindInstanceLayout(LayoutId layout, u32 instanceByteOf
device_.setIndexBuffer(s.ebo);
}
+void TransientBufferPool::bindInstanceBuffer(LayoutId layout, BufferHandle instances) {
+ const Stream& s = stream(layout);
+ device_.setVertexBuffer(0, s.quad_vbo, 0);
+ device_.setVertexBuffer(1, instances, 0);
+ device_.setIndexBuffer(s.ebo);
+}
+
VertexLayoutHandle TransientBufferPool::layoutHandle(LayoutId layout) const {
return stream(layout).layout;
}
diff --git a/src/esengine/renderer/rhi/TransientBufferPool.hpp b/src/esengine/renderer/rhi/TransientBufferPool.hpp
index 4896afa95..eb974c94d 100644
--- a/src/esengine/renderer/rhi/TransientBufferPool.hpp
+++ b/src/esengine/renderer/rhi/TransientBufferPool.hpp
@@ -58,6 +58,11 @@ public:
* slot here before drawElementsInstanced. The static quad slot is untouched.
*/
void bindInstanceLayout(LayoutId layout, u32 instanceByteOffset);
+ /** The same layout with the per-instance slot taken from @p instances whole — records a compute kernel wrote. */
+ void bindInstanceBuffer(LayoutId layout, BufferHandle instances);
+ /** Creates a stream's static buffers (a particle's quad and indices) without writing to it: a draw whose records
+ * live elsewhere still needs them, and nothing else would ask. */
+ void reserveStream(LayoutId layout) { ensureStorage(layout); }
/** The device vertex layout a pipeline drawing this stream must reference. */
VertexLayoutHandle layoutHandle(LayoutId layout) const;
diff --git a/src/esengine/renderer/webgpu/WebGPUMappings.hpp b/src/esengine/renderer/webgpu/WebGPUMappings.hpp
index 04226d716..c193c5a07 100644
--- a/src/esengine/renderer/webgpu/WebGPUMappings.hpp
+++ b/src/esengine/renderer/webgpu/WebGPUMappings.hpp
@@ -227,8 +227,9 @@ inline WGPUBufferUsage toWGPUBufferUsage(GfxBufferUsage usage) {
case GfxBufferUsage::Vertex: return WGPUBufferUsage_Vertex | WGPUBufferUsage_CopyDst;
case GfxBufferUsage::Index: return WGPUBufferUsage_Index | WGPUBufferUsage_CopyDst;
case GfxBufferUsage::Uniform: return WGPUBufferUsage_Uniform | WGPUBufferUsage_CopyDst;
- // Copy both ways: a compute buffer is filled from the CPU and read back to it.
- case GfxBufferUsage::Storage: return WGPUBufferUsage_Storage | WGPUBufferUsage_CopyDst | WGPUBufferUsage_CopySrc;
+ // Copy both ways: a compute buffer is filled from the CPU and read back to it. Vertex too: what a
+ // kernel wrote can be drawn as it lies (GPU particles), in a later pass.
+ case GfxBufferUsage::Storage: return WGPUBufferUsage_Storage | WGPUBufferUsage_Vertex | WGPUBufferUsage_CopyDst | WGPUBufferUsage_CopySrc;
default: return WGPUBufferUsage_CopyDst;
}
}
diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.h
index 72cc462dc..95c887e63 100644
--- a/tests/aot/generated/conformance/handshake.h
+++ b/tests/aot/generated/conformance/handshake.h
@@ -1,5 +1,5 @@
/* GENERATED by sdk/tests/aot-conformance.test.ts — do not edit. */
/* The contract half of the handshake. The width half is the harness. */
-#define ES_CONF_EXPECTED_CONTRACT_HASH 0x83e8a5bdeea599a8ULL
+#define ES_CONF_EXPECTED_CONTRACT_HASH 0x8ecf13a182e11801ULL
/* And which BUILD the artifact beside this one is. */
#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULL
diff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.c
index b4b0e10a6..d927080a3 100644
--- a/tests/aot/generated/conformance/systems_decl.c
+++ b/tests/aot/generated/conformance/systems_decl.c
@@ -10,7 +10,7 @@
answer, it is a read of a different field. The address width belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0x83e8a5bdeea599a8ULL
+#define ES_ABI_ENGINE_DIGEST 0x8ecf13a182e11801ULL
ES_EXPORT const uint64_t es_abi_hash =
ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));
diff --git a/tests/aot/generated/move_system_decl.c b/tests/aot/generated/move_system_decl.c
index 905090f2d..2a2fffae5 100644
--- a/tests/aot/generated/move_system_decl.c
+++ b/tests/aot/generated/move_system_decl.c
@@ -10,7 +10,7 @@
answer, it is a read of a different field. The address width belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0x83e8a5bdeea599a8ULL
+#define ES_ABI_ENGINE_DIGEST 0x8ecf13a182e11801ULL
ES_EXPORT const uint64_t es_abi_hash =
ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));
diff --git a/tests/aot/generated/move_system_hash.h b/tests/aot/generated/move_system_hash.h
index 782506327..e90f6c68c 100644
--- a/tests/aot/generated/move_system_hash.h
+++ b/tests/aot/generated/move_system_hash.h
@@ -1,6 +1,6 @@
/* GENERATED by @estella/compiler — do not edit. */
/* The contract half of the handshake. The width half is the harness. */
-#define ES_EXPECTED_CONTRACT_HASH 0x83e8a5bdeea599a8ULL
+#define ES_EXPECTED_CONTRACT_HASH 0x8ecf13a182e11801ULL
/* And which BUILD the artifact beside this one is, which the sidecar
written with it has to carry too. */
#define ES_EXPECTED_MODULE_CONTRACT 0x10bf77bb714ea1e3ULL
diff --git a/tests/particle/test_particle.cpp b/tests/particle/test_particle.cpp
index 4194ae32c..3784ac49a 100644
--- a/tests/particle/test_particle.cpp
+++ b/tests/particle/test_particle.cpp
@@ -6,6 +6,7 @@
#include <esengine/particle/ParticleEasing.hpp>
#include <esengine/particle/ParticleSystem.hpp>
#include <cmath>
+#include <functional>
using namespace esengine;
using namespace esengine::particle;
@@ -781,6 +782,145 @@ TEST_CASE("system_burst_emission") {
CHECK_EQ(system.aliveCount(e), 100u);
}
+// ============================================================================
+// GPU simulation: the schedule the kernel is handed (the kernel itself runs in the pixel gates)
+// ============================================================================
+
+namespace {
+Entity makeGpuEmitter(ecs::Registry& registry, const std::function<void(ecs::ParticleEmitter&)>& tune) {
+ Entity e = registry.create();
+ registry.emplace<ecs::Transform>(e);
+ auto& emitter = registry.emplace<ecs::ParticleEmitter>(e);
+ emitter.rate = 0.0f;
+ emitter.lifetimeMin = emitter.lifetimeMax = 10.0f;
+ emitter.maxParticles = 1000;
+ emitter.gpuSimulation = true;
+ tune(emitter);
+ return e;
+}
+} // namespace
+
+TEST_CASE("gpu_emitter_without_a_compute_device_runs_on_the_cpu_capped") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ Entity e = makeGpuEmitter(registry, [](ecs::ParticleEmitter& m) { m.burstCount = 50000; m.maxParticles = 200000; });
+ system.update(registry, 0.01f);
+ GpuStep step;
+ CHECK_FALSE(system.peekGpuStep(e, step));
+ // The capacity is what keeps a million-particle setup from taking the CPU down: it fills, and stops.
+ CHECK_EQ(system.aliveCount(e), ParticleSystem::kGpuFallbackCapacity);
+}
+
+TEST_CASE("gpu_emitter_hands_over_a_step_and_keeps_no_pool") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ system.setGpuAvailable(true);
+ Entity e = makeGpuEmitter(registry, [](ecs::ParticleEmitter& m) { m.burstCount = 500; m.maxParticles = 1'000'000; });
+ system.update(registry, 0.01f);
+ CHECK_EQ(system.getState(e)->pool.capacity(), 0u);
+
+ GpuStep step;
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK_EQ(step.capacity, 1'000'000u);
+ CHECK_EQ(step.spawnCount, 500u);
+ CHECK_EQ(step.smoothCount, 0u);
+ CHECK_EQ(step.firstIndex, 0u);
+ CHECK_EQ(step.drawCount, 500u);
+
+ // Nothing is spent until the kernel has run it: a step asked for twice is the same step.
+ GpuStep again;
+ REQUIRE(system.peekGpuStep(e, again));
+ CHECK_EQ(again.spawnCount, 500u);
+ CHECK_EQ(again.firstIndex, 0u);
+
+ system.commitGpuStep(e, step);
+ GpuStep next;
+ REQUIRE(system.peekGpuStep(e, next));
+ CHECK_EQ(next.spawnCount, 0u);
+ CHECK_EQ(next.firstIndex, 500u);
+ CHECK_EQ(next.drawCount, 500u);
+ CHECK_EQ(system.aliveCount(e), 500u);
+}
+
+TEST_CASE("gpu_emitter_rate_births_are_the_smooth_ones") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ system.setGpuAvailable(true);
+ Entity e = makeGpuEmitter(registry, [](ecs::ParticleEmitter& m) { m.rate = 1000.0f; m.burstCount = 7; m.burstInterval = 100.0f; });
+ system.update(registry, 0.1f);
+ GpuStep step;
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK_EQ(step.smoothCount, 100u);
+ CHECK_EQ(step.spawnCount, 107u);
+ CHECK(step.dt == doctest::Approx(0.1f));
+}
+
+TEST_CASE("gpu_emitter_ring_never_asks_for_more_than_it_holds") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ system.setGpuAvailable(true);
+ Entity e = makeGpuEmitter(registry, [](ecs::ParticleEmitter& m) { m.burstCount = 250; m.maxParticles = 100; });
+ system.update(registry, 0.01f);
+ GpuStep step;
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK_EQ(step.spawnCount, 100u);
+ CHECK_EQ(step.drawCount, 100u);
+}
+
+TEST_CASE("gpu_emitter_a_long_frame_is_not_one_huge_step") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ system.setGpuAvailable(true);
+ Entity e = makeGpuEmitter(registry, [](ecs::ParticleEmitter&) {});
+ system.update(registry, 1.0f);
+ GpuStep step;
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK(step.dt == doctest::Approx(0.1f));
+ system.commitGpuStep(e, step);
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK(step.dt == 0.0f);
+}
+
+TEST_CASE("gpu_emitter_reset_clears_the_ring_until_the_kernel_has_done_it") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ system.setGpuAvailable(true);
+ Entity e = makeGpuEmitter(registry, [](ecs::ParticleEmitter& m) { m.burstCount = 40; });
+ system.update(registry, 0.01f);
+ GpuStep step;
+ REQUIRE(system.peekGpuStep(e, step));
+ system.commitGpuStep(e, step);
+ CHECK_EQ(system.aliveCount(e), 40u);
+
+ system.reset(e);
+ CHECK_EQ(system.aliveCount(e), 0u);
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK(step.reset);
+ CHECK_EQ(step.drawCount, 0u);
+ system.commitGpuStep(e, step);
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK_FALSE(step.reset);
+}
+
+TEST_CASE("gpu_emitter_that_began_on_the_cpu_moves_over_without_firing_its_burst_twice") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ Entity e = makeGpuEmitter(registry, [](ecs::ParticleEmitter& m) { m.burstCount = 50; m.burstInterval = 100.0f; });
+ // The device is only known once the renderer has run, a frame after the first update.
+ system.update(registry, 0.01f);
+ CHECK_EQ(system.aliveCount(e), 50u);
+
+ system.setGpuAvailable(true);
+ system.update(registry, 0.01f);
+ GpuStep step;
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK_EQ(step.spawnCount, 50u);
+ system.commitGpuStep(e, step);
+ system.update(registry, 0.01f);
+ REQUIRE(system.peekGpuStep(e, step));
+ CHECK_EQ(step.spawnCount, 0u);
+}
+
// ============================================================================
// Shape Tests
// ============================================================================
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 7fd99ae82..e4e4eefea 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -2523,6 +2523,8 @@ export const NOTED = {
{"internal":"the editor checks for the Skin and Hair entry above"},
"feat(import): separate metalness, roughness and occlusion maps are packed the way glTF packs them":
{"note":"Importing an FBX with separate metalness, roughness and occlusion images now packs them into the one map the Model shader samples, instead of dropping them."},
+ "feat(particles): emitters can simulate on the GPU":
+ {"note":"Particle emitters can now simulate on the GPU: turn on gpuSimulation and a compute kernel advances every particle, so an emitter of a hundred thousand or a million particles costs a dispatch instead of a loop."},
"chore(tools): the gates run in parallel with --jobs, and the reds a full run gathered are cleared":
{"internal":"tooling for the static gates, and fixes to checks that had drifted from the code they guard"},
"fix(render): a wire narrower than a pixel is no longer painted over by the sky in dashes":
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index ff161d9c2..a6297ff9b 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -506,6 +506,13 @@ export const SCENES = [
{ id: "particles-trail", tier: "pr", webgpu: true, rendersOnly: "seeded and reproducible, but a ribbon of moving comets has no flat region a probe survives", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-trail.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-trail.textures.json", ESTELLA_VERIFY_STEPS: "60", ESTELLA_VERIFY_SEED: "1234" } },
{ id: "particles-collision", tier: "pr", webgpu: true, rendersOnly: "sparks bouncing off a floor plane are in motion at every step a probe could read", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-collision.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-collision.textures.json", ESTELLA_VERIFY_STEPS: "70", ESTELLA_VERIFY_SEED: "1234" } },
{ id: "particles-forcefield", tier: "pr", webgpu: true, rendersOnly: "a vortex keeps every particle moving, so no cell settles", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-forcefield.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-forcefield.textures.json", ESTELLA_VERIFY_STEPS: "80", ESTELLA_VERIFY_SEED: "1234" } },
+ // Simulated by a compute kernel where the device has one, by the CPU (capped) where it does not: the same scene on both,
+ // so the two paths are held to one picture. A box of green squares thick enough to be solid inside its edge, black outside.
+ { id: "particles-gpu", tier: "pr", webgpu: { ESTELLA_VERIFY_COUNTERS: "{\"render.particles.gpuSlots\":4000}" }, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-gpu.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-gpu.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_SEED: "1234", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.3,\"y\":0.3,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.7,\"y\":0.7,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.5,\"y\":0.06,\"rgb\":[0,0,0],\"tol\":25},{\"x\":0.94,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":25}]" } },
+ // The over-life curves the kernel samples: the same two scenes as the CPU gates, simulated on the GPU.
+ { id: "particles-gpu-gradient", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-gpu-gradient.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-gpu-gradient.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":90}]" } },
+ { id: "particles-gpu-sizecurve", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-gpu-sizecurve.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-gpu-sizecurve.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":110},{\"x\":0.28,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":50}]" } },
+ { id: "particles-gpu-fountain", tier: "pr", webgpu: true, rendersOnly: "a hundred thousand sparks falling, drifting on noise and bouncing off a floor are in motion at every step a probe could read", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-gpu-fountain.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-gpu-fountain.textures.json", ESTELLA_VERIFY_STEPS: "90", ESTELLA_VERIFY_SEED: "1234" } },
{ id: "particles-gradient", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-gradient.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-gradient.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":90}]" } },
{ id: "particles-sizecurve", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-sizecurve.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-sizecurve.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":110},{\"x\":0.28,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":50}]" } },
// The bright centre the chain leaves, and a corner it does not reach. Three