Give Particles Access to Their Spawner Effect (#7034)

* Make particles aware of the effect that spawned them

* Allow modular curves to call global functions from submember inputs

* Add more in and outputs for particle lifetime curves

* Allow post-curve velocity as a curve input

* fix warning and incorrect assig

* Disable CheckTriviallyCopyableMove

* Clang Tidy

Author: BMagnu

.clang-tidy

@@ -48,5 +48,7 @@ CheckOptions:
     value:        'std::vector;std::deque;std::list;SCP_vector;SCP_deque;SCP_list'
   - key:          'readability-braces-around-statements.ShortStatementLines'
     value:        '4' # Avoid flagging simple if (...) return false; statements
+  - key:          'performance-move-const-arg.CheckTriviallyCopyableMove' # This isn't actually performance relevant, but using move on trivially copyable types can well indicate that the variable should not be used anymore, such as when passing a builder type to the finialization function
+    value:        'false'
 ...
 

code/particle/ParticleEffect.cpp

@@ -48,8 +48,6 @@ ParticleEffect::ParticleEffect(SCP_string name)
 	  m_manual_offset (std::nullopt),
 	  m_manual_velocity_offset(std::nullopt),
 	  m_particleTrail(ParticleEffectHandle::invalid()),
-	  m_size_lifetime_curve(-1),
-	  m_vel_lifetime_curve (-1),
 	  m_particleChance(1.f),
 	  m_distanceCulled(-1.f)
 	{}
@@ -119,8 +117,6 @@ ParticleEffect::ParticleEffect(SCP_string name,
 	  m_manual_offset(offsetLocal),
 	  m_manual_velocity_offset(velocityOffsetLocal),
 	  m_particleTrail(particleTrail),
-	  m_size_lifetime_curve(-1),
-	  m_vel_lifetime_curve (-1),
 	  m_particleChance(particleChance),
 	  m_distanceCulled(distanceCulled) {}
 
@@ -268,11 +264,11 @@ auto ParticleEffect::processSourceInternal(float interp, const ParticleSource& s
 	for (uint i = 0; i < num_spawn; ++i) {
 		float particleFraction = static_cast<float>(i) / static_cast<float>(num_spawn);
 
-		particle_info info;
+		particle info;
 
 		info.reverse = m_reverseAnimation;
 		info.pos = pos;
-		info.vel = velParent;
+		info.velocity = velParent;
 
 		if (m_parent_local) {
 			info.attached_objnum = parent;
@@ -284,9 +280,9 @@ auto ParticleEffect::processSourceInternal(float interp, const ParticleSource& s
 		}
 
 		if (m_vel_inherit_absolute)
-			vm_vec_normalize_safe(&info.vel, true);
+			vm_vec_normalize_safe(&info.velocity, true);
 
-		info.vel *= (m_ignore_velocity_inherit_if_has_parent && parent >= 0) ? 0.f : m_vel_inherit.next() * inheritVelocityMultiplier;
+		info.velocity *= (m_ignore_velocity_inherit_if_has_parent && parent >= 0) ? 0.f : m_vel_inherit.next() * inheritVelocityMultiplier;
 
 		vec3d localVelocity = velNoise;
 		vec3d localPos = posNoise;
@@ -325,32 +321,43 @@ auto ParticleEffect::processSourceInternal(float interp, const ParticleSource& s
 				m_velocity_directional_scaling == VelocityScaling::DOT ? dot : 1.f / std::max(0.001f, dot));
 		}
 
-		info.vel += localVelocity;
-		info.pos += localPos + info.vel * (interp * f2fl(Frametime));
+		info.velocity += localVelocity;
+		info.pos += localPos + info.velocity * (interp * f2fl(Frametime));
 
 		info.bitmap = m_bitmap_list[m_bitmap_range.next()];
 
 		if (m_parentScale)
 			// if we were spawned by a particle, parentRadius is the parent's radius and m_radius is a factor of that
-			info.rad = parentRadius * m_radius.next() * radiusMultiplier;
+			info.radius = parentRadius * m_radius.next() * radiusMultiplier;
 		else
-			info.rad = m_radius.next() * radiusMultiplier;
+			info.radius = m_radius.next() * radiusMultiplier;
 
 		info.length = m_length.next() * lengthMultiplier;
-		if (m_hasLifetime) {
-			if (m_parentLifetime)
-				// if we were spawned by a particle, parentLifetime is the parent's remaining lifetime and m_lifetime is a factor of that
-				info.lifetime = parentLifetime * m_lifetime.next() * lifetimeMultiplier;
-			else
-				info.lifetime = m_lifetime.next() * lifetimeMultiplier;
 
-			info.lifetime_from_animation = m_keep_anim_length_if_available;
+		int fps = 1;
+		if (info.nframes < 0) {
+			Assertion(bm_is_valid(info.bitmap), "Invalid bitmap handle passed to particle create.");
+			bm_get_info(info.bitmap, nullptr, nullptr, nullptr, &info.nframes, &fps);
+		}
+
+		if (m_hasLifetime) {
+			if (m_keep_anim_length_if_available && info.nframes > 1) {
+				// Recalculate max life for ani's
+				info.max_life = i2fl(info.nframes) / i2fl(fps);
+			}
+			else {
+				if (m_parentLifetime)
+					// if we were spawned by a particle, parentLifetime is the parent's remaining lifetime and m_lifetime is a factor of that
+					info.max_life = parentLifetime * m_lifetime.next() * lifetimeMultiplier;
+				else
+					info.max_life = m_lifetime.next() * lifetimeMultiplier;
+			}
 		}
 
-		info.starting_age = interp * f2fl(Frametime);
-		
-		info.size_lifetime_curve = m_size_lifetime_curve;
-		info.vel_lifetime_curve = m_vel_lifetime_curve;
+		info.age = interp * f2fl(Frametime);
+		info.looping = false;
+		info.angle = frand_range(0.0f, PI2);
+		info.parent_effect = m_self;
 
 		switch (m_rotation_type) {
 			case RotationType::DEFAULT:
@@ -367,7 +374,7 @@ auto ParticleEffect::processSourceInternal(float interp, const ParticleSource& s
 		}
 
 		if (m_particleTrail.isValid()) {
-			auto part = createPersistent(&info);
+			auto part = createPersistent(std::move(info));
 
 			if constexpr (isPersistent)
 				createdParticles.push_back(part);
@@ -381,12 +388,12 @@ auto ParticleEffect::processSourceInternal(float interp, const ParticleSource& s
 			}
 		} else {
 			if constexpr (isPersistent){
-				auto part = createPersistent(&info);
+				auto part = createPersistent(std::move(info));
 				createdParticles.push_back(part);
 			}
 			else {
 				// We don't have a trail so we don't need a persistent particle
-				create(&info);
+				create(std::move(info));
 			}
 		}
 	}

code/particle/ParticleEffect.h

@@ -84,15 +84,25 @@ class ParticleEffect {
 		NUM_VALUES
 	};
 
+	enum class ParticleLifetimeCurvesOutput : uint8_t {
+		VELOCITY_MULT,
+		RADIUS_MULT,
+		LENGTH_MULT,
+		ANIM_STATE,
+
+		NUM_VALUES
+	};
+
  private:
 	friend struct ParticleParse;
-
+	friend class ParticleManager;
 	friend int ::parse_weapon(int, bool, const char*);
-
 	friend ParticleEffectHandle scripting::api::getLegacyScriptingParticleEffect(int bitmap, bool reversed);
 
 	SCP_string m_name; //!< The name of this effect
 
+	ParticleSubeffectHandle m_self;
+
 	Duration m_duration;
 	RotationType m_rotation_type;
 	ShapeDirection m_direction;
@@ -138,9 +148,6 @@ class ParticleEffect {
 
 	ParticleEffectHandle m_particleTrail;
 
-	int m_size_lifetime_curve; //This is a curve of the particle, not of the particle effect, as such, it should not be part of the curve set
-	int m_vel_lifetime_curve; //This is a curve of the particle, not of the particle effect, as such, it should not be part of the curve set
-
 	float m_particleChance; //Deprecated. Use particle num random ranges instead.
 	float m_distanceCulled; //Kinda deprecated. Only used by the oldest of legacy effects.
 
@@ -251,7 +258,28 @@ class ParticleEffect {
 			ModularCurvesMathOperators::division>{}}
 		);
 
+	constexpr static auto modular_curves_lifetime_definition = make_modular_curve_definition<particle, ParticleLifetimeCurvesOutput>(
+		std::array {
+				std::pair {"Radius", ParticleLifetimeCurvesOutput::RADIUS_MULT},
+				std::pair {"Velocity", ParticleLifetimeCurvesOutput::VELOCITY_MULT},
+				std::pair {"Length", ParticleLifetimeCurvesOutput::LENGTH_MULT},
+				std::pair {"Anim State", ParticleLifetimeCurvesOutput::ANIM_STATE},
+		},
+		//Should you ever need to access something from the effect as a modular curve input:
+		//std::pair {"", modular_curves_submember_input<&particle::parent_effect, &ParticleSubeffectHandle::getParticleEffect, &ParticleEffect::>{}}
+		std::pair {"Age", modular_curves_submember_input<&particle::age>{}},
+		std::pair {"Lifetime", modular_curves_math_input<
+		     modular_curves_submember_input<&particle::age>,
+			 modular_curves_submember_input<&particle::max_life>,
+			 ModularCurvesMathOperators::division>{}},
+		std::pair {"Radius", modular_curves_submember_input<&particle::radius>{}},
+		std::pair {"Velocity", modular_curves_submember_input<&particle::velocity, &vm_vec_mag_quick>{}})
+	.derive_modular_curves_input_only_subset<float>(
+		std::pair {"Post-Curves Velocity", modular_curves_self_input{}}
+		);
+
 	MODULAR_CURVE_SET(m_modular_curves, modular_curves_definition);
+	MODULAR_CURVE_SET(m_lifetime_curves, modular_curves_lifetime_definition);
 
   private:
 	float getCurrentFrequencyMult(decltype(modular_curves_definition)::input_type_t source) const;

code/particle/ParticleManager.cpp

@@ -135,9 +135,13 @@ ParticleEffectHandle ParticleManager::addEffect(SCP_vector<ParticleEffect>&& eff
 	}
 #endif
 
-	m_effects.emplace_back(std::move(effect));
+	auto& effect_after_emplace = m_effects.emplace_back(std::move(effect));
 
-	return ParticleEffectHandle(static_cast<ParticleEffectHandle::impl_type>(m_effects.size() - 1));
+	auto handle = ParticleEffectHandle(static_cast<ParticleEffectHandle::impl_type>(m_effects.size() - 1));
+	for (size_t i = 0; i < effect_after_emplace.size(); i++)
+		effect_after_emplace[i].m_self = ParticleSubeffectHandle{handle, i};
+
+	return handle;
 }
 
 void ParticleManager::pageIn() {

code/particle/ParticleParse.cpp

@@ -283,20 +283,7 @@ namespace particle {
 		}
 
 		static void parseModularCurvesLifetime(ParticleEffect& effect) {
-			//TODO The following loop behaves as a true subset of how parsing will work once the particle modular curve set is implemented.
-			//As such, once that's added the loop can be replaced with a modular_curve_set.parse without worry about breaking tables.
-			while (optional_string("$Particle Lifetime Curve:")) {
-				required_string("+Input: Lifetime");
-
-				required_string("+Output:");
-				int output = required_string_one_of(2, "Radius", "Velocity");
-				//The required string part enforces this to be either 0 or 1
-				required_string(output == 0 ? "Radius" : "Velocity");
-				int& curve = output == 0 ? effect.m_size_lifetime_curve : effect.m_vel_lifetime_curve;
-
-				required_string_either("+Curve Name:", "+Curve:", true);
-				curve = curve_parse(" Unknown curve requested for modular curves!");
-			}
+			effect.m_lifetime_curves.parse("$Particle Lifetime Curve:");
 		}
 
 		static void parseModularCurvesSource(ParticleEffect& effect) {
@@ -368,13 +355,13 @@ namespace particle {
 
 		static void parseSizeLifetimeCurve(ParticleEffect &effect) {
 			if (optional_string("+Size over lifetime curve:")) {
-				effect.m_size_lifetime_curve = curve_parse("");
+				effect.m_lifetime_curves.add_curve("Lifetime", ParticleEffect::ParticleLifetimeCurvesOutput::RADIUS_MULT, modular_curves_entry{curve_parse("")});
 			}
 		}
 
 		static void parseVelocityLifetimeCurve(ParticleEffect &effect) {
 			if (optional_string("+Velocity scalar over lifetime curve:")) {
-				effect.m_vel_lifetime_curve = curve_parse("");
+				effect.m_lifetime_curves.add_curve("Lifetime", ParticleEffect::ParticleLifetimeCurvesOutput::VELOCITY_MULT, modular_curves_entry{curve_parse("")});
 			}
 		}
 

code/particle/ParticleSource.h

@@ -19,11 +19,6 @@ struct weapon_info;
 enum class WeaponState: uint32_t;
 
 namespace particle {
-	
-class ParticleEffect;
-struct particle_effect_tag {
-};
-using ParticleEffectHandle = ::util::ID<particle_effect_tag, ptrdiff_t, -1>;
 
 /**
  * @brief The orientation of a particle source

code/particle/hosts/EffectHostParticle.cpp

@@ -7,6 +7,8 @@
 
 #include "freespace.h"
 
+#include "particle/ParticleEffect.h"
+
 EffectHostParticle::EffectHostParticle(particle::WeakParticlePtr particle, matrix orientationOverride, bool orientationOverrideRelative) :
 	EffectHost(orientationOverride, orientationOverrideRelative), m_particle(std::move(particle)) {}
 
@@ -16,10 +18,7 @@ std::pair<vec3d, matrix> EffectHostParticle::getPositionAndOrientation(bool /*re
 
 	vec3d pos;
 	if (interp != 0.0f) {
-		float vel_scalar = 1.0f;
-		if (particle->vel_lifetime_curve >= 0) {
-			vel_scalar = Curves[particle->vel_lifetime_curve].GetValue(particle->age / particle->max_life);
-		}
+		float vel_scalar = particle->parent_effect.getParticleEffect().m_lifetime_curves.get_output(particle::ParticleEffect::ParticleLifetimeCurvesOutput::VELOCITY_MULT, std::forward_as_tuple(*particle, vm_vec_mag_quick(&particle->velocity)));
 		vec3d pos_last = particle->pos - (particle->velocity * vel_scalar * flFrametime);
 		vm_vec_linear_interpolate(&pos, &particle->pos, &pos_last, interp);
 	} else {
@@ -52,11 +51,11 @@ float EffectHostParticle::getLifetime() const {
 
 float EffectHostParticle::getScale() const {
 	const auto& particle = m_particle.lock();
-	int idx = particle->size_lifetime_curve;
-	if (idx >= 0)
-		return particle->radius * Curves[idx].GetValue(particle->age / particle->max_life);
-	else
-		return particle->radius;
+	//For anything apart from the velocity curve, "Post-Curves Velocity" is well defined. This is needed to facilitate complex but common particle scaling and appearance curves.
+	const auto& curve_input = std::forward_as_tuple(*particle,
+		vm_vec_mag_quick(&particle->velocity) * particle->parent_effect.getParticleEffect().m_lifetime_curves.get_output(particle::ParticleEffect::ParticleLifetimeCurvesOutput::ANIM_STATE, std::forward_as_tuple(*particle, vm_vec_mag_quick(&particle->velocity))));
+
+	return particle->radius * particle->parent_effect.getParticleEffect().m_lifetime_curves.get_output(particle::ParticleEffect::ParticleLifetimeCurvesOutput::RADIUS_MULT, curve_input);
 }
 
 bool EffectHostParticle::isValid() const {