This page is incomplete! You can contribute information using GitHub issues or pull requests.

Weapons are most commonly seen as the wieldable items dropped by enemies and found in the environment. However, they are also used for items like the CTF flag, oddball, and weapons attached to vehicles.

Weapons are intended to fire instances of the projectile tag, but they can technically reference any object (spawning bipeds, for example). Thrown grenades are not a type of weapon, but rather a projectile referenced by globals.

Structure and fields

This tag inherits fields from item which are not shown here. See the parent's page for more information. The following information is unique to the weapon tag.

Field Type Comments
weapon flags bitfield
Flag Mask Comments
vertical heat display 0x1
mutually exclusive triggers 0x2
attacks automatically on bump 0x4
must be readied 0x8
doesn't count toward maximum 0x10

Used for weapons like the oddball and flag which technically count as a third carried weapon, despite the game having a soft limit of 2 held weapons (scripts and mods aside).

aim assists only when zoomed 0x20
prevents grenade throwing 0x40
must be picked up 0x80
holds triggers when dropped 0x100
prevents melee attack 0x200
detonates when dropped 0x400

Causes the weapon to explode using its item detonation effect after being dropped. This is used to make the singleplayer fuel rod gun and energy sword explode when the enemies who carry them die.

cannot fire at maximum age 0x800
secondary trigger overrides grenades 0x1000
obsolete does not depower active camo in multilplayer 0x2000
enables integrated night vision 0x4000
ais use weapon melee damage 0x8000
label TagString

Units that have this label in their animations will be able to pick up the weapon

secondary trigger mode enum
Option Value Comments
normal 0x0
slaved to primary 0x1
inhibits primary 0x2
loads alterate ammunition 0x3
loads multiple primary ammunition 0x4
maximum alternate shots loaded uint16
weapon a in enum
Option Value Comments
none 0x0
heat 0x1
primary ammunition 0x2
secondary ammunition 0x3
primary rate of fire 0x4
secondary rate of fire 0x5
ready 0x6
primary ejection port 0x7
secondary ejection port 0x8
overheated 0x9
primary charged 0xA
secondary charged 0xB
illumination 0xC
age 0xD
integrated light 0xE
primary firing 0xF
secondary firing 0x10
primary firing on 0x11
secondary firing on 0x12
weapon b in enum?
weapon c in enum?
weapon d in enum?
ready time float
ready effect
heat recovery threshold float
  • Min: 0
  • Max: 1
overheated threshold float
  • Min: 0
  • Max: 1
heat detonation threshold float
  • Min: 0
  • Max: 1
heat detonation fraction float
  • Min: 0
  • Max: 1
heat loss rate float
  • Unit: per second
  • Min: 0
heat illumination float
  • Min: 0
  • Max: 1
overheat detonation

This effect is played when the weapon overheats and is set to detonate as a result

player melee damage TagDependency: damage_effect
player melee response TagDependency: damage_effect
actor firing parameters TagDependency: actor_variant
near reticle range float
  • Unit: world units
far reticle range float
  • Unit: world units
intersection reticle range float
zoom levels uint16
zoom magnification range Bounds

Minimum is the magnification amount for the first zoom level, and maximum is the magnification amount for the final zoom level

Field Type Comments
min float
max float
autoaim angle float

Determines the aiming cone where projectiles paths will be pulled towards the target biped's autoaim pill. This is the "red reticle" angle.

autoaim range float
  • Unit: world units

The maximum range of the autoaim cone.

magnetism angle float

For controller input, sets the angle where crosshair "stickiness" becomes a factor and aiming direction automatically tracks targets.

magnetism range float
  • Unit: world units

The maximum target distance for magnetism to apply.

deviation angle float

Used for vehicle weapons to control the maximum angle of deviation when the aiming direction does not match the direction the weapon is facing. For example, the Ghost's deviation angle of 45 degrees allows the driver to fire in the direction they are aiming even if the Ghost has not yet turned to face that direction. Compare this to the Warthog gun's tighter 10 degree limit.

movement penalized enum

Unused. This was meant to slow the player when using certain weapons like the rocket launcher, but it has no effect ingame regardless of the options, penalty values used, or game mode.

Option Value Comments
always 0x0

No effect.

when zoomed 0x1

No effect.

when zoomed or reloading 0x2

No effect.

forward movement penalty float

No effect.

sideways movement penalty float

No effect.

minimum target range float
looking time modifier float
light power on time float
  • Unit: seconds
light power off time float
  • Unit: seconds
