Classes:Weapon

Note: Wait! Stop! You do not need to copy this actor's code into your project! Here's why: This actor is already defined in GZDoom, there's no reason to define it again. In fact, trying to define an actor with the same name will cause an error (because it already exists). If you want to make your own version of this actor, use inheritance. Definitions for existing actors are put on the wiki for reference purpose only.

Weapon
Actor type	Internal	Game	(ZDoom)
DoomEd Number	None	Class Name	Weapon

Classes: Inventory→StateProvider→Weapon
 →Beak
 →Chainsaw
 →ClericWeapon
 →DoomWeapon
 →FighterWeapon
 →Fist
 →HereticWeapon
 →MageWeapon
 →PhoenixRod
 →Sigil
 →Snout
 →StrifeWeapon

Weapon is the base class for all weapons in the game. Weapons are the most complex of all inventory items due to their nature or requiring additional animation states.

Like with normal inventory items, an actor can have more than one sample of a weapon in its inventory.

Do not forget weapon icons! Even though they are not used by the default HUDs for Doom, Heretic and Hexen, ZDoom uses them for Strife's HUD and for the alternate HUD. Custom HUDs can also require them.

Note: a weapon which has an invalid or nonexistent sprite for the first state in its Ready state sequence cannot be obtained.

Warning: do not execute any code right after removing the currently selected weapon from within its own actor definition during the same tic, since that code would be operating without a caller (the weapon itself) and would cause the engine to abort with an error.

Using in DECORATE and ZScript

Weapon flags and properties

The DropItem property operates differently on weapons. When the sv_weapondrop console variable is enabled, if a dying player was using a weapon which has a DropItem list, the items from this list will be spawned instead of the weapon. This is to allow using scripted pickups instead of spawning a weapon directly; for example in multiplayer if several player classes use the "same" weapon in different ways, which are represented as different weapon actors.

In addition to some of the basic Inventory properties, weapons support the following:

• Weapon.AmmoGive amount
• Weapon.AmmoGive1 amount

The amount of primary ammo you receive from this weapon.

• Weapon.AmmoGive2 amount

The amount of secondary ammo you get from picking up the weapon.

• Weapon.AmmoType type
• Weapon.AmmoType1 type

The type of primary ammo the weapon uses. This must be a valid ammo type.

• Weapon.AmmoType2 type

The type of secondary ammo the weapon uses.

• Weapon.AmmoUse amount
• Weapon.AmmoUse1 amount

The amount of primary ammo the weapon uses per shot.

• Weapon.AmmoUse2 amount

The amount of the secondary ammo that the weapon uses per shot. Normally secondary ammo is used by the secondary attack but if the WEAPON.PRIMARY_USES_BOTH flag is set the primary attack will use both types of ammo for each attack.

• Weapon.MinSelectionAmmo1 amount

A weapon with this property will not be auto-switched to if the available amount of ammo for the primary attack is less than the value specified. The weapon can still be switched to manually, however.

• Weapon.MinSelectionAmmo2 amount

A weapon with this property will not be auto-switched to if the available amount of ammo for the secondary attack is less than the value specified. The weapon can still be switched to manually, however.

• Weapon.BobPivot3D (x, y, z) (ZScript only)

(Need more info)

Default is (0.0, 0.0, 0.0).

• Weapon.BobRangeX amount

Range multiplier for horizontal bobbing.

Default is 1.0.

• Weapon.BobRangeY amount

Range multiplier for vertical bobbing.

Default is 1.0.

• Weapon.BobSpeed amount

Bobbing speed multiplier. Affects how quickly the bobbing motion occurs.

Default is 1.0.

• Weapon.BobStyle type

The type of bobbing to use. Possible values include Normal, Inverse, Alpha, InverseAlpha, Smooth, and InverseSmooth.

• Normal is the default value and corresponds to the bobbing motion used in all old Doom-engine games.
• Alpha is the bobbing motion used in the alpha versions of Doom.
• Smooth is a smoother version of the normal style.
• Inverse* types mirror the motion vertically compared to the non-inverse version. InverseAlpha lowers the weapon sprite while bobbing; the others raise it.

• Weapon.KickBack amount

How far attacks by this weapon push the enemy back. Damage is also a factor in kickback.

• Weapon.DefaultKickBack

Weapons with this property have a kickback value which is specified by the defkickback MAPINFO property.

