Merge pull request #79527 from QbieShay/qbe/particles-rework

Particle internal refactor and additions for more artistic control

4 files changed, 118 insertions, 5 deletions

diff --git a/doc/classes/GPUParticles2D.xml b/doc/classes/GPUParticles2D.xml
index ee55288783..54c8689ab0 100644
--- a/doc/classes/GPUParticles2D.xml
+++ b/doc/classes/GPUParticles2D.xml
@@ -50,6 +50,10 @@
 		<member name="amount" type="int" setter="set_amount" getter="get_amount" default="8">
 			Number of particles emitted in one emission cycle.
 		</member>
+		<member name="amount_ratio" type="float" setter="set_amount_ratio" getter="get_amount_ratio" default="1.0">
+			The ratio of particles that should actually be emitted. If set to a value lower than [code]1.0[/code], this will set the amount of emitted particles throughout the lifetime to [code]amount * amount_ratio[/code]. Unlike changing [member amount], changing [member amount_ratio] while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. [member amount_ratio] can be used to create effects that make the number of emitted particles vary over time.
+			[b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio].
+		</member>
 		<member name="collision_base_size" type="float" setter="set_collision_base_size" getter="get_collision_base_size" default="1.0">
 			Multiplier for particle's collision radius. [code]1.0[/code] corresponds to the size of the sprite.
 		</member>
@@ -68,6 +72,10 @@
 		<member name="fract_delta" type="bool" setter="set_fractional_delta" getter="get_fractional_delta" default="true">
 			If [code]true[/code], results in fractional delta calculation which has a smoother particles display effect.
 		</member>
+		<member name="interp_to_end" type="float" setter="set_interp_to_end" getter="get_interp_to_end" default="0.0">
+			Causes all the particles in this node to interpolate towards the end of their lifetime.
+			[b]Note[/b]: This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders.
+		</member>
 		<member name="interpolate" type="bool" setter="set_interpolate" getter="get_interpolate" default="true">
 			Enables particle interpolation, which makes the particle movement smoother when their [member fixed_fps] is lower than the screen refresh rate.
 		</member>
diff --git a/doc/classes/GPUParticles3D.xml b/doc/classes/GPUParticles3D.xml
index 3d7243fcbd..dc7e51b7d7 100644
--- a/doc/classes/GPUParticles3D.xml
+++ b/doc/classes/GPUParticles3D.xml
@@ -63,6 +63,10 @@
 		<member name="amount" type="int" setter="set_amount" getter="get_amount" default="8">
 			Number of particles to emit.
 		</member>
+		<member name="amount_ratio" type="float" setter="set_amount_ratio" getter="get_amount_ratio" default="1.0">
+			The ratio of particles that should actually be emitted. If set to a value lower than [code]1.0[/code], this will set the amount of emitted particles throughout the lifetime to [code]amount * amount_ratio[/code]. Unlike changing [member amount], changing [member amount_ratio] while emitting does not affect already-emitted particles and doesn't cause the particle system to restart. [member amount_ratio] can be used to create effects that make the number of emitted particles vary over time.
+			[b]Note:[/b] Reducing the [member amount_ratio] has no performance benefit, since resources need to be allocated and processed for the total [member amount] of particles regardless of the [member amount_ratio].
+		</member>
 		<member name="collision_base_size" type="float" setter="set_collision_base_size" getter="get_collision_base_size" default="0.01">
 		</member>
 		<member name="draw_order" type="int" setter="set_draw_order" getter="get_draw_order" enum="GPUParticles3D.DrawOrder" default="0">
@@ -98,6 +102,10 @@
 		<member name="fract_delta" type="bool" setter="set_fractional_delta" getter="get_fractional_delta" default="true">
 			If [code]true[/code], results in fractional delta calculation which has a smoother particles display effect.
 		</member>
+		<member name="interp_to_end" type="float" setter="set_interp_to_end" getter="get_interp_to_end" default="0.0">
+			Causes all the particles in this node to interpolate towards the end of their lifetime.
+			[b]Note[/b]: This only works when used with a [ParticleProcessMaterial]. It needs to be manually implemented for custom process shaders.
+		</member>
 		<member name="interpolate" type="bool" setter="set_interpolate" getter="get_interpolate" default="true">
 			Enables particle interpolation, which makes the particle movement smoother when their [member fixed_fps] is lower than the screen refresh rate.
 		</member>
