Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(particle): add floor collision (Collision phase 1)

yhh5fb8f0c4f4c6
diff --git a/desktop/public/scenes/particle-collision.esscene b/desktop/public/scenes/particle-collision.esscene
new file mode 100644
index 000000000..5016683a0
--- /dev/null
+++ b/desktop/public/scenes/particle-collision.esscene
@@ -0,0 +1,54 @@
+{
+ "version": "1.0",
+ "name": "ParticleCollision",
+ "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": 300, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "BouncingSparks",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 120, "z": 0 } } },
+ { "type": "ParticleEmitter", "data": {
+ "rate": 80,
+ "maxParticles": 400,
+ "lifetimeMin": 1.8,
+ "lifetimeMax": 2.6,
+ "shape": 3,
+ "shapeRadius": 10,
+ "shapeAngle": 60,
+ "speedMin": 220,
+ "speedMax": 420,
+ "startSizeMin": 6,
+ "startSizeMax": 10,
+ "endSizeMin": 3,
+ "endSizeMax": 5,
+ "startColor": { "r": 1, "g": 0.9, "b": 0.4, "a": 1 },
+ "endColor": { "r": 1, "g": 0.4, "b": 0.1, "a": 0.5 },
+ "gravity": { "x": 0, "y": -520 },
+ "simulationSpace": 0,
+ "looping": true,
+ "playOnStart": true,
+ "collisionEnabled": true,
+ "collisionFloor": -200,
+ "collisionBounce": 0.55,
+ "collisionFriction": 0.2,
+ "collisionLifetimeLoss": 0.08,
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0"
+ }}
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/particle-collision.textures.json b/desktop/public/scenes/particle-collision.textures.json
new file mode 100644
index 000000000..0acb647eb
--- /dev/null
+++ b/desktop/public/scenes/particle-collision.textures.json
@@ -0,0 +1,3 @@
+{
+ "24cb4e0f-7c75-4df4-9a4d-58480ee405c0": "/scenes/particle-demo/textures/particle.png"
+}
diff --git a/docs/astro/src/content/docs/guides/particle.mdx b/docs/astro/src/content/docs/guides/particle.mdx
index 8252ce9f8..ca2630b66 100644
--- a/docs/astro/src/content/docs/guides/particle.mdx
+++ b/docs/astro/src/content/docs/guides/particle.mdx
@@ -416,6 +416,36 @@ Two caveats: fields act on **world-space** particles only (a `Local` emitter's p
move with their emitter and ignore fields), and `strength: 0` or `enabled: false` skips
a field entirely.
+## Floor collision
+
+Turn on `collisionEnabled` and particles bounce off a horizontal **floor plane** at
+world height `collisionFloor` — rain splashing on the ground, sparks skittering across
+a surface, snow settling. It's self-contained CPU collision with no physics dependency.
+
+```typescript
+.insert(ParticleEmitter, {
+ rate: 60, speedMin: 200, speedMax: 400, shape: EmitterShape.Cone, shapeAngle: 50,
+ gravity: { x: 0, y: -500 },
+ collisionEnabled: true,
+ collisionFloor: -200, // world Y the particles land on
+ collisionBounce: 0.5, // 0 = stop dead, 1 = fully elastic
+ collisionFriction: 0.2, // horizontal speed shed per bounce
+ collisionLifetimeLoss: 0.1, // fraction of life burned per bounce (fade as they settle)
+});
+```
+
+When a world-space particle falls below `collisionFloor`, it's snapped back to the
+plane and its vertical velocity is reflected and scaled by `collisionBounce`;
+`collisionFriction` bleeds off horizontal speed and `collisionLifetimeLoss` ages it so
+splashes fade out instead of skittering forever.
+
+<Aside type="note">
+ This is a single horizontal floor — the common case (a ground line). Collision
+ against arbitrary geometry and tilemaps goes through the physics world and is a
+ separate, opt-in path. Like force fields, floor collision applies to **world-space**
+ particles only.
+</Aside>
+
## Simulation space
| Value | Particles follow the emitter? | Use for |
diff --git a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
index d3a47ad81..af8e59d43 100644
--- a/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
+++ b/docs/astro/src/content/docs/zh-cn/guides/particle.mdx
@@ -383,6 +383,32 @@ cmds.spawn()
两个注意:力场只作用于**世界空间**粒子(`Local` 发射器的粒子随发射器移动、忽略力场);
`strength: 0` 或 `enabled: false` 直接跳过该力场。
+## 地面碰撞
+
+打开 `collisionEnabled`,粒子就会在世界高度 `collisionFloor` 处的水平**地面平面**上弹跳
+—— 雨点砸地、火花在表面上溅跳、雪花落定。纯 CPU 碰撞,不依赖物理。
+
+```typescript
+.insert(ParticleEmitter, {
+ rate: 60, speedMin: 200, speedMax: 400, shape: EmitterShape.Cone, shapeAngle: 50,
+ gravity: { x: 0, y: -500 },
+ collisionEnabled: true,
+ collisionFloor: -200, // 粒子落到的世界 Y
+ collisionBounce: 0.5, // 0 = 立即停住,1 = 完全弹性
+ collisionFriction: 0.2, // 每次弹跳损失的水平速度
+ collisionLifetimeLoss: 0.1, // 每次弹跳烧掉的生命比例(落定时渐隐)
+});
+```
+
+当世界空间粒子落到 `collisionFloor` 以下,它被拉回平面、竖直速度按 `collisionBounce`
+反射缩放;`collisionFriction` 削掉水平速度,`collisionLifetimeLoss` 加速其衰老,让溅
+射渐隐而不是永远蹦跳。
+
+<Aside type="note">
+ 这是单一水平地面 —— 最常见的情形(一条地平线)。对任意几何体和瓦片地图的碰撞走物理
+ 世界,是另一条可选路径。和力场一样,地面碰撞只作用于**世界空间**粒子。
+</Aside>
+
## 模拟空间
| 取值 | 粒子跟随发射器吗? | 用于 |
diff --git a/examples/particle-demo/README.md b/examples/particle-demo/README.md
index 24c61bf87..8c2af29bd 100644
--- a/examples/particle-demo/README.md
+++ b/examples/particle-demo/README.md
@@ -1,6 +1,6 @@
# Particle Effects
-A gallery of the engine's `ParticleEmitter`. Page through ten composed effects
+A gallery of the engine's `ParticleEmitter`. Page through eleven composed effects
with on-screen buttons, and click empty space to throw fireworks.
## Controls
@@ -19,9 +19,10 @@ with on-screen buttons, and click empty space to throw fireworks.
`Bursting Rockets` (**sub-emitter** — rockets that explode into a shell burst on
death) · `Turbulent Smoke` (curl-**noise** flow — smoke that rolls, embers that
weave) · `Comet Trails` (per-particle **trail** — sparks that drag fading ribbons) ·
-`Vortex Galaxy` (**force fields** — a vortex + point pull swirl sparks into a spiral).
+`Vortex Galaxy` (**force fields** — a vortex + point pull swirl sparks into a spiral) ·
+`Bouncing Sparks` (floor **collision** — a fountain that bounces and settles on a floor).
Each mixes shape, velocity, colour/size-over-life, gravity, spin, blend mode, and now
-noise, sub-emitters, trails and force fields — see `src/config.ts`.
+noise, sub-emitters, trails, force fields and collision — see `src/config.ts`.
## How it works
@@ -56,7 +57,7 @@ assets/
textures/particle.png # soft radial particle sprite
src/
main.ts # registers the systems
- config.ts # the ten showcases, the firework, spawnShowcase()
+ config.ts # the eleven showcases, the firework, spawnShowcase()
components.ts # tags (buttons, TexHolder, ShowcaseEmitter) + Burst
state.ts # the current showcase index
systems/
diff --git a/examples/particle-demo/src/config.ts b/examples/particle-demo/src/config.ts
index 471a54716..f97769b6d 100644
--- a/examples/particle-demo/src/config.ts
+++ b/examples/particle-demo/src/config.ts
@@ -206,6 +206,21 @@ export const SHOWCASES: Showcase[] = [
startColor: { r: 0.7, g: 0.85, b: 1, a: 1 }, endColor: { r: 0.8, g: 0.4, b: 1, a: 0 } } },
],
},
+ {
+ // Shows off Floor collision: a fountain of sparks arcs up, falls, and bounces
+ // and skitters along a floor plane, fading as they settle.
+ name: 'Bouncing Sparks',
+ emitters: [
+ { x: 0, y: 120, data: {
+ rate: 55, maxParticles: 260, lifetimeMin: 1.8, lifetimeMax: 2.6,
+ shape: EmitterShape.Cone, shapeRadius: 10, shapeAngle: 60, speedMin: 220, speedMax: 420,
+ startSizeMin: 6, startSizeMax: 10, endSizeMin: 3, endSizeMax: 5,
+ startColor: { r: 1, g: 0.9, b: 0.4, a: 1 }, endColor: { r: 1, g: 0.4, b: 0.1, a: 0.5 },
+ gravity: { x: 0, y: -520 },
+ collisionEnabled: true, collisionFloor: -200, collisionBounce: 0.55,
+ collisionFriction: 0.2, collisionLifetimeLoss: 0.1 } },
+ ],
+ },
];
export const SHOWCASE_COUNT = SHOWCASES.length;
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 8213f2895..804340a0d 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 1265 stable · 17 beta · 0 deprecated
## ABI_LAYOUT_HASH — const
```
-"1ea8bcc5e5a72cc7"
+"56d27a450a1ab9c6"
```
## ANCHOR_AXES — const
@@ -4051,6 +4051,11 @@ angularVelocityMin: number
blendMode: number
burstCount: number
burstInterval: number
+collisionBounce: number
+collisionEnabled: boolean
+collisionFloor: number
+collisionFriction: number
+collisionLifetimeLoss: number
colorEasing: number
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 173d327c2..d99fc0065 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4046,6 +4046,11 @@ angularVelocityMin: number
blendMode: number
burstCount: number
burstInterval: number
+collisionBounce: number
+collisionEnabled: boolean
+collisionFloor: number
+collisionFriction: number
+collisionLifetimeLoss: number
colorEasing: number
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 0eff9c016..6d3e1af17 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -4053,6 +4053,11 @@ angularVelocityMin: number
blendMode: number
burstCount: number
burstInterval: number
+collisionBounce: number
+collisionEnabled: boolean
+collisionFloor: number
+collisionFriction: number
+collisionLifetimeLoss: number
colorEasing: number
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
diff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.ts
index 2c110744d..cf7ddd070 100644
--- a/sdk/src/component.generated.ts
+++ b/sdk/src/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from './wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '1ea8bcc5e5a72cc7';
+export const ABI_LAYOUT_HASH = '56d27a450a1ab9c6';
export interface AssetFieldMeta {
field: string;
@@ -345,6 +345,11 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
trailWidth: 8,
trailPoints: 6,
trailMinDistance: 6,
+ collisionEnabled: false,
+ collisionFloor: 0,
+ collisionBounce: 0.5,
+ collisionFriction: 0.1,
+ collisionLifetimeLoss: 0,
},
assetFields: [{ field: 'texture', type: 'texture' as AssetFieldType }, { field: 'material', type: 'material' as AssetFieldType }],
entityFields: ['subEmitter'],
@@ -403,6 +408,11 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
trailWidth: { min: 0, category: "Trail" },
trailPoints: { min: 2, max: 12, step: 1, category: "Trail" },
trailMinDistance: { min: 0, category: "Trail" },
+ collisionEnabled: { category: "Collision" },
+ collisionFloor: { category: "Collision" },
+ collisionBounce: { min: 0, max: 1, category: "Collision" },
+ collisionFriction: { min: 0, max: 1, category: "Collision" },
+ collisionLifetimeLoss: { min: 0, max: 1, category: "Collision" },
},
},
ParticleForceField: {
@@ -919,6 +929,11 @@ export interface ParticleEmitterData {
trailWidth: number;
trailPoints: number;
trailMinDistance: number;
+ collisionEnabled: boolean;
+ collisionFloor: number;
+ collisionBounce: number;
+ collisionFriction: number;
+ collisionLifetimeLoss: number;
}
export interface ParticleForceFieldData {
diff --git a/sdk/src/ecs/ptrAccessors.generated.ts b/sdk/src/ecs/ptrAccessors.generated.ts
index de1c0e21e..5657ff4a6 100644
--- a/sdk/src/ecs/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/ptrAccessors.generated.ts
@@ -575,6 +575,11 @@ export interface ParticleEmitterPtrData {
trailWidth: number;
trailPoints: number;
trailMinDistance: number;
+ collisionEnabled: boolean;
+ collisionFloor: number;
+ collisionBounce: number;
+ collisionFriction: number;
+ collisionLifetimeLoss: number;
}
export function fillParticleEmitter(
@@ -634,6 +639,11 @@ export function fillParticleEmitter(
out.trailWidth = f32[(ptr + 228) >> 2];
out.trailPoints = u32[(ptr + 232) >> 2] | 0;
out.trailMinDistance = f32[(ptr + 236) >> 2];
+ out.collisionEnabled = u8[ptr + 240] !== 0;
+ out.collisionFloor = f32[(ptr + 244) >> 2];
+ out.collisionBounce = f32[(ptr + 248) >> 2];
+ out.collisionFriction = f32[(ptr + 252) >> 2];
+ out.collisionLifetimeLoss = f32[(ptr + 256) >> 2];
}
export function writeParticleEmitter(
@@ -693,6 +703,11 @@ export function writeParticleEmitter(
f32[(ptr + 228) >> 2] = data.trailWidth;
u32[(ptr + 232) >> 2] = data.trailPoints | 0;
f32[(ptr + 236) >> 2] = data.trailMinDistance;
+ u8[ptr + 240] = data.collisionEnabled ? 1 : 0;
+ f32[(ptr + 244) >> 2] = data.collisionFloor;
+ f32[(ptr + 248) >> 2] = data.collisionBounce;
+ f32[(ptr + 252) >> 2] = data.collisionFriction;
+ f32[(ptr + 256) >> 2] = data.collisionLifetimeLoss;
}
export function createParticleEmitterData(): ParticleEmitterPtrData {
@@ -750,6 +765,11 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {
trailWidth: 0,
trailPoints: 0,
trailMinDistance: 0,
+ collisionEnabled: false,
+ collisionFloor: 0,
+ collisionBounce: 0,
+ collisionFriction: 0,
+ collisionLifetimeLoss: 0,
};
}
diff --git a/sdk/src/ptrLayouts.generated.ts b/sdk/src/ptrLayouts.generated.ts
index d7738fb3e..069db5879 100644
--- a/sdk/src/ptrLayouts.generated.ts
+++ b/sdk/src/ptrLayouts.generated.ts
@@ -202,6 +202,11 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'trailWidth', type: 'f32', offset: 228 },
{ name: 'trailPoints', type: 'i32', offset: 232 },
{ name: 'trailMinDistance', type: 'f32', offset: 236 },
+ { name: 'collisionEnabled', type: 'bool', offset: 240 },
+ { name: 'collisionFloor', type: 'f32', offset: 244 },
+ { name: 'collisionBounce', type: 'f32', offset: 248 },
+ { name: 'collisionFriction', type: 'f32', offset: 252 },
+ { name: 'collisionLifetimeLoss', type: 'f32', offset: 256 },
],
},
ParticleForceField: {
diff --git a/sdk/src/wasm.generated.ts b/sdk/src/wasm.generated.ts
index 92657878b..d7c839470 100644
--- a/sdk/src/wasm.generated.ts
+++ b/sdk/src/wasm.generated.ts
@@ -374,6 +374,11 @@ export interface ParticleEmitter {
trailWidth: number;
trailPoints: number;
trailMinDistance: number;
+ collisionEnabled: boolean;
+ collisionFloor: number;
+ collisionBounce: number;
+ collisionFriction: number;
+ collisionLifetimeLoss: number;
}
export interface ParticleForceField {
diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
index 426413107..d389e4ed1 100644
--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap
@@ -251,6 +251,27 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho
"category": "Emission",
"min": 0,
},
+ "collisionBounce": {
+ "category": "Collision",
+ "max": 1,
+ "min": 0,
+ },
+ "collisionEnabled": {
+ "category": "Collision",
+ },
+ "collisionFloor": {
+ "category": "Collision",
+ },
+ "collisionFriction": {
+ "category": "Collision",
+ "max": 1,
+ "min": 0,
+ },
+ "collisionLifetimeLoss": {
+ "category": "Collision",
+ "max": 1,
+ "min": 0,
+ },
"colorEasing": {
"category": "Color",
"enum": [
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index 6896ca2cd..9264d40b3 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 b84b827b8b13d659
+ * @schema_hash 143effaba07f6224
*/
-#define ES_EDITOR_API_SCHEMA_HASH "b84b827b8b13d659"
+#define ES_EDITOR_API_SCHEMA_HASH "143effaba07f6224"
#include <emscripten/bind.h>
#include <string>
@@ -295,7 +295,12 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"trailEnabled","type":"bool","group":"ParticleEmitter"},
{"key":"trailWidth","type":"float","group":"ParticleEmitter"},
{"key":"trailPoints","type":"int","group":"ParticleEmitter"},
- {"key":"trailMinDistance","type":"float","group":"ParticleEmitter"}
+ {"key":"trailMinDistance","type":"float","group":"ParticleEmitter"},
+ {"key":"collisionEnabled","type":"bool","group":"ParticleEmitter"},
+ {"key":"collisionFloor","type":"float","group":"ParticleEmitter"},
+ {"key":"collisionBounce","type":"float","group":"ParticleEmitter"},
+ {"key":"collisionFriction","type":"float","group":"ParticleEmitter"},
+ {"key":"collisionLifetimeLoss","type":"float","group":"ParticleEmitter"}
])JSON";
} else if (name == "ParticleForceField") {
return R"JSON([
@@ -930,6 +935,10 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "subEmitterInheritVelocity") { c.subEmitterInheritVelocity = value; }
else if (field == "trailWidth") { c.trailWidth = value; }
else if (field == "trailMinDistance") { c.trailMinDistance = value; }
+ else if (field == "collisionFloor") { c.collisionFloor = value; }
+ else if (field == "collisionBounce") { c.collisionBounce = value; }
+ else if (field == "collisionFriction") { c.collisionFriction = value; }
+ else if (field == "collisionLifetimeLoss") { c.collisionLifetimeLoss = value; }
else { return false; }
return true;
} else if (comp == "ParticleForceField") {
@@ -1290,6 +1299,10 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "subEmitterInheritVelocity") { return c.subEmitterInheritVelocity; }
else if (field == "trailWidth") { return c.trailWidth; }
else if (field == "trailMinDistance") { return c.trailMinDistance; }
+ else if (field == "collisionFloor") { return c.collisionFloor; }
+ else if (field == "collisionBounce") { return c.collisionBounce; }
+ else if (field == "collisionFriction") { return c.collisionFriction; }
+ else if (field == "collisionLifetimeLoss") { return c.collisionLifetimeLoss; }
} else if (comp == "ParticleForceField") {
if (!reg.has<esengine::ecs::ParticleForceField>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::ParticleForceField>(entity);
@@ -1870,6 +1883,7 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "spriteLoop") { c.spriteLoop = value; }
else if (field == "enabled") { c.enabled = value; }
else if (field == "trailEnabled") { c.trailEnabled = value; }
+ else if (field == "collisionEnabled") { c.collisionEnabled = value; }
else { return false; }
return true;
} else if (comp == "ParticleForceField") {
@@ -2015,6 +2029,7 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "spriteLoop") { return c.spriteLoop; }
else if (field == "enabled") { return c.enabled; }
else if (field == "trailEnabled") { return c.trailEnabled; }
+ else if (field == "collisionEnabled") { return c.collisionEnabled; }
} else if (comp == "ParticleForceField") {
if (!reg.has<esengine::ecs::ParticleForceField>(entity)) return false;
const auto& c = reg.get<esengine::ecs::ParticleForceField>(entity);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index c5f575611..5aebdd827 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -512,6 +512,11 @@ struct ParticleEmitterJS {
f32 trailWidth;
i32 trailPoints;
f32 trailMinDistance;
+ bool collisionEnabled;
+ f32 collisionFloor;
+ f32 collisionBounce;
+ f32 collisionFriction;
+ f32 collisionLifetimeLoss;
};
esengine::ecs::ParticleEmitter particleemitterFromJS(const ParticleEmitterJS& js) {
@@ -569,6 +574,11 @@ esengine::ecs::ParticleEmitter particleemitterFromJS(const ParticleEmitterJS& js
c.trailWidth = js.trailWidth;
c.trailPoints = js.trailPoints;
c.trailMinDistance = js.trailMinDistance;
+ c.collisionEnabled = js.collisionEnabled;
+ c.collisionFloor = js.collisionFloor;
+ c.collisionBounce = js.collisionBounce;
+ c.collisionFriction = js.collisionFriction;
+ c.collisionLifetimeLoss = js.collisionLifetimeLoss;
return c;
}
@@ -627,6 +637,11 @@ ParticleEmitterJS particleemitterToJS(const esengine::ecs::ParticleEmitter& c) {
js.trailWidth = c.trailWidth;
js.trailPoints = c.trailPoints;
js.trailMinDistance = c.trailMinDistance;
+ js.collisionEnabled = c.collisionEnabled;
+ js.collisionFloor = c.collisionFloor;
+ js.collisionBounce = c.collisionBounce;
+ js.collisionFriction = c.collisionFriction;
+ js.collisionLifetimeLoss = c.collisionLifetimeLoss;
return js;
}
@@ -1129,7 +1144,12 @@ EMSCRIPTEN_BINDINGS(esengine_components) {
.field("trailEnabled", &ParticleEmitterJS::trailEnabled)
.field("trailWidth", &ParticleEmitterJS::trailWidth)
.field("trailPoints", &ParticleEmitterJS::trailPoints)
- .field("trailMinDistance", &ParticleEmitterJS::trailMinDistance);
+ .field("trailMinDistance", &ParticleEmitterJS::trailMinDistance)
+ .field("collisionEnabled", &ParticleEmitterJS::collisionEnabled)
+ .field("collisionFloor", &ParticleEmitterJS::collisionFloor)
+ .field("collisionBounce", &ParticleEmitterJS::collisionBounce)
+ .field("collisionFriction", &ParticleEmitterJS::collisionFriction)
+ .field("collisionLifetimeLoss", &ParticleEmitterJS::collisionLifetimeLoss);
value_object<esengine::ecs::ParticleForceField>("ParticleForceField")
.field("type", &esengine::ecs::ParticleForceField::type)
@@ -2077,6 +2097,11 @@ static_assert(offsetof(esengine::ecs::ParticleEmitter, trailEnabled) == 224, "AB
static_assert(offsetof(esengine::ecs::ParticleEmitter, trailWidth) == 228, "ABI offset drift: esengine::ecs::ParticleEmitter.trailWidth (EHT expected 228)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 232, "ABI offset drift: esengine::ecs::ParticleEmitter.trailPoints (EHT expected 232)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 236, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 236)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 240, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 240)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 244)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionBounce) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionBounce (EHT expected 248)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFriction) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFriction (EHT expected 252)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionLifetimeLoss) == 256, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionLifetimeLoss (EHT expected 256)");
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)");
@@ -2196,7 +2221,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "1ea8bcc5e5a72cc7";
+static const char* kEsAbiLayoutHash = "56d27a450a1ab9c6";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hpp
index 485fbef32..dec3a28fe 100644
--- a/src/esengine/ecs/components/ParticleEmitter.hpp
+++ b/src/esengine/ecs/components/ParticleEmitter.hpp
@@ -234,6 +234,30 @@ struct ParticleEmitter {
ES_PROPERTY(min=0, category=Trail)
f32 trailMinDistance{6.0f};
+ // Collision (Phase 1: a horizontal floor plane) — world-space particles that fall
+ // below `collisionFloor` (world Y) bounce off it. Self-contained CPU collision, no
+ // physics dependency: rain splashing on the ground, sparks skittering on a floor,
+ // snow settling. Off by default.
+ ES_PROPERTY(category=Collision)
+ bool collisionEnabled{false};
+
+ ES_PROPERTY(category=Collision)
+ f32 collisionFloor{0.0f};
+
+ // Restitution: 0 = particles stop dead on the floor, 1 = a full elastic bounce.
+ ES_PROPERTY(min=0, max=1, category=Collision)
+ f32 collisionBounce{0.5f};
+
+ // Tangential friction applied on each bounce (0 = frictionless slide, 1 = stop
+ // horizontal motion).
+ ES_PROPERTY(min=0, max=1, category=Collision)
+ f32 collisionFriction{0.1f};
+
+ // Fraction of a particle's remaining life burned on each bounce (0 = none, 1 =
+ // dies on first contact) — fades splashes/sparks out as they settle.
+ ES_PROPERTY(min=0, max=1, category=Collision)
+ f32 collisionLifetimeLoss{0.0f};
+
ParticleEmitter() = default;
};
diff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cpp
index ac39dc338..ae331def2 100644
--- a/src/esengine/particle/ParticleSystem.cpp
+++ b/src/esengine/particle/ParticleSystem.cpp
@@ -458,6 +458,8 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
int trailKeep = std::clamp(emitter.trailPoints, 2, kMaxTrailPoints);
f32 trailMinDistSq = emitter.trailMinDistance * emitter.trailMinDistance;
+ bool collisionOn = emitter.collisionEnabled && isWorldSpace;
+
dead_particle_indices_.clear();
state.pool.forEachAlive([&](Particle& p) {
@@ -492,6 +494,19 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
emitter.noiseStrength * dt;
}
+ // Floor collision: a particle that has fallen through the floor plane while
+ // moving down is snapped back and bounced, losing tangential speed to friction
+ // and (optionally) some life. Done before the trail records so the streak
+ // follows the bounce.
+ if (collisionOn && p.position.y < emitter.collisionFloor && p.velocity.y < 0.0f) {
+ p.position.y = emitter.collisionFloor;
+ p.velocity.y = -p.velocity.y * emitter.collisionBounce;
+ p.velocity.x *= (1.0f - emitter.collisionFriction);
+ if (emitter.collisionLifetimeLoss > 0.0f) {
+ p.age += emitter.collisionLifetimeLoss * p.lifetime;
+ }
+ }
+
// Record the settled position into this particle's trail ring (oldest→newest),
// gated by trailMinDistance so a slow particle doesn't pile up coincident points.
if (trailOn) {
diff --git a/tests/particle/test_particle.cpp b/tests/particle/test_particle.cpp
index fb391aa0b..4573383b8 100644
--- a/tests/particle/test_particle.cpp
+++ b/tests/particle/test_particle.cpp
@@ -602,6 +602,73 @@ TEST_CASE("system_force_field_radius_excludes_distant_particles") {
CHECK_FALSE(anyMoved); // out of range → untouched
}
+// A downward-falling emitter at the origin with a floor below it. `collision`
+// toggles the floor plane on/off.
+static Entity makeFallingEmitter(ecs::Registry& registry, bool collision) {
+ Entity e = registry.create();
+ registry.emplace<ecs::Transform>(e);
+ auto& emitter = registry.emplace<ecs::ParticleEmitter>(e);
+ emitter.rate = 500.0f;
+ emitter.lifetimeMin = emitter.lifetimeMax = 10.0f;
+ emitter.maxParticles = 30;
+ emitter.speedMin = emitter.speedMax = 0.0f;
+ emitter.shape = static_cast<i32>(ecs::EmitterShape::Point); // spawn at (0,0)
+ emitter.gravity = glm::vec2(0.0f, -600.0f); // fall down
+ emitter.collisionEnabled = collision;
+ emitter.collisionFloor = -100.0f;
+ emitter.collisionBounce = 0.6f;
+ emitter.playOnStart = true;
+ return e;
+}
+
+TEST_CASE("system_collision_floor_keeps_particles_above") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ Entity e = makeFallingEmitter(registry, /*collision=*/true);
+
+ system.update(registry, 0.02f);
+ for (int i = 0; i < 30; ++i) system.update(registry, 0.05f);
+
+ bool anyFarBelow = false;
+ system.forEachParticle(e, [&](const Particle& p) {
+ if (p.position.y < -160.0f) anyFarBelow = true; // floor is at -100
+ });
+ CHECK_FALSE(anyFarBelow);
+}
+
+TEST_CASE("system_collision_disabled_particles_fall_through_floor") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ Entity e = makeFallingEmitter(registry, /*collision=*/false);
+
+ system.update(registry, 0.02f);
+ for (int i = 0; i < 30; ++i) system.update(registry, 0.05f);
+
+ bool anyFarBelow = false;
+ system.forEachParticle(e, [&](const Particle& p) {
+ if (p.position.y < -400.0f) anyFarBelow = true; // no floor → falls well past -100
+ });
+ CHECK(anyFarBelow);
+}
+
+TEST_CASE("system_collision_bounce_gives_upward_velocity") {
+ ecs::Registry registry;
+ ParticleSystem system;
+ Entity e = makeFallingEmitter(registry, /*collision=*/true);
+
+ // The small synchronized pool oscillates in phase, so sample every frame and
+ // catch the upward leg of a bounce whenever it occurs.
+ system.update(registry, 0.02f);
+ bool bouncedUp = false;
+ for (int i = 0; i < 40 && !bouncedUp; ++i) {
+ system.update(registry, 0.03f);
+ system.forEachParticle(e, [&](const Particle& p) {
+ if (p.velocity.y > 1.0f) bouncedUp = true; // reflected up off the floor
+ });
+ }
+ CHECK(bouncedUp);
+}
+
TEST_CASE("system_size_interpolation") {
ecs::Registry registry;
ParticleSystem system;