enhance goals with additional parameters

Author: Goober5000

code/ai/ai_flags.h

@@ -44,6 +44,7 @@ namespace AI {
 		Goal_on_hold,		// when set, this goal cannot currently be satisfied, although it could be in the future
 		Subsys_needs_fixup,	// when set, the subsystem index (for a destroy subsystem goal) is invalid and must be gotten from the subsys name stored in docker.name field!!
 		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
 		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 ;)
@@ -177,6 +178,9 @@ namespace AI {
 		Freespace_1_missile_behavior,
 		ETS_uses_power_output,
 		ETS_energy_same_regardless_of_system_presence,
+		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,
 
 		NUM_VALUES
 	};

code/ai/ai_profiles.cpp

@@ -707,6 +707,21 @@ void parse_ai_profiles_tbl(const char *filename)
 
 				set_flag(profile, "$ETS energy same regardless of system presence:", AI::Profile_Flags::ETS_energy_same_regardless_of_system_presence);
 
+				if (optional_string("$default form-on-wing priority:")) {
+					int priority;
+					stuff_int(&priority);
+					if (priority > 0) {
+						profile->default_form_on_wing_priority = priority;
+					} else {
+						mprintf(("Warning: $default form-on-wing priority: should be > 0 (read %d).  Value will not be used.\n", priority));
+					}
+				}
+
+				set_flag(profile, "$do not clear goals when assigning form-on-wing:", AI::Profile_Flags::Do_not_clear_goals_when_assigning_form_on_wing);
+
+				set_flag(profile, "$do not clear goals when assigning stay-still:", AI::Profile_Flags::Do_not_clear_goals_when_assigning_stay_still);
+
+				set_flag(profile, "$do not set override when assigning form-on-wing:", AI::Profile_Flags::Do_not_set_override_when_assigning_form_on_wing);
 
 				// end of options ----------------------------------------
 
@@ -810,6 +825,8 @@ void ai_profile_t::reset()
 	guard_big_orbit_above_target_radius = 500.0f;
 	guard_big_orbit_max_speed_percent = 1.0f;
 
+	default_form_on_wing_priority = 99;	// as originally assigned in ai_add_goal_sub_sexp()
+
     for (int i = 0; i < NUM_SKILL_LEVELS; ++i) {
         max_incoming_asteroids[i] = 0;
         max_allowed_player_homers[i] = 0;

code/ai/ai_profiles.h

@@ -144,6 +144,8 @@ class ai_profile_t {
 	float guard_big_orbit_above_target_radius; // Radius of guardee that triggers ai_big_guard() 
 	float guard_big_orbit_max_speed_percent;   // Max percent of forward speed that is used in ai_big_guard() 
 
+	int default_form_on_wing_priority;	// the priority used if not specified in the sexp
+
     void reset();
 };
 

code/ai/aigoals.cpp

@@ -754,8 +754,14 @@ void ai_add_goal_sub_player(ai_goal_type type, ai_goal_mode mode, int submode, c
 		aigp->target_name = ai_get_goal_target_name( target_name, &aigp->target_name_index );
 
 	// set up the clear-goals flag for certain goals
-	if (mode == AI_GOAL_STAY_STILL || mode == AI_GOAL_FORM_ON_WING || mode == AI_GOAL_PLAY_DEAD)
-		aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
+	if ((mode == AI_GOAL_STAY_STILL && !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_clear_goals_when_assigning_stay_still])
+	 || (mode == AI_GOAL_FORM_ON_WING && !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_clear_goals_when_assigning_form_on_wing])
+	 || (mode == AI_GOAL_PLAY_DEAD))
+			aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
+
+	// also set up the override, since it's no longer done automatically in ai_mission_goal_achievable
+	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);
 
 	if (The_mission.ai_profile->flags[AI::Profile_Flags::Player_orders_afterburn_hard])
 		aigp->flags.set(AI::Goal_Flags::Afterburn_hard);
@@ -839,8 +845,14 @@ void ai_add_goal_sub_scripting(ai_goal_type type, ai_goal_mode mode, int submode
 		aigp->target_name = ai_get_goal_target_name( target_name, &aigp->target_name_index );
 
 	// set up the clear-goals flag for certain goals
-	if (mode == AI_GOAL_STAY_STILL || mode == AI_GOAL_FORM_ON_WING || mode == AI_GOAL_PLAY_DEAD)
-		aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
+	if ((mode == AI_GOAL_STAY_STILL && !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_clear_goals_when_assigning_stay_still])
+	 || (mode == AI_GOAL_FORM_ON_WING && !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_clear_goals_when_assigning_form_on_wing])
+	 || (mode == AI_GOAL_PLAY_DEAD))
+			aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
+
+	// also set up the override, since it's no longer done automatically in ai_mission_goal_achievable
+	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);
 
 	aigp->priority = priority;
 	aigp->int_data = int_data;
