subsystem scripting enhancements

Add several API features to improve scripting support for subsystems.

1. A `CanonicalName` virtvar to provide a clear way to get subsystem names for indexing and referencing
2. `Submodel` and `SubmodelInstance` virtvars to get the submodel information associated with the subsystem, if it exists
3. A `getSubsystemList()` function to provide a subsystem iterator

Author: Goober5000

code/scripting/api/objs/model.cpp

@@ -63,6 +63,34 @@ bool submodel_h::isValid() const
 }
 
 
+ADE_FUNC(__eq, l_Model, "model, model", "Checks if two model handles refer to the same model", "boolean", "True if models are equal")
+{
+	model_h* mdl1;
+	model_h* mdl2;
+
+	if (!ade_get_args(L, "oo", l_Model.GetPtr(&mdl1), l_Model.GetPtr(&mdl2)))
+		return ADE_RETURN_NIL;
+
+	if (mdl1->GetID() == mdl2->GetID())
+		return ADE_RETURN_TRUE;
+
+	return ADE_RETURN_FALSE;
+}
+
+ADE_FUNC(__eq, l_Submodel, "submodel, submodel", "Checks if two submodel handles refer to the same submodel", "boolean", "True if submodels are equal")
+{
+	submodel_h* smh1;
+	submodel_h* smh2;
+
+	if (!ade_get_args(L, "oo", l_Submodel.GetPtr(&smh1), l_Submodel.GetPtr(&smh2)))
+		return ADE_RETURN_NIL;
+
+	if (smh1->GetModelID() == smh2->GetModelID() && smh1->GetSubmodelIndex() == smh2->GetSubmodelIndex())
+		return ADE_RETURN_TRUE;
+
+	return ADE_RETURN_FALSE;
+}
+
 ADE_VIRTVAR(Submodels, l_Model, nullptr, "Model submodels", "submodels", "Model submodels, or an invalid submodels handle if the model handle is invalid")
 {
 	model_h *mdl = nullptr;

code/scripting/api/objs/ship.cpp

@@ -94,6 +94,36 @@ ADE_FUNC(__len, l_Ship, NULL, "Number of subsystems on ship", "number", "Subsyst
 	return ade_set_args(L, "i", ship_get_num_subsys(&Ships[objh->objp()->instance]));
 }
 
+ADE_FUNC(getSubsystemList,
+	l_Ship,
+	nullptr,
+	"Get the list of subsystems on this ship",
+	"iterator<subsystem>",
+	"An iterator across all subsystems on the ship. Can be used in a for .. in loop. Is not valid for more than one frame.")
+{
+	object_h* objh;
+	if (!ade_get_args(L, "o", l_Ship.GetPtr(&objh)))
+		return ADE_RETURN_NIL;
+
+	if (!objh->isValid())
+		return ADE_RETURN_NIL;
+
+	ship* shipp = &Ships[objh->objp()->instance];
+	ship_subsys* ss = &shipp->subsys_list;
+
+	return ade_set_args(L, "u", luacpp::LuaFunction::createFromStdFunction(L, [shipp, ss](lua_State* LInner, const luacpp::LuaValueList& /*params*/) mutable -> luacpp::LuaValueList {
+		//Since the first element of a list is the next element from the head, and we start this function with the captured "ss" object being the head, this GET_NEXT will return the first element on first call of this lambda.
+		//Similarly, an empty list is defined by the head's next element being itself, hence an empty list will immediately return nil just fine
+		ss = GET_NEXT(ss);
+
+		if (ss == END_OF_LIST(&shipp->subsys_list) || ss == nullptr) {
+			return luacpp::LuaValueList{ luacpp::LuaValue::createNil(LInner) };
+		}
+
+		return luacpp::LuaValueList{ luacpp::LuaValue::createValue(LInner, l_Subsystem.Set(ship_subsys_h(&Objects[shipp->objnum], ss))) };
+	}));
+}
+
 ADE_FUNC(setFlag, l_Ship, "boolean set_it, string flag_name", "Sets or clears one or more flags - this function can accept an arbitrary number of flag arguments.  The flag names can be any string that the alter-ship-flag SEXP operator supports.", nullptr, "Returns nothing")
 {
 	object_h *objh;

code/scripting/api/objs/subsystem.cpp

@@ -2,13 +2,15 @@
 //
 
 #include "subsystem.h"
+#include "model.h"
 #include "model_path.h"
 #include "object.h"
 #include "ship.h"
 #include "ship_bank.h"
 #include "vecmath.h"
 #include "hud/hudtarget.h"
 #include "ship/shiphit.h"
+#include "modelinstance.h"
 
 #include "network/multi.h"
 #include "network/multimsgs.h"
@@ -121,6 +123,38 @@ ADE_VIRTVAR(AWACSRadius, l_Subsystem, "number", "Subsystem AWACS radius", "numbe
 	return ade_set_args(L, "f", sso->ss->awacs_radius);
 }
 
+ADE_VIRTVAR(Submodel, l_Subsystem, "submodel", "The submodel corresponding to this subsystem, if one exists", "submodel", "Submodel handle, or invalid submodel handle if this subsystem does not have a submodel, or if the subsystem handle is invalid")
+{
+	ship_subsys_h *sso;
+	if (!ade_get_args(L, "o", l_Subsystem.GetPtr(&sso)))
+		return ade_set_error(L, "o", l_Submodel.Set(submodel_h()));
+
+	if (!sso->isValid())
+		return ade_set_error(L, "o", l_Submodel.Set(submodel_h()));
+
+	if (ADE_SETTING_VAR)
+		LuaError(L, "Setting the Submodel is not allowed!");
+
+	return ade_set_args(L, "o", l_Submodel.Set(submodel_h(sso->ss->system_info->model_num, sso->ss->system_info->subobj_num)));
+}
+
+ADE_VIRTVAR(SubmodelInstance, l_Subsystem, "submodel_instance", "The submodel instance corresponding to this subsystem, if one exists", "submodel_instance", "Submodel instance handle, or invalid submodel instance handle if this subsystem does not have a submodel instance, or if the subsystem handle is invalid")
+{
+	ship_subsys_h *sso;
+	if (!ade_get_args(L, "o", l_Subsystem.GetPtr(&sso)))
+		return ade_set_error(L, "o", l_SubmodelInstance.Set(submodelinstance_h()));
+
+	if (!sso->isValid())
+		return ade_set_error(L, "o", l_SubmodelInstance.Set(submodelinstance_h()));
+
+	if (ADE_SETTING_VAR)
+		LuaError(L, "Setting the SubmodelInstance is not allowed!");
+
+	auto shipp = &Ships[sso->objh.objp()->instance];
+	auto pmi = model_get_instance(shipp->model_instance_num);
+	return ade_set_args(L, "o", l_SubmodelInstance.Set(submodelinstance_h(pmi, sso->ss->system_info->subobj_num)));
+}
+
 ADE_VIRTVAR(Orientation, l_Subsystem, "orientation", "Orientation of subobject or turret base", "orientation", "Subsystem orientation, or identity orientation if handle is invalid")
 {
 	ship_subsys_h *sso;
@@ -345,6 +379,22 @@ ADE_VIRTVAR(NameOnHUD, l_Subsystem, "string", "Subsystem name as it would be dis
 	return ade_set_args(L, "s", ship_subsys_get_name_on_hud(sso->ss));
 }
 
+ADE_VIRTVAR(CanonicalName, l_Subsystem, "string", "Canonical subsystem name that can be used to reference this subsystem in a SEXP or script", "string", "Canonical subsystem name, or an empty string if handle is invalid")
+{
+	ship_subsys_h *sso;
+
+	if (!ade_get_args(L, "o", l_Subsystem.GetPtr(&sso)))
+		return ade_set_error(L, "s", "");
+
+	if (!sso->isValid())
+		return ade_set_error(L, "s", "");
+
+	if (ADE_SETTING_VAR)
+		LuaError(L, "Setting the CanonicalName is not allowed!");
+
+	return ade_set_args(L, "s", ship_subsys_get_canonical_name(sso->ss));
+}
+
 ADE_VIRTVAR(NumFirePoints, l_Subsystem, "number", "Number of firepoints", "number", "Number of fire points, or 0 if handle is invalid")
 {
 	ship_subsys_h* sso;
@@ -384,7 +434,7 @@ ADE_VIRTVAR(FireRateMultiplier, l_Subsystem, "number", "Factor by which turret's
 	return ade_set_args(L, "f", sso->ss->rof_scaler);
 }
 
-ADE_FUNC(getModelName, l_Subsystem, NULL, "Returns the original name of the subsystem in the model file", "string", "name or empty string on error")
+ADE_FUNC(getModelName, l_Subsystem, nullptr, "Returns the original name of the subsystem as defined in the ship class, which could possibly correspond to a submodel in the model file.  This is the same as CanonicalName.", "string", "name or empty string on error")
 {
 	ship_subsys_h *sso;
 	if(!ade_get_args(L, "o", l_Subsystem.GetPtr(&sso)))
@@ -393,7 +443,7 @@ ADE_FUNC(getModelName, l_Subsystem, NULL, "Returns the original name of the subs
 	if (!sso->isValid())
 		return ade_set_error(L, "s", "");
 
-	return ade_set_args(L, "s", sso->ss->system_info->subobj_name);
+	return ade_set_args(L, "s", ship_subsys_get_canonical_name(sso->ss));
 }
 
 ADE_VIRTVAR(PrimaryBanks, l_Subsystem, "weaponbanktype", "Array of primary weapon banks", "weaponbanktype", "Primary banks, or invalid weaponbanktype handle if subsystem handle is invalid")

code/ship/ship.cpp

@@ -17189,6 +17189,11 @@ const char *ship_subsys_get_name_on_hud(const ship_subsys *ss)
 		return ship_subsys_get_name(ss);
 }
 
+const char *ship_subsys_get_canonical_name(const ship_subsys *ss)
+{
+	return ss->system_info->subobj_name;
+}
+
 /**
  * Return the shield strength of the specified quadrant on hit_objp
  *

code/ship/ship.h

@@ -1803,6 +1803,7 @@ bool ship_subsys_has_instance_name(const ship_subsys *ss);
 void ship_subsys_set_name(ship_subsys* ss, const char* n_name);
 
 const char *ship_subsys_get_name_on_hud(const ship_subsys *ss);
+const char *ship_subsys_get_canonical_name(const ship_subsys *ss);
 
 // subsys disruption
 extern int ship_subsys_disrupted(const ship_subsys *ss);