Usage description of particles in rendering server is nonexistent

[mk56-spn]

Godot 4.4

Issue description:

Simply put. the documentation for how to use any particles with the rendering server seems almost entirely non existent

• most of the particles related methods give 0 information on how or when to use them

• most of them do not seem to throw errors even when nothing is being produced by the system you try to make

• googling the issue returns very little :

• A post with a single supremely unhelpful comment from some user on this post : https://www.reddit.com/r/godot/comments/17drqbt/is_anyone_familiar_with_the_particle_system/

• Another post with another unhelpful comment from the same user:

https://www.reddit.com/r/godot/comments/16nzmpz/adding_particles_with_renderingserver_keeps/

• A post referencing the procedure for the quite different visualserver from 3 x godot
  https://www.reddit.com/r/godot/comments/uznvrv/trying_to_add_particles2d_using_visualserver_any/.

so far i am yet to see a single instance of someone having managed to use it online. im sure they exist ofcourse but that alone should show that this issue is isolated

i have myself dug through the cpp files for the 2d particles node. but even a direct transfer of that code to the degree ive been able to to c# has yielded a whole lot of nothing

[mk56-spn]

Well after a decent amount of hair pulling i got it figured out.

public partial class ParticlesTest : Node2D
	{
		public override void _Ready()
		{
                         // The usual rendering server boilerplate attaching of your new canvas to whatever canvas you please
			Rid r = RenderingServer.CanvasItemCreate();
			RenderingServer.CanvasItemSetParent(r, GetCanvasItem());


			Rid particles = RenderingServer.ParticlesCreate();

                        //Ensure the mode matches
			RenderingServer.ParticlesSetMode(particles, RenderingServer.ParticlesMode.Mode2D);

			// A mesh of your choosing.
			// an upcoming PR will add custom 2d meshes but till then the easiest way to obtain a mesh for testing is to have
			// a sprite 2d and convert it to one in the editor
			Rid myMesh = GD.Load<ArrayMesh>("uid://m1gavyt4hc1g").GetRid();

			RenderingServer.ParticlesSetDrawPasses(particles, 1);
			RenderingServer.ParticlesSetDrawPassMesh(particles, 0, myMesh);

            // Particles seem to default to not emitting
			RenderingServer.ParticlesSetEmitting(particles,true);
			RenderingServer.ParticlesSetAmount(particles, 100);

                       // No idea what it defaults to , not necessary for particles to display but good to have just in case its very high by default
			RenderingServer.ParticlesSetFixedFps(particles, 120);
			RenderingServer.ParticlesSetDrawOrder(particles, RenderingServer.ParticlesDrawOrder.Lifetime);

                        // The usual particles setup you´d do in the editor, in fact unless you need to do it procedurally youd be better off testing it on a regular particles node and then saving it for direct usage
			ParticleProcessMaterial material = new ParticleProcessMaterial
			{
                         InitialVelocity = new Vector2(20, 200),
			};

                        // Your texture of choosing
			GradientTexture2D gradientTexture2D  = GD.Load<GradientTexture2D>("uid://ywrfawtk72po");

			RenderingServer.ParticlesSetProcessMaterial(particles, material.GetRid());
			RenderingServer.CanvasItemAddParticles(r, particles, gradientTexture2D.GetRid() );
		}
	}

Would a proper write up be desirable or is this too niche?

[tetrapod00]

Would a proper write up be desirable or is this too niche?

Thanks for figuring out the minimal example! Personally I think this is worth documenting. My first inclination would be to make a new section on an existing page - either 2D Particle Systems or Optimization using servers. Call the section something like "Using particles with RenderingServer" or similar. Potentially this could be a separate page but I think it's better to start as a section then split out later if needed.

Ideally:

• You would split the code example into a few sections and explain what each section does, to make it more understandable. Ideally in the docs explanation is done more in the body of the page than in the comments of the code examples. Though code comments are of course welcome too.
• Add links to the class reference for each used function when you mention them.
• This will need a GDScript example too. I can help with that if you're not familiar with GDScript (you have permission to submit a PR with just the C# example and we can add the GDScript in review).

Feel free to ping in the contributor chat docs channel too to discuss.

