add $purge player-issued form-on-wing after subsequent order: flag

Author: Goober5000

code/ai/ai_flags.h

@@ -46,6 +46,7 @@ namespace AI {
 		Goal_override,		// paired with ai_goal_type::DYNAMIC to mean this goal overrides any other goal
 		Want_override,		// a goal should set this flag if Goal_override should be assigned when the goal is achievable
 		Purge,				// purge this goal next time we process
+		Purge_when_new_goal_added,	// this goal is perpetual until any other goal is added, at which time it sets its own Purge flag
 		Goals_purged,		// this goal has already caused other goals to get purged (because it is something like ai-disarm that renders other goals invalid)
 		Depart_sound_played,// Goober5000 - replacement for AL's hack ;)
 		Target_own_team,	// this attack goal is allowed to target friendlies
@@ -183,6 +184,7 @@ namespace AI {
 		Do_not_clear_goals_when_assigning_form_on_wing,
 		Do_not_clear_goals_when_assigning_stay_still,
 		Do_not_set_override_when_assigning_form_on_wing,
+		Purge_player_issued_form_on_wing_after_subsequent_order,
 
 		NUM_VALUES
 	};

code/ai/ai_profiles.cpp

@@ -727,6 +727,9 @@ void parse_ai_profiles_tbl(const char *filename)
 
 				set_flag(profile, "$do not set override when assigning form-on-wing:", AI::Profile_Flags::Do_not_set_override_when_assigning_form_on_wing);
 
+				set_flag(profile, "$purge player-issued form-on-wing after subsequent order:", AI::Profile_Flags::Purge_player_issued_form_on_wing_after_subsequent_order);
+
+
 				// end of options ----------------------------------------
 
 				// if we've been through once already and are at the same place, force a move
@@ -944,5 +947,6 @@ void ai_profile_t::reset()
 	}
 	if (mod_supports_version(25, 0, 0)) {
 		flags.set(AI::Profile_Flags::Fix_avoid_shockwave_bugs);
+		flags.set(AI::Profile_Flags::Purge_player_issued_form_on_wing_after_subsequent_order);
 	}
 }

code/ai/aigoals.cpp

@@ -763,6 +763,10 @@ void ai_add_goal_sub_player(ai_goal_type type, ai_goal_mode mode, int submode, c
 	if (mode == AI_GOAL_FORM_ON_WING && !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_set_override_when_assigning_form_on_wing])
 		aigp->flags.set(AI::Goal_Flags::Want_override);
 
+	// generally, players want ships to form-on-wing only until they need to do something else
+	if (mode == AI_GOAL_FORM_ON_WING && The_mission.ai_profile->flags[AI::Profile_Flags::Purge_player_issued_form_on_wing_after_subsequent_order])
+		aigp->flags.set(AI::Goal_Flags::Purge_when_new_goal_added);
+
 	if (The_mission.ai_profile->flags[AI::Profile_Flags::Player_orders_afterburn_hard])
 		aigp->flags.set(AI::Goal_Flags::Afterburn_hard);
 
