Add EffectAsset::prng_seed (#427)

Add a new field to the effect asset, which determines the seed for the
GPU side PRNG used in shader expressions. This value defaults to zero,
making consecutive runs deterministic. This both gives better artistic
control (what executes at runtime is what was authored), and helps with
debugging by making repros consistent.

To restore the old behavior, assign a random value to the seed when
creating the effect asset, _.e.g_ `prng_seed = rand::random::<u32>()`.

Author: djeedai

CHANGELOG.md

@@ -35,6 +35,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added new `InheritAttributeModifier` to set the value of a particle attribute by copying the value of its parent.
   This modifier is only valid for the `ModifierContext::Init` pass,
   when an effect has a parent (uses `EffectParent`).
+- Added `EffectAsset::prng_seed` used as the PRNG seed for random expressions on GPU.
+  Previously the PRNG seed was implicitly set to a random value.
+  To restore the former behavior, just set `prng_seed = rand::random::<u32>()`.
 
 ### Changed
 

docs/migration-v0.14-to-v0.15.md

@@ -155,3 +155,21 @@ and use multiple ribbons in the same effect.
 Following Bevy's own deprecation of the bundle mechanism, `ParticleEffectBundle` has been removed.
 Use `ParticleEffect` directly instead, which now supports the ECS `#[require()]` mechanism,
 and will automatically add the mandatory components `CompiledParticleEffect`, `Visibility`, and `Transform`.
+
+## Deterministic randomness
+
+Effects using GPU expressions with randomness, like the built-in expression obtained from `ExprWriter::rand()`,
+now use an explicit PRNG seed set stored in `EffectAsset::prng_seed`.
+This value is `0` by default, meaning the effect will produce the same result each application run.
+This ensures the effect authored is played back deterministically, which gives artistic control,
+and is also useful to generate deterministic repro examples of bugs for debugging.
+
+If you want true randomness (old behavior), simply assign this new field to a random value yourself,
+for example:
+
+```rust
+EffectAsset { 
+    prng_seed: rand::random::<u32>(),
+    // [...]
+}
+```

src/asset.rs

@@ -295,6 +295,10 @@ pub struct EffectAsset {
     pub simulation_space: SimulationSpace,
     /// Condition under which the effect is simulated.
     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.
+    pub prng_seed: u32,
     /// Init modifier defining the effect.
     #[reflect(ignore)]
     // TODO - Can't manage to implement FromReflect for BoxedModifier in a nice way yet
@@ -870,6 +874,7 @@ mod tests {
     z_layer_2d: 0.0,
     simulation_space: Global,
     simulation_condition: WhenVisible,
+    prng_seed: 0,
     init_modifiers: [
         {
             "SetAttributeModifier": (

src/lib.rs

@@ -593,8 +593,7 @@ impl From<&PropertyInstance> for PropertyValue {
 ///   make use of the Bevy visibility system and optimize rendering of the
 ///   effects. This influences simulation when using
 ///   [`SimulationCondition::WhenVisible`].
-/// - A [`Transform`] component to define the position of the particle
-///   emitter.
+/// - A [`Transform`] component to define the position of the particle emitter.
 ///
 /// ## Optional components
 ///
@@ -1331,7 +1330,10 @@ pub struct CompiledParticleEffect {
     layout_flags: LayoutFlags,
     /// Alpha mode.
     alpha_mode: AlphaMode,
+    /// Particle layout of the parent effect, if any.
     parent_particle_layout: Option<ParticleLayout>,
+    /// PRNG seed.
+    prng_seed: u32,
 }
 
 impl Default for CompiledParticleEffect {
@@ -1349,6 +1351,7 @@ impl Default for CompiledParticleEffect {
             layout_flags: LayoutFlags::NONE,
             alpha_mode: default(),
             parent_particle_layout: None,
+            prng_seed: 0,
         }
     }
 }
@@ -1395,6 +1398,7 @@ impl CompiledParticleEffect {
         // diff what may or may not have changed.
         self.asset = instance.handle.clone();
         self.simulation_condition = asset.simulation_condition;
+        self.prng_seed = asset.prng_seed;
 
         // Check if the instance changed. If so, rebuild some data from this compiled
         // effect based on the new data of the effect instance.

src/render/mod.rs

@@ -2139,7 +2139,7 @@ impl SpecializedRenderPipeline for ParticlesRenderPipeline {
 /// render world item.
 ///
 /// [`ParticleEffect`]: crate::ParticleEffect
-#[derive(Debug, Component)]
+#[derive(Debug)]
 pub(crate) struct ExtractedEffect {
     /// Main world entity owning the [`CompiledParticleEffect`] this effect was
     /// extracted from. Mainly used for visibility.
@@ -2166,14 +2166,13 @@ pub(crate) struct ExtractedEffect {
     ///
     /// [`property_layout`]: crate::render::ExtractedEffect::property_layout
     pub property_data: Option<Vec<u8>>,
-    /// Effect spawner.
-    ///
-    /// Obtained from calling [`EffectSpawner::tick()`] on the source effect
-    /// instance.
+    /// Number of particles to spawn this frame.
     ///
-    /// [`EffectSpawner::tick()`]: crate::EffectSpawner::tick
-    pub effect_spawner: EffectSpawner, /* TODO - move to separate component instead of
-                                        * extracting into this struct? */
+    /// This is ignored if the effect is a child effect consuming GPU spawn
+    /// events.
+    pub spawn_count: u32,
+    /// PRNG seed.
+    pub prng_seed: u32,
     /// Global transform of the effect origin.
     pub transform: GlobalTransform,
     /// Layout flags.
@@ -2564,7 +2563,8 @@ pub(crate) fn extract_effects(
             particle_layout: asset.particle_layout().clone(),
             property_layout,
             property_data,
-            effect_spawner: *effect_spawner,
+            spawn_count: effect_spawner.spawn_count,
+            prng_seed: compiled_effect.prng_seed,
             transform: *transform,
             layout_flags,
             texture_layout,
@@ -2970,6 +2970,7 @@ impl EffectsMeta {
         &mut self,
         global_transform: &GlobalTransform,
         spawn_count: u32,
+        prng_seed: u32,
         effect_metadata_buffer_table_id: BufferTableId,
     ) -> u32 {
         let spawner_base = self.spawner_buffer.len() as u32;
@@ -2980,14 +2981,11 @@ impl EffectsMeta {
             global_transform.affine().inverse(),
         )
         .into();
-        // FIXME - Probably bad to re-seed each time there's a change (actually, each
-        // frame even!)
-        let seed = 0; //rand::random::<u32>();
         let spawner_params = GpuSpawnerParams {
             transform,
             inverse_transform,
             spawn: spawn_count as i32,
-            seed,
+            seed: prng_seed,
             effect_metadata_index: effect_metadata_buffer_table_id.0,
             ..default()
         };
@@ -3935,7 +3933,8 @@ pub(crate) fn prepare_effects(
 
         let spawner_index = effects_meta.allocate_spawner(
             &extracted_effect.transform,
-            extracted_effect.effect_spawner.spawn_count,
+            extracted_effect.spawn_count,
+            extracted_effect.prng_seed,
             dispatch_buffer_indices.effect_metadata_buffer_table_id,
         );
 
@@ -3962,7 +3961,7 @@ pub(crate) fn prepare_effects(
             particle_layout: extracted_effect.particle_layout.clone(),
             shaders: extracted_effect.effect_shaders,
             spawner_base: spawner_index,
-            spawn_count: extracted_effect.effect_spawner.spawn_count,
+            spawn_count: extracted_effect.spawn_count,
             #[cfg(feature = "3d")]
             position: extracted_effect.transform.translation(),
             init_indirect_dispatch_index: cached_child_info