Turret functions - inkoalawetrust/KAI GitHub Wiki

These are the ZScript functions shared by all turrets.

GetElevationState()

Return type(s):

Returns one of the elevation states (Integer).

Function:

Returns if the turret is too high up or low down over its' pitch limits.

IsOverPitchLimits()

Parameters:

Other: The actor to check the pitch to.
ZOfs: The Z offset to use on the calling turret, normally this should be the spawn height of its' attack.
TargZOfs: The Z offset to use on the Other actor, such as to check the pitch to the top of their hitbox.
Padding: Additional padding to both the Min and MaxPitch of the turret. Useful if you want something that goes over the turrets' normal pitch limit.

Return type(s):

Returns an elevation state based on if Other is to high or under the turrets' elevation limits.

Function:

Checks if the pitch to the Other actor is outside the turrets' elevation limits or not, usually used to make turrets not try attacking actors they can't aim up or down to.

UpdateTurretElevation()

Note: Pitch in ZDoom is all fucked up. So negative pitches are up, and positive ones are down !

Parameters:

FaceDown: The sprite frame to return if the turrets' pitch is over 6 degrees.
FaceStraight: The sprite frame to return if the turrets' pitch is less than 6 degrees and over -15 degrees.
FaceUp: The sprite frame to return if the turrets' pitch is less than -14 degrees, but more than -50 degrees.
FaceUp2: The sprite frame to return if the turrets' pitch is less than -50 degrees.

Return type(s):

Returns a sprite frame (Integer) based on the bounds specified above.

Function:

This function returns a sprite frame based on the pitch. This allows turrets to visually change their elevation based on their actual pitch. Since this is a simple "if within this pitch return that frame" check, I'd suggest making your own function similar to this one, if you want different pitch boundaries for a certain visual elevation, or you want more visual elevations that 1 down, and 2 up.

Example:

This is how the autocannon turret of the APC in the Military Vehicles Pack uses this function to change its visual elevation, notice the special frame name on the state. And how the frames to conditionally change to are swapped on the state where the turret actually shots.

		Fire:
			APC2 ###### 1
			{
				If (bNoCombatTraverse) A_FaceTarget (0,0,flags:FAF_MIDDLE);
				Frame = UpdateTurretElevation (2,0,4,6); //C, A, E, G //These are the frame letters that correspond to the indices.
			}
			APC2 # 3 Light ("AutocannonFlash") Bright
			{
				If (bNoCombatTraverse) A_FaceTarget (0,0,flags:FAF_MIDDLE);
				A_StartSound (AttackSound,CHAN_WEAPON,CHANF_OVERLAP,1.0,0.25);
				Actor Proj = A_SpawnProjectile ("MVP_AutocannonShell",16,flags:CMF_AIMDIRECTION,Pitch); //pew pew
				HandleTargetPrediction (Proj,(0.3,-0.3),(0.45,-0.45),768);
				//If the enemy the shell was fired at is a flying enemy vulnerable to radius damage. Then use the proximity fuze.
				If (Target && IsFlying (Target) && !Target.bNoRadiusDmg)
				{
					Proj.Tracer = Target;
					MVP_AutocannonShell(Proj).IsAirburst = True;
				}
				Frame = UpdateTurretElevation (3,1,5,7); //D, B, F, H //Notice how they change for the actual firing frame.
			}
			//Other code...

RotateToVehicle()

Parameters:

Flags:
- RTVF_NOTARGETCHECK: The function will run even if the turret has a target. This is explicitly specified so the function doesn't mess up the turrets' traverse when chasing a target but not shooting at it yet.
- RTVF_RELATIVEONLY: Only rotate relative to the turrets' TurretRotationOffset, even if the turret isn't dead. The behavior of this flag is also applied when the turret is killed.
- RTVF_ADDANGLE: The turrets' TurretRotationOffset is added on the turrets' angle.

Return type(s):

None

Function:

Handles the angle and pitch rotation of turrets when not in combat. It rotates the turret back to facing the angle that the vehicle it's attached to is facing, after the turret has finished attacking something, then goes back to the turret being glued in whatever direction the vehicle faces. If the turret is destroyed/dead, this function will make the turret always maintain the same angle relative to its' vehicle.

Examples:

This is how the function is called when the turret is alive, it's normally just plainly called in the turrets' idle and chase states.

		Spawn:
			MSV1 A 0;
			MSV1 # 1
			{
				RotateToVehicle();
				KAI_Look (maxseedist:MaxTargetRange,DEFAULT_HEARDISTANCE,extraflags:KAIL_CHASETARGET);
				Frame = UpdateTurretElevation (10,6,8,8); //K, G, I, I
			}
			Goto Spawn+1;

And when the turret is dead, it's called with RTVF_RELATIVEONLY, the TurretRotationOffset the function follows is expected to be set upon death.

		Death:
			MSV1 WXY 10 RotateToVehicle(RTVF_RELATIVEONLY);
			MSV1 Y 1 RotateToVehicle(RTVF_RELATIVEONLY);
			Wait;

