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

FieldTypeComments
weapon flagsbitfield
FlagMaskComments
vertical heat display0x1
  • Unused
mutually exclusive triggers0x2
  • Unused
attacks automatically on bump0x4
  • Unused
must be readied0x8
doesn't count toward maximum0x10

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 zoomed0x20
prevents grenade throwing0x40
must be picked up0x80
  • Unused
holds triggers when dropped0x100
  • Unused
prevents melee attack0x200
detonates when dropped0x400

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 age0x800
secondary trigger overrides grenades0x1000
obsolete does not depower active camo in multilplayer0x2000
  • Unused
enables integrated night vision0x4000
ais use weapon melee damage0x8000
prevents crouching0x10000
  • H1A only
  • Unused

Planned backport from H3, currently unused.

uses 3rd person camera0x20000
  • 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.

labelTagString

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

secondary trigger modeenum
OptionValueComments
normal0x0
slaved to primary0x1
inhibits primary0x2
loads alterate ammunition0x3
loads multiple primary ammunition0x4
maximum alternate shots loadeduint16
weapon a inenum
OptionValueComments
none0x0
heat0x1
primary ammunition0x2
secondary ammunition0x3
primary rate of fire0x4
secondary rate of fire0x5
ready0x6
primary ejection port0x7
secondary ejection port0x8
overheated0x9
primary charged0xA
secondary charged0xB
illumination0xC
age0xD
integrated light0xE
primary firing0xF
secondary firing0x10
primary firing on0x11
secondary firing on0x12
weapon b inenum?
weapon c inenum?
weapon d inenum?
ready timefloat
ready effect
TagDependency
heat recovery thresholdfloat
  • Min: 0
  • Max: 1
overheated thresholdfloat
  • Min: 0
  • Max: 1
heat detonation thresholdfloat
  • Min: 0
  • Max: 1
heat detonation fractionfloat
  • Min: 0
  • Max: 1
heat loss ratefloat
  • Unit: per second
  • Min: 0
heat illuminationfloat
  • 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 damageTagDependency: damage_effect
player melee responseTagDependency: damage_effect
actor firing parametersTagDependency: actor_variant
near reticle rangefloat
  • Unit: world units
far reticle rangefloat
  • Unit: world units
intersection reticle rangefloat
zoom levelsuint16
zoom magnification rangeBounds

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

FieldTypeComments
minfloat
maxfloat
autoaim anglefloat

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

autoaim rangefloat
  • Unit: world units

The maximum range of the autoaim cone.

magnetism anglefloat

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

magnetism rangefloat
  • Unit: world units

The maximum target distance for magnetism to apply.

deviation anglefloat

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 penalizedenum
  • 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.

OptionValueComments
always0x0

Movement is penalized at all times while held.

when zoomed0x1

Movement is penalized only when zoomed in.

when zoomed or reloading0x2

Bugged. Movement is penalized only when not reloading.

forward movement penaltyfloat

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 penaltyfloat

As above, but for movement from side to side.

minimum target rangefloat

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

looking time modifierfloat
light power on timefloat
  • Unit: seconds
light power off timefloat
  • Unit: seconds
light power on effect
TagDependency
light power off effect
TagDependency
age heat recovery penaltyfloat
age rate of fire penaltyfloat
age misfire startfloat
  • Min: 0
  • Max: 1
age misfire chancefloat
  • Min: 0
  • Max: 1
first person model
TagDependency
first person animationsTagDependency: model_animations
hud interfaceTagDependency: weapon_hud_interface
pickup soundTagDependency: sound
zoom in soundTagDependency: sound
zoom out soundTagDependency: sound
active camo dingfloat
active camo regrowth ratefloat
weapon typeenum
OptionValueComments
undefined0x0
shotgun0x1
needler0x2
plasma pistol0x3
plasma rifle0x4
more predicted resourcesBlock
  • HEK max count: 1024
  • Cache only
FieldTypeComments
typeenum
OptionValueComments
bitmap0x0
sound0x1
resource indexuint16
taguint32
magazinesBlock
  • HEK max count: 2
FieldTypeComments
flagsbitfield
FlagMaskComments
wastes rounds when reloaded0x1
every round must be chambered0x2
rounds rechargeduint16
rounds total initialuint16

includes loaded ammo

rounds reserved maximumuint16

does not include loaded ammo

rounds loaded maximumuint16
reload timefloat
rounds reloadeduint16
chamber timefloat
reloading effect
TagDependency
chambering effect
TagDependency
magazine objectsBlock
  • HEK max count: 8
FieldTypeComments
roundsuint16
equipmentTagDependency: equipment
triggersBlock
  • HEK max count: 2
  • Processed during compile
FieldTypeComments
flagsbitfield

Various flags that change the behavior of the given trigger.

FlagMaskComments
tracks fired projectile0x1
random firing effects0x2

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 ammo0x4

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

does not repeat automatically0x8

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 state0x10

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 origin0x20

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 dropped0x40

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 chamber0x80
discharging spews0x100

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 fire0x200
use error when unzoomed0x400

Makes the trigger always fire completely accurately when zoomed in, disregarding the triggers' defined error values.

projectile vector cannot be adjusted0x800

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 error0x1000

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 only0x2000

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 halo10x4000
  • 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 fireBounds?
  • 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 timefloat
  • 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 timefloat
  • 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 firefloat

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

magazineuint16

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 shotint16

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 loadedint16

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 contrailsint16

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 noiseenum

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

OptionValueComments
silent0x0

The sound is not perceived at all.

medium0x1

This is the volume of the sniper rifle. The exact radius is unknown.

loud0x2
shout0x3

Every AI in the BSP can hear this.

quiet0x4
errorBounds
  • 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 timefloat

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 timefloat

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

charging timefloat

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

charged timefloat

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 actionenum

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

OptionValueComments
none0x0

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

explode0x1

The weapon will detonate using its item detonation effect.

discharge0x2

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

charged illuminationfloat
spew timefloat

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

charging effect
TagDependency
distribution functionenum
OptionValueComments
point0x0

Causes projectiles' firing angle to be randomly offset by a number between the minimum error and the current error angle (see below).

horizontal fan0x1

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

projectiles per shotint16

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 anglefloat

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

minimum errorfloat

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 angleBounds

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.

FieldTypeComments
minfloat
maxfloat
first person offsetPoint3D

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 (-).

FieldTypeComments
xfloat
yfloat
zfloat
projectile objectTagDependency: 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 timefloat
illumination recovery timefloat
heat generated per roundfloat
  • Min: 0
  • Max: 1
age generated per roundfloat
  • Min: 0
  • Max: 1
overload timefloat
  • Unit: seconds
illumination recovery ratefloat
  • Cache only
ejection port recovery ratefloat
  • Cache only
firing acceleration ratefloat
  • Cache only

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

firing deceleration ratefloat
  • Cache only

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

error acceleration ratefloat
  • Cache only

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

error deceleration ratefloat
  • Cache only

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

firing effectsBlock
  • HEK max count: 8
FieldTypeComments
shot count lower bounduint16
shot count upper bounduint16
firing effect
TagDependency
misfire effect
TagDependency
empty effect
TagDependency
firing damageTagDependency: damage_effect

Damage effect applied to the wielder when a shot is normally fired. Used for camera shaking, etc.

misfire damageTagDependency: damage_effect
empty damageTagDependency: 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)