@@ -1025,11 +1037,27 @@ void ai_add_goal_sub_sexp( int sexp, ai_goal_type type, ai_info *aip, ai_goal *a
 	}
 
 	case OP_AI_STAY_STILL:
+	{
+		int n = CDR(node);
+
+		aigp->target_name = ai_get_goal_target_name(CTEXT(n), &aigp->target_name_index);  // waypoint path name;
+		n = CDR(n);
+
+		aigp->priority = eval_num(n, priority_is_nan, priority_is_nan_forever);
+		n = CDR(n);
+
+		bool clear_goals = !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_clear_goals_when_assigning_stay_still];
+		if (n >= 0)
+		{
+			clear_goals = is_sexp_true(n);
+			n = CDR(n);
+		}
+		if (clear_goals)
+			aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
+
 		aigp->ai_mode = AI_GOAL_STAY_STILL;
-		aigp->target_name = ai_get_goal_target_name(CTEXT(CDR(node)), &aigp->target_name_index);  // waypoint path name;
-		aigp->priority = eval_num(CDDR(node), priority_is_nan, priority_is_nan_forever);
-		aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
 		break;
+	}
 
 	case OP_AI_DOCK:
 		aigp->target_name = ai_get_goal_target_name( CTEXT(CDR(node)), &aigp->target_name_index );
@@ -1088,11 +1116,41 @@ void ai_add_goal_sub_sexp( int sexp, ai_goal_type type, ai_info *aip, ai_goal *a
 	}
 
 	case OP_AI_FORM_ON_WING:
-		aigp->priority = 99;
-		aigp->target_name = ai_get_goal_target_name(CTEXT(CDR(node)), &aigp->target_name_index);
+	{
+		int n = CDR(node);
+
+		aigp->target_name = ai_get_goal_target_name(CTEXT(n), &aigp->target_name_index);
+		n = CDR(n);
+
+		if (n >= 0)
+		{
+			aigp->priority = eval_num(n, priority_is_nan, priority_is_nan_forever);
+			n = CDR(n);
+		}
+		else
+			aigp->priority = The_mission.ai_profile->default_form_on_wing_priority;
+
+		bool clear_goals = !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_clear_goals_when_assigning_form_on_wing];
+		if (n >= 0)
+		{
+			clear_goals = is_sexp_true(n);
+			n = CDR(n);
+		}
+		if (clear_goals)
+			aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
+
+		bool set_override = !The_mission.ai_profile->flags[AI::Profile_Flags::Do_not_set_override_when_assigning_form_on_wing];
+		if (n >= 0)
+		{
+			set_override = is_sexp_true(n);
+			n = CDR(n);
+		}
+		if (set_override)
+			aigp->flags.set(AI::Goal_Flags::Want_override);
+
 		aigp->ai_mode = AI_GOAL_FORM_ON_WING;
-		aigp->flags.set(AI::Goal_Flags::Clear_all_goals_first);
 		break;
+	}
 
 	case OP_AI_CHASE:
 	case OP_AI_CHASE_WING:
@@ -1657,7 +1715,7 @@ ai_achievability ai_mission_goal_achievable( int objnum, ai_goal *aigp )
 		if (!target_ship_entry || !target_ship_entry->has_shipp())
 			return ai_achievability::NOT_ACHIEVABLE;
 
-		aigp->flags.set(AI::Goal_Flags::Goal_override);
+		// the override flag is now set in the calling function, ai_mission_goal_achievable
 		return ai_achievability::ACHIEVABLE;
 	}
 
@@ -2227,6 +2285,10 @@ void validate_mission_goals(int objnum, ai_info *aip)
 			continue;
 		}
 
+		// if the status is achievable, and we want to set the override, set it
+		if ( (state == ai_achievability::ACHIEVABLE) && (aigp->flags[AI::Goal_Flags::Want_override]))
+			aigp->flags.set(AI::Goal_Flags::Goal_override);
+
 		// if the status is achievable, and the on_hold flag is set, clear the flagb
 		if ( (state == ai_achievability::ACHIEVABLE) && (aigp->flags[AI::Goal_Flags::Goal_on_hold]) )
 			aigp->flags.remove(AI::Goal_Flags::Goal_on_hold);

code/parse/sexp.cpp

