Skip to content

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

feat: add budgeted 2d and 3d particle scene collisions

yhhf14313f18cb7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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/desktop
index 241a23472..b74cb9fb5 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit 241a2347274cf0265fd4fc50b63b5e47040e70f6
+Subproject commit b74cb9fb5b0b0f10742ad88654a2390162755d44
diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdx
index 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, not
diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdx
index 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.json
index 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.json
index 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.md
index 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), TexHolder
diff --git a/examples/particle-demo/assets/scenes/scene-collisions.esscene b/examples/particle-demo/assets/scenes/scene-collisions.esscene
new file mode 100644
index 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.meta
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.md
index 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: boolean
getAliveCount: (entity: Entity) => number
play: (entity: Entity) => void
reset: (entity: Entity) => void
+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => void
setColorLut: (entity: Entity, lut: Float32Array | null) => void
setSizeLut: (entity: Entity, lut: Float32Array | null) => void
setSpeedLut: (entity: Entity, lut: Float32Array | null) => void
stop: (entity: Entity) => void
update: (dt: number) => void
-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPI
static 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: number
burstInterval: number
collisionBounce: number
collisionEnabled: boolean
+collisionEventBudget: number
+collisionEvents: boolean
+collisionFallback: ParticleCollisionFallback
collisionFloor: number
collisionFriction: number
collisionLifetimeLoss: number
+collisionMask: number
+collisionMaxDistance: number
+collisionMode: ParticleCollisionMode
+collisionQueryBudget: number
colorEasing: ParticleEasing
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
@@ -8690,6 +8758,7 @@ skyUnavailable: SkyUnavailable | null
## SubEmitterTrigger — enum @beta
```
Birth = 1
+Collision = 2
Death = 0
```
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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: boolean
getAliveCount: (entity: Entity) => number
play: (entity: Entity) => void
reset: (entity: Entity) => void
+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => void
setColorLut: (entity: Entity, lut: Float32Array | null) => void
setSizeLut: (entity: Entity, lut: Float32Array | null) => void
setSpeedLut: (entity: Entity, lut: Float32Array | null) => void
stop: (entity: Entity) => void
update: (dt: number) => void
-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPI
static 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: number
burstInterval: number
collisionBounce: number
collisionEnabled: boolean
+collisionEventBudget: number
+collisionEvents: boolean
+collisionFallback: ParticleCollisionFallback
collisionFloor: number
collisionFriction: number
collisionLifetimeLoss: number
+collisionMask: number
+collisionMaxDistance: number
+collisionMode: ParticleCollisionMode
+collisionQueryBudget: number
colorEasing: ParticleEasing
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
@@ -8903,6 +8971,7 @@ skyUnavailable: SkyUnavailable | null
## SubEmitterTrigger — enum @beta
```
Birth = 1
+Collision = 2
Death = 0
```
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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: boolean
getAliveCount: (entity: Entity) => number
play: (entity: Entity) => void
reset: (entity: Entity) => void
+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => void
setColorLut: (entity: Entity, lut: Float32Array | null) => void
setSizeLut: (entity: Entity, lut: Float32Array | null) => void
setSpeedLut: (entity: Entity, lut: Float32Array | null) => void
stop: (entity: Entity) => void
update: (dt: number) => void
-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPI
static 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: number
burstInterval: number
collisionBounce: number
collisionEnabled: boolean
+collisionEventBudget: number
+collisionEvents: boolean
+collisionFallback: ParticleCollisionFallback
collisionFloor: number
collisionFriction: number
collisionLifetimeLoss: number
+collisionMask: number
+collisionMaxDistance: number
+collisionMode: ParticleCollisionMode
+collisionQueryBudget: number
colorEasing: ParticleEasing
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
@@ -8685,6 +8753,7 @@ skyUnavailable: SkyUnavailable | null
## SubEmitterTrigger — enum @beta
```
Birth = 1
+Collision = 2
Death = 0
```
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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: boolean
getAliveCount: (entity: Entity) => number
play: (entity: Entity) => void
reset: (entity: Entity) => void
+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => void
setColorLut: (entity: Entity, lut: Float32Array | null) => void
setSizeLut: (entity: Entity, lut: Float32Array | null) => void
setSpeedLut: (entity: Entity, lut: Float32Array | null) => void
stop: (entity: Entity) => void
update: (dt: number) => void
-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPI
static 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: number
burstInterval: number
collisionBounce: number
collisionEnabled: boolean
+collisionEventBudget: number
+collisionEvents: boolean
+collisionFallback: ParticleCollisionFallback
collisionFloor: number
collisionFriction: number
collisionLifetimeLoss: number
+collisionMask: number
+collisionMaxDistance: number
+collisionMode: ParticleCollisionMode
+collisionQueryBudget: number
colorEasing: ParticleEasing
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
@@ -8978,6 +9046,7 @@ skyUnavailable: SkyUnavailable | null
## SubEmitterTrigger — enum @beta
```
Birth = 1
+Collision = 2
Death = 0
```
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 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, vertexStri
mesh_release: ((meshHandle: number) => void) | undefined
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) | undefined
notifyDeviceLost: ((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) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
particle_reset: ((registry: CppRegistry, entity: number) => void) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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: boolean
getAliveCount: (entity: Entity) => number
play: (entity: Entity) => void
reset: (entity: Entity) => void
+setCollisionBudget: (budget: Partial<ParticleCollisionBudget>) => void
setColorLut: (entity: Entity, lut: Float32Array | null) => void
setSizeLut: (entity: Entity, lut: Float32Array | null) => void
setSpeedLut: (entity: Entity, lut: Float32Array | null) => void
stop: (entity: Entity) => void
update: (dt: number) => void
-static new (module: NonNullable<EngineApi>, registry: CppRegistry): ParticleAPI
+static new (module: NonNullable<EngineApi>, registry: CppRegistry, resolve?: ParticleQueryResolver): ParticleAPI
static 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: number
burstInterval: number
collisionBounce: number
collisionEnabled: boolean
+collisionEventBudget: number
+collisionEvents: boolean
+collisionFallback: ParticleCollisionFallback
collisionFloor: number
collisionFriction: number
collisionLifetimeLoss: number
+collisionMask: number
+collisionMaxDistance: number
+collisionMode: ParticleCollisionMode
+collisionQueryBudget: number
colorEasing: ParticleEasing
colorGradient: { stops: { t: number; color: Color; }[]; }
damping: number
@@ -8692,6 +8760,7 @@ skyUnavailable: SkyUnavailable | null
## SubEmitterTrigger — enum @beta
```
Birth = 1
+Collision = 2
Death = 0
```
diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 Component
diff --git a/sdk/src/particle/ParticleAPI.ts b/sdk/src/particle/ParticleAPI.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.snap
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.cpp
index 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::s
else 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::st
else 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::str
else 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::stri
else 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::st
else 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::st
else 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.cpp
index 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_PARTICLES
void 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.hpp
index 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_PARTICLES
void 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.cpp
index 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 ParticleEmi
c.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, "ABI
static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 244)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 248)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 252)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, 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.cpp
index 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_PARTICLES
emscripten::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.cpp
index 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.hpp
index 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.cpp
index 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.hpp
index 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::particle
diff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cpp
index 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::particle
diff --git a/src/esengine/particle/ParticleSystem.hpp b/src/esengine/particle/ParticleSystem.hpp
index 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.h
index 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 0xc3d0e057d5701a2eULL
diff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.c
index 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 belongs
to the MACHINE, so it mixes in here rather than in the compiler and a
32-bit artifact cannot load into a 64-bit host. */
-#define ES_ABI_ENGINE_DIGEST 0xc9f0e995116b985bULL
+#define ES_ABI_ENGINE_DIGEST 0x33ad01505ff01deaULL
ES_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.cpp
index 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.mjs
index 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.' },