light power on effect
light power off effect
age heat recovery penalty float
age rate of fire penalty float
age misfire start float
  • Min: 0
  • Max: 1
age misfire chance float
  • Min: 0
  • Max: 1
first person model
first person animations TagDependency: model_animations
hud interface TagDependency: weapon_hud_interface
pickup sound TagDependency: sound
zoom in sound TagDependency: sound
zoom out sound TagDependency: sound
active camo ding float
active camo regrowth rate float
weapon type enum
Option Value Comments
undefined 0x0
shotgun 0x1
needler 0x2
plasma pistol 0x3
plasma rifle 0x4
more predicted resources Block
  • HEK max count: 1024
  • Cache only
Field Type Comments
type enum
Option Value Comments
bitmap 0x0
sound 0x1
resource index uint16
tag uint32
magazines Block
  • HEK max count: 2
Field Type Comments
flags bitfield
Flag Mask Comments
wastes rounds when reloaded 0x1
every round must be chambered 0x2
rounds recharged uint16
rounds total initial uint16

includes loaded ammo

rounds reserved maximum uint16

does not include loaded ammo

rounds loaded maximum uint16
reload time float
rounds reloaded uint16
chamber time float
reloading effect
chambering effect
magazine objects Block
  • HEK max count: 8
Field Type Comments
rounds uint16
equipment TagDependency: equipment
triggers Block
  • HEK max count: 2
  • Processed during compile
Field Type Comments
flags bitfield

Various flags that change the behavior of the given trigger.

Flag Mask Comments
tracks fired projectile 0x1
random firing effects 0x2

If false the firing effects in the firing effects block will be picked in order. If true they will be picked randomly.

can fire with partial ammo 0x4

The weapon will be able to fire as long as the magazine content is above 0.

does not repeat automatically 0x8

Disables repeat fires while holding the trigger. If true you need to release the trigger before it can fire again. Bug: This breaks if the weapon is a charge weapon with the discharging spews behavior. When the player is a client in multiplayer it will immediately start charging again as soon as it is fired potentially causing automatic firing behavior.

locks in on off state 0x10

Makes the trigger behave like a switch. Tap it to turn it on. Tap it again to turn it off.

projectiles use weapon origin 0x20

If true the projectiles will spawn at the third person primary trigger or secondary trigger marker instead of originating from the center of the first person view.

sticks when dropped 0x40

If true the weapon will keep the trigger state from the time it was dropped. If it was being held while dropped it will continue being held.

ejects during chamber 0x80
discharging spews 0x100
analog rate of fire 0x200
use error when unzoomed 0x400

Makes the trigger always fire completely accurately when zoomed in.

projectile vector cannot be adjusted 0x800
projectiles have identical error 0x1000

Makes it so that all projectiles that are fired simultaneously move in the same direction. Only affects triggers that have multiple projectiles per shot.

projectile is client side only 0x2000

Makes it so that in multiplayer the projectile does is not syncronized over the network and is instead created by client trigger simulation.

use unit adjust projectile ray from halo1 0x4000
  • H1A only

By default, the engine now uses the logic found in later Halos to address projectile bugs. This flag forces the original H1 behavior and is used for the Covenant dropship turret.

maximum rate of fire Bounds?
  • Unit: shots per second

This determines the maximum number of times this trigger can be fired per second. The first value is initial rate of fire and the second value is the final rate of fire. Weapons cannot fire faster than once per tick, and non-positive (0 or less) rate of fire results in firing once per tick. Because weapons cannot fire in between ticks, fire rate is also effectively rounded down to the nearest tickrate/n for any positive integer n (so at 30 ticks per second: 30, 15, 10, 7.5, 6, 5, 4.288, 3.75, 3.333, 3, etc.)

acceleration time float
  • Unit: seconds

The number of seconds required to hold the trigger in order to reach the final rate of fire. A value of 0 means the trigger will always use the final rate of fire.

deceleration time float
  • Unit: seconds

The number of seconds required to release the trigger in order to reach the initial rate of fire. A value of 0 means the trigger will revert to the initial rate of fire the moment the trigger is released.

blurred rate of fire float

The rate of fire needed to switch the object to its ~blur permutation.

magazine uint16

The index of the magazine which this trigger draws ammunition from. If no magazine is given (null), then the weapon effectively has an unlimited amount of rounds.

rounds per shot int16