If all that sounds like too much work (and it is work to create an example up to docs standards), you can also post your solution as a comment to a page you consider relevant (again, probably either 2D Particle Systems or Optimization using servers). That will make it available to readers of the offical documentation without needing to go through the formal review process. (You can do github formatting in the comment by editing or writing your comment on github directly instead of using Giscus.)

Oh, and it would be nice if you posted an MRP in this issue, with the minimal solution including a scene in addition to the script. That would make testing a slight bit easier

See also #5967 for some info on setting up Mesh2Ds that may be relevant here

[mk56-spn]

Would a proper write up be desirable or is this too niche?

Thanks for figuring out the minimal example! Personally I think this is worth documenting. My first inclination would be to make a new section on an existing page - either 2D Particle Systems or Optimization using servers. Call the section something like "Using particles with RenderingServer" or similar. Potentially this could be a separate page but I think it's better to start as a section then split out later if needed.

Ideally:

• You would split the code example into a few sections and explain what each section does, to make it more understandable. Ideally in the docs explanation is done more in the body of the page than in the comments of the code examples. Though code comments are of course welcome too.
• Add links to the class reference for each used function when you mention them.
• This will need a GDScript example too. I can help with that if you're not familiar with GDScript (you have permission to submit a PR with just the C# example and we can add the GDScript in review).

Feel free to ping in the contributor chat docs channel too to discuss.

If all that sounds like too much work (and it is work to create an example up to docs standards), you can also post your solution as a comment to a page you consider relevant (again, probably either 2D Particle Systems or Optimization using servers). That will make it available to readers of the offical documentation without needing to go through the formal review process. (You can do github formatting in the comment by editing or writing your comment on github directly instead of using Giscus.)

Oh, and it would be nice if you posted an MRP in this issue, with the minimal solution including a scene in addition to the script. That would make testing a slight bit easier

See also #5967 for some info on setting up Mesh2Ds that may be relevant here

Ill def try and get around to it at some point soonish, however i want to better grasp it before i do a write up. still dubious about some of the behaviours so i want to test some more scenarios

[dugramen]

@mk56-spn Thanks, I was just trying to do this again (I'm the asker in the 2nd reddit link) and I could only find my own unanswered question and this 😅. I guess the issue was I never used particles_set_draw_pass_mesh

But what even is the mesh here? Is that like mash for the particle texture or maybe the region the particles are drawn in?

[mk56-spn]

@mk56-spn Thanks, I was just trying to do this again (I'm the asker in the 2nd reddit link) and I could only find my own unanswered question and this 😅. I guess the issue was I never used particles_set_draw_pass_mesh

But what even is the mesh here? Is that like mash for the particle texture or maybe the region the particles are drawn in?

It's a mesh like the one a mesh instance 2d uses. The GPU particles node doesn't expose it but the particle system fully supports making a particle out of any mesh shape you please. This can be useful for reducing overdraw or making a vector styled game where you don't want the loss of sharpness of a scaled texture or similar

[dugramen]

@mk56-spn Thanks, I was just trying to do this again (I'm the asker in the 2nd reddit link) and I could only find my own unanswered question and this 😅. I guess the issue was I never used particles_set_draw_pass_mesh

But what even is the mesh here? Is that like mash for the particle texture or maybe the region the particles are drawn in?

It's a mesh like the one a mesh instance 2d uses. The GPU particles node doesn't expose it but the particle system fully supports making a particle out of any mesh shape you please. This can be useful for reducing overdraw or making a vector styled game where you don't want the loss of sharpness of a scaled texture or similar

Hmm, I don't really get why that'd be required though. Especially with how weird it is to even make the mesh

[mk56-spn]

@mk56-spn Thanks, I was just trying to do this again (I'm the asker in the 2nd reddit link) and I could only find my own unanswered question and this 😅. I guess the issue was I never used particles_set_draw_pass_mesh

But what even is the mesh here? Is that like mash for the particle texture or maybe the region the particles are drawn in?

It's a mesh like the one a mesh instance 2d uses. The GPU particles node doesn't expose it but the particle system fully supports making a particle out of any mesh shape you please. This can be useful for reducing overdraw or making a vector styled game where you don't want the loss of sharpness of a scaled texture or similar

Hmm, I don't really get why that'd be required though. Especially with how weird it is to even make the mesh

It's what the node does internally. It generates a square mesh