Improve Particle node defaults when created in the editor

This aims to improve the particle system's usability by setting
sensible defaults automatically. This should greatly reduce the
number of clicks required to achieve a fully functional particle setup
(with scale, color and flipbook animation support).

For compatibility reasons, Particles created via code or in older
versions of Godot are not affected.

Author: Calinou

editor/scene/2d/particles_2d_editor_plugin.cpp

@@ -33,6 +33,7 @@
 #include "core/io/image_loader.h"
 #include "core/object/callable_mp.h"
 #include "core/os/os.h"
+#include "editor/editor_interface.h"
 #include "editor/editor_node.h"
 #include "editor/editor_string_names.h"
 #include "editor/editor_undo_redo_manager.h"
@@ -47,6 +48,42 @@
 #include "scene/resources/image_texture.h"
 #include "scene/resources/particle_process_material.h"
 
+void GPUParticles2DEditorPlugin::_notification(int p_what) {
+	switch (p_what) {
+		case NOTIFICATION_READY: {
+			EditorInterface::get_singleton()->connect("object_created_in_editor", callable_mp(this, &GPUParticles2DEditorPlugin::_object_created_in_editor));
+		} break;
+	}
+}
+
+void GPUParticles2DEditorPlugin::_object_created_in_editor(Object *p_object) {
+	GPUParticles2D *gpu_particles_2d = Object::cast_to<GPUParticles2D>(p_object);
+	if (gpu_particles_2d) {
+		// Increase the particle amount somewhat to make moving particle systems more visible out of the box.
+		gpu_particles_2d->set_amount(30);
+
+		// Simulate particles at the render framerate to avoid issues with interpolation.
+		// Enabling trails will internally force fixed FPS to 30 anyway (without changing the value of the property).
+		gpu_particles_2d->set_fixed_fps(0);
+
+		gpu_particles_2d->set_process_material(get_material_for_object_created_in_editor());
+		Ref<ParticleProcessMaterial> process_material = gpu_particles_2d->get_process_material();
+		if (process_material.is_valid()) {
+			// Set gravity according to the 2D project settings.
+			const float default_gravity = GLOBAL_GET("physics/2d/default_gravity");
+			const Vector2 default_gravity_vector = GLOBAL_GET("physics/2d/default_gravity_vector");
+			process_material->set_gravity(Vector3(default_gravity_vector.x, default_gravity_vector.y, 0.0) * default_gravity);
+
+			// Emit particles upwards, so that they are visible even when the particles node is placed on the ground.
+			// Adjust for the default gravity, so that particles are emitted upwards even when gravity is set to a high value.
+			process_material->set_direction(Vector3(0, -1, 0));
+			process_material->set_param_min(ParticleProcessMaterial::PARAM_INITIAL_LINEAR_VELOCITY, MAX(100.0, default_gravity * 0.4));
+		}
+
+		gpu_particles_2d->set_texture(get_texture_for_object_created_in_editor());
+	}
+}
+
 void GPUParticles2DEditorPlugin::_menu_callback(int p_idx) {
 	if (p_idx == MENU_GENERATE_VISIBILITY_RECT) {
 		if (need_show_lifetime_dialog(generate_seconds)) {
@@ -674,6 +711,57 @@ GPUParticles2DEditorPlugin::GPUParticles2DEditorPlugin() {
 	generate_visibility_rect->connect(SceneStringName(confirmed), callable_mp(this, &GPUParticles2DEditorPlugin::_generate_visibility_rect));
 }
 
+void CPUParticles2DEditorPlugin::_notification(int p_what) {
+	switch (p_what) {
+		case NOTIFICATION_READY: {
+			EditorInterface::get_singleton()->connect("object_created_in_editor", callable_mp(this, &CPUParticles2DEditorPlugin::_object_created_in_editor));
+		} break;
+	}
+}
+
+void CPUParticles2DEditorPlugin::_object_created_in_editor(Object *p_object) {
+	CPUParticles2D *cpu_particles_2d = Object::cast_to<CPUParticles2D>(p_object);
+	if (cpu_particles_2d) {
+		// Increase the particle amount somewhat to make moving particle systems more visible out of the box.
+		cpu_particles_2d->set_amount(30);
+
+		// Reduce particle spread to make the particle node's rotation easier to notice.
+		cpu_particles_2d->set_spread(5.0);
+
+		// Randomize initial particle rotation.
+		cpu_particles_2d->set_param_min(CPUParticles2D::PARAM_ANGLE, 0.0);
+		cpu_particles_2d->set_param_max(CPUParticles2D::PARAM_ANGLE, 360.0);
+
+		// Scale particles up and down as the lifetime progresses.
+		Ref<Curve> curve = memnew(Curve);
+		// The wind-up occurs significantly faster than the fade-out.
+		curve->add_point(Vector2(0.0, 0.0));
+		curve->add_point(Vector2(0.1, 1.0));
+		curve->add_point(Vector2(1.0, 0.0));
+		cpu_particles_2d->set_param_curve(CPUParticles2D::PARAM_SCALE, curve);
+
+		// Fade particles with transparency as the lifetime progresses.
+		Ref<Gradient> gradient = memnew(Gradient);
+		// The fade-in occurs significantly faster than the fade-out.
+		gradient->set_color(0, Color(1, 1, 1, 0));
+		gradient->set_color(1, Color(1, 1, 1, 0));
+		gradient->add_point(0.1, Color(1, 1, 1, 1));
+		cpu_particles_2d->set_color_ramp(gradient);
+
+		// Set gravity according to the 2d project settings.
+		const float default_gravity = GLOBAL_GET("physics/2d/default_gravity");
+		const Vector2 default_gravity_vector = GLOBAL_GET("physics/2d/default_gravity_vector");
+		cpu_particles_2d->set_gravity(default_gravity_vector * default_gravity);
+
+		// Emit particles upwards, so that they are visible even when the particles node is placed on the ground.
+		// Adjust for the default gravity, so that particles are emitted upwards even when gravity is set to a high value.
+		cpu_particles_2d->set_direction(Vector2(0, -1));
+		cpu_particles_2d->set_param_min(CPUParticles2D::PARAM_INITIAL_LINEAR_VELOCITY, MAX(100.0, default_gravity * 0.4));
+
+		cpu_particles_2d->set_texture(get_texture_for_object_created_in_editor();
+	}
+}
+
 Node *CPUParticles2DEditorPlugin::_convert_particles() {
 	CPUParticles2D *particles = Object::cast_to<CPUParticles2D>(edited_node);
 

editor/scene/2d/particles_2d_editor_plugin.h

@@ -117,8 +117,10 @@ class GPUParticles2DEditorPlugin : public Particles2DEditorPlugin {
 	SpinBox *generate_seconds = nullptr;
 
 	void _generate_visibility_rect();
+	void _object_created_in_editor(Object *p_object);
 
 protected:
+	void _notification(int p_what);
 	void _menu_callback(int p_idx) override;
 	void _add_menu_options(PopupMenu *p_menu) override;
 
@@ -133,7 +135,10 @@ class GPUParticles2DEditorPlugin : public Particles2DEditorPlugin {
 class CPUParticles2DEditorPlugin : public Particles2DEditorPlugin {
 	GDCLASS(CPUParticles2DEditorPlugin, Particles2DEditorPlugin);
 
+	void _object_created_in_editor(Object *p_object);
+
 protected:
+	void _notification(int p_what);
 	Node *_convert_particles() override;
 
 	void _generate_emission_mask() override;

editor/scene/3d/particles_3d_editor_plugin.cpp

@@ -32,6 +32,7 @@
 
 #include "core/object/callable_mp.h"
 #include "core/os/os.h"
+#include "editor/editor_interface.h"
 #include "editor/editor_node.h"
 #include "editor/editor_undo_redo_manager.h"
 #include "editor/scene/scene_tree_editor.h"
@@ -41,9 +42,29 @@
 #include "scene/gui/box_container.h"
 #include "scene/gui/option_button.h"
 #include "scene/gui/spin_box.h"
+#include "scene/resources/3d/primitive_meshes.h"
 #include "scene/resources/image_texture.h"
 #include "scene/resources/particle_process_material.h"
 
+Ref<Mesh> Particles3DEditorPlugin::get_mesh_for_node_created_in_editor() const {
+	Ref<QuadMesh> quad_mesh = memnew(QuadMesh);
+	quad_mesh->set_size(Vector2(0.1, 0.1));
+
+	// Create material to display billboarded texture that follows the color and scale ramps
+	// defined in ParticleProcessMaterial.
+	Ref<StandardMaterial3D> material = memnew(StandardMaterial3D);
+	material->set_shading_mode(BaseMaterial3D::SHADING_MODE_UNSHADED);
+	material->set_transparency(BaseMaterial3D::TRANSPARENCY_ALPHA);
+	material->set_flag(BaseMaterial3D::FLAG_ALBEDO_FROM_VERTEX_COLOR, true);
+	material->set_flag(BaseMaterial3D::FLAG_BILLBOARD_KEEP_SCALE, true);
+	material->set_billboard_mode(BaseMaterial3D::BILLBOARD_PARTICLES);
+
+	material->set_texture(BaseMaterial3D::TEXTURE_ALBEDO, get_texture_for_object_created_in_editor());
+	quad_mesh->set_material(material);
+
+	return quad_mesh;
+}
+
 void Particles3DEditorPlugin::_generate_aabb() {
 	double time = generate_seconds->get_value();
 
@@ -316,6 +337,42 @@ Particles3DEditorPlugin::Particles3DEditorPlugin() {
 	emission_dialog->connect(SceneStringName(confirmed), callable_mp(this, &Particles3DEditorPlugin::_generate_emission_points));
 }
 
+void GPUParticles3DEditorPlugin::_notification(int p_what) {
+	switch (p_what) {
+		case NOTIFICATION_READY: {
+			EditorInterface::get_singleton()->connect("object_created_in_editor", callable_mp(this, &GPUParticles3DEditorPlugin::_object_created_in_editor));
+		} break;
+	}
+}
+
+void GPUParticles3DEditorPlugin::_object_created_in_editor(Object *p_object) {
+	GPUParticles3D *gpu_particles_3d = Object::cast_to<GPUParticles3D>(p_object);
+	if (gpu_particles_3d) {
+		// Increase the particle amount somewhat to make moving particle systems more visible out of the box.
+		gpu_particles_3d->set_amount(30);
+
+		// Simulate particles at the render framerate to avoid issues with interpolation.
+		// Enabling trails will internally force fixed FPS to 30 anyway (without changing the value of the property).
+		gpu_particles_3d->set_fixed_fps(0);
+
+		gpu_particles_3d->set_process_material(get_material_for_object_created_in_editor());
+		Ref<ParticleProcessMaterial> process_material = gpu_particles_3d->get_process_material();
+		if (process_material.is_valid()) {
+			// Set gravity according to the 3D project settings.
+			const float default_gravity = GLOBAL_GET("physics/3d/default_gravity");
+			const Vector3 default_gravity_vector = GLOBAL_GET("physics/3d/default_gravity_vector");
+			process_material->set_gravity(default_gravity_vector * default_gravity);
+
+			// Emit particles upwards, so that they are visible even when the particles node is placed on the ground.
+			// Adjust for the default gravity, so that particles are emitted upwards even when gravity is set to a high value.
+			process_material->set_direction(Vector3(0, 1, 0));
+			process_material->set_param_min(ParticleProcessMaterial::PARAM_INITIAL_LINEAR_VELOCITY, MAX(1.0, default_gravity * 0.4));
+		}
+
+		gpu_particles_3d->set_draw_pass_mesh(0, get_mesh_for_node_created_in_editor());
+	}
+}
+
 Node *GPUParticles3DEditorPlugin::_convert_particles() {
 	GPUParticles3D *particles = Object::cast_to<GPUParticles3D>(edited_node);
 
@@ -417,6 +474,57 @@ GPUParticles3DEditorPlugin::GPUParticles3DEditorPlugin() {
 	conversion_option_name = TTR("Convert to CPUParticles3D");
 }
 
+void CPUParticles3DEditorPlugin::_notification(int p_what) {
+	switch (p_what) {
+		case NOTIFICATION_READY: {
+			EditorInterface::get_singleton()->connect("object_created_in_editor", callable_mp(this, &CPUParticles3DEditorPlugin::_object_created_in_editor));
+		} break;
+	}
+}
+
+void CPUParticles3DEditorPlugin::_object_created_in_editor(Object *p_object) {
+	CPUParticles3D *cpu_particles_3d = Object::cast_to<CPUParticles3D>(p_object);
+	if (cpu_particles_3d) {
+		// Increase the particle amount somewhat to make moving particle systems more visible out of the box.
+		cpu_particles_3d->set_amount(30);
+
+		// Reduce particle spread to make the particle node's rotation easier to notice.
+		cpu_particles_3d->set_spread(5.0);
+
+		// Randomize initial particle rotation.
+		cpu_particles_3d->set_param_min(CPUParticles3D::PARAM_ANGLE, 0.0);
+		cpu_particles_3d->set_param_max(CPUParticles3D::PARAM_ANGLE, 360.0);
+
+		// Scale particles up and down as the lifetime progresses.
+		Ref<Curve> curve = memnew(Curve);
+		// The wind-up occurs significantly faster than the fade-out.
+		curve->add_point(Vector2(0.0, 0.0));
+		curve->add_point(Vector2(0.1, 1.0));
+		curve->add_point(Vector2(1.0, 0.0));
+		cpu_particles_3d->set_param_curve(CPUParticles3D::PARAM_SCALE, curve);
+
+		// Fade particles with transparency as the lifetime progresses.
+		Ref<Gradient> gradient = memnew(Gradient);
+		// The fade-in occurs significantly faster than the fade-out.
+		gradient->set_color(0, Color(1, 1, 1, 0));
+		gradient->set_color(1, Color(1, 1, 1, 0));
+		gradient->add_point(0.1, Color(1, 1, 1, 1));
+		cpu_particles_3d->set_color_ramp(gradient);
+
+		// Set gravity according to the 3D project settings.
+		const float default_gravity = GLOBAL_GET("physics/3d/default_gravity");
+		const Vector3 default_gravity_vector = GLOBAL_GET("physics/3d/default_gravity_vector");
+		cpu_particles_3d->set_gravity(default_gravity_vector * default_gravity);
+
+		// Emit particles upwards, so that they are visible even when the particles node is placed on the ground.
+		// Adjust for the default gravity, so that particles are emitted upwards even when gravity is set to a high value.
+		cpu_particles_3d->set_direction(Vector3(0, 1, 0));
+		cpu_particles_3d->set_param_min(CPUParticles3D::PARAM_INITIAL_LINEAR_VELOCITY, MAX(1.0, default_gravity * 0.4));
+
+		cpu_particles_3d->set_mesh(get_mesh_for_node_created_in_editor());
+	}
+}
+
 Node *CPUParticles3DEditorPlugin::_convert_particles() {
 	CPUParticles3D *particles = Object::cast_to<CPUParticles3D>(edited_node);
 

editor/scene/3d/particles_3d_editor_plugin.h

@@ -54,6 +54,8 @@ class Particles3DEditorPlugin : public ParticlesEditorPlugin {
 protected:
 	Vector<Face3> geometry;
 
+	Ref<Mesh> get_mesh_for_node_created_in_editor() const;
+
 	virtual void _menu_callback(int p_idx) override;
 	virtual void _add_menu_options(PopupMenu *p_menu) override;
 
@@ -68,7 +70,11 @@ class Particles3DEditorPlugin : public ParticlesEditorPlugin {
 class GPUParticles3DEditorPlugin : public Particles3DEditorPlugin {
 	GDCLASS(GPUParticles3DEditorPlugin, Particles3DEditorPlugin);
 
+	void _object_created_in_editor(Object *p_object);
+
 protected:
+	void _notification(int p_what);
+
 	Node *_convert_particles() override;
 
 	bool _can_generate_points() const override;
@@ -81,7 +87,11 @@ class GPUParticles3DEditorPlugin : public Particles3DEditorPlugin {
 class CPUParticles3DEditorPlugin : public Particles3DEditorPlugin {
 	GDCLASS(CPUParticles3DEditorPlugin, Particles3DEditorPlugin);
 
+	void _object_created_in_editor(Object *p_object);
+
 protected:
+	void _notification(int p_what);
+
 	Node *_convert_particles() override;
 
 	bool _can_generate_points() const override { return true; }

editor/scene/particles_editor_plugin.cpp

@@ -37,6 +37,8 @@
 #include "scene/gui/box_container.h"
 #include "scene/gui/menu_button.h"
 #include "scene/gui/spin_box.h"
+#include "scene/resources/gradient_texture.h"
+#include "scene/resources/particle_process_material.h"
 
 void ParticlesEditorPlugin::_notification(int p_what) {
 	switch (p_what) {
@@ -60,6 +62,61 @@ void ParticlesEditorPlugin::_notification(int p_what) {
 	}
 }
 
+Ref<ParticleProcessMaterial> ParticlesEditorPlugin::get_material_for_object_created_in_editor() const {
+	Ref<ParticleProcessMaterial> particle_process_material;
+	particle_process_material.instantiate();
+
+	// Reduce particle spread to make the particle node's rotation easier to notice.
+	particle_process_material->set_spread(5.0);
+
+	// Randomize initial particle rotation.
+	particle_process_material->set_param_min(ParticleProcessMaterial::PARAM_ANGLE, 0.0);
+	particle_process_material->set_param_max(ParticleProcessMaterial::PARAM_ANGLE, 360.0);
+
+	// Scale particles up and down as the lifetime progresses.
+	Ref<CurveTexture> curve_texture = memnew(CurveTexture);
+	Ref<Curve> curve = memnew(Curve);
+	// The wind-up occurs significantly faster than the fade-out.
+	curve->add_point(Vector2(0.0, 0.0));
+	curve->add_point(Vector2(0.1, 1.0));
+	curve->add_point(Vector2(1.0, 0.0));
+	curve_texture->set_curve(curve);
+	particle_process_material->set_param_texture(ParticleProcessMaterial::PARAM_SCALE, curve_texture);
+
+	// Fade particles with transparency as the lifetime progresses.
+	Ref<GradientTexture1D> gradient_texture = memnew(GradientTexture1D);
+	Ref<Gradient> gradient = memnew(Gradient);
+	// The fade-in occurs significantly faster than the fade-out.
+	gradient->set_color(0, Color(1, 1, 1, 0));
+	gradient->set_color(1, Color(1, 1, 1, 0));
+	gradient->add_point(0.1, Color(1, 1, 1, 1));
+	gradient_texture->set_gradient(gradient);
+	particle_process_material->set_color_ramp(gradient_texture);
+
+	return particle_process_material;
+}
+
+Ref<Texture2D> ParticlesEditorPlugin::get_texture_for_object_created_in_editor() const {
+	// Create a solid square texture.
+	// We use a square instead of a circle, so that billboarded particle rotation is visible.
+	Ref<GradientTexture2D> texture = memnew(GradientTexture2D);
+	// Use a low resolution, so that it displays at a comparable size between 2D and 3D.
+	// Texture size defines each particle's size in 2D, but not in 3D.
+	texture->set_width(12);
+	texture->set_height(12);
+	texture->set_fill(GradientTexture2D::FILL_SQUARE);
+	texture->set_fill_from(Vector2(0.5, 0.5));
+	texture->set_fill_to(Vector2(0.5, 0.01));
+	Ref<Gradient> gradient = memnew(Gradient);
+	gradient->set_color(0, Color(1, 1, 1));
+	gradient->set_color(1, Color(1, 1, 1, 0));
+	// Harden the gradient so the texture has a sharper (but still somewhat soft) falloff.
+	gradient->set_offset(0, 0.75);
+	texture->set_gradient(gradient);
+
+	return texture;
+}
+
 bool ParticlesEditorPlugin::need_show_lifetime_dialog(SpinBox *p_seconds) {
 	// Add one second to the default generation lifetime, since the progress is updated every second.
 	p_seconds->set_value(MAX(1.0, std::trunc(edited_node->get("lifetime").operator double()) + 1.0));

editor/scene/particles_editor_plugin.h

@@ -37,8 +37,10 @@ class ConfirmationDialog;
 class HBoxContainer;
 class MenuButton;
 class OptionButton;
+class ParticleProcessMaterial;
 class SceneTreeDialog;
 class SpinBox;
+class Texture2D;
 
 class ParticlesEditorPlugin : public EditorPlugin {
 	GDCLASS(ParticlesEditorPlugin, EditorPlugin);
@@ -60,6 +62,8 @@ class ParticlesEditorPlugin : public EditorPlugin {
 
 	void _notification(int p_what);
 
+	Ref<ParticleProcessMaterial> get_material_for_object_created_in_editor() const;
+	Ref<Texture2D> get_texture_for_object_created_in_editor() const;
 	bool need_show_lifetime_dialog(SpinBox *p_seconds);
 	virtual void _menu_callback(int p_idx);