A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(particle): a stretched render mode lays a particle along its velocity and lengthens it with speed, and the Cocos stretched billboard maps onto it
yhh977ecf75aeec
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 23e57eeb5..63baf0bc6 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -20,6 +20,7 @@ published separately; it ships inside the editor.- **Scroll areas can be pulled past an end and spring back.** A scroll area whose movement is Elastic now does what the setting always said: a drag past an end is stiffer the further out it goes, letting go returns the content, and a flick that reaches an end bounces off it. It is opt-in per area (`ScrollMovement.Elastic`; Clamped, the default, behaves as before), and the gesture model (`ScrollMotion`, with `ScrollContainer.dragTo` and `getOverscroll`) is exported for scrolling anything else the same way.- **More easing curves.** Sine, quart, quint, expo and circ (each in, out and in-out), bounce in and in-out, and smoothstep and smootherstep join the quad, cubic, back, elastic and out-bounce curves. They are new `EasingType` members after the existing ones, so a saved tween keeps its curve, and they ease the same in a C++ tween and a script value tween.- **World content has a rectangle: `ContentRect`.** A size and the pivot the entity's transform sits on, which the `Sprite` and `Text` on the entity follow and which a `UIMask` on it clips to — no `UINode` needed, so a clipping region or a scroll viewport can stand in the world. `contentRectContains` tests a world point against it.+- **Particles can be stretched along their velocity.** `ParticleEmitter.renderMode` is `Billboard` (as before) or `Stretched`, which turns each particle's quad so its Y axis runs along the particle's velocity and makes it `size * lengthScale + speed * velocityScale` long: sparks, rain and streaks. A particle at rest keeps its own rotation. It is drawn by the CPU simulation; an emitter simulated on the GPU still draws as a billboard.- **Fade a whole group of world content with one value: `GroupOpacity`.** On an entity it fades that entity and everything under it; the opacities multiply down the hierarchy into each descendant's own alpha, as `UINode.opacity` does for a UI subtree. Sprites, text, shapes, trails and tilemap layers follow it. It is not a composited layer, so children that overlap show through one another while the group is partly faded.- **Open a Cocos Creator project from the editor.** Choosing a Cocos Creator 3.x folder in Open Project (recognised by the Creator version in its `package.json`) offers to convert its scenes and prefabs into a new Estella project beside it, `<name>-estella`, and opens that; the Cocos folder is only read. Opening the same folder again opens the converted project instead of converting twice.- **Re-import a Cocos project without losing your edits.** Run Re-import Cocos Project in a project converted from Cocos Creator and the scenes and prefabs changed on the Cocos side are brought across, new ones are added, and a document you edited here is left as it is and counted in the result. After the first conversion a message lists the components that did not come across (their data is kept on the entity, but nothing runs), most used first.diff --git a/docs/astro/src/content/docs/world/particles.mdx b/docs/astro/src/content/docs/world/particles.mdxindex 75eed9ab6..a313ce11f 100644--- a/docs/astro/src/content/docs/world/particles.mdx+++ b/docs/astro/src/content/docs/world/particles.mdx@@ -183,6 +183,9 @@ See [Noise & turbulence](#noise--turbulence-1) below.| `layer` | number | `0` | Sorting layer for draw order. || `material` | asset | none | Optional custom material/shader. || `simulationSpace` | `SimulationSpace` | `World` | `World` or `Local` (see [below](#simulation-space)). |+| `renderMode` | `ParticleRenderMode` | `Billboard` | `Billboard` faces the view; `Stretched` lays the quad along the particle's velocity (see [Stretched particles](#stretched-particles)). |+| `velocityScale` | number | `0` | `Stretched`: length added per unit of speed. |+| `lengthScale` | number | `1` | `Stretched`: the quad's own length is its size times this. || `enabled` | boolean | `true` | Disable to freeze and hide without removing the component. |### Sub-emitter@@ -458,6 +461,13 @@ splashes fade out instead of skittering forever.| `World` (default) | No — they stay where they were born | Trails, exhaust, sparks left behind a moving object || `Local` | Yes — they move with the entity's transform | Auras, shields, effects rigidly attached to a mover |+## Stretched particles++With `renderMode: Stretched` each particle's quad turns so its Y axis runs along the particle's velocity, and its length is+`size × lengthScale + speed × velocityScale` while its width stays the particle's own. Use a texture drawn pointing up: a spark,+a raindrop, a streak. A particle that is not moving keeps the rotation it was born with. Stretching is done where the CPU+simulation draws; an emitter simulated on the GPU draws as `Billboard`.+## Blend modes`BlendMode` controls how particles composite over the scene:diff --git a/docs/astro/src/content/docs/zh-cn/world/particles.mdx b/docs/astro/src/content/docs/zh-cn/world/particles.mdxindex 312b91302..e5bb8f244 100644--- a/docs/astro/src/content/docs/zh-cn/world/particles.mdx+++ b/docs/astro/src/content/docs/zh-cn/world/particles.mdx@@ -174,6 +174,9 @@ const spawnEmbers = defineSystem([Commands()], (cmds) => {| `layer` | number | `0` | 决定绘制顺序的排序层。 || `material` | asset | 无 | 可选的自定义材质/着色器。 || `simulationSpace` | `SimulationSpace` | `World` | `World` 或 `Local`(见[下](#模拟空间))。 |+| `renderMode` | `ParticleRenderMode` | `Billboard` | `Billboard` 朝向视图;`Stretched` 让四边形沿粒子速度方向拉伸(见[拉伸粒子](#拉伸粒子))。 |+| `velocityScale` | number | `0` | `Stretched`:每单位速度增加的长度。 |+| `lengthScale` | number | `1` | `Stretched`:四边形自身长度是 size 乘以它。 || `enabled` | boolean | `true` | 关掉即冻结并隐藏,而不移除组件。 |### 子发射器 (Sub-emitter)@@ -421,6 +424,12 @@ cmds.spawn()| `World`(默认) | 否——它们留在出生的地方 | 拖尾、尾焰、移动物体身后留下的火花 || `Local` | 是——它们随实体的 transform 移动 | 光环、护盾、刚性附着在移动体上的特效 |+## 拉伸粒子++`renderMode` 设为 `Stretched` 后,每个粒子的四边形会转到 Y 轴沿着粒子速度的方向,长度是+`size × lengthScale + speed × velocityScale`,宽度仍是粒子自己的大小。贴图应画成朝上的形状:火花、雨滴、拖光。+静止的粒子保持出生时的旋转。拉伸发生在 CPU 模拟的绘制处,用 GPU 模拟的发射器按 `Billboard` 绘制。+## 混合模式`BlendMode` 控制粒子如何叠加到场景上:diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.jsonindex 0e09e26d5..e48557d63 100644--- a/docs/astro/src/data/apiStability.generated.json+++ b/docs/astro/src/data/apiStability.generated.json@@ -2,11 +2,11 @@"note": "Generated by tools/api-stability.mjs from sdk/etc/*.api.md — do not edit.","counts": {"public": 115,- "beta": 172,+ "beta": 173,"experimental": 2733,"deprecated": 3},- "total": 3020,+ "total": 3021,"subsystems": [{"id": "mobile-controls",@@ -2439,6 +2439,18 @@"minigame"]},+ {+ "name": "ParticleRenderMode",+ "kind": "enum",+ "deprecated": false,+ "entries": [+ "index",+ "index.node",+ "index.native",+ "wechat",+ "minigame"+ ]+ },{"name": "Physics2D","kind": "const",diff --git a/docs/astro/src/data/components.generated.json b/docs/astro/src/data/components.generated.jsonindex 7225d00fa..00793e4d0 100644--- a/docs/astro/src/data/components.generated.json+++ b/docs/astro/src/data/components.generated.json@@ -3708,6 +3708,30 @@"Local"]},+ {+ "key": "renderMode",+ "type": "enum",+ "default": "Billboard",+ "doc": "Billboard faces the view. Stretched lays the quad's long axis (its Y) along the particle's velocity and lengthens it with speed. Drawn by the CPU simulation; a GPU-simulated emitter draws as Billboard.",+ "values": [+ "Billboard",+ "Stretched"+ ]+ },+ {+ "key": "velocityScale",+ "type": "number",+ "default": "0",+ "doc": "Stretched: how much of the particle's speed is added to the quad's length, in world units per unit of speed.",+ "range": "≥ 0"+ },+ {+ "key": "lengthScale",+ "type": "number",+ "default": "1",+ "doc": "Stretched: the quad's own length is its size times this.",+ "range": "≥ 0"+ },{"key": "enabled","type": "boolean",diff --git a/pipeline/src/import/cocos/particle.ts b/pipeline/src/import/cocos/particle.tsindex 1a4cba06b..f30b8ea01 100644--- a/pipeline/src/import/cocos/particle.ts+++ b/pipeline/src/import/cocos/particle.ts@@ -269,7 +269,14 @@ export function particleSystem(c: { enabled: boolean; data: Raw }, ctx: Particleif (isObj(m) && m._enable === true) lose(code);}const renderer = isObj(d.renderer) ? d.renderer : null;- if (renderer && num(renderer._renderMode, 0) !== 0) lose('particle-render-mode');+ const renderMode = renderer ? num(renderer._renderMode, 0) : 0;+ if (renderMode === 1) {+ out.renderMode = 1; // Stretched+ out.velocityScale = num(renderer?._velocityScale, 0);+ out.lengthScale = num(renderer?._lengthScale, 1);+ } else if (renderMode !== 0) {+ lose('particle-render-mode'); // horizontal, vertical and mesh particles have no counterpart+ }ctx.report.component('cc.ParticleSystem', partial ? 'partial' : 'mapped');return { type: 'ParticleEmitter', data: out };diff --git a/pipeline/tests/cocos-particle.test.ts b/pipeline/tests/cocos-particle.test.tsindex 7c58b18b5..a2b7bb71b 100644--- a/pipeline/tests/cocos-particle.test.ts+++ b/pipeline/tests/cocos-particle.test.ts@@ -104,6 +104,19 @@ describe('a particle system', () => {expect(validate('ParticleEmitter', def._default, d, def.assetFields)).toEqual([]);});+ it('maps a stretched billboard with its scales, and counts the render modes it cannot draw', () => {+ const stretched = convert({ renderer: { _renderMode: 1, _velocityScale: 1, _lengthScale: 7 } });+ const d = stretched.out.data as Record<string, any>;+ expect([d.renderMode, d.velocityScale, d.lengthScale]).toEqual([1, 1, 7]);+ expect(stretched.report.components['cc.ParticleSystem']).toEqual({ mapped: 1, partial: 0, unmapped: 0 });+ const def = registry.ParticleEmitter!;+ expect(validate('ParticleEmitter', def._default, d, def.assetFields)).toEqual([]);++ const mesh = convert({ renderer: { _renderMode: 4 } });+ expect(mesh.report.notes['particle-render-mode']?.count).toBe(1);+ expect((mesh.out.data as Record<string, any>).renderMode).toBeUndefined();+ });+it('counts the modules the emitter has no field for', () => {const { report } = convert({ _noiseModule: { _enable: true }, _trailModule: { _enable: true } });expect(report.notes['particle-noise']?.count).toBe(1);diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex a5eab1e85..da1eca5e1 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,11 +1,11 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 160 beta · 1966 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 1966 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"e064dcf6ece54b86"+"7e1e50433c8b93cf"```## ANCHOR_AXES — const @experimental@@ -6493,6 +6493,7 @@ endSizeMin: numbergpuSimulation: booleangravity: Vec3layer: number+lengthScale: numberlifetimeMax: numberlifetimeMin: numberlooping: boolean@@ -6504,6 +6505,7 @@ noiseScrollSpeed: numbernoiseStrength: numberplayOnStart: booleanrate: number+renderMode: ParticleRenderModerotationMax: numberrotationMin: numbershape: EmitterShape@@ -6531,6 +6533,7 @@ trailEnabled: booleantrailMinDistance: numbertrailPoints: numbertrailWidth: number+velocityScale: number```## ParticleForceField — const @experimental@@ -6557,6 +6560,12 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## ParticleRenderMode — enum @beta+```+Billboard = 0+Stretched = 1+```+## PartitionOptions — interface @experimental```entityFieldsOf: (componentType: string) => readonly string[]diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 68d471336..36540b5cc 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,11 +1,11 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 165 beta · 1985 experimental · 3 deprecated+Symbols: 115 public · 166 beta · 1985 experimental · 3 deprecated## ABI_LAYOUT_HASH — const @experimental```-"e064dcf6ece54b86"+"7e1e50433c8b93cf"```## ANCHOR_AXES — const @experimental@@ -6696,6 +6696,7 @@ endSizeMin: numbergpuSimulation: booleangravity: Vec3layer: number+lengthScale: numberlifetimeMax: numberlifetimeMin: numberlooping: boolean@@ -6707,6 +6708,7 @@ noiseScrollSpeed: numbernoiseStrength: numberplayOnStart: booleanrate: number+renderMode: ParticleRenderModerotationMax: numberrotationMin: numbershape: EmitterShape@@ -6734,6 +6736,7 @@ trailEnabled: booleantrailMinDistance: numbertrailPoints: numbertrailWidth: number+velocityScale: number```## ParticleForceField — const @experimental@@ -6760,6 +6763,12 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## ParticleRenderMode — enum @beta+```+Billboard = 0+Stretched = 1+```+## PartitionOptions — interface @experimental```entityFieldsOf: (componentType: string) => readonly string[]diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 0a90cfbf7..01a91ec76 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 162 beta · 1965 experimental · 3 deprecated+Symbols: 115 public · 163 beta · 1965 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -6488,6 +6488,7 @@ endSizeMin: numbergpuSimulation: booleangravity: Vec3layer: number+lengthScale: numberlifetimeMax: numberlifetimeMin: numberlooping: boolean@@ -6499,6 +6500,7 @@ noiseScrollSpeed: numbernoiseStrength: numberplayOnStart: booleanrate: number+renderMode: ParticleRenderModerotationMax: numberrotationMin: numbershape: EmitterShape@@ -6526,6 +6528,7 @@ trailEnabled: booleantrailMinDistance: numbertrailPoints: numbertrailWidth: number+velocityScale: number```## ParticleForceField — const @experimental@@ -6552,6 +6555,12 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## ParticleRenderMode — enum @beta+```+Billboard = 0+Stretched = 1+```+## PartitionOptions — interface @experimental```entityFieldsOf: (componentType: string) => readonly string[]diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 6f8f44d00..c699c453b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 160 beta · 1987 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 1987 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -6783,6 +6783,7 @@ endSizeMin: numbergpuSimulation: booleangravity: Vec3layer: number+lengthScale: numberlifetimeMax: numberlifetimeMin: numberlooping: boolean@@ -6794,6 +6795,7 @@ noiseScrollSpeed: numbernoiseStrength: numberplayOnStart: booleanrate: number+renderMode: ParticleRenderModerotationMax: numberrotationMin: numbershape: EmitterShape@@ -6821,6 +6823,7 @@ trailEnabled: booleantrailMinDistance: numbertrailPoints: numbertrailWidth: number+velocityScale: number```## ParticleForceField — const @experimental@@ -6847,6 +6850,12 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## ParticleRenderMode — enum @beta+```+Billboard = 0+Stretched = 1+```+## PartitionOptions — interface @experimental```entityFieldsOf: (componentType: string) => readonly string[]diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 9a498d7e5..310bc9022 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 115 public · 160 beta · 1978 experimental · 3 deprecated+Symbols: 115 public · 161 beta · 1978 experimental · 3 deprecated## ANCHOR_AXES — const @experimental```@@ -6495,6 +6495,7 @@ endSizeMin: numbergpuSimulation: booleangravity: Vec3layer: number+lengthScale: numberlifetimeMax: numberlifetimeMin: numberlooping: boolean@@ -6506,6 +6507,7 @@ noiseScrollSpeed: numbernoiseStrength: numberplayOnStart: booleanrate: number+renderMode: ParticleRenderModerotationMax: numberrotationMin: numbershape: EmitterShape@@ -6533,6 +6535,7 @@ trailEnabled: booleantrailMinDistance: numbertrailPoints: numbertrailWidth: number+velocityScale: number```## ParticleForceField — const @experimental@@ -6559,6 +6562,12 @@ static new (): ParticlePluginstatic prototype: ParticlePlugin```+## ParticleRenderMode — enum @beta+```+Billboard = 0+Stretched = 1+```+## PartitionOptions — interface @experimental```entityFieldsOf: (componentType: string) => readonly string[]diff --git a/sdk/src/core-runtime.ts b/sdk/src/core-runtime.tsindex 91c3f3869..0c270ca57 100644--- a/sdk/src/core-runtime.ts+++ b/sdk/src/core-runtime.ts@@ -165,6 +165,7 @@ export {ParticleEasing,ParticleCollisionMode,ParticleCollisionFallback,+ ParticleRenderMode,type ParticleEmitterData,ParticleForceField,ForceFieldType,diff --git a/sdk/src/ecs/bridge/ptrAccessors.generated.ts b/sdk/src/ecs/bridge/ptrAccessors.generated.tsindex ed2d168d7..59974ac52 100644--- a/sdk/src/ecs/bridge/ptrAccessors.generated.ts+++ b/sdk/src/ecs/bridge/ptrAccessors.generated.ts@@ -1267,6 +1267,9 @@ export interface ParticleEmitterPtrData {layer: number;material: number;simulationSpace: number;+ renderMode: number;+ velocityScale: number;+ lengthScale: number;enabled: boolean;subEmitterTrigger: number;subEmitterChance: number;@@ -1339,27 +1342,30 @@ export function fillParticleEmitter(out.layer = u32[(ptr + 204) >> 2] | 0;out.material = u32[(ptr + 208) >> 2];out.simulationSpace = u32[(ptr + 212) >> 2] | 0;- out.enabled = u8[ptr + 216] !== 0;- out.subEmitterTrigger = u32[(ptr + 220) >> 2] | 0;- out.subEmitterChance = f32[(ptr + 224) >> 2];- out.subEmitterInheritVelocity = f32[(ptr + 228) >> 2];- out.subEmitter = u32[(ptr + 232) >> 2];- out.trailEnabled = u8[ptr + 236] !== 0;- out.trailWidth = f32[(ptr + 240) >> 2];- out.trailPoints = u32[(ptr + 244) >> 2] | 0;- out.trailMinDistance = f32[(ptr + 248) >> 2];- out.collisionEnabled = u8[ptr + 252] !== 0;- out.collisionFloor = f32[(ptr + 256) >> 2];- out.collisionMode = u32[(ptr + 260) >> 2] | 0;- out.collisionMask = u32[(ptr + 264) >> 2];- out.collisionQueryBudget = u32[(ptr + 268) >> 2] | 0;- out.collisionMaxDistance = f32[(ptr + 272) >> 2];- out.collisionFallback = u32[(ptr + 276) >> 2] | 0;- out.collisionEvents = u8[ptr + 280] !== 0;- out.collisionEventBudget = u32[(ptr + 284) >> 2] | 0;- out.collisionBounce = f32[(ptr + 288) >> 2];- out.collisionFriction = f32[(ptr + 292) >> 2];- out.collisionLifetimeLoss = f32[(ptr + 296) >> 2];+ out.renderMode = u32[(ptr + 216) >> 2] | 0;+ out.velocityScale = f32[(ptr + 220) >> 2];+ out.lengthScale = f32[(ptr + 224) >> 2];+ out.enabled = u8[ptr + 228] !== 0;+ out.subEmitterTrigger = u32[(ptr + 232) >> 2] | 0;+ out.subEmitterChance = f32[(ptr + 236) >> 2];+ out.subEmitterInheritVelocity = f32[(ptr + 240) >> 2];+ out.subEmitter = u32[(ptr + 244) >> 2];+ out.trailEnabled = u8[ptr + 248] !== 0;+ out.trailWidth = f32[(ptr + 252) >> 2];+ out.trailPoints = u32[(ptr + 256) >> 2] | 0;+ out.trailMinDistance = f32[(ptr + 260) >> 2];+ out.collisionEnabled = u8[ptr + 264] !== 0;+ out.collisionFloor = f32[(ptr + 268) >> 2];+ out.collisionMode = u32[(ptr + 272) >> 2] | 0;+ out.collisionMask = u32[(ptr + 276) >> 2];+ out.collisionQueryBudget = u32[(ptr + 280) >> 2] | 0;+ out.collisionMaxDistance = f32[(ptr + 284) >> 2];+ out.collisionFallback = u32[(ptr + 288) >> 2] | 0;+ out.collisionEvents = u8[ptr + 292] !== 0;+ out.collisionEventBudget = u32[(ptr + 296) >> 2] | 0;+ out.collisionBounce = f32[(ptr + 300) >> 2];+ out.collisionFriction = f32[(ptr + 304) >> 2];+ out.collisionLifetimeLoss = f32[(ptr + 308) >> 2];}export function writeParticleEmitter(@@ -1411,27 +1417,30 @@ export function writeParticleEmitter(u32[(ptr + 204) >> 2] = data.layer | 0;u32[(ptr + 208) >> 2] = data.material;u32[(ptr + 212) >> 2] = data.simulationSpace | 0;- u8[ptr + 216] = data.enabled ? 1 : 0;- u32[(ptr + 220) >> 2] = data.subEmitterTrigger | 0;- f32[(ptr + 224) >> 2] = data.subEmitterChance;- f32[(ptr + 228) >> 2] = data.subEmitterInheritVelocity;- u32[(ptr + 232) >> 2] = data.subEmitter;- u8[ptr + 236] = data.trailEnabled ? 1 : 0;- f32[(ptr + 240) >> 2] = data.trailWidth;- u32[(ptr + 244) >> 2] = data.trailPoints | 0;- f32[(ptr + 248) >> 2] = data.trailMinDistance;- u8[ptr + 252] = data.collisionEnabled ? 1 : 0;- f32[(ptr + 256) >> 2] = data.collisionFloor;- u32[(ptr + 260) >> 2] = data.collisionMode | 0;- u32[(ptr + 264) >> 2] = data.collisionMask;- u32[(ptr + 268) >> 2] = data.collisionQueryBudget | 0;- f32[(ptr + 272) >> 2] = data.collisionMaxDistance;- u32[(ptr + 276) >> 2] = data.collisionFallback | 0;- u8[ptr + 280] = data.collisionEvents ? 1 : 0;- u32[(ptr + 284) >> 2] = data.collisionEventBudget | 0;- f32[(ptr + 288) >> 2] = data.collisionBounce;- f32[(ptr + 292) >> 2] = data.collisionFriction;- f32[(ptr + 296) >> 2] = data.collisionLifetimeLoss;+ u32[(ptr + 216) >> 2] = data.renderMode | 0;+ f32[(ptr + 220) >> 2] = data.velocityScale;+ f32[(ptr + 224) >> 2] = data.lengthScale;+ u8[ptr + 228] = data.enabled ? 1 : 0;+ u32[(ptr + 232) >> 2] = data.subEmitterTrigger | 0;+ f32[(ptr + 236) >> 2] = data.subEmitterChance;+ f32[(ptr + 240) >> 2] = data.subEmitterInheritVelocity;+ u32[(ptr + 244) >> 2] = data.subEmitter;+ u8[ptr + 248] = data.trailEnabled ? 1 : 0;+ f32[(ptr + 252) >> 2] = data.trailWidth;+ u32[(ptr + 256) >> 2] = data.trailPoints | 0;+ f32[(ptr + 260) >> 2] = data.trailMinDistance;+ u8[ptr + 264] = data.collisionEnabled ? 1 : 0;+ f32[(ptr + 268) >> 2] = data.collisionFloor;+ u32[(ptr + 272) >> 2] = data.collisionMode | 0;+ u32[(ptr + 276) >> 2] = data.collisionMask;+ u32[(ptr + 280) >> 2] = data.collisionQueryBudget | 0;+ f32[(ptr + 284) >> 2] = data.collisionMaxDistance;+ u32[(ptr + 288) >> 2] = data.collisionFallback | 0;+ u8[ptr + 292] = data.collisionEvents ? 1 : 0;+ u32[(ptr + 296) >> 2] = data.collisionEventBudget | 0;+ f32[(ptr + 300) >> 2] = data.collisionBounce;+ f32[(ptr + 304) >> 2] = data.collisionFriction;+ f32[(ptr + 308) >> 2] = data.collisionLifetimeLoss;}export function createParticleEmitterData(): ParticleEmitterPtrData {@@ -1481,6 +1490,9 @@ export function createParticleEmitterData(): ParticleEmitterPtrData {layer: 0,material: 0,simulationSpace: 0,+ renderMode: 0,+ velocityScale: 0,+ lengthScale: 0,enabled: false,subEmitterTrigger: 0,subEmitterChance: 0,diff --git a/sdk/src/ecs/component.generated.ts b/sdk/src/ecs/component.generated.tsindex ccb9b9b6b..dcd9165d3 100644--- a/sdk/src/ecs/component.generated.ts+++ b/sdk/src/ecs/component.generated.ts@@ -7,7 +7,7 @@import type { AssetFieldType } from '../scene/scene';import type { FieldMeta } from './component';import type { Color, Entity, Quat, Vec2, Vec3, Vec4 } from '../types';-import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleCollisionFallback, ParticleCollisionMode, ParticleEasing, ProjectionType, ReflectionAxis, ReflectionQuality, ReflectionUpdate, ScrollMovement, ShapeType, SimulationSpace, SpringBoneShape, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';+import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, ClearFlags, Dimension, EmitterShape, FlexDirection, FlexWrap, ForceFieldType, JustifyContent, LightType, MaskMode, Padding, ParticleCollisionFallback, ParticleCollisionMode, ParticleEasing, ParticleRenderMode, ProjectionType, ReflectionAxis, ReflectionQuality, ReflectionUpdate, ScrollMovement, ShapeType, SimulationSpace, SpringBoneShape, SpriteDrawMode, SpriteMaskInteraction, SubEmitterTrigger, TextAlign, TilemapOrientation, TilemapStaggerAxis, TilemapStaggerIndex, UIDisplay, UIFillMethod, UIFillOrigin, UIPointerEvents, UIPositionType, UIVisualFit, UIVisualType } from '../wasm/wasm.generated';/*** Single-source-of-truth hash of the C++/TS boundary ABI (component@@ -15,7 +15,7 @@ import type { AlignContent, AlignItems, AlignSelf, BodyType, CanvasScaleMode, Cl* getAbiLayoutHash(); BuiltinBridge.connect() compares them and refuses to* run on mismatch, because mismatched offsets read the wrong heap bytes.*/-export const ABI_LAYOUT_HASH = 'e064dcf6ece54b86';+export const ABI_LAYOUT_HASH = '7e1e50433c8b93cf';/*** One asset-valued field of a component: which field, and what kind of@@ -745,6 +745,9 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {layer: 0,material: 0,simulationSpace: 0,+ renderMode: 0,+ velocityScale: 0,+ lengthScale: 1,enabled: true,subEmitterTrigger: 0,subEmitterChance: 1,@@ -818,6 +821,9 @@ export const COMPONENT_META: Record<string, ComponentMetaEntry> = {layer: { step: 1, category: "Rendering", enumSource: "sortingLayers" },material: { category: "Rendering" },simulationSpace: { enum: [{ label: 'World', value: 0 }, { label: 'Local', value: 1 }], category: "Rendering" },+ renderMode: { enum: [{ label: 'Billboard', value: 0 }, { label: 'Stretched', value: 1 }], tooltip: "Billboard faces the view. Stretched lays the quad's long axis (its Y) along the particle's velocity and lengthens it with speed. Drawn by the CPU simulation; a GPU-simulated emitter draws as Billboard.", category: "Rendering" },+ velocityScale: { min: 0, tooltip: "Stretched: how much of the particle's speed is added to the quad's length, in world units per unit of speed.", category: "Rendering", shownWhen: { field: "renderMode", values: [1] } },+ lengthScale: { min: 0, tooltip: "Stretched: the quad's own length is its size times this.", category: "Rendering", shownWhen: { field: "renderMode", values: [1] } },subEmitterTrigger: { enum: [{ label: 'Death', value: 0 }, { label: 'Birth', value: 1 }, { label: 'Collision', value: 2 }], category: "SubEmitter" },subEmitterChance: { min: 0, max: 1, category: "SubEmitter" },subEmitterInheritVelocity: { min: 0, max: 1, category: "SubEmitter" },@@ -1766,6 +1772,9 @@ export interface ParticleEmitterData {layer: number;material: number;simulationSpace: SimulationSpace;+ renderMode: ParticleRenderMode;+ velocityScale: number;+ lengthScale: number;enabled: boolean;subEmitterTrigger: SubEmitterTrigger;subEmitterChance: number;diff --git a/sdk/src/ecs/component.ts b/sdk/src/ecs/component.tsindex 26e5920d8..96c918196 100644--- a/sdk/src/ecs/component.ts+++ b/sdk/src/ecs/component.ts@@ -28,7 +28,7 @@ import type {// C++ enum and the editor dropdowns derive from the same values. ScaleMode's// canonical values come from CanvasScaleMode (only its Cocos-compat aliases// ShowAll/NoBorder are TS-side).-import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ReflectionAxis, ReflectionQuality, ReflectionUpdate, SpriteMaskInteraction, SpriteDrawMode } from '../wasm/wasm.generated';+import { ProjectionType, ClearFlags, EmitterShape, SimulationSpace, SubEmitterTrigger, ForceFieldType, LightType, CanvasScaleMode, ShapeType, ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ParticleRenderMode, ReflectionAxis, ReflectionQuality, ReflectionUpdate, SpriteMaskInteraction, SpriteDrawMode } from '../wasm/wasm.generated';import { BlendMode } from '../render/blend';import { getDefaultContext } from './context';import type {@@ -1190,7 +1190,7 @@ export const TilemapLayer = defineBuiltin<TilemapLayerData>('TilemapLayer',// EmitterShape, SimulationSpace and ParticleEasing are re-exported from the// generated module (see the import at the top) — single-sourced from their C++// ES_ENUMs beside the component fields that serialize them.-export { ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ReflectionAxis, ReflectionQuality, ReflectionUpdate };+export { ParticleEasing, ParticleCollisionMode, ParticleCollisionFallback, ParticleRenderMode, ReflectionAxis, ReflectionQuality, ReflectionUpdate };// =============================================================================// ParticleEmitter Componentdiff --git a/sdk/src/wasm/ptrLayouts.generated.ts b/sdk/src/wasm/ptrLayouts.generated.tsindex 5a5655ecf..6e638fb45 100644--- a/sdk/src/wasm/ptrLayouts.generated.ts+++ b/sdk/src/wasm/ptrLayouts.generated.ts@@ -378,27 +378,30 @@ export const PTR_LAYOUTS: Record<string, PtrLayout> = {{ name: 'layer', type: 'i32', offset: 204 },{ name: 'material', type: 'u32', offset: 208 },{ name: 'simulationSpace', type: 'i32', offset: 212 },- { name: 'enabled', type: 'bool', offset: 216 },- { name: 'subEmitterTrigger', type: 'i32', offset: 220 },- { name: 'subEmitterChance', type: 'f32', offset: 224 },- { name: 'subEmitterInheritVelocity', type: 'f32', offset: 228 },- { name: 'subEmitter', type: 'u32', offset: 232 },- { name: 'trailEnabled', type: 'bool', offset: 236 },- { name: 'trailWidth', type: 'f32', offset: 240 },- { name: 'trailPoints', type: 'i32', offset: 244 },- { name: 'trailMinDistance', type: 'f32', offset: 248 },- { name: 'collisionEnabled', type: 'bool', offset: 252 },- { name: 'collisionFloor', type: 'f32', offset: 256 },- { name: 'collisionMode', type: 'i32', offset: 260 },- { name: 'collisionMask', type: 'u32', offset: 264 },- { name: 'collisionQueryBudget', type: 'i32', offset: 268 },- { name: 'collisionMaxDistance', type: 'f32', offset: 272 },- { name: 'collisionFallback', type: 'i32', offset: 276 },- { name: 'collisionEvents', type: 'bool', offset: 280 },- { name: 'collisionEventBudget', type: 'i32', offset: 284 },- { name: 'collisionBounce', type: 'f32', offset: 288 },- { name: 'collisionFriction', type: 'f32', offset: 292 },- { name: 'collisionLifetimeLoss', type: 'f32', offset: 296 },+ { name: 'renderMode', type: 'i32', offset: 216 },+ { name: 'velocityScale', type: 'f32', offset: 220 },+ { name: 'lengthScale', type: 'f32', offset: 224 },+ { name: 'enabled', type: 'bool', offset: 228 },+ { name: 'subEmitterTrigger', type: 'i32', offset: 232 },+ { name: 'subEmitterChance', type: 'f32', offset: 236 },+ { name: 'subEmitterInheritVelocity', type: 'f32', offset: 240 },+ { name: 'subEmitter', type: 'u32', offset: 244 },+ { name: 'trailEnabled', type: 'bool', offset: 248 },+ { name: 'trailWidth', type: 'f32', offset: 252 },+ { name: 'trailPoints', type: 'i32', offset: 256 },+ { name: 'trailMinDistance', type: 'f32', offset: 260 },+ { name: 'collisionEnabled', type: 'bool', offset: 264 },+ { name: 'collisionFloor', type: 'f32', offset: 268 },+ { name: 'collisionMode', type: 'i32', offset: 272 },+ { name: 'collisionMask', type: 'u32', offset: 276 },+ { name: 'collisionQueryBudget', type: 'i32', offset: 280 },+ { name: 'collisionMaxDistance', type: 'f32', offset: 284 },+ { name: 'collisionFallback', type: 'i32', offset: 288 },+ { name: 'collisionEvents', type: 'bool', offset: 292 },+ { name: 'collisionEventBudget', type: 'i32', offset: 296 },+ { name: 'collisionBounce', type: 'f32', offset: 300 },+ { name: 'collisionFriction', type: 'f32', offset: 304 },+ { name: 'collisionLifetimeLoss', type: 'f32', offset: 308 },],},ParticleForceField: {diff --git a/sdk/src/wasm/wasm.generated.ts b/sdk/src/wasm/wasm.generated.tsindex fc95ea0a1..43b96ad22 100644--- a/sdk/src/wasm/wasm.generated.ts+++ b/sdk/src/wasm/wasm.generated.ts@@ -222,6 +222,16 @@ export enum ParticleEasing {EaseInOut = 3,}+/**+ * The engine's `ParticleRenderMode`, generated from the C++ enum.+ *+ * @beta+ */+export enum ParticleRenderMode {+ Billboard = 0,+ Stretched = 1,+}+/*** The engine's `ProjectionType`, generated from the C++ enum.*@@ -769,6 +779,9 @@ export interface ParticleEmitter {layer: number;material: number;simulationSpace: number;+ renderMode: number;+ velocityScale: number;+ lengthScale: number;enabled: boolean;subEmitterTrigger: number;subEmitterChance: number;diff --git a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snapindex ef3ad5bed..e677a56b6 100644--- a/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap+++ b/sdk/tests/__snapshots__/component-fieldmeta-golden.test.ts.snap@@ -853,6 +853,17 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"enumSource": "sortingLayers","step": 1,},+ "lengthScale": {+ "category": "Rendering",+ "min": 0,+ "shownWhen": {+ "field": "renderMode",+ "values": [+ 1,+ ],+ },+ "tooltip": "Stretched: the quad's own length is its size times this.",+ },"lifetimeMax": {"category": "Lifetime","min": 0,@@ -896,6 +907,20 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho"category": "Emission","min": 0,},+ "renderMode": {+ "category": "Rendering",+ "enum": [+ {+ "label": "Billboard",+ "value": 0,+ },+ {+ "label": "Stretched",+ "value": 1,+ },+ ],+ "tooltip": "Billboard faces the view. Stretched lays the quad's long axis (its Y) along the particle's velocity and lengthens it with speed. Drawn by the CPU simulation; a GPU-simulated emitter draws as Billboard.",+ },"rotationMax": {"category": "Rotation","unit": "°",@@ -1105,6 +1130,17 @@ exports[`builtin FieldMeta (RC9-1 equivalence gate) > matches the golden snapsho],},},+ "velocityScale": {+ "category": "Rendering",+ "min": 0,+ "shownWhen": {+ "field": "renderMode",+ "values": [+ 1,+ ],+ },+ "tooltip": "Stretched: how much of the particle's speed is added to the quad's length, in world units per unit of speed.",+ },},"ParticleForceField": {"direction": {diff --git a/src/esengine/aot/EngineDigest.generated.h b/src/esengine/aot/EngineDigest.generated.hindex 014b06b43..76d7a9876 100644--- a/src/esengine/aot/EngineDigest.generated.h+++ b/src/esengine/aot/EngineDigest.generated.h@@ -6,7 +6,7 @@/* One per address width, because the width is IN the digest: a host thattook the other one would refuse every module built for it. */-#define ES_ENGINE_ABI_DIGEST_32 0xdc0775787030c60fULL-#define ES_ENGINE_ABI_DIGEST_64 0x1cab327a1c52a33bULL+#define ES_ENGINE_ABI_DIGEST_32 0x9b05ee5f4e1f8502ULL+#define ES_ENGINE_ABI_DIGEST_64 0x2ce1a65275f59b66ULL#define ES_ENGINE_ABI_DIGEST \(sizeof(es_addr_t) == 8 ? ES_ENGINE_ABI_DIGEST_64 : ES_ENGINE_ABI_DIGEST_32)diff --git a/src/esengine/bindings/EditorAPI.generated.cpp b/src/esengine/bindings/EditorAPI.generated.cppindex 7cb55df02..291a0a52e 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 f3c0b41d2c68bec0+ * @schema_hash b635f84e4d129fb8*/-#define ES_EDITOR_API_SCHEMA_HASH "f3c0b41d2c68bec0"+#define ES_EDITOR_API_SCHEMA_HASH "b635f84e4d129fb8"#include <emscripten/bind.h>#include <string>@@ -513,6 +513,9 @@ std::string editor_getComponentSchema(const std::string& name) {{"key":"layer","type":"int","group":"ParticleEmitter"},{"key":"material","type":"asset","group":"ParticleEmitter"},{"key":"simulationSpace","type":"int","group":"ParticleEmitter"},+ {"key":"renderMode","type":"int","group":"ParticleEmitter"},+ {"key":"velocityScale","type":"float","group":"ParticleEmitter"},+ {"key":"lengthScale","type":"float","group":"ParticleEmitter"},{"key":"enabled","type":"bool","group":"ParticleEmitter"},{"key":"subEmitterTrigger","type":"int","group":"ParticleEmitter"},{"key":"subEmitterChance","type":"float","group":"ParticleEmitter"},@@ -1591,6 +1594,8 @@ bool editor_setFloat(Registry& reg, u32 e, const std::string& comp, const std::selse if (field == "noiseFrequency") { c.noiseFrequency = value; }else if (field == "noiseScrollSpeed") { c.noiseScrollSpeed = value; }else if (field == "spriteFPS") { c.spriteFPS = value; }+ else if (field == "velocityScale") { c.velocityScale = value; }+ else if (field == "lengthScale") { c.lengthScale = value; }else if (field == "subEmitterChance") { c.subEmitterChance = value; }else if (field == "subEmitterInheritVelocity") { c.subEmitterInheritVelocity = value; }else if (field == "trailWidth") { c.trailWidth = value; }@@ -2160,6 +2165,8 @@ f32 editor_getFloat(Registry& reg, u32 e, const std::string& comp, const std::stelse if (field == "noiseFrequency") { return c.noiseFrequency; }else if (field == "noiseScrollSpeed") { return c.noiseScrollSpeed; }else if (field == "spriteFPS") { return c.spriteFPS; }+ else if (field == "velocityScale") { return c.velocityScale; }+ else if (field == "lengthScale") { return c.lengthScale; }else if (field == "subEmitterChance") { return c.subEmitterChance; }else if (field == "subEmitterInheritVelocity") { return c.subEmitterInheritVelocity; }else if (field == "trailWidth") { return c.trailWidth; }@@ -2563,6 +2570,7 @@ bool editor_setInt(Registry& reg, u32 e, const std::string& comp, const std::strelse if (field == "layer") { c.layer = static_cast<i32>(value); }else if (field == "material") { c.material = static_cast<u32>(value); }else if (field == "simulationSpace") { c.simulationSpace = static_cast<i32>(value); }+ else if (field == "renderMode") { c.renderMode = static_cast<i32>(value); }else if (field == "subEmitterTrigger") { c.subEmitterTrigger = static_cast<i32>(value); }else if (field == "subEmitter") { c.subEmitter = static_cast<u32>(value); }else if (field == "trailPoints") { c.trailPoints = static_cast<i32>(value); }@@ -2838,6 +2846,7 @@ i32 editor_getInt(Registry& reg, u32 e, const std::string& comp, const std::strielse if (field == "layer") { return static_cast<i32>(c.layer); }else if (field == "material") { return static_cast<i32>(c.material); }else if (field == "simulationSpace") { return static_cast<i32>(c.simulationSpace); }+ else if (field == "renderMode") { return static_cast<i32>(c.renderMode); }else if (field == "subEmitterTrigger") { return static_cast<i32>(c.subEmitterTrigger); }else if (field == "subEmitter") { return static_cast<i32>(c.subEmitter); }else if (field == "trailPoints") { return static_cast<i32>(c.trailPoints); }diff --git a/src/esengine/bindings/WebBindings.generated.cpp b/src/esengine/bindings/WebBindings.generated.cppindex 53731e7b0..dd02f93e0 100644--- a/src/esengine/bindings/WebBindings.generated.cpp+++ b/src/esengine/bindings/WebBindings.generated.cpp@@ -239,6 +239,10 @@ EMSCRIPTEN_BINDINGS(esengine_enums) {.value("EaseOut", esengine::ecs::ParticleEasing::EaseOut).value("EaseInOut", esengine::ecs::ParticleEasing::EaseInOut);+ enum_<esengine::ecs::ParticleRenderMode>("ParticleRenderMode")+ .value("Billboard", esengine::ecs::ParticleRenderMode::Billboard)+ .value("Stretched", esengine::ecs::ParticleRenderMode::Stretched);+enum_<esengine::ecs::ProjectionType>("ProjectionType").value("Perspective", esengine::ecs::ProjectionType::Perspective).value("Orthographic", esengine::ecs::ProjectionType::Orthographic);@@ -979,6 +983,9 @@ struct ParticleEmitterJS {i32 layer;u32 material;i32 simulationSpace;+ i32 renderMode;+ f32 velocityScale;+ f32 lengthScale;bool enabled;i32 subEmitterTrigger;f32 subEmitterChance;@@ -1048,6 +1055,9 @@ void particleemitterApplyJS(esengine::ecs::ParticleEmitter& c, const ParticleEmic.layer = js.layer;c.material = js.material;c.simulationSpace = js.simulationSpace;+ c.renderMode = js.renderMode;+ c.velocityScale = js.velocityScale;+ c.lengthScale = js.lengthScale;c.enabled = js.enabled;c.subEmitterTrigger = js.subEmitterTrigger;c.subEmitterChance = js.subEmitterChance;@@ -1124,6 +1134,9 @@ ParticleEmitterJS particleemitterToJS(const esengine::ecs::ParticleEmitter& c) {js.layer = c.layer;js.material = c.material;js.simulationSpace = c.simulationSpace;+ js.renderMode = c.renderMode;+ js.velocityScale = c.velocityScale;+ js.lengthScale = c.lengthScale;js.enabled = c.enabled;js.subEmitterTrigger = c.subEmitterTrigger;js.subEmitterChance = c.subEmitterChance;@@ -2098,6 +2111,9 @@ EMSCRIPTEN_BINDINGS(esengine_components) {.field("layer", &ParticleEmitterJS::layer).field("material", &ParticleEmitterJS::material).field("simulationSpace", &ParticleEmitterJS::simulationSpace)+ .field("renderMode", &ParticleEmitterJS::renderMode)+ .field("velocityScale", &ParticleEmitterJS::velocityScale)+ .field("lengthScale", &ParticleEmitterJS::lengthScale).field("enabled", &ParticleEmitterJS::enabled).field("subEmitterTrigger", &ParticleEmitterJS::subEmitterTrigger).field("subEmitterChance", &ParticleEmitterJS::subEmitterChance)@@ -4028,27 +4044,30 @@ static_assert(offsetof(esengine::ecs::ParticleEmitter, blendMode) == 200, "ABI ostatic_assert(offsetof(esengine::ecs::ParticleEmitter, layer) == 204, "ABI offset drift: esengine::ecs::ParticleEmitter.layer (EHT expected 204)");static_assert(offsetof(esengine::ecs::ParticleEmitter, material) == 208, "ABI offset drift: esengine::ecs::ParticleEmitter.material (EHT expected 208)");static_assert(offsetof(esengine::ecs::ParticleEmitter, simulationSpace) == 212, "ABI offset drift: esengine::ecs::ParticleEmitter.simulationSpace (EHT expected 212)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 216, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 216)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterTrigger) == 220, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterTrigger (EHT expected 220)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterChance) == 224, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterChance (EHT expected 224)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterInheritVelocity) == 228, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterInheritVelocity (EHT expected 228)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitter) == 232, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitter (EHT expected 232)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailEnabled) == 236, "ABI offset drift: esengine::ecs::ParticleEmitter.trailEnabled (EHT expected 236)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailWidth) == 240, "ABI offset drift: esengine::ecs::ParticleEmitter.trailWidth (EHT expected 240)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.trailPoints (EHT expected 244)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 248)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 252)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 256, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 256)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMode) == 260, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMode (EHT expected 260)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMask) == 264, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMask (EHT expected 264)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionQueryBudget) == 268, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionQueryBudget (EHT expected 268)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMaxDistance) == 272, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMaxDistance (EHT expected 272)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFallback) == 276, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFallback (EHT expected 276)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEvents) == 280, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEvents (EHT expected 280)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEventBudget) == 284, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEventBudget (EHT expected 284)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionBounce) == 288, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionBounce (EHT expected 288)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFriction) == 292, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFriction (EHT expected 292)");-static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionLifetimeLoss) == 296, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionLifetimeLoss (EHT expected 296)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, renderMode) == 216, "ABI offset drift: esengine::ecs::ParticleEmitter.renderMode (EHT expected 216)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, velocityScale) == 220, "ABI offset drift: esengine::ecs::ParticleEmitter.velocityScale (EHT expected 220)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, lengthScale) == 224, "ABI offset drift: esengine::ecs::ParticleEmitter.lengthScale (EHT expected 224)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, enabled) == 228, "ABI offset drift: esengine::ecs::ParticleEmitter.enabled (EHT expected 228)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterTrigger) == 232, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterTrigger (EHT expected 232)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterChance) == 236, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterChance (EHT expected 236)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitterInheritVelocity) == 240, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitterInheritVelocity (EHT expected 240)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, subEmitter) == 244, "ABI offset drift: esengine::ecs::ParticleEmitter.subEmitter (EHT expected 244)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailEnabled) == 248, "ABI offset drift: esengine::ecs::ParticleEmitter.trailEnabled (EHT expected 248)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailWidth) == 252, "ABI offset drift: esengine::ecs::ParticleEmitter.trailWidth (EHT expected 252)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailPoints) == 256, "ABI offset drift: esengine::ecs::ParticleEmitter.trailPoints (EHT expected 256)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, trailMinDistance) == 260, "ABI offset drift: esengine::ecs::ParticleEmitter.trailMinDistance (EHT expected 260)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEnabled) == 264, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEnabled (EHT expected 264)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFloor) == 268, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFloor (EHT expected 268)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMode) == 272, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMode (EHT expected 272)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMask) == 276, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMask (EHT expected 276)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionQueryBudget) == 280, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionQueryBudget (EHT expected 280)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionMaxDistance) == 284, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionMaxDistance (EHT expected 284)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFallback) == 288, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFallback (EHT expected 288)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEvents) == 292, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEvents (EHT expected 292)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionEventBudget) == 296, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionEventBudget (EHT expected 296)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionBounce) == 300, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionBounce (EHT expected 300)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionFriction) == 304, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionFriction (EHT expected 304)");+static_assert(offsetof(esengine::ecs::ParticleEmitter, collisionLifetimeLoss) == 308, "ABI offset drift: esengine::ecs::ParticleEmitter.collisionLifetimeLoss (EHT expected 308)");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)");@@ -4246,7 +4265,7 @@ static_assert(offsetof(esengine::ecs::Velocity, angular) == 12, "ABI offset drif// ABI Hash -- runtime handshake against the SDK bundle// =============================================================================-static const char* kEsAbiLayoutHash = "e064dcf6ece54b86";+static const char* kEsAbiLayoutHash = "7e1e50433c8b93cf";std::string esengineGetAbiLayoutHash() {return std::string(kEsAbiLayoutHash);diff --git a/src/esengine/ecs/components/ParticleEmitter.hpp b/src/esengine/ecs/components/ParticleEmitter.hppindex e1e7d7928..12cda5edd 100644--- a/src/esengine/ecs/components/ParticleEmitter.hpp+++ b/src/esengine/ecs/components/ParticleEmitter.hpp@@ -32,6 +32,14 @@ enum class ParticleEasing : i32 {EaseInOut = 3,};+/// How a particle's quad is turned. Billboard faces the view and spins by its own rotation; Stretched lays the quad's+/// long axis along the particle's velocity and lengthens it with speed — sparks, rain, streaks.+ES_ENUM(stability=beta)+enum class ParticleRenderMode : i32 {+ Billboard = 0,+ Stretched = 1,+};+ES_ENUM(stability=beta)enum class SimulationSpace : i32 {World = 0,@@ -221,6 +229,15 @@ struct ParticleEmitter {ES_PROPERTY(enum=SimulationSpace, category=Rendering)i32 simulationSpace{static_cast<i32>(SimulationSpace::World)};+ ES_PROPERTY(enum=ParticleRenderMode, category=Rendering, tooltip="Billboard faces the view. Stretched lays the quad's long axis (its Y) along the particle's velocity and lengthens it with speed. Drawn by the CPU simulation; a GPU-simulated emitter draws as Billboard.")+ i32 renderMode{static_cast<i32>(ParticleRenderMode::Billboard)};++ ES_PROPERTY(min=0, category=Rendering, shown_when=renderMode:Stretched, tooltip="Stretched: how much of the particle's speed is added to the quad's length, in world units per unit of speed.")+ f32 velocityScale{0.0f};++ ES_PROPERTY(min=0, category=Rendering, shown_when=renderMode:Stretched, tooltip="Stretched: the quad's own length is its size times this.")+ f32 lengthScale{1.0f};+// StateES_PROPERTY()bool enabled{true};diff --git a/src/esengine/particle/ParticleStretch.hpp b/src/esengine/particle/ParticleStretch.hppnew file mode 100644index 000000000..2dca00da2--- /dev/null+++ b/src/esengine/particle/ParticleStretch.hpp@@ -0,0 +1,31 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+#pragma once++#include "../core/Types.hpp"++#include <glm/glm.hpp>++#include <cmath>++namespace esengine::particle {++/**+ * @brief How a stretched particle's quad is laid along its velocity.+ *+ * @details The quad's +Y runs along the velocity and is lengthened by speed; its width stays the particle's own. A particle that is not+ * moving keeps the rotation it was given, since a direction needs a velocity.+ */+struct StretchedQuad {+ f32 rotation; ///< Radians, counter-clockwise, turning the quad's +Y onto the velocity.+ f32 length; ///< The quad's extent along its Y.+};++inline StretchedQuad stretchedQuad(glm::vec2 velocity, f32 rotation, f32 size, f32 lengthScale, f32 velocityScale) {+ const f32 speed = glm::length(velocity);+ if (speed <= 1e-4f) return {rotation, size};+ constexpr f32 kHalfPi = 1.57079632679f;+ return {std::atan2(velocity.y, velocity.x) - kHalfPi, size * lengthScale + speed * velocityScale};+}++} // namespace esengine::particlediff --git a/src/esengine/renderer/plugins/ParticlePlugin.cpp b/src/esengine/renderer/plugins/ParticlePlugin.cppindex f48bb2334..352d0c13f 100644--- a/src/esengine/renderer/plugins/ParticlePlugin.cpp+++ b/src/esengine/renderer/plugins/ParticlePlugin.cpp@@ -17,6 +17,7 @@#include "../../particle/ParticleSystem.hpp"#include "../../particle/Particle.hpp"+#include "../../particle/ParticleStretch.hpp"#include <algorithm>#include <string>#include <cmath>@@ -155,6 +156,10 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {buffers.vertexData(LayoutId::ParticleInstance) + instByteOffset);}+ const bool stretched = emitter.renderMode == static_cast<i32>(ecs::ParticleRenderMode::Stretched);+ const f32 lengthScale = emitter.lengthScale;+ const f32 velocityScale = emitter.velocityScale;+u32 i = 0;if (!state->gpu) state->pool.forEachAlive([&](const particle::Particle& p) {glm::vec3 worldPos;@@ -183,10 +188,23 @@ void ParticlePlugin::collect(RenderCollectContext& collect_ctx) {v0 = static_cast<f32>(row) * uvScaleY;}+ f32 rotation = p.rotation;+ if (stretched) {+ // The velocity as the world sees it: a local-space emitter's turn and scale carry it too.+ glm::vec2 v(p.velocity);+ if (isLocalSpace) {+ v *= emitterScale;+ v = glm::vec2(v.x * cosA - v.y * sinA, v.x * sinA + v.y * cosA);+ }+ const particle::StretchedQuad quad = particle::stretchedQuad(v, rotation, size.y, lengthScale, velocityScale);+ rotation = quad.rotation;+ size.y = quad.length;+ }+ParticleInstanceData& d = inst[i++];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.rotation = rotation;d.color = packColor(p.color);d.uvOffsetX = u0; d.uvOffsetY = v0;d.uvScaleX = sheet ? uvScaleX : 1.0f;diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txtindex 75b3c0f6a..c4069fce2 100644--- a/tests/CMakeLists.txt+++ b/tests/CMakeLists.txt@@ -350,6 +350,14 @@ target_include_directories(test_particle_shapes PRIVATE)add_test(NAME test_particle_shapes COMMAND test_particle_shapes)+# Stretched billboards: where the quad turns and how long it grows. Header-only.+add_executable(test_particle_stretch particle/test_particle_stretch.cpp)+target_include_directories(test_particle_stretch PRIVATE+ ${CMAKE_SOURCE_DIR}/src+ ${CMAKE_SOURCE_DIR}/third_party/glm+)+add_test(NAME test_particle_stretch COMMAND test_particle_stretch)+# LOD selection: the projection arithmetic, the hysteresis band and the per-view# memory. Header-only, so it runs without a device — the pixel gates say which# level was drawn, this says which of the claims behind it broke.diff --git a/tests/aot/generated/conformance/handshake.h b/tests/aot/generated/conformance/handshake.hindex eda741588..e0ae9a30a 100644--- a/tests/aot/generated/conformance/handshake.h+++ b/tests/aot/generated/conformance/handshake.h@@ -1,5 +1,5 @@/* GENERATED by sdk/tests/aot-conformance.test.ts — do not edit. *//* The contract half of the handshake. The width half is the harness. */-#define ES_CONF_EXPECTED_CONTRACT_HASH 0x1cab327a1c52a33bULL+#define ES_CONF_EXPECTED_CONTRACT_HASH 0x2ce1a65275f59b66ULL/* And which BUILD the artifact beside this one is. */#define ES_CONF_EXPECTED_MODULE_CONTRACT 0xc3d0e057d5701a2eULLdiff --git a/tests/aot/generated/conformance/systems_decl.c b/tests/aot/generated/conformance/systems_decl.cindex f34296500..854a05ad7 100644--- a/tests/aot/generated/conformance/systems_decl.c+++ b/tests/aot/generated/conformance/systems_decl.c@@ -10,7 +10,7 @@answer, it is a read of a different field. The address width belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0x1cab327a1c52a33bULL+#define ES_ABI_ENGINE_DIGEST 0x2ce1a65275f59b66ULLES_EXPORT const uint64_t es_abi_hash =ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));diff --git a/tests/aot/generated/move_system_decl.c b/tests/aot/generated/move_system_decl.cindex 4a9277655..2cf842a08 100644--- a/tests/aot/generated/move_system_decl.c+++ b/tests/aot/generated/move_system_decl.c@@ -10,7 +10,7 @@answer, it is a read of a different field. The address width belongsto the MACHINE, so it mixes in here rather than in the compiler and a32-bit artifact cannot load into a 64-bit host. */-#define ES_ABI_ENGINE_DIGEST 0x1cab327a1c52a33bULL+#define ES_ABI_ENGINE_DIGEST 0x2ce1a65275f59b66ULLES_EXPORT const uint64_t es_abi_hash =ES_ABI_ENGINE_DIGEST ^ (0x9e3779b97f4a7c15ULL * (uint64_t)sizeof(es_addr_t));diff --git a/tests/aot/generated/move_system_hash.h b/tests/aot/generated/move_system_hash.hindex a59be1adc..7b71a1bbb 100644--- a/tests/aot/generated/move_system_hash.h+++ b/tests/aot/generated/move_system_hash.h@@ -1,6 +1,6 @@/* GENERATED by @estella/compiler — do not edit. *//* The contract half of the handshake. The width half is the harness. */-#define ES_EXPECTED_CONTRACT_HASH 0x1cab327a1c52a33bULL+#define ES_EXPECTED_CONTRACT_HASH 0x2ce1a65275f59b66ULL/* And which BUILD the artifact beside this one is, which the sidecarwritten with it has to carry too. */#define ES_EXPECTED_MODULE_CONTRACT 0x10bf77bb714ea1e3ULLdiff --git a/tests/particle/test_particle_stretch.cpp b/tests/particle/test_particle_stretch.cppnew file mode 100644index 000000000..4817f8de9--- /dev/null+++ b/tests/particle/test_particle_stretch.cpp@@ -0,0 +1,45 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file test_particle_stretch.cpp — a stretched particle lies along its velocity and grows with speed.+ */+#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN+#include <doctest.h>++#include <esengine/particle/ParticleStretch.hpp>++using namespace esengine;+using namespace esengine::particle;++namespace {+constexpr f32 kPi = 3.14159265359f;+// Where a quad's +Y points once turned by `rotation`.+glm::vec2 upAfter(f32 rotation) { return {-std::sin(rotation), std::cos(rotation)}; }+} // namespace++TEST_CASE("the quad's +Y points along the velocity, whichever way it goes") {+ for (const glm::vec2 v : {glm::vec2{3, 0}, glm::vec2{0, 2}, glm::vec2{-1, -1}, glm::vec2{4, -3}}) {+ const StretchedQuad q = stretchedQuad(v, 0.0f, 10.0f, 1.0f, 0.0f);+ const glm::vec2 up = upAfter(q.rotation);+ const glm::vec2 dir = glm::normalize(v);+ CHECK(up.x == doctest::Approx(dir.x).epsilon(1e-4));+ CHECK(up.y == doctest::Approx(dir.y).epsilon(1e-4));+ }+}++TEST_CASE("the length is the size times lengthScale plus the speed times velocityScale") {+ const StretchedQuad q = stretchedQuad({3, 4}, 0.0f, 10.0f, 2.0f, 0.5f); // speed 5+ CHECK(q.length == doctest::Approx(10.0f * 2.0f + 5.0f * 0.5f));+}++TEST_CASE("a particle at rest keeps its own rotation and its own size") {+ const StretchedQuad q = stretchedQuad({0, 0}, 0.7f, 10.0f, 3.0f, 9.0f);+ CHECK(q.rotation == doctest::Approx(0.7f));+ CHECK(q.length == doctest::Approx(10.0f));+}++TEST_CASE("a particle moving straight up needs no turn") {+ const StretchedQuad q = stretchedQuad({0, 5}, 1.0f, 1.0f, 1.0f, 0.0f);+ CHECK(q.rotation == doctest::Approx(0.0f).epsilon(1e-4));+ (void)kPi;+}diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjsindex 5dc32cd34..7edf68d50 100644--- a/tools/releaseNotes.mjs+++ b/tools/releaseNotes.mjs@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';* the reader recognises anyway.*/export const NOTED = {+ 'feat(particle): a stretched render mode lays a particle along its velocity and lengthens it with speed, and the Cocos stretched billboard maps onto it':+ {"note":"Particles can be stretched along their velocity."},'feat(cocos): a particle system colour gradient and size curve become the emitter colorGradient and sizeCurve instead of their two ends':{"internal":"The Cocos Creator compatibility layer and importer have not shipped; nothing a creator reaches without opting in."},'feat(cocos): the importer maps ParticleSystem onto ParticleEmitter, and counts what the emitter has no field for':