This is the amount of ammo each trigger fire uses. Unless the "can fire with partial ammo" flag is set, the trigger cannot be fired if there is less than this much ammo remaining and will, instead, reload automatically. Firing with partial ammo with the partial ammo flag will result in the loaded ammo reaching 0 rather than a negative amount. A negative value results in the magazine gaining loaded rounds upon firing.

minimum rounds loaded int16

The magazine will automatically reload if less than this much ammo remains in the magazine, and the weapon cannot fire unless this much ammo is loaded. Unlike rounds per shot, this ignores the "can fire with partial ammo" flag.

projectiles between contrails int16

Contrails will not be created until this many projectiles have been fired. This resets every time the trigger is released, and the first projectile will always have a contrail.

firing noise enum

How loudly AI will perceive this trigger when it fires, determining how they will react (if at all).

Option Value Comments
silent 0x0
medium 0x1
loud 0x2
shout 0x3
quiet 0x4
error Bounds
  • Unused

The function of this field is unknown. It is unused by the game. Although labeled in Guerilla as a range [0, 1], the pistol has a max value of 2. Setting this to 0 does not affect projectile spread.

error acceleration time float

Affects how long it takes for the weapon to reach its maximum projectile error angle while holding the trigger. Can be negated using quick trigger taps.

error deceleration time float

Affects how long it takes for the weapon to reach its minimum projectile error angle during a pause in firing.

charging time float

The amount of time the user has to hold the trigger before the weapon is considered charged.

charged time float

The amount of time it takes after the weapon becomes charged before the overcharged behavior takes effect. Unused if overcharged action is set to none.

overcharged action enum

The reaction the weapon will have to the charged time running out.

Option Value Comments
none 0x0

Nothing happens and the gun will stay charged until the trigger is released.

explode 0x1

The weapon will detonate using its item detonation effect.

discharge 0x2

Forces the gun to fire as it would have had the user let go of the trigger.

charged illumination float
spew time float

The amount of time the weapon will be forced to fire at its given firerate after overcharging.

charging effect
distribution function enum
Option Value Comments
point 0x0
horizontal fan 0x1

Causes projectiles to be spread out in a fan, which actually seems to be vertical.

projectiles per shot int16

Affects how many projectiles are produced by a single shot. For example, the shotgun has this value set to 15. Each projectile is scattered by error angle independently.

distribution angle float

Affects the spread of projectiles when projectiles per shot is greater than 1 and distribution function is fan.

minimum error float

Floor value for error angle. Even if the minimum error angle is 0, this value takes precedence. Note that this field receives a hard-coded singleplayer adjustment at map compile time for the pistol.

error angle Bounds

Determines the minimum and maximum angle of the "error cone". The min angle is for when you begin firing, while the max is reached after a period of sustained fire. The values are shown in degrees in Guerilla, but internally stored in radians. Note that these fields receives hard-coded singleplayer adjustments at map compile time for the pistol and plasma rifle.

Field Type Comments
min float
max float
first person offset Point3D

The relative offset from the first person camera the projectile spawns. X is front (+) and back (-), Y is left (+) and right (-), Z is up (+) and down (-).

Field Type Comments
x float
y float
z float
projectile object TagDependency: object

This is the object that spawns when firing the weapon. The object will spawn facing the same direction as the first person camera (along with any error angle applied, if necessary) with the velocity of the shooter. This reference should not be NULL to prevent crashes in H1CE.

ejection port recovery time float
illumination recovery time float
heat generated per round float
  • Min: 0
  • Max: 1
age generated per round float
  • Min: 0
  • Max: 1
overload time float
  • Unit: seconds
illumination recovery rate float
  • Cache only
ejection port recovery rate float
  • Cache only
firing acceleration rate float
  • Cache only

Pre-calculated rate of firing rate increase, based on the acceleration time field.

firing deceleration rate float
  • Cache only

Pre-calculated rate of firing rate decrease, based on the deceleration time field.

error acceleration rate float
  • Cache only

Pre-calculated rate of error angle increase, based on the error acceleration time field.

error deceleration rate float
  • Cache only

Pre-calculated rate of error angle decrease, based on the error deceleration time field.

firing effects Block
  • HEK max count: 8
Field Type Comments
shot count lower bound uint16
shot count upper bound uint16
firing effect
misfire effect
empty effect
firing damage TagDependency: damage_effect
misfire damage TagDependency: damage_effect
empty damage TagDependency: damage_effect


Thanks to the following individuals for their research or contributions to this topic:

  • Jakey (Explaining weapon error fields)
  • Kavawuvi (Invader tag definitions)
  • MosesOfEgypt (Tag structure research)