DepleteAmmo

Weapon

virtual bool DepleteAmmo(bool altFire, bool checkEnough = true, int ammouse = -1, bool forceammouse = false)

Usage

A Weapon virtual function that consumes the weapon's ammo. The type of ammo is determined by the Weapon.AmmoType1/Weapon.AmmoType2 properties. This should be used instead of A_TakeInventory when manual control over ammo consumption is needed. Can be bother overridden to modify the base ammo consumption behavior, and called directly to manually check for and consume ammo. Returns true if the user has enough ammo to fire.

Despite being a weapon function, this is not an action function. As such, if this is called from inside an action function or a weapon state handled by a PSprite (i.e. any state outside of the ones in the Spawn sequence), it needs an invoker. prefix.

For checking for ammo without consuming it, see CheckAmmo.

Parameters

• bool altFire

Determines if primary or secondary ammo should be consumed. Normally you would pass invoker.bAltFire to this, which is a weapon flag that automatically gets set to true when the weapon is using a secondary attack (i.e. the player used BT_ALTATTACK button to initiate the AltFire sequence). Passing true or false instead allows for manual control.

• bool checkEnough

If true, the function will first check if the user has enough ammo (in accordance with the ammouse argument - see CheckAmmo to see how it's interpreted). If this is true and the user doesn't have enough ammo, the function returns false.

If false, the function will try to consume ammo even if the user doesn't have enough, and will always return true at the end (see Return values).

• int ammouse

If checkenough is true, this value will be passed to the CheckAmmo call to check if the user has enough of the specified ammo.

Additionally, if this value is 0 or higher, altfire is false, and either forceammouse is true or the ammo class in question is affected by a DEHACKED patch, this much ammo will be consumed from AmmoType1. It has no effect on AmmoType2.

The default value is -1, which means the ammount of required/consumed ammo will be determined by the weapon's Weapon.AmmoUse1/Weapon.AmmoUse2 property (whichever is relevant based on the value of altFire).

• bool forceammouse

Ignores infinite ammo effects and forcefully checks if the user actually has enough ammo. Also allows passing a custom value to ammouse.

Return values

• bool - returns true if the owner of the weapon has enough ammo to fire. This is only done if the checkEnough argument was set to true; otherwise the function tries to consume ammo and always returns true even if there wasn't enough ammo.

ZScript definition

Note: The ZScript definition below is for reference and may be different in the current version of GZDoom.The most up-to-date version of this code can be found on GZDoom GitHub.

The base Weapon class defines it as follows:

	virtual bool DepleteAmmo(bool altFire, bool checkEnough = true, int ammouse = -1, bool forceammouse = false)
	{
		if (!(sv_infiniteammo || (Owner.FindInventory ('PowerInfiniteAmmo', true) != null)))
		{
			if (checkEnough && !CheckAmmo (altFire ? AltFire : PrimaryFire, false, false, ammouse))
			{
				return false;
			}
			if (!altFire)
			{
				if (Ammo1 != null)
				{
					if (ammouse >= 0 && (bDehAmmo || forceammouse))
					{
						Ammo1.Amount -= ammouse;
					}
					else
					{
						Ammo1.Amount -= AmmoUse1;
					}
				}
				if (bPRIMARY_USES_BOTH && Ammo2 != null)
				{
					Ammo2.Amount -= AmmoUse2;
				}
			}
			else
			{
				if (Ammo2 != null)
				{
					Ammo2.Amount -= AmmoUse2;
				}
				if (bALT_USES_BOTH && Ammo1 != null)
				{
					Ammo1.Amount -= AmmoUse1;
				}
			}
			if (Ammo1 != null && Ammo1.Amount < 0)
				Ammo1.Amount = 0;
			if (Ammo2 != null && Ammo2.Amount < 0)
				Ammo2.Amount = 0;
		}
		return true;
	}

Examples

class PlasmaShotgun : Shotgun
{
	States
	{
	Fire:
		SHTG A 3;
		SHTG A 7 
		{
			// Consume 1 shell:
			invoker.DepleteAmmo(invoker.bAltFire, true);
			A_GunFlash();
			// Fire 8 plasmaballs:
			for (int i = 8; i > 0; i--)
			{
				A_FireProjectile("Plasmaball", angle: frandom(-5.6, 5.6), useammo: false);
			}
		}
		SHTG BC 5;
		SHTG D 4;
		SHTG CB 5;
		SHTG A 3;
		SHTG A 7 A_ReFire;
		Goto Ready;
	}
}

Alternatively, this can also be packed into a custom function:

class PlasmaShotgun : Shotgun
{
	action void A_FirePlasmaShotgun()
	{
		// Consume ammo and return if there isn't enough
		// of it:
		if (!invoker.DepleteAmmo(invoker.bAltFire, true))
		{
			return;
		}
		A_GunFlash();
		// Fire 8 plasmaballs:
		for (int i = 8; i > 0; i--)
		{
			A_FireProjectile("Plasmaball", angle: frandom(-5.6, 5.6), useammo: false);
		}
	}

	States
	{
	Fire:
		SHTG A 3;
		SHTG A 7 A_FirePlasmaShotgun();
		SHTG BC 5;
		SHTG D 4;
		SHTG CB 5;
		SHTG A 3;
		SHTG A 7 A_ReFire;
		Goto Ready;
	}
}