Godot-docs: Particle2D documentation is lacking

[dejaime]

TL;DR
The process of using image masks to generate particles is not documented.

Problem

After reading several times the Godot 3.0 docs on Particle2D, ParticleSystems and ParticleMaterial, I still don't understand how to use some Emission Shapes, namely
EMISSION_SHAPE_POINTS = 3 and EMISSION_SHAPE_DIRECTED_POINTS = 4.

Thinking I could make some clarifying changes to the docs, I went ahead and downloaded the _2D Particles Demo_ and there they were, three Particle2D nodes emitting in a "HI!" shape. Still, I could not figure out how to replicate that; even copying over the same image file from the demo into a new project and trying to recreate it.

There seems to be an undocumented extra step (or at least one that I might have missed) where we need to get an image and generate a .tres file, but I couldn't find how.

References:
Particles 2D docs: http://docs.godotengine.org/en/3.0/classes/class_particles2d.html
Particle Systems (2D) docs: http://docs.godotengine.org/en/3.0/tutorials/2d/particle_systems_2d.html
Particles Material docs: http://docs.godotengine.org/en/3.0/classes/class_particlesmaterial.html

Thank you!

[dejaime]

Actually, I'm starting to believe there is a bug in the engine and that this process is, not only undocumented but not even functional on v3.0.6 ... Have to test it a bit more.

[pwab]

Hey @dejaime
I tried to help here and also got trouble replicating the "HI!" shape. Used Godot 3.1.alpha and was only able to set the Particle Texture (star image) but no Point Texture (HI mask) for the Emission Shape (Points).

I also got alot of errors on the way:

ERROR: texture_get_data: Condition ' !texture->active ' is true. returned: Ref<Image>()
   At: drivers/gles3/rasterizer_storage_gles3.cpp:1013

ERROR: texture_get_data: Condition ' texture->data_size == 0 && !texture->render_target ' is true. returned: Ref<Image>()
   At: drivers/gles3/rasterizer_storage_gles3.cpp:1014

ERROR: Resource was not pre cached for the resource section, bug?
   At: scene/resources/scene_format_text.cpp:1369

I tried reimporting the images/textures and changed some scaling properties and flags but didn't come to a result where I could clearly see the emission shape. I'm going to investigate the demo now and see which properties were set there.

---

There seems to be an undocumented extra step (or at least one that I might have missed) where we need to get an image and generate a .tres file, but I couldn't find how.

Exactly. I was able to get the effect running by copying the point_texture_emit.tres from the demo to my own project. I have no clue how this was generated.

[dejaime]

Hi, thanks for double checking that for me, good to know there is some output.

Checking the console output didn't even cross my mind to be honest, as initially I didn't think it could be a problem in the engine.

I guess I will open a twin issue on the engine repo as it seems to be broken and, if it is not broken it is absolutely unintuitive.

ref: https://github.com/godotengine/godot/issues/22966

[ghost]

This should be re-opened, and the title changed to "Particles2D Emission Shapes are undocumented".

[dejaime]

I closed this issue since the bug present in the previous version was reported as fixed, but in light of your messages today¹ I do agree this process needs to be documented somewhere. I was looking at the Godot docs trying to find where it would fit the best and was thinking of a way to add it to http://docs.godotengine.org/en/3.1/tutorials/2d/particle_systems_2d.html#particlesmaterial-settings

¹ - https://github.com/godotengine/godot/issues/22966#issuecomment-473479924

[ghost]

@dejaime Somewhere around there, yeah.

I'll probably take a stab at it tomorrow when I'm free, but you're also welcome to give it a shot.

[dejaime]

Thank you @homer666