GPUParticles2D Conversion Failings and Usage Oddities in 4.X #8400

gokiburikin · 2023-11-11T12:44:53Z

gokiburikin
Nov 11, 2023

I've started on the daunting task of porting somewhat complicated particle effects to 4.2 and it's a big pain point. At some point in the development process it seems these nodes lost a lot of polish. This is by no means an exhaustive list, this is just the issues I found going through THREE of my particle effects.

EDIT: Check #8400 (comment) for tips on batch conversion.

Conversion

The conversion is very incomplete and I don't think a single particle effect made it through working as intended. All of the parameters that had a random slider (linear_accel + linear_accel_random for example) just weren't even attempted to be retained despite the logic being consistent as far as I can tell:

linear_accel becomes linear_accel_max
linear_accel * 1.0 - linear_accel_random becomes linear_accel_min
if linear_accel was negative then swap linear_accel_min and linear_accel_max

I have to basically redo all of the particle effects out the gate because what particle effect doesn't use those parameters?

Even lower hanging fruit, the particle flags themselves weren't kept. flag_align_y becomes particle_flag_align_y, etc.
Emission shapes weren't converted: Sphere needs to become Sphere Radius, Ring for some reason becomes Directed Points (I assume this is an enum thing and the old values were just numbers that no longer line up.)
Some previously additive curves are now used as multipliers against the parameters instead. If you used those together before this makes the conversion more difficult since now you have to think about the math works out to get a similar effect since -50 + a curve that goes from 100 to 0 over time has to become -50 + a curve that goes from -1 to 1 over time. Not sure if this could have been added to the converter but a math wizard might be able to answer that.
Previously additive but now multiplicative curves still have additive sensible default values. If I've got -50 I likely don't want to multiply that by 200. -1 to 1 seems like a more sensible default. Some curves don't even get a default range.

Trails

