Merge pull request #48242 from reduz/particle-trails

Implement Particle Trails

2 files changed, 196 insertions, 5 deletions

diff --git a/scene/3d/gpu_particles_3d.cpp b/scene/3d/gpu_particles_3d.cpp
index a075dcf990..ab85338f36 100644
--- a/scene/3d/gpu_particles_3d.cpp
+++ b/scene/3d/gpu_particles_3d.cpp
@@ -181,12 +181,33 @@ void GPUParticles3D::set_draw_order(DrawOrder p_order) {
 	RS::get_singleton()->particles_set_draw_order(particles, RS::ParticlesDrawOrder(p_order));
 }
 
+void GPUParticles3D::set_enable_trail(bool p_enabled) {
+	trail_enabled = p_enabled;
+	RS::get_singleton()->particles_set_trails(particles, trail_enabled, trail_length);
+	update_configuration_warnings();
+}
+void GPUParticles3D::set_trail_length(float p_seconds) {
+	ERR_FAIL_COND(p_seconds < 0.001);
+	trail_length = p_seconds;
+	RS::get_singleton()->particles_set_trails(particles, trail_enabled, trail_length);
+}
+
+bool GPUParticles3D::is_trail_enabled() const {
+	return trail_enabled;
+}
+float GPUParticles3D::get_trail_length() const {
+	return trail_length;
+}
+
 GPUParticles3D::DrawOrder GPUParticles3D::get_draw_order() const {
 	return draw_order;
 }
 
 void GPUParticles3D::set_draw_passes(int p_count) {
 	ERR_FAIL_COND(p_count < 1);
+	for (int i = p_count; i < draw_passes.size(); i++) {
+		set_draw_pass_mesh(i, Ref<Mesh>());
+	}
 	draw_passes.resize(p_count);
 	RS::get_singleton()->particles_set_draw_passes(particles, p_count);
 	notify_property_list_changed();
@@ -199,8 +220,16 @@ int GPUParticles3D::get_draw_passes() const {
 void GPUParticles3D::set_draw_pass_mesh(int p_pass, const Ref<Mesh> &p_mesh) {
 	ERR_FAIL_INDEX(p_pass, draw_passes.size());
 
+	if (Engine::get_singleton()->is_editor_hint() && draw_passes.write[p_pass].is_valid()) {
+		draw_passes.write[p_pass]->disconnect("changed", callable_mp((Node *)this, &Node::update_configuration_warnings));
+	}
+
 	draw_passes.write[p_pass] = p_mesh;
 
+	if (Engine::get_singleton()->is_editor_hint() && draw_passes.write[p_pass].is_valid()) {
+		draw_passes.write[p_pass]->connect("changed", callable_mp((Node *)this, &Node::update_configuration_warnings), varray(), CONNECT_DEFERRED);
+	}
+
 	RID mesh_rid;
 	if (p_mesh.is_valid()) {
 		mesh_rid = p_mesh->get_rid();
@@ -208,6 +237,7 @@ void GPUParticles3D::set_draw_pass_mesh(int p_pass, const Ref<Mesh> &p_mesh) {
 
 	RS::get_singleton()->particles_set_draw_pass_mesh(particles, p_pass, mesh_rid);
 
+	_skinning_changed();
 	update_configuration_warnings();
 }
 
@@ -235,6 +265,15 @@ bool GPUParticles3D::get_fractional_delta() const {
 	return fractional_delta;
 }
 
+void GPUParticles3D::set_interpolate(bool p_enable) {
+	interpolate = p_enable;
+	RS::get_singleton()->particles_set_interpolate(particles, p_enable);
+}
+
+bool GPUParticles3D::get_interpolate() const {
+	return interpolate;
+}
+
 TypedArray<String> GPUParticles3D::get_configuration_warnings() const {
 	TypedArray<String> warnings = Node::get_configuration_warnings();
 
@@ -250,7 +289,7 @@ TypedArray<String> GPUParticles3D::get_configuration_warnings() const {
 			meshes_found = true;
 			for (int j = 0; j < draw_passes[i]->get_surface_count(); j++) {
 				anim_material_found = Object::cast_to<ShaderMaterial>(draw_passes[i]->surface_get_material(j).ptr()) != nullptr;
-				StandardMaterial3D *spat = Object::cast_to<StandardMaterial3D>(draw_passes[i]->surface_get_material(j).ptr());
+				BaseMaterial3D *spat = Object::cast_to<BaseMaterial3D>(draw_passes[i]->surface_get_material(j).ptr());
 				anim_material_found = anim_material_found || (spat && spat->get_billboard_mode() == StandardMaterial3D::BILLBOARD_PARTICLES);
 			}
 			if (anim_material_found) {
@@ -260,8 +299,10 @@ TypedArray<String> GPUParticles3D::get_configuration_warnings() const {
 	}
 
 	anim_material_found = anim_material_found || Object::cast_to<ShaderMaterial>(get_material_override().ptr()) != nullptr;
-	StandardMaterial3D *spat = Object::cast_to<StandardMaterial3D>(get_material_override().ptr());
-	anim_material_found = anim_material_found || (spat && spat->get_billboard_mode() == StandardMaterial3D::BILLBOARD_PARTICLES);
+	{
+		BaseMaterial3D *spat = Object::cast_to<BaseMaterial3D>(get_material_override().ptr());
+		anim_material_found = anim_material_found || (spat && spat->get_billboard_mode() == BaseMaterial3D::BILLBOARD_PARTICLES);
+	}
 
 	if (!meshes_found) {
 		warnings.push_back(TTR("Nothing is visible because meshes have not been assigned to draw passes."));
@@ -274,7 +315,57 @@ TypedArray<String> GPUParticles3D::get_configuration_warnings() const {
 		if (!anim_material_found && process &&
 				(process->get_param(ParticlesMaterial::PARAM_ANIM_SPEED) != 0.0 || process->get_param(ParticlesMaterial::PARAM_ANIM_OFFSET) != 0.0 ||
 						process->get_param_texture(ParticlesMaterial::PARAM_ANIM_SPEED).is_valid() || process->get_param_texture(ParticlesMaterial::PARAM_ANIM_OFFSET).is_valid())) {
-			warnings.push_back(TTR("Particles animation requires the usage of a StandardMaterial3D whose Billboard Mode is set to \"Particle Billboard\"."));
+			warnings.push_back(TTR("Particles animation requires the usage of a BaseMaterial3D whose Billboard Mode is set to \"Particle Billboard\"."));
+		}
+	}
+
+	if (trail_enabled) {
+		int dp_count = 0;
+		bool missing_trails = false;
+		bool no_materials = false;
+
+		for (int i = 0; i < draw_passes.size(); i++) {
+			Ref<Mesh> draw_pass = draw_passes[i];
+			if (draw_pass.is_valid() && draw_pass->get_builtin_bind_pose_count() > 0) {
+				dp_count++;
+			}
+
+			if (draw_pass.is_valid()) {
+				int mats_found = 0;
+				for (int j = 0; j < draw_passes[i]->get_surface_count(); j++) {
+					BaseMaterial3D *spat = Object::cast_to<BaseMaterial3D>(draw_passes[i]->surface_get_material(j).ptr());
+					if (spat) {
+						mats_found++;
+					}
+					if (spat && !spat->get_flag(BaseMaterial3D::FLAG_PARTICLE_TRAILS_MODE)) {
+						missing_trails = true;
+					}
+				}
+
+				if (mats_found != draw_passes[i]->get_surface_count()) {
+					no_materials = true;
+				}
+			}
+		}
+
+		BaseMaterial3D *spat = Object::cast_to<BaseMaterial3D>(get_material_override().ptr());
+		if (spat) {
+			no_materials = false;
+		}
+		if (spat && !spat->get_flag(BaseMaterial3D::FLAG_PARTICLE_TRAILS_MODE)) {
+			missing_trails = true;
+		}
+
+		if (dp_count && skin.is_valid()) {
+			warnings.push_back(TTR("Using Trail meshes with a skin causes Skin to override Trail poses. Suggest removing the Skin."));
+		} else if (dp_count == 0 && skin.is_null()) {
+			warnings.push_back(TTR("Trails active, but neither Trail meshes or a Skin were found."));
+		} else if (dp_count > 1) {
+			warnings.push_back(TTR("Only one Trail mesh is supported. If you want to use more than a single mesh, a Skin is needed (see documentation)."));
+		}
+
+		if ((dp_count || !skin.is_null()) && (missing_trails || no_materials)) {
+			warnings.push_back(TTR("Trails enabled, but one or more mesh materials are either missing or not set for trails rendering."));
 		}
 	}
 
@@ -366,6 +457,47 @@ void GPUParticles3D::_notification(int p_what) {
 	}
 }
 
+void GPUParticles3D::_skinning_changed() {
+	Vector<Transform> xforms;
+	if (skin.is_valid()) {
+		xforms.resize(skin->get_bind_count());
+		for (int i = 0; i < skin->get_bind_count(); i++) {
+			xforms.write[i] = skin->get_bind_pose(i);
+		}
+	} else {
+		for (int i = 0; i < draw_passes.size(); i++) {
+			Ref<Mesh> draw_pass = draw_passes[i];
+			if (draw_pass.is_valid() && draw_pass->get_builtin_bind_pose_count() > 0) {
+				xforms.resize(draw_pass->get_builtin_bind_pose_count());
+				for (int j = 0; j < draw_pass->get_builtin_bind_pose_count(); j++) {
+					xforms.write[i] = draw_pass->get_builtin_bind_pose(j);
+				}
+				break;
+			}
+		}
+	}
+
+	RS::get_singleton()->particles_set_trail_bind_poses(particles, xforms);
+	update_configuration_warnings();
+}
+
+void GPUParticles3D::set_skin(const Ref<Skin> &p_skin) {
+	skin = p_skin;
+	_skinning_changed();
+}
+Ref<Skin> GPUParticles3D::get_skin() const {
+	return skin;
+}
+
+void GPUParticles3D::set_transform_align(TransformAlign p_align) {
+	ERR_FAIL_INDEX(uint32_t(p_align), 4);
+	transform_align = p_align;
+	RS::get_singleton()->particles_set_transform_align(particles, RS::ParticlesTransformAlign(transform_align));
+}
+GPUParticles3D::TransformAlign GPUParticles3D::get_transform_align() const {
+	return transform_align;
+}
+
 void GPUParticles3D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_emitting", "emitting"), &GPUParticles3D::set_emitting);
 	ClassDB::bind_method(D_METHOD("set_amount", "amount"), &GPUParticles3D::set_amount);
@@ -378,6 +510,7 @@ void GPUParticles3D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("set_use_local_coordinates", "enable"), &GPUParticles3D::set_use_local_coordinates);
 	ClassDB::bind_method(D_METHOD("set_fixed_fps", "fps"), &GPUParticles3D::set_fixed_fps);
 	ClassDB::bind_method(D_METHOD("set_fractional_delta", "enable"), &GPUParticles3D::set_fractional_delta);
+	ClassDB::bind_method(D_METHOD("set_interpolate", "enable"), &GPUParticles3D::set_interpolate);
 	ClassDB::bind_method(D_METHOD("set_process_material", "material"), &GPUParticles3D::set_process_material);
 	ClassDB::bind_method(D_METHOD("set_speed_scale", "scale"), &GPUParticles3D::set_speed_scale);
 	ClassDB::bind_method(D_METHOD("set_collision_base_size", "size"), &GPUParticles3D::set_collision_base_size);
@@ -393,6 +526,7 @@ void GPUParticles3D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("get_use_local_coordinates"), &GPUParticles3D::get_use_local_coordinates);
 	ClassDB::bind_method(D_METHOD("get_fixed_fps"), &GPUParticles3D::get_fixed_fps);
 	ClassDB::bind_method(D_METHOD("get_fractional_delta"), &GPUParticles3D::get_fractional_delta);
+	ClassDB::bind_method(D_METHOD("get_interpolate"), &GPUParticles3D::get_interpolate);
 	ClassDB::bind_method(D_METHOD("get_process_material"), &GPUParticles3D::get_process_material);
 	ClassDB::bind_method(D_METHOD("get_speed_scale"), &GPUParticles3D::get_speed_scale);
 	ClassDB::bind_method(D_METHOD("get_collision_base_size"), &GPUParticles3D::get_collision_base_size);
@@ -407,6 +541,9 @@ void GPUParticles3D::_bind_methods() {
 	ClassDB::bind_method(D_METHOD("get_draw_passes"), &GPUParticles3D::get_draw_passes);
 	ClassDB::bind_method(D_METHOD("get_draw_pass_mesh", "pass"), &GPUParticles3D::get_draw_pass_mesh);
 
+	ClassDB::bind_method(D_METHOD("set_skin", "skin"), &GPUParticles3D::set_skin);
+	ClassDB::bind_method(D_METHOD("get_skin"), &GPUParticles3D::get_skin);
+
 	ClassDB::bind_method(D_METHOD("restart"), &GPUParticles3D::restart);
 	ClassDB::bind_method(D_METHOD("capture_aabb"), &GPUParticles3D::capture_aabb);
 
@@ -415,6 +552,15 @@ void GPUParticles3D::_bind_methods() {
 
 	ClassDB::bind_method(D_METHOD("emit_particle", "xform", "velocity", "color", "custom", "flags"), &GPUParticles3D::emit_particle);
 
+	ClassDB::bind_method(D_METHOD("set_enable_trail", "enabled"), &GPUParticles3D::set_enable_trail);
+	ClassDB::bind_method(D_METHOD("set_trail_length", "secs"), &GPUParticles3D::set_trail_length);
+
+	ClassDB::bind_method(D_METHOD("is_trail_enabled"), &GPUParticles3D::is_trail_enabled);
+	ClassDB::bind_method(D_METHOD("get_trail_length"), &GPUParticles3D::get_trail_length);
+
+	ClassDB::bind_method(D_METHOD("set_transform_align", "align"), &GPUParticles3D::set_transform_align);
+	ClassDB::bind_method(D_METHOD("get_transform_align"), &GPUParticles3D::get_transform_align);
+
 	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "emitting"), "set_emitting", "is_emitting");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "amount", PROPERTY_HINT_EXP_RANGE, "1,1000000,1"), "set_amount", "get_amount");
 	ADD_PROPERTY(PropertyInfo(Variant::NODE_PATH, "sub_emitter", PROPERTY_HINT_NODE_PATH_VALID_TYPES, "GPUParticles3D"), "set_sub_emitter", "get_sub_emitter");
@@ -426,6 +572,7 @@ void GPUParticles3D::_bind_methods() {
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "explosiveness", PROPERTY_HINT_RANGE, "0,1,0.01"), "set_explosiveness_ratio", "get_explosiveness_ratio");
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "randomness", PROPERTY_HINT_RANGE, "0,1,0.01"), "set_randomness_ratio", "get_randomness_ratio");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "fixed_fps", PROPERTY_HINT_RANGE, "0,1000,1"), "set_fixed_fps", "get_fixed_fps");
+	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "interpolate"), "set_interpolate", "get_interpolate");
 	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "fract_delta"), "set_fractional_delta", "get_fractional_delta");
 	ADD_GROUP("Collision", "collision_");
 	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "collision_base_size", PROPERTY_HINT_RANGE, "0,128,0.01,or_greater"), "set_collision_base_size", "get_collision_base_size");