@@ -866,12 +866,12 @@ 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,	1,			SEXP_GOAL_OPERATOR, },
+	{ "ai-form-on-wing",				OP_AI_FORM_ON_WING,						1,	4,			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,	},
 	{ "ai-keep-safe-distance",			OP_AI_KEEP_SAFE_DISTANCE,				1,	1,			SEXP_GOAL_OPERATOR,	},
-	{ "ai-stay-still",					OP_AI_STAY_STILL,						2,	2,			SEXP_GOAL_OPERATOR,	},
+	{ "ai-stay-still",					OP_AI_STAY_STILL,						2,	3,			SEXP_GOAL_OPERATOR,	},
 	{ "ai-play-dead",					OP_AI_PLAY_DEAD,						1,	1,			SEXP_GOAL_OPERATOR,	},
 	{ "ai-play-dead-persistent",		OP_AI_PLAY_DEAD_PERSISTENT,				1,	1,			SEXP_GOAL_OPERATOR, },
 
@@ -32981,13 +32981,20 @@ int query_operator_argument_type(int op, int argnum)
 			return OPF_POSITIVE;
 
 		case OP_AI_STAY_STILL:
-			if (!argnum)
+			if (argnum == 0)
 				return OPF_SHIP_POINT;
-			else
+			else if (argnum == 1)
 				return OPF_POSITIVE;
+			else
+				return OPF_BOOL;
 
 		case OP_AI_FORM_ON_WING:
-			return OPF_SHIP;
+			if (argnum == 0)
+				return OPF_SHIP;
+			else if (argnum == 1)
+				return OPF_POSITIVE;
+			else
+				return OPF_BOOL;
 
 		case OP_GOOD_REARM_TIME:
 		case OP_BAD_REARM_TIME:
@@ -39813,16 +39820,18 @@ SCP_vector<sexp_help_struct> Sexp_help = {
 
 	{ OP_AI_STAY_STILL, "Ai-stay-still (Ship goal)\r\n"
 		"\tCauses the specified ship to stay still.  The ship will do nothing until attacked at "
-		"which time the ship will come to life and defend itself.  All other goals specified for the ship will be cleared.\r\n\r\n"
+		"which time the ship will come to life and defend itself.  By default all goals on the ship's goal list will be cleared when this goal runs.\r\n\r\n"
 		"Takes 2 arguments...\r\n"
 		"\t1:\tShip or waypoint the ship staying still will directly face (currently not implemented)\r\n"
-		"\t2:\tGoal priority (number between 0 and 89)." },
+		"\t2:\tGoal priority (number between 0 and 89).\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"
+	},
 
 	{ OP_AI_PLAY_DEAD, "Ai-play-dead (Ship goal)\r\n"
 		"\tCauses the specified ship to pretend that it is dead and not do anything.  This "
 		"expression should be used to indicate that a ship has no pilot and cannot respond "
 		"to any enemy threats.  A ship playing dead will not respond to any attack.\r\n\r\n"
-		"Do note that the ship's goal list is cleared, which means both that it forgets "
+		"Do note that all goals on the ship's goal list will be cleared when this goal runs, which means that the ship forgets both "
 		"this goal and all previous goals, and that if it receives any other goal in any way, "
 		"it will immediately come back to life.  Use ai-play-dead-persistent to prevent this "
 		"from happening.\r\n\r\n"
@@ -39841,9 +39850,14 @@ SCP_vector<sexp_help_struct> Sexp_help = {
 
 	{ OP_AI_FORM_ON_WING, "Ai-form-on-wing (Ship Goal)\r\n"
 		"\tCauses the ship to form on the specified ship's wing. This works analogous to the "
-		"player order, and will cause all other goals specified for the ship to be cleared.\r\n\r\n"
-		"Takes 1 argument...\r\n"
-		"\t1:\tShip to form on." },
+		"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"
+		"\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"
+	},
 
 	{ OP_FLASH_HUD_GAUGE, "Ai-flash hud gauge (Training goal)\r\n"
 		"\tCauses the specified hud gauge to flash to draw the player's attention to it.\r\n\r\n"

code/scripting/api/objs/order.cpp

@@ -489,6 +489,22 @@ 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")
+{
+	order_h* ohp = nullptr;
+	bool want_override = false;
+	if (!ade_get_args(L, "o|b", l_Order.GetPtr(&ohp), &want_override))
+		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);
+
+	return ade_set_args(L, "b", ohp->aigp->flags[AI::Goal_Flags::Want_override]);
+}
+
 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")
 {
 	order_h *ohp = NULL;