diff --git a/doc/classes/ParticleProcessMaterial.xml b/doc/classes/ParticleProcessMaterial.xml
index 0f6cc3b29e..b7f55184f0 100644
--- a/doc/classes/ParticleProcessMaterial.xml
+++ b/doc/classes/ParticleProcessMaterial.xml
@@ -71,6 +71,9 @@
 		</method>
 	</methods>
 	<members>
+		<member name="alpha_curve" type="Texture2D" setter="set_alpha_curve" getter="get_alpha_curve">
+			The alpha value of each particle's color will be multiplied by this [CurveTexture] over its lifetime.
+		</member>
 		<member name="angle_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture">
 			Each particle's rotation will be animated along this [CurveTexture].
 		</member>
@@ -151,6 +154,18 @@
 		<member name="direction" type="Vector3" setter="set_direction" getter="get_direction" default="Vector3(1, 0, 0)">
 			Unit vector specifying the particles' emission direction.
 		</member>
+		<member name="directional_velocity_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture">
+			A curve that specifies the velocity along each of the axes of the particle system along its lifetime.
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
+		</member>
+		<member name="directional_velocity_max" type="float" setter="set_param_max" getter="get_param_max">
+			Maximum directional velocity value, which is multiplied by [member directional_velocity_curve].
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
+		</member>
+		<member name="directional_velocity_min" type="float" setter="set_param_min" getter="get_param_min">
+			Minimum directional velocity value, which is multiplied by [member directional_velocity_curve].
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
+		</member>
 		<member name="emission_box_extents" type="Vector3" setter="set_emission_box_extents" getter="get_emission_box_extents">
 			The box's extents if [member emission_shape] is set to [constant EMISSION_SHAPE_BOX].
 		</member>
@@ -158,6 +173,10 @@
 			Particle color will be modulated by color determined by sampling this texture at the same point as the [member emission_point_texture].
 			[b]Note:[/b] [member emission_color_texture] multiplies the particle mesh's vertex colors. To have a visible effect on a [BaseMaterial3D], [member BaseMaterial3D.vertex_color_use_as_albedo] [i]must[/i] be [code]true[/code]. For a [ShaderMaterial], [code]ALBEDO *= COLOR.rgb;[/code] must be inserted in the shader's [code]fragment()[/code] function. Otherwise, [member emission_color_texture] will have no visible effect.
 		</member>
+		<member name="emission_curve" type="Texture2D" setter="set_emission_curve" getter="get_emission_curve">
+			Each particle's color will be multiplied by this [CurveTexture] over its lifetime.
+			[b]Note:[/b] This property won't have a visible effect unless the render material is marked as unshaded.
+		</member>
 		<member name="emission_normal_texture" type="Texture2D" setter="set_emission_normal_texture" getter="get_emission_normal_texture">
 			Particle velocity and rotation will be set by sampling this texture at the same point as the [member emission_point_texture]. Used only in [constant EMISSION_SHAPE_DIRECTED_POINTS]. Can be created automatically from mesh or node by selecting "Create Emission Points from Mesh/Node" under the "Particles" tool in the toolbar.
 		</member>
@@ -182,6 +201,12 @@
 		<member name="emission_shape" type="int" setter="set_emission_shape" getter="get_emission_shape" enum="ParticleProcessMaterial.EmissionShape" default="0">
 			Particles will be emitted inside this region. Use [enum EmissionShape] constants for values.
 		</member>
+		<member name="emission_shape_offset" type="Vector3" setter="set_emission_shape_offset" getter="get_emission_shape_offset" default="Vector3(0, 0, 0)">
+			The offset for the [member emission_shape], in local space.
+		</member>
+		<member name="emission_shape_scale" type="Vector3" setter="set_emission_shape_scale" getter="get_emission_shape_scale" default="Vector3(1, 1, 1)">
+			The scale of the [member emission_shape], in local space.
+		</member>
 		<member name="emission_sphere_radius" type="float" setter="set_emission_sphere_radius" getter="get_emission_sphere_radius">
 			The sphere's radius if [member emission_shape] is set to [constant EMISSION_SHAPE_SPHERE].
 		</member>
@@ -200,6 +225,9 @@
 		<member name="hue_variation_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0">
 			Minimum equivalent of [member hue_variation_max].
 		</member>
+		<member name="inherit_velocity_ratio" type="float" setter="set_inherit_velocity_ratio" getter="get_inherit_velocity_ratio" default="0.0">
+			Percentage of the velocity of the respective [GPUParticles2D] or [GPUParticles3D] inherited by each particle when spawning.
+		</member>
 		<member name="initial_velocity_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
 			Maximum initial velocity magnitude for each particle. Direction comes from [member direction] and [member spread].
 		</member>
