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: add budgeted 2d and 3d particle scene collisions
yhhf14313f18cb7
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 03d755576..e3ca70782 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -16,6 +16,7 @@ published separately; it ships inside the editor.### Added+- **Budgeted particle scene collisions.** Particles query existing 2D or 3D physics along their movement segments, with layer filtering, rotating per-emitter/App query budgets, camera-distance culling and explicit floor/skip fallback. Bounded collision events use the standard EventReader; collision-triggered sub-emitters support local storage and capped inheritance depth. Details adds live counters and transient hit normals. A side-by-side sample demonstrates both physics paths and project-owned contact counters; device and performance acceptance remain pending.- **Reusable UI trees and color pickers.** TreeView adapts arbitrary project records with stable IDs to the existing virtualized ListView. It supports expansion, selection, keyboard navigation, row and empty-state prefabs, and validated drop requests whose mutations remain project-owned. ColorPicker composes HSV/RGB/HEX and alpha editing with standard sliders and text inputs, per-control recent colors, and canonical RGBA change events for 2D UI, sprites and 3D materials. Both have UI Widgets presets and themed Inspectors; preview sample data never overwrites saved project data. Their Details panels use standard property alignment, shared override/reset feedback, concise manual links and folded editor-only previews. Recent-color capacity is disabled without losing its value when history is off; opaque color editing fixes alpha at 1.- **UI tabs and tooltips.** TabView connects ordinary Toggles to content pages, with ordered entity bindings, keyboard navigation and an editor preview that leaves the saved initial page untouched. Tooltip adds delayed hover, keyboard-focus and touch-long-press hints, screen-edge placement and project theme or prefab styling. Both are available in the UI Widgets palette.- **3D swing/twist and six-axis joints.** SwingTwistJoint3D adds an elliptical swing cone and twist limits; SixDOFJoint3D locks, limits or frees each translation/rotation axis. Both support live velocity motors. The existing Details controls expose degree-based authoring, and selected viewport gizmos show limits. The 3D Physics example includes a shoulder and carriage with reversible motors. Partial property searches keep only matching generic fields. Headless solver checks do not replace target-device acceptance.diff --git a/desktop b/desktopindex 241a23472..b74cb9fb5 160000--- a/desktop+++ b/desktop@@ -1 +1 @@-Subproject commit 241a2347274cf0265fd4fc50b63b5e47040e70f6+Subproject commit b74cb9fb5b0b0f10742ad88654a2390162755d44diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex beb08bd4d..d30bde103 100644--- a/docs/astro/src/content/docs/world/particles.mdx+++ b/docs/astro/src/content/docs/world/particles.mdx@@ -501,6 +501,40 @@ const control = defineSystem([Res(Particle)], (particles) => {spawning a new entity each time.</Aside>+## Scene collisions++Enable collision and choose `ParticleCollisionMode.Floor`, `Physics2D` or+`Physics3D`. Scene modes cast each particle's movement segment through the+existing physics plugin, including fast motion across thin walls. These are+point queries, not rigid particle volumes or depth-buffer collision. Particle+positions, hit points and event velocities use project world units; physics+adapters perform their existing unit conversion.++`collisionQueryBudget` caps queries per emitter per update. The shared App cap+defaults to 4,096 queries and 1,024 notifications; change it through+`app.getResource(Particle).setCollisionBudget({ queries: 2048, events: 256 })`.+Partial budgets rotate between emitters and live particles. `collisionMaxDistance`+measures distance from the nearest active camera; zero or no active camera+disables distance culling. Offscreen particles still collide within the budget.++Choose `ParticleCollisionFallback.Floor` or `Skip` for unavailable physics,+exhausted budgets and distance culling. An ordinary query miss never invokes+fallback. `collisionMask` filters physics layers; zero selects none.++Set `collisionEvents: true` and read `EventReader(ParticleCollisionEvent)` in a+system on the next frame. Each payload contains emitter, pool slot, hit body,+mode, world point, normal and incoming velocity. Floor hits use `INVALID_ENTITY`+as their body. The `subEmitterTrigger: SubEmitterTrigger.Collision` option reuses+the child's burst settings; local-space children are supported. Self triggers+are rejected and inherited chains stop at depth eight.++`collisionEventBudget` and the App event cap bound collision notifications,+diagnostic contacts and collision sub-bursts. `collisionStats` exposes the latest+queries, hits, skipped work, unavailable queries, fallbacks and dropped events.+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.+## Performance & best practices- **Budget `maxParticles`.** It's a fixed pool; size it to the worst case, notdiff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxindex 19aa7c2d1..eff367ff3 100644--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx@@ -462,6 +462,31 @@ const control = defineSystem([Res(Particle)], (particles) => {用 `reset` + `play` 重新触发(比如可复用的受击火花)——比每次都生成新实体更省。</Aside>+## 场景碰撞++启用碰撞后可选 `ParticleCollisionMode.Floor`、`Physics2D` 或 `Physics3D`。+场景模式复用现有物理插件,查询粒子本帧移动线段,支持高速粒子越过薄墙的情况。+这是点粒子查询,不模拟有体积的刚体粒子,也不使用深度缓冲碰撞。+粒子位置、命中点与事件速度统一使用项目世界单位,物理适配器负责已有的单位换算。++`collisionQueryBudget` 限制单发射器每次更新的查询量。App 总预算默认为 4096 次查询、+1024 条通知,可用 `app.getResource(Particle).setCollisionBudget({ queries: 2048, events: 256 })`+调整。预算不足时在发射器与存活粒子间轮换采样。`collisionMaxDistance` 按最近活动相机裁剪;+0 或没有活动相机时不裁剪。离屏粒子在预算内仍执行碰撞。++`ParticleCollisionFallback.Floor` / `Skip` 决定物理不可用、预算耗尽、距离裁剪时的降级方式。+正常查询未命中不触发降级。`collisionMask` 按物理层过滤,0 表示不选择任何层。++启用 `collisionEvents` 后,下一帧可通过标准 `EventReader(ParticleCollisionEvent)` 读取+发射器、粒子池槽位、命中实体、查询模式、世界命中点、法线与入射速度。地面命中的实体为+`INVALID_ENTITY`。`subEmitterTrigger: SubEmitterTrigger.Collision` 复用子发射器的爆发设置,+支持局部坐标子发射器;拒绝自身触发,继承链最多八层。++`collisionEventBudget` 和 App 事件预算共同约束碰撞通知、诊断接触记录与碰撞子爆发。+`collisionStats` 提供最近一次更新的查询、命中、预算跳过、距离裁剪、不可用、降级和事件超限计数。+Details 支持查看计数与临时碰撞法线,法线开关不写入场景。+`particle-demo/assets/scenes/scene-collisions.esscene` 示例包含 2D / 3D 墙面、撞击爆发与项目事件计数。+## 性能与最佳实践- **控制 `maxParticles`。** 它是固定池;按最坏情况定大小,别更高。多个小发射器比一个巨大的diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 77793729f..fae43871a 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -2,11 +2,11 @@"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {"public": 115,- "beta": 158,+ "beta": 164,"experimental": 2236,"deprecated": 3},- "total": 2509,+ "total": 2515,"subsystems": [{"id": "mobile-controls",@@ -2282,6 +2282,78 @@"minigame"]},+ {+ "name": "ParticleCollisionBudget",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ParticleCollisionEvent",+ "kind": "const",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ParticleCollisionEventPayload",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ParticleCollisionFallback",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ParticleCollisionMode",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },+ {+ "name": "ParticleCollisionStats",+ "kind": "interface",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "ParticleEasing","kind": "enum",diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 110249096..8f5980dae 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -3093,7 +3093,8 @@"default": "Death","values": ["Death",- "Birth"+ "Birth",+ "Collision"]},{@@ -3146,6 +3147,54 @@"type": "number","default": "0"},+ {+ "key": "collisionMode",+ "type": "enum",+ "default": "Floor",+ "values": [+ "Floor",+ "Physics2D",+ "Physics3D"+ ]+ },+ {+ "key": "collisionMask",+ "type": "number",+ "default": "65535",+ "range": "0–65535, step 1"+ },+ {+ "key": "collisionQueryBudget",+ "type": "number",+ "default": "128",+ "range": "0–4096, step 1"+ },+ {+ "key": "collisionMaxDistance",+ "type": "number",+ "default": "0",+ "range": "≥ 0"+ },+ {+ "key": "collisionFallback",+ "type": "enum",+ "default": "Floor",+ "values": [+ "Floor",+ "Skip"+ ]+ },+ {+ "key": "collisionEvents",+ "type": "boolean",+ "default": "false"+ },+ {+ "key": "collisionEventBudget",+ "type": "number",+ "default": "32",+ "range": "0–1024, step 1"+ },{"key": "collisionBounce","type": "number",diff --git a/examples/particle-demo/README.md b/examples/particle-demo/README.mdindex 8c2af29bd..13ed3d41a 100644--- a/examples/particle-demo/README.md+++ b/examples/particle-demo/README.md@@ -51,6 +51,13 @@ into glows.## Files+Open `assets/scenes/scene-collisions.esscene` for side-by-side 2D and 3D physics+queries. Sparks bounce off thin walls and trigger impact sub-emitters; text+counters consume `ParticleCollisionEvent` through the standard event reader.+Both emitters have a 128-query / 32-event frame cap and an explicit floor+fallback. The 2D collider dimensions are metres; 3D colliders use world units.+The default gallery scene and its controls remain available.+```assets/scenes/main.esscene # camera, backdrop, UI (title + Prev/Next), TexHolderdiff --git a/examples/particle-demo/assets/scenes/scene-collisions.esscene b/examples/particle-demo/assets/scenes/scene-collisions.esscenenew file mode 100644index 000000000..c5989ac7e--- /dev/null+++ b/examples/particle-demo/assets/scenes/scene-collisions.esscene@@ -0,0 +1,523 @@+{+ "version": 4,+ "name": "Scene Collisions",+ "entities": [+ {+ "id": 0,+ "name": "Camera",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 1000+ }+ }+ },+ {+ "type": "Camera",+ "data": {+ "projectionType": 1,+ "orthoSize": 360,+ "isActive": true,+ "priority": 0+ }+ }+ ]+ },+ {+ "id": 1,+ "name": "Sparks2D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -420,+ "y": 80,+ "z": 0+ }+ }+ },+ {+ "type": "ParticleEmitter",+ "data": {+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",+ "shape": 0,+ "angleSpreadMin": -6,+ "angleSpreadMax": 6,+ "rate": 50,+ "maxParticles": 256,+ "lifetimeMin": 2,+ "lifetimeMax": 2,+ "speedMin": 330,+ "speedMax": 360,+ "gravity": {+ "x": 0,+ "y": -40,+ "z": 0+ },+ "startSizeMin": 7,+ "startSizeMax": 10,+ "endSizeMin": 2,+ "endSizeMax": 3,+ "endColor": {+ "r": 1,+ "g": 0.3,+ "b": 0.1,+ "a": 0+ },+ "collisionEnabled": true,+ "collisionQueryBudget": 128,+ "collisionMask": 65535,+ "collisionFallback": 0,+ "collisionFloor": -200,+ "collisionBounce": 0.65,+ "collisionFriction": 0.15,+ "collisionEvents": true,+ "collisionEventBudget": 32,+ "subEmitterTrigger": 2,+ "subEmitterInheritVelocity": 0.15,+ "subEmitterChance": 1,+ "collisionMode": 1,+ "subEmitter": 3,+ "startColor": {+ "r": 1,+ "g": 0.65,+ "b": 0.18,+ "a": 1+ }+ }+ }+ ]+ },+ {+ "id": 2,+ "name": "Wall2D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -120,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "RigidBody2D",+ "data": {+ "bodyType": 0+ }+ },+ {+ "type": "BoxCollider2D",+ "data": {+ "halfExtents": {+ "x": 0.05,+ "y": 1.8+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 10,+ "y": 360+ },+ "color": {+ "r": 0.25,+ "g": 0.31,+ "b": 0.4,+ "a": 1+ }+ }+ }+ ]+ },+ {+ "id": 3,+ "name": "Impact2D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "ParticleEmitter",+ "data": {+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",+ "playOnStart": false,+ "shape": 0,+ "rate": 0,+ "burstCount": 5,+ "maxParticles": 256,+ "lifetimeMin": 0.18,+ "lifetimeMax": 0.35,+ "speedMin": 35,+ "speedMax": 80,+ "gravity": {+ "x": 0,+ "y": -80,+ "z": 0+ },+ "startSizeMin": 6,+ "startSizeMax": 9,+ "endSizeMin": 0,+ "endSizeMax": 1,+ "startColor": {+ "r": 1,+ "g": 0.65,+ "b": 0.18,+ "a": 1+ },+ "endColor": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 0+ }+ }+ }+ ]+ },+ {+ "id": 7,+ "name": "2D Physics",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -420,+ "y": 250,+ "z": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "2D Physics",+ "fontSize": 26,+ "color": {+ "r": 1,+ "g": 0.65,+ "b": 0.18,+ "a": 1+ }+ }+ }+ ]+ },+ {+ "id": 9,+ "name": "CollisionCounter2D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": -420,+ "y": -260,+ "z": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "Waiting for contacts",+ "fontSize": 18,+ "color": {+ "r": 0.75,+ "g": 0.82,+ "b": 0.9,+ "a": 1+ }+ }+ },+ {+ "type": "CollisionCounter",+ "data": {+ "mode": 1,+ "total": 0+ }+ }+ ]+ },+ {+ "id": 4,+ "name": "Sparks3D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 80,+ "y": 80,+ "z": 0+ }+ }+ },+ {+ "type": "ParticleEmitter",+ "data": {+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",+ "shape": 0,+ "angleSpreadMin": -6,+ "angleSpreadMax": 6,+ "rate": 50,+ "maxParticles": 256,+ "lifetimeMin": 2,+ "lifetimeMax": 2,+ "speedMin": 330,+ "speedMax": 360,+ "gravity": {+ "x": 0,+ "y": -40,+ "z": 0+ },+ "startSizeMin": 7,+ "startSizeMax": 10,+ "endSizeMin": 2,+ "endSizeMax": 3,+ "endColor": {+ "r": 1,+ "g": 0.3,+ "b": 0.1,+ "a": 0+ },+ "collisionEnabled": true,+ "collisionQueryBudget": 128,+ "collisionMask": 65535,+ "collisionFallback": 0,+ "collisionFloor": -200,+ "collisionBounce": 0.65,+ "collisionFriction": 0.15,+ "collisionEvents": true,+ "collisionEventBudget": 32,+ "subEmitterTrigger": 2,+ "subEmitterInheritVelocity": 0.15,+ "subEmitterChance": 1,+ "collisionMode": 2,+ "subEmitter": 6,+ "startColor": {+ "r": 0.2,+ "g": 0.75,+ "b": 1,+ "a": 1+ }+ }+ }+ ]+ },+ {+ "id": 5,+ "name": "Wall3D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 380,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "RigidBody3D",+ "data": {+ "bodyType": 0+ }+ },+ {+ "type": "BoxCollider3D",+ "data": {+ "halfExtents": {+ "x": 5,+ "y": 180,+ "z": 80+ }+ }+ },+ {+ "type": "Sprite",+ "data": {+ "size": {+ "x": 10,+ "y": 360+ },+ "color": {+ "r": 0.25,+ "g": 0.31,+ "b": 0.4,+ "a": 1+ }+ }+ }+ ]+ },+ {+ "id": 6,+ "name": "Impact3D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 0,+ "y": 0,+ "z": 0+ }+ }+ },+ {+ "type": "ParticleEmitter",+ "data": {+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0",+ "playOnStart": false,+ "shape": 0,+ "rate": 0,+ "burstCount": 5,+ "maxParticles": 256,+ "lifetimeMin": 0.18,+ "lifetimeMax": 0.35,+ "speedMin": 35,+ "speedMax": 80,+ "gravity": {+ "x": 0,+ "y": -80,+ "z": 0+ },+ "startSizeMin": 6,+ "startSizeMax": 9,+ "endSizeMin": 0,+ "endSizeMax": 1,+ "startColor": {+ "r": 0.2,+ "g": 0.75,+ "b": 1,+ "a": 1+ },+ "endColor": {+ "r": 1,+ "g": 1,+ "b": 1,+ "a": 0+ }+ }+ }+ ]+ },+ {+ "id": 8,+ "name": "3D Physics",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 80,+ "y": 250,+ "z": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "3D Physics",+ "fontSize": 26,+ "color": {+ "r": 0.2,+ "g": 0.75,+ "b": 1,+ "a": 1+ }+ }+ }+ ]+ },+ {+ "id": 10,+ "name": "CollisionCounter3D",+ "parent": null,+ "children": [],+ "visible": true,+ "components": [+ {+ "type": "Transform",+ "data": {+ "position": {+ "x": 80,+ "y": -260,+ "z": 0+ }+ }+ },+ {+ "type": "Text",+ "data": {+ "content": "Waiting for contacts",+ "fontSize": 18,+ "color": {+ "r": 0.75,+ "g": 0.82,+ "b": 0.9,+ "a": 1+ }+ }+ },+ {+ "type": "CollisionCounter",+ "data": {+ "mode": 2,+ "total": 0+ }+ }+ ]+ }+ ]+}diff --git a/examples/particle-demo/assets/scenes/scene-collisions.esscene.meta b/examples/particle-demo/assets/scenes/scene-collisions.esscene.metanew file mode 100644index 000000000..e132f235d--- /dev/null+++ b/examples/particle-demo/assets/scenes/scene-collisions.esscene.meta@@ -0,0 +1,8 @@+{+ "uuid": "24b329a9-f2af-4fa6-9ef3-11c3a3886af1",+ "version": "2.0",+ "type": "scene",+ "importer": {+ "autoMigrate": true+ }+}diff --git a/examples/particle-demo/src/components.ts b/examples/particle-demo/src/components.tsindex 99458cdbc..31ea12980 100644--- a/examples/particle-demo/src/components.ts+++ b/examples/particle-demo/src/components.ts@@ -21,3 +21,8 @@ export const ShowcaseEmitter = defineTag('ShowcaseEmitter');export const Burst = defineComponent('Burst', {age: 0,});++export const CollisionCounter = defineComponent('CollisionCounter', {+ mode: 1,+ total: 0,+});diff --git a/examples/particle-demo/src/main.ts b/examples/particle-demo/src/main.tsindex 9e3feb5e7..ab2af9ef1 100644--- a/examples/particle-demo/src/main.ts+++ b/examples/particle-demo/src/main.ts@@ -16,8 +16,10 @@ import { setupSystem } from './systems/setup';import { switchSystem } from './systems/switch';import { sparkSystem } from './systems/spark';import { cleanupSystem } from './systems/cleanup';+import { collisionSystem } from './systems/collision';addStartupSystem(setupSystem);addSystemToSchedule(Schedule.Update, switchSystem);addSystemToSchedule(Schedule.Update, sparkSystem);addSystemToSchedule(Schedule.Update, cleanupSystem);+addSystemToSchedule(Schedule.Update, collisionSystem);diff --git a/examples/particle-demo/src/systems/collision.ts b/examples/particle-demo/src/systems/collision.tsnew file mode 100644index 000000000..566657fe5--- /dev/null+++ b/examples/particle-demo/src/systems/collision.ts@@ -0,0 +1,18 @@+import {+ defineSystem, EventReader, Mut, Query, ParticleCollisionEvent, Text,+ type EventReaderInstance, type ParticleCollisionEventPayload,+} from 'esengine';+import { CollisionCounter } from '../components';++export const collisionSystem = defineSystem(+ [EventReader(ParticleCollisionEvent), Query(Mut(CollisionCounter), Mut(Text))],+ (events: EventReaderInstance<ParticleCollisionEventPayload>, counters) => {+ const counts = new Map<number, number>();+ for (const event of events) counts.set(event.mode, (counts.get(event.mode) ?? 0) + 1);+ for (const [, counter, text] of counters) {+ counter.total += counts.get(counter.mode) ?? 0;+ text.content = `${counter.total} contacts`;+ }+ },+ { name: 'ParticleCollisionCounter' },+);diff --git a/examples/particle-demo/src/systems/spark.ts b/examples/particle-demo/src/systems/spark.tsindex 6b12e9d97..03e2616b5 100644--- a/examples/particle-demo/src/systems/spark.ts+++ b/examples/particle-demo/src/systems/spark.ts@@ -13,7 +13,9 @@ export const sparkSystem = defineSystem((input, camera: UICameraData, holders, cmds) => {if (!camera.valid || !input.isMouseButtonPressed(0) || input.isPointerOverUI()) return;let texture = 0;- for (const [, sprite] of holders) texture = sprite.texture;+ let hasHolder = false;+ for (const [, sprite] of holders) { texture = sprite.texture; hasHolder = true; }+ if (!hasHolder) return;cmds.spawn().insert(Transform, { position: { x: camera.worldMouseX, y: camera.worldMouseY, z: 0 } }).insert(ParticleEmitter, { ...BURST, texture })diff --git a/examples/particle-demo/src/systems/switch.ts b/examples/particle-demo/src/systems/switch.tsindex cf3c0e3f5..05937f11e 100644--- a/examples/particle-demo/src/systems/switch.ts+++ b/examples/particle-demo/src/systems/switch.ts@@ -19,6 +19,10 @@ export const switchSystem = defineSystem(Commands(),],(input, events: UIEventQueue, prevs, nexts, holders, emitters, titles, cmds) => {+ let texture = 0;+ let hasHolder = false;+ for (const [, sprite] of holders) { texture = sprite.texture; hasHolder = true; }+ if (!hasHolder) return;let dir = 0;if (input.isKeyPressed('ArrowRight') || input.isKeyPressed('Space')) dir = 1;else if (input.isKeyPressed('ArrowLeft')) dir = -1;@@ -31,8 +35,6 @@ export const switchSystem = defineSystem(state.current = (state.current + dir + SHOWCASE_COUNT) % SHOWCASE_COUNT;for (const [entity] of emitters) cmds.despawn(entity);- let texture = 0;- for (const [, sprite] of holders) texture = sprite.texture;spawnShowcase(cmds, state.current, texture);for (const [, text] of titles) text.content = SHOWCASES[state.current].name;},diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 1aa3aa2bf..b050a91ac 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,11 +1,11 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 146 beta · 1612 experimental · 3 deprecated+Symbols: 115 public · 152 beta · 1612 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"4a247e158faf0865"+"2f29375a9e0f797d"```## ANCHOR_AXES — const @experimental@@ -5703,18 +5703,79 @@ ResourceDef<ParticleAPI>## ParticleAPI — class @experimental```+@internal collisionContacts: readonly ParticleCollisionEventPayload[]+collisionError: string | null+collisionEvents: readonly ParticleCollisionEventPayload[]+collisionStats: readonly ParticleCollisionStats[]+debugNormals: booleangetAliveCount: (entity: Entity) => numberplay: (entity: Entity) => voidreset: (entity: Entity) => void+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => voidsetColorLut: (entity: Entity, lut: Float32Array | null) => voidsetSizeLut: (entity: Entity, lut: Float32Array | null) => voidsetSpeedLut: (entity: Entity, lut: Float32Array | null) => voidstop: (entity: Entity) => voidupdate: (dt: number) => void-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPIstatic prototype: ParticleAPI```+## ParticleCollisionBudget — interface @beta+```+events: number+queries: number+```++## ParticleCollisionEvent — const @beta+```+EventDef<ParticleCollisionEventPayload>+```++## ParticleCollisionEventPayload — interface @beta+```+body: number+emitter: number+mode: number+normalX: number+normalY: number+normalZ: number+particle: number+velocityX: number+velocityY: number+velocityZ: number+x: number+y: number+z: number+```++## ParticleCollisionFallback — enum @beta+```+Floor = 0+Skip = 1+```++## ParticleCollisionMode — enum @beta+```+Floor = 0+Physics2D = 1+Physics3D = 2+```++## ParticleCollisionStats — interface @beta+```+budgetSkipped: number+distanceSkipped: number+emitter: number+eventDropped: number+events: number+fallbacks: number+hits: number+mode: number+queries: number+unavailable: number+```+## ParticleEasing — enum @beta```EaseIn = 1@@ -5739,9 +5800,16 @@ burstCount: numberburstInterval: numbercollisionBounce: numbercollisionEnabled: boolean+collisionEventBudget: number+collisionEvents: boolean+collisionFallback: ParticleCollisionFallbackcollisionFloor: numbercollisionFriction: numbercollisionLifetimeLoss: number+collisionMask: number+collisionMaxDistance: number+collisionMode: ParticleCollisionMode+collisionQueryBudget: numbercolorEasing: ParticleEasingcolorGradient: { stops: { t: number; color: Color; }[]; }damping: number@@ -8690,6 +8758,7 @@ skyUnavailable: SkyUnavailable | null## SubEmitterTrigger — enum @beta```Birth = 1+Collision = 2Death = 0```diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex eb702ba10..1daa742ba 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,11 +1,11 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 151 beta · 1631 experimental · 3 deprecated+Symbols: 115 public · 157 beta · 1631 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"4a247e158faf0865"+"2f29375a9e0f797d"```## ANCHOR_AXES — const @experimental@@ -5906,18 +5906,79 @@ ResourceDef<ParticleAPI>## ParticleAPI — class @experimental```+@internal collisionContacts: readonly ParticleCollisionEventPayload[]+collisionError: string | null+collisionEvents: readonly ParticleCollisionEventPayload[]+collisionStats: readonly ParticleCollisionStats[]+debugNormals: booleangetAliveCount: (entity: Entity) => numberplay: (entity: Entity) => voidreset: (entity: Entity) => void+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => voidsetColorLut: (entity: Entity, lut: Float32Array | null) => voidsetSizeLut: (entity: Entity, lut: Float32Array | null) => voidsetSpeedLut: (entity: Entity, lut: Float32Array | null) => voidstop: (entity: Entity) => voidupdate: (dt: number) => void-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPIstatic prototype: ParticleAPI```+## ParticleCollisionBudget — interface @beta+```+events: number+queries: number+```++## ParticleCollisionEvent — const @beta+```+EventDef<ParticleCollisionEventPayload>+```++## ParticleCollisionEventPayload — interface @beta+```+body: number+emitter: number+mode: number+normalX: number+normalY: number+normalZ: number+particle: number+velocityX: number+velocityY: number+velocityZ: number+x: number+y: number+z: number+```++## ParticleCollisionFallback — enum @beta+```+Floor = 0+Skip = 1+```++## ParticleCollisionMode — enum @beta+```+Floor = 0+Physics2D = 1+Physics3D = 2+```++## ParticleCollisionStats — interface @beta+```+budgetSkipped: number+distanceSkipped: number+emitter: number+eventDropped: number+events: number+fallbacks: number+hits: number+mode: number+queries: number+unavailable: number+```+## ParticleEasing — enum @beta```EaseIn = 1@@ -5942,9 +6003,16 @@ burstCount: numberburstInterval: numbercollisionBounce: numbercollisionEnabled: boolean+collisionEventBudget: number+collisionEvents: boolean+collisionFallback: ParticleCollisionFallbackcollisionFloor: numbercollisionFriction: numbercollisionLifetimeLoss: number+collisionMask: number+collisionMaxDistance: number+collisionMode: ParticleCollisionMode+collisionQueryBudget: numbercolorEasing: ParticleEasingcolorGradient: { stops: { t: number; color: Color; }[]; }damping: number@@ -8903,6 +8971,7 @@ skyUnavailable: SkyUnavailable | null## SubEmitterTrigger — enum @beta```Birth = 1+Collision = 2Death = 0```diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 6020a31fa..9082c05d5 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 148 beta · 1611 experimental · 3 deprecated+Symbols: 115 public · 154 beta · 1611 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -5698,18 +5698,79 @@ ResourceDef<ParticleAPI>## ParticleAPI — class @experimental```+@internal collisionContacts: readonly ParticleCollisionEventPayload[]+collisionError: string | null+collisionEvents: readonly ParticleCollisionEventPayload[]+collisionStats: readonly ParticleCollisionStats[]+debugNormals: booleangetAliveCount: (entity: Entity) => numberplay: (entity: Entity) => voidreset: (entity: Entity) => void+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => voidsetColorLut: (entity: Entity, lut: Float32Array | null) => voidsetSizeLut: (entity: Entity, lut: Float32Array | null) => voidsetSpeedLut: (entity: Entity, lut: Float32Array | null) => voidstop: (entity: Entity) => voidupdate: (dt: number) => void-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPIstatic prototype: ParticleAPI```+## ParticleCollisionBudget — interface @beta+```+events: number+queries: number+```++## ParticleCollisionEvent — const @beta+```+EventDef<ParticleCollisionEventPayload>+```++## ParticleCollisionEventPayload — interface @beta+```+body: number+emitter: number+mode: number+normalX: number+normalY: number+normalZ: number+particle: number+velocityX: number+velocityY: number+velocityZ: number+x: number+y: number+z: number+```++## ParticleCollisionFallback — enum @beta+```+Floor = 0+Skip = 1+```++## ParticleCollisionMode — enum @beta+```+Floor = 0+Physics2D = 1+Physics3D = 2+```++## ParticleCollisionStats — interface @beta+```+budgetSkipped: number+distanceSkipped: number+emitter: number+eventDropped: number+events: number+fallbacks: number+hits: number+mode: number+queries: number+unavailable: number+```+## ParticleEasing — enum @beta```EaseIn = 1@@ -5734,9 +5795,16 @@ burstCount: numberburstInterval: numbercollisionBounce: numbercollisionEnabled: boolean+collisionEventBudget: number+collisionEvents: boolean+collisionFallback: ParticleCollisionFallbackcollisionFloor: numbercollisionFriction: numbercollisionLifetimeLoss: number+collisionMask: number+collisionMaxDistance: number+collisionMode: ParticleCollisionMode+collisionQueryBudget: numbercolorEasing: ParticleEasingcolorGradient: { stops: { t: number; color: Color; }[]; }damping: number@@ -8685,6 +8753,7 @@ skyUnavailable: SkyUnavailable | null## SubEmitterTrigger — enum @beta```Birth = 1+Collision = 2Death = 0```diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 0c7f86e83..4ba3d6acc 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 146 beta · 1633 experimental · 3 deprecated+Symbols: 115 public · 152 beta · 1633 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -5991,18 +5991,79 @@ ResourceDef<ParticleAPI>## ParticleAPI — class @experimental```+@internal collisionContacts: readonly ParticleCollisionEventPayload[]+collisionError: string | null+collisionEvents: readonly ParticleCollisionEventPayload[]+collisionStats: readonly ParticleCollisionStats[]+debugNormals: booleangetAliveCount: (entity: Entity) => numberplay: (entity: Entity) => voidreset: (entity: Entity) => void+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => voidsetColorLut: (entity: Entity, lut: Float32Array | null) => voidsetSizeLut: (entity: Entity, lut: Float32Array | null) => voidsetSpeedLut: (entity: Entity, lut: Float32Array | null) => voidstop: (entity: Entity) => voidupdate: (dt: number) => void-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPIstatic prototype: ParticleAPI```+## ParticleCollisionBudget — interface @beta+```+events: number+queries: number+```++## ParticleCollisionEvent — const @beta+```+EventDef<ParticleCollisionEventPayload>+```++## ParticleCollisionEventPayload — interface @beta+```+body: number+emitter: number+mode: number+normalX: number+normalY: number+normalZ: number+particle: number+velocityX: number+velocityY: number+velocityZ: number+x: number+y: number+z: number+```++## ParticleCollisionFallback — enum @beta+```+Floor = 0+Skip = 1+```++## ParticleCollisionMode — enum @beta+```+Floor = 0+Physics2D = 1+Physics3D = 2+```++## ParticleCollisionStats — interface @beta+```+budgetSkipped: number+distanceSkipped: number+emitter: number+eventDropped: number+events: number+fallbacks: number+hits: number+mode: number+queries: number+unavailable: number+```+## ParticleEasing — enum @beta```EaseIn = 1@@ -6027,9 +6088,16 @@ burstCount: numberburstInterval: numbercollisionBounce: numbercollisionEnabled: boolean+collisionEventBudget: number+collisionEvents: boolean+collisionFallback: ParticleCollisionFallbackcollisionFloor: numbercollisionFriction: numbercollisionLifetimeLoss: number+collisionMask: number+collisionMaxDistance: number+collisionMode: ParticleCollisionMode+collisionQueryBudget: numbercolorEasing: ParticleEasingcolorGradient: { stops: { t: number; color: Color; }[]; }damping: number@@ -8978,6 +9046,7 @@ skyUnavailable: SkyUnavailable | null## SubEmitterTrigger — enum @beta```Birth = 1+Collision = 2Death = 0```diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 52d8e580d..2fd7d1f8b 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -362,6 +362,14 @@ mesh_createFromChannels: ((channelsPtr: number, channelCount: number, vertexStrimesh_release: ((meshHandle: number) => void) | undefinedmesh_rematerializeFromChannels: ((targetHandle: number, channelsPtr: number, channelCount: number, vertexStride: number, vertexPtr: number, vertexBytes: number, indexPtr: number, indexCount: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, bindPtr: number, bindFloats: number, morphPtr: number, morphFloats: number, morphTargets: number, morphNormals: number) => number) | undefinednotifyDeviceLost: ((reason: number, message: string) => void) | undefined+particle_collisionEventCount: (() => number) | undefined+particle_collisionEvents: (() => number) | undefined+particle_collisionQueries: (() => number) | undefined+particle_collisionQueryCount: (() => number) | undefined+particle_collisionResolve: ((registry: CppRegistry, ptr: number, count: number) => void) | undefined+particle_collisionSetBudget: ((queries: number, events: number, debug: boolean) => void) | undefined+particle_collisionStats: (() => number) | undefined+particle_collisionStatsCount: (() => number) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefinedparticle_reset: ((registry: CppRegistry, entity: number) => void) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 3577199fb..1c5842c4a 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 146 beta · 1624 experimental · 3 deprecated+Symbols: 115 public · 152 beta · 1624 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -5705,18 +5705,79 @@ ResourceDef<ParticleAPI>## ParticleAPI — class @experimental```+@internal collisionContacts: readonly ParticleCollisionEventPayload[]+collisionError: string | null+collisionEvents: readonly ParticleCollisionEventPayload[]+collisionStats: readonly ParticleCollisionStats[]+debugNormals: booleangetAliveCount: (entity: Entity) => numberplay: (entity: Entity) => voidreset: (entity: Entity) => void+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => voidsetColorLut: (entity: Entity, lut: Float32Array | null) => voidsetSizeLut: (entity: Entity, lut: Float32Array | null) => voidsetSpeedLut: (entity: Entity, lut: Float32Array | null) => voidstop: (entity: Entity) => voidupdate: (dt: number) => void-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPIstatic prototype: ParticleAPI```+## ParticleCollisionBudget — interface @beta+```+events: number+queries: number+```++## ParticleCollisionEvent — const @beta+```+EventDef<ParticleCollisionEventPayload>+```++## ParticleCollisionEventPayload — interface @beta+```+body: number+emitter: number+mode: number+normalX: number+normalY: number+normalZ: number+particle: number+velocityX: number+velocityY: number+velocityZ: number+x: number+y: number+z: number+```++## ParticleCollisionFallback — enum @beta+```+Floor = 0+Skip = 1+```++## ParticleCollisionMode — enum @beta+```+Floor = 0+Physics2D = 1+Physics3D = 2+```++## ParticleCollisionStats — interface @beta+```+budgetSkipped: number+distanceSkipped: number+emitter: number+eventDropped: number+events: number+fallbacks: number+hits: number+mode: number+queries: number+unavailable: number+```+## ParticleEasing — enum @beta```EaseIn = 1@@ -5741,9 +5802,16 @@ burstCount: numberburstInterval: numbercollisionBounce: numbercollisionEnabled: boolean+collisionEventBudget: number+collisionEvents: boolean+collisionFallback: ParticleCollisionFallbackcollisionFloor: numbercollisionFriction: numbercollisionLifetimeLoss: number+collisionMask: number+collisionMaxDistance: number+collisionMode: ParticleCollisionMode+collisionQueryBudget: numbercolorEasing: ParticleEasingcolorGradient: { stops: { t: number; color: Color; }[]; }damping: number@@ -8692,6 +8760,7 @@ skyUnavailable: SkyUnavailable | null## SubEmitterTrigger — enum @beta```Birth = 1+Collision = 2Death = 0```diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex b2aebc6b7..54715b55e 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -747,6 +747,10 @@ export {ParticleAPI,ParticlePlugin,particlePlugin,+ ParticleCollisionEvent,+ type ParticleCollisionEventPayload,+ type ParticleCollisionStats,+ type ParticleCollisionBudget,} from './particle';// =============================================================================diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex ca4298073..bd1636e7f 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -154,6 +154,8 @@ export {SimulationSpace,SubEmitterTrigger,ParticleEasing,+ ParticleCollisionMode,+ ParticleCollisionFallback,type ParticleEmitterData,ParticleForceField,ForceFieldType,diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 999aa0a61..f643a5b10 100644--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts@@ -83,6 +83,14 @@ export interface NativeEngineApi {mesh_createFromChannels?(channelsPtr: number, channelCount: number, vertexStride: number, vertexPtr: number, vertexBytes: number, indexPtr: number, indexCount: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, bindPtr: number, bindFloats: number, morphPtr: number, morphFloats: number, morphTargets: number, morphNormals: number): number;mesh_release?(meshHandle: number): void;mesh_rematerializeFromChannels?(targetHandle: number, channelsPtr: number, channelCount: number, vertexStride: number, vertexPtr: number, vertexBytes: number, indexPtr: number, indexCount: number, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number, bindPtr: number, bindFloats: number, morphPtr: number, morphFloats: number, morphTargets: number, morphNormals: number): number;+ particle_collisionEventCount?(): number;+ particle_collisionEvents?(): number;+ particle_collisionQueries?(): number;+ particle_collisionQueryCount?(): number;+ particle_collisionResolve?(registry: unknown, ptr: number, count: number): void;+ particle_collisionSetBudget?(queries: number, events: number, debug: boolean): void;+ particle_collisionStats?(): number;+ particle_collisionStatsCount?(): number;particle_getAliveCount?(entity: number): number;particle_play?(registry: unknown, entity: number): void;particle_reset?(registry: unknown, entity: number): void;@@ -386,6 +394,14 @@ export function createNativeEngineApi(bind('mesh_createFromChannels', 'es_mesh_createFromChannels', false);bind('mesh_release', 'es_mesh_release', false);bind('mesh_rematerializeFromChannels', 'es_mesh_rematerializeFromChannels', false);+ bind('particle_collisionEventCount', 'es_particle_collisionEventCount', false);+ bind('particle_collisionEvents', 'es_particle_collisionEvents', false);+ bind('particle_collisionQueries', 'es_particle_collisionQueries', false);+ bind('particle_collisionQueryCount', 'es_particle_collisionQueryCount', false);+ bind('particle_collisionResolve', 'es_particle_collisionResolve', true);+ bind('particle_collisionSetBudget', 'es_particle_collisionSetBudget', false);+ bind('particle_collisionStats', 'es_particle_collisionStats', false);+ bind('particle_collisionStatsCount', 'es_particle_collisionStatsCount', false);bind('particle_getAliveCount', 'es_particle_getAliveCount', false);bind('particle_play', 'es_particle_play', true);bind('particle_reset', 'es_particle_reset', true);diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex bb3770b7c..739ac9d91 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -1153,6 +1153,13 @@ export interface ParticleEmitterPtrData {trailMinDistance: number;collisionEnabled: boolean;collisionFloor: number;+ collisionMode: number;+ collisionMask: number;+ collisionQueryBudget: number;+ collisionMaxDistance: number;+ collisionFallback: number;+ collisionEvents: boolean;+ collisionEventBudget: number;collisionBounce: number;collisionFriction: number;collisionLifetimeLoss: number;@@ -1217,9 +1224,16 @@ export function fillParticleEmitter(out.trailMinDistance = f32[(ptr + 244) >> 2];out.collisionEnabled = u8[ptr + 248] !== 0;out.collisionFloor = f32[(ptr + 252) >> 2];- out.collisionBounce = f32[(ptr + 256) >> 2];- out.collisionFriction = f32[(ptr + 260) >> 2];- out.collisionLifetimeLoss = f32[(ptr + 264) >> 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];}export function writeParticleEmitter(@@ -1281,9 +1295,16 @@ export function writeParticleEmitter(f32[(ptr + 244) >> 2] = data.trailMinDistance;u8[ptr + 248] = data.collisionEnabled ? 1 : 0;f32[(ptr + 252) >> 2] = data.collisionFloor;- f32[(ptr + 256) >> 2] = data.collisionBounce;- f32[(ptr + 260) >> 2] = data.collisionFriction;- f32[(ptr + 264) >> 2] = data.collisionLifetimeLoss;+ 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;}export function createParticleEmitterData(): ParticleEmitterPtrData {@@ -1343,6 +1364,13 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {trailMinDistance: 0,collisionEnabled: false,collisionFloor: 0,+ collisionMode: 0,+ collisionMask: 0,+ collisionQueryBudget: 0,+ collisionMaxDistance: 0,+ collisionFallback: 0,+ collisionEvents: false,+ collisionEventBudget: 0,collisionBounce: 0,collisionFriction: 0,collisionLifetimeLoss: 0,diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex 77116980b..f288b79bf 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -7,7 +7,7 @@import type { AssetFieldType } from '../scene/scene';import type { FieldMeta } from './component';import type { Color, Entity, Quat, Vec2, Vec3, Vec4 } from '../types';-import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleEasing, ProjectionType, ScrollMovement, ShapeType, SimulationSpace, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';+import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleCollisionFallback, ParticleCollisionMode, ParticleEasing, ProjectionType, ScrollMovement, ShapeType, SimulationSpace, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';/*** Single-source-of-truth hash of the C++/TS boundary ABI (component@@ -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 = '4a247e158faf0865';+export const ABI_LAYOUT_HASH = '2f29375a9e0f797d';/*** One asset-valued field of a component: which field, and what kind of@@ -694,6 +694,13 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {trailMinDistance: 6,collisionEnabled: false,collisionFloor: 0,+ collisionMode: 0,+ collisionMask: 65535,+ collisionQueryBudget: 128,+ collisionMaxDistance: 0,+ collisionFallback: 0,+ collisionEvents: false,+ collisionEventBudget: 32,collisionBounce: 0.5,collisionFriction: 0.1,collisionLifetimeLoss: 0,@@ -748,7 +755,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {layer: { step: 1, category: "Rendering", enumSource: "sortingLayers" },material: { category: "Rendering" },simulationSpace: { enum: [{ label: 'World', value: 0 }, { label: 'Local', value: 1 }], category: "Rendering" },- subEmitterTrigger: { enum: [{ label: 'Death', value: 0 }, { label: 'Birth', value: 1 }], category: "SubEmitter" },+ subEmitterTrigger: { enum: [{ label: 'Death', value: 0 }, { label: 'Birth', value: 1 }, { label: 'Collision', value: 2 }], category: "SubEmitter" },subEmitterChance: { min: 0, max: 1, category: "SubEmitter" },subEmitterInheritVelocity: { min: 0, max: 1, category: "SubEmitter" },subEmitter: { category: "SubEmitter" },@@ -758,6 +765,13 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {trailMinDistance: { min: 0, category: "Trail", shownWhen: { field: "trailEnabled", values: [1] } },collisionEnabled: { category: "Collision" },collisionFloor: { category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },+ collisionMode: { enum: [{ label: 'Floor', value: 0 }, { label: 'Physics2D', value: 1 }, { label: 'Physics3D', value: 2 }], category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },+ collisionMask: { min: 0, max: 65535, step: 1, category: "Collision", bitmask: { source: "collisionLayers" }, shownWhen: { field: "collisionEnabled", values: [1] } },+ collisionQueryBudget: { min: 0, max: 4096, step: 1, category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },+ collisionMaxDistance: { min: 0, category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },+ collisionFallback: { enum: [{ label: 'Floor', value: 0 }, { label: 'Skip', value: 1 }], category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },+ collisionEvents: { category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },+ collisionEventBudget: { min: 0, max: 1024, step: 1, category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },collisionBounce: { min: 0, max: 1, category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },collisionFriction: { min: 0, max: 1, category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },collisionLifetimeLoss: { min: 0, max: 1, category: "Collision", shownWhen: { field: "collisionEnabled", values: [1] } },@@ -1583,6 +1597,13 @@ export interface ParticleEmitterData {trailMinDistance: number;collisionEnabled: boolean;collisionFloor: number;+ collisionMode: ParticleCollisionMode;+ collisionMask: number;+ collisionQueryBudget: number;+ collisionMaxDistance: number;+ collisionFallback: ParticleCollisionFallback;+ collisionEvents: boolean;+ collisionEventBudget: number;collisionBounce: number;collisionFriction: number;collisionLifetimeLoss: number;diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex 51b544d7d..dfdc4094a 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -28,7 +28,7 @@ import type {// C++ enum and the editor dropdowns derive from the same values. ScaleMode's// canonical values come from CanvasScaleMode (only its Cocos-compat aliases// ShowAll/NoBorder are TS-side).-import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, SpriteMaskInteraction, SpriteDrawMode } from '../wasm/wasm.generated';+import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, SpriteMaskInteraction, SpriteDrawMode } from '../wasm/wasm.generated';import { BlendMode } from '../render/blend';import { getDefaultContext } from './context';import type {@@ -1167,7 +1167,7 @@ export const TilemapLayer = defineBuiltin<TilemapLayerData>('TilemapLayer',// EmitterShape, SimulationSpace and ParticleEasing are re-exported from the// generated module (see the import at the top) — single-sourced from their C++// ES_ENUMs beside the component fields that serialize them.-export { ParticleEasing };+export { ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback };// =============================================================================// ParticleEmitter Componentdiff --git a/sdk/src/particle/ParticleAPI.ts b/sdk/src/particle/ParticleAPI.tsindex 0dae80ed9..87c63e952 100644--- a/sdk/src/particle/ParticleAPI.ts+++ b/sdk/src/particle/ParticleAPI.ts@@ -4,6 +4,8 @@ import type { CppRegistry } from '../wasm';import type { EngineApi } from '../ecs/bridge/engineApi';import type { Entity } from '../types';import { defineResource } from '../ecs/resource';+import { ParticleCollisionBridge, type ParticleQueryResolver } from './ParticleCollisionBridge';+import type { ParticleCollisionBudget, ParticleCollisionEventPayload, ParticleCollisionStats } from './collision';/*** Per-app particle API. Wraps the C++ registry-scoped particle system@@ -16,18 +18,39 @@ import { defineResource } from '../ecs/resource';export class ParticleAPI {private readonly module_: NonNullable<EngineApi>;private readonly registry_: CppRegistry;+ private readonly collisions_: ParticleCollisionBridge;/** @param module whichever engine core is present — the wasm module on the web,* the native host's bindings on a device (see ecs/engineApi.ts). */- constructor(module: NonNullable<EngineApi>, registry: CppRegistry) {+ constructor(module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver) {this.module_ = module;this.registry_ = registry;+ this.collisions_ = new ParticleCollisionBridge(module,registry,resolve);}update(dt: number): void {- this.module_.particle_update?.(this.registry_, dt);+ this.collisions_.update(dt);}+ /** Contacts published by the last completed update, in project world units. */+ get collisionEvents(): readonly ParticleCollisionEventPayload[] { return this.collisions_.events; }+ /** Per-emitter counters from the last update, including fallback reasons. */+ get collisionStats(): readonly ParticleCollisionStats[] { return this.collisions_.stats; }+ /** Provider errors are visible alongside the unavailable/fallback counters. */+ get collisionError(): string | null { return this.collisions_.error; }+ /** Global App caps, independent of each emitter's smaller limits. */+ setCollisionBudget(budget: Partial<ParticleCollisionBudget>): void {+ for (const key of ['queries','events'] as const) {+ const value=budget[key];+ if (value!==undefined) this.collisions_.budget[key]=Number.isFinite(value)?Math.max(0,Math.min(key==='queries'?65536:16384,Math.floor(value))):0;+ }+ }+ /** Draw bounded hit normals without enabling gameplay collision events. */+ get debugNormals(): boolean { return this.collisions_.debug; }+ set debugNormals(enabled: boolean) { this.collisions_.debug=enabled; }+ /** @internal */+ get collisionContacts(): readonly ParticleCollisionEventPayload[] { return this.collisions_.contacts; }+play(entity: Entity): void {this.module_.particle_play?.(this.registry_, entity as number);}diff --git a/sdk/src/particle/ParticleCollisionBridge.ts b/sdk/src/particle/ParticleCollisionBridge.tsnew file mode 100644index 000000000..e0c1bd200--- /dev/null+++ b/sdk/src/particle/ParticleCollisionBridge.ts@@ -0,0 +1,92 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import type { App } from '../app/app';+import type { Entity } from '../types';+import type { EngineApi } from '../ecs/bridge/engineApi';+import type { CppRegistry } from '../wasm';+import type { Physics2DAPI } from '../physics/Physics2D';+import type { Physics3DQueries } from '../physics3d/Physics3DQueries';+import type { ParticleCollisionBudget, ParticleCollisionEventPayload, ParticleCollisionStats } from './collision';++interface Query { mode: number; mask: number; x: number; y: number; z: number; dx: number; dy: number; dz: number }+interface Hit { body: Entity; x: number; y: number; z: number; nx: number; ny: number; nz: number }+/** null is a miss; undefined means unavailable and explicitly invokes the authored fallback. @internal */+export type ParticleQueryResolver = (query: Query) => Hit | null | undefined;+/** No hard dependency on either optional physics plugin. Their existing APIs own unit conversion. @internal */+export function particleQueryResolver(app: App): ParticleQueryResolver {+ return q => {+ if (q.mask === 0) return null;+ if (q.mode === 1) {+ const physics = app.getResourceByName('Physics2D') as Physics2DAPI | null;+ if (!physics) return undefined;+ const length = Math.hypot(q.dx,q.dy);+ if (!length) return null;+ const hits = physics.raycast({x:q.x,y:q.y},{x:q.dx/length,y:q.dy/length},length,q.mask);+ const hit = hits.find(h=>Number.isFinite(h.fraction) && h.fraction>=0 && h.fraction<=1);+ return hit ? {body:hit.entity,x:hit.point.x,y:hit.point.y,z:q.z,nx:hit.normal.x,ny:hit.normal.y,nz:0} : null;+ }+ if (q.mode === 2) {+ const physics = app.getResourceByName('Physics3D') as Physics3DQueries | null;+ if (!physics) return undefined;+ const hit = physics.raycast({x:q.x,y:q.y,z:q.z},{x:q.dx,y:q.dy,z:q.dz},q.mask);+ return hit ? {body:hit.entity,x:hit.x,y:hit.y,z:hit.z,nx:hit.normalX,ny:hit.normalY,nz:hit.normalZ} : null;+ }+ return undefined;+ };+}+/** Same-frame bulk exchange with either a WASM or native core. @internal */+export class ParticleCollisionBridge {+ events: ParticleCollisionEventPayload[] = [];+ contacts: ParticleCollisionEventPayload[] = [];+ debug = false;+ stats: ParticleCollisionStats[] = [];+ error: string | null = null;+ budget: ParticleCollisionBudget = {queries:4096,events:1024};+ private updating_ = false;+ constructor(private readonly engine_: NonNullable<EngineApi>, private readonly registry_: CppRegistry,+ private readonly resolve_?: ParticleQueryResolver) {}+ private read_(count: number, words: number, getter: (()=>number) | undefined, max: number): ArrayBuffer | undefined {+ if (!Number.isInteger(count) || count < 0 || count > max || !getter) return undefined;+ const ptr = getter(), heap = this.engine_.HEAPU8;+ if (!heap || !Number.isSafeInteger(ptr) || ptr % 4 !== 0 || (count>0 && ptr===0) || ptr<0 || ptr + count*words*4 > heap.byteLength) return undefined;+ return heap.slice(ptr,ptr+count*words*4).buffer;+ }+ update(dt: number): void {+ if (this.updating_) throw new Error('Particle.update cannot re-enter during collision queries');+ this.updating_=true;this.events=[];this.contacts=[];this.stats=[];this.error=null;+ const e=this.engine_;+ try {+ e.particle_collisionSetBudget?.(this.budget.queries,this.budget.events,this.debug);+ e.particle_update?.(this.registry_,dt);+ const count=e.particle_collisionQueryCount?.() ?? 0;+ if (count>0 && e.particle_collisionResolve) {+ const queries=this.read_(count,10,e.particle_collisionQueries?.bind(e),65536);+ let ptr=0;+ try {+ if (queries && e._malloc && e._free && e.HEAPU8) ptr=e._malloc(count*32);+ if (ptr && queries) {+ const inputU=new Uint32Array(queries), inputF=new Float32Array(queries);+ const replyBuffer=new ArrayBuffer(count*32), replyU=new Uint32Array(replyBuffer), replyF=new Float32Array(replyBuffer);+ for(let i=0;i<count;i++) {+ const q=i*10,r=i*8;+ let hit:Hit|null|undefined;+ try {hit=this.resolve_?.({mode:inputU[q+2],mask:inputU[q+3],x:inputF[q+4],y:inputF[q+5],z:inputF[q+6],dx:inputF[q+7],dy:inputF[q+8],dz:inputF[q+9]});}+ catch(error){this.error=String(error);hit=undefined;}+ replyU[r]=hit===undefined?2:hit===null?0:1;+ if(hit){replyU[r+1]=hit.body;replyF.set([hit.x,hit.y,hit.z,hit.nx,hit.ny,hit.nz],r+2);}+ }+ // A query provider may grow the engine heap. Acquire the current view only AFTER it returns.+ e.HEAPU8!.set(new Uint8Array(replyBuffer),ptr);+ e.particle_collisionResolve(this.registry_,ptr,count);+ } else e.particle_collisionResolve(this.registry_,0,0);+ } finally {if(ptr)e._free?.(ptr);}+ }+ const eventCount=e.particle_collisionEventCount?.() ?? 0;+ const events=this.read_(eventCount,14,e.particle_collisionEvents?.bind(e),16384);+ if(events){const u=new Uint32Array(events),f=new Float32Array(events);for(let i=0;i<eventCount;i++){const b=i*14;const event={emitter:u[b] as Entity,particle:u[b+1],body:u[b+2] as Entity,mode:u[b+3],x:f[b+4],y:f[b+5],z:f[b+6],normalX:f[b+7],normalY:f[b+8],normalZ:f[b+9],velocityX:f[b+10],velocityY:f[b+11],velocityZ:f[b+12]};this.contacts.push(event);if(u[b+13])this.events.push(event);}}+ const statCount=e.particle_collisionStatsCount?.() ?? 0;+ const stats=this.read_(statCount,10,e.particle_collisionStats?.bind(e),1000000);+ if(stats){const u=new Uint32Array(stats);for(let i=0;i<statCount;i++){const b=i*10;this.stats.push({emitter:u[b] as Entity,queries:u[b+1],hits:u[b+2],budgetSkipped:u[b+3],distanceSkipped:u[b+4],unavailable:u[b+5],events:u[b+6],eventDropped:u[b+7],fallbacks:u[b+8],mode:u[b+9]});}}+ } finally {this.updating_=false;}+ }+}diff --git a/sdk/src/particle/ParticlePlugin.ts b/sdk/src/particle/ParticlePlugin.tsindex 276a0dbae..e8233ae2e 100644--- a/sdk/src/particle/ParticlePlugin.ts+++ b/sdk/src/particle/ParticlePlugin.ts@@ -9,9 +9,17 @@ import type { CppRegistry } from '../wasm';import { engineApi } from '../ecs/bridge/engineApi';import { registerSceneComponentCodec } from '../scene/scene';import { Particle, ParticleAPI } from './ParticleAPI';+import { particleQueryResolver } from './ParticleCollisionBridge';+import { ParticleCollisionEvent, type ParticleCollisionEventPayload } from './collision';+import { EventWriter, type EventWriterInstance } from '../ecs/event';+import { Draw } from '../render/draw';+import { registerScopedDrawCallback, unregisterDrawCallback } from '../render/customDraw';+import { bakeGradient, type Gradient } from './gradient';import { bakeCurve, type Curve } from './curve';+let overlayId = 0;+export class ParticlePlugin implements Plugin {name = 'particle';@@ -19,6 +27,7 @@ export class ParticlePlugin implements Plugin {private readonly gradients_ = new Map<number, Gradient>();/** Entity → authored size-over-life curve (out-of-band; baked to the C++ LUT). */private readonly sizeCurves_ = new Map<number, Curve>();+ private overlay_: string | null = null;private offDespawn_: (() => void) | null = null;build(app: App): void {@@ -28,8 +37,17 @@ export class ParticlePlugin implements Plugin {// the resource, and every call through it no-ops.const engine = engineApi(app) ?? {};const registry = app.world.getCppRegistry() as CppRegistry;- const api = new ParticleAPI(engine, registry);+ const api = new ParticleAPI(engine, registry, particleQueryResolver(app));app.insertResource(Particle, api);+ this.overlay_ = `particle-collision:${++overlayId}`;+ registerScopedDrawCallback(this.overlay_,registry,()=>{+ if (!api.debugNormals) return;+ for (const hit of api.collisionContacts) {+ Draw.line3D({x:hit.x,y:hit.y,z:hit.z},+ {x:hit.x+hit.normalX*20,y:hit.y+hit.normalY*20,z:hit.z+hit.normalZ*20},+ {r:.2,g:.9,b:.7,a:1},1);+ }+ });// The color gradient is authored as stops in the component data but isn't a// C++ field — carry it out-of-band and bake it into the sim's LUT on load.@@ -66,15 +84,18 @@ export class ParticlePlugin implements Plugin {// play mode / standalone runtime (matches animation/physics/timeline).// The FX edit-preview flag is the one authoring exception (env.ts).app.addSystemToSchedule(Schedule.Update, defineSystem(- [Res(Time), Res(Particle)],- (time: TimeData, particle: ParticleAPI) => {+ [Res(Time), Res(Particle), EventWriter(ParticleCollisionEvent)],+ (time: TimeData, particle: ParticleAPI, events: EventWriterInstance<ParticleCollisionEventPayload>) => {particle.update(time.delta);+ for (const hit of particle.collisionEvents) events.send(hit);},{ name: 'ParticleSystem' }), { runIf: fxPreviewOrPlayMode });}cleanup(): void {+ if (this.overlay_) unregisterDrawCallback(this.overlay_);+ this.overlay_ = null;this.offDespawn_?.();this.offDespawn_ = null;this.gradients_.clear();diff --git a/sdk/src/particle/collision.ts b/sdk/src/particle/collision.tsnew file mode 100644index 000000000..baa7bae48--- /dev/null+++ b/sdk/src/particle/collision.ts@@ -0,0 +1,24 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { defineEvent, type EventDef } from '../ecs/event';+import type { Entity } from '../types';++/** A bounded contact in project world units; body is INVALID_ENTITY for a plane. @beta */+export interface ParticleCollisionEventPayload {+ emitter: Entity; particle: number; body: Entity; mode: number;+ x: number; y: number; z: number;+ normalX: number; normalY: number; normalZ: number;+ velocityX: number; velocityY: number; velocityZ: number;+}+/** Read with EventReader; like other engine events, contacts are readable next frame. @beta */+export const ParticleCollisionEvent: EventDef<ParticleCollisionEventPayload> = defineEvent('ParticleCollisionEvent', {+ emitter: 0 as Entity, particle: 0, body: 0xffffffff as Entity, mode: 0,+ x: 0, y: 0, z: 0, normalX: 0, normalY: 1, normalZ: 0, velocityX: 0, velocityY: 0, velocityZ: 0,+});+/** One emitter's latest completed update. Events count accepted notifications/sub-bursts. @beta */+export interface ParticleCollisionStats {+ emitter: Entity; queries: number; hits: number; budgetSkipped: number; distanceSkipped: number;+ unavailable: number; events: number; eventDropped: number; fallbacks: number; mode: number;+}+/** App-wide limits, shared fairly by all scene emitters. Zero disables that work. @beta */+export interface ParticleCollisionBudget { queries: number; events: number }diff --git a/sdk/src/particle/index.ts b/sdk/src/particle/index.tsindex 6fcd8da4d..749cf57cb 100644--- a/sdk/src/particle/index.ts+++ b/sdk/src/particle/index.ts@@ -4,3 +4,4 @@ export { Particle, ParticleAPI } from './ParticleAPI';export { ParticlePlugin, particlePlugin } from './ParticlePlugin';export { bakeGradient, GRADIENT_LUT_SIZE, type Gradient, type GradientStop } from './gradient';export { bakeCurve, type Curve, type Keyframe } from './curve';+export { ParticleCollisionEvent, type ParticleCollisionEventPayload, type ParticleCollisionStats, type ParticleCollisionBudget } from './collision';diff --git a/sdk/src/render/customDraw.ts b/sdk/src/render/customDraw.tsindex 322b42601..065e5b285 100644--- a/sdk/src/render/customDraw.ts+++ b/sdk/src/render/customDraw.ts@@ -16,12 +16,18 @@ export interface DrawFrameInfo {export type DrawCallback = (elapsed: number, frame: DrawFrameInfo) => void;-const callbacks = new Map<string, { fn: DrawCallback; scene: string }>();+type DrawEntry = { fn: DrawCallback; scene: string; registry?: unknown };+const callbacks = new Map<string, DrawEntry>();export function registerDrawCallback(id: string, fn: DrawCallback, scene?: string): void {callbacks.set(id, { fn, scene: scene ?? '' });}+/** An engine-owned overlay belongs to one world's render passes. @internal */+export function registerScopedDrawCallback(id: string, registry: unknown, fn: DrawCallback): void {+ callbacks.set(id,{fn,scene:'',registry});+}+export function unregisterDrawCallback(id: string): void {callbacks.delete(id);}@@ -38,7 +44,7 @@ export function clearSceneDrawCallbacks(sceneName: string): void {}}-export function getDrawCallbacks(): ReadonlyMap<string, { fn: DrawCallback; scene: string }> {+export function getDrawCallbacks(): ReadonlyMap<string, DrawEntry> {return callbacks;}diff --git a/sdk/src/render/renderPipeline.ts b/sdk/src/render/renderPipeline.tsindex b70c934d7..6acf2491f 100644--- a/sdk/src/render/renderPipeline.ts+++ b/sdk/src/render/renderPipeline.ts@@ -204,7 +204,7 @@ export class RenderPipeline {this.runPreFlushCallbacks(registry, viewProjection);Renderer.flush();- this.executeDrawCallbacks(viewProjection, viewport, _elapsed);+ this.executeDrawCallbacks(viewProjection, viewport, _elapsed, registry._cpp);}render(params: RenderParams): void {@@ -330,7 +330,7 @@ export class RenderPipeline {}}- private executeDrawCallbacks(viewProjection: Float32Array, viewport: Viewport, elapsed: number): void {+ private executeDrawCallbacks(viewProjection: Float32Array, viewport: Viewport, elapsed: number, registry: CppRegistry): void {const cbs = getDrawCallbacks();// Plugins register overlays at build time whether one is ever turned on,// and a core with no Draw API has no batch to open — opening one throws@@ -339,6 +339,7 @@ export class RenderPipeline {beginPresentedDraw(viewProjection, viewport.w, viewport.h);const failed: string[] = [];for (const [id, entry] of cbs.entries()) {+ if (entry.registry !== undefined && entry.registry !== registry) continue;if (entry.scene && this.activeScenes_ && !this.activeScenes_.has(entry.scene)) continue;try {entry.fn(elapsed, {diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 6670f5daf..4e82eedf3 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -592,6 +592,14 @@ export interface ESEngineModule {renderer_endScreenOverlay?(targetHandle: number): void;renderer_submitAll(registry: CppRegistry, vpX: number, vpY: number, vpW: number, vpH: number): void;particle_update?(registry: CppRegistry, dt: number): void;+ particle_collisionQueryCount?(): number;+ particle_collisionQueries?(): number;+ particle_collisionEventCount?(): number;+ particle_collisionEvents?(): number;+ particle_collisionStatsCount?(): number;+ particle_collisionStats?(): number;+ particle_collisionResolve?(registry: CppRegistry, ptr: number, count: number): void;+ particle_collisionSetBudget?(queries: number, events: number, debug: boolean): void;particle_play?(registry: CppRegistry, entity: number): void;particle_stop?(registry: CppRegistry, entity: number): void;particle_reset?(registry: CppRegistry, entity: number): void;diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 7820ff4ea..121aa454e 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -357,9 +357,16 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'trailMinDistance', type: 'f32', offset: 244 },{ name: 'collisionEnabled', type: 'bool', offset: 248 },{ name: 'collisionFloor', type: 'f32', offset: 252 },- { name: 'collisionBounce', type: 'f32', offset: 256 },- { name: 'collisionFriction', type: 'f32', offset: 260 },- { name: 'collisionLifetimeLoss', type: 'f32', offset: 264 },+ { 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 },],},ParticleForceField: {diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex 2b382c237..7a9b4996a 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -170,6 +170,27 @@ export enum MaskMode {Stencil = 1,}+/**+ * The engine's `ParticleCollisionFallback`, generated from the C++ enum.+ *+ * @beta+ */+export enum ParticleCollisionFallback {+ Floor = 0,+ Skip = 1,+}++/**+ * The engine's `ParticleCollisionMode`, generated from the C++ enum.+ *+ * @beta+ */+export enum ParticleCollisionMode {+ Floor = 0,+ Physics2D = 1,+ Physics3D = 2,+}+/*** The engine's `ParticleEasing`, generated from the C++ enum.*@@ -244,6 +265,7 @@ export enum SpriteMaskInteraction {export enum SubEmitterTrigger {Death = 0,Birth = 1,+ Collision = 2,}export enum TextAlign {@@ -691,6 +713,13 @@ export interface ParticleEmitter {trailMinDistance: number;collisionEnabled: boolean;collisionFloor: number;+ collisionMode: number;+ collisionMask: number;+ collisionQueryBudget: number;+ collisionMaxDistance: number;+ collisionFallback: number;+ collisionEvents: boolean;+ collisionEventBudget: number;collisionBounce: number;collisionFriction: number;collisionLifetimeLoss: number;diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex 80be1a570..11ac49303 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -584,6 +584,46 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"collisionEnabled": {"category": "Collision",},+ "collisionEventBudget": {+ "category": "Collision",+ "max": 1024,+ "min": 0,+ "shownWhen": {+ "field": "collisionEnabled",+ "values": [+ 1,+ ],+ },+ "step": 1,+ },+ "collisionEvents": {+ "category": "Collision",+ "shownWhen": {+ "field": "collisionEnabled",+ "values": [+ 1,+ ],+ },+ },+ "collisionFallback": {+ "category": "Collision",+ "enum": [+ {+ "label": "Floor",+ "value": 0,+ },+ {+ "label": "Skip",+ "value": 1,+ },+ ],+ "shownWhen": {+ "field": "collisionEnabled",+ "values": [+ 1,+ ],+ },+ },"collisionFloor": {"category": "Collision","shownWhen": {@@ -615,6 +655,66 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho],},},+ "collisionMask": {+ "bitmask": {+ "source": "collisionLayers",+ },+ "category": "Collision",+ "max": 65535,+ "min": 0,+ "shownWhen": {+ "field": "collisionEnabled",+ "values": [+ 1,+ ],+ },+ "step": 1,+ },+ "collisionMaxDistance": {+ "category": "Collision",+ "min": 0,+ "shownWhen": {+ "field": "collisionEnabled",+ "values": [+ 1,+ ],+ },+ },+ "collisionMode": {+ "category": "Collision",+ "enum": [+ {+ "label": "Floor",+ "value": 0,+ },+ {+ "label": "Physics2D",+ "value": 1,+ },+ {+ "label": "Physics3D",+ "value": 2,+ },+ ],+ "shownWhen": {+ "field": "collisionEnabled",+ "values": [+ 1,+ ],+ },+ },+ "collisionQueryBudget": {+ "category": "Collision",+ "max": 4096,+ "min": 0,+ "shownWhen": {+ "field": "collisionEnabled",+ "values": [+ 1,+ ],+ },+ "step": 1,+ },"colorEasing": {"category": "Color","enum": [@@ -875,6 +975,10 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"label": "Birth","value": 1,},+ {+ "label": "Collision",+ "value": 2,+ },],},"texture": {diff --git a/sdk/tests/particle-collision-wasm.test.ts b/sdk/tests/particle-collision-wasm.test.tsnew file mode 100644index 000000000..0a0525225--- /dev/null+++ b/sdk/tests/particle-collision-wasm.test.ts@@ -0,0 +1,39 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import {afterEach,beforeAll,describe,it,expect} from 'vitest';+import {App} from '../src/app/app';+import {Transform,ParticleEmitter} from '../src/ecs/component';+import {Particle,ParticlePlugin} from '../src/particle';+import {ParticleCollisionEvent,type ParticleCollisionEventPayload} from '../src/particle/collision';+import {EventReader,type EventReaderInstance} from '../src/ecs/event';+import {defineSystem,Schedule} from '../src/ecs/system';+import {Physics2DPlugin} from '../src/physics/Physics2DPlugin';+import {Physics2DRuntime} from '../src/physics/Physics2DRuntime';+import {RigidBody2D,BoxCollider2D,BodyType} from '../src/physics/PhysicsComponents';+import type {PhysicsWasmModule} from '../src/physics/PhysicsModuleLoader';+import {Physics3DPlugin,Physics3DRuntime} from '../src/physics3d/Physics3DPlugin';+import {RigidBody3D,BoxCollider3D} from '../src/physics3d/Physics3DComponents';+import type {Physics3DWasmModule} from '../src/physics3d/Physics3DModule';+import type {ESEngineModule} from '../src/wasm';+import {HAS_WASM,hasSideModule,loadSideModule,loadWasmModule} from './helpers/loadWasm';+let engine:ESEngineModule;const apps:App[]=[];+afterEach(()=>{for(const app of apps.splice(0))app.quit()});+describe.skipIf(!HAS_WASM||!hasSideModule('physics')||!hasSideModule('physics3d'))('particle scene collision through actual core / Box2D / Jolt WASM',()=>{+ beforeAll(async()=>{engine=await loadWasmModule()});+ it.each([1,2])('casts fast particles across a thin wall and publishes world-unit events (mode=%i)',async mode=>{+ const app=App.new();apps.push(app);app.connectCpp(new engine.Registry(),engine,{ownedRegistry:true});+ if(mode===1){const module=await loadSideModule<PhysicsWasmModule>('physics');app.addPlugin(new Physics2DPlugin('',{gravity:{x:0,y:0}},async()=>module));await app.getResource(Physics2DRuntime).initPromise;}+ else{const module=await loadSideModule<Physics3DWasmModule>('physics3d');app.addPlugin(new Physics3DPlugin('',{gravity:{x:0,y:0,z:0}},async()=>module));await app.getResource(Physics3DRuntime).initPromise;}+ app.addPlugin(new ParticlePlugin());const world=app.world,wall=world.spawn();world.insert(wall,Transform,{position:{x:100,y:0,z:0}});+ if(mode===1){world.insert(wall,RigidBody2D,{bodyType:BodyType.Static});world.insert(wall,BoxCollider2D,{halfExtents:{x:.05,y:2}});}+ else{world.insert(wall,RigidBody3D,{bodyType:0});world.insert(wall,BoxCollider3D,{halfExtents:{x:5,y:200,z:200}});}+ const received:ParticleCollisionEventPayload[]=[];+ app.addSystemToSchedule(Schedule.Update,defineSystem([EventReader(ParticleCollisionEvent)],(reader:EventReaderInstance<ParticleCollisionEventPayload>)=>{for(const hit of reader)received.push(hit)},{name:'ReadParticleContacts'}));+ await app.stepFrames(2,1/30);+ const emitter=world.spawn();world.insert(emitter,Transform,{rotation:{x:0,y:0,z:-Math.SQRT1_2,w:Math.SQRT1_2}});+ world.insert(emitter,ParticleEmitter,{shape:0,angleSpreadMin:90,angleSpreadMax:90,rate:0,burstCount:1,burstInterval:100,maxParticles:4,lifetimeMin:2,lifetimeMax:2,speedMin:60000,speedMax:60000,gravity:{x:0,y:0,z:0},collisionEnabled:true,collisionMode:mode,collisionFallback:1,collisionEvents:true,collisionBounce:1,collisionMask:65535});+ await app.stepFrames(3,1/60);+ const hit=received.find(h=>h.emitter===emitter);expect(hit).toBeDefined();expect(hit!.body).toBe(wall);expect(hit!.x).toBeCloseTo(95,1);expect(hit!.normalX).toBeLessThan(-.99);expect(hit!.velocityX).toBeCloseTo(60000,0);expect(hit!.mode).toBe(mode);+ expect(app.getResource(Particle).collisionError).toBeNull();+ });+});diff --git a/sdk/tests/particle-collision.test.ts b/sdk/tests/particle-collision.test.tsnew file mode 100644index 000000000..e8681e4f7--- /dev/null+++ b/sdk/tests/particle-collision.test.ts@@ -0,0 +1,82 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+import { expect, it, vi } from 'vitest';+import { ParticleAPI } from '../src/particle/ParticleAPI';+import { particleQueryResolver } from '../src/particle/ParticleCollisionBridge';+import type { EngineApi } from '../src/ecs/bridge/engineApi';+import type { CppRegistry } from '../src/wasm';+import type { App } from '../src/app/app';+import type { Entity } from '../src/types';+function engineFixture() {+ const memory=new WebAssembly.Memory({initial:1,maximum:4});let count=1,eventCount=0;+ const engine={get HEAPU8(){return new Uint8Array(memory.buffer)},get HEAPF32(){return new Float32Array(memory.buffer)},+ _malloc:vi.fn(()=>16384),_free:vi.fn(),particle_collisionSetBudget:vi.fn(),particle_update:vi.fn(),+ particle_collisionQueryCount:()=>count,particle_collisionQueries:()=>128,+ particle_collisionEventCount:()=>eventCount,particle_collisionEvents:()=>4096,+ particle_collisionStatsCount:()=>0,particle_collisionStats:()=>8192,+ particle_collisionResolve:vi.fn((_registry:unknown,ptr:number,n:number)=>{+ count=0;if(!ptr||!n)return;+ const u=new Uint32Array(memory.buffer),f=new Float32Array(memory.buffer);const r=ptr/4;+ if(u[r]!==1)return;+ eventCount=1;u.set([0xf0012345,7,u[r+1],2],1024);f.set([f[r+2],f[r+3],f[r+4],f[r+5],f[r+6],f[r+7],10,0,0],1028);u[1037]=1;+ }),+ };+ const u=new Uint32Array(memory.buffer),f=new Float32Array(memory.buffer);+ u.set([0xf0012345,7,2,65535],32);f.set([0,0,0,10,0,0],36);+ return {engine:engine as unknown as EngineApi,raw:engine,memory};+}+it('copies the query batch before providers grow WASM memory and preserves integer IDs',()=>{+ const {engine,raw,memory}=engineFixture();+ const api=new ParticleAPI(engine,{} as CppRegistry,q=>{+ memory.grow(1);expect(q.dx).toBe(10);expect(q.mask).toBe(65535);+ return {body:0xf1234567 as Entity,x:2,y:0,z:0,nx:-1,ny:0,nz:0};+ });+ api.update(.1);expect(raw._free).toHaveBeenCalledWith(16384);+ expect(api.collisionEvents[0]).toMatchObject({emitter:0xf0012345,body:0xf1234567,x:2,normalX:-1,velocityX:10});+});+it('separates a valid miss from an unavailable provider',()=>{+ for(const [hit,status] of [[null,0],[undefined,2]] as const){+ const {engine,raw,memory}=engineFixture();const api=new ParticleAPI(engine,{} as CppRegistry,()=>hit);+ api.update(.1);expect(new Uint32Array(memory.buffer)[4096]).toBe(status);expect(raw.particle_collisionResolve).toHaveBeenCalledOnce();+ }+});+it('records query errors and still completes the batch through authored fallback',()=>{+ const {engine,memory}=engineFixture();const api=new ParticleAPI(engine,{} as CppRegistry,()=>{throw Error('physics offline')});+ api.update(.1);expect(api.collisionError).toContain('physics offline');expect(new Uint32Array(memory.buffer)[4096]).toBe(2);+});+it('rejects recursive update without corrupting the pending batch',()=>{+ const {engine}=engineFixture();const api=new ParticleAPI(engine,{} as CppRegistry,()=>{api.update(.1);return null});+ api.update(.1);expect(api.collisionError).toContain('cannot re-enter');+});+it('cleans up the reply allocation even when the core rejects the resolve',()=>{+ const {engine,raw}=engineFixture();raw.particle_collisionResolve.mockImplementation(()=>{throw Error('reject')});+ const api=new ParticleAPI(engine,{} as CppRegistry,()=>null);expect(()=>api.update(.1)).toThrow('reject');expect(raw._free).toHaveBeenCalledOnce();+});+it('explicitly finishes malformed or unallocatable batches as unavailable',()=>{+ const {engine,raw}=engineFixture();raw._malloc.mockReturnValue(0);+ new ParticleAPI(engine,{} as CppRegistry).update(.1);expect(raw.particle_collisionResolve).toHaveBeenCalledWith({},0,0);+ const malformed=engineFixture();malformed.raw.particle_collisionQueries=()=>65532;+ new ParticleAPI(malformed.engine,{} as CppRegistry).update(.1);+ expect(malformed.raw._malloc).not.toHaveBeenCalled();+ expect(malformed.raw.particle_collisionResolve).toHaveBeenCalledWith({},0,0);+});+it('keeps budgets, contacts and provider state isolated per API',()=>{+ const first=engineFixture(),second=engineFixture();const a=new ParticleAPI(first.engine,{} as CppRegistry),b=new ParticleAPI(second.engine,{} as CppRegistry);+ a.setCollisionBudget({queries:-1,events:Infinity});a.debugNormals=true;a.update(.1);b.update(.1);+ expect(first.raw.particle_collisionSetBudget).toHaveBeenCalledWith(0,0,true);expect(second.raw.particle_collisionSetBudget).toHaveBeenCalledWith(4096,1024,false);+ expect(a.collisionEvents).not.toBe(b.collisionEvents);+});+it('adapts 2D unit-direction/distance and 3D displacement without converting units twice',()=>{+ const ray2=vi.fn(()=>[{entity:5,point:{x:1,y:2},normal:{x:-1,y:0},fraction:.2}]);+ const ray3=vi.fn(()=>({entity:8,x:1,y:2,z:3,normalX:0,normalY:0,normalZ:-1}));+ const app={getResourceByName:(name:string)=>name==='Physics2D'?{raycast:ray2}:{raycast:ray3}} as unknown as App;+ const resolve=particleQueryResolver(app);+ const q={mode:1,mask:3,x:10,y:20,z:17,dx:3,dy:4,dz:5};+ expect(resolve(q)).toMatchObject({body:5,z:17,nz:0});expect(ray2).toHaveBeenCalledWith({x:10,y:20},{x:.6,y:.8},5,3);+ expect(resolve({...q,mode:2})).toMatchObject({body:8,z:3});expect(ray3).toHaveBeenCalledWith({x:10,y:20,z:17},{x:3,y:4,z:5},3);+});+it('supports missing optional physics modules and an explicit empty layer mask',()=>{+ const resolve=particleQueryResolver({getResourceByName:()=>null} as unknown as App);+ const q={mode:1,mask:65535,x:0,y:0,z:0,dx:1,dy:0,dz:0};+ expect(resolve(q)).toBeUndefined();expect(resolve({...q,mode:2})).toBeUndefined();expect(resolve({...q,mask:0})).toBeNull();+});diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex f98f2da10..dd50f672f 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 0687add0b330ecdc+ * @schema_hash 6d39e5df3d1dc9e7*/-#define ES_EDITOR_API_SCHEMA_HASH "0687add0b330ecdc"+#define ES_EDITOR_API_SCHEMA_HASH "6d39e5df3d1dc9e7"#include <emscripten/bind.h>#include <string>@@ -483,6 +483,13 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"trailMinDistance","type":"float","group":"ParticleEmitter"},{"key":"collisionEnabled","type":"bool","group":"ParticleEmitter"},{"key":"collisionFloor","type":"float","group":"ParticleEmitter"},+ {"key":"collisionMode","type":"int","group":"ParticleEmitter"},+ {"key":"collisionMask","type":"int","group":"ParticleEmitter"},+ {"key":"collisionQueryBudget","type":"int","group":"ParticleEmitter"},+ {"key":"collisionMaxDistance","type":"float","group":"ParticleEmitter"},+ {"key":"collisionFallback","type":"int","group":"ParticleEmitter"},+ {"key":"collisionEvents","type":"bool","group":"ParticleEmitter"},+ {"key":"collisionEventBudget","type":"int","group":"ParticleEmitter"},{"key":"collisionBounce","type":"float","group":"ParticleEmitter"},{"key":"collisionFriction","type":"float","group":"ParticleEmitter"},{"key":"collisionLifetimeLoss","type":"float","group":"ParticleEmitter"}@@ -1436,6 +1443,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::selse if (field == "trailWidth") { c.trailWidth = value; }else if (field == "trailMinDistance") { c.trailMinDistance = value; }else if (field == "collisionFloor") { c.collisionFloor = value; }+ else if (field == "collisionMaxDistance") { c.collisionMaxDistance = value; }else if (field == "collisionBounce") { c.collisionBounce = value; }else if (field == "collisionFriction") { c.collisionFriction = value; }else if (field == "collisionLifetimeLoss") { c.collisionLifetimeLoss = value; }@@ -1944,6 +1952,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "trailWidth") { return c.trailWidth; }else if (field == "trailMinDistance") { return c.trailMinDistance; }else if (field == "collisionFloor") { return c.collisionFloor; }+ else if (field == "collisionMaxDistance") { return c.collisionMaxDistance; }else if (field == "collisionBounce") { return c.collisionBounce; }else if (field == "collisionFriction") { return c.collisionFriction; }else if (field == "collisionLifetimeLoss") { return c.collisionLifetimeLoss; }@@ -2306,6 +2315,11 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::strelse if (field == "subEmitterTrigger") { c.subEmitterTrigger = static_cast<i32>(value); }else if (field == "subEmitter") { c.subEmitter = static_cast<u32>(value); }else if (field == "trailPoints") { c.trailPoints = static_cast<i32>(value); }+ else if (field == "collisionMode") { c.collisionMode = static_cast<i32>(value); }+ else if (field == "collisionMask") { c.collisionMask = static_cast<u32>(value); }+ else if (field == "collisionQueryBudget") { c.collisionQueryBudget = static_cast<i32>(value); }+ else if (field == "collisionFallback") { c.collisionFallback = static_cast<i32>(value); }+ else if (field == "collisionEventBudget") { c.collisionEventBudget = static_cast<i32>(value); }else { return false; }return true;} else if (comp == "ParticleForceField") {@@ -2553,6 +2567,11 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::strielse if (field == "subEmitterTrigger") { return static_cast<i32>(c.subEmitterTrigger); }else if (field == "subEmitter") { return static_cast<i32>(c.subEmitter); }else if (field == "trailPoints") { return static_cast<i32>(c.trailPoints); }+ else if (field == "collisionMode") { return static_cast<i32>(c.collisionMode); }+ else if (field == "collisionMask") { return static_cast<i32>(c.collisionMask); }+ else if (field == "collisionQueryBudget") { return static_cast<i32>(c.collisionQueryBudget); }+ else if (field == "collisionFallback") { return static_cast<i32>(c.collisionFallback); }+ else if (field == "collisionEventBudget") { return static_cast<i32>(c.collisionEventBudget); }} else if (comp == "ParticleForceField") {if (!reg.has<esengine::ecs::ParticleForceField>(entity)) return 0;const auto& c = reg.get<esengine::ecs::ParticleForceField>(entity);@@ -2796,6 +2815,7 @@ bool editor_setBool(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "enabled") { c.enabled = value; }else if (field == "trailEnabled") { c.trailEnabled = value; }else if (field == "collisionEnabled") { c.collisionEnabled = value; }+ else if (field == "collisionEvents") { c.collisionEvents = value; }else { return false; }return true;} else if (comp == "ParticleForceField") {@@ -3042,6 +3062,7 @@ bool editor_getBool(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "enabled") { return c.enabled; }else if (field == "trailEnabled") { return c.trailEnabled; }else if (field == "collisionEnabled") { return c.collisionEnabled; }+ else if (field == "collisionEvents") { return c.collisionEvents; }} 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/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 991e052de..7429e912e 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -706,9 +706,24 @@ void renderer_submitAll(ecs::Registry& registry, i32 vpX, i32 vpY, i32 vpW, i32#ifdef ES_ENABLE_PARTICLESvoid particle_update(ecs::Registry& registry, f32 dt) {if (!g_particleSystem) return;+ ensureTransformsUpdated(registry);g_particleSystem->update(registry, dt);}+u32 particle_collisionQueryCount() { return g_particleSystem ? static_cast<u32>(g_particleSystem->collisionQueries().size()) : 0; }+uintptr_t particle_collisionQueries() { return g_particleSystem ? reinterpret_cast<uintptr_t>(g_particleSystem->collisionQueries().data()) : 0; }+u32 particle_collisionEventCount() { return g_particleSystem ? static_cast<u32>(g_particleSystem->collisionEvents().size()) : 0; }+uintptr_t particle_collisionEvents() { return g_particleSystem ? reinterpret_cast<uintptr_t>(g_particleSystem->collisionEvents().data()) : 0; }+u32 particle_collisionStatsCount() { return g_particleSystem ? static_cast<u32>(g_particleSystem->collisionStats().size()) : 0; }+uintptr_t particle_collisionStats() { return g_particleSystem ? reinterpret_cast<uintptr_t>(g_particleSystem->collisionStats().data()) : 0; }+void particle_collisionSetBudget(u32 queries, u32 events, bool debug) { if (g_particleSystem) g_particleSystem->setCollisionBudget(queries,events,debug); }+void particle_collisionResolve(ecs::Registry& registry, uintptr_t ptr, u32 count) {+ if (!g_particleSystem) return;+ const u32 expected = static_cast<u32>(g_particleSystem->collisionQueries().size());+ const auto* replies = count == expected && count <= 65536 ? boundarySpan<particle::CollisionReply>(ptr,count,"particle_collisionResolve") : nullptr;+ g_particleSystem->resolveCollisions(registry,replies,replies ? count : 0);+}+// The entity crosses the wasm boundary as a raw u32 (Embind has no registered// binding for esengine::Entity — calling with it throws "unbound types"). Rebuild// the Entity C++-side, matching particle_set_color_lut/set_size_lut below.diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex b58db17ad..63f35301b 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -143,6 +143,17 @@ void renderer_setEntityDrawOrder(ecs::Registry& registry, uintptr_t entitiesPtr,void renderer_submitAll(ecs::Registry& registry, i32 vpX, i32 vpY, i32 vpW, i32 vpH);#ifdef ES_ENABLE_PARTICLESvoid particle_update(ecs::Registry& registry, f32 dt);+u32 particle_collisionQueryCount();+// @heapreturn esengine::particle_collisionQueryCount() * 40+uintptr_t particle_collisionQueries();+u32 particle_collisionEventCount();+// @heapreturn esengine::particle_collisionEventCount() * 56+uintptr_t particle_collisionEvents();+u32 particle_collisionStatsCount();+// @heapreturn esengine::particle_collisionStatsCount() * 40+uintptr_t particle_collisionStats();+void particle_collisionResolve(ecs::Registry& registry, uintptr_t ptr, u32 count);+void particle_collisionSetBudget(u32 queries, u32 events, bool debug);void particle_play(ecs::Registry& registry, u32 entity);void particle_stop(ecs::Registry& registry, u32 entity);void particle_reset(ecs::Registry& registry, u32 entity);diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex c31c44138..053a1a90f 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -201,6 +201,15 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {.value("Scissor", esengine::ecs::MaskMode::Scissor).value("Stencil", esengine::ecs::MaskMode::Stencil);+ enum_<esengine::ecs::ParticleCollisionFallback>("ParticleCollisionFallback")+ .value("Floor", esengine::ecs::ParticleCollisionFallback::Floor)+ .value("Skip", esengine::ecs::ParticleCollisionFallback::Skip);++ enum_<esengine::ecs::ParticleCollisionMode>("ParticleCollisionMode")+ .value("Floor", esengine::ecs::ParticleCollisionMode::Floor)+ .value("Physics2D", esengine::ecs::ParticleCollisionMode::Physics2D)+ .value("Physics3D", esengine::ecs::ParticleCollisionMode::Physics3D);+enum_<esengine::ecs::ParticleEasing>("ParticleEasing").value("Linear", esengine::ecs::ParticleEasing::Linear).value("EaseIn", esengine::ecs::ParticleEasing::EaseIn)@@ -237,7 +246,8 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {enum_<esengine::ecs::SubEmitterTrigger>("SubEmitterTrigger").value("Death", esengine::ecs::SubEmitterTrigger::Death)- .value("Birth", esengine::ecs::SubEmitterTrigger::Birth);+ .value("Birth", esengine::ecs::SubEmitterTrigger::Birth)+ .value("Collision", esengine::ecs::SubEmitterTrigger::Collision);enum_<esengine::ecs::TextAlign>("TextAlign").value("Left", esengine::ecs::TextAlign::Left)@@ -885,6 +895,13 @@ struct ParticleEmitterJS {f32 trailMinDistance;bool collisionEnabled;f32 collisionFloor;+ i32 collisionMode;+ u32 collisionMask;+ i32 collisionQueryBudget;+ f32 collisionMaxDistance;+ i32 collisionFallback;+ bool collisionEvents;+ i32 collisionEventBudget;f32 collisionBounce;f32 collisionFriction;f32 collisionLifetimeLoss;@@ -946,6 +963,13 @@ void particleemitterApplyJS(esengine::ecs::ParticleEmitter& c, const ParticleEmic.trailMinDistance = js.trailMinDistance;c.collisionEnabled = js.collisionEnabled;c.collisionFloor = js.collisionFloor;+ c.collisionMode = js.collisionMode;+ c.collisionMask = js.collisionMask;+ c.collisionQueryBudget = js.collisionQueryBudget;+ c.collisionMaxDistance = js.collisionMaxDistance;+ c.collisionFallback = js.collisionFallback;+ c.collisionEvents = js.collisionEvents;+ c.collisionEventBudget = js.collisionEventBudget;c.collisionBounce = js.collisionBounce;c.collisionFriction = js.collisionFriction;c.collisionLifetimeLoss = js.collisionLifetimeLoss;@@ -1014,6 +1038,13 @@ ParticleEmitterJS particleemitterToJS(const esengine::ecs::ParticleEmitter& c) {js.trailMinDistance = c.trailMinDistance;js.collisionEnabled = c.collisionEnabled;js.collisionFloor = c.collisionFloor;+ js.collisionMode = c.collisionMode;+ js.collisionMask = c.collisionMask;+ js.collisionQueryBudget = c.collisionQueryBudget;+ js.collisionMaxDistance = c.collisionMaxDistance;+ js.collisionFallback = c.collisionFallback;+ js.collisionEvents = c.collisionEvents;+ js.collisionEventBudget = c.collisionEventBudget;js.collisionBounce = c.collisionBounce;js.collisionFriction = c.collisionFriction;js.collisionLifetimeLoss = c.collisionLifetimeLoss;@@ -1830,6 +1861,13 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("trailMinDistance", &ParticleEmitterJS::trailMinDistance).field("collisionEnabled", &ParticleEmitterJS::collisionEnabled).field("collisionFloor", &ParticleEmitterJS::collisionFloor)+ .field("collisionMode", &ParticleEmitterJS::collisionMode)+ .field("collisionMask", &ParticleEmitterJS::collisionMask)+ .field("collisionQueryBudget", &ParticleEmitterJS::collisionQueryBudget)+ .field("collisionMaxDistance", &ParticleEmitterJS::collisionMaxDistance)+ .field("collisionFallback", &ParticleEmitterJS::collisionFallback)+ .field("collisionEvents", &ParticleEmitterJS::collisionEvents)+ .field("collisionEventBudget", &ParticleEmitterJS::collisionEventBudget).field("collisionBounce", &ParticleEmitterJS::collisionBounce).field("collisionFriction", &ParticleEmitterJS::collisionFriction).field("collisionLifetimeLoss", &ParticleEmitterJS::collisionLifetimeLoss);@@ -3549,9 +3587,16 @@ static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 240, "ABIstatic_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, collisionBounce) == 256, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionBounce (EHT expected 256)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFriction) == 260, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFriction (EHT expected 260)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionLifetimeLoss) == 264, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionLifetimeLoss (EHT expected 264)");+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::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)");@@ -3725,7 +3770,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "4a247e158faf0865";+static const char* kEsAbiLayoutHash = "2f29375a9e0f797d";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 8eab45f47..b9876b1e6 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -724,6 +724,14 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("renderer_submitAll", &esengine::renderer_submitAll);#ifdef ES_ENABLE_PARTICLESemscripten::function("particle_update", &esengine::particle_update);+ emscripten::function("particle_collisionQueryCount", &esengine::particle_collisionQueryCount);+ emscripten::function("particle_collisionQueries", &esengine::particle_collisionQueries);+ emscripten::function("particle_collisionEventCount", &esengine::particle_collisionEventCount);+ emscripten::function("particle_collisionEvents", &esengine::particle_collisionEvents);+ emscripten::function("particle_collisionStatsCount", &esengine::particle_collisionStatsCount);+ emscripten::function("particle_collisionStats", &esengine::particle_collisionStats);+ emscripten::function("particle_collisionResolve", &esengine::particle_collisionResolve);+ emscripten::function("particle_collisionSetBudget", &esengine::particle_collisionSetBudget);emscripten::function("particle_play", &esengine::particle_play);emscripten::function("particle_stop", &esengine::particle_stop);emscripten::function("particle_reset", &esengine::particle_reset);diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cppindex 37a1439e2..47a26f95e 100644--- a/src/esengine/core/EstellaContext.cpp+++ b/src/esengine/core/EstellaContext.cpp@@ -64,6 +64,19 @@ void EstellaContext::registerLogicSystems() {// shutdown()+init() cycle clears services_ and re-registers. UISystem is the// membership sentinel for the whole logic-system set.if (services_.getService<ecs::UISystem>()) return;+ // Before the systems that draw from it: a consumer takes its stream at+ // registration, so the seed has to be the engine's before anyone asks.+ auto randomSource = makeUnique<RandomSource>();+ // A seed the SDK set before this context existed (see setPendingRandomSeed).+ if (u32 pending = 0; takePendingRandomSeed(pending)) randomSource->reseed(pending);+ services_.registerOwned<RandomSource>(std::move(randomSource));+#ifdef ES_ENABLE_PARTICLES+ services_.registerOwned<particle::ParticleSystem>(makeUnique<particle::ParticleSystem>());+ services_.getService<particle::ParticleSystem>()->reseedFrom(*services_.getService<RandomSource>());+#endif+ services_.registerOwned<trail::TrailSystem>(makeUnique<trail::TrailSystem>());++services_.registerOwned<ecs::TransformSystem>(makeUnique<ecs::TransformSystem>());services_.registerOwned<ecs::UISystem>(makeUnique<ecs::UISystem>());services_.registerOwned<animation::TweenSystem>(makeUnique<animation::TweenSystem>());@@ -157,18 +170,6 @@ void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {// they are already present.registerLogicSystems();- // Before the systems that draw from it: a consumer takes its stream at- // registration, so the seed has to be the engine's before anyone asks.- auto randomSource = makeUnique<RandomSource>();- // A seed the SDK set before this context existed (see setPendingRandomSeed).- if (u32 pending = 0; takePendingRandomSeed(pending)) randomSource->reseed(pending);- services_.registerOwned<RandomSource>(std::move(randomSource));-#ifdef ES_ENABLE_PARTICLES- services_.registerOwned<particle::ParticleSystem>(makeUnique<particle::ParticleSystem>());- services_.getService<particle::ParticleSystem>()->reseedFrom(*services_.getService<RandomSource>());-#endif- services_.registerOwned<trail::TrailSystem>(makeUnique<trail::TrailSystem>());-auto* rm = services_.getService<resource::ResourceManager>();auto* rc = services_.getService<RenderContext>();auto immediateDraw = makeUnique<ImmediateDraw>(*gfxDevicePtr, *rc, *rm);diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hppindex 998b1f4ee..6b896ede8 100644--- a/src/esengine/ecs/components/ParticleEmitter.hpp+++ b/src/esengine/ecs/components/ParticleEmitter.hpp@@ -39,12 +39,25 @@ enum class SimulationSpace : i32 {};// When a sub-emitter fires the referenced child emitter's burst: as each parent-// particle is born, or as it dies. (Collision joins this list once particle-// collision lands.)+// particle is born, dies, or collides. Serialized values remain stable.ES_ENUM(stability=beta)enum class SubEmitterTrigger : i32 {Death = 0,Birth = 1,+ Collision = 2,+};++ES_ENUM(stability=beta)+enum class ParticleCollisionMode : i32 {+ Floor = 0,+ Physics2D = 1,+ Physics3D = 2,+};++ES_ENUM(stability=beta)+enum class ParticleCollisionFallback : i32 {+ Floor = 0,+ Skip = 1,};ES_COMPONENT(renderable=enabled, stability=beta)@@ -243,16 +256,38 @@ struct ParticleEmitter {ES_PROPERTY(min=0, category=Trail, shown_when=trailEnabled:true)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.+ // Collision is opt-in. Floor remains the default for existing scenes; optional+ // 2D/3D adapters query the swept segment in project world units.ES_PROPERTY(category=Collision)bool collisionEnabled{false};ES_PROPERTY(category=Collision, shown_when=collisionEnabled:true)f32 collisionFloor{0.0f};+ // Scene queries use the same response/events as the legacy plane. Results are+ // exchanged as a bounded batch, so the core depends on no physics backend.+ ES_PROPERTY(enum=ParticleCollisionMode, category=Collision, shown_when=collisionEnabled:true)+ i32 collisionMode{static_cast<i32>(ParticleCollisionMode::Floor)};++ ES_PROPERTY(bitmask_source=collisionLayers, min=0, max=65535, step=1, category=Collision, shown_when=collisionEnabled:true)+ u32 collisionMask{65535};++ ES_PROPERTY(min=0, max=4096, step=1, category=Collision, shown_when=collisionEnabled:true)+ i32 collisionQueryBudget{128};++ // World units from the nearest active camera; 0 means no distance culling.+ ES_PROPERTY(min=0, category=Collision, shown_when=collisionEnabled:true)+ f32 collisionMaxDistance{0.0f};++ ES_PROPERTY(enum=ParticleCollisionFallback, category=Collision, shown_when=collisionEnabled:true)+ i32 collisionFallback{static_cast<i32>(ParticleCollisionFallback::Floor)};++ ES_PROPERTY(category=Collision, shown_when=collisionEnabled:true)+ bool collisionEvents{false};++ ES_PROPERTY(min=0, max=1024, step=1, category=Collision, shown_when=collisionEnabled:true)+ i32 collisionEventBudget{32};+// Restitution: 0 = particles stop dead on the floor, 1 = a full elastic bounce.ES_PROPERTY(min=0, max=1, category=Collision, shown_when=collisionEnabled:true)f32 collisionBounce{0.5f};diff --git a/src/esengine/particle/Particle.cpp b/src/esengine/particle/Particle.cppindex 22a0224d6..1b3509990 100644--- a/src/esengine/particle/Particle.cpp+++ b/src/esengine/particle/Particle.cpp@@ -20,6 +20,8 @@ Particle* ParticlePool::allocate() {free_list_.pop_back();particles_[index] = Particle{};particles_[index].alive = true;+ if (++next_generation_ == 0) ++next_generation_;+ particles_[index].generation = next_generation_;alive_count_++;return &particles_[index];}diff --git a/src/esengine/particle/Particle.hpp b/src/esengine/particle/Particle.hppindex 325838e7a..e394c4c0b 100644--- a/src/esengine/particle/Particle.hpp+++ b/src/esengine/particle/Particle.hpp@@ -25,6 +25,8 @@ struct Particle {glm::vec4 end_color{1.0f, 1.0f, 1.0f, 0.0f};u16 sprite_frame = 0;bool alive = false;+ u32 generation = 0;+ u32 subEmitterDepth = 0;};class ParticlePool {@@ -51,6 +53,7 @@ private:std::vector<u32> free_list_;u32 capacity_;u32 alive_count_ = 0;+ u32 next_generation_ = 0;};} // namespace esengine::particlediff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cppindex 96412f23e..f03f86194 100644--- a/src/esengine/particle/ParticleSystem.cpp+++ b/src/esengine/particle/ParticleSystem.cpp@@ -8,6 +8,7 @@#include <cmath>#include "../core/RandomSource.hpp"+#include "../ecs/components/Camera.hpp"namespace esengine::particle {@@ -19,6 +20,17 @@ void ParticleSystem::reseedFrom(const esengine::RandomSource& source) {}void ParticleSystem::update(ecs::Registry& registry, f32 dt) {+ collision_queries_.clear(); collision_pending_.clear(); collision_events_.clear();+ collision_stats_.clear(); collision_cameras_.clear();+ event_attempts_ = 0; collision_child_bursts_ = 0;+ if (!std::isfinite(dt) || dt < 0) return;+ auto cameras = registry.activeView<ecs::Camera, ecs::Transform>();+ for (auto entity : cameras) {+ if (!cameras.get<ecs::Camera>(entity).isActive) continue;+ auto& transform = cameras.get<ecs::Transform>(entity);+ transform.ensureDecomposed();+ collision_cameras_.push_back(transform.worldPosition);+ }if (!destroyConn_.isConnected()) {destroyConn_ = registry.onDestroy([this](Entity entity) {states_.erase(entity);@@ -52,6 +64,20 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {}auto view = registry.activeView<ecs::Transform, ecs::ParticleEmitter>();+ // Share the App cap across active scene emitters. Rotate remainder slots so+ // a budget smaller than the emitter count never permanently starves a tail.+ collision_quotas_.clear();+ std::vector<Entity> sceneEmitters;+ for (auto entity : view) {+ const auto& e = view.get<ecs::ParticleEmitter>(entity);+ if (e.enabled && e.collisionEnabled && e.collisionMode != 0) sceneEmitters.push_back(entity);+ }+ const u32 n = static_cast<u32>(sceneEmitters.size());+ for (u32 i = 0; i < n; ++i) {+ const u32 rank = (i + n - collision_frame_ % n) % n;+ collision_quotas_[sceneEmitters[i]] = query_budget_ / n + (rank < query_budget_ % n ? 1u : 0u);+ }+ ++collision_frame_;for (auto entity : view) {const auto& emitter = view.get<ecs::ParticleEmitter>(entity);const auto& transform = view.get<ecs::Transform>(entity);@@ -130,6 +156,13 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {bool isWorldSpace = emitter.simulationSpace ==static_cast<i32>(ecs::SimulationSpace::World);+ collision_emitter_ = entity;+ collision_stats_index_ = collision_stats_.size();+ if (emitter.collisionEnabled) {+ CollisionStats stats; stats.emitter = entity.raw;+ stats.mode = static_cast<u32>(emitter.collisionMode);+ collision_stats_.push_back(stats);+ }auto lutIt = colorLuts_.find(entity);auto sizeIt = sizeLuts_.find(entity);auto speedIt = speedLuts_.find(entity);@@ -139,9 +172,14 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {speedIt != speedLuts_.end() ? &speedIt->second : nullptr,frame, isWorldSpace);+ if (state.pool.capacity() > 0) {+ const u32 step = std::max(1u, std::min(static_cast<u32>(std::clamp(emitter.collisionQueryBudget, 0, 4096)), collision_quotas_[entity]));+ state.collisionCursor = (state.collisionCursor + step) % std::max(1u,state.pool.aliveCount());+ }+// Fire the child sub-emitter's burst at every birth/death queued this frame.if (emitter.subEmitter != 0 && !subemit_requests_.empty()) {- drainSubEmitters(registry, Entity::fromRaw(emitter.subEmitter),+ drainSubEmitters(registry, entity, Entity::fromRaw(emitter.subEmitter),emitter.subEmitterInheritVelocity, emitter.subEmitterChance);}}@@ -255,7 +293,8 @@ void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState& state,const EmitterFrame& frame, bool isWorldSpace,- glm::vec3 velocityBias, u32 count, bool allowBirthTrigger) {+ glm::vec3 velocityBias, u32 count, bool allowBirthTrigger, u32 depth,+ const EmitterFrame* storageFrame) {// Record each spawned particle for a Birth-triggered sub-emitter (in world// space, since a sub-burst is a world event).bool recordBirth = allowBirthTrigger &&@@ -309,17 +348,23 @@ void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState&p->velocity = dir * speed + velocityBias;p->sprite_frame = 0;+ p->subEmitterDepth = depth;if (recordBirth) {glm::vec3 worldPos = isWorldSpace ? p->position: frame.position + frame.rotation * p->position;glm::vec3 worldVel = isWorldSpace ? p->velocity : frame.rotation * p->velocity;- subemit_requests_.push_back({worldPos, worldVel});+ subemit_requests_.push_back({worldPos, worldVel, p->subEmitterDepth});+ }+ if (storageFrame) {+ const auto inverseRotation = glm::inverse(storageFrame->rotation);+ p->position = inverseRotation * (p->position - storageFrame->position);+ p->velocity = inverseRotation * p->velocity;}}}-void ParticleSystem::drainSubEmitters(ecs::Registry& registry, Entity child,+void ParticleSystem::drainSubEmitters(ecs::Registry& registry, Entity parent, Entity child,f32 inheritVelocity, f32 chance) {// Take ownership of the queue up front: emitInto below spawns into the child// with allowBirthTrigger=false, so it never re-enters this buffer, but swapping@@ -327,7 +372,7 @@ void ParticleSystem::drainSubEmitters(ecs::Registry& registry, Entity child,std::vector<SubEmitRequest> requests;requests.swap(subemit_requests_);- if (!registry.valid(child) || !registry.has<ecs::ParticleEmitter>(child)) {+ if (child == parent || !registry.valid(child) || !registry.has<ecs::ParticleEmitter>(child)) {return; // a deleted/retargeted child just drops its bursts}const auto& childEmitter = registry.get<ecs::ParticleEmitter>(child);@@ -341,11 +386,19 @@ void ParticleSystem::drainSubEmitters(ecs::Registry& registry, Entity child,it = insertIt;}EmitterState& childState = it->second;+ EmitterFrame storageFrame;+ const bool local = childEmitter.simulationSpace == static_cast<i32>(ecs::SimulationSpace::Local);+ if (local && registry.has<ecs::Transform>(child)) {+ const auto& transform = registry.get<ecs::Transform>(child);+ storageFrame = {transform.worldPosition, transform.worldRotation, transform.worldScale};+ }// The child's burstCount sizes each sub-burst (fall back to 1 so a misconfigured// template still shows something).u32 count = childEmitter.burstCount > 0 ? static_cast<u32>(childEmitter.burstCount) : 1;+ count = std::min(count, childState.pool.capacity());for (const auto& req : requests) {+ if (req.depth >= 8) continue;if (chance < 1.0f && randomRange(0.0f, 1.0f) >= chance) {continue;}@@ -354,7 +407,8 @@ void ParticleSystem::drainSubEmitters(ecs::Registry& registry, Entity child,// no orientation to inherit.emitInto(childEmitter, childState, EmitterFrame{req.position, glm::quat(1, 0, 0, 0),glm::vec3(1.0f)}, /*isWorldSpace=*/true,- req.velocity * inheritVelocity, count, /*allowBirthTrigger=*/false);+ req.velocity * inheritVelocity, count, /*allowBirthTrigger=*/false, req.depth + 1,+ local ? &storageFrame : nullptr);}}@@ -441,9 +495,10 @@ 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;+ bool collisionOn = emitter.collisionEnabled;dead_particle_indices_.clear();+ state.collisionOrdinal = 0;state.pool.forEachAlive([&](Particle& p) {p.age += dt;@@ -453,7 +508,7 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,glm::vec3 worldPos = isWorldSpace ? p.position: frame.position + frame.rotation * p.position;glm::vec3 worldVel = isWorldSpace ? p.velocity : frame.rotation * p.velocity;- subemit_requests_.push_back({worldPos, worldVel});+ subemit_requests_.push_back({worldPos, worldVel, p.subEmitterDepth});}u32 idx = static_cast<u32>(&p - &state.pool.particles()[0]);dead_particle_indices_.push_back(idx);@@ -472,6 +527,7 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,// Applied to the STEP, not to velocity, so speed-over-life cannot become// a second force system: gravity, damping and noise still accumulate into// velocity exactly as before.+ const glm::vec3 collisionFrom = p.position;p.position += p.velocity * (speedLut ? sampleSizeLut(*speedLut, t) : 1.0f) * dt;if (noiseOn) {@@ -483,16 +539,11 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,p.position += glm::vec3(flow, 0.0f) * 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;+ if (collisionOn) {+ collisionStep(emitter, state, p, collisionFrom, frame, isWorldSpace);+ if (p.age >= p.lifetime) {+ dead_particle_indices_.push_back(static_cast<u32>(&p - state.pool.particles().data()));+ return;}}@@ -566,4 +617,132 @@ f32 ParticleSystem::randomRange(f32 min, f32 max) {// An aim in the emitter's own plane: an angle names a direction there, and the// emitter's rotation is what turns the plane. Aiming out of it is the emitter's// job to be turned, not this one's to invent a second angle nobody authored.++namespace {+bool finitePoint(glm::vec3 p) { return std::isfinite(p.x) && std::isfinite(p.y) && std::isfinite(p.z); }+f32 unitValue(f32 x) { return std::isfinite(x) ? std::clamp(x, 0.0f, 1.0f) : 0.0f; }+}++void ParticleSystem::collisionStep(const ecs::ParticleEmitter& emitter, EmitterState& state,+ Particle& p, glm::vec3 from, const EmitterFrame& frame, bool world) {+ const u32 ordinal = state.collisionOrdinal++;+ if (emitter.collisionMode == 0) { floorCollision(emitter, state, p, frame, world); return; }+ auto& stats = collision_stats_[collision_stats_index_];+ auto fallback = [&] {+ if (emitter.collisionFallback == 0) { ++stats.fallbacks; floorCollision(emitter, state, p, frame, world); }+ };+ if (emitter.collisionMode != 1 && emitter.collisionMode != 2) { ++stats.unavailable; fallback(); return; }+ const glm::vec3 start = world ? from : frame.position + frame.rotation * from;+ const glm::vec3 end = world ? p.position : frame.position + frame.rotation * p.position;+ glm::vec3 delta = end - start;+ if (emitter.collisionMode == 1) delta.z = 0; // 2D queries never invent depth.+ if ((emitter.collisionMask & 0xffffu) == 0) return;+ if (!finitePoint(start) || !finitePoint(end) || !std::isfinite(glm::dot(delta,delta)) || glm::dot(delta, delta) < 1e-12f) return;+ if (std::isfinite(emitter.collisionMaxDistance) && emitter.collisionMaxDistance > 0 && !collision_cameras_.empty()) {+ const f32 maxSq = emitter.collisionMaxDistance * emitter.collisionMaxDistance;+ bool near = false;+ for (auto camera : collision_cameras_) {+ const auto offset = end - camera;+ if (glm::dot(offset, offset) <= maxSq) { near = true; break; }+ }+ if (!near) { ++stats.distanceSkipped; fallback(); return; }+ }+ const u32 slot = static_cast<u32>(&p - state.pool.particles().data());+ const u32 limit = std::min(static_cast<u32>(std::clamp(emitter.collisionQueryBudget, 0, 4096)), collision_quotas_[collision_emitter_]);+ const u32 alive = std::max(1u,state.pool.aliveCount());+ const u32 rank = (ordinal + alive - state.collisionCursor % alive) % alive;+ if (rank >= limit || stats.queries >= limit || collision_queries_.size() >= query_budget_) {+ ++stats.budgetSkipped; fallback(); return;+ }+ collision_queries_.push_back({collision_emitter_.raw, slot, static_cast<u32>(emitter.collisionMode),+ emitter.collisionMask & 0xffffu, start.x,start.y,start.z,delta.x,delta.y,delta.z});+ collision_pending_.push_back({collision_emitter_, p.generation, frame, world, collision_stats_index_});+ ++stats.queries;+}++void ParticleSystem::floorCollision(const ecs::ParticleEmitter& emitter, EmitterState& state,+ Particle& p, const EmitterFrame& frame, bool world) {+ const glm::vec3 point = world ? p.position : frame.position + frame.rotation * p.position;+ const glm::vec3 velocity = world ? p.velocity : frame.rotation * p.velocity;+ if (std::isfinite(emitter.collisionFloor) && point.y < emitter.collisionFloor && velocity.y < 0) {+ collide(emitter, state, p, {point.x,emitter.collisionFloor,point.z}, {0,1,0}, 0xffffffffu, frame, world);+ }+}++void ParticleSystem::collide(const ecs::ParticleEmitter& emitter, EmitterState& state, Particle& p,+ glm::vec3 point, glm::vec3 normal, u32 body, const EmitterFrame& frame, bool world) {+ auto& stats = collision_stats_[collision_stats_index_];+ const u32 slot = static_cast<u32>(&p - state.pool.particles().data());+ glm::vec3 velocity = world ? p.velocity : frame.rotation * p.velocity;+ const glm::vec3 incoming = velocity;+ const f32 approach = glm::dot(velocity, normal);+ if (approach < 0) {+ velocity = (velocity - normal * approach) * (1 - unitValue(emitter.collisionFriction))+ - normal * approach * unitValue(emitter.collisionBounce);+ }+ p.position = world ? point : glm::inverse(frame.rotation) * (point - frame.position);+ p.velocity = world ? velocity : glm::inverse(frame.rotation) * velocity;+ p.age += unitValue(emitter.collisionLifetimeLoss) * p.lifetime;+ ++stats.hits;+ const bool child = emitter.subEmitter != 0 && emitter.subEmitterTrigger == static_cast<i32>(ecs::SubEmitterTrigger::Collision);+ if (emitter.collisionEvents || child || collision_debug_) {+ const u32 perEmitter = static_cast<u32>(std::clamp(emitter.collisionEventBudget, 0, 1024));+ if (stats.events < perEmitter && event_attempts_ < event_budget_) {+ ++stats.events; ++event_attempts_;+ if (emitter.collisionEvents || collision_debug_) collision_events_.push_back({collision_emitter_.raw,slot,body,stats.mode,+ point.x,point.y,point.z,normal.x,normal.y,normal.z,incoming.x,incoming.y,incoming.z,emitter.collisionEvents ? 1u : 0u});+ if (child && p.subEmitterDepth < 8 && collision_child_bursts_ < event_budget_) {+ subemit_requests_.push_back({point,velocity,p.subEmitterDepth}); ++collision_child_bursts_;+ }+ } else ++stats.eventDropped;+ }+ if (p.age >= p.lifetime && emitter.subEmitter != 0 && emitter.subEmitterTrigger == static_cast<i32>(ecs::SubEmitterTrigger::Death))+ subemit_requests_.push_back({point,velocity,p.subEmitterDepth});+}++void ParticleSystem::resolveCollisions(ecs::Registry& registry, const CollisionReply* replies, u32 count) {+ // Consume once. A stale/repeated reply cannot bounce a particle twice.+ for (std::size_t i = 0; i < collision_queries_.size(); ++i) {+ const auto& query = collision_queries_[i]; const auto& pending = collision_pending_[i];+ if (!registry.valid(pending.emitter) || !registry.has<ecs::ParticleEmitter>(pending.emitter)) continue;+ auto stateIt = states_.find(pending.emitter);+ if (stateIt == states_.end() || query.slot >= stateIt->second.pool.capacity()) continue;+ auto& state = stateIt->second; auto& p = state.pool.particles()[query.slot];+ if (!p.alive || p.generation != pending.generation) continue;+ const auto& emitter = registry.get<ecs::ParticleEmitter>(pending.emitter);+ if (!emitter.enabled || !emitter.collisionEnabled) continue;+ collision_emitter_ = pending.emitter; collision_stats_index_ = pending.stats;+ auto& stats = collision_stats_[pending.stats];+ const CollisionReply reply = replies && i < count ? replies[i] : CollisionReply{2,0,0,0,0,0,0,0};+ if (reply.status == 1) {+ glm::vec3 normal(reply.nx,reply.ny,reply.nz), point(reply.x,reply.y,reply.z);+ if (query.mode == 1) { normal.z = 0; point.z = pending.world ? p.position.z : (pending.frame.position + pending.frame.rotation * p.position).z; }+ const f32 normSq = glm::dot(normal,normal);+ const glm::vec3 from(query.ox,query.oy,query.oz), delta(query.dx,query.dy,query.dz);+ // A provider must report a finite point on this segment; invalid replies+ // are unavailable queries (same explicit fallback), never teleports.+ const f32 deltaSq = glm::dot(delta,delta);+ const f32 fraction = glm::dot(point - from,delta) / deltaSq;+ glm::vec3 offset = point - (from + delta * fraction);+ if (query.mode == 1) offset.z = 0;+ if (finitePoint(normal) && finitePoint(point) && std::isfinite(normSq) && normSq > 1e-12f &&+ fraction >= -1e-4f && fraction <= 1.0001f && glm::dot(offset,offset) <= std::max(1e-6f,deltaSq*1e-6f)) {+ normal /= std::sqrt(normSq);+ if (glm::dot(delta,normal) > 0) normal = -normal;+ collide(emitter,state,p,point + normal * 1e-4f,normal,reply.body,pending.frame,pending.world);+ } else { ++stats.unavailable; if (emitter.collisionFallback == 0) { ++stats.fallbacks; floorCollision(emitter,state,p,pending.frame,pending.world); } }+ } else if (reply.status != 0) {+ ++stats.unavailable;+ if (emitter.collisionFallback == 0) { ++stats.fallbacks; floorCollision(emitter,state,p,pending.frame,pending.world); }+ }+ if (query.slot < state.trail_count.size() && state.trail_count[query.slot] > 0) {+ const auto last = static_cast<std::size_t>(query.slot)*kMaxTrailPoints + state.trail_count[query.slot]-1;+ state.trail_pos[last] = p.position;+ }+ if (p.age >= p.lifetime) state.pool.deallocateByIndex(query.slot);+ if (!subemit_requests_.empty()) drainSubEmitters(registry,pending.emitter,Entity::fromRaw(emitter.subEmitter),emitter.subEmitterInheritVelocity,emitter.subEmitterChance);+ }+ collision_queries_.clear(); collision_pending_.clear();+}+} // namespace esengine::particlediff --git a/src/esengine/particle/ParticleSystem.hpp b/src/esengine/particle/ParticleSystem.hppindex 43e85e6b2..f8aba8976 100644--- a/src/esengine/particle/ParticleSystem.hpp+++ b/src/esengine/particle/ParticleSystem.hpp@@ -17,6 +17,7 @@#include <functional>#include <random>#include <array>+#include <algorithm>#include "../core/Reflection.hpp"namespace esengine { class RandomSource; }@@ -48,6 +49,28 @@ struct ForceFieldInstance {bool falloff = true;};+// Fixed-width batch records shared by Web and native heaps. Integers keep their+// bits (including generational entity IDs); they are not converted through float.+struct CollisionQuery {+ u32 emitter, slot, mode, mask;+ f32 ox, oy, oz, dx, dy, dz;+};+struct CollisionReply {+ u32 status, body; // 0 miss, 1 hit, 2 backend unavailable+ f32 x, y, z, nx, ny, nz;+};+struct CollisionEvent {+ u32 emitter, slot, body, mode;+ f32 x, y, z, nx, ny, nz, vx, vy, vz;+ u32 publish;+};+struct CollisionStats {+ u32 emitter = 0, queries = 0, hits = 0, budgetSkipped = 0, distanceSkipped = 0;+ u32 unavailable = 0, events = 0, eventDropped = 0, fallbacks = 0, mode = 0;+};+static_assert(sizeof(CollisionQuery) == 40 && sizeof(CollisionReply) == 32);+static_assert(sizeof(CollisionEvent) == 56 && sizeof(CollisionStats) == 40);+struct EmitterState {ParticlePool pool;f32 emission_accumulator = 0.0f;@@ -66,6 +89,8 @@ struct EmitterState {std::vector<glm::vec3> trail_pos;std::vector<u8> trail_count;+ u32 collisionCursor = 0, collisionOrdinal = 0;+explicit EmitterState(u32 capacity) : pool(capacity) {}};@@ -82,6 +107,17 @@ public:void update(ecs::Registry& registry, f32 dt);+ // 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_; }+ const std::vector<CollisionEvent>& collisionEvents() const { return collision_events_; }+ const std::vector<CollisionStats>& collisionStats() const { return collision_stats_; }+ void setCollisionBudget(u32 queries, u32 events, bool debug = false) {+ collision_debug_ = debug;+ query_budget_ = std::min(queries, 65536u); event_budget_ = std::min(events, 16384u);+ }+ void resolveCollisions(ecs::Registry& registry, const CollisionReply* replies, u32 count);+void play(Entity entity);void stop(Entity entity);void reset(Entity entity);@@ -118,25 +154,44 @@ private:// sub-burst's own spawn so a drain can't re-enter the request buffer it's reading.void emitInto(const ecs::ParticleEmitter& emitter, EmitterState& state,const EmitterFrame& frame, bool isWorldSpace,- glm::vec3 velocityBias, u32 count, bool allowBirthTrigger);+ glm::vec3 velocityBias, u32 count, bool allowBirthTrigger, u32 depth = 0,+ const EmitterFrame* storageFrame = nullptr);// Fire the referenced child emitter's burst at each pending sub-emit request.- void drainSubEmitters(ecs::Registry& registry, Entity child,+ void drainSubEmitters(ecs::Registry& registry, Entity parent, Entity child,f32 inheritVelocity, f32 chance);void updateParticles(const ecs::ParticleEmitter& emitter, EmitterState& state, f32 dt,const ColorLut* colorLut, const SizeLut* sizeLut,const SizeLut* speedLut,const EmitterFrame& frame, bool isWorldSpace);+ void collisionStep(const ecs::ParticleEmitter&, EmitterState&, Particle&, glm::vec3 from,+ const EmitterFrame&, bool world);+ void collide(const ecs::ParticleEmitter&, EmitterState&, Particle&, glm::vec3 point,+ glm::vec3 normal, u32 body, const EmitterFrame&, bool world);+ void floorCollision(const ecs::ParticleEmitter&, EmitterState&, Particle&, const EmitterFrame&, bool world);f32 randomRange(f32 min, f32 max);// A parent particle's birth/death position + velocity, queued during a parent's// update and drained into its child sub-emitter right after.- struct SubEmitRequest { glm::vec3 position; glm::vec3 velocity; };+ struct SubEmitRequest { glm::vec3 position; glm::vec3 velocity; u32 depth = 0; };std::vector<SubEmitRequest> subemit_requests_;+ struct PendingCollision { Entity emitter; u32 generation; EmitterFrame frame; bool world; std::size_t stats; };+ std::vector<CollisionQuery> collision_queries_;+ std::vector<PendingCollision> collision_pending_;+ std::vector<CollisionEvent> collision_events_;+ std::vector<CollisionStats> collision_stats_;+ std::vector<glm::vec3> collision_cameras_;+ Entity collision_emitter_{};+ std::size_t collision_stats_index_ = 0;+ u32 query_budget_ = 4096, event_budget_ = 1024, event_attempts_ = 0;+ u32 collision_child_bursts_ = 0;+ u32 collision_frame_ = 0;+ bool collision_debug_ = false;+ std::unordered_map<Entity, u32> collision_quotas_;std::unordered_map<Entity, EmitterState> states_;// A play() that arrives before the emitter's first update (its state isn't// created yet) is remembered here and applied on state creation, not dropped.diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.hindex 00645d192..077a00def 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 0xc9f0e995116b985bULL+#define ES_CONF_EXPECTED_CONTRACT_HASH 0x33ad01505ff01deaULL/* And which BUILD the artifact beside this one is. */#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULLdiff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.cindex d9a444ff5..11a345ed1 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 belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0xc9f0e995116b985bULL+#define ES_ABI_ENGINE_DIGEST 0x33ad01505ff01deaULLES_EXPORT const uint64_t es_abi_hash =ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));diff --git a/tests/particle/test_particle.cpp b/tests/particle/test_particle.cppindex 76f3448d8..4194ae32c 100644--- a/tests/particle/test_particle.cpp+++ b/tests/particle/test_particle.cpp@@ -1432,3 +1432,136 @@ TEST_CASE("shape_cone_direction_within_angle") {});CHECK(allWithinCone);}++// Scene collision is a synchronous two-stage batch: the physics adapters do not+// own integration, responses, event limits or particle lifetime.+static Entity makeSceneCollisionEmitter(ecs::Registry& registry, ParticleSystem& system, i32 mode=2, i32 capacity=4) {+ Entity e=registry.create(); registry.emplace<ecs::Transform>(e);+ auto& emitter=registry.emplace<ecs::ParticleEmitter>(e);+ emitter.rate=0;emitter.burstCount=0;emitter.maxParticles=capacity;+ emitter.gravity=glm::vec3(0);emitter.collisionEnabled=true;emitter.collisionMode=mode;+ emitter.collisionFallback=1;emitter.collisionBounce=.5f;emitter.collisionFriction=.25f;+ emitter.collisionEvents=true;emitter.collisionFloor=-1;+ system.update(registry,0);+ system.getState(e)->collisionCursor=0;+ return e;+}+static Particle* movingParticle(ParticleSystem& system, Entity e, glm::vec3 position={0,0,0}, glm::vec3 velocity={10,2,4}) {+ auto* p=system.getState(e)->pool.allocate();p->lifetime=10;p->position=position;p->velocity=velocity;return p;+}+TEST_CASE("particle_scene_segment_response_and_integer_entity_event") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system);+ auto* p=movingParticle(system,e);system.update(registry,.5f);+ REQUIRE_EQ(system.collisionQueries().size(),1u);+ CHECK_EQ(system.collisionQueries()[0].dx,5);CHECK_EQ(system.collisionQueries()[0].dz,2);+ const CollisionReply hit{1,0xf1234567u,2,.4f,.8f,-1,0,0};system.resolveCollisions(registry,&hit,1);+ CHECK(p->position.x==doctest::Approx(1.9999f));CHECK(p->velocity.x==doctest::Approx(-5));+ CHECK(p->velocity.y==doctest::Approx(1.5f));CHECK(p->velocity.z==doctest::Approx(3));+ REQUIRE_EQ(system.collisionEvents().size(),1u);CHECK_EQ(system.collisionEvents()[0].body,0xf1234567u);+ CHECK_EQ(system.collisionEvents()[0].vx,10);CHECK_EQ(system.collisionStats()[0].hits,1u);+ system.resolveCollisions(registry,&hit,1);CHECK_EQ(system.collisionEvents().size(),1u);+}+TEST_CASE("particle_scene_miss_is_not_unavailable_or_floor_fallback") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system);+ registry.get<ecs::ParticleEmitter>(e).collisionFallback=0;+ auto* p=movingParticle(system,e,{0,0,0},{0,-10,0});system.update(registry,.5f);+ const CollisionReply miss{0,0,0,0,0,0,0,0};system.resolveCollisions(registry,&miss,1);+ CHECK_EQ(p->position.y,-5);CHECK_EQ(system.collisionStats()[0].fallbacks,0u);CHECK_EQ(system.collisionStats()[0].unavailable,0u);+}+TEST_CASE("particle_scene_missing_provider_uses_explicit_floor_fallback") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system);+ registry.get<ecs::ParticleEmitter>(e).collisionFallback=0;+ auto* p=movingParticle(system,e,{0,0,0},{0,-10,0});system.update(registry,.5f);system.resolveCollisions(registry,nullptr,0);+ CHECK_EQ(p->position.y,-1);CHECK_EQ(p->velocity.y,5);CHECK_EQ(system.collisionStats()[0].unavailable,1u);CHECK_EQ(system.collisionStats()[0].fallbacks,1u);+}+TEST_CASE("particle_scene_budget_and_nearest_camera_distance_are_bounded") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system);+ auto& emitter=registry.get<ecs::ParticleEmitter>(e);emitter.collisionQueryBudget=0;+ movingParticle(system,e);system.update(registry,.1f);+ CHECK(system.collisionQueries().empty());CHECK_EQ(system.collisionStats()[0].budgetSkipped,1u);+ emitter.collisionQueryBudget=128;emitter.collisionMaxDistance=1;+ const auto camera=registry.create();registry.emplace<ecs::Camera>(camera).isActive=true;registry.emplace<ecs::Transform>(camera);+ system.getState(e)->pool.particles()[0].position={100,100,0};system.update(registry,.1f);+ CHECK(system.collisionQueries().empty());CHECK_EQ(system.collisionStats()[0].distanceSkipped,1u);+}+TEST_CASE("particle_scene_global_cap_rotates_between_emitters") {+ ecs::Registry registry;ParticleSystem system;+ Entity a=makeSceneCollisionEmitter(registry,system,2,1),b=makeSceneCollisionEmitter(registry,system,2,1);+ movingParticle(system,a);movingParticle(system,b);system.setCollisionBudget(1,32);+ system.update(registry,.1f);REQUIRE_EQ(system.collisionQueries().size(),1u);const auto first=system.collisionQueries()[0].emitter;+ system.resolveCollisions(registry,nullptr,0);system.update(registry,.1f);REQUIRE_EQ(system.collisionQueries().size(),1u);+ CHECK_NE(system.collisionQueries()[0].emitter,first);+}+TEST_CASE("particle_scene_partial_budget_rotates_pool_slots") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system,2,2);+ registry.get<ecs::ParticleEmitter>(e).collisionQueryBudget=1;+ movingParticle(system,e);movingParticle(system,e);system.update(registry,.1f);+ REQUIRE_EQ(system.collisionQueries().size(),1u);const auto first=system.collisionQueries()[0].slot;+ system.resolveCollisions(registry,nullptr,0);system.update(registry,.1f);REQUIRE_EQ(system.collisionQueries().size(),1u);+ CHECK_NE(system.collisionQueries()[0].slot,first);+}+TEST_CASE("particle_scene_2d_retains_particle_depth_and_local_rotation") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system,1);+ auto* p=movingParticle(system,e,{0,0,17},{10,0,5});system.update(registry,.5f);+ REQUIRE_EQ(system.collisionQueries().size(),1u);CHECK_EQ(system.collisionQueries()[0].dz,0);+ const CollisionReply hit{1,5,2,0,0,-1,0,0};system.resolveCollisions(registry,&hit,1);+ CHECK_EQ(p->position.z,19.5f);+ registry.get<ecs::ParticleEmitter>(e).collisionMode=2;+ registry.get<ecs::ParticleEmitter>(e).simulationSpace=static_cast<i32>(ecs::SimulationSpace::Local);+ auto& transform=registry.get<ecs::Transform>(e);transform.worldPosition={10,0,0};+ transform.worldRotation=glm::angleAxis(glm::radians(90.0f),glm::vec3(0,0,1));+ p->position={0,0,0};p->velocity={10,0,0};system.getState(e)->collisionCursor=0;system.update(registry,.5f);+ REQUIRE_EQ(system.collisionQueries().size(),1u);CHECK(system.collisionQueries()[0].dy==doctest::Approx(5));+ const CollisionReply localHit{1,5,10,2,0,0,-1,0};system.resolveCollisions(registry,&localHit,1);+ CHECK(p->position.x==doctest::Approx(1.9999f));CHECK(p->velocity.x==doctest::Approx(-5));+}+TEST_CASE("particle_scene_event_budget_lifetime_and_self_child_are_bounded") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system,2,2);+ auto& emitter=registry.get<ecs::ParticleEmitter>(e);emitter.collisionEventBudget=1;emitter.collisionLifetimeLoss=1;+ emitter.subEmitter=e.raw;emitter.subEmitterTrigger=static_cast<i32>(ecs::SubEmitterTrigger::Collision);+ movingParticle(system,e);movingParticle(system,e);system.update(registry,.5f);+ const CollisionReply hits[2]={{1,5,2,.4f,.8f,-1,0,0},{1,5,2,.4f,.8f,-1,0,0}};system.resolveCollisions(registry,hits,2);+ CHECK_EQ(system.collisionEvents().size(),1u);CHECK_EQ(system.collisionStats()[0].eventDropped,1u);CHECK_EQ(system.aliveCount(e),0u);+}+TEST_CASE("particle_scene_stale_slot_and_invalid_hit_never_teleport") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system);+ movingParticle(system,e);system.update(registry,.5f);system.reset(e);+ auto* p=movingParticle(system,e,{99,0,0});const CollisionReply hit{1,5,2,.4f,.8f,-1,0,0};system.resolveCollisions(registry,&hit,1);+ CHECK_EQ(p->position.x,99);CHECK(system.collisionEvents().empty());+ p->position={0,0,0};system.getState(e)->collisionCursor=0;system.update(registry,.5f);+ const CollisionReply invalid{1,5,1000,1000,1000,0,0,0};system.resolveCollisions(registry,&invalid,1);+ CHECK_EQ(p->position.x,5);CHECK_EQ(system.collisionStats()[0].unavailable,1u);+}+TEST_CASE("particle_scene_debug_contacts_do_not_publish_gameplay_events") {+ ecs::Registry registry;ParticleSystem system;Entity e=makeSceneCollisionEmitter(registry,system);+ registry.get<ecs::ParticleEmitter>(e).collisionEvents=false;system.setCollisionBudget(4096,1024,true);+ movingParticle(system,e);system.update(registry,.5f);const CollisionReply hit{1,5,2,.4f,.8f,-1,0,0};system.resolveCollisions(registry,&hit,1);+ REQUIRE_EQ(system.collisionEvents().size(),1u);CHECK_EQ(system.collisionEvents()[0].publish,0u);+}+TEST_CASE("particle_collision_child_uses_its_local_storage_frame") {+ ecs::Registry registry; ParticleSystem system;+ const Entity parent = makeSceneCollisionEmitter(registry, system);+ const Entity child = registry.create();+ auto& transform = registry.emplace<ecs::Transform>(child);+ transform.worldPosition = {100,20,0};+ transform.worldRotation = glm::angleAxis(glm::radians(90.0f), glm::vec3(0,0,1));+ auto& emitter = registry.emplace<ecs::ParticleEmitter>(child);+ emitter.simulationSpace = static_cast<i32>(ecs::SimulationSpace::Local);+ emitter.rate = 0; emitter.burstCount = 1; emitter.maxParticles = 4;+ emitter.shape = 0; emitter.speedMin = emitter.speedMax = 0;+ auto& source = registry.get<ecs::ParticleEmitter>(parent);+ source.subEmitter = child.raw;+ source.subEmitterTrigger = static_cast<i32>(ecs::SubEmitterTrigger::Collision);+ source.subEmitterInheritVelocity = .5f;+ movingParticle(system, parent); system.update(registry,.5f); system.reset(child);+ const CollisionReply hit{1,5,2,.4f,.8f,-1,0,0};+ system.resolveCollisions(registry,&hit,1);+ REQUIRE_EQ(system.aliveCount(child),1u);+ const auto& spawned = system.getState(child)->pool.particles()[0];+ const auto position = transform.worldPosition + transform.worldRotation * spawned.position;+ const auto velocity = transform.worldRotation * spawned.velocity;+ CHECK(position.x == doctest::Approx(1.9999f));+ CHECK(position.y == doctest::Approx(.4f).epsilon(.0001f));+ CHECK(velocity.x == doctest::Approx(-2.5f));+ CHECK_EQ(spawned.subEmitterDepth,1u);+}diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex e3bf01b79..d805acf65 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,10 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'fix: serialize binaryen optimization on windows': { internal: 'Uses one optimizer worker after wider builds reproduced heap corruption with four; release optimization flags stay unchanged.' },+ 'feat: add budgeted 2d and 3d particle scene collisions': { note: 'Budgeted particle scene collisions.' },+ 'feat(editor): add particle collision authoring and diagnostics': { note: 'Budgeted particle scene collisions.' },+ 'fix: bound binaryen workers on windows': { internal: 'Bounds Windows build-time optimizer workers without changing shipped optimization flags or runtime behavior.' },'fix(editor): align tree and color inspectors with shared Details controls': { note: 'Reusable UI trees and color pickers.' },'fix(editor): adopt consistent tree and color Details': { note: 'Reusable UI trees and color pickers.' },'refactor(ui): distinguish mutation drafts from borrowed reads': { internal: 'Names observed World.update drafts distinctly from borrowed snapshots; runtime behavior and public APIs are unchanged.' },