• Weapon.ReadySound sound

The sound the weapon plays in its ready state.

• Weapon.SelectionOrder value

Defines the place in the weapons list when ammo runs out. Lower numbers have higher priority. The standard Doom II weapons range from 100 for the Plasma Rifle to 3700 for the Fist.

• Weapon.SisterWeapon weapontype

Defined weapon is also given when flagged weapon is picked up. Used primarily for Tome Of Power attacks but it can also be used to create weapons with 2 distinct attack modes. Several Strife weapons use this.

• Weapon.SlotNumber value

Default slot for this weapon. For mods that want to add new weapons without completely redoing the player's arsenal. For other ways to assign weapons to slots, see weapon slots.

• Weapon.SlotPriority value

Selection order within slot for this weapon. This is a floating-point value. Higher numbers mean higher priority.

• Weapon.UpSound sound

The sound played when the select state is called.

• Weapon.WeaponScaleX value

The horizontal scale multiplier of the weapon's HUD sprite.

Default is 1.0.

• Weapon.WeaponScaleY value

The vertical scale multiplier of the weapon's HUD sprite.

Default is 1.2.

• Weapon.YAdjust amount

Shifts the HUD sprites vertically when the status bar is off. Note: positive y values shift the weapon down.

• Weapon.LookScale amount

Multiplier for the player's look sensitivity. Operates identically to the look sensitivity for FOV scaling, but without changing the FOV.

Weapons also define new flags (note: The WEAPON. prefix is optional in DECORATE but not optional in ZScript):

• WEAPON.NOAUTOFIRE

Does not fire when selected automatically and the fire button is still pressed. Used to prevent dangerous weapons from firing accidentally.

In addition to the main effect, if a weapon uses this flag and does not call A_ReFire anywhere, it won't be able to fire continuously if the player just keeps holding the attack button; instead, the player will be required to press it every time they want the weapon to fire.

• WEAPON.READYSNDHALF

The ready sound is played only with 50% probability.

• WEAPON.DONTBOB

The weapon sprite does not bob.

• WEAPON.AXEBLOOD

This weapon spawns the special AxeBlood type when hitting something that bleeds. This only has an effect for hitscan and melee weapons.

• WEAPON.NOALERT

Does not alert nearby monsters when being fired.

• WEAPON.AMMO_OPTIONAL

Tells the engine that this weapon doesn't require ammo to work.

• WEAPON.ALT_AMMO_OPTIONAL

The same for the alternate attack.

• WEAPON.AMMO_CHECKBOTH

The weapon can be selected if either the primary or the alternate fire have enough ammo. Both weapon properties Weapon.AmmoUse1 and Weapon.AmmoUse2 must have a positive value for this flag to work correctly.

• WEAPON.PRIMARY_USES_BOTH

The primary attack uses both ammo types.

• WEAPON.ALT_USES_BOTH

Like WEAPON.PRIMARY_USES_BOTH, makes the AltFire (secondary) attack use both ammo types.

• WEAPON.WIMPY_WEAPON

A small weapon with limited capabilities. If ammo for something better gets picked up the game will automatically switch weapons unless the weapon to switch to has the NOAUTOSWITCHTO flag set.

• WEAPON.POWERED_UP

This is a powered up weapon. Powered up weapons cannot exist by themselves. They always are linked to a normal weapon via the weapon.sisterweapon property and are only activated by using Heretic's Tome of Power or another artifact based on PowerWeaponLevel2.

• WEAPON.STAFF2_KICKBACK

Uses the special kickback formula of Heretic's powered up staff. Unlike normal kickback this is a fixed thrust value.

• WEAPON.EXPLOSIVE

Signifies to bots that the weapon fires explosive projectiles.

• WEAPON.MELEEWEAPON

Signifies to bots, and to monsters with the AVOIDMELEE flag, that the weapon is a melee weapon.

• WEAPON.BFG

Signifies to bots that the weapon causes a lot of damage.

• WEAPON.CHEATNOTWEAPON

Weapon is not given by the 'give weapons' cheat.

• WEAPON.NO_AUTO_SWITCH

When the player picks this weapon up, they will never automatically switch to it.

• WEAPON.NOAUTOSWITCHTO

