Add ratio to cpu particles to dynamically change amount emitted

[chrisb123]

This commit adds a ratio slider expressed in percentage to the cpu particles so that users can dynamically adjusts the amount of emitted particles without clearing or resetting the existing particles.

A new property ratio is added
Two extra bool properties are added to the particle array to control processing of the particles

Setting the ratio clears the stopped flag and evenly distributes which particles should be stopped by setting a stopping flag or clearing it for other particles that should keep running
Each particle continues its life until it restarts
When the particle is restarted the stopping flag is checked, if true the stopped flag is set

It will always submit at least 1 particle.

Another option maybe to:

1. Clear emitting when ratio is set 0% and when raised above 0% set emitting
2. Use integer math instead of float
3. Increase ratio precision

This is my first commit and pull request

• Production edit: This closes Dynamically adjust the amount of particles emitted without clearing all the particles godot-proposals#5939.

[Zireael07]

This needs some docs. Percentage of what???

[chrisb123]

ratio is percent of amount with a minimum of 1 particle

[KoBeWi]

You need to run doctool and fill the descriptions (start your compiled executable with --doctool argument).

[Calinou]

Should ratio be renamed to amount_ratio to make it clearer that it affects how the Amount will appear in practice?

[chrisb123]

It will make it clearer as to what ratio refers too, all reference to ratio are now amount_ratio

[KoBeWi]

The feature looks ok, but I think it shouldn't affect emitting.

Also it would be nice to see it in GPUParticles, but could be done in another PR.

[chrisb123]

The purpose of that code is to evenly distribute which individual particles do not get restarted.

[Calinou]

Also it would be nice to see it in GPUParticles, but could be done in another PR.

This is now done in #79527 (comment) 🙂

[Calinou]

Tested locally (rebased on top of master eb4301b), it works as expected in both 2D and 3D.

Testing project: test_pr_70145.zip

One issue I notice however is that Emitting is dynamically set based on Amount Ratio. Considering the controversy around Oneshot toggling Emitting on its own, I would prefer not having this kind of automatic behavior which can work against the user.

A GPUParticles implementation would also not toggle Emitting on its own for Amount Ratio, so I'd prefer it to work consistently too.

[Calinou]

Improve documentation to match my GPUParticles branch:

Suggested change

	Amount Ratio multiplied by [member amount] is how many particles will be emmitted each cycle. This value is to be adjusted while emitting particles as it will not clear the existing particles.
	When not used leave this ratio at 1 and adjust amount accordingly.
	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] If you don't need to change the number of particles emitted while particles are emitting, keep [member amount_ratio] at [code]1.0[/code] and change [member amount] instead. This will result in better performance, as inactive particles still need to be partially evaluated in the shader otherwise.

[Calinou]

Suggested change

	Amount Ratio multiplied by [member amount] is how many particles will be emmitted each cycle. This value is to be adjusted while emitting particles as it will not clear the existing particles.
	When not used leave this ratio at 1 and adjust amount accordingly.
	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] If you don't need to change the number of particles emitted while particles are emitting, keep [member amount_ratio] at [code]1.0[/code] and change [member amount] instead. This will result in better performance, as inactive particles still need to be partially evaluated in the shader otherwise.

[QbieShay]

To merge after #79527 and once Calinou's feedback on documentation and functionality is addressed 👍 good job!

[clayjohn]

@QbieShay This is superseded by #79527 now right?

[QbieShay]

No this is CPUParticles!

[damian1ilin]

Hi! Any chance to get a similar function but in 2d particles? I'm using 2d cpu particles in my game and I'm facing the issue of them disappearing as trying to dinamically change the amount.

[arkology]

@damian1ilin this PR implements both 2D and 3D.
As I see it is in almost ready state as per #70145 (comment).
But it seems that the author has not been active on GitHub for quite some time.