@@ -433,6 +580,10 @@ void GPUParticles3D::_bind_methods() {
 	ADD_PROPERTY(PropertyInfo(Variant::AABB, "visibility_aabb"), "set_visibility_aabb", "get_visibility_aabb");
 	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "local_coords"), "set_use_local_coordinates", "get_use_local_coordinates");
 	ADD_PROPERTY(PropertyInfo(Variant::INT, "draw_order", PROPERTY_HINT_ENUM, "Index,Lifetime,View Depth"), "set_draw_order", "get_draw_order");
+	ADD_PROPERTY(PropertyInfo(Variant::INT, "transform_align", PROPERTY_HINT_ENUM, "Disabled,ZBillboard,YToVelocity,ZBillboardYToVelocity"), "set_transform_align", "get_transform_align");
+	ADD_GROUP("Trails", "trail_");
+	ADD_PROPERTY(PropertyInfo(Variant::BOOL, "trail_enabled"), "set_enable_trail", "is_trail_enabled");
+	ADD_PROPERTY(PropertyInfo(Variant::FLOAT, "trail_length_secs", PROPERTY_HINT_RANGE, "0.01,4,0.01"), "set_trail_length", "get_trail_length");
 	ADD_GROUP("Process Material", "");
 	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "process_material", PROPERTY_HINT_RESOURCE_TYPE, "ShaderMaterial,ParticlesMaterial"), "set_process_material", "get_process_material");
 	ADD_GROUP("Draw Passes", "draw_");