A weapon with this flag set cannot be switched to automatically upon obtaining ammo for it. Typically, if the player had run out of ammo for a weapon, and the weapon that was automatically switched to as a result is a weak weapon, obtaining ammo for the other weapon automatically switches away from the weak weapon and back to it, provided the player had not manually switched weapons in the interim, and the other weapon has a higher selection priority than the weak one.

• WEAPON.NOAUTOAIM

A weapon with that flag will not adjust the aim of an attack, no matter the player's autoaim settings. This is intended to be used only for projectiles affected by gravity, such as grenades, where the player will usually want to aim higher than in a straight line, though it does also affect hitscan and railgun attacks.

• WEAPON.NODEATHDESELECT

The weapon will not jump to the deselect state when the player dies.

• WEAPON.NODEATHINPUT

The weapon cannot act on any input if the player is dead.

Weapon states

Weapons also require additional states to define the HUD weapon animation:

• Ready

Defines the weapon's ready sequence. This is where A_WeaponReady is normally called to make the weapon ready for firing and deselecting.

• Deselect

Defines a weapons lowering sequence. It must lower the weapon to the bottom of the screen and should not do any other actions. Requires calling A_Lower for that to happen.

• Select

Defines a weapons raising sequence. It must raise the weapon to the normal firing height and should not do any other actions. Normally, this is achieved by calling A_Raise, but it's possible to raise the weapon sprite by any means, including A_WeaponOffset/A_OverlayOffset, the offset keyword, or setting the offsets directly on the PSP_WEAPON PSprite. Note that ready height for the weapon is 32, which can also be accessed in ZScript using a global constant WEAPONTOP.

If the sprite isn't raised with any of the above outlined methods and the weapon enters the Ready state sequence, then it'll be instantly set to the default position of (0, 32) by its first A_WeaponReady call.

• Fire
• AltFire

Defines the primary and secondary firing sequence. Entered when the player presses primary and secondary fire buttons.

• Hold
• AltHold

These define the refiring loop. A_ReFire jumps to these states when it determines that the weapon should continue firing. If these states are not defined, A_ReFire will loop back to the beginning of the Fire/AltFire states. However, if a weapon inherits from an existing weapon these states will be defined and might need to be overridden!

• Flash
• AltFlash

Defines the flash state. Flash animations run parallel to the normal firing animation and are triggered by calling A_GunFlash.

• Reload

Defines the Reload state. Can be entered if A_WeaponReady is called with WRF_ALLOWRELOAD flag and the player presses the Reload button.

There's no default reloading logic, implementing it is up to the modder. One of the common methods involves defining the "magazine" ammo as ammotype1 and the "reserve" ammo as ammotype2, and then taking reserve ammo and giving magazine ammo to handle reloading.

• Zoom

Defines the Zoom sequence. Can be entered if A_WeaponReady is called with WRF_ALLOWZOOM flag and the player presses the Zoom button.

There's no default zoom logic, implementing it is up to the modder. A_ZoomFactor is commonly used for implementing that logic.

• User1
• User2
• User3
• User4

Defines the four user states. The engine provides no default implementation for these, and there are keybinds available to trigger them, just like zoom and reload (specifically, the +user1, +user2, +user3 and +user4). Also like Reload and Zoom sequences, they must be enabled via A_WeaponReady using WRF_ALLOWUSER# flags where # is the number.

• DeadLowered

Upon the player's death and after their weapon has completely lowered, this state, if present, is entered.

• Lightdone

This state sequence is defined in the base Weapon class and does not need to be redefined. By default it calls A_Light0 and destroys the calling layer. This state sequence is normally entered at the end of the Flash/AltFlash states: they normally increase the map's light level with A_Light1 and other similar functions, then move to Lightdone to return the light level to normal and disappear. However, using it isn't obligatory; it's also possible to call A_Light0 and then stop manually.

Weapon offsets

Weapon sprites can be offset dynamically, those offsets are added on top of the sprites' offsets. The offsets consist of x and y values which correspond to horizontal and vertical offsets:

• x sets the weapon sprite's horizontal offset across the screen. 0 means the weapon is centered, positive values shift the weapon to the right, and negative values shift the weapon to the left.
• y sets the weapon sprite's vertical offset down the screen. Positive values shift the weapon down, negative values shift it up. Note that the default y value of a ready weapon is not 0, as one might think, but actually 32 (in ZScript it can also be accessed via the global constant WEAPONTOP). Overlays, however, use 0 by default (see below).

