From ZDoom Wiki
Jump to navigation Jump to search
Note: Wait! Stop! Before you copy this actor's definition into your mod, remember the following things:
  1. You do not need to copy that actor, since it is already defined.
  2. In fact, it's not just useless, it's actually harmful as it can cause problems.
  3. If you want to modify it, or use a modified version, using inheritance is the way to go.
  4. The actor definitions here are put on the wiki for reference purpose only. Learn from them, don't copy them.
  5. There is only one exception: if what you want is changing Ammo capacity, you need to create a new type from Ammo.
Actor type Internal Game MiniZDoomLogoIcon.png
DoomEd Number None Class Name Weapon

Classes: InventoryWeapon

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.

A player can never carry more than one weapon of each kind.

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. SBARINFO 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.


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.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 DoomWikiLogoIcon.pngalpha 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.YAdjust amount
Shifts the HUD sprites vertically when the status bar is off. Note: positive y values shift the weapon down.
The sound played when the select state is called.
  • 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 not necessary. However, to make things easier to read it is recommended to be used):

Does not fire when selected automatically and the fire button is still pressed. Used to prevent dangerous weapons from firing accidentally.
The ready sound is played only with 50% probability.
The weapon sprite does not bob.
This weapon spawns the special AxeBlood type when hitting something that bleeds. This only has an effect for hitscan and melee weapons.
Does not alert nearby monsters when being fired.
Tells the engine that this weapon doesn't require ammo to work.
The same for the alternate attack.
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.
The primary attack uses both ammo types.
Like WEAPON.PRIMARY_USES_BOTH, makes the AltFire (secondary) attack use both ammo types.
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.
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.
Uses the special kickback formula of Heretic's powered up staff. Unlike normal kickback this is a fixed thrust value.
Signifies to bots that the weapon fires explosive projectiles.
Signifies to bots, and to monsters with the AVOIDMELEE flag, that the weapon is a melee weapon.
Signifies to bots that the weapon causes a lot of damage.
Weapon is not given by the 'give weapons' cheat.
When the player picks this weapon up, they will never automatically switch to it.
  • WEAPON.NOAUTOSWITCHTO (New from 4.7.0)
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.
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.
The weapon will not jump to the deselect state when the player dies.
The weapon cannot act on any input if the player is dead.

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

  • Ready
Defines the weapon's ready sequence. If a weapon is in this sequence it can fire and be deselected.
  • Deselect
Defines a weapons lowering sequence. It must lower the weapon to the bottom of the screen and should not do any other actions.
  • Select
Defines a weapons raising sequence. It must raise the weapon to the normal firing height and should not do any other actions.
  • Fire
  • AltFire
Defines the primary and secondary firing sequence.
  • 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 they will default to 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
  • Zoom
Defines reload and zoom states. The engine provides no default implementation for these, so it is up to the modder to define the weapon's reloading/zoom logic. Also note that these state jumps need to be explicitly enabled via flags in A_WeaponReady.
  • 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. Also like reload and zoom states, they must be enabled via A_WeaponReady.
  • DeadLowered
Upon the player's death and after their weapon has completely lowered, this state, if present, is entered.

Weapons also allow a second keyword in the frame definition, offset, that is placed right after bright (if present) and just before the ACS special or DECORATE function being called. The keyword requires two parameters, x and y, in parentheses. The sprite's own offset is ignored when you specify offset this way.

  • 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. A value of 1 puts the top of the sprite very close to the center of the screen, while higher values cause the weapon to be drawn lower. A value of 0 does not center the weapon; instead, it snaps the bottom of the sprite to the bottom of the screen. Negative values will cause the sprite not to be drawn at all.

The offset keyword may not be used in conjunction with A_WeaponReady.

Note that the offset applies to all future frames until the weapon returns to the Ready state, and that using offset(0, 0) does not manually reset the weapon to its normal offsets. (This would actually indicate no change to offset) Currently there is no way to restore a weapon to default offset other than to return to the Ready state.


OFFG A 5 bright offset (24, 35) A_GunFlash

See also Creating new weapons.

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
    KARW A -1
    KARA A 1 A_WeaponReady
    KARA A 1 A_Lower
    KARA A 1 A_Raise
    KARA A 4
    KARA I 0 A_GunFlash
    KARA I 5 A_FireBullets (6, 0, 16, 5, "BulletPuff")
    KARA J 4
    KARA H 8 A_PlaySound ("karabiner/close")
    KARA A 5 A_ReFire
    goto Ready
    KARA I 5 bright A_Light1
    KARA J 4 bright A_Light2
    KARA J 0 A_Light0

DECORATE definition

ACTOR Weapon : Inventory native
  Inventory.PickupSound "misc/w_pkup"
  Weapon.BobSpeed 1.0
  Weapon.BobRangeX 1.0
  Weapon.BobRangeY 1.0
    SHTG E 0 A_Light0
  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);