@@ -220,17 +248,23 @@
 		</member>
 		<member name="orbit_velocity_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture">
 			Each particle's orbital velocity will vary along this [CurveTexture].
+			[b]Note:[/b] For 3D orbital velocity, use a [CurveXYZTexture].
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
 		</member>
-		<member name="orbit_velocity_max" type="float" setter="set_param_max" getter="get_param_max">
+		<member name="orbit_velocity_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
 			Maximum orbital velocity applied to each particle. Makes the particles circle around origin. Specified in number of full rotations around origin per second.
-			Only available when [member particle_flag_disable_z] is [code]true[/code].
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
 		</member>
-		<member name="orbit_velocity_min" type="float" setter="set_param_min" getter="get_param_min">
+		<member name="orbit_velocity_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0">
 			Minimum equivalent of [member orbit_velocity_max].
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
 		</member>
 		<member name="particle_flag_align_y" type="bool" setter="set_particle_flag" getter="get_particle_flag" default="false">
 			Align Y axis of particle with the direction of its velocity.
 		</member>
+		<member name="particle_flag_damping_as_friction" type="bool" setter="set_particle_flag" getter="get_particle_flag" default="false">
+			Changes the behavior of the damping properties from a linear deceleration to a deceleration based on speed percentage.
+		</member>
 		<member name="particle_flag_disable_z" type="bool" setter="set_particle_flag" getter="get_particle_flag" default="false">
 			If [code]true[/code], particles will not move on the z axis.
 		</member>
@@ -246,6 +280,18 @@
 		<member name="radial_accel_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0">
 			Minimum equivalent of [member radial_accel_max].
 		</member>
+		<member name="radial_velocity_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture">
+			A [CurveTexture] that defines the velocity over the particle's lifetime away (or toward) the [member velocity_pivot].
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
+		</member>
+		<member name="radial_velocity_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
+			Maximum radial velocity applied to each particle. Makes particles move away from the [member velocity_pivot], or toward it if negative.
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
+		</member>
+		<member name="radial_velocity_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0">
+			Minimum radial velocity applied to each particle. Makes particles move away from the [member velocity_pivot], or toward it if negative.
+			[b]Note:[/b] Animated velocities will not be affected by damping, use [member velocity_limit_curve] instead.
+		</member>
 		<member name="scale_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture">
 			Each particle's scale will vary along this [CurveTexture]. If a [CurveXYZTexture] is supplied instead, the scale will be separated per-axis.
 		</member>
@@ -255,6 +301,17 @@
 		<member name="scale_min" type="float" setter="set_param_min" getter="get_param_min" default="1.0">
 			Minimum equivalent of [member scale_max].
 		</member>
+		<member name="scale_over_velocity_curve" type="Texture2D" setter="set_param_texture" getter="get_param_texture">
+			Either a [CurveTexture] or a [CurveXYZTexture] that scales each particle based on its velocity.
+		</member>
+		<member name="scale_over_velocity_max" type="float" setter="set_param_max" getter="get_param_max" default="0.0">
+			Maximum velocity value reference for [member scale_over_velocity_curve].
+			[member scale_over_velocity_curve] will be interpolated between [member scale_over_velocity_min] and [member scale_over_velocity_max].
+		</member>
+		<member name="scale_over_velocity_min" type="float" setter="set_param_min" getter="get_param_min" default="0.0">
+			Minimum velocity value reference for [member scale_over_velocity_curve].
+			[member scale_over_velocity_curve] will be interpolated between [member scale_over_velocity_min] and [member scale_over_velocity_max].
+		</member>
 		<member name="spread" type="float" setter="set_spread" getter="get_spread" default="45.0">
 			Each particle's initial direction range from [code]+spread[/code] to [code]-spread[/code] degrees.
 		</member>
@@ -317,6 +374,11 @@
 		<member name="turbulence_noise_strength" type="float" setter="set_turbulence_noise_strength" getter="get_turbulence_noise_strength" default="1.0">
 			The turbulence noise strength. Increasing this will result in a stronger, more contrasting, flow pattern.
 		</member>
