Skip to content

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

feat(particles): simulated and drawn in three dimensions

esenginef7e024c3ffde
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 57e86f402..65f309731 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,28 @@ published separately; it ships inside the editor.
### Changed
+- **Particles are simulated and drawn in three dimensions.** A particle's position
+ and velocity, an emitter's `gravity` and `shapeSize`, and a force field's
+ `direction` are all three-axis now, and the field's zone is a ball rather than a
+ column. The quad is a BILLBOARD: it faces the viewer wherever it is seen from,
+ built from the `viewDirection` helper both shader dialects already had — and
+ head-on under an orthographic camera those axes come out (1,0,0) and (0,1,0),
+ which is the flat quad every 2D scene has always drawn. A billboard is not a
+ second path; the flat quad is the corner of it a 2D scene sits in.
+
+ **Breaking for code, not for data.** `gravity` / `shapeSize` / `direction` are
+ `Vec3` in TypeScript, so `{ x, y }` written in a script no longer type-checks —
+ add `z: 0` for what it meant. Scenes, prefabs and saves already on disk are
+ unaffected: component data is now merged one level into nested objects, so a
+ pair written before the field grew an axis reads back with a zero depth.
+
+ What stayed two-dimensional, and why: the curl-noise field is a flow sampled on
+ the plane a particle is over, an emitter's own rotation is a turn about Z as a
+ flat scene's is, and a trail ribbon is widened in the scene's plane rather than
+ toward the eye (a per-segment billboard is a turn its vertex path has no room
+ for). Emission aims in the emitter's own plane; a 3D emitter is turned, not
+ given a second angle nobody authored.
+
- **`Draggable` is an engine component.** It was a script component, so it never
reached the inspector's reflection table, the scene file or the editor's usual
component list the way engine components do. Its optional bounds changed shape
@@ -67,6 +89,23 @@ published separately; it ships inside the editor.
listed rather than the field name dropped — dropping it to spare the sprite is
what hid the volume.
+- **Component data merges one level into nested objects.** A builtin's fields were
+ laid over their defaults with a shallow spread, so a value the data carried
+ replaced the default whole — and a `{x, y}` written before that field grew a `z`
+ arrived with no depth at all. Not an error, a silent zero: two of the engine's
+ own particle scenes rendered nothing the moment `gravity` became a `Vec3`. The
+ script path already merged this way through `create`; both now share
+ `mergeIntoDefaults`, which also copies nested defaults rather than handing every
+ entity the same array.
+
+- **Three particle fixtures had no check running them.** `particle-trail`,
+ `particle-collision` and `particle-forcefield` existed as scenes that nothing
+ loaded — the trail, floor-collision and force-field paths were unwatched, which
+ is where a simulation rewritten in three axes most easily stops producing a
+ frame. All three now run at PR tier, alongside a new `particles-billboard` that
+ views one particle from the side: a quad fixed in the x/y plane is edge-on there
+ and covers nothing.
+
- **The navigation grid can be seen in the running game.** `NavDebugDraw` outlines
the walkable cells at the height of their own ground and marks the pairs the
step limit refuses — the only thing that explains a route going the long way
diff --git a/desktop b/desktop
index bec0d367d..f4e4279f9 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit bec0d367d4dc627bba586c0ed7a085d313ed6dae
+Subproject commit f4e4279f9e191b4441615f5d0afe713fcb9b37a9
diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.json
index a0e604884..568ce83b9 100644
--- a/docs/astro/src/data/components.generated.json
+++ b/docs/astro/src/data/components.generated.json
@@ -2155,8 +2155,8 @@
},
{
"key": "shapeSize",
- "type": "Vec2",
- "default": "(100, 100)"
+ "type": "Vec3",
+ "default": "(100, 100, 0)"
},
{
"key": "shapeAngle",
@@ -2261,8 +2261,8 @@
},
{
"key": "gravity",
- "type": "Vec2",
- "default": "(0, 0)"
+ "type": "Vec3",
+ "default": "(0, 0, 0)"
},
{
"key": "damping",
@@ -2480,8 +2480,8 @@
},
{
"key": "direction",
- "type": "Vec2",
- "default": "(1, 0)"
+ "type": "Vec3",
+ "default": "(1, 0, 0)"
},
{
"key": "falloff",
diff --git a/examples/particle-demo/src/config.ts b/examples/particle-demo/src/config.ts
index f97769b6d..83fcbe00b 100644
--- a/examples/particle-demo/src/config.ts
+++ b/examples/particle-demo/src/config.ts
@@ -42,21 +42,21 @@ export const SHOWCASES: Showcase[] = [
angleSpreadMin: 78, angleSpreadMax: 102, startSizeMin: 18, startSizeMax: 30,
endSizeMin: 3, endSizeMax: 6, sizeEasing: ParticleEasing.EaseOut,
startColor: { r: 1, g: 0.65, b: 0.15, a: 1 }, endColor: { r: 1, g: 0.12, b: 0.02, a: 0 },
- colorEasing: ParticleEasing.EaseIn, gravity: { x: 0, y: 70 } } },
+ colorEasing: ParticleEasing.EaseIn, gravity: { x: 0, y: 70, z: 0 } } },
{ x: 0, y: -70, data: {
rate: 22, maxParticles: 140, lifetimeMin: 2.0, lifetimeMax: 3.5,
shape: EmitterShape.Circle, shapeRadius: 14, speedMin: 30, speedMax: 55,
angleSpreadMin: 75, angleSpreadMax: 105, startSizeMin: 26, startSizeMax: 40,
endSizeMin: 90, endSizeMax: 130, sizeEasing: ParticleEasing.EaseOut,
startColor: { r: 0.5, g: 0.5, b: 0.53, a: 0.45 }, endColor: { r: 0.25, g: 0.25, b: 0.28, a: 0 },
- gravity: { x: 0, y: 40 }, damping: 0.4, blendMode: BlendMode.Normal } },
+ gravity: { x: 0, y: 40, z: 0 }, damping: 0.4, blendMode: BlendMode.Normal } },
{ x: 0, y: -150, data: {
rate: 14, maxParticles: 90, lifetimeMin: 1.2, lifetimeMax: 2.2,
shape: EmitterShape.Circle, shapeRadius: 10, speedMin: 60, speedMax: 150,
angleSpreadMin: 60, angleSpreadMax: 120, startSizeMin: 3, startSizeMax: 6,
endSizeMin: 0, endSizeMax: 0, startColor: { r: 1, g: 0.8, b: 0.3, a: 1 },
endColor: { r: 1, g: 0.4, b: 0.1, a: 0 }, angularVelocityMin: -180, angularVelocityMax: 180,
- gravity: { x: 0, y: 95 } } },
+ gravity: { x: 0, y: 95, z: 0 } } },
],
},
{
@@ -67,7 +67,7 @@ export const SHOWCASES: Showcase[] = [
lifetimeMin: 0.8, lifetimeMax: 1.6, shape: EmitterShape.Point, speedMin: 170, speedMax: 380,
startSizeMin: 5, startSizeMax: 10, endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseOut,
startColor: [{ r: 1, g: 0.85, b: 0.3, a: 1 }, { r: 0.4, g: 0.9, b: 1, a: 1 }, { r: 1, g: 0.4, b: 0.9, a: 1 }][i],
- endColor: { r: 1, g: 0.3, b: 0.1, a: 0 }, gravity: { x: 0, y: -150 }, damping: 0.3,
+ endColor: { r: 1, g: 0.3, b: 0.1, a: 0 }, gravity: { x: 0, y: -150, z: 0 }, damping: 0.3,
},
})),
},
@@ -96,13 +96,13 @@ export const SHOWCASES: Showcase[] = [
shape: EmitterShape.Point, speedMin: 320, speedMax: 460, angleSpreadMin: 84, angleSpreadMax: 96,
startSizeMin: 6, startSizeMax: 12, endSizeMin: 3, endSizeMax: 5,
startColor: { r: 0.5, g: 0.8, b: 1, a: 1 }, endColor: { r: 0.2, g: 0.4, b: 1, a: 0 },
- gravity: { x: 0, y: -430 } } },
+ gravity: { x: 0, y: -430, z: 0 } } },
{ x: 0, y: -170, data: {
rate: 40, maxParticles: 160, lifetimeMin: 1.5, lifetimeMax: 2.5,
shape: EmitterShape.Circle, shapeRadius: 20, speedMin: 60, speedMax: 140,
angleSpreadMin: 70, angleSpreadMax: 110, startSizeMin: 8, startSizeMax: 16,
endSizeMin: 20, endSizeMax: 30, startColor: { r: 0.6, g: 0.85, b: 1, a: 0.5 },
- endColor: { r: 0.4, g: 0.6, b: 1, a: 0 }, gravity: { x: 0, y: -120 }, damping: 0.5 } },
+ endColor: { r: 0.4, g: 0.6, b: 1, a: 0 }, gravity: { x: 0, y: -120, z: 0 }, damping: 0.5 } },
],
},
{
@@ -110,11 +110,11 @@ export const SHOWCASES: Showcase[] = [
emitters: [
{ x: 0, y: 380, data: {
rate: 90, maxParticles: 800, lifetimeMin: 5, lifetimeMax: 8,
- shape: EmitterShape.Rectangle, shapeSize: { x: 1320, y: 12 },
+ shape: EmitterShape.Rectangle, shapeSize: { x: 1320, y: 12, z: 0 },
speedMin: 40, speedMax: 90, angleSpreadMin: 250, angleSpreadMax: 290,
startSizeMin: 5, startSizeMax: 11, endSizeMin: 5, endSizeMax: 11,
startColor: { r: 1, g: 1, b: 1, a: 0.9 }, endColor: { r: 0.85, g: 0.92, b: 1, a: 0.5 },
- angularVelocityMin: -25, angularVelocityMax: 25, gravity: { x: 0, y: -12 },
+ angularVelocityMin: -25, angularVelocityMax: 25, gravity: { x: 0, y: -12, z: 0 },
damping: 0.05, blendMode: BlendMode.Normal } },
],
},
@@ -123,7 +123,7 @@ export const SHOWCASES: Showcase[] = [
emitters: [
{ x: 0, y: 0, data: {
rate: 70, maxParticles: 320, lifetimeMin: 1.0, lifetimeMax: 2.2,
- shape: EmitterShape.Rectangle, shapeSize: { x: 1120, y: 620 },
+ shape: EmitterShape.Rectangle, shapeSize: { x: 1120, y: 620, z: 0 },
speedMin: 5, speedMax: 25, startSizeMin: 3, startSizeMax: 9,
endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseInOut,
startColor: { r: 1, g: 1, b: 0.8, a: 1 }, endColor: { r: 0.6, g: 0.8, b: 1, a: 0 },
@@ -141,14 +141,14 @@ export const SHOWCASES: Showcase[] = [
speedMin: 160, speedMax: 340, startSizeMin: 5, startSizeMax: 9,
endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseOut,
startColor: { r: 1, g: 0.85, b: 0.35, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.08, a: 0 },
- gravity: { x: 0, y: -150 }, damping: 0.4 } },
+ gravity: { x: 0, y: -150, z: 0 }, damping: 0.4 } },
emitters: [
{ x: 0, y: -230, sub: true, data: {
rate: 2.5, maxParticles: 40, lifetimeMin: 1.4, lifetimeMax: 1.8,
shape: EmitterShape.Point, speedMin: 560, speedMax: 660,
angleSpreadMin: 84, angleSpreadMax: 96, startSizeMin: 8, startSizeMax: 12,
endSizeMin: 5, endSizeMax: 7, startColor: { r: 1, g: 0.95, b: 0.75, a: 1 },
- endColor: { r: 1, g: 0.6, b: 0.25, a: 0.7 }, gravity: { x: 0, y: -230 },
+ endColor: { r: 1, g: 0.6, b: 0.25, a: 0.7 }, gravity: { x: 0, y: -230, z: 0 },
subEmitterTrigger: SubEmitterTrigger.Death, subEmitterInheritVelocity: 0.15 } },
],
},
@@ -163,14 +163,14 @@ export const SHOWCASES: Showcase[] = [
angleSpreadMin: 80, angleSpreadMax: 100, startSizeMin: 30, startSizeMax: 50,
endSizeMin: 120, endSizeMax: 180, sizeEasing: ParticleEasing.EaseOut,
startColor: { r: 0.55, g: 0.6, b: 0.7, a: 0.5 }, endColor: { r: 0.2, g: 0.22, b: 0.3, a: 0 },
- gravity: { x: 0, y: 30 }, damping: 0.2, blendMode: BlendMode.Normal,
+ gravity: { x: 0, y: 30, z: 0 }, damping: 0.2, blendMode: BlendMode.Normal,
noiseStrength: 140, noiseFrequency: 0.006, noiseScrollSpeed: 0.4, noiseOctaves: 2 } },
{ x: 0, y: -220, data: {
rate: 34, maxParticles: 200, lifetimeMin: 1.8, lifetimeMax: 3.0,
shape: EmitterShape.Circle, shapeRadius: 16, speedMin: 60, speedMax: 120,
angleSpreadMin: 78, angleSpreadMax: 102, startSizeMin: 4, startSizeMax: 8,
endSizeMin: 0, endSizeMax: 0, startColor: { r: 1, g: 0.7, b: 0.3, a: 1 },
- endColor: { r: 1, g: 0.3, b: 0.1, a: 0 }, gravity: { x: 0, y: 20 },
+ endColor: { r: 1, g: 0.3, b: 0.1, a: 0 }, gravity: { x: 0, y: 20, z: 0 },
noiseStrength: 220, noiseFrequency: 0.012, noiseScrollSpeed: 0.6, noiseOctaves: 3 } },
],
},
@@ -185,7 +185,7 @@ export const SHOWCASES: Showcase[] = [
startSizeMin: 8, startSizeMax: 12, endSizeMin: 2, endSizeMax: 4,
sizeEasing: ParticleEasing.EaseOut,
startColor: { r: 0.6, g: 0.9, b: 1, a: 1 }, endColor: { r: 0.5, g: 0.3, b: 1, a: 0 },
- gravity: { x: 0, y: -150 },
+ gravity: { x: 0, y: -150, z: 0 },
trailEnabled: true, trailWidth: 12, trailPoints: 8, trailMinDistance: 5 } },
],
},
@@ -216,7 +216,7 @@ export const SHOWCASES: Showcase[] = [
shape: EmitterShape.Cone, shapeRadius: 10, shapeAngle: 60, speedMin: 220, speedMax: 420,
startSizeMin: 6, startSizeMax: 10, endSizeMin: 3, endSizeMax: 5,
startColor: { r: 1, g: 0.9, b: 0.4, a: 1 }, endColor: { r: 1, g: 0.4, b: 0.1, a: 0.5 },
- gravity: { x: 0, y: -520 },
+ gravity: { x: 0, y: -520, z: 0 },
collisionEnabled: true, collisionFloor: -200, collisionBounce: 0.55,
collisionFriction: 0.2, collisionLifetimeLoss: 0.1 } },
],
@@ -235,7 +235,7 @@ export const BURST: Partial<ParticleEmitterData> = {
lifetimeMin: 0.7, lifetimeMax: 1.5, startSizeMin: 6, startSizeMax: 12,
endSizeMin: 0, endSizeMax: 0, sizeEasing: ParticleEasing.EaseOut,
startColor: { r: 1, g: 0.9, b: 0.4, a: 1 }, endColor: { r: 1, g: 0.3, b: 0.1, a: 0 },
- gravity: { x: 0, y: -160 }, damping: 0.4, layer: 5,
+ gravity: { x: 0, y: -160, z: 0 }, damping: 0.4, layer: 5,
};
// Spawn every emitter of a showcase, tagged so they can be despawned together.
diff --git a/fixtures/scenes/particle-billboard.esscene b/fixtures/scenes/particle-billboard.esscene
new file mode 100644
index 000000000..b0e4e4317
--- /dev/null
+++ b/fixtures/scenes/particle-billboard.esscene
@@ -0,0 +1,53 @@
+{
+ "version": 1,
+ "name": "ParticleBillboard",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": {
+ "position": { "x": 300, "y": 0, "z": 0 },
+ "rotation": { "x": 0, "y": 0.7071068, "z": 0, "w": 0.7071068 }
+ } },
+ { "type": "Camera", "data": { "projectionType": 0, "fov": 60, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Edge",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "ParticleEmitter", "data": {
+ "rate": 0,
+ "burstCount": 1,
+ "burstInterval": 1000,
+ "maxParticles": 1,
+ "lifetimeMin": 10,
+ "lifetimeMax": 10,
+ "shape": 0,
+ "speedMin": 0,
+ "speedMax": 0,
+ "startSizeMin": 120,
+ "startSizeMax": 120,
+ "endSizeMin": 120,
+ "endSizeMax": 120,
+ "gravity": { "x": 0, "y": 0, "z": 0 },
+ "damping": 0,
+ "simulationSpace": 0,
+ "looping": false,
+ "playOnStart": true,
+ "startColor": { "r": 0, "g": 1, "b": 0, "a": 1 },
+ "endColor": { "r": 0, "g": 1, "b": 0, "a": 1 },
+ "texture": "@uuid:24cb4e0f-7c75-4df4-9a4d-58480ee405c0"
+ }}
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/fixtures/scenes/particle-billboard.textures.json b/fixtures/scenes/particle-billboard.textures.json
new file mode 100644
index 000000000..0acb647eb
--- /dev/null
+++ b/fixtures/scenes/particle-billboard.textures.json
@@ -0,0 +1,3 @@
+{
+ "24cb4e0f-7c75-4df4-9a4d-58480ee405c0": "/scenes/particle-demo/textures/particle.png"
+}
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 619ad50be..3b970e6de 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 66 beta · 1491 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"1df12cb48da3bf45"
+"dc813d9c5d77b235"
```
## ANCHOR_AXES — const @experimental
@@ -5003,7 +5003,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
-gravity: Vec2
+gravity: Vec3
layer: number
lifetimeMax: number
lifetimeMin: number
@@ -5021,7 +5021,7 @@ rotationMin: number
shape: number
shapeAngle: number
shapeRadius: number
-shapeSize: Vec2
+shapeSize: Vec3
simulationSpace: number
sizeCurve: { keys: { t: number; v: number; }[]; }
sizeEasing: number
@@ -5052,7 +5052,7 @@ BuiltinComponentDef<ParticleForceFieldData>
## ParticleForceFieldData — interface @experimental
```
-direction: Vec2
+direction: Vec3
enabled: boolean
falloff: boolean
radius: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 1a52e676e..19a050fc0 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -5,7 +5,7 @@ Symbols: 113 public · 71 beta · 1510 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
-"1df12cb48da3bf45"
+"dc813d9c5d77b235"
```
## ANCHOR_AXES — const @experimental
@@ -5186,7 +5186,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
-gravity: Vec2
+gravity: Vec3
layer: number
lifetimeMax: number
lifetimeMin: number
@@ -5204,7 +5204,7 @@ rotationMin: number
shape: number
shapeAngle: number
shapeRadius: number
-shapeSize: Vec2
+shapeSize: Vec3
simulationSpace: number
sizeCurve: { keys: { t: number; v: number; }[]; }
sizeEasing: number
@@ -5235,7 +5235,7 @@ BuiltinComponentDef<ParticleForceFieldData>
## ParticleForceFieldData — interface @experimental
```
-direction: Vec2
+direction: Vec3
enabled: boolean
falloff: boolean
radius: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index decfbab90..7a0a35d19 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -4998,7 +4998,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
-gravity: Vec2
+gravity: Vec3
layer: number
lifetimeMax: number
lifetimeMin: number
@@ -5016,7 +5016,7 @@ rotationMin: number
shape: number
shapeAngle: number
shapeRadius: number
-shapeSize: Vec2
+shapeSize: Vec3
simulationSpace: number
sizeCurve: { keys: { t: number; v: number; }[]; }
sizeEasing: number
@@ -5047,7 +5047,7 @@ BuiltinComponentDef<ParticleForceFieldData>
## ParticleForceFieldData — interface @experimental
```
-direction: Vec2
+direction: Vec3
enabled: boolean
falloff: boolean
radius: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 6a0da444f..8300431bb 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -5243,7 +5243,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
-gravity: Vec2
+gravity: Vec3
layer: number
lifetimeMax: number
lifetimeMin: number
@@ -5261,7 +5261,7 @@ rotationMin: number
shape: number
shapeAngle: number
shapeRadius: number
-shapeSize: Vec2
+shapeSize: Vec3
simulationSpace: number
sizeCurve: { keys: { t: number; v: number; }[]; }
sizeEasing: number
@@ -5292,7 +5292,7 @@ BuiltinComponentDef<ParticleForceFieldData>
## ParticleForceFieldData — interface @experimental
```
-direction: Vec2
+direction: Vec3
enabled: boolean
falloff: boolean
radius: number
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 6c73709f3..9f820a731 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -5005,7 +5005,7 @@ enabled: boolean
endColor: Color
endSizeMax: number
endSizeMin: number
-gravity: Vec2
+gravity: Vec3
layer: number
lifetimeMax: number
lifetimeMin: number
@@ -5023,7 +5023,7 @@ rotationMin: number
shape: number
shapeAngle: number
shapeRadius: number
-shapeSize: Vec2
+shapeSize: Vec3
simulationSpace: number
sizeCurve: { keys: { t: number; v: number; }[]; }
sizeEasing: number
@@ -5054,7 +5054,7 @@ BuiltinComponentDef<ParticleForceFieldData>
## ParticleForceFieldData — interface @experimental
```
-direction: Vec2
+direction: Vec3
enabled: boolean
falloff: boolean
radius: number
diff --git a/sdk/src/ecs/bridge/BuiltinBridge.ts b/sdk/src/ecs/bridge/BuiltinBridge.ts
index 52c66865e..efacdba91 100644
--- a/sdk/src/ecs/bridge/BuiltinBridge.ts
+++ b/sdk/src/ecs/bridge/BuiltinBridge.ts
@@ -6,6 +6,7 @@
*/
import { Entity } from '../../types';
+import { mergeIntoDefaults } from '../component';
import type { BuiltinComponentDef } from '../component';
import type { CppRegistry, ESEngineModule } from '../../wasm';
import { validateComponentData, formatValidationErrors, assetFieldNames } from '../../util/validation';
@@ -594,7 +595,9 @@ export class BuiltinBridge {
throw new Error(formatValidationErrors(component._name, errors));
}
}
- const merged = { ...component._default, ...filtered } as T;
+ // Merged one level in, as a script component's `create` is: a builtin whose
+ // field grew an axis still reads the data written before it did.
+ const merged = mergeIntoDefaults(component._default as object, filtered) as T;
let isNew = true;
if (this.cppRegistry_) {
diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
index 1f6347448..d999624e5 100644
--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts
+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts
@@ -929,7 +929,7 @@ export interface ParticleEmitterPtrData {
lifetimeMax: number;
shape: number;
shapeRadius: number;
- shapeSize: Vec2;
+ shapeSize: Vec3;
shapeAngle: number;
speedMin: number;
speedMax: number;
@@ -947,7 +947,7 @@ export interface ParticleEmitterPtrData {
rotationMax: number;
angularVelocityMin: number;
angularVelocityMax: number;
- gravity: Vec2;
+ gravity: Vec3;
damping: number;
noiseStrength: number;
noiseFrequency: number;
@@ -993,53 +993,53 @@ export function fillParticleEmitter(
out.lifetimeMax = f32[(ptr + 28) >> 2];
out.shape = u32[(ptr + 32) >> 2] | 0;
out.shapeRadius = f32[(ptr + 36) >> 2];
- const shapeSize_ = out.shapeSize; shapeSize_.x = f32[(ptr + 40) >> 2]; shapeSize_.y = f32[((ptr + 40) >> 2) + 1];
- out.shapeAngle = f32[(ptr + 48) >> 2];
- out.speedMin = f32[(ptr + 52) >> 2];
- out.speedMax = f32[(ptr + 56) >> 2];
- out.angleSpreadMin = f32[(ptr + 60) >> 2];
- out.angleSpreadMax = f32[(ptr + 64) >> 2];
- out.startSizeMin = f32[(ptr + 68) >> 2];
- out.startSizeMax = f32[(ptr + 72) >> 2];
- out.endSizeMin = f32[(ptr + 76) >> 2];
- out.endSizeMax = f32[(ptr + 80) >> 2];
- out.sizeEasing = u32[(ptr + 84) >> 2] | 0;
- const startColor_ = out.startColor; startColor_.r = f32[(ptr + 88) >> 2]; startColor_.g = f32[((ptr + 88) >> 2) + 1]; startColor_.b = f32[((ptr + 88) >> 2) + 2]; startColor_.a = f32[((ptr + 88) >> 2) + 3];
- const endColor_ = out.endColor; endColor_.r = f32[(ptr + 104) >> 2]; endColor_.g = f32[((ptr + 104) >> 2) + 1]; endColor_.b = f32[((ptr + 104) >> 2) + 2]; endColor_.a = f32[((ptr + 104) >> 2) + 3];
- out.colorEasing = u32[(ptr + 120) >> 2] | 0;
- out.rotationMin = f32[(ptr + 124) >> 2];
- out.rotationMax = f32[(ptr + 128) >> 2];
- out.angularVelocityMin = f32[(ptr + 132) >> 2];
- out.angularVelocityMax = f32[(ptr + 136) >> 2];
- const gravity_ = out.gravity; gravity_.x = f32[(ptr + 140) >> 2]; gravity_.y = f32[((ptr + 140) >> 2) + 1];
- out.damping = f32[(ptr + 148) >> 2];
- out.noiseStrength = f32[(ptr + 152) >> 2];
- out.noiseFrequency = f32[(ptr + 156) >> 2];
- out.noiseScrollSpeed = f32[(ptr + 160) >> 2];
- out.noiseOctaves = u32[(ptr + 164) >> 2] | 0;
- out.texture = u32[(ptr + 168) >> 2];
- out.spriteColumns = u32[(ptr + 172) >> 2] | 0;
- out.spriteRows = u32[(ptr + 176) >> 2] | 0;
- out.spriteFPS = f32[(ptr + 180) >> 2];
- out.spriteLoop = u8[ptr + 184] !== 0;
- out.blendMode = u32[(ptr + 188) >> 2] | 0;
- out.layer = u32[(ptr + 192) >> 2] | 0;
- out.material = u32[(ptr + 196) >> 2];
- out.simulationSpace = u32[(ptr + 200) >> 2] | 0;
- out.enabled = u8[ptr + 204] !== 0;
- out.subEmitterTrigger = u32[(ptr + 208) >> 2] | 0;
- out.subEmitterChance = f32[(ptr + 212) >> 2];
- out.subEmitterInheritVelocity = f32[(ptr + 216) >> 2];
- out.subEmitter = u32[(ptr + 220) >> 2];
- out.trailEnabled = u8[ptr + 224] !== 0;
- out.trailWidth = f32[(ptr + 228) >> 2];
- out.trailPoints = u32[(ptr + 232) >> 2] | 0;
- out.trailMinDistance = f32[(ptr + 236) >> 2];
- out.collisionEnabled = u8[ptr + 240] !== 0;
- out.collisionFloor = f32[(ptr + 244) >> 2];
- out.collisionBounce = f32[(ptr + 248) >> 2];
- out.collisionFriction = f32[(ptr + 252) >> 2];
- out.collisionLifetimeLoss = f32[(ptr + 256) >> 2];
+ const shapeSize_ = out.shapeSize; shapeSize_.x = f32[(ptr + 40) >> 2]; shapeSize_.y = f32[((ptr + 40) >> 2) + 1]; shapeSize_.z = f32[((ptr + 40) >> 2) + 2];
+ out.shapeAngle = f32[(ptr + 52) >> 2];
+ out.speedMin = f32[(ptr + 56) >> 2];
+ out.speedMax = f32[(ptr + 60) >> 2];
+ out.angleSpreadMin = f32[(ptr + 64) >> 2];
+ out.angleSpreadMax = f32[(ptr + 68) >> 2];
+ out.startSizeMin = f32[(ptr + 72) >> 2];
+ out.startSizeMax = f32[(ptr + 76) >> 2];
+ out.endSizeMin = f32[(ptr + 80) >> 2];
+ out.endSizeMax = f32[(ptr + 84) >> 2];
+ out.sizeEasing = u32[(ptr + 88) >> 2] | 0;
+ const startColor_ = out.startColor; startColor_.r = f32[(ptr + 92) >> 2]; startColor_.g = f32[((ptr + 92) >> 2) + 1]; startColor_.b = f32[((ptr + 92) >> 2) + 2]; startColor_.a = f32[((ptr + 92) >> 2) + 3];
+ const endColor_ = out.endColor; endColor_.r = f32[(ptr + 108) >> 2]; endColor_.g = f32[((ptr + 108) >> 2) + 1]; endColor_.b = f32[((ptr + 108) >> 2) + 2]; endColor_.a = f32[((ptr + 108) >> 2) + 3];
+ out.colorEasing = u32[(ptr + 124) >> 2] | 0;
+ out.rotationMin = f32[(ptr + 128) >> 2];
+ out.rotationMax = f32[(ptr + 132) >> 2];
+ out.angularVelocityMin = f32[(ptr + 136) >> 2];
+ out.angularVelocityMax = f32[(ptr + 140) >> 2];
+ const gravity_ = out.gravity; gravity_.x = f32[(ptr + 144) >> 2]; gravity_.y = f32[((ptr + 144) >> 2) + 1]; gravity_.z = f32[((ptr + 144) >> 2) + 2];
+ out.damping = f32[(ptr + 156) >> 2];
+ out.noiseStrength = f32[(ptr + 160) >> 2];
+ out.noiseFrequency = f32[(ptr + 164) >> 2];
+ out.noiseScrollSpeed = f32[(ptr + 168) >> 2];
+ out.noiseOctaves = u32[(ptr + 172) >> 2] | 0;
+ out.texture = u32[(ptr + 176) >> 2];
+ out.spriteColumns = u32[(ptr + 180) >> 2] | 0;
+ out.spriteRows = u32[(ptr + 184) >> 2] | 0;
+ out.spriteFPS = f32[(ptr + 188) >> 2];
+ out.spriteLoop = u8[ptr + 192] !== 0;
+ out.blendMode = u32[(ptr + 196) >> 2] | 0;
+ out.layer = u32[(ptr + 200) >> 2] | 0;
+ out.material = u32[(ptr + 204) >> 2];
+ out.simulationSpace = u32[(ptr + 208) >> 2] | 0;
+ out.enabled = u8[ptr + 212] !== 0;
+ out.subEmitterTrigger = u32[(ptr + 216) >> 2] | 0;
+ out.subEmitterChance = f32[(ptr + 220) >> 2];
+ out.subEmitterInheritVelocity = f32[(ptr + 224) >> 2];
+ out.subEmitter = u32[(ptr + 228) >> 2];
+ out.trailEnabled = u8[ptr + 232] !== 0;
+ out.trailWidth = f32[(ptr + 236) >> 2];
+ out.trailPoints = u32[(ptr + 240) >> 2] | 0;
+ out.trailMinDistance = f32[(ptr + 244) >> 2];
+ out.collisionEnabled = u8[ptr + 248] !== 0;
+ out.collisionFloor = f32[(ptr + 252) >> 2];
+ out.collisionBounce = f32[(ptr + 256) >> 2];
+ out.collisionFriction = f32[(ptr + 260) >> 2];
+ out.collisionLifetimeLoss = f32[(ptr + 264) >> 2];
}
export function writeParticleEmitter(
@@ -1057,53 +1057,53 @@ export function writeParticleEmitter(
f32[(ptr + 28) >> 2] = data.lifetimeMax;
u32[(ptr + 32) >> 2] = data.shape | 0;
f32[(ptr + 36) >> 2] = data.shapeRadius;
- f32[(ptr + 40) >> 2] = data.shapeSize.x; f32[((ptr + 40) >> 2) + 1] = data.shapeSize.y;
- f32[(ptr + 48) >> 2] = data.shapeAngle;
- f32[(ptr + 52) >> 2] = data.speedMin;
- f32[(ptr + 56) >> 2] = data.speedMax;
- f32[(ptr + 60) >> 2] = data.angleSpreadMin;
- f32[(ptr + 64) >> 2] = data.angleSpreadMax;
- f32[(ptr + 68) >> 2] = data.startSizeMin;
- f32[(ptr + 72) >> 2] = data.startSizeMax;
- f32[(ptr + 76) >> 2] = data.endSizeMin;
- f32[(ptr + 80) >> 2] = data.endSizeMax;
- u32[(ptr + 84) >> 2] = data.sizeEasing | 0;
- f32[(ptr + 88) >> 2] = data.startColor.r; f32[((ptr + 88) >> 2) + 1] = data.startColor.g; f32[((ptr + 88) >> 2) + 2] = data.startColor.b; f32[((ptr + 88) >> 2) + 3] = data.startColor.a;
- f32[(ptr + 104) >> 2] = data.endColor.r; f32[((ptr + 104) >> 2) + 1] = data.endColor.g; f32[((ptr + 104) >> 2) + 2] = data.endColor.b; f32[((ptr + 104) >> 2) + 3] = data.endColor.a;
- u32[(ptr + 120) >> 2] = data.colorEasing | 0;
- f32[(ptr + 124) >> 2] = data.rotationMin;
- f32[(ptr + 128) >> 2] = data.rotationMax;
- f32[(ptr + 132) >> 2] = data.angularVelocityMin;
- f32[(ptr + 136) >> 2] = data.angularVelocityMax;
- f32[(ptr + 140) >> 2] = data.gravity.x; f32[((ptr + 140) >> 2) + 1] = data.gravity.y;
- f32[(ptr + 148) >> 2] = data.damping;
- f32[(ptr + 152) >> 2] = data.noiseStrength;
- f32[(ptr + 156) >> 2] = data.noiseFrequency;
- f32[(ptr + 160) >> 2] = data.noiseScrollSpeed;
- u32[(ptr + 164) >> 2] = data.noiseOctaves | 0;
- u32[(ptr + 168) >> 2] = data.texture;
- u32[(ptr + 172) >> 2] = data.spriteColumns | 0;
- u32[(ptr + 176) >> 2] = data.spriteRows | 0;
- f32[(ptr + 180) >> 2] = data.spriteFPS;
- u8[ptr + 184] = data.spriteLoop ? 1 : 0;
- u32[(ptr + 188) >> 2] = data.blendMode | 0;
- u32[(ptr + 192) >> 2] = data.layer | 0;
- u32[(ptr + 196) >> 2] = data.material;
- u32[(ptr + 200) >> 2] = data.simulationSpace | 0;
- u8[ptr + 204] = data.enabled ? 1 : 0;
- u32[(ptr + 208) >> 2] = data.subEmitterTrigger | 0;
- f32[(ptr + 212) >> 2] = data.subEmitterChance;
- f32[(ptr + 216) >> 2] = data.subEmitterInheritVelocity;
- u32[(ptr + 220) >> 2] = data.subEmitter;
- u8[ptr + 224] = data.trailEnabled ? 1 : 0;
- f32[(ptr + 228) >> 2] = data.trailWidth;
- u32[(ptr + 232) >> 2] = data.trailPoints | 0;
- f32[(ptr + 236) >> 2] = data.trailMinDistance;
- u8[ptr + 240] = data.collisionEnabled ? 1 : 0;
- f32[(ptr + 244) >> 2] = data.collisionFloor;
- f32[(ptr + 248) >> 2] = data.collisionBounce;
- f32[(ptr + 252) >> 2] = data.collisionFriction;
- f32[(ptr + 256) >> 2] = data.collisionLifetimeLoss;
+ f32[(ptr + 40) >> 2] = data.shapeSize.x; f32[((ptr + 40) >> 2) + 1] = data.shapeSize.y; f32[((ptr + 40) >> 2) + 2] = data.shapeSize.z;
+ f32[(ptr + 52) >> 2] = data.shapeAngle;
+ f32[(ptr + 56) >> 2] = data.speedMin;
+ f32[(ptr + 60) >> 2] = data.speedMax;
+ f32[(ptr + 64) >> 2] = data.angleSpreadMin;
+ f32[(ptr + 68) >> 2] = data.angleSpreadMax;
+ f32[(ptr + 72) >> 2] = data.startSizeMin;
+ f32[(ptr + 76) >> 2] = data.startSizeMax;
+ f32[(ptr + 80) >> 2] = data.endSizeMin;
+ f32[(ptr + 84) >> 2] = data.endSizeMax;
+ u32[(ptr + 88) >> 2] = data.sizeEasing | 0;
+ f32[(ptr + 92) >> 2] = data.startColor.r; f32[((ptr + 92) >> 2) + 1] = data.startColor.g; f32[((ptr + 92) >> 2) + 2] = data.startColor.b; f32[((ptr + 92) >> 2) + 3] = data.startColor.a;
+ f32[(ptr + 108) >> 2] = data.endColor.r; f32[((ptr + 108) >> 2) + 1] = data.endColor.g; f32[((ptr + 108) >> 2) + 2] = data.endColor.b; f32[((ptr + 108) >> 2) + 3] = data.endColor.a;
+ u32[(ptr + 124) >> 2] = data.colorEasing | 0;
+ f32[(ptr + 128) >> 2] = data.rotationMin;
+ f32[(ptr + 132) >> 2] = data.rotationMax;
+ f32[(ptr + 136) >> 2] = data.angularVelocityMin;
+ f32[(ptr + 140) >> 2] = data.angularVelocityMax;
+ f32[(ptr + 144) >> 2] = data.gravity.x; f32[((ptr + 144) >> 2) + 1] = data.gravity.y; f32[((ptr + 144) >> 2) + 2] = data.gravity.z;
+ f32[(ptr + 156) >> 2] = data.damping;
+ f32[(ptr + 160) >> 2] = data.noiseStrength;
+ f32[(ptr + 164) >> 2] = data.noiseFrequency;
+ f32[(ptr + 168) >> 2] = data.noiseScrollSpeed;
+ u32[(ptr + 172) >> 2] = data.noiseOctaves | 0;
+ u32[(ptr + 176) >> 2] = data.texture;
+ u32[(ptr + 180) >> 2] = data.spriteColumns | 0;
+ u32[(ptr + 184) >> 2] = data.spriteRows | 0;
+ f32[(ptr + 188) >> 2] = data.spriteFPS;
+ u8[ptr + 192] = data.spriteLoop ? 1 : 0;
+ u32[(ptr + 196) >> 2] = data.blendMode | 0;
+ u32[(ptr + 200) >> 2] = data.layer | 0;
+ u32[(ptr + 204) >> 2] = data.material;
+ u32[(ptr + 208) >> 2] = data.simulationSpace | 0;
+ u8[ptr + 212] = data.enabled ? 1 : 0;
+ u32[(ptr + 216) >> 2] = data.subEmitterTrigger | 0;
+ f32[(ptr + 220) >> 2] = data.subEmitterChance;
+ f32[(ptr + 224) >> 2] = data.subEmitterInheritVelocity;
+ u32[(ptr + 228) >> 2] = data.subEmitter;
+ u8[ptr + 232] = data.trailEnabled ? 1 : 0;
+ f32[(ptr + 236) >> 2] = data.trailWidth;
+ u32[(ptr + 240) >> 2] = data.trailPoints | 0;
+ f32[(ptr + 244) >> 2] = data.trailMinDistance;
+ u8[ptr + 248] = data.collisionEnabled ? 1 : 0;
+ f32[(ptr + 252) >> 2] = data.collisionFloor;
+ f32[(ptr + 256) >> 2] = data.collisionBounce;
+ f32[(ptr + 260) >> 2] = data.collisionFriction;
+ f32[(ptr + 264) >> 2] = data.collisionLifetimeLoss;
}
export function createParticleEmitterData(): ParticleEmitterPtrData {
@@ -1119,7 +1119,7 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {
lifetimeMax: 0,
shape: 0,
shapeRadius: 0,
- shapeSize: { x: 0, y: 0 },
+ shapeSize: { x: 0, y: 0, z: 0 },
shapeAngle: 0,
speedMin: 0,
speedMax: 0,
@@ -1137,7 +1137,7 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {
rotationMax: 0,
angularVelocityMin: 0,
angularVelocityMax: 0,
- gravity: { x: 0, y: 0 },
+ gravity: { x: 0, y: 0, z: 0 },
damping: 0,
noiseStrength: 0,
noiseFrequency: 0,
@@ -1173,7 +1173,7 @@ export interface ParticleForceFieldPtrData {
type: number;
strength: number;
radius: number;
- direction: Vec2;
+ direction: Vec3;
falloff: boolean;
enabled: boolean;
}
@@ -1185,9 +1185,9 @@ export function fillParticleForceField(
out.type = u32[ptr >> 2] | 0;
out.strength = f32[(ptr + 4) >> 2];
out.radius = f32[(ptr + 8) >> 2];
- const direction_ = out.direction; direction_.x = f32[(ptr + 12) >> 2]; direction_.y = f32[((ptr + 12) >> 2) + 1];
- out.falloff = u8[ptr + 20] !== 0;
- out.enabled = u8[ptr + 21] !== 0;
+ const direction_ = out.direction; direction_.x = f32[(ptr + 12) >> 2]; direction_.y = f32[((ptr + 12) >> 2) + 1]; direction_.z = f32[((ptr + 12) >> 2) + 2];
+ out.falloff = u8[ptr + 24] !== 0;
+ out.enabled = u8[ptr + 25] !== 0;
}
export function writeParticleForceField(
@@ -1197,9 +1197,9 @@ export function writeParticleForceField(
u32[ptr >> 2] = data.type | 0;
f32[(ptr + 4) >> 2] = data.strength;
f32[(ptr + 8) >> 2] = data.radius;
- f32[(ptr + 12) >> 2] = data.direction.x; f32[((ptr + 12) >> 2) + 1] = data.direction.y;
- u8[ptr + 20] = data.falloff ? 1 : 0;
- u8[ptr + 21] = data.enabled ? 1 : 0;
+ f32[(ptr + 12) >> 2] = data.direction.x; f32[((ptr + 12) >> 2) + 1] = data.direction.y; f32[((ptr + 12) >> 2) + 2] = data.direction.z;
+ u8[ptr + 24] = data.falloff ? 1 : 0;
+ u8[ptr + 25] = data.enabled ? 1 : 0;
}
export function createParticleForceFieldData(): ParticleForceFieldPtrData {
@@ -1207,7 +1207,7 @@ export function createParticleForceFieldData(): ParticleForceFieldPtrData {
type: 0,
strength: 0,
radius: 0,
- direction: { x: 0, y: 0 },
+ direction: { x: 0, y: 0, z: 0 },
falloff: false,
enabled: false,
};
diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.ts
index 9c15f95c3..ae7d40cef 100644
--- a/sdk/src/ecs/component.generated.ts
+++ b/sdk/src/ecs/component.generated.ts
@@ -15,7 +15,7 @@ import type { Dimension, Padding } from '../wasm/wasm.generated';
* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to
* run on mismatch, because mismatched offsets read the wrong heap bytes.
*/
-export const ABI_LAYOUT_HASH = '1df12cb48da3bf45';
+export const ABI_LAYOUT_HASH = 'dc813d9c5d77b235';
/**
* One asset-valued field of a component: which field, and what kind of
@@ -532,7 +532,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
lifetimeMax: 5,
shape: 3,
shapeRadius: 100,
- shapeSize: { x: 100, y: 100 },
+ shapeSize: { x: 100, y: 100, z: 0 },
shapeAngle: 25,
speedMin: 500,
speedMax: 500,
@@ -550,7 +550,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
rotationMax: 0,
angularVelocityMin: 0,
angularVelocityMax: 0,
- gravity: { x: 0, y: 0 },
+ gravity: { x: 0, y: 0, z: 0 },
damping: 0,
noiseStrength: 0,
noiseFrequency: 0.01,
@@ -650,7 +650,7 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {
type: 0,
strength: 200,
radius: 0,
- direction: { x: 1, y: 0 },
+ direction: { x: 1, y: 0, z: 0 },
falloff: true,
enabled: true,
},
@@ -1301,7 +1301,7 @@ export interface ParticleEmitterData {
lifetimeMax: number;
shape: number;
shapeRadius: number;
- shapeSize: Vec2;
+ shapeSize: Vec3;
shapeAngle: number;
speedMin: number;
speedMax: number;
@@ -1319,7 +1319,7 @@ export interface ParticleEmitterData {
rotationMax: number;
angularVelocityMin: number;
angularVelocityMax: number;
- gravity: Vec2;
+ gravity: Vec3;
damping: number;
noiseStrength: number;
noiseFrequency: number;
@@ -1354,7 +1354,7 @@ export interface ParticleForceFieldData {
type: number;
strength: number;
radius: number;
- direction: Vec2;
+ direction: Vec3;
falloff: boolean;
enabled: boolean;
}
diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.ts
index 3d7edcc90..7f97356c5 100644
--- a/sdk/src/ecs/component.ts
+++ b/sdk/src/ecs/component.ts
@@ -229,6 +229,32 @@ export interface ComponentDef<T> {
create(data?: Partial<T>): T;
}
+/**
+ * `defaults` with `data` laid over it, ONE LEVEL INTO plain objects: a whole-object
+ * overwrite drops what the data does not carry, so a `{x, y}` written before that
+ * field grew a `z` would arrive with no depth. Arrays and nested defaults are
+ * copied, not shared — two entities taking the default would write into one array.
+ */
+export function mergeIntoDefaults<T extends object>(defaults: T, data?: Partial<T>): T {
+ const out = { ...defaults } as Record<string, unknown>;
+ const src = defaults as Record<string, unknown>;
+ for (const k of Object.keys(src)) {
+ const v = src[k];
+ if (Array.isArray(v)) out[k] = v.slice();
+ else if (v !== null && typeof v === 'object') out[k] = { ...(v as object) };
+ }
+ if (!data) return out as T;
+ for (const [k, v] of Object.entries(data as Record<string, unknown>)) {
+ if (v === undefined) continue;
+ const base = out[k];
+ const nest = base !== null && typeof base === 'object' && !Array.isArray(base)
+ && v !== null && typeof v === 'object' && !Array.isArray(v);
+ if (nest) Object.assign(base as object, v);
+ else out[k] = v;
+ }
+ return out as T;
+}
+
function classifyKeys(obj: object): { flatKeys: string[]; objectKeys: string[]; arrayKeys: string[] } | null {
const flatKeys: string[] = [];
const objectKeys: string[] = [];
@@ -333,24 +359,8 @@ function createComponentDef<T extends object>(
transient: metadata?.transient ?? false,
renderableField: renderableField ?? null,
create(data?: Partial<T>): T {
- if (keyInfo) {
- const result = { ...defaultsRec };
- for (const k of keyInfo.objectKeys) result[k] = { ...(defaultsRec[k] as object) };
- for (const k of keyInfo.arrayKeys) result[k] = (defaultsRec[k] as unknown[]).slice();
- if (data) {
- const dataRec = data as Record<string, unknown>;
- for (const k of Object.keys(dataRec)) {
- if (dataRec[k] !== undefined) {
- if (keyInfo.objectKeys.includes(k) && typeof dataRec[k] === 'object' && dataRec[k] !== null && !Array.isArray(dataRec[k])) {
- Object.assign(result[k] as object, dataRec[k]);
- } else {
- result[k] = dataRec[k];
- }
- }
- }
- }
- return result as T;
- }
+ // Flat defaults have nothing to merge into, so they take the cheap path.
+ if (keyInfo) return mergeIntoDefaults(defaults, data);
return data ? { ...defaults, ...data } : { ...defaults };
}
};
diff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.ts
index eb4706211..635b96958 100644
--- a/sdk/src/wasm/ptrLayouts.generated.ts
+++ b/sdk/src/wasm/ptrLayouts.generated.ts
@@ -268,53 +268,53 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'lifetimeMax', type: 'f32', offset: 28 },
{ name: 'shape', type: 'i32', offset: 32 },
{ name: 'shapeRadius', type: 'f32', offset: 36 },
- { name: 'shapeSize', type: 'vec2', offset: 40 },
- { name: 'shapeAngle', type: 'f32', offset: 48 },
- { name: 'speedMin', type: 'f32', offset: 52 },
- { name: 'speedMax', type: 'f32', offset: 56 },
- { name: 'angleSpreadMin', type: 'f32', offset: 60 },
- { name: 'angleSpreadMax', type: 'f32', offset: 64 },
- { name: 'startSizeMin', type: 'f32', offset: 68 },
- { name: 'startSizeMax', type: 'f32', offset: 72 },
- { name: 'endSizeMin', type: 'f32', offset: 76 },
- { name: 'endSizeMax', type: 'f32', offset: 80 },
- { name: 'sizeEasing', type: 'i32', offset: 84 },
- { name: 'startColor', type: 'color', offset: 88 },
- { name: 'endColor', type: 'color', offset: 104 },
- { name: 'colorEasing', type: 'i32', offset: 120 },
- { name: 'rotationMin', type: 'f32', offset: 124 },
- { name: 'rotationMax', type: 'f32', offset: 128 },
- { name: 'angularVelocityMin', type: 'f32', offset: 132 },
- { name: 'angularVelocityMax', type: 'f32', offset: 136 },
- { name: 'gravity', type: 'vec2', offset: 140 },
- { name: 'damping', type: 'f32', offset: 148 },
- { name: 'noiseStrength', type: 'f32', offset: 152 },
- { name: 'noiseFrequency', type: 'f32', offset: 156 },
- { name: 'noiseScrollSpeed', type: 'f32', offset: 160 },
- { name: 'noiseOctaves', type: 'i32', offset: 164 },
- { name: 'texture', type: 'u32', offset: 168 },
- { name: 'spriteColumns', type: 'i32', offset: 172 },
- { name: 'spriteRows', type: 'i32', offset: 176 },
- { name: 'spriteFPS', type: 'f32', offset: 180 },
- { name: 'spriteLoop', type: 'bool', offset: 184 },
- { name: 'blendMode', type: 'i32', offset: 188 },
- { name: 'layer', type: 'i32', offset: 192 },
- { name: 'material', type: 'u32', offset: 196 },
- { name: 'simulationSpace', type: 'i32', offset: 200 },
- { name: 'enabled', type: 'bool', offset: 204 },
- { name: 'subEmitterTrigger', type: 'i32', offset: 208 },
- { name: 'subEmitterChance', type: 'f32', offset: 212 },
- { name: 'subEmitterInheritVelocity', type: 'f32', offset: 216 },
- { name: 'subEmitter', type: 'u32', offset: 220 },
- { name: 'trailEnabled', type: 'bool', offset: 224 },
- { name: 'trailWidth', type: 'f32', offset: 228 },
- { name: 'trailPoints', type: 'i32', offset: 232 },
- { name: 'trailMinDistance', type: 'f32', offset: 236 },
- { name: 'collisionEnabled', type: 'bool', offset: 240 },
- { name: 'collisionFloor', type: 'f32', offset: 244 },
- { name: 'collisionBounce', type: 'f32', offset: 248 },
- { name: 'collisionFriction', type: 'f32', offset: 252 },
- { name: 'collisionLifetimeLoss', type: 'f32', offset: 256 },
+ { name: 'shapeSize', type: 'vec3', offset: 40 },
+ { name: 'shapeAngle', type: 'f32', offset: 52 },
+ { name: 'speedMin', type: 'f32', offset: 56 },
+ { name: 'speedMax', type: 'f32', offset: 60 },
+ { name: 'angleSpreadMin', type: 'f32', offset: 64 },
+ { name: 'angleSpreadMax', type: 'f32', offset: 68 },
+ { name: 'startSizeMin', type: 'f32', offset: 72 },
+ { name: 'startSizeMax', type: 'f32', offset: 76 },
+ { name: 'endSizeMin', type: 'f32', offset: 80 },
+ { name: 'endSizeMax', type: 'f32', offset: 84 },
+ { name: 'sizeEasing', type: 'i32', offset: 88 },
+ { name: 'startColor', type: 'color', offset: 92 },
+ { name: 'endColor', type: 'color', offset: 108 },
+ { name: 'colorEasing', type: 'i32', offset: 124 },
+ { name: 'rotationMin', type: 'f32', offset: 128 },
+ { name: 'rotationMax', type: 'f32', offset: 132 },
+ { name: 'angularVelocityMin', type: 'f32', offset: 136 },
+ { name: 'angularVelocityMax', type: 'f32', offset: 140 },
+ { name: 'gravity', type: 'vec3', offset: 144 },
+ { name: 'damping', type: 'f32', offset: 156 },
+ { name: 'noiseStrength', type: 'f32', offset: 160 },
+ { name: 'noiseFrequency', type: 'f32', offset: 164 },
+ { name: 'noiseScrollSpeed', type: 'f32', offset: 168 },
+ { name: 'noiseOctaves', type: 'i32', offset: 172 },
+ { name: 'texture', type: 'u32', offset: 176 },
+ { name: 'spriteColumns', type: 'i32', offset: 180 },
+ { name: 'spriteRows', type: 'i32', offset: 184 },
+ { name: 'spriteFPS', type: 'f32', offset: 188 },
+ { name: 'spriteLoop', type: 'bool', offset: 192 },
+ { name: 'blendMode', type: 'i32', offset: 196 },
+ { name: 'layer', type: 'i32', offset: 200 },
+ { name: 'material', type: 'u32', offset: 204 },
+ { name: 'simulationSpace', type: 'i32', offset: 208 },
+ { name: 'enabled', type: 'bool', offset: 212 },
+ { name: 'subEmitterTrigger', type: 'i32', offset: 216 },
+ { name: 'subEmitterChance', type: 'f32', offset: 220 },
+ { name: 'subEmitterInheritVelocity', type: 'f32', offset: 224 },
+ { name: 'subEmitter', type: 'u32', offset: 228 },
+ { name: 'trailEnabled', type: 'bool', offset: 232 },
+ { name: 'trailWidth', type: 'f32', offset: 236 },
+ { name: 'trailPoints', type: 'i32', offset: 240 },
+ { name: 'trailMinDistance', type: 'f32', offset: 244 },
+ { name: 'collisionEnabled', type: 'bool', offset: 248 },
+ { name: 'collisionFloor', type: 'f32', offset: 252 },
+ { name: 'collisionBounce', type: 'f32', offset: 256 },
+ { name: 'collisionFriction', type: 'f32', offset: 260 },
+ { name: 'collisionLifetimeLoss', type: 'f32', offset: 264 },
],
},
ParticleForceField: {
@@ -323,9 +323,9 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {
{ name: 'type', type: 'i32', offset: 0 },
{ name: 'strength', type: 'f32', offset: 4 },
{ name: 'radius', type: 'f32', offset: 8 },
- { name: 'direction', type: 'vec2', offset: 12 },
- { name: 'falloff', type: 'bool', offset: 20 },
- { name: 'enabled', type: 'bool', offset: 21 },
+ { name: 'direction', type: 'vec3', offset: 12 },
+ { name: 'falloff', type: 'bool', offset: 24 },
+ { name: 'enabled', type: 'bool', offset: 25 },
],
},
RigidBody: {
diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.ts
index 3837de87f..52a40b79b 100644
--- a/sdk/src/wasm/wasm.generated.ts
+++ b/sdk/src/wasm/wasm.generated.ts
@@ -440,7 +440,7 @@ export interface ParticleEmitter {
lifetimeMax: number;
shape: number;
shapeRadius: number;
- shapeSize: Vec2;
+ shapeSize: Vec3;
shapeAngle: number;
speedMin: number;
speedMax: number;
@@ -458,7 +458,7 @@ export interface ParticleEmitter {
rotationMax: number;
angularVelocityMin: number;
angularVelocityMax: number;
- gravity: Vec2;
+ gravity: Vec3;
damping: number;
noiseStrength: number;
noiseFrequency: number;
@@ -493,7 +493,7 @@ export interface ParticleForceField {
type: number;
strength: number;
radius: number;
- direction: Vec2;
+ direction: Vec3;
falloff: boolean;
enabled: boolean;
}
diff --git a/sdk/tests/component-default-merge.test.ts b/sdk/tests/component-default-merge.test.ts
new file mode 100644
index 000000000..ea232bdf9
--- /dev/null
+++ b/sdk/tests/component-default-merge.test.ts
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Data written before a field grew is still read as that field.
+ *
+ * A component's fields gain axes: a gravity that was a pair becomes a triple the
+ * day the engine learns about depth. Every scene, prefab and save already on disk
+ * carries the pair. Overwriting the default wholesale drops what the data does
+ * not carry, and the result is not an error — it is a value with a missing
+ * component, which reads as zero and draws on a plane the scene left. Two of the
+ * engine's own particle scenes went black exactly that way.
+ */
+import { describe, it, expect } from 'vitest';
+import { mergeIntoDefaults, defineComponent, clearUserComponents } from '../src/ecs/component';
+
+describe('mergeIntoDefaults', () => {
+ it('fills in the axis older data does not carry', () => {
+ const merged = mergeIntoDefaults({ gravity: { x: 0, y: 0, z: 0 } },
+ { gravity: { x: 1, y: -2 } as never });
+ expect(merged.gravity).toEqual({ x: 1, y: -2, z: 0 });
+ });
+
+ it('takes every field the data does carry', () => {
+ expect(mergeIntoDefaults({ size: { x: 1, y: 1, z: 1 } }, { size: { x: 5, y: 6, z: 7 } }))
+ .toEqual({ size: { x: 5, y: 6, z: 7 } });
+ });
+
+ it('replaces arrays rather than merging them', () => {
+ expect(mergeIntoDefaults({ stops: [1, 2, 3] }, { stops: [9] })).toEqual({ stops: [9] });
+ });
+
+ // Two entities that both took the default would otherwise write into one
+ // array — the aliasing that makes one entity's edit appear on another.
+ it('copies the defaults rather than handing out the same objects', () => {
+ const defaults = { pos: { x: 0, y: 0 }, tags: [] as string[] };
+ const a = mergeIntoDefaults(defaults);
+ const b = mergeIntoDefaults(defaults);
+ a.pos.x = 5;
+ a.tags.push('one');
+ expect(b.pos.x).toBe(0);
+ expect(b.tags).toEqual([]);
+ expect(defaults.pos.x).toBe(0);
+ });
+
+ it('leaves flat fields alone, including nulls and undefined', () => {
+ expect(mergeIntoDefaults({ a: 1, b: 'x' }, { a: 2, b: undefined }))
+ .toEqual({ a: 2, b: 'x' });
+ expect(mergeIntoDefaults({ ref: null as string | null }, { ref: 'set' })).toEqual({ ref: 'set' });
+ });
+
+ // The script path merges through `create`; the builtin path through the
+ // bridge. Same rule, or a C++ component and a TS one disagree about what an
+ // incomplete vector means.
+ it('is what a script component create does', () => {
+ clearUserComponents();
+ const Comp = defineComponent('MergeProbe', { v: { x: 0, y: 0, z: 0 }, n: 1 });
+ expect(Comp.create({ v: { x: 3, y: 4 } as never })).toEqual({ v: { x: 3, y: 4, z: 0 }, n: 1 });
+ clearUserComponents();
+ });
+});
diff --git a/sdk/tests/particle.test.ts b/sdk/tests/particle.test.ts
index c05d29cef..04401b58d 100644
--- a/sdk/tests/particle.test.ts
+++ b/sdk/tests/particle.test.ts
@@ -33,7 +33,8 @@ describe('ParticleEmitter Component', () => {
expect(defaults.shape).toBe(3);
expect(defaults.shapeRadius).toBe(100);
- expect(defaults.shapeSize).toEqual({ x: 100, y: 100 });
+ // A BOX, whose depth of 0 is the flat rectangle a 2D emitter spawns from.
+ expect(defaults.shapeSize).toEqual({ x: 100, y: 100, z: 0 });
expect(defaults.shapeAngle).toBe(25);
});
diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cpp
index b4f011f6f..4b9dcd503 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 96c16f9290122248
+ * @schema_hash 2ccf06ed7cc3721f
*/
-#define ES_EDITOR_API_SCHEMA_HASH "96c16f9290122248"
+#define ES_EDITOR_API_SCHEMA_HASH "2ccf06ed7cc3721f"
#include <emscripten/bind.h>
#include <string>
@@ -368,6 +368,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"shapeRadius","type":"float","group":"ParticleEmitter"},
{"key":"shapeSize.x","type":"float","group":"ParticleEmitter"},
{"key":"shapeSize.y","type":"float","group":"ParticleEmitter"},
+ {"key":"shapeSize.z","type":"float","group":"ParticleEmitter"},
{"key":"shapeAngle","type":"float","group":"ParticleEmitter"},
{"key":"speedMin","type":"float","group":"ParticleEmitter"},
{"key":"speedMax","type":"float","group":"ParticleEmitter"},
@@ -393,6 +394,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"angularVelocityMax","type":"float","group":"ParticleEmitter"},
{"key":"gravity.x","type":"float","group":"ParticleEmitter"},
{"key":"gravity.y","type":"float","group":"ParticleEmitter"},
+ {"key":"gravity.z","type":"float","group":"ParticleEmitter"},
{"key":"damping","type":"float","group":"ParticleEmitter"},
{"key":"noiseStrength","type":"float","group":"ParticleEmitter"},
{"key":"noiseFrequency","type":"float","group":"ParticleEmitter"},
@@ -429,6 +431,7 @@ std::string editor_getComponentSchema(const std::string& name) {
{"key":"radius","type":"float","group":"ParticleForceField"},
{"key":"direction.x","type":"float","group":"ParticleForceField"},
{"key":"direction.y","type":"float","group":"ParticleForceField"},
+ {"key":"direction.z","type":"float","group":"ParticleForceField"},
{"key":"falloff","type":"bool","group":"ParticleForceField"},
{"key":"enabled","type":"bool","group":"ParticleForceField"}
])JSON";
@@ -1211,6 +1214,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "shapeRadius") { c.shapeRadius = value; }
else if (field == "shapeSize.x") { c.shapeSize.x = value; }
else if (field == "shapeSize.y") { c.shapeSize.y = value; }
+ else if (field == "shapeSize.z") { c.shapeSize.z = value; }
else if (field == "shapeAngle") { c.shapeAngle = value; }
else if (field == "speedMin") { c.speedMin = value; }
else if (field == "speedMax") { c.speedMax = value; }
@@ -1234,6 +1238,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "angularVelocityMax") { c.angularVelocityMax = value; }
else if (field == "gravity.x") { c.gravity.x = value; }
else if (field == "gravity.y") { c.gravity.y = value; }
+ else if (field == "gravity.z") { c.gravity.z = value; }
else if (field == "damping") { c.damping = value; }
else if (field == "noiseStrength") { c.noiseStrength = value; }
else if (field == "noiseFrequency") { c.noiseFrequency = value; }
@@ -1256,6 +1261,7 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::s
else if (field == "radius") { c.radius = value; }
else if (field == "direction.x") { c.direction.x = value; }
else if (field == "direction.y") { c.direction.y = value; }
+ else if (field == "direction.z") { c.direction.z = value; }
else { return false; }
return true;
} else if (comp == "RigidBody") {
@@ -1667,6 +1673,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "shapeRadius") { return c.shapeRadius; }
else if (field == "shapeSize.x") { return c.shapeSize.x; }
else if (field == "shapeSize.y") { return c.shapeSize.y; }
+ else if (field == "shapeSize.z") { return c.shapeSize.z; }
else if (field == "shapeAngle") { return c.shapeAngle; }
else if (field == "speedMin") { return c.speedMin; }
else if (field == "speedMax") { return c.speedMax; }
@@ -1690,6 +1697,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "angularVelocityMax") { return c.angularVelocityMax; }
else if (field == "gravity.x") { return c.gravity.x; }
else if (field == "gravity.y") { return c.gravity.y; }
+ else if (field == "gravity.z") { return c.gravity.z; }
else if (field == "damping") { return c.damping; }
else if (field == "noiseStrength") { return c.noiseStrength; }
else if (field == "noiseFrequency") { return c.noiseFrequency; }
@@ -1710,6 +1718,7 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::st
else if (field == "radius") { return c.radius; }
else if (field == "direction.x") { return c.direction.x; }
else if (field == "direction.y") { return c.direction.y; }
+ else if (field == "direction.z") { return c.direction.z; }
} else if (comp == "RigidBody") {
if (!reg.has<esengine::ecs::RigidBody>(entity)) return 0.0f;
const auto& c = reg.get<esengine::ecs::RigidBody>(entity);
diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cpp
index f09b2f385..eacaced6a 100644
--- a/src/esengine/bindings/WebBindings.generated.cpp
+++ b/src/esengine/bindings/WebBindings.generated.cpp
@@ -657,7 +657,7 @@ struct ParticleEmitterJS {
f32 lifetimeMax;
i32 shape;
f32 shapeRadius;
- glm::vec2 shapeSize;
+ glm::vec3 shapeSize;
f32 shapeAngle;
f32 speedMin;
f32 speedMax;
@@ -675,7 +675,7 @@ struct ParticleEmitterJS {
f32 rotationMax;
f32 angularVelocityMin;
f32 angularVelocityMax;
- glm::vec2 gravity;
+ glm::vec3 gravity;
f32 damping;
f32 noiseStrength;
f32 noiseFrequency;
@@ -2861,58 +2861,58 @@ static_assert(offsetof(esengine::ecs::ParticleEmitter, lifetimeMax) == 28, "ABI
static_assert(offsetof(esengine::ecs::ParticleEmitter, shape) == 32, "ABI offset drift: esengine::ecs::ParticleEmitter.shape (EHT expected 32)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeRadius) == 36, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeRadius (EHT expected 36)");
static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeSize) == 40, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeSize (EHT expected 40)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeAngle) == 48, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeAngle (EHT expected 48)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMin) == 52, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMin (EHT expected 52)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMax) == 56, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMax (EHT expected 56)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMin) == 60, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMin (EHT expected 60)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMax) == 64, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMax (EHT expected 64)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMin) == 68, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMin (EHT expected 68)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMax) == 72, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMax (EHT expected 72)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMin) == 76, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMin (EHT expected 76)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMax) == 80, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMax (EHT expected 80)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, sizeEasing) == 84, "ABI offset drift: esengine::ecs::ParticleEmitter.sizeEasing (EHT expected 84)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, startColor) == 88, "ABI offset drift: esengine::ecs::ParticleEmitter.startColor (EHT expected 88)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, endColor) == 104, "ABI offset drift: esengine::ecs::ParticleEmitter.endColor (EHT expected 104)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, colorEasing) == 120, "ABI offset drift: esengine::ecs::ParticleEmitter.colorEasing (EHT expected 120)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMin) == 124, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMin (EHT expected 124)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMax) == 128, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMax (EHT expected 128)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMin) == 132, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMin (EHT expected 132)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMax) == 136, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMax (EHT expected 136)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, gravity) == 140, "ABI offset drift: esengine::ecs::ParticleEmitter.gravity (EHT expected 140)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, damping) == 148, "ABI offset drift: esengine::ecs::ParticleEmitter.damping (EHT expected 148)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseStrength) == 152, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseStrength (EHT expected 152)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseFrequency) == 156, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseFrequency (EHT expected 156)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseScrollSpeed) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseScrollSpeed (EHT expected 160)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseOctaves) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseOctaves (EHT expected 164)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 168)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 172)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 176)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 180)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 184)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 188)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 192, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 192)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 196, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 196)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 200, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 200)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 204, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 204)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterTrigger) == 208, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterTrigger (EHT expected 208)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterChance) == 212, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterChance (EHT expected 212)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterInheritVelocity) == 216, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterInheritVelocity (EHT expected 216)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitter) == 220, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitter (EHT expected 220)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailEnabled) == 224, "ABI offset drift: esengine::ecs::ParticleEmitter.trailEnabled (EHT expected 224)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailWidth) == 228, "ABI offset drift: esengine::ecs::ParticleEmitter.trailWidth (EHT expected 228)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 232, "ABI offset drift: esengine::ecs::ParticleEmitter.trailPoints (EHT expected 232)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 236, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 236)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 240, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 240)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 244)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionBounce) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionBounce (EHT expected 248)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFriction) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFriction (EHT expected 252)");
-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionLifetimeLoss) == 256, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionLifetimeLoss (EHT expected 256)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, shapeAngle) == 52, "ABI offset drift: esengine::ecs::ParticleEmitter.shapeAngle (EHT expected 52)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMin) == 56, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMin (EHT expected 56)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, speedMax) == 60, "ABI offset drift: esengine::ecs::ParticleEmitter.speedMax (EHT expected 60)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMin) == 64, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMin (EHT expected 64)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angleSpreadMax) == 68, "ABI offset drift: esengine::ecs::ParticleEmitter.angleSpreadMax (EHT expected 68)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMin) == 72, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMin (EHT expected 72)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startSizeMax) == 76, "ABI offset drift: esengine::ecs::ParticleEmitter.startSizeMax (EHT expected 76)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMin) == 80, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMin (EHT expected 80)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endSizeMax) == 84, "ABI offset drift: esengine::ecs::ParticleEmitter.endSizeMax (EHT expected 84)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, sizeEasing) == 88, "ABI offset drift: esengine::ecs::ParticleEmitter.sizeEasing (EHT expected 88)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, startColor) == 92, "ABI offset drift: esengine::ecs::ParticleEmitter.startColor (EHT expected 92)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, endColor) == 108, "ABI offset drift: esengine::ecs::ParticleEmitter.endColor (EHT expected 108)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, colorEasing) == 124, "ABI offset drift: esengine::ecs::ParticleEmitter.colorEasing (EHT expected 124)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMin) == 128, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMin (EHT expected 128)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, rotationMax) == 132, "ABI offset drift: esengine::ecs::ParticleEmitter.rotationMax (EHT expected 132)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMin) == 136, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMin (EHT expected 136)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, angularVelocityMax) == 140, "ABI offset drift: esengine::ecs::ParticleEmitter.angularVelocityMax (EHT expected 140)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, gravity) == 144, "ABI offset drift: esengine::ecs::ParticleEmitter.gravity (EHT expected 144)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, damping) == 156, "ABI offset drift: esengine::ecs::ParticleEmitter.damping (EHT expected 156)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseStrength) == 160, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseStrength (EHT expected 160)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseFrequency) == 164, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseFrequency (EHT expected 164)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseScrollSpeed) == 168, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseScrollSpeed (EHT expected 168)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, noiseOctaves) == 172, "ABI offset drift: esengine::ecs::ParticleEmitter.noiseOctaves (EHT expected 172)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, texture) == 176, "ABI offset drift: esengine::ecs::ParticleEmitter.texture (EHT expected 176)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteColumns) == 180, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteColumns (EHT expected 180)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteRows) == 184, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteRows (EHT expected 184)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteFPS) == 188, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteFPS (EHT expected 188)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, spriteLoop) == 192, "ABI offset drift: esengine::ecs::ParticleEmitter.spriteLoop (EHT expected 192)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 196, "ABI offset drift: esengine::ecs::ParticleEmitter.blendMode (EHT expected 196)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 200, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 200)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 204, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 204)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 208, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 208)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 212, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 212)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterTrigger) == 216, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterTrigger (EHT expected 216)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterChance) == 220, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterChance (EHT expected 220)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterInheritVelocity) == 224, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterInheritVelocity (EHT expected 224)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitter) == 228, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitter (EHT expected 228)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailEnabled) == 232, "ABI offset drift: esengine::ecs::ParticleEmitter.trailEnabled (EHT expected 232)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailWidth) == 236, "ABI offset drift: esengine::ecs::ParticleEmitter.trailWidth (EHT expected 236)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 240, "ABI offset drift: esengine::ecs::ParticleEmitter.trailPoints (EHT expected 240)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 244)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 248)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 252)");
+static_assert(offsetof(esengine::ecs::ParticleEmitter, 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::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)");
static_assert(offsetof(esengine::ecs::ParticleForceField, direction) == 12, "ABI offset drift: esengine::ecs::ParticleForceField.direction (EHT expected 12)");
-static_assert(offsetof(esengine::ecs::ParticleForceField, falloff) == 20, "ABI offset drift: esengine::ecs::ParticleForceField.falloff (EHT expected 20)");
-static_assert(offsetof(esengine::ecs::ParticleForceField, enabled) == 21, "ABI offset drift: esengine::ecs::ParticleForceField.enabled (EHT expected 21)");
+static_assert(offsetof(esengine::ecs::ParticleForceField, falloff) == 24, "ABI offset drift: esengine::ecs::ParticleForceField.falloff (EHT expected 24)");
+static_assert(offsetof(esengine::ecs::ParticleForceField, enabled) == 25, "ABI offset drift: esengine::ecs::ParticleForceField.enabled (EHT expected 25)");
static_assert(offsetof(esengine::ecs::RigidBody, bodyType) == 0, "ABI offset drift: esengine::ecs::RigidBody.bodyType (EHT expected 0)");
static_assert(offsetof(esengine::ecs::RigidBody, gravityScale) == 4, "ABI offset drift: esengine::ecs::RigidBody.gravityScale (EHT expected 4)");
static_assert(offsetof(esengine::ecs::RigidBody, linearDamping) == 8, "ABI offset drift: esengine::ecs::RigidBody.linearDamping (EHT expected 8)");
@@ -3065,7 +3065,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif
// ABI Hash -- runtime handshake against the SDK bundle
// =============================================================================
-static const char* kEsAbiLayoutHash = "1df12cb48da3bf45";
+static const char* kEsAbiLayoutHash = "dc813d9c5d77b235";
std::string esengineGetAbiLayoutHash() {
return std::string(kEsAbiLayoutHash);
diff --git a/src/esengine/data/shaders/particle.esshader b/src/esengine/data/shaders/particle.esshader
index 992f6a00f..ee3fbb1f9 100644
--- a/src/esengine/data/shaders/particle.esshader
+++ b/src/esengine/data/shaders/particle.esshader
@@ -5,7 +5,7 @@
layout(location = 0) in vec2 a_position;
layout(location = 1) in vec2 a_texCoord;
-layout(location = 2) in vec2 a_inst_position;
+layout(location = 2) in vec3 a_inst_position;
layout(location = 3) in vec2 a_inst_size;
layout(location = 4) in float a_inst_rotation;
layout(location = 5) in vec4 a_inst_color;
@@ -15,6 +15,18 @@ layout(location = 7) in vec2 a_inst_uv_scale;
out vec2 v_texCoord;
out vec4 v_color;
+// The quad's own axes in world space: a particle faces the viewer wherever it is
+// seen from. Head-on and orthographic these come out (1,0,0) and (0,1,0), which
+// is the flat quad every 2D scene has always drawn — a billboard is not a second
+// path, it is the general case the flat one is a corner of.
+void billboardAxes(in highp vec3 worldCenter, out highp vec3 right, out highp vec3 up) {
+ highp vec3 fwd = viewDirection(worldCenter);
+ // Looking straight down the world up, that axis cannot orient the quad.
+ highp vec3 refUp = abs(fwd.y) > 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(0.0, 1.0, 0.0);
+ right = normalize(cross(refUp, fwd));
+ up = cross(fwd, right);
+}
+
void main() {
vec2 scaled = a_position * a_inst_size;
@@ -25,8 +37,11 @@ void main() {
scaled.x * sinR + scaled.y * cosR
);
- vec2 worldPos = rotated + a_inst_position;
- gl_Position = u_projection * vec4(worldPos, 0.0, 1.0);
+ highp vec3 right;
+ highp vec3 up;
+ billboardAxes(a_inst_position, right, up);
+ vec3 worldPos = a_inst_position + right * rotated.x + up * rotated.y;
+ gl_Position = u_projection * vec4(worldPos, 1.0);
v_texCoord = a_texCoord * a_inst_uv_scale + a_inst_uv_offset;
v_color = a_inst_color;
@@ -53,7 +68,7 @@ void main() {
struct VSIn {
@location(0) a_position : vec2f,
@location(1) a_texCoord : vec2f,
- @location(2) a_inst_position : vec2f,
+ @location(2) a_inst_position : vec3f,
@location(3) a_inst_size : vec2f,
@location(4) a_inst_rotation : f32,
@location(5) a_inst_color : vec4f,
@@ -76,10 +91,17 @@ struct VSOut {
scaled.x * sinR + scaled.y * cosR
);
- let worldPos = rotated + v.a_inst_position;
+ // The GLSL stage's billboardAxes, in the dialect: face the viewer, and fall
+ // back to world +Z as the reference when looking straight down world up.
+ let fwd = viewDirection(v.a_inst_position);
+ var refUp = vec3f(0.0, 1.0, 0.0);
+ if (abs(fwd.y) > 0.999) { refUp = vec3f(0.0, 0.0, 1.0); }
+ let right = normalize(cross(refUp, fwd));
+ let up = cross(fwd, right);
+ let worldPos = v.a_inst_position + right * rotated.x + up * rotated.y;
var out : VSOut;
- out.pos = frame.projection * vec4f(worldPos, 0.0, 1.0);
+ out.pos = frame.projection * vec4f(worldPos, 1.0);
out.v_texCoord = v.a_texCoord * v.a_inst_uv_scale + v.a_inst_uv_offset;
out.v_color = v.a_inst_color;
return out;
diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hpp
index ad768cf44..d40e59158 100644
--- a/src/esengine/ecs/components/ParticleEmitter.hpp
+++ b/src/esengine/ecs/components/ParticleEmitter.hpp
@@ -82,7 +82,7 @@ struct ParticleEmitter {
f32 shapeRadius{100.0f};
ES_PROPERTY(category=Shape, shown_when=shape:Rectangle)
- glm::vec2 shapeSize{100.0f, 100.0f};
+ glm::vec3 shapeSize{100.0f, 100.0f, 0.0f};
ES_PROPERTY(unit="°", category=Shape, shown_when=shape:Cone)
f32 shapeAngle{25.0f};
@@ -142,7 +142,7 @@ struct ParticleEmitter {
// Forces (grouped under the Velocity category in the inspector)
ES_PROPERTY(category=Velocity)
- glm::vec2 gravity{0.0f, 0.0f};
+ glm::vec3 gravity{0.0f, 0.0f, 0.0f};
ES_PROPERTY(min=0, category=Velocity)
f32 damping{0.0f};
diff --git a/src/esengine/ecs/components/ParticleForceField.hpp b/src/esengine/ecs/components/ParticleForceField.hpp
index b968634bb..5be39d0ab 100644
--- a/src/esengine/ecs/components/ParticleForceField.hpp
+++ b/src/esengine/ecs/components/ParticleForceField.hpp
@@ -49,7 +49,7 @@ struct ParticleForceField {
// Push direction for a Directional field (normalized at use). Point/Vortex/Drag
// derive their direction from the field→particle vector and ignore this.
ES_PROPERTY(category=Field)
- glm::vec2 direction{1.0f, 0.0f};
+ glm::vec3 direction{1.0f, 0.0f, 0.0f};
// Fade the force linearly to 0 at the radius edge (only meaningful when radius > 0).
ES_PROPERTY(category=Field)
diff --git a/src/esengine/particle/Particle.hpp b/src/esengine/particle/Particle.hpp
index 73a861235..325838e7a 100644
--- a/src/esengine/particle/Particle.hpp
+++ b/src/esengine/particle/Particle.hpp
@@ -11,8 +11,8 @@
namespace esengine::particle {
struct Particle {
- glm::vec2 position{0.0f};
- glm::vec2 velocity{0.0f};
+ glm::vec3 position{0.0f};
+ glm::vec3 velocity{0.0f};
f32 rotation = 0.0f;
f32 angular_velocity = 0.0f;
f32 lifetime = 1.0f;
diff --git a/src/esengine/particle/ParticleSystem.cpp b/src/esengine/particle/ParticleSystem.cpp
index 16ed57a8b..cbaacf46d 100644
--- a/src/esengine/particle/ParticleSystem.cpp
+++ b/src/esengine/particle/ParticleSystem.cpp
@@ -37,11 +37,12 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
if (!ff.enabled || ff.strength == 0.0f) continue;
auto& ffTransform = ffView.get<ecs::Transform>(ffEntity);
ffTransform.ensureDecomposed();
- f32 dl = std::sqrt(ff.direction.x * ff.direction.x + ff.direction.y * ff.direction.y);
+ f32 dl = std::sqrt(ff.direction.x * ff.direction.x + ff.direction.y * ff.direction.y
+ + ff.direction.z * ff.direction.z);
ForceFieldInstance inst;
inst.type = ff.type;
- inst.position = glm::vec2(ffTransform.worldPosition.x, ffTransform.worldPosition.y);
- inst.direction = dl > 1e-6f ? ff.direction / dl : glm::vec2(1.0f, 0.0f);
+ inst.position = ffTransform.worldPosition;
+ inst.direction = dl > 1e-6f ? ff.direction / dl : glm::vec3(1.0f, 0.0f, 0.0f);
inst.strength = ff.strength;
inst.radius = ff.radius;
inst.radiusSq = ff.radius * ff.radius;
@@ -88,7 +89,7 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
if (emitter.trailEnabled && state.trail_count.size() != state.pool.capacity()) {
state.trail_count.assign(state.pool.capacity(), 0);
state.trail_pos.assign(static_cast<std::size_t>(state.pool.capacity()) * kMaxTrailPoints,
- glm::vec2(0.0f));
+ glm::vec3(0.0f));
}
if (state.first_update && emitter.playOnStart) {
@@ -123,7 +124,7 @@ void ParticleSystem::update(ecs::Registry& registry, f32 dt) {
}
}
- glm::vec2 emitterPos(transform.worldPosition.x, transform.worldPosition.y);
+ glm::vec3 emitterPos = transform.worldPosition;
f32 emitterAngle = 0.0f;
if (transform.worldRotation.w != 1.0f || transform.worldRotation.z != 0.0f) {
emitterAngle = 2.0f * std::atan2(transform.worldRotation.z,
@@ -233,15 +234,17 @@ const EmitterState* ParticleSystem::getState(Entity entity) const {
return it != states_.end() ? &it->second : nullptr;
}
-// Rotate a 2D vector by a precomputed cos/sin.
-static inline glm::vec2 rotate2(glm::vec2 v, f32 cosA, f32 sinA) {
- return glm::vec2(v.x * cosA - v.y * sinA, v.x * sinA + v.y * cosA);
+// Turn a vector about Z by a precomputed cos/sin — the emitter's own rotation,
+// which is a turn in the plane whether or not the particle has depth. Depth rides
+// through it, as it does under any rotation about the axis it lies on.
+static inline glm::vec3 rotate2(glm::vec3 v, f32 cosA, f32 sinA) {
+ return glm::vec3(v.x * cosA - v.y * sinA, v.x * sinA + v.y * cosA, v.z);
}
void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,
const ecs::Transform& transform,
EmitterState& state, u32 count) {
- glm::vec2 emitterPos(transform.worldPosition.x, transform.worldPosition.y);
+ glm::vec3 emitterPos = transform.worldPosition;
f32 emitterAngle = 0.0f;
if (transform.worldRotation.w != 1.0f || transform.worldRotation.z != 0.0f) {
emitterAngle = 2.0f * std::atan2(transform.worldRotation.z,
@@ -249,13 +252,13 @@ void ParticleSystem::emitParticles(const ecs::ParticleEmitter& emitter,
}
bool isWorldSpace = emitter.simulationSpace ==
static_cast<i32>(ecs::SimulationSpace::World);
- emitInto(emitter, state, emitterPos, emitterAngle, isWorldSpace, glm::vec2(0.0f), count,
+ emitInto(emitter, state, emitterPos, emitterAngle, isWorldSpace, glm::vec3(0.0f), count,
/*allowBirthTrigger=*/true);
}
void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState& state,
- glm::vec2 emitterPos, f32 emitterAngle, bool isWorldSpace,
- glm::vec2 velocityBias, u32 count, bool allowBirthTrigger) {
+ glm::vec3 emitterPos, f32 emitterAngle, bool isWorldSpace,
+ glm::vec3 velocityBias, u32 count, bool allowBirthTrigger) {
// Record each spawned particle for a Birth-triggered sub-emitter (in world
// space, since a sub-burst is a world event).
bool recordBirth = allowBirthTrigger &&
@@ -293,7 +296,7 @@ void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState&
p->angular_velocity = randomRange(emitter.angularVelocityMin,
emitter.angularVelocityMax);
- glm::vec2 offset = randomShapeOffset(emitter);
+ glm::vec3 offset = randomShapeOffset(emitter);
if (isWorldSpace) {
// Rotate the spawn footprint by the emitter angle so the emission
// shape agrees with the (already-rotated) velocity below; otherwise a
@@ -306,7 +309,7 @@ void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState&
}
f32 speed = randomRange(emitter.speedMin, emitter.speedMax);
- glm::vec2 dir;
+ glm::vec3 dir;
auto shape = static_cast<ecs::EmitterShape>(emitter.shape);
switch (shape) {
case ecs::EmitterShape::Circle: {
@@ -321,7 +324,7 @@ void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState&
case ecs::EmitterShape::Cone: {
f32 halfAngle = emitter.shapeAngle * 0.5f * math::DEG_TO_RAD;
f32 angle = randomRange(-halfAngle, halfAngle);
- dir = glm::vec2(std::sin(angle), std::cos(angle));
+ dir = glm::vec3(std::sin(angle), std::cos(angle), 0.0f);
break;
}
// Point and Rectangle share one aiming rule: the shape decides WHERE a
@@ -342,9 +345,9 @@ void ParticleSystem::emitInto(const ecs::ParticleEmitter& emitter, EmitterState&
p->sprite_frame = 0;
if (recordBirth) {
- glm::vec2 worldPos = isWorldSpace ? p->position
+ glm::vec3 worldPos = isWorldSpace ? p->position
: emitterPos + rotate2(p->position, cosA, sinA);
- glm::vec2 worldVel = isWorldSpace ? p->velocity : rotate2(p->velocity, cosA, sinA);
+ glm::vec3 worldVel = isWorldSpace ? p->velocity : rotate2(p->velocity, cosA, sinA);
subemit_requests_.push_back({worldPos, worldVel});
}
}
@@ -403,8 +406,9 @@ static f32 sampleSizeLut(const SizeLut& lut, f32 t) {
// Fold one force field into a world-space particle's velocity.
static void applyForceField(const ForceFieldInstance& ff, Particle& p, f32 dt) {
- glm::vec2 toField = ff.position - p.position; // field ← particle
- f32 distSq = toField.x * toField.x + toField.y * toField.y;
+ glm::vec3 toField = ff.position - p.position; // field ← particle
+ // The zone is a ball: a radius that drops depth pulls on particles a room away.
+ f32 distSq = toField.x * toField.x + toField.y * toField.y + toField.z * toField.z;
f32 factor = 1.0f;
if (ff.radius > 0.0f) {
if (distSq > ff.radiusSq) return; // outside the zone
@@ -422,9 +426,14 @@ static void applyForceField(const ForceFieldInstance& ff, Particle& p, f32 dt) {
case ecs::ForceFieldType::Vortex: {
f32 d = std::sqrt(distSq);
if (d > 1e-4f) {
- glm::vec2 radial = -toField / d; // field → particle
- glm::vec2 perp(-radial.y, radial.x); // tangent (CCW swirl)
- p.velocity += perp * (ff.strength * factor * dt);
+ glm::vec3 radial = -toField / d; // field → particle
+ // A vortex needs an axis to swirl about, and the field's own
+ // direction is the one it has; world up when it names none.
+ glm::vec3 axis = glm::length(ff.direction) > 1e-6f
+ ? glm::normalize(ff.direction) : glm::vec3(0.0f, 0.0f, 1.0f);
+ glm::vec3 perp = glm::cross(axis, radial);
+ f32 pl = glm::length(perp);
+ if (pl > 1e-6f) p.velocity += (perp / pl) * (ff.strength * factor * dt);
}
break;
}
@@ -437,7 +446,7 @@ static void applyForceField(const ForceFieldInstance& ff, Particle& p, f32 dt) {
void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
EmitterState& state, f32 dt,
const ColorLut* colorLut, const SizeLut* sizeLut,
- glm::vec2 emitterPos, f32 emitterAngle,
+ glm::vec3 emitterPos, f32 emitterAngle,
bool isWorldSpace) {
auto sizeEasing = static_cast<EasingType>(emitter.sizeEasing);
auto colorEasing = static_cast<EasingType>(emitter.colorEasing);
@@ -472,9 +481,9 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
if (p.age >= p.lifetime) {
if (recordDeath) {
- glm::vec2 worldPos = isWorldSpace ? p.position
+ glm::vec3 worldPos = isWorldSpace ? p.position
: emitterPos + rotate2(p.position, cosA, sinA);
- glm::vec2 worldVel = isWorldSpace ? p.velocity : rotate2(p.velocity, cosA, sinA);
+ glm::vec3 worldVel = isWorldSpace ? p.velocity : rotate2(p.velocity, cosA, sinA);
subemit_requests_.push_back({worldPos, worldVel});
}
u32 idx = static_cast<u32>(&p - &state.pool.particles()[0]);
@@ -494,9 +503,12 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
p.position += p.velocity * dt;
if (noiseOn) {
- glm::vec2 sample = p.position * emitter.noiseFrequency + noiseScroll;
- p.position += noise::curl(sample, emitter.noiseOctaves) *
- emitter.noiseStrength * dt;
+ // The curl field is a 2D flow, sampled on the plane the particle is
+ // over. Depth passes through it: turbulence that also pushed on z
+ // would be a different field, not this one read further.
+ glm::vec2 sample = glm::vec2(p.position) * emitter.noiseFrequency + noiseScroll;
+ glm::vec2 flow = noise::curl(sample, emitter.noiseOctaves);
+ p.position += glm::vec3(flow, 0.0f) * emitter.noiseStrength * dt;
}
// Floor collision: a particle that has fallen through the floor plane while
@@ -517,10 +529,10 @@ void ParticleSystem::updateParticles(const ecs::ParticleEmitter& emitter,
if (trailOn) {
auto idx = static_cast<std::size_t>(&p - state.pool.particles().data());
u8& cnt = state.trail_count[idx];
- glm::vec2* ring = &state.trail_pos[idx * kMaxTrailPoints];
+ glm::vec3* ring = &state.trail_pos[idx * kMaxTrailPoints];
bool record = cnt == 0;
if (!record) {
- glm::vec2 d = p.position - ring[cnt - 1];
+ glm::vec3 d = p.position - ring[cnt - 1];
record = glm::dot(d, d) >= trailMinDistSq;
}
if (record) {
@@ -579,33 +591,41 @@ f32 ParticleSystem::randomRange(f32 min, f32 max) {
return dist(rng_);
}
-glm::vec2 ParticleSystem::randomDirection(f32 angleMin, f32 angleMax) {
+// 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.
+glm::vec3 ParticleSystem::randomDirection(f32 angleMin, f32 angleMax) {
f32 angleDeg = randomRange(angleMin, angleMax);
f32 angleRad = angleDeg * math::DEG_TO_RAD;
- return glm::vec2(std::cos(angleRad), std::sin(angleRad));
+ return glm::vec3(std::cos(angleRad), std::sin(angleRad), 0.0f);
}
-glm::vec2 ParticleSystem::randomShapeOffset(const ecs::ParticleEmitter& emitter) {
+glm::vec3 ParticleSystem::randomShapeOffset(const ecs::ParticleEmitter& emitter) {
auto shape = static_cast<ecs::EmitterShape>(emitter.shape);
switch (shape) {
case ecs::EmitterShape::Circle: {
f32 angle = randomRange(0.0f, math::TWO_PI);
f32 radius = randomRange(0.0f, emitter.shapeRadius);
- return glm::vec2(std::cos(angle) * radius, std::sin(angle) * radius);
+ return glm::vec3(std::cos(angle) * radius, std::sin(angle) * radius, 0.0f);
}
case ecs::EmitterShape::Rectangle: {
+ // A BOX where the scene gives it depth: `shapeSize.z` of 0 is the flat
+ // rectangle every 2D emitter has spawned from, so one field covers both.
f32 x = randomRange(-emitter.shapeSize.x * 0.5f, emitter.shapeSize.x * 0.5f);
f32 y = randomRange(-emitter.shapeSize.y * 0.5f, emitter.shapeSize.y * 0.5f);
- return glm::vec2(x, y);
+ f32 z = emitter.shapeSize.z > 0.0f
+ ? randomRange(-emitter.shapeSize.z * 0.5f, emitter.shapeSize.z * 0.5f) : 0.0f;
+ return glm::vec3(x, y, z);
}
case ecs::EmitterShape::Cone: {
f32 halfAngle = emitter.shapeAngle * 0.5f * math::DEG_TO_RAD;
f32 angle = randomRange(-halfAngle, halfAngle);
- return glm::vec2(std::sin(angle), std::cos(angle)) * randomRange(0.0f, emitter.shapeRadius);
+ return glm::vec3(std::sin(angle), std::cos(angle), 0.0f)
+ * randomRange(0.0f, emitter.shapeRadius);
}
case ecs::EmitterShape::Point:
default:
- return glm::vec2(0.0f);
+ return glm::vec3(0.0f);
}
}
diff --git a/src/esengine/particle/ParticleSystem.hpp b/src/esengine/particle/ParticleSystem.hpp
index c0a45d36c..f1abc253d 100644
--- a/src/esengine/particle/ParticleSystem.hpp
+++ b/src/esengine/particle/ParticleSystem.hpp
@@ -37,8 +37,8 @@ inline constexpr int kMaxTrailPoints = 12;
// once per update() so the hot loop touches no components.
struct ForceFieldInstance {
i32 type = 0;
- glm::vec2 position{0.0f};
- glm::vec2 direction{1.0f, 0.0f}; // pre-normalized (Directional only)
+ glm::vec3 position{0.0f};
+ glm::vec3 direction{1.0f, 0.0f, 0.0f}; // pre-normalized (Directional only)
f32 strength = 0.0f;
f32 radius = 0.0f; // 0 = unbounded
f32 radiusSq = 0.0f;
@@ -60,7 +60,7 @@ struct EmitterState {
// enables trails (free otherwise). trail_pos is a flat [capacity × kMaxTrailPoints]
// ring of raw particle-space positions (oldest→newest); trail_count is how many
// slots each particle has filled.
- std::vector<glm::vec2> trail_pos;
+ std::vector<glm::vec3> trail_pos;
std::vector<u8> trail_count;
explicit EmitterState(u32 capacity) : pool(capacity) {}
@@ -108,8 +108,8 @@ private:
// `allowBirthTrigger` records Birth events for a nested sub-emitter; false for a
// 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,
- glm::vec2 emitterPos, f32 emitterAngle, bool isWorldSpace,
- glm::vec2 velocityBias, u32 count, bool allowBirthTrigger);
+ glm::vec3 emitterPos, f32 emitterAngle, bool isWorldSpace,
+ glm::vec3 velocityBias, u32 count, bool allowBirthTrigger);
// Fire the referenced child emitter's burst at each pending sub-emit request.
void drainSubEmitters(ecs::Registry& registry, Entity child,
@@ -117,15 +117,15 @@ private:
void updateParticles(const ecs::ParticleEmitter& emitter, EmitterState& state, f32 dt,
const ColorLut* colorLut, const SizeLut* sizeLut,
- glm::vec2 emitterPos, f32 emitterAngle, bool isWorldSpace);
+ glm::vec3 emitterPos, f32 emitterAngle, bool isWorldSpace);
f32 randomRange(f32 min, f32 max);
- glm::vec2 randomDirection(f32 angleMin, f32 angleMax);
- glm::vec2 randomShapeOffset(const ecs::ParticleEmitter& emitter);
+ glm::vec3 randomDirection(f32 angleMin, f32 angleMax);
+ glm::vec3 randomShapeOffset(const ecs::ParticleEmitter& emitter);
// 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::vec2 position; glm::vec2 velocity; };
+ struct SubEmitRequest { glm::vec3 position; glm::vec3 velocity; };
std::vector<SubEmitRequest> subemit_requests_;
std::unordered_map<Entity, EmitterState> states_;
diff --git a/src/esengine/renderer/plugins/ParticlePlugin.cpp b/src/esengine/renderer/plugins/ParticlePlugin.cpp
index 475358354..bca370a7a 100644
--- a/src/esengine/renderer/plugins/ParticlePlugin.cpp
+++ b/src/esengine/renderer/plugins/ParticlePlugin.cpp
@@ -24,14 +24,14 @@ namespace {
// (locations 2-7). The GPU expands the 4-vertex quad; the CPU only fills these 40 bytes
// per particle (vs. the old 4 verts + 6 indices), which is the whole point of RC7-1.
struct ParticleInstanceData {
- f32 px, py; // a_inst_position (world)
+ f32 px, py, pz; // a_inst_position (world)
f32 sx, sy; // a_inst_size
f32 rotation; // a_inst_rotation
u32 color; // a_inst_color (RGBA8)
f32 uvOffsetX, uvOffsetY;
f32 uvScaleX, uvScaleY;
};
-static_assert(sizeof(ParticleInstanceData) == 40, "instance stride must match the VAO layout");
+static_assert(sizeof(ParticleInstanceData) == 44, "instance stride must match the VAO layout");
} // namespace
void ParticlePlugin::init(RenderFrameContext& ctx) {
@@ -116,15 +116,17 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
u32 i = 0;
state->pool.forEachAlive([&](const particle::Particle& p) {
- glm::vec2 worldPos;
+ glm::vec3 worldPos;
glm::vec2 size;
if (isLocalSpace) {
- glm::vec2 rel = p.position * emitterScale;
+ // The emitter's own turn is about Z, as a flat scene's is; depth
+ // rides through it untouched rather than being dropped.
+ glm::vec3 rel = p.position * glm::vec3(emitterScale, 1.0f);
if (std::abs(emitterAngle) > 0.001f) {
- worldPos = glm::vec2(emitterWorldPos) +
- glm::vec2(rel.x * cosA - rel.y * sinA, rel.x * sinA + rel.y * cosA);
+ worldPos = emitterWorldPos +
+ glm::vec3(rel.x * cosA - rel.y * sinA, rel.x * sinA + rel.y * cosA, rel.z);
} else {
- worldPos = glm::vec2(emitterWorldPos) + rel;
+ worldPos = emitterWorldPos + rel;
}
size = glm::vec2(p.size) * emitterScale;
} else {
@@ -141,7 +143,7 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
}
ParticleInstanceData& d = inst[i++];
- d.px = worldPos.x; d.py = worldPos.y;
+ d.px = worldPos.x; d.py = worldPos.y; d.pz = worldPos.z;
d.sx = size.x; d.sy = size.y;
d.rotation = p.rotation;
d.color = packColor(p.color);
@@ -189,38 +191,41 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
};
const int keep = std::min(std::max(emitter.trailPoints, 2), particle::kMaxTrailPoints);
const auto& particles = state->pool.particles();
- auto toWorld = [&](glm::vec2 pos) -> glm::vec2 {
+ auto toWorld = [&](glm::vec3 pos) -> glm::vec3 {
if (!isLocalSpace) return pos;
- glm::vec2 rel = pos * emitterScale;
+ glm::vec3 rel = pos * glm::vec3(emitterScale, 1.0f);
if (std::abs(emitterAngle) > 0.001f)
- return glm::vec2(emitterWorldPos) +
- glm::vec2(rel.x * cosA - rel.y * sinA, rel.x * sinA + rel.y * cosA);
- return glm::vec2(emitterWorldPos) + rel;
+ return emitterWorldPos +
+ glm::vec3(rel.x * cosA - rel.y * sinA, rel.x * sinA + rel.y * cosA, rel.z);
+ return emitterWorldPos + rel;
};
for (std::size_t idx = 0; idx < particles.size(); ++idx) {
const particle::Particle& p = particles[idx];
if (!p.alive || state->trail_count[idx] == 0) continue;
- const glm::vec2* ring = &state->trail_pos[idx * particle::kMaxTrailPoints];
+ const glm::vec3* ring = &state->trail_pos[idx * particle::kMaxTrailPoints];
// Centerline: recorded points (oldest→newest) then the live head.
trail_center_.clear();
int m = std::min<int>(state->trail_count[idx], keep);
for (int k = 0; k < m; ++k) trail_center_.push_back(toWorld(ring[k]));
- glm::vec2 head = toWorld(p.position);
- glm::vec2 dHead = head - trail_center_.back();
+ glm::vec3 head = toWorld(p.position);
+ glm::vec3 dHead = head - trail_center_.back();
if (glm::dot(dHead, dHead) > 1e-4f) trail_center_.push_back(head);
const int n = static_cast<int>(trail_center_.size());
if (n < 2) continue;
// 2 verts per point: t runs 0 at the faded zero-width tail (oldest) → 1
// at the full-width head carrying the particle's current colour.
+ // Widened in the scene's own plane, not toward the eye: the
+ // centreline carries depth, but a billboarded ribbon is a
+ // per-segment turn this vertex path has no room for.
trail_verts_.clear();
glm::vec2 lastTangent(1.0f, 0.0f);
for (int j = 0; j < n; ++j) {
- const glm::vec2& a = trail_center_[j == 0 ? 0 : j - 1];
- const glm::vec2& b = trail_center_[j + 1 == n ? j : j + 1];
- glm::vec2 seg = b - a;
+ const glm::vec3& a = trail_center_[j == 0 ? 0 : j - 1];
+ const glm::vec3& b = trail_center_[j + 1 == n ? j : j + 1];
+ glm::vec2 seg = glm::vec2(b) - glm::vec2(a);
f32 len = std::sqrt(seg.x * seg.x + seg.y * seg.y);
glm::vec2 tangent = len > 1e-6f ? seg / len : lastTangent;
lastTangent = tangent;
@@ -232,8 +237,9 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {
col.a *= t;
u32 packed = packColor(col);
- trail_verts_.push_back({{trail_center_[j] + perp * halfW, emitterWorldPos.z}, packed, glm::vec2(1.0f - t, 0.0f)});
- trail_verts_.push_back({{trail_center_[j] - perp * halfW, emitterWorldPos.z}, packed, glm::vec2(1.0f - t, 1.0f)});
+ const glm::vec3& c = trail_center_[j];
+ trail_verts_.push_back({{c.x + perp.x * halfW, c.y + perp.y * halfW, c.z}, packed, glm::vec2(1.0f - t, 0.0f)});
+ trail_verts_.push_back({{c.x - perp.x * halfW, c.y - perp.y * halfW, c.z}, packed, glm::vec2(1.0f - t, 1.0f)});
}
trail_indices_.clear();
diff --git a/src/esengine/renderer/plugins/ParticlePlugin.hpp b/src/esengine/renderer/plugins/ParticlePlugin.hpp
index 0980a5e20..4b288f067 100644
--- a/src/esengine/renderer/plugins/ParticlePlugin.hpp
+++ b/src/esengine/renderer/plugins/ParticlePlugin.hpp
@@ -31,7 +31,7 @@ private:
resource::ShaderHandle particle_shader_handle_;
// Reused per-frame scratch for per-particle trail ribbons.
- std::vector<glm::vec2> trail_center_; ///< Centerline (world), oldest→head.
+ std::vector<glm::vec3> trail_center_; ///< Centerline (world), oldest→head.
std::vector<BatchVertex> trail_verts_; ///< 2 verts per centerline point.
std::vector<u32> trail_indices_; ///< 6 indices per segment.
};
diff --git a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
index 16ad175de..13748b565 100644
--- a/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
+++ b/src/esengine/renderer/rhi/ShaderEmbeds.generated.hpp
@@ -587,7 +587,7 @@ inline constexpr const char* PARTICLE = R"esshader(#pragma shader "ParticleInsta
layout(location = 0) in vec2 a_position;
layout(location = 1) in vec2 a_texCoord;
-layout(location = 2) in vec2 a_inst_position;
+layout(location = 2) in vec3 a_inst_position;
layout(location = 3) in vec2 a_inst_size;
layout(location = 4) in float a_inst_rotation;
layout(location = 5) in vec4 a_inst_color;
@@ -597,6 +597,18 @@ layout(location = 7) in vec2 a_inst_uv_scale;
out vec2 v_texCoord;
out vec4 v_color;
+// The quad's own axes in world space: a particle faces the viewer wherever it is
+// seen from. Head-on and orthographic these come out (1,0,0) and (0,1,0), which
+// is the flat quad every 2D scene has always drawn — a billboard is not a second
+// path, it is the general case the flat one is a corner of.
+void billboardAxes(in highp vec3 worldCenter, out highp vec3 right, out highp vec3 up) {
+ highp vec3 fwd = viewDirection(worldCenter);
+ // Looking straight down the world up, that axis cannot orient the quad.
+ highp vec3 refUp = abs(fwd.y) > 0.999 ? vec3(0.0, 0.0, 1.0) : vec3(0.0, 1.0, 0.0);
+ right = normalize(cross(refUp, fwd));
+ up = cross(fwd, right);
+}
+
void main() {
vec2 scaled = a_position * a_inst_size;
@@ -607,8 +619,11 @@ void main() {
scaled.x * sinR + scaled.y * cosR
);
- vec2 worldPos = rotated + a_inst_position;
- gl_Position = u_projection * vec4(worldPos, 0.0, 1.0);
+ highp vec3 right;
+ highp vec3 up;
+ billboardAxes(a_inst_position, right, up);
+ vec3 worldPos = a_inst_position + right * rotated.x + up * rotated.y;
+ gl_Position = u_projection * vec4(worldPos, 1.0);
v_texCoord = a_texCoord * a_inst_uv_scale + a_inst_uv_offset;
v_color = a_inst_color;
@@ -635,7 +650,7 @@ void main() {
struct VSIn {
@location(0) a_position : vec2f,
@location(1) a_texCoord : vec2f,
- @location(2) a_inst_position : vec2f,
+ @location(2) a_inst_position : vec3f,
@location(3) a_inst_size : vec2f,
@location(4) a_inst_rotation : f32,
@location(5) a_inst_color : vec4f,
@@ -658,10 +673,17 @@ struct VSOut {
scaled.x * sinR + scaled.y * cosR
);
- let worldPos = rotated + v.a_inst_position;
+ // The GLSL stage's billboardAxes, in the dialect: face the viewer, and fall
+ // back to world +Z as the reference when looking straight down world up.
+ let fwd = viewDirection(v.a_inst_position);
+ var refUp = vec3f(0.0, 1.0, 0.0);
+ if (abs(fwd.y) > 0.999) { refUp = vec3f(0.0, 0.0, 1.0); }
+ let right = normalize(cross(refUp, fwd));
+ let up = cross(fwd, right);
+ let worldPos = v.a_inst_position + right * rotated.x + up * rotated.y;
var out : VSOut;
- out.pos = frame.projection * vec4f(worldPos, 0.0, 1.0);
+ out.pos = frame.projection * vec4f(worldPos, 1.0);
out.v_texCoord = v.a_texCoord * v.a_inst_uv_scale + v.a_inst_uv_offset;
out.v_color = v.a_inst_color;
return out;
diff --git a/src/esengine/renderer/rhi/TransientBufferPool.cpp b/src/esengine/renderer/rhi/TransientBufferPool.cpp
index 2f9d522de..053ef9336 100644
--- a/src/esengine/renderer/rhi/TransientBufferPool.cpp
+++ b/src/esengine/renderer/rhi/TransientBufferPool.cpp
@@ -237,16 +237,18 @@ void TransientBufferPool::setupStream(LayoutId layout) {
VertexLayoutDesc desc;
desc.attributeCount = 8;
desc.strides[0] = 16;
- desc.strides[1] = 40;
+ desc.strides[1] = 44;
desc.instanceStep[1] = true;
desc.attributes[0] = {0, 2, GfxDataType::Float, false, 0, 0};
desc.attributes[1] = {1, 2, GfxDataType::Float, false, 8, 0};
- desc.attributes[2] = {2, 2, GfxDataType::Float, false, 0, 1};
- desc.attributes[3] = {3, 2, GfxDataType::Float, false, 8, 1};
- desc.attributes[4] = {4, 1, GfxDataType::Float, false, 16, 1};
- desc.attributes[5] = {5, 4, GfxDataType::UnsignedByte, true, 20, 1};
- desc.attributes[6] = {6, 2, GfxDataType::Float, false, 24, 1};
- desc.attributes[7] = {7, 2, GfxDataType::Float, false, 32, 1};
+ // The instance position carries all three axes: a particle simulated in
+ // depth and uploaded as a pair is drawn on the plane it left.
+ desc.attributes[2] = {2, 3, GfxDataType::Float, false, 0, 1};
+ desc.attributes[3] = {3, 2, GfxDataType::Float, false, 12, 1};
+ desc.attributes[4] = {4, 1, GfxDataType::Float, false, 20, 1};
+ desc.attributes[5] = {5, 4, GfxDataType::UnsignedByte, true, 24, 1};
+ desc.attributes[6] = {6, 2, GfxDataType::Float, false, 28, 1};
+ desc.attributes[7] = {7, 2, GfxDataType::Float, false, 36, 1};
s.vertex_stride = desc.strides[1];
s.layout = device_.createVertexLayout(desc);
return;
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 97b7c8454..45ba86074 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -182,6 +182,16 @@ export const SCENES = [
// runs at the same step count, and a run nobody can reproduce is a run whose
// failures cannot be told apart from its variety.
{ id: "particles", tier: "nightly", webgpu: true, rendersOnly: "seeded it reproduces exactly, but its particles are single points — no region is flat enough for a probe to survive CI's rasterizer", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-demo.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-demo.textures.json", ESTELLA_VERIFY_STEPS: "90", ESTELLA_VERIFY_SEED: "1234" } },
+ // A camera 300 to the side, turned to look back down world -X at ONE particle.
+ // A quad fixed in the x/y plane is edge-on from there and covers nothing; a
+ // billboard faces the viewer wherever it stands, which is the whole claim.
+ { id: "particles-billboard", tier: "pr", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-billboard.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-billboard.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":90}]" } },
+ // Trail, floor collision and force fields — fixtures that existed with nothing
+ // running them. Probe-less for the reason `particles` is; each claims its path
+ // still produces a frame. PR tier: half a second each, otherwise unwatched.
+ { id: "particles-trail", tier: "pr", webgpu: true, rendersOnly: "seeded and reproducible, but a ribbon of moving comets has no flat region a probe survives", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-trail.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-trail.textures.json", ESTELLA_VERIFY_STEPS: "60", ESTELLA_VERIFY_SEED: "1234" } },
+ { id: "particles-collision", tier: "pr", webgpu: true, rendersOnly: "sparks bouncing off a floor plane are in motion at every step a probe could read", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-collision.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-collision.textures.json", ESTELLA_VERIFY_STEPS: "70", ESTELLA_VERIFY_SEED: "1234" } },
+ { id: "particles-forcefield", tier: "pr", webgpu: true, rendersOnly: "a vortex keeps every particle moving, so no cell settles", env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-forcefield.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-forcefield.textures.json", ESTELLA_VERIFY_STEPS: "80", ESTELLA_VERIFY_SEED: "1234" } },
{ id: "particles-gradient", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-gradient.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-gradient.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":90}]" } },
{ id: "particles-sizecurve", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/particle-sizecurve.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/particle-sizecurve.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "20", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":110},{\"x\":0.28,\"y\":0.5,\"rgb\":[0,0,0],\"tol\":50}]" } },
// The bright centre the chain leaves, and a corner it does not reach. Three