The change to trails without keeping the existing behaviour under another parameter makes some particle effects just impossible to transfer. Trails were absolutely not great trails before (since they often had gaps and didn't spawn more particles to "make up" for the divisor), but they were a unique visual effect. For example I don't think it's possible to get this kind of clumping behaviour at all anymore:

Godot_v3.5.2-stable_win64_2023-11-11_07-04-12.mp4

Trails (in 2D at least) are still not how I expect particle trails to be and I personally found more value in the previous implementation. For one, why do they fade in reverse? Why do they utilize color ramp differently? If they can't cleanly be faded, I don't want to use them.

3.5 vs 4.2 (attempted recreation)

Godot_v3.5.2-stable_win64_2023-11-11_07-13-52.mp4

Godot_v4.2-beta5_win64_2023-11-11_07-16-00.mp4

Sub Emitters

Sub emitters are inaccurate and lack control. Even in the gif used for the documentation page it's plain to see that they do not spawn how you'd want them to.

They don't spawn where the particle is visually. I assume there is some prediction going on that gets screwed up by lower FPS / interpolation. I can't even begin to guess how it's working because of the inconsistency here.

Godot_v4.2-beta5_win64_2023-11-11_07-27-23.mp4

If you try to fix their offset by tinkering with the FPS / interpolation they just don't spawn sometimes.
They ignore their emission shape offset. Even if only Point + Offset was supported this would help a lot when it comes to visual consistency.

It's also possible that the lifetime of particles just doesn't work properly and the sub emitter is the ground truth for where a particle actually is and otherwise particles persist for too long, I really just can't tell.

In Conclusion

All in all this has just been a particularly negative part of the porting experience that could be smoothed out.

Here's what a bunch of my particle effects looked like in 3.5 vs post-conversion 4.2 (I have already fixed a few) for reference:

Godot_v3.5.2-stable_win64_2023-11-11_06-59-58.mp4

Godot_v4.2-beta5_win64_2023-11-11_07-01-29.mp4

Calinou · 2023-11-12T10:36:41Z

Calinou
Nov 12, 2023
Maintainer

The conversion is very incomplete and I don't think a single particle effect made it through working as intended. All of the parameters that had a random slider (linear_accel + linear_accel_random for example) just weren't even attempted to be retained despite the logic being consistent as far as I can tell:

This is because the Godot 4 project converter can only rename properties, not compute new values for them. To compute new values for old properties that were renamed, a _get() method must be implemented in ParticleProcessMaterial instead. This can be done (in which case the property renames should be removed from the converter as they'll be handled by _get()), but it's not trivial.

This can't be done for properties that weren't renamed though, so fixing emission shape after conversion is likely not possible.

The change to trails without keeping the existing behaviour under another parameter makes some particle effects just impossible to transfer. Trails were absolutely not great trails before (since they often had gaps and didn't spawn more particles to "make up" for the divisor), but they were a unique visual effect. For example I don't think it's possible to get this kind of clumping behaviour at all anymore:

3.x-style particle trails can be created using subemitters with the Constant subemitter mode. This is also generally more flexible.

They don't spawn where the particle is visually. I assume there is some prediction going on that gets screwed up by lower FPS / interpolation. I can't even begin to guess how it's working because of the inconsistency here.

My recommendation when working with GPU-based particles in 4.x is to set Fixed FPS to 0 and disable Interpolation, because it often breaks effects in various ways. This essentially restores the behavior of 3.x GPU-based particles.

If this still occurs with fixed FPS set to 0 and interpolation disabled, then this may be due to a mismatch between the end of the particle's lifetime and what the subemitter code considers as "end of the particle's lifetime" (maybe a off-by-one or rounding error).

Interpolation allows for more reliable particle behavior at varying framerates so it should ideally be fixed, but it's a lot of work to resolve all the bugs mentioned in that PR.

1 reply

gokiburikin Nov 12, 2023
Author

Thanks for the informative reply.

This is because the Godot 4 project converter can only rename properties, not compute new values for them.

That's a shame. My plan to fix this automatically is to calculate the new emission shape, min, and max values in 3.5, store them as metadata on the nodes (since that seems to be retained in the conversion process) and parse the metadata in 4.X to fix on ready. Not sure if that's an approach that can be taken by the converter but it should address both issues.

EDIT: Turns out metadata format changed between 3.5 and 4.x as well and also isn't properly converted. Problems on problems.

If this still occurs with fixed FPS set to 0 and interpolation disabled, then this may be due to a mismatch between the end of the particle's lifetime and what the subemitter code considers as "end of the particle's lifetime" (maybe a off-by-one or rounding error).

It does still occur but it is consistent behaviour now. Here's a visual of the issue. I changed the rain speed to be higher and the speed scale to be lower to exacerbate the issue (which is present without changing those things.)

Godot_v4.2-beta5_win64_2023-11-12_06-27-47.mp4

For posterity, I worked around this by adding a very sharp alpha fade to the color ramp of the rain particle at 96%. Here's what that looks like.

Godot_v4.2-beta5_win64_2023-11-12_06-40-57.mp4

3.x-style particle trails can be created using subemitters with the Constant subemitter mode.

It took a bit of finagling but I did land on something pretty similar to the effect I had using this method. Thanks for the tip.

I also realized that unfortunately I don't think Disable Z works the same anymore. I can't get the particles I'm using as a spawn position to have a consistent velocity like in 3.5. They either don't obey min and max initial velocity or they're traveling into the background.

Same settings here between 3.5 and 4.2: Disable Z, no acceleration, Initial Velocity (min and max) 50, Lifetime 1 second. The drawn circle is a radius of 50 so you'd expect all of the particles to hit the edge like in 3.5.

Godot_v3.5.2-stable_win64_2023-11-12_07-33-14.mp4

Godot_v4.2-beta5_win64_2023-11-12_07-33-30.mp4

My recommendation when working with GPU-based particles in 4.x is to set Fixed FPS to 0 and disable Interpolation,

Good to know. The default setting being 30 made me think Fixed FPS was just how things worked now. reduz's comment in that thread hints at a deeper problem, but for now this is what I'll do.

gokiburikin · 2023-11-12T17:50:34Z

gokiburikin
Nov 12, 2023
Author

This post details the steps I took to help with the batch conversion of Particles2D in 3.5 to GPUParticles2D in 4.2.

EDIT: There are currently a handful of bugs that affect porting particle effects from 3.5 to 4.2. When these bugs are fixed I'll edit this post to include the full process I took which clears up a handful of issues that exist in the scripts below, but also takes a bit more effort apply because of full project conversion shortcomings. For now here are the methods you can use to more fully convert Particles2D to GPUParticles2D.

The methods that need to be called

func _get_conversion_data():
	if child.conversion_data.is_empty() and Engine.get_version_info().major < 4:
		var new_data := {}
		if child.process_material.get("emission_shape") > 0: new_data["push_emission_shape"] = true
		if child.process_material.get("flag_align_y"): new_data["flag_align_y"] = true
		if child.process_material.get("flag_disable_z"): new_data["flag_disable_z"] = true
		if child.process_material.get("color_ramp"): new_data["convert_color_ramp"] = true
		new_data["convert_color_space"] = true
		new_data["disable_fixed_fps"] = true
		new_data["disable_interpolation"] = true

		for parameter in ["initial_velocity", "angular_velocity","orbit_velocity","linear_accel","radial_accel","tangential_accel","damping","angle","scale","anim_speed","anim_offset"]:
			var parameter_random = child.process_material.get( parameter + "_random" )
			var conversion_max = child.process_material.get( parameter )
			var conversion_min = conversion_max * (1.0 - parameter_random)
			if parameter == "scale" and conversion_max < 1:
				conversion_min = conversion_max
				conversion_max = 1.0
			elif conversion_max < 0:
				var swap = conversion_min
				conversion_min = conversion_max
				conversion_max = swap
			new_data[parameter + "_min"] = conversion_min
			new_data[parameter + "_max"] = conversion_max
		
		for parameter in ["hue_variation"]:
			var parameter_random = child.process_material.get( parameter + "_random" )
			var conversion_max = child.process_material.get( parameter )
			var conversion_min = lerp( conversion_max, -conversion_max, child.process_material.get( parameter_random ) )
			if conversion_max < 0:
				var swap = conversion_min
				conversion_min = conversion_max
				conversion_max = swap
			new_data[parameter + "_min"] = conversion_min
			new_data[parameter + "_max"] = conversion_max
		
		for parameter in ["angle_curve", "linear_accel_curve", "tangential_accel_curve", "radial_accel_curve", "damping_curve"]:
			if not child.process_material.get( parameter ):
				continue
			var curve:Curve = child.process_material.get( parameter ).curve
			if curve:
				var parameter_base = parameter.trim_suffix("_curve")
				var parameter_random = parameter_base + "_random"
				var parameter_value = child.process_material.get( parameter_base )
				var parameter_min = parameter_base + "_min"
				var parameter_max = parameter_base + "_max"
				new_data[parameter_min] = 1.0 - child.process_material.get( parameter_random )
				new_data[parameter_max] = 1.0
				if abs(parameter_value) <= 1:
					continue
				child.process_material.set( parameter_base, 0 )
				for i in curve.get_point_count():
					curve.set_point_value( i, curve.get_point_position( i ).y + parameter_value )
			
		child.conversion_data = new_data

func _conversion() -> void:
	if Engine.get_version_info().major < 4:
		return
	for child in get_children():
		if child is DynamicParticles2D:
			if child.conversion_data.get("convert_color_ramp",false):
				var new_gradient := GradientTexture1D.new()
				new_gradient.gradient = child.process_material.get("color_ramp").gradient
				child.process_material.set("color_ramp", new_gradient)
			if child.conversion_data.get("convert_color_space",false):
				child.process_material.set("color", child.process_material.get("color").linear_to_srgb() )
				child.conversion_data.erase("convert_color_space")
			if child.conversion_data.get("push_emission_shape",false):
				child.process_material.set( "emission_shape", child.process_material.get("emission_shape") + 1 )
				child.conversion_data.erase("push_emission_shape")
			if child.conversion_data.get("flag_align_y",false):
				child.process_material.set("particle_flag_align_y",true)
				child.conversion_data.erase("flag_align_y")
			if child.conversion_data.get("flag_disable_z",false):
				child.process_material.set("particle_flag_disable_z",true)
				child.conversion_data.erase("flag_disable_z")
			if child.conversion_data.get("disable_fixed_fps",false):
				child.fixed_fps = 0
				child.conversion_data.erase("disable_fixed_fps")
			if child.conversion_data.get("disable_interpolation",false):
				child.interpolate = false
				child.conversion_data.erase("disable_interpolation")
			for meta_variable in child.conversion_data.keys():
				var meta_value = child.conversion_data[meta_variable]
				if child.conversion_data.has( meta_variable ):
					child.process_material.set( meta_variable, meta_value )
					child.conversion_data.erase(meta_variable)

Original Post

Step 1) Use a custom class (Particles2DtoGPUParticles2D is what I called it for these scripts) to store data that is not retained across the conversion (mostly *_accel and *_random variables and flags.) I used a class because the metadata format also changed between major versions.

tool
class_name Particles2DToGPUParticles2D extends Particles2D
export var conversion_data := {}

This code should be run on all your Particles2DtoGPUParticles2D somehow. I had a custom container class that managed multiple Particles2D so I ran it on all its Particles2DToGPUParticles2D children in _ready on a tool script.

NOTE: I use new_data and conversion_data = new_data because setting properties on an export dictionary does not trigger the variable has changed logic and it wouldn't be serialized.

var meta_min_max_fix_variables := ["initial_velocity", "angular_velocity","orbit_velocity","linear_accel","radial_accel","tangential_accel","damping","angle","hue_variation","scale"]
var new_data := {}
if process_material.get("emission_shape") > 0:
	new_data["push_emission_shape"] = true
if process_material.get("flag_align_y"):
	new_data["flag_align_y"] = true
if process_material.get("flag_disable_z"):
	new_data["flag_disable_z"] = true
new_data["disable_fixed_fps"] = true
new_data["disable_interpolation"] = true
for parameter in meta_min_max_fix_variables:
	var parameter_random = process_material.get( parameter + "_random" )
	var conversion_max = process_material.get( parameter )
	var conversion_min = conversion_max * (1.0 - parameter_random)
	if sign(conversion_max) == -1:
		var swap = conversion_min
		conversion_min = conversion_max
		conversion_max = swap
	new_data[parameter + "_min"] = conversion_min
	new_data[parameter + "_max"] = conversion_max
	conversion_data = new_data

Step 2) Open all of the Particles2DToGPUParticles2D scenes so that you can Save All Scenes to serialize the contents of conversion_data to disk.

Step 3) Copy the project and perform the full project conversion.