@@ -440,6 +591,7 @@ void GPUParticles3D::_bind_methods() {
 	for (int i = 0; i < MAX_DRAW_PASSES; i++) {
 		ADD_PROPERTYI(PropertyInfo(Variant::OBJECT, "draw_pass_" + itos(i + 1), PROPERTY_HINT_RESOURCE_TYPE, "Mesh"), "set_draw_pass_mesh", "get_draw_pass_mesh", i);
 	}
+	ADD_PROPERTY(PropertyInfo(Variant::OBJECT, "draw_skin", PROPERTY_HINT_RESOURCE_TYPE, "Skin"), "set_skin", "get_skin");
 
 	BIND_ENUM_CONSTANT(DRAW_ORDER_INDEX);
 	BIND_ENUM_CONSTANT(DRAW_ORDER_LIFETIME);
@@ -452,6 +604,11 @@ void GPUParticles3D::_bind_methods() {
 	BIND_ENUM_CONSTANT(EMIT_FLAG_CUSTOM);
 
 	BIND_CONSTANT(MAX_DRAW_PASSES);
+
+	BIND_CONSTANT(TRANSFORM_ALIGN_DISABLED);
+	BIND_CONSTANT(TRANSFORM_ALIGN_Z_BILLBOARD);
+	BIND_CONSTANT(TRANSFORM_ALIGN_Y_TO_VELOCITY);
+	BIND_CONSTANT(TRANSFORM_ALIGN_Z_BILLBOARD_Y_TO_VELOCITY);
 }
 
 GPUParticles3D::GPUParticles3D() {
@@ -462,17 +619,20 @@ GPUParticles3D::GPUParticles3D() {
 	set_one_shot(false);
 	set_amount(8);
 	set_lifetime(1);
-	set_fixed_fps(0);
+	set_fixed_fps(30);
 	set_fractional_delta(true);
+	set_interpolate(true);
 	set_pre_process_time(0);
 	set_explosiveness_ratio(0);
 	set_randomness_ratio(0);
+	set_trail_length(0.3);
 	set_visibility_aabb(AABB(Vector3(-4, -4, -4), Vector3(8, 8, 8)));
 	set_use_local_coordinates(true);
 	set_draw_passes(1);
 	set_draw_order(DRAW_ORDER_INDEX);
 	set_speed_scale(1);
 	set_collision_base_size(0.01);
+	set_transform_align(TRANSFORM_ALIGN_DISABLED);
 }
 
 GPUParticles3D::~GPUParticles3D() {
diff --git a/scene/3d/gpu_particles_3d.h b/scene/3d/gpu_particles_3d.h
index b9e2b5ccef..1f9cea79b6 100644
--- a/scene/3d/gpu_particles_3d.h
+++ b/scene/3d/gpu_particles_3d.h
@@ -34,6 +34,7 @@
 #include "core/templates/rid.h"
 #include "scene/3d/visual_instance_3d.h"
 #include "scene/resources/material.h"
+#include "scene/resources/skin.h"
 
 class GPUParticles3D : public GeometryInstance3D {
 private:
@@ -46,6 +47,13 @@ public:
 		DRAW_ORDER_VIEW_DEPTH,
 	};
 
+	enum TransformAlign {
+		TRANSFORM_ALIGN_DISABLED,
+		TRANSFORM_ALIGN_Z_BILLBOARD,
+		TRANSFORM_ALIGN_Y_TO_VELOCITY,
+		TRANSFORM_ALIGN_Z_BILLBOARD_Y_TO_VELOCITY
+	};
+
 	enum {
 		MAX_DRAW_PASSES = 4
 	};
@@ -64,17 +72,26 @@ private:
 	bool local_coords;
 	int fixed_fps;
 	bool fractional_delta;
+	bool interpolate = true;
 	NodePath sub_emitter;
 	float collision_base_size;
 
+	bool trail_enabled = false;
+	float trail_length = 0.3;
+
+	TransformAlign transform_align = TRANSFORM_ALIGN_DISABLED;
+
 	Ref<Material> process_material;
 
 	DrawOrder draw_order;
 
 	Vector<Ref<Mesh>> draw_passes;
+	Ref<Skin> skin;
 
 	void _attach_sub_emitter();
 
+	void _skinning_changed();
+
 protected:
 	static void _bind_methods();
 	void _notification(int p_what);
@@ -96,6 +113,8 @@ public:
 	void set_process_material(const Ref<Material> &p_material);
 	void set_speed_scale(float p_scale);
 	void set_collision_base_size(float p_ratio);
+	void set_enable_trail(bool p_enabled);
+	void set_trail_length(float p_seconds);
 
 	bool is_emitting() const;
 	int get_amount() const;
@@ -109,6 +128,8 @@ public:
 	Ref<Material> get_process_material() const;
 	float get_speed_scale() const;
 	float get_collision_base_size() const;
+	bool is_trail_enabled() const;
+	float get_trail_length() const;
 
 	void set_fixed_fps(int p_count);
 	int get_fixed_fps() const;
@@ -116,6 +137,9 @@ public:
 	void set_fractional_delta(bool p_enable);
 	bool get_fractional_delta() const;
 
+	void set_interpolate(bool p_enable);
+	bool get_interpolate() const;
+
 	void set_draw_order(DrawOrder p_order);
 	DrawOrder get_draw_order() const;
 
@@ -130,6 +154,12 @@ public:
 	void set_sub_emitter(const NodePath &p_path);
 	NodePath get_sub_emitter() const;
 
+	void set_skin(const Ref<Skin> &p_skin);
+	Ref<Skin> get_skin() const;
+
+	void set_transform_align(TransformAlign p_align);
+	TransformAlign get_transform_align() const;
+
 	void restart();
 
 	enum EmitFlags {
@@ -148,6 +178,7 @@ public:
 };
 
 VARIANT_ENUM_CAST(GPUParticles3D::DrawOrder)
+VARIANT_ENUM_CAST(GPUParticles3D::TransformAlign)
 VARIANT_ENUM_CAST(GPUParticles3D::EmitFlags)
 
 #endif // PARTICLES_H