Remove z_layer_2d (#429)

djeedai · web-flow · commit 20aa419f43f4 · 2025-03-10T21:07:31.000Z
Remove `ParticleEffect::z_layer_2d` in favor of just using the effect `Transform`'s Z coordinate. This makes ordering particle effects in layers (along Z) more consistent and expected. Fixes #423
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -78,6 +78,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Removed `EffectAsset::ribbon_group` as well as `with_trails()` and `with_ribbons()`.
   Use the `Attribute::RIBBON_ID` instead to assign a per-particle ribbon ID.
 - Removed `ParticleEffectBundle`. Use `ParticleEffect` directly instead.
+- Removed `ParticleEffect::z_layer_2d`. Use the Z coordinate of the effect's `Tranform` to order effects.
 
 ## [0.14.0] 2024-12-09
 
diff --git a/examples/2d.rs b/examples/2d.rs
@@ -1,8 +1,4 @@
 //! A particle system with a 2D camera.
-//!
-//! The particle effect instance override its `z_layer_2d` field, which can be
-//! tweaked at runtime via the egui inspector to move the 2D rendering layer of
-//! particle above or below the reference square.
 
 use bevy::{prelude::*, render::camera::ScalingMode};
 use bevy_hanabi::prelude::*;
@@ -95,15 +91,11 @@ fn setup(
 
     // Spawn an instance of the particle effect, and override its Z layer to
     // be above the reference white square previously spawned.
-    commands.spawn((
-        // Assign the Z layer so it appears in the egui inspector and can be modified at runtime
-        ParticleEffect::new(effect).with_z_layer_2d(Some(0.1)),
-        Name::new("effect:2d"),
-    ));
+    commands.spawn((ParticleEffect::new(effect), Name::new("effect:2d")));
 }
 
 fn update_plane(time: Res<Time>, mut query: Query<&mut Transform, With<Mesh2d>>) {
     let mut transform = query.single_mut();
     // Move the plane back and forth to show particles ordering relative to it
-    transform.translation.z = (time.elapsed_secs() * 2.5).sin() * 0.045 + 0.1;
+    transform.translation.z = (time.elapsed_secs() * 2.5).sin() * 0.045;
 }
diff --git a/src/asset.rs b/src/asset.rs
@@ -297,7 +297,8 @@ pub struct EffectAsset {
     pub simulation_condition: SimulationCondition,
     /// Seed for the pseudo-random number generator.
     ///
-    /// This is uploaded to GPU and used for the various random expressions and quantities computed in shaders.
+    /// This is uploaded to GPU and used for the various random expressions and
+    /// quantities computed in shaders.
     pub prng_seed: u32,
     /// Init modifier defining the effect.
     #[reflect(ignore)]
diff --git a/src/lib.rs b/src/lib.rs
@@ -166,8 +166,6 @@
 
 use std::fmt::Write as _;
 
-#[cfg(feature = "2d")]
-use bevy::math::FloatOrd;
 use bevy::{
     prelude::*,
     render::sync_world::SyncToRenderWorld,
@@ -625,55 +623,12 @@ impl From<&PropertyInstance> for PropertyValue {
 pub struct ParticleEffect {
     /// Handle of the effect to instantiate.
     pub handle: Handle<EffectAsset>,
-    /// For 2D rendering, override the value of the Z coordinate of the layer at
-    /// which the particles are rendered.
-    ///
-    /// This value is passed to the render pipeline and used when sorting
-    /// transparent items to render, to order them. As a result, effects
-    /// with different Z values cannot be batched together, which may
-    /// negatively affect performance.
-    ///
-    /// Note that this value is shared by all particles of the effect instance.
-    ///
-    /// This is only available with the `2d` feature.
-    #[cfg(feature = "2d")]
-    pub z_layer_2d: Option<f32>,
 }
 
 impl ParticleEffect {
     /// Create a new particle effect without a spawner or any modifier.
     pub fn new(handle: Handle<EffectAsset>) -> Self {
-        Self {
-            handle,
-            #[cfg(feature = "2d")]
-            z_layer_2d: None,
-        }
-    }
-
-    /// Set the value of the Z layer used when rendering in 2D mode.
-    ///
-    /// In 2D mode, the Bevy renderer sorts all render items according to their
-    /// Z layer value, from back (negative) to front (positive). This
-    /// function sets the value assigned to the current particle effect, to
-    /// order it relative to any other 2D render item (including non-effects).
-    /// Setting the value to `None` reverts to the default sorting and put the
-    /// effect back into the default layer.
-    ///
-    /// This function has no effect when rendering in 3D mode.
-    ///
-    /// # Example
-    ///
-    /// ```
-    /// # use bevy_hanabi::*;
-    /// # use bevy::asset::Handle;
-    /// # let asset = Handle::<EffectAsset>::default();
-    /// // Always render the effect in front of the default layer (z=0)
-    /// let effect = ParticleEffect::new(asset).with_z_layer_2d(Some(0.1));
-    /// ```
-    #[cfg(feature = "2d")]
-    pub fn with_z_layer_2d(mut self, z_layer_2d: Option<f32>) -> Self {
-        self.z_layer_2d = z_layer_2d;
-        self
+        Self { handle }
     }
 }
 
@@ -1323,9 +1278,6 @@ pub struct CompiledParticleEffect {
     effect_shader: Option<EffectShader>,
     /// Textures used by the effect, if any.
     textures: Vec<Handle<Image>>,
-    /// 2D layer for the effect instance.
-    #[cfg(feature = "2d")]
-    z_layer_2d: FloatOrd,
     /// Layout flags.
     layout_flags: LayoutFlags,
     /// Alpha mode.
@@ -1346,8 +1298,6 @@ impl Default for CompiledParticleEffect {
             mesh: None,
             effect_shader: None,
             textures: vec![],
-            #[cfg(feature = "2d")]
-            z_layer_2d: FloatOrd(0.0),
             layout_flags: LayoutFlags::NONE,
             alpha_mode: default(),
             parent_particle_layout: None,
@@ -1368,7 +1318,6 @@ impl CompiledParticleEffect {
     pub(crate) fn update(
         &mut self,
         rebuild: bool,
-        #[cfg(feature = "2d")] z_layer_2d: FloatOrd,
         instance: &ParticleEffect,
         material: Option<&EffectMaterial>,
         asset: &EffectAsset,
@@ -1407,12 +1356,6 @@ impl CompiledParticleEffect {
             // smarter here, only invalidate what changed, but for now just wipe everything
             // and rebuild from scratch all three shaders together.
             self.effect_shader = None;
-
-            // Update the 2D layer
-            #[cfg(feature = "2d")]
-            {
-                self.z_layer_2d = z_layer_2d;
-            }
         }
 
         // If the shaders are already compiled, there's nothing more to do
@@ -1726,17 +1669,8 @@ fn compile_effects(
             debug!("Invalidating the compiled cache for effect on entity {:?} due to changes in the ParticleEffect component. If you see this message too much, then performance might be affected. Find why the change detection of the ParticleEffect is triggered.", entity);
         }
 
-        #[cfg(feature = "2d")]
-        let z_layer_2d = effect
-            .z_layer_2d
-            .map_or(FloatOrd(asset.z_layer_2d), |z_layer_2d| {
-                FloatOrd(z_layer_2d)
-            });
-
         compiled_effect.update(
             need_rebuild,
-            #[cfg(feature = "2d")]
-            z_layer_2d,
             &effect,
             material.map(|r| r.into_inner()),
             asset,
diff --git a/src/render/batch.rs b/src/render/batch.rs
@@ -1,7 +1,5 @@
 use std::{collections::VecDeque, fmt::Debug, num::NonZeroU32, ops::Range};
 
-#[cfg(feature = "2d")]
-use bevy::math::FloatOrd;
 use bevy::{
     prelude::*,
     render::{
@@ -322,14 +320,8 @@ pub(crate) struct EffectDrawBatch {
     /// Note: currently there's a 1:1 mapping between effect batch and draw
     /// batch.
     pub effect_batch_index: EffectBatchIndex,
-    /// For 2D rendering, the Z coordinate used as the sort key. Ignored for 3D
-    /// rendering.
-    #[cfg(feature = "2d")]
-    pub z_sort_key_2d: FloatOrd,
-    /// For 3d rendering, the position of the emitter so we can compute distance
-    /// to camera. Ignored for 2D rendering.
-    #[cfg(feature = "3d")]
-    pub translation_3d: Vec3,
+    /// Position of the emitter so we can compute distance to camera.
+    pub translation: Vec3,
 }
 
 impl EffectBatch {
@@ -429,15 +421,11 @@ pub(crate) struct BatchInput {
     pub spawner_base: u32,
     /// Number of particles to spawn for this effect.
     pub spawn_count: u32,
-    /// Emitter position, for 3D sorting.
-    #[cfg(feature = "3d")]
+    /// Emitter position.
     pub position: Vec3,
     /// Index of the init indirect dispatch struct, if any.
     // FIXME - Contains a single effect's data; should handle multiple ones.
     pub init_indirect_dispatch_index: Option<u32>,
-    /// Sort key, for 2D only.
-    #[cfg(feature = "2d")]
-    pub z_sort_key_2d: FloatOrd,
 }
 
 #[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
diff --git a/src/render/mod.rs b/src/render/mod.rs
@@ -2185,10 +2185,6 @@ pub(crate) struct ExtractedEffect {
     pub alpha_mode: AlphaMode,
     /// Effect shaders.
     pub effect_shaders: EffectShader,
-    /// For 2D rendering, the Z coordinate used as the sort key. Ignored for 3D
-    /// rendering.
-    #[cfg(feature = "2d")]
-    pub z_sort_key_2d: FloatOrd,
 }
 
 pub struct AddedEffectParent {
@@ -2519,9 +2515,6 @@ pub(crate) fn extract_effects(
             None
         };
 
-        #[cfg(feature = "2d")]
-        let z_sort_key_2d = compiled_effect.z_layer_2d;
-
         let property_layout = asset.property_layout();
         let property_data = if let Some(properties) = maybe_properties {
             // Note: must check that property layout is not empty, because the
@@ -2571,8 +2564,6 @@ pub(crate) fn extract_effects(
             textures: compiled_effect.textures.clone(),
             alpha_mode,
             effect_shaders: effect_shaders.clone(),
-            #[cfg(feature = "2d")]
-            z_sort_key_2d,
         });
     }
 }
@@ -3926,10 +3917,6 @@ pub(crate) fn prepare_effects(
         );
         trace!("layout_flags = {:?}", extracted_effect.layout_flags);
         trace!("particle_layout = {:?}", effect_slice.particle_layout);
-        #[cfg(feature = "2d")]
-        {
-            trace!("z_sort_key_2d = {:?}", extracted_effect.z_sort_key_2d);
-        }
 
         let spawner_index = effects_meta.allocate_spawner(
             &extracted_effect.transform,
@@ -3962,12 +3949,9 @@ pub(crate) fn prepare_effects(
             shaders: extracted_effect.effect_shaders,
             spawner_base: spawner_index,
             spawn_count: extracted_effect.spawn_count,
-            #[cfg(feature = "3d")]
             position: extracted_effect.transform.translation(),
             init_indirect_dispatch_index: cached_child_info
                 .map(|cc| cc.init_indirect_dispatch_index),
-            #[cfg(feature = "2d")]
-            z_sort_key_2d: extracted_effect.z_sort_key_2d,
         });
 
         // Update properties
@@ -4238,11 +4222,7 @@ pub(crate) fn batch_effects(
         //     continue;
         // }
 
-        #[cfg(feature = "2d")]
-        let z_sort_key_2d = input.z_sort_key_2d;
-
-        #[cfg(feature = "3d")]
-        let translation_3d = input.position;
+        let translation = input.position;
 
         // Spawn one EffectBatch per instance (no batching; TODO). This contains
         // most of the data needed to drive rendering. However this doesn't drive
@@ -4340,10 +4320,7 @@ pub(crate) fn batch_effects(
         commands
             .spawn(EffectDrawBatch {
                 effect_batch_index,
-                #[cfg(feature = "2d")]
-                z_sort_key_2d,
-                #[cfg(feature = "3d")]
-                translation_3d,
+                translation,
             })
             .insert(TemporaryRenderEntity);
     }
@@ -5273,7 +5250,7 @@ pub(crate) fn queue_effects(
                 &render_meshes,
                 &pipeline_cache,
                 |id, entity, draw_batch, _view| Transparent2d {
-                    sort_key: draw_batch.z_sort_key_2d,
+                    sort_key: FloatOrd(draw_batch.translation.z),
                     entity,
                     pipeline: id,
                     draw_function: draw_effects_function_2d,
@@ -5318,7 +5295,7 @@ pub(crate) fn queue_effects(
                     entity,
                     distance: view
                         .rangefinder3d()
-                        .distance_translation(&batch.translation_3d),
+                        .distance_translation(&batch.translation),
                     batch_range: 0..1,
                     extra_index: PhaseItemExtraIndex::NONE,
                 },
diff --git a/src/spawn.rs b/src/spawn.rs
@@ -971,17 +971,13 @@ mod test {
                             InheritedVisibility::default(),
                             ParticleEffect {
                                 handle: handle.clone(),
-                                #[cfg(feature = "2d")]
-                                z_layer_2d: None,
                             },
                         ))
                         .id()
                 } else {
                     world
                         .spawn((ParticleEffect {
                             handle: handle.clone(),
-                            #[cfg(feature = "2d")]
-                            z_layer_2d: None,
                         },))
                         .id()
                 };