@@ -792,14 +796,19 @@ void ai_add_goal_sub_player(ai_goal_type type, ai_goal_mode mode, int submode, c
 // my new docking code. :)
 int ai_goal_find_empty_slot( ai_goal *goals, int active_goal )
 {
-	int gindex, oldest_index;
+	int oldest_index = -1, empty_index = -1;
 
-	oldest_index = -1;
-	for ( gindex = 0; gindex < MAX_AI_GOALS; gindex++ )
+	for ( int gindex = 0; gindex < MAX_AI_GOALS; gindex++ )
 	{
 		// get the index for the first unused goal
 		if (goals[gindex].ai_mode == AI_GOAL_NONE)
-			return gindex;
+		{
+			if (empty_index < 0)
+				empty_index = gindex;
+		}
+		// if any goal needs to be purged when we add a goal, set the flag
+		else if (goals[gindex].flags[AI::Goal_Flags::Purge_when_new_goal_added])
+			goals[gindex].flags.set(AI::Goal_Flags::Purge);
 
 		// if this is the active goal, don't consider it for pre-emption!!
 		if (gindex == active_goal)
@@ -812,6 +821,10 @@ int ai_goal_find_empty_slot( ai_goal *goals, int active_goal )
 			oldest_index = gindex;
 	}
 
+	// try to use the first empty slot
+	if (empty_index >= 0)
+		return empty_index;
+
 	// if we didn't find an empty slot, use the oldest goal's slot
 	return oldest_index;
 }
@@ -1148,6 +1161,13 @@ void ai_add_goal_sub_sexp( int sexp, ai_goal_type type, ai_info *aip, ai_goal *a
 		if (set_override)
 			aigp->flags.set(AI::Goal_Flags::Want_override);
 
+		if (n >= 0)
+		{
+			if (is_sexp_true(n))
+				aigp->flags.set(AI::Goal_Flags::Purge_when_new_goal_added);
+			n = CDR(n);
+		}
+
 		aigp->ai_mode = AI_GOAL_FORM_ON_WING;
 		break;
 	}

code/parse/sexp.cpp

@@ -866,7 +866,7 @@ SCP_vector<sexp_oper> Operators = {
 	{ "ai-waypoints-once",				OP_AI_WAYPOINTS_ONCE,					2,	5,			SEXP_GOAL_OPERATOR,	},
 	{ "ai-ignore",						OP_AI_IGNORE,							2,	2,			SEXP_GOAL_OPERATOR,	},
 	{ "ai-ignore-new",					OP_AI_IGNORE_NEW,						2,	2,			SEXP_GOAL_OPERATOR,	},
-	{ "ai-form-on-wing",				OP_AI_FORM_ON_WING,						1,	4,			SEXP_GOAL_OPERATOR, },
+	{ "ai-form-on-wing",				OP_AI_FORM_ON_WING,						1,	5,			SEXP_GOAL_OPERATOR, },
 	{ "ai-fly-to-ship",					OP_AI_FLY_TO_SHIP,						2,	5,			SEXP_GOAL_OPERATOR, },
 	{ "ai-stay-near-ship",				OP_AI_STAY_NEAR_SHIP,					2,	5,			SEXP_GOAL_OPERATOR,	},
 	{ "ai-evade-ship",					OP_AI_EVADE_SHIP,						2,	2,			SEXP_GOAL_OPERATOR,	},
@@ -39918,11 +39918,12 @@ SCP_vector<sexp_help_struct> Sexp_help = {
 		"\tCauses the ship to form on the specified ship's wing. This works analogous to the "
 		"player order, and by default will cause all goals on the ship's goal list to be cleared when this goal runs. "
 		"By default it will also take priority over all other goals.\r\n\r\n"
-		"Takes 1 to 4 arguments...\r\n"
+		"Takes 1 to 5 arguments...\r\n"
 		"\t1:\tShip to form on.\r\n"
 		"\t2:\tGoal priority (number between 0 and 89, optional).  If not specified this will be 99, or the number defined in ai_profiles.\r\n"
 		"\t3:\tWhether to clear all goals (optional).  If not specified this will be true, or the value defined in ai_profiles.\r\n"
 		"\t4:\tWhether this goal should override all other goals (optional).  If not specified this will be true, or the value defined in ai_profiles.\r\n"
+		"\t5:\tWhether this goal should be cleared if any other goal is assigned (optional).  If not specified this will be false.\r\n"
 	},
 
 	{ OP_FLASH_HUD_GAUGE, "Ai-flash hud gauge (Training goal)\r\n"

code/scripting/api/objs/order.cpp

@@ -489,20 +489,30 @@ ADE_VIRTVAR(WaypointsInReverse, l_Order, "boolean", "Waypoint-reverse flag of th
 	return ade_set_args(L, "b", ohp->aigp->flags[AI::Goal_Flags::Waypoints_in_reverse]);
 }
 
-ADE_VIRTVAR(OverridesWhenAchievable, l_Order, "boolean", "Whether this goal pre-empts all other goals when it is achievable", "boolean", "OverridesWhenAchievable flag, or invalid false if order handle is invalid")
+int goal_flag_helper(lua_State* L, AI::Goal_Flags flag)
 {
 	order_h* ohp = nullptr;
-	bool want_override = false;
-	if (!ade_get_args(L, "o|b", l_Order.GetPtr(&ohp), &want_override))
+	bool set_it = false;
+	if (!ade_get_args(L, "o|b", l_Order.GetPtr(&ohp), &set_it))
 		return ade_set_error(L, "b", false);
 
 	if (!ohp->isValid())
 		return ade_set_error(L, "b", false);
 
 	if (ADE_SETTING_VAR)
-		ohp->aigp->flags.set(AI::Goal_Flags::Want_override, want_override);
+		ohp->aigp->flags.set(flag, set_it);
+
+	return ade_set_args(L, "b", ohp->aigp->flags[flag]);
+}
+
+ADE_VIRTVAR(OverridesWhenAchievable, l_Order, "boolean", "Whether this goal pre-empts all other goals when it is achievable", "boolean", "OverridesWhenAchievable flag, or invalid false if order handle is invalid")
+{
+	return goal_flag_helper(L, AI::Goal_Flags::Want_override);
+}
 
-	return ade_set_args(L, "b", ohp->aigp->flags[AI::Goal_Flags::Want_override]);
+ADE_VIRTVAR(PurgeWhenNewGoalAdded, l_Order, "boolean", "Whether this goal should be purged (removed) when another goal is assigned", "boolean", "PurgeWhenNewGoalAdded flag, or invalid false if order handle is invalid")
+{
+	return goal_flag_helper(L, AI::Goal_Flags::Purge_when_new_goal_added);
 }
 
 ADE_FUNC(isValid, l_Order, NULL, "Detects whether handle is valid", "boolean", "true if valid, false if handle is invalid, nil if a syntax/type error occurs")