weapon

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.

Aim assist

Aim assist includes three distinct features which are customizable on a per-weapon basis. These systems make it easier for players to land shots on enemy units, especially on controllers.

Autoaim: The "red reticle" feature which causes projectile paths to deviate towards enemy autoaim pills when they're within the autoaim range and angle.
Magnetism: Only applicable to controllers where it causes the player's view to slightly "follow" enemy units. This is disabled in H1PC by default, but can be enabled for controllers with player_magnetism 1.
Vehicle weapon deviation: Only applicable to vehicle weapons where the player's viewing angle can be out of alignment with the weapon's own forward angle. For example, the Warthog turret cannot rotate as fast as the player can turn their camera. In this situation the game allows projectiles to be deviated towards the player's viewing direction rather than firing straight forward from the weapon, up to a maximum deviation angle.

Enable these globals to see aim assist in action:

debug_objects 1
debug_objects_biped_autoaim_pills 1
temporary_hud 1

Structure and fields

Field Type Comments

weapon flags bitfield

Flag	Mask	Comments
vertical heat display	`0x1`	Unused
mutually exclusive triggers	`0x2`	Unused
attacks automatically on bump	`0x4`	Unused
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`	Unused
holds triggers when dropped	`0x100`	Unused
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`	Unused
enables integrated night vision	`0x4000`
ais use weapon melee damage	`0x8000`
prevents crouching	`0x10000`	H1A only Unused Planned backport from H3, currently unused.
uses 3rd person camera	`0x20000`	H1A only While this weapon is held the player will have a third person view. The player unit's second camera track is used for this. The camera smoothly transitions to/from third person.

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

TagDependency

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

overheated

TagDependency

overheat detonation

TagDependency

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

H1A only

Present in previous versions, but has no effect in them. Reduces or inverts player movement by a fraction when this weapon is held.

Option	Value	Comments
always	`0x0`	Movement is penalized at all times while held.
when zoomed	`0x1`	Movement is penalized only when zoomed in.
when zoomed or reloading	`0x2`	Bugged. Movement is penalized only when not reloading.

forward movement penalty

float

The fraction of movement speed lost when moving forward or backward. A value of 1.0 prevents movement. Values greater than 1.0 invert input, up to 2.0 which gives full movement speed in the opposite direction.

sideways movement penalty

float

As above, but for movement from side to side.

minimum target range

float

AI actors will not fire this weapon on targets below this range; but Overcharge special fire mode will ignore this setting.

looking time modifier float

light power on time

float

Unit: seconds

light power off time

float

Unit: seconds

light power on effect

TagDependency

light power off effect

TagDependency

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

TagDependency

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

TagDependency

chambering effect

TagDependency

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. While on, weapon will continue firing while meleeing or throwing grenades, when dropped, and when switched, firing in unexpected directions in the latter two states.
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's trigger will be held down when it is dropped, regardless of whether it was held down by the wielder at the time. These dropped weapons will expend ammunition but not build up age.
ejects during chamber	`0x80`
discharging spews	`0x100`	If true and the trigger is set to discharge on overcharge, will automatically fire every tick for the duration of spew time.
analog rate of fire	`0x200`
use error when unzoomed	`0x400`	Makes the trigger always fire completely accurately when zoomed in, disregarding the triggers' defined error values.
projectile vector cannot be adjusted	`0x800`	Forces projectiles to be fired in the direction the gun (more precisely the gun's trigger marker) is facing, rather than the direction the wielder is looking. Most relevant for vehicle-mounted weapons.
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 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`	The sound is not perceived at all.
medium	`0x1`	This is the volume of the sniper rifle. The exact radius is unknown.
loud	`0x2`
shout	`0x3`	Every AI in the BSP can hear this.
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

TagDependency

distribution function enum

Option	Value	Comments
point	`0x0`	Causes projectiles' firing angle to be randomly offset by a number between the minimum error and the current error angle (see below).
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	`TagDependency` sound effect
misfire effect	`TagDependency` sound effect
empty effect	`TagDependency` sound effect
firing damage	`TagDependency`: damage_effect	Damage effect applied to the wielder when a shot is normally fired. Used for camera shaking, etc.
misfire damage	`TagDependency`: damage_effect
empty damage	`TagDependency`: damage_effect

Acknowledgements

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)
t3h m00kz (Aim assist vs magnetism explanation)