DepleteAmmo

From ZDoom Wiki
Jump to navigation Jump to search

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.

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.

Returns true if the user has enough ammo to fire.

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). Otherwise this value will be used in the check directly.
  • bool forceammouse
Ignores infinite ammo effects and forcefully checks if the user actually has enough ammo.

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 only consumes ammo and always returns true.

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