UpdateTurretSnapTimer()

Parameters:

DefaultValue: The default value to set the timer to when it reaches 0.

Return type(s):

None

Function:

Updates TurretSnapDelay, when it reaches 0, the turret stops trying to face the vehicles' angle again and begins snapping back to said angle. RotateToVehicle() also begins snapping back if the angle difference between the turret and vehicle is small enough (Within 0.75 degrees). This function must be called in the See states of turrets.

DoCombatTraverse()

Function:

Performs the combat traverse code that is ran every tick when the turret is in any of its' attack states. This is basically a wrapper for AimAtTarget(), that takes the turret's CombatAngleTurnRate and CombatPitchTurnRate and divides them by the tics per second. Making the turret turn over time in degrees per second. This function can also be called in state sequences that are not attack states. Such as calling it in 1-tic long See states on turrets, to make them continue leading their aim direction even when not shooting. Which is something you should likely do anyway if you want turrets to lead their shots without HandleTargetPrediction().

AimAtTarget()

See here

AimingAheadOfTarget()

See here

IsInCone()

Parameters:

Other: The actor to check fore.
Size: The size of the cone in degrees, default is 5.
FalloffScale: The amount that the cones' size falls off with distance, this is broken. Default is 256.

Return type(s):

Returns true if the Other is within the specified 3D FOV, false otherwise.

Function:

Checks if the Other actor is within the specified cone relative to the caller. This function has a super broken falloff formula that tried to make the cone retain the same relative size the further Other is from the caller. This function should not really be used for anything, or at least the falloff shouldn't at all, so always set it to 0 if you are going to use this function.

KAI_TurretRefire()

See here. This wrapper automatically passes the turrets' TurretAimPos into the AimPos parameter. Therefore it DOESN'T have that parameter.

Function:

This is essentially an extended version of A_MonsterRefire for turrets, with optional support for RetargetVehicleHull() to make turrets able to decide to fire at an enemy turrets' vehicle if more advantageous.

PickDifferentTarget()

Parameters:

Avoid: The actor to be avoided.
Origin: The actor to find a different target around, normally this will just be the Avoid actor too.
CheckRange: The range to try and find a different target within.
MinAlternateTargetRange: How far the potential new target must be from Avoid to be a valid candidate. Default is -1, which means no such distance restriction is applied.

Return type(s):

A pointer to the alternate actor for the caller to target instead. Returns Null if nothing is found.

Function:

Forcibly finds a new target for the caller to chase that is not the Avoid actor, by searching in a range around Origin for one. The target must be a targetable, visible enemy that is in range. This function is useful if you want two actors to not share the same target, such as if you want the turret to always have a different target from their vehicle if their targets' are the same.

KAI_TurretCheckLOF()

See here. This wrapper function however does NOT have KAI_CheckLOF()'s AimPos parameter, and instead uses the turrets' TurretAimPos. Which it also automatically updates before running the check.

KAI_FindInLOF()

Parameters:

Flags:
- FIL_FaceTarget: Fire the check at the direction of Other instead of wherever the turret is currently facing.
- FIL_HitscanHit: Make the check blockable by hitscan blocking lines.
- FIL_MissileHit: Make the check blockable by missile blocking lines.
Range: The range of the check.
ActorLimit: How many actors the ray can find before stopping. Default is 0, which means that it will only stop if it hits level geometry or its' Range.
CheckOffsets: How much to offset the starting position of the check relative to the callers' origin, this is a Vector3 parameter. Default is (0,0,32).
Other: The actor to fire the ray towards, if any.
FoundActors: The dynamic array to input into the function, so that it can be filled with the actors the raycast found.

Return type(s):

You must pass an array to the FoundActors parameter, so that all the actors the function finds can be returned. The function doesn't directly return anything.

Function:

Finds all the actors in front of the turret or in the direction of Other and outputs pointers to them in FoundActors. Allowing for finding specific things standing in the way. This is a wrapper for KAI_LOFActorFinder

Turret functions - inkoalawetrust/KAI GitHub Wiki

GetElevationState()

Return type(s):

Function:

IsOverPitchLimits()

Parameters:

Return type(s):

Function:

UpdateTurretElevation()

Parameters:

Return type(s):

Function:

Example:

RotateToVehicle()

Parameters:

Return type(s):

Function:

Examples:

UpdateTurretSnapTimer()

Parameters:

Return type(s):

Function:

DoCombatTraverse()

Function:

AimAtTarget()

AimingAheadOfTarget()

IsInCone()

Parameters:

Return type(s):

Function:

KAI_TurretRefire()

Function:

PickDifferentTarget()

Parameters:

Return type(s):

Function:

KAI_TurretCheckLOF()

KAI_FindInLOF()

Parameters:

Return type(s):

Function:

See also