From bdba75e7cbaeaca53c911f900a460744761930eb Mon Sep 17 00:00:00 2001
From: Chris K <55621012+chrisk-7777@users.noreply.github.com>
Date: Tue, 26 Aug 2025 23:35:20 +1000
Subject: [PATCH] fix: Apply z index to particles [#3503] (#3505)

Closes #3503

Bug raised in Discord:
https://discord.com/channels/1195771303215513671/1408751467808034936

## Changes

 - The ParticleEmitter passes its z value down to particles when configured for Global space
---
 CHANGELOG.md                            | 1 +
 src/engine/Particles/ParticleEmitter.ts | 1 +
 src/engine/Particles/Particles.ts       | 5 +++++
 src/spec/vitest/ParticleSpec.ts         | 6 ++++++
 4 files changed, 13 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 74f3da43..6cc86a48 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -90,6 +90,7 @@ const query = new Query({})
 
 ### Fixed
 
+- Fixed issue where `ParticleEmitter` `Particle` did not receive z index value from emitter when in World space
 - Fixed issue where an animation that was `anim.reset()` inside of an animation event handler like `anim.once('end', () => anim.reset())` would not work correctly
 - Fixed issue where `GpuParticleEmitter` did not rotate with their parents
 - Fixed issue where Cpu `ParticleEmitter` did not respect `ParticleTransform.Local`
diff --git a/src/engine/Particles/ParticleEmitter.ts b/src/engine/Particles/ParticleEmitter.ts
index 425aada4..eb69d3c7 100644
--- a/src/engine/Particles/ParticleEmitter.ts
+++ b/src/engine/Particles/ParticleEmitter.ts
@@ -156,6 +156,7 @@ export class ParticleEmitter extends Actor {
       beginColor: this.particle.beginColor,
       endColor: this.particle.endColor,
       pos: vec(ranX, ranY),
+      z: this.particle.transform === ParticleTransform.Global ? this.z : undefined,
       vel: vec(dx, dy),
       acc: this.particle.acc,
       angularVelocity: this.particle.angularVelocity,
diff --git a/src/engine/Particles/Particles.ts b/src/engine/Particles/Particles.ts
index 6e19a5ff..222b9648 100644
--- a/src/engine/Particles/Particles.ts
+++ b/src/engine/Particles/Particles.ts
@@ -94,6 +94,7 @@ export class Particle extends Entity {
     this.transform.pos = options.pos ?? this.transform.pos;
     this.transform.rotation = options.rotation ?? 0;
     this.transform.scale = vec(1, 1);
+    this.transform.z = options.z ?? 0;
 
     this.motion.vel = options.vel ?? this.motion.vel;
     this.motion.angularVelocity = options.angularVelocity ?? 0;
@@ -198,6 +199,10 @@ export interface ParticleConfig {
    * Starting rotation of the particle
    */
   rotation?: number;
+  /**
+   * Optionally set the z index of the particle, default is 0
+   */
+  z?: number;
   /**
    * Size of the particle in pixels
    */
diff --git a/src/spec/vitest/ParticleSpec.ts b/src/spec/vitest/ParticleSpec.ts
index 5147ca4a..dfbde073 100644
--- a/src/spec/vitest/ParticleSpec.ts
+++ b/src/spec/vitest/ParticleSpec.ts
@@ -279,6 +279,7 @@ describe('A particle', () => {
         randomRotation: false
       },
       pos: new ex.Vector(0, 0),
+      z: 5,
       width: 20,
       height: 30,
       isEmitting: true,
@@ -294,5 +295,10 @@ describe('A particle', () => {
     expect(emitter.children.length).toBe(0);
     expect(engine.currentScene.actors.length).toBe(1);
     expect(engine.currentScene.world.entityManager.entities.length).toBe(21);
+    expect(
+      engine.currentScene.world.entityManager.entities
+        .filter((entity) => entity instanceof ex.Particle)
+        .every((entity) => entity.transform.z === 5)
+    ).toBeTruthy();
   });
 });
-- 
2.51.2