Skip to content

Turret functions

inkoalawetrust edited this page Sep 8, 2023 · 10 revisions

These are the ZScript functions shared by all turrets.

GetElevationState()

Return type(s):

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.

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()

Parameters:

  • Chance, AbortState: These parameters work the same as in A_MonsterRefire().
  • DontFaceTarget: Do not call A_FaceTarget() when the function runs, which is what A_MonsterRefire() does. Default is false.
  • RetargetCheckChance: The chance of the function also calling RetargetVehicleHull(), works the same as the refire chance itself. Default is -1, which means the function never runs.
  • RetargetCheckFlags: The flags to pass to RetargetVehicleHull() if it decides to run.

Return type(s):

  • Returns the AbortState if Chance is met, returns Null otherwise.

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()

Parameters:

  • Other: The actor to check. This is actually for secondary checks like the SplashRadius below, by default the check is aimed at wherever the turret is aiming, not at where Other is. Default is null as it is optional unless TLOF_FaceOther is on.
  • PropHealthThreshold: If an obstacle on the turrets' way is a prop that can be destroyed, and has this much health or less, then don't consider it an obstacle. Useful to make turrets still fire at obstacles that they can blow through in a timely manner, to prevent cheesing by actions like an enemy hiding behind a small destructible table. Default is 400.
  • SplashRadius: If the LOF check misses Other, but the target would still be caught within this radius, then still return the LOF as valid. Useful for turrets with explosive attacks, since it can make them still shoot if they'd do splash damage to the Other. Default is 0, which means this check doesn't run.
  • 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).
  • Flags:
    • TLOF_FaceOther: Instead of firing the check at wherever the turret is facing, firing it at a direction facing Other. This makes the check behave more like A_CheckLOF().
    • TLOF_DoStayAround: The function won't turn on +DONTSTAYAROUND if the LOF is bad. This is done by default so if the vehicle the turret is on is sitting around to let its' turret shoot. Then it will get moving again if the turret cannot actually fire at its' target.
    • TLOF_FriendlyFire: The attack the check is running for can hurt monsters friendly to the shooter, meaning that it should stop if an ally is in the LOF.
    • TLOF_OnlyAhead: Only return a good LOF if the turret is successfully leading its' shot ahead of the target. Useful for LOF checks for infrequent attacks, such as a cannon shot.

Return type(s):

  • Returns true if the LOF is valid, false otherwise.

Function:

The primary function used to do line of fire checks for turrets, it works for most normal projectile attacks, except for special projectiles like rippers as it does not account for any penetration. The check also includes special handling for if the Other actor is behind weak cover, and if the check misses but Other would still be caught in the blast. However, the SplashRadius check automatically fails if Other is immune to blast damage. It also calls GetFAFAimPos() before firing the trace, to be able to aim at partially covered enemies. This function is basically a wrapper for creating a KAI_LOFProjectileCheck tracer.

GetTurretAimOffset()

Function:

Gets the height offset to use relative to the target for LOF and LOS checks based on the value of TurretAimPos.

Example:

This is how KAI_TurretCheckLOF() uses the function to determine the height to check the turrets' target at:

		TurretAimPos = GetFAFAimPos (Target);
		
		//If not aiming ahead of the target
		If (Flags & TLOF_OnlyAhead && !AimingAheadOfTarget())
			Return False;
		
		Vector3 Direction;
		If (!(Flags & TLOF_FaceOther))
			Direction = (AngleToVector(Angle, Cos(Pitch)), -Sin(Pitch));
		Else
		{
			If (Other)
			{
				Double PitchTo = PitchTo (Other,Height/2,GetTurretAimPosOffset());
				Direction = (AngleToVector(AngleTo(Other), Cos(PitchTo)), -Sin(PitchTo));
			}
			Else
				Return False; //Actor stopped existing, so no need to fire.
		}

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

See also

Clone this wiki locally