Step 4) Run this code on all of your Particles2DToGPUParticles2D somehow. It will perform the necessary steps to copy the information from conversion_data and erase it from the dictionary when its done. If the dictionary is empty at the end then the conversion worked out.

if conversion_data.is_empty():
	continue
if conversion_data.get("push_emission_shape",false):
	process_material.set( "emission_shape", process_material.get("emission_shape") + 1 )
	conversion_data.erase("push_emission_shape")
if conversion_data.get("flag_align_y",false):
	process_material.set("particle_flag_align_y",true)
	conversion_data.erase("flag_align_y")
if conversion_data.get("flag_disable_z",false):
	process_material.set("particle_flag_disable_z",true)
	conversion_data.erase("flag_disable_z")
if conversion_data.get("disable_fixed_fps",false):
	fixed_fps = 0
	conversion_data.erase("disable_fixed_fps")
if conversion_data.get("disable_interpolation",false):
	interpolate = false
	conversion_data.erase("disable_interpolation")
for meta_variable in conversion_data.keys():
	var meta_value = conversion_data[meta_variable]
	if conversion_data.has( meta_variable ):
		process_material.set( meta_variable, meta_value )
		conversion_data.erase(meta_variable)

NOTE: This is not a complete conversion. See Further Considerations below.

Results