There are several ways to modify the offsets:

1. The offset keyword that can be placed right after bright (if present) and just before the function call. The keyword requires two parameters, x and y, in parentheses:

OFFG A 5 bright offset (24, 35) A_GunFlash

2. The A_WeaponOffset function. It's a regular function call, not a keyword, however, it's a lot more flexible since it allows modifying the values additively.

3. The A_OverlayOffset function. It works the same way as A_WeaponOffset, except it allows specifying the layer, so it can be used for overlays that are meant to be moved independently from the main weapon layer. Note, by default overlays will follow the main layer's offsets, and their default offsets are (0, 0) (as opposed to the main layer's (0, 32)). Adding offsets will move the overlay relative to the main layer. However, if the PSPF_ADDWEAPON overlay flag is set to false for an overlay, it'll be possible to set its offsets completely independently from the main layer, and it will no longer follow the main layer's position. (Note, as soon as you do that, your overlay's sprite will jump 32 units down because it will no longer be synced with the main layer's position, which, as mentioned, is (0, 32) by default).

See also Creating new weapons.

Weapon methods

Virtual

• int, int CheckAddToSlots()

Called when the level is first loaded if the weapon has neither a defined slot number property nor is assigned to a slot in a player class. Returns the slot number of the weapon and its slot priority multiplied by 65536.

• State GetReadyState()

Returns the weapon's Ready state. Called by multiple functions when setting a weapon to its Ready state (e.g. A_Raise).

• State GetUpState()

Returns the weapon's Select state. Called when a pending weapon becomes the player's current weapon.

• State GetDownState()

Returns the weapon's Deselect state. Called when a pending weapon has been queued up and the current weapon needs to be lowered.

• State GetAtkState(bool hold)

Returns the weapon's Fire state. Called by PlayerPawn's fire function.

• hold - If true, returns the Hold state instead if one is found, otherwise returning Fire.

• State GetAltAtkState(bool hold)

Returns the weapon's Altfire state. Called by PlayerPawn's alt fire function

• hold - If true, returns the AltHold state instead if one is found, otherwise returning Altfire.

• void PlayUpSound(Actor origin)

Plays the weapon's UpSound. Called when a pending weapon becomes the player's current weapon.

• origin - The actor to play the sound from.

• void EndPowerup()

Called when a Tome of Power expires and the weapon is currently powered up.

• bool CheckAmmo(int fireMode, bool autoSwitch, bool requireAmmo = false, int ammocount = -1)

Called when the game checks to see if a weapon has enough ammo either for firing or for switching to. Returns true if the weapon has enough ammo.

