DDF Weapons

Stored in the DDFWEAP data lump, or the weapons.ddf file.

DDFWEAP allows you to define and modify weapons for the player to use. Each entry consists of a unique name, enclosed in square brackets, plus a series of commands that specify the characteristics of the weapon, such as ammo, damage, range, speed and HUD animation.

Names should be descriptive of what the weapon does, and are referred to from the DDFTHING/things.ddf file.

Commands

The commands used for weapon entries are as follows:

COMMAND	TYPE	DESCRIPTION
AMMOPERSHOT	[integer]	The amount of ammo of the weapons type that is expended each time the weapon is fired. Eg for the BFG it's 40, the Super Shotgun is 2, and most other things are 1.
AMMOTYPE	[special]	Type of ammo the weapon uses. There are 12 different types of ammo in EDGE. See the section on [AMMO types](#ammo) for details.
ATTACK	[attack]	Attack type to use when the weapon is fired. Must refer to a valid entry in the attacks.ddf file.
AUTOMATIC	[boolean]	If TRUE, the Weapon is fully automatic. If FALSE then the weapon is only semi automatic. A semi-automatic weapon must **not** use the REFIRE action in it's attack states. The SHOOT action should be used instead.
BOBBING	[percentage]	How much the weapon should bob up and down while walking
BINDKEY	[integer]	The key this weapon binds to. Valid values are 0 - 9\. Any number of weapons can bind to a single key, so it is recommended you group them accordingly, e.g key 1 for close combat weapons, key 5 for missile/grenade weapons etc. Note only the normal six weapon lights will be shown in the status bar.
CLIPSIZE	[integer]	The amount of ammo that a weapon will use before going into its RELOAD state. Weapon must have RELOAD states and use the CHECKRELOAD action for this to work.
DANGEROUS	[boolean]	If TRUE, this weapon will not be automatically selected when another runs our of ammo, regardles of the weapons PRIORITY. This is because it is considered dangerous to the player. E.g. the Rocket Launcher
EJECT_ATTACK	[attack]	Attack type used by default when the EJECT action is encountered in the weapon states. Primarily used for ejecting shell casings.
ENGAGED_SOUND	[sound]	Sound to play when the trigger is pulled, but the target missed. Used primarily for the chainsaw.
FEEDBACK	[boolean]	If TRUE, then the Player will be thrown around by this weapon. Used originally for the chainsaw.
FREE	[boolean]	If TRUE, then the player starts with this weapon. E.g Fist, pistol
IGNORE_CROSSHAIR_SCALING	[boolean]	If TRUE, and this weapon has custom crosshair sprites, they will not be affected by Video menu option "Crosshair Size".
HIT_SOUND	[sound]	Sound played when the trigger is pulled and a target is found. Used originally for the chainsaw.
IDLE_WAIT	[time]	The minimum time before entering the IDLE states.
IDLE_CHANCE	[percentage]	The chance to enter the idle states when the timer runs out. If the timer runs out and the random test fails, then the timer is reset to 1/10th of IDLE_WAIT
IDLE_SOUND	[sound]	Sound played while the weapon is idle. Used originally for the chainsaw weapon.
KICK	[float]	Amount the player receives as kick from the weapon, making the weapon aim and view `jiggle'. Values between 0 and 0.2 are best.Works well on weapons like the shotgun, or auto bullet weapons (i.e chaingun).
MODEL_ASPECT	[float]	Change the models width and length, therefore making it fatter/skinnier. 0.5 would be half width(skinny), 2.0 would be double width(fatter)
MODEL_BIAS	[float]	Move model up or down. Negative numbers move the model lower on-screen, postive numbers move it up.
MODEL_FORWARD	[float]	Move the weapon forward/backward
MODEL_SIDE	[float]	Move the model left or right on screen. Negative numbers move it more left, Positive numbers move it more to the right.
MODEL_SKIN	[integer]	Up to nine skins can currently be used (1 to 9). Skins must be defined in DDFImages
NOTHRUST	[boolean]	If TRUE, then targets will not be pushed away by a hit from this weapon. Used originally for the chainsaw.
PRIORITY	[integer]	This is used for selecting another weapon when the current weapon runs out of ammo. When this happens, the weapon with the highest priority value that has enough ammo to shoot will be selected. (-1 means that you will need to manually select the weapon)
REFIRE_INACCURATE	[boolean]	If TRUE, then shots from this weapon in, automatic firing mode, will become less accurate E.g The Chaingun. Attack states must contain the REFIRE action for this to work.
SEC_AMMOPERSHOT	[integer]	Like AMMOPERSHOT but for the weapon's secondary attack.
SEC_AMMOTYPE	[special]	Like AMMOTYPE but for the weapon's secondary attack.
SEC_AUTOMATIC	[boolean]	Like AUTOMATIC but for the weapon's secondary attack.
SEC_CLIPSIZE	[integer]	Like CLIPSIZE but for the weapon's secondary attack.
SEC_REFIRE_INACCURATE	[boolean]	Like REFIRE_INACCURATE but for the weapon's secondary attack.
SECOND_ATTACK	[attack]	Attack type to use by default for the weapon's secondary attack. Weapon must have SECATTACK states and use the SEC_SHOOT and/or SEC_REFIRE actions.
SHARED_CLIP	[boolean]	If TRUE, the primary and secondary attacks use a single (shared) clip. Hence you cannot use SEC_AMMOTYPE, SEC_AMMOPERSHOT or SEC_CLIPSIZE commands when using SHARED_CLIP. There can only be a single reload animation (SECRELOAD states will be ignored).
SHOW_CLIP	[boolean]	If TRUE, then shows clipsize remaining on the status bar instead of total ammo of that type.
[SPECIAL](#special)	[special]	Special characteristics of the weapon. See 'list' of specials below.
[SEC_SPECIAL](#special)	[special]	Special characteristics of the secondary attack. See 'list' of specials below.
START_SOUND	[sound]	Sound played when the weapon is selected.
[STATES](#states)(state_name)	[state]	States are used to create weapon animations in the HUD, E.g. when a weapon is fired or when it reloads. The 'state_name' can be any string, or one of the [special STATES](#Speshstates) lited below.
SWAYING	[percentage]	How much the weapon should sway left and right while walking
TEMPLATE	[existing DDF entry]	This allows a new DDF entry to be based off an existing one. Inheritance for DDF basically.
UPGRADES	[special]	A previously declared weapon name that this weapon should replace. E.g a silencer for a pistol, or homing rocket for the rocket launcher.
Y_ADJUST	[integer]	Will offset the weapon sprites in Y (negative numbers move it down, positive numbers move it up). Mainly for Heretic compatibility (were most weapons have a Y_ADJUST=-15)
ZOOM_FACTOR	[float]	When this is used, the weapon has a zoom capability. The value is how much zoom we want, for example 2.0 is double, 3.0 is triple. Setting it to 0.0 disables zooming.
ZOOM_FOV	[float]	When this is used, the weapon has a zoom capability. The value is the FOV angle, for example 10\. Should be used in conjunction with the levels.ddf special LIMIT_ZOOM, which prevents zooming unless the player is holding a weapon with zoom capability. Deprecated, should use ZOOM_FACTOR instead.

STATES

Each named STATES entry defines an animation sequence to play when a weapon is performing particular function, as well as calling the actions required at the appropriate frames in the animation. These consist of a series of states, which are individual frames of the animation. A state is defined like this:
   Sprite:Frame:Tics:Bright:Action
as follows:

Sprite	The four letter name of the sprite to use.
Frame	The frame reference, A-Z, '[', '\', ']' If you need more than this, use another sprite.
Tics	Number of tics to spend on this frame. -1 means the frame should last forever.
Bright	Can be 'BRIGHT', 'NORMAL' or 'LIT00-99'. Bright frames are always drawn full brightness. LIT00-LIT99: This allows fine-grained control of dynamic lights. LIT00 is the same as 'NORMAL', LIT99 is the same as 'BRIGHT'.
Action	Action to be carried out. Actions are listed below.

Each frame ends with either a semincolon ; if it is the last frame in the animation or a comma , if it is not.

In addition, any line may include a #Command at the end. This will either be #STATENAME which causes a jump to the first frame in the animation of the named state. #STATENAME:FRAME causing a jump to the specified frame number in the animation of the named state. OR #REMOVE to remove the animation shown from the HUD.

Special STATES

The following are predefined state names that have specifc purposes:

STATE NAME	SPECIAL USE
ATTACK	The state to use when the trigger is pulled.
CROSSHAIR	Used to create custom crosshairs, can be static or animated.
DOWN	The states to use when this weapon is deselected. (Usually, but not necessarily the same as the upstate)
DISCARD	Similar to the PARTIAL special: if you press the reload key with a half-empty clip (i.e. neither empty nor full), then the clip is discarded and the DISCARD states are entered. These states must end with the CHECKRELOAD action to cause the weapon to reload
EMPTY	The states to use when the primary attack runs out of ammo. You must use the "EMPTY" action in the empty states, for example: STATES(EMPTY) = ABCD:E:1:NORMAL:EMPTY;
FLASH	Miscellaneous state for use of muzzle flashes etc...
IDLE	These are entered from the READY or EMPTY states after a certain time has elapsed. Used in conjunction with IDLE_WAIT and IDLE_CHANCE commands.
READY	The normal state for a weapon, when it is ready to be fired.
RELOAD	State for reloading weapon. (See shotgun)
UP	The states to use when this weapon is selected.
SECATTACK	State for when user triggers secondary attack.
SECDISCARD	Same as DISCARD, but for secondary attack.
SECRELOAD	Like RELOAD, but for the secondary attack.
SECFLASH	Like FLASH, but for the secondary attack.
ZOOM	States used for this weapon in zoomed field of view mode.

  ACTIONS

The following actions can be used in weapon states:

ACTION	DESCRIPTION
BECOME	Allows a weapon to turn into another weapon. The name must be given in brackets, e.g. BECOME(SUPER_PISTOL). It's also possible to jump directly to a certain state e.g. BECOME(SUPER_PISTOL,READY:2)
CHECKRELOAD	Checks whether the player has used up the clip quantity of ammo. If yes, then force a reload by jumping into the RELOAD states.
DJNE	Used like JUMP(state_name:frame,xx%), but decrements the reload quantity for the specified attack and jumps if it's not zero. The jump chance is now interpreted as the attack specifier: 0% is the primary attack ammo, and non-zero percent is the secondary attack ammo.
EJECT	Like SHOOT, but without any kick, flash or change in player state, and without using any ammo. Used to create ejecting shells from weapons. Used like EJECT(attack_name), but will use the weapons EJECT_ATTACK (if defined) if no attack_name is specified.
FLASH	Starts the weapon's FLASH states.
JUMP	Used like JUMP(state_name:frame,xx%), this activates with a xx% chance of causing a switch to the specified frame of the named state. Useful for adding a random aspect to the animations
KICK	This action generates and additional kick effect to that specified in the commands. It is used like so KICK(value), where the value will usually be between 0 and 0.2, though higher values are possible.
KILLSOUND	Stops any sound playing that is associated with this weapon.
LIGHT0	Sets light around player to normal.
LIGHT1	Sets light around player to bright.
LIGHT2	Sets light around player to brightest.
LOWER	Lowers the player's weapon sprite off the screen when selecting a new weapon or dead.
NOFIRE	When using more than one attack per weapon, the firing sequence is reset once the player stops firing. e.g the quake super nailgun.
NOFIRE_RETURN	When using more than one attack per weapon, this will 'remember' the firing sequence.
NOTHING	Like the sign says... Do nothing. This is the most common 'action' in weapon states.
PLAYSOUND	Used like PLAYSOUND(sound_name), this plays the specified sound referred to in sounds.ddf
RAISE	Raises the player's weapon sprite onto the screen when selecting a new weapon.
READY	Checks for trigger pulled, and enters the ATTACK states if it is (or SECATTACK states for the secondary attack key).
REFIRE	Checks whether the player has stopped firing. If yes, then the weapon returns to the READY states. If not, the weapon goes back to the ATTACK states. Only needed for automatic weapons.
RTS_ENABLE_TAGGED(tagnum)	Trigger an RTS script with this tag number.
RTS_DISABLE_TAGGED(tagnum)	Disable an RTS script with this tag number.
SEC_CHECKRELOAD	Same as CHECKRELOAD, but used for the secondary attack.
SEC_FLASH	Starts the weapon's SEC_FLASH states.
SEC_NOFIRE	Same as NOFIRE, but used for the secondary attack.
SEC_NOFIRE_RETURN	Same as NOFIRE_RETURN, but used for the secondary attack.
SEC_REFIRE	Same as REFIRE, but used for the secondary attack.
SEC_SHOOT	Same as SHOOT, but used for the secondary attack.
SET_SKIN(skin number)	Dynamically change the current skin to a different one.
SHOOT	Starts attack associated with weapon. If the FLASH action hasn't been called, starts the flash state. The SHOOT action uses the weapon's default attack, but a valid attack can be placed in brackets after the statement, for example: SHOOT(GRENADE).
TRANS_SET	Used like TRANS_SET(xx%) to set the transparency of the animation as a percentage of it's original.
TRANS_FADE	Used like TRANS_FADE(xx%) to fade the transparency of the animation from it's previous level to that specified.
SETCROSS(FRAME)	Crosshair jumps to the given frame
TARGET_JUMP(FRAME)	The action will check if there is something that the autoaiming can lock onto, and change the crosshair accordingly. Crosshair jumps to the given frame IF player has a target. Can only be used in the crosshair states. Example: STATES(CROSSHAIR) =  CROS:A:0:NORMAL:**TARGET_JUMP**(C_ENEMY), CROS:A:5:NORMAL:NOTHING; STATES(C_ENEMY) =  CROS:B:5:NORMAL:NOTHING,#CROSSHAIR;
UNZOOM	Forces the screen to be unzoomed if zoom is active. Basically deactivates zoom for this weapon.
FRIEND_JUMP(FRAME)	Similar to TARGET_JUMP, but for friendlies. Crosshair jumps to the given frame IF player target is a friend. Can only be used in the crosshair states

AMMO Types

The following ammo types are available in edge. These include the regular Doom and Doom2 ammo types, as well as 94 new ones specially for use in EDGE:

AMMO Type	DESCRIPTION
NOAMMO	For weapons like the chainsaw and fist -- Used in Doom and Doom 2
BULLETS or AMMO1	Normally used for the pistol and chaingun -- Used in Doom and Doom 2
SHELLS or AMMO2	Used for the Shotgun and Super Shotgun -- Used in Doom and Doom 2
ROCKETS or AMMO3	For the Rocket Launcher -- Used in Doom and Doom 2
CELLS or AMMO4	Usually for the Plasmagun and BFG -- Used in Doom and Doom 2
AMMO5 (aka PELLETS)	Can be for anything
AMMO6 (aka NAILS)	Can be for anything
AMMO7 (aka GRENADES)	Can be for anything
AMMO8 (aka GAS)	Can be for anything
AMMO9	Can be for anything
AMMO10	Can be for anything
AMMO11	Can be for anything
AMMO12	Can be for anything
AMMO13	Can be for anything
AMMO14	Can be for anything
AMMO15	Can be for anything
...	...
AMMO99	Can be for anything

SPECIAL Flags

SPECIAL	DESCRIPTION
SILENT_TO_MONSTERS	Monsters cannot hear this attack. Used for punch or other weapon you'd like to silence.
ANIMATED	UP and DOWN states are animated. When using this special, the weapon sprite doesn't raise up or lower down. Instead the UP and DOWN states should show an animation. The RAISE and LOWER commands must occur once, in the very last frame
NO_SWITCH	don't switch to new weapon if ammo runs out
NO_TRIGGER	prevent reloading by pressing fire button
FRESH	reload empty clip when fresh ammo is picked up
NO_MANUAL	disable manual reloading key
NO_PARTIAL	manual reload: clip must be empty to refill it

Examples

The following are examples of complete weapon entries:

[FIST]  
AMMOTYPE=NOAMMO;  
AUTOMATIC=TRUE;  
FREE=TRUE;  
BINDKEY=1;  
PRIORITY=0;  
ATTACK=PLAYER_PUNCH;  
STATES(UP)=PUNG:A:1:NORMAL:RAISE;  
STATES(DOWN)=PUNG:A:1:NORMAL:LOWER;  
STATES(READY)=PUNG:A:1:NORMAL:READY;  
STATES(ATTACK)=PUNG:B:4:NORMAL:NOTHING,  
                PUNG:C:4:NORMAL:SHOOT,  
                PUNG:D:5:NORMAL:NOTHING,  
                PUNG:C:4:NORMAL:NOTHING,  
                PUNG:B:5:NORMAL:REFIRE;  

[SUPERSHOTGUN]  
AMMOTYPE=SHELLS;  
AMMOPERSHOT=2;  
AUTOMATIC=TRUE;  
BINDKEY=3;  
PRIORITY=4;  
ATTACK=PLAYER_SHOTGUN2;  
SOUND1=DBOPN;  
SOUND2=DBLOAD;  
SOUND3=DBCLS;  
KICK=0.1;  
STATES(UP)=SHT2:A:1:NORMAL:RAISE;  
STATES(DOWN)=SHT2:A:1:NORMAL:LOWER;  
STATES(READY)=SHT2:A:1:NORMAL:READY;  
STATES(ATTACK)=SHT2:A:3:NORMAL:NOTHING,  
                SHT2:A:7:NORMAL:SHOOT,  
                SHT2:B:7:NORMAL:NOTHING,  
                SHT2:C:7:NORMAL:CHECKRELOAD;  
STATES(RELOAD)=SHT2:D:7:NORMAL:SOUND1, // OPEN Sound  
                SHT2:E:7:NORMAL:NOTHING,  
                SHT2:F:7:NORMAL:SOUND2, // reload sound  
                SHT2:G:6:NORMAL:NOTHING,  
                SHT2:H:6:NORMAL:SOUND3, // close sound  
                SHT2:A:5:NORMAL:REFIRE;  
STATES(FLASH)=SHT2:I:5:BRIGHT:LIGHT1,  
                SHT2:J:4:BRIGHT:LIGHT2,  
                SHT2:J:0:NORMAL:LIGHT0,#REMOVE;

DDF docs written by Andy Baker and Ziggy Gnarly, with updates by Andrew Apted, Andy Brewood and Luke Brennan. © EDGE Team, et al. 1998 - 2024.