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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(particle): add floor collision (Collision phase 1)
yhh5fb8f0c4f4c6
diff --git a/desktop/public/scenes/particle-collision.esscene b/desktop/public/scenes/particle-collision.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.mdxindex 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 pmove with their emitter and ignore fields), and `strength: 0` or `enabled: false` skipsa 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.mdxindex 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.mdindex 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 effectswith 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 ondeath) · `Turbulent Smoke` (curl-**noise** flow — smoke that rolls, embers thatweave) · `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 spritesrc/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) + Burststate.ts # the current showcase indexsystems/diff --git a/examples/particle-demo/src/config.ts b/examples/particle-demo/src/config.tsindex 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.mdindex 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: numberblendMode: numberburstCount: numberburstInterval: number+collisionBounce: number+collisionEnabled: boolean+collisionFloor: number+collisionFriction: number+collisionLifetimeLoss: numbercolorEasing: numbercolorGradient: { stops: { t: number; color: Color; }[]; }damping: numberdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 173d327c2..d99fc0065 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -4046,6 +4046,11 @@ angularVelocityMin: numberblendMode: numberburstCount: numberburstInterval: number+collisionBounce: number+collisionEnabled: boolean+collisionFloor: number+collisionFriction: number+collisionLifetimeLoss: numbercolorEasing: numbercolorGradient: { stops: { t: number; color: Color; }[]; }damping: numberdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 0eff9c016..6d3e1af17 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -4053,6 +4053,11 @@ angularVelocityMin: numberblendMode: numberburstCount: numberburstInterval: number+collisionBounce: number+collisionEnabled: boolean+collisionFloor: number+collisionFriction: number+collisionLifetimeLoss: numbercolorEasing: numbercolorGradient: { stops: { t: number; color: Color; }[]; }damping: numberdiff --git a/sdk/src/component.generated.ts b/sdk/src/component.generated.tsindex 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.tsindex 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.tsindex 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.tsindex 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.snapindex 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.cppindex 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::selse 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::stelse 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::stelse 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::stelse 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.cppindex 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& jsc.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, "ABstatic_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.hppindex 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.cppindex 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.cppindex 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;