Here's a comparison of running just the full project conversion vs running with this additional conversion step.

Original 3.5.2 Particle Effects

Godot_v3.5.2-stable_win64_2023-11-11_06-59-58.mp4

4.2 Full Conversion

Godot_v4.2-beta5_win64_2023-11-12_12-23-49.mp4

4.2 Full Conversion + Conversion Class

Godot_v4.2-beta5_win64_2023-11-12_12-24-30.mp4

Further Considerations

~~It should be possible to calculate the new values for curves though I need to go through and discover which curves became multiplicative~~ The updated methods handle this
~~Scale needs to be treated slightly differently (which is not handled in the custom class atm) since its randomness is implemented uniquely (<1 instead of <0)~~ The updated methods handle this
Color ramp needs to be converted from a Gradient/GradientTexture2D to a GradientTexture1D because of Failed to set a resource of the type 'GradientTexture2D' because this EditorResourcePicker only accepts 'GradientTexture1D' and its derivatives. errors The updated methods handle this
~~Emissive curve needs to be set~~ it's the sRGB to linear issue that is causing darker colors
GPUParticles2D colors are being rendered darker than expected godot#80025
ParticleProcessMaterial breaks when using anim_offset_curve godot#84819
ParticleProcessMaterial ignores anim_speed_curve godot#84818
This doesn't and will not handle trails since the replication of the previous trails effect is non-trivial and probably can't be done 1-to-1 anyway

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

GPUParticles2D Conversion Failings and Usage Oddities in 4.X #8400

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Replies: 2 comments 1 reply

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Uh oh!

{{title}}

Uh oh!

Uh oh!

{{editor}}'s edit

{{editor}}'s edit

Uh oh!

Select a reply

Uh oh!

Uh oh!

GPUParticles2D Conversion Failings and Usage Oddities in 4.X #8400

Uh oh!

Uh oh!

gokiburikin Nov 11, 2023

Conversion

Trails

Sub Emitters

In Conclusion

Replies: 2 comments · 1 reply

Uh oh!

Uh oh!

Calinou Nov 12, 2023 Maintainer

Uh oh!

Uh oh!

gokiburikin Nov 12, 2023 Author

Uh oh!

Uh oh!

gokiburikin Nov 12, 2023 Author

Original Post

Results

Further Considerations

gokiburikin
Nov 11, 2023

Replies: 2 comments 1 reply

Calinou
Nov 12, 2023
Maintainer

gokiburikin Nov 12, 2023
Author

gokiburikin
Nov 12, 2023
Author