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 either with the AmmoType1/AmmoType2 property, or the ammouse argument if that's not -1). 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

Determines how much ammo the user should have for the check to pass successfully. At the default value (-1) this will check the value of the Weapon.AmmoUse1/Weapon.AmmoUse2 property (whichever is relevant based on the value of altFire). If this parameter is greater than zero and forceammouse is set to true, this value will be used in the check instead.

• 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;
	}
}