+		<member name="velocity_limit_curve" type="Texture2D" setter="set_velocity_limit_curve" getter="get_velocity_limit_curve">
+			A [CurveTexture] that defines the maximum velocity of a particle during its lifetime.
+		</member>
+		<member name="velocity_pivot" type="Vector3" setter="set_velocity_pivot" getter="get_velocity_pivot" default="Vector3(0, 0, 0)">
+		</member>
 	</members>
 	<constants>
 		<constant name="PARAM_INITIAL_LINEAR_VELOCITY" value="0" enum="Parameter">
@@ -355,7 +417,16 @@
 		<constant name="PARAM_ANIM_OFFSET" value="11" enum="Parameter">
 			Use with [method set_param_min], [method set_param_max], and [method set_param_texture] to set animation offset properties.
 		</constant>
-		<constant name="PARAM_MAX" value="15" enum="Parameter">
+		<constant name="PARAM_RADIAL_VELOCITY" value="15" enum="Parameter">
+			Use with [method set_param_min], [method set_param_max], and [method set_param_texture] to set radial velocity properties.
+		</constant>
+		<constant name="PARAM_DIRECTIONAL_VELOCITY" value="16" enum="Parameter">
+			Use with [method set_param_min], [method set_param_max], and [method set_param_texture] to set directional velocity properties.
+		</constant>
+		<constant name="PARAM_SCALE_OVER_VELOCITY" value="17" enum="Parameter">
+			Use with [method set_param_min], [method set_param_max], and [method set_param_texture] to set scale over velocity properties.
+		</constant>
+		<constant name="PARAM_MAX" value="18" enum="Parameter">
 			Represents the size of the [enum Parameter] enum.
 		</constant>
 		<constant name="PARTICLE_FLAG_ALIGN_Y_TO_VELOCITY" value="0" enum="ParticleFlags">
@@ -367,7 +438,9 @@
 		<constant name="PARTICLE_FLAG_DISABLE_Z" value="2" enum="ParticleFlags">
 			Use with [method set_particle_flag] to set [member particle_flag_disable_z].
 		</constant>
-		<constant name="PARTICLE_FLAG_MAX" value="3" enum="ParticleFlags">
+		<constant name="PARTICLE_FLAG_DAMPING_AS_FRICTION" value="3" enum="ParticleFlags">
+		</constant>
+		<constant name="PARTICLE_FLAG_MAX" value="4" enum="ParticleFlags">
 			Represents the size of the [enum ParticleFlags] enum.
 		</constant>
 		<constant name="EMISSION_SHAPE_POINT" value="0" enum="EmissionShape">
diff --git a/doc/classes/RenderingServer.xml b/doc/classes/RenderingServer.xml
index 24b409d941..dd279206ab 100644
--- a/doc/classes/RenderingServer.xml
+++ b/doc/classes/RenderingServer.xml
@@ -2627,6 +2627,14 @@
 				Sets the number of particles to be drawn and allocates the memory for them. Equivalent to [member GPUParticles3D.amount].
 			</description>
 		</method>
+		<method name="particles_set_amount_ratio">
+			<return type="void" />
+			<param index="0" name="particles" type="RID" />
+			<param index="1" name="ratio" type="float" />
+			<description>
+				Sets the amount ratio for particles to be emitted. Equivalent to [member GPUParticles3D.amount_ratio].
+			</description>
+		</method>
 		<method name="particles_set_collision_base_size">
 			<return type="void" />
 			<param index="0" name="particles" type="RID" />
@@ -2675,6 +2683,14 @@
 				Sets the [Transform3D] that will be used by the particles when they first emit.
 			</description>
 		</method>
+		<method name="particles_set_emitter_velocity">
+			<return type="void" />
+			<param index="0" name="particles" type="RID" />
+			<param index="1" name="velocity" type="Vector3" />
+			<description>
+				Sets the velocity of a particle node, that will be used by [member ParticleProcessMaterial.inherit_velocity_ratio].
+			</description>
+		</method>
 		<method name="particles_set_emitting">
 			<return type="void" />
 			<param index="0" name="particles" type="RID" />
@@ -2707,6 +2723,14 @@
 				If [code]true[/code], uses fractional delta which smooths the movement of the particles. Equivalent to [member GPUParticles3D.fract_delta].
 			</description>
 		</method>
+		<method name="particles_set_interp_to_end">
+			<return type="void" />
+			<param index="0" name="particles" type="RID" />
+			<param index="1" name="factor" type="float" />
+			<description>
+				Sets the value that informs a [ParticleProcessMaterial] to rush all particles towards the end of their lifetime.
+			</description>
+		</method>
 		<method name="particles_set_interpolate">
 			<return type="void" />
 			<param index="0" name="particles" type="RID" />