Followup improvement for the LuaAI AI Control Helper (#4422)

* Followup improvement for the LuaAI AI Control Helper

* Update docs

Author: BMagnu

code/ai/ai.h

@@ -72,6 +72,7 @@ extern ai_flag_name Ai_flag_names[];
 #define AITTV_VIA_SEXP				(1<<1)	//	Goober5000 - via sexp
 #define AITTV_IGNORE_BANK			(1<<2)	//	Goober5000 - ignore bank when turning
 #define AITTV_SLOW_BANK_ACCEL		(1<<3)  //  Asteroth - used by formation flying
+#define AITTV_FORCE_DELTA_BANK		(1<<4)  //  Lafiel - Always use the provided delta bank and override calculated values
 
 #define	KAMIKAZE_HULL_ON_DEATH	-1000.0f	//	Hull strength ship gets set to if it crash-dies.
 

code/ai/aicode.cpp

@@ -1288,7 +1288,9 @@ void ai_turn_towards_vector(vec3d* dest, object* objp, vec3d* slide_vec, vec3d*
 
 	//	Should be more general case here.  Currently, anything that is not a weapon will bank when it turns.
 	// Goober5000 - don't bank if sexp or ship says not to
-	if ( (objp->type == OBJ_WEAPON) || (flags & AITTV_IGNORE_BANK ) )
+	if (flags & AITTV_FORCE_DELTA_BANK)
+		bank = bank_override;
+	else if ( (objp->type == OBJ_WEAPON) || (flags & AITTV_IGNORE_BANK ) )
 		bank = 0.0f;
 	else if (objp->type == OBJ_SHIP && Ship_info[Ships[objp->instance].ship_info_index].flags[Ship::Info_Flags::Dont_bank_when_turning])
 		bank = 0.0f;
@@ -14816,12 +14818,12 @@ void ai_process( object * obj, int ai_index, float frametime )
 
 	memset( &AI_ci, 0, sizeof(AI_ci) );
 
-	ai_frame(OBJ_INDEX(obj));
-
 	AI_ci.pitch = 0.0f;
 	AI_ci.bank = 0.0f;
 	AI_ci.heading = 0.0f;
 
+	ai_frame(OBJ_INDEX(obj));
+
 	// the ships maximum velocity now depends on the energy flowing to engines
 	obj->phys_info.max_vel.xyz.z = shipp->current_max_speed;
 

code/scripting/api/objs/ai_helper.cpp

@@ -41,65 +41,19 @@ inline int aici_getset_helper(lua_State* L, float control_info::* value) {
 	return ade_set_args(L, "f", AI_ci.*value);
 }
 
-inline int pi_rotation_getset_helper(lua_State* L, int axis) {
-	//Use with care! This works only if, as expected, the l_AI_Helper object is the one supplied to the luaai scripts this very frame
-	object_h ship;
-	float f = 0.0f;
-	if (!ade_get_args(L, "o|f", l_AI_Helper.Get(&ship), &f))
-		return ade_set_error(L, "f", 0.0f);
-
-	if (!ship.IsValid())
-		return ade_set_error(L, "f", 0.0f);
-
-	vec3d vel_limit;
-	// get the turn rate if we have Use_axial_turnrate_differences
-	if (The_mission.ai_profile->flags[AI::Profile_Flags::Use_axial_turnrate_differences]) {
-		vel_limit = Ship_info[Ships[ship.objp->instance].ship_info_index].max_rotvel;
-	}
-	else { // else get the turn time
-		float turn_time = Ship_info[Ships[ship.objp->instance].ship_info_index].srotation_time;
-
-		if (turn_time > 0.0f)
-		{
-			vel_limit.xyz.x = PI2 / turn_time;
-			vel_limit.xyz.y = PI2 / turn_time;
-			vel_limit.xyz.z = PI2 / turn_time;
-		}
-	}
-	vec3d acc_limit = ai_get_acc_limit(&vel_limit, ship.objp);
-
-	float currentThrustRate = ((ship.objp->phys_info.desired_rotvel.a1d[axis] - ship.objp->phys_info.rotvel.a1d[axis]) / AI_frametime) / acc_limit.a1d[axis];
-
-	if (ADE_SETTING_VAR) {
-		currentThrustRate = f;
-		float targetVel = currentThrustRate * acc_limit.a1d[axis] * AI_frametime + ship.objp->phys_info.rotvel.a1d[axis];
-		CLAMP(targetVel, -vel_limit.a1d[axis], vel_limit.a1d[axis]);
-		ship.objp->phys_info.desired_rotvel.a1d[axis] = targetVel;
-
-		vec3d rotstep = ship.objp->phys_info.desired_rotvel * AI_frametime;
-
-		matrix	rotmat;
-		angles rotangles{ rotstep.xyz.x, rotstep.xyz.z, rotstep.xyz.y };
-		vm_angles_2_matrix(&rotmat, &rotangles);
-		vm_matrix_x_matrix(&ship.objp->phys_info.ai_desired_orient, &ship.objp->orient, &rotmat);
-	}
-
-	return ade_set_args(L, "f", currentThrustRate);
-}
-
 ADE_VIRTVAR(Pitch, l_AI_Helper, "number", "The pitch thrust rate for the ship this frame, -1 to 1", "number", "The pitch rate, or 0 if the handle is invalid")
 {
-	return pi_rotation_getset_helper(L, 0);
+	return aici_getset_helper(L, &control_info::pitch);
 }
 
 ADE_VIRTVAR(Bank, l_AI_Helper, "number", "The bank thrust rate for the ship this frame, -1 to 1", "number", "The bank rate, or 0 if the handle is invalid")
 {
-	return pi_rotation_getset_helper(L, 2);
+	return aici_getset_helper(L, &control_info::bank);
 }
 
 ADE_VIRTVAR(Heading, l_AI_Helper, "number", "The heading thrust rate for the ship this frame, -1 to 1", "number", "The heading rate, or 0 if the handle is invalid")
 {
-	return pi_rotation_getset_helper(L, 1);
+	return aici_getset_helper(L, &control_info::heading);
 }
 
 ADE_VIRTVAR(ForwardThrust, l_AI_Helper, "number", "The forward thrust rate for the ship this frame, -1 to 1", "number", "The forward thrust rate, or 0 if the handle is invalid")
@@ -119,7 +73,7 @@ ADE_VIRTVAR(SidewaysThrust, l_AI_Helper, "number", "The sideways thrust rate for
 
 ADE_FUNC(turnTowardsPoint,
 	l_AI_Helper,
-	"vector target, [boolean respectDifficulty = true, vector turnrateModifier /* 100% of tabled values in all rotation axes by default */]",
+	"vector target, [boolean respectDifficulty = true, vector turnrateModifier /* 100% of tabled values in all rotation axes by default */, number bank /* native bank-on-heading by default */ ]",
 	"turns the ship towards the specified point during this frame",
 	nullptr,
 	nullptr)
@@ -128,11 +82,14 @@ ADE_FUNC(turnTowardsPoint,
 	vec3d* target;
 	bool diffTurn = true;
 	vec3d* modifier = nullptr;
-	if (!ade_get_args(L, "oo|bo", l_AI_Helper.Get(&ship), l_Vector.GetPtr(&target), &diffTurn, l_Vector.GetPtr(&modifier))) {
+	float bank = 0.0f;
+
+	int argnum = ade_get_args(L, "oo|bof", l_AI_Helper.Get(&ship), l_Vector.GetPtr(&target), &diffTurn, l_Vector.GetPtr(&modifier), &bank);
+	if (argnum == 0) {
 		return ADE_RETURN_NIL;
 	}
 
-	ai_turn_towards_vector(target, ship.objp, nullptr, nullptr, 0.0f, diffTurn ? 0 : AITTV_FAST, nullptr, modifier);
+	ai_turn_towards_vector(target, ship.objp, nullptr, nullptr, bank, (diffTurn ? 0 : AITTV_FAST) | (argnum >= 5 ? AITTV_FORCE_DELTA_BANK : 0), nullptr, modifier);
 	return ADE_RETURN_NIL;
 }