• bool DepleteAmmo(bool altFire, bool checkEnough = true, int 'ammouse = -1)

Called to consume ammo when attacking.

• ui Vector2 ModifyBobLayer(Vector2 Bob, int layer, double ticfrac)

Allows modifying the weapon bob values after they have been calculated by the BobWeapon() call on the PlayerPawn.

• bob - the bob value received from BobWeapon().
• layer - the number of the layer that is bobbing.
• ticfrac - current tic fraction.

By default the function returns bob unmodified.

• ui Vector3, Vector3 ModifyBobLayer3D(Vector3 Translation, Vector3 Rotation, int layer, double ticfrac)

Allows modifying the weapon bob values for 3D-model-based weapons after they have been calculated by the BobWeapon3D() call on the PlayerPawn.

• Translation - the 3D position value received from BobWeapon3D().
• Rotation - the 3D rotation value received from BobWeapon3D().
• layer - the number of the layer that is bobbing.
• ticfrac - current tic fraction.

By default the function returns Translation, Rotation unmodified.

• ui Vector3 ModifyBobPivotLayer3D(int layer, double ticfrac)

(Need more info)

Action functions

• A_WeaponReady
• A_WeaponOffset
• A_Lower
• A_Raise
• A_ReFire
• A_ClearReFire
• A_GunFlash
• A_CheckReload
• A_CheckForReload
• A_CheckRailReload (Skulltag only: not supported by ZDoom) (deprecated)
• A_ResetReloadCounter
• A_Light
• A_Light0
• A_Light1
• A_Light2
• A_LightInverse
• A_ClearOverlays
• A_Overlay
• A_OverlayAlpha
• A_OverlayFlags
• A_OverlayOffset
• A_OverlayPivot
• A_OverlayPivotAlign
• A_OverlayRenderstyle
• A_OverlayRotate
• A_OverlayScale
• A_OverlayTranslation
• A_OverlayVertexOffset
• ResetPSprite
• A_Recoil
• A_ZoomFactor
• A_SetCrosshair

Static

• static void DoReadyWeaponToSwitch (PlayerInfo player, bool switchable)

Readies a weapon for switching. Used by A_WeaponReady.

• static void DoReadyWeaponDisableSwitch (PlayerInfo player, int disable)

Disables a weapon's ability to switch to another weapon. Used by A_WeaponReady.

• static void DoReadyWeaponToFire (PlayerPawn pawn, bool prim, bool alt)

Readies a weapon for attacking. Used by A_WeaponReady.

• static void DoReadyWeaponToBob (PlayerInfo player)

Allows the weapon to bob. Used by A_WeaponReady.

• static int GetButtonStateFlags(int flags)

Examples

ZScript

Note: DoomEdNums must be specified via MAPINFO when using ZScript.

class Karabiner98K : Weapon
{
	Default
	{
		Attacksound "wolf/karabiner";
		Decal "BulletChip";
		Inventory.pickupsound "misc/w_pkup";
		Inventory.pickupmessage "You got the Karabiner 98K!";
		Inventory.icon "KARWA0";
		Weapon.selectionorder 400;
		Weapon.ammotype "Magazine";
		Weapon.ammogive 20;
		Weapon.ammouse 2;
	}
	States
	{
	Spawn:
		KARW A -1;
		stop;
	Ready:
		KARA A 1 A_WeaponReady;
		loop;
	Deselect:
		KARA A 1 A_Lower;
		loop;
	Select:
		KARA A 1 A_Raise;
		loop;
	Fire:
		KARA A 4;
		KARA I 5 
		{
			A_FireBullets(6, 0, 16, 5);
			A_GunFlash();
		}
		KARA J 4;
		KARA H 8 A_StartSound ("karabiner/close");
		KARA A 5 A_ReFire;
		goto Ready;
	Flash:
		KARA I 5 bright A_Light1;
		KARA J 4 bright A_Light2;
		goto Lightdone;
	}
}

DECORATE

actor Karabiner98K : Weapon 10287
{
  Attacksound "wolf/karabiner"
  Decal BulletChip
  Inventory.pickupsound "misc/w_pkup"
  Inventory.pickupmessage "You got the Karabiner 98K!"
  Inventory.icon "KARWA0"
  Weapon.selectionorder 400
  Weapon.ammotype Magazine
  Weapon.ammogive 20
  Weapon.ammouse 2
  States
  {
  Spawn:
    KARW A -1
    stop
  Ready:
    KARA A 1 A_WeaponReady
    loop
  Deselect:
    KARA A 1 A_Lower
    loop
  Select:
    KARA A 1 A_Raise
    loop
  Fire:
    KARA A 4
    TNT1 A 0 A_GunFlash
    KARA I 5 A_FireBullets (6, 0, 16, 5, "BulletPuff")
    KARA J 4
    KARA H 8 A_StartSound ("karabiner/close")
    KARA A 5 A_ReFire
    goto Ready
  Flash:
    KARA I 5 bright A_Light1
    KARA J 4 bright A_Light2
    goto Lightdone
  }
}

Base class definition

ZScript definition

The ZScript definition is very long and its full version can be found on GZDoom github.

DECORATE definition

Note: This is legacy code, kept for archival purposes only. DECORATE is deprecated in GZDoom and is completely superseded by ZScript. GZDoom internally uses the ZScript definition above.

ACTOR Weapon : Inventory native
{
  Inventory.PickupSound "misc/w_pkup"
  Weapon.DefaultKickback
  Weapon.BobSpeed 1.0
  Weapon.BobRangeX 1.0
  Weapon.BobRangeY 1.0
  +WEAPONSPAWN
  States
  {
  LightDone:
    SHTG E 0 A_Light0
    Stop
  }
  
  action native A_ZoomFactor(float scale = 1, int flags = 0);
  const int ZOOM_INSTANT = 1;
  const int ZOOM_NOSCALETURNING = 2;
  
  action native A_SetCrosshair(int xhair);
}