actor_variant

An actor variant specializes an actor by defining their use of weapons, grenades, their health, their color, and what equipment they drop. While the actor tag defines common behaviour of an AI type and rank, the actor variant adds additional variety in their appearance and weapon use.

Burst geometry

A burst is a series of shots made at a target. The burst geometry controls how the shots within a burst start and move over time.

At the start of every burst, the game picks a random origin point horizontally near the target to fire at, either to the left or right. The AI will then correct their shots by returning aim back towards the target over the course of the burst.

See the burst geometry fields in the tag structure for more information.

Firing patterns

Firing patterns modify the burst geometry and ranged combat values depending on the actor's state:

  • New-target is when the actor finds a new target to shoot at.
  • Moving is when the actor is moving between scenario firing positions while shooting.
  • Berserk is when the actor is in a berserk state charging at the player.

The firing pattern multipliers (starting at new target burst duration) modify the default burst geometry and ranged combat values only when their value is non-zero.

Change colors

The change colors block of the tag can be used to change armor color, which relies on the bipeds model's shader_model shader(s) having a multipurpose map with a color change mask. Using the change colors block of this tag overrides the biped's color change permutations.

Halo randomly interpolates between the upper and lower bound colors, in either RGB space or HSV if the interpolate color in HSV flag is checked. This gives the Flood their varying skin tones, for example.

If you are looking for multiplayer armor colors, see here.

Structure and fields

Field Type Comments
flags bitfield
Flag Mask Comments
can shoot while flying 0x1
interpolate color in hsv 0x2

Determines if change colors upper and lower bounds are interpolated in HSV space as opposed to RGB.

has unlimited grenades 0x4

Gives the actor an unlimited supply of grenades to throw.

moveswitch stay w friends 0x8
active camouflage 0x10

Gives the actor permanent active camouflage, e.g. stealth Elites.

super active camouflage 0x20

When enabled, makes the active camouflage the hyper stealth variant from globals, which can have a different appearance.

cannot use ranged weapons 0x40

Disables ranged combat settings (beginning at the weapon reference). Even if the AI is holding a weapon, it will not fire it.

prefer passenger seat 0x80

The actor will prefer to enter a vehicle's passenger seat over a gunner seat, as determined by the unit's seat flags.

actor definition

TagDependency: actor

unit

TagDependency: unit

Specifies which biped this variant will spawn as.

major variant

TagDependency: actor_variant

Specifies the next highest "rank" of this actor variant. This allows enemies to "upgrade" in higher difficulties, with the chance being controlled by both the per-difficulty major upgrade globals multipliers and the major upgrade squad setting in the scenario.

metagame type enum
  • H1A only

Used for kill scoring and achievements in MCC. Since this field was padding in pre-MCC editions, maps compiled for MCC should use MCC-native actor_variant tags or set these fields, or else enemies may be scored as Brutes or other unexpected types due to having zeroed-out or garbage data.

Option Value Comments
brute 0x0
grunt 0x1
jackal 0x2
skirmisher 0x3
marine 0x4
spartan 0x5
bugger 0x6

Also called "drone".

hunter 0x7
flood infection 0x8
flood carrier 0x9
flood combat 0xA
flood pure 0xB
sentinel 0xC
elite 0xD
engineer 0xE

Also called "huragok".

mule 0xF
turret 0x10
mongoose 0x11
warthog 0x12
scorpion 0x13
hornet 0x14
pelican 0x15
revenant 0x16
seraph 0x17
shade 0x18
watchtower 0x19
ghost 0x1A
chopper 0x1B
mauler 0x1C

Also called "prowler".

wraith 0x1D
banshee 0x1E
phantom 0x1F
scarab 0x20
guntower 0x21
tuning fork 0x22

Also called "spirit".

broadsword 0x23
mammoth 0x24
lich 0x25
mantis 0x26
wasp 0x27
phaeton 0x28
bishop 0x29

Also called "watcher".

knight 0x2A
pawn 0x2B

Also called "crawler".

metagame class enum
  • H1A only

Used for kill scoring and achievements in MCC.

Option Value Comments
infantry 0x0
leader 0x1
hero 0x2
specialist 0x3
light vehicle 0x4
heavy vehicle 0x5
giant vehicle 0x6
standard vehicle 0x7
movement type enum
Option Value Comments
always run 0x0
always crouch 0x1
switch types 0x2
initial crouch chance float
  • Min: 0
  • Max: 1
crouch time Bounds
  • Unit: seconds
Field Type Comments
min float
max float
run time Bounds?
  • Unit: seconds
weapon

TagDependency: weapon

The weapon that the actor spawns with.

maximum firing distance float
  • Unit: world units

The maximum range, in world units, where the unit can fire at a target.

rate of fire float

This lets you pick the firing rate for this actor. Which affects firing behavior in the following ways:

  • Any above 0 rate of fire is limited by the referenced weapon's minimum rounds per second as the actor will only tap the trigger not hold, not causing the firing speed to climb.

  • When set to 0, the actor will hold the trigger causing it to use the weapon's windup behavior and allows it to reach the weapon's max firing rate.

  • If 0 and the weapon is a charging weapon the actor will hold the charge until the burst ends or the weapon's overcharged action behavior kicks in.

  • If not 0 charging the weapon will fire their uncharged projectiles if they have them.

  • Setting a number higher than the weapon's minimum rate of fire can prompt the actor to fire their gun slower than the weapon's minimum because it will try to tap fire at every 1/rate_of_fire causing it to not be able to fire again immediately after the firing delay.

projectile error float

Adds error on top of the weapon's own error. This makes actors fire inaccurately.

first burst delay time Bounds?
  • Unit: seconds

The delay in seconds before the actor starts its first burst on a new target.

new target firing pattern time float
  • Unit: seconds
surprise delay time float
  • Unit: seconds
surprise fire wildly time float
  • Unit: seconds
death fire wildly chance float
  • Min: 0
  • Max: 1

Sets the chance that the actor will fire their weapon while dying.

death fire wildly time float
  • Unit: seconds

Controls how long the actor will continue firing after death.

desired combat range Bounds?
  • Unit: world units

The distance in world units the actor will try to be in to attack; lower bounds is the minimum range and upper is the maximum. The actor may still fire outside this range, but will move to attain it.

custom stand gun offset Vector3D
Field Type Comments
i float
j float
k float
custom crouch gun offset Vector3D?
target tracking float
  • Min: 0
  • Max: 1

Determines how closely the actor will follow moving targets when firing. bursts. A value of 0 means only firing at the target's location at the start of the burst, while while 1 means following the target perfectly. with each shot. A value in-between can be provided.

target leading float
  • Min: 0
  • Max: 1

Determines how accurately to predict lead on moving targets. A value of 0 means not leading at all and shooting directly at the target, while 1 means perfectly predicting how far in front of the target to lead based on projectile speed and distance. A value in-between can be provided.

weapon damage modifier float

Allows weapon damage to be buffed or nerfed for this actor variant. A value of 0 disables this modifier.

damage per second float

Overrides weapon damage if set and weapon damage modifier is 0.

burst origin radius float
  • Unit: world units

The starting point of the burst, randomly to the left or right of the target in world units.

burst origin angle float

Controls the maximum angle from horizontal that the orgin can be, from the point of view of the actor. For example, a value of 0 indicates the origin will alway be directly to the left or right of the target, while 90 would allow the origin to be above or below the target as well.

burst return length Bounds?
  • Unit: world units

How far the burst point moves back towards the target. This can be negative to make the burst lead away from the target.

burst return angle float

Controls how close to horizontal the return motion can be.

burst duration Bounds?
  • Unit: seconds

Cotrols the length of burst, during which multiple shots are fired.

burst separation Bounds?
  • Unit: seconds

Controls how long to wait between bursts.

burst angular velocity float
  • Unit: degrees per second

Sets the maximum rotational rate that the burst can sweep. A value of 0 means unlimited. For example, if the burst origin radius is large and the burst duration is short, the return burst will cover a large area in a short amount of time unless limited by this angular velocity.

special damage modifier float
  • Min: 0
  • Max: 1

A damage modifier for special weapon fire (e.g. overcharged shots and secondary triggers), applied in addition to the normal damage modifier. No effect if 0.

special projectile error float

An error angle, applied in addition to normal error, for special fire.

new target burst duration float

Multiplier for burst duration in the new target state. No effect if 0.

new target burst separation float

Multiplier for burst separation in the new target state. No effect if 0.

new target rate of fire float

Multiplier for rate of fire in the new target state. No effect if 0.

new target projectile error float

Multiplier for projectile error in the new target state. No effect if 0.

moving burst duration float

Multiplier for burst duration in the moving state. No effect if 0.

moving burst separation float

Multiplier for burst separation in the moving state. No effect if 0.

moving rate of fire float

Multiplier for rate of fire in the moving state. No effect if 0.

moving projectile error float

Multiplier for projectile error in the moving state. No effect if 0.

berserk burst duration float

Multiplier for burst duration in the berserk state. No effect if 0.

berserk burst separation float

Multiplier for burst separation in the berserk state. No effect if 0.

berserk rate of fire float

Multiplier for rate of fire in the berserk state. No effect if 0.

berserk projectile error float

Multiplier for projectile error in the berserk state. No effect if 0.

super ballistic range float
bombardment range float

When non-zero, causes the burst target to be offset by a random distance in this range when the enemy is not visible.

modified vision range float

Overrides the actor's vision range. Normal if 0.

special fire mode enum

If set, allows the actor to use their weapon in alternate ways.

Option Value Comments
none 0x0

No special fire will be used.

overcharge 0x1

The actor will hold down the primary trigger for an overcharged shot. Jackals use this with the plasma pistol.

secondary trigger 0x2

The actor will fire the weapon's secondary trigger.

special fire situation enum

Determines the situation in which the actor has a chance of using special fire.

Option Value Comments
never 0x0

The actor will never special fire their weapon.

enemy visible 0x1

Special fire happens only when the target is visible.

enemy out of sight 0x2

Special fire happens only when the target is behind cover.

strafing 0x3
special fire chance float
  • Min: 0
  • Max: 1

How likely the actor will use their weapon's special fire mode. Setting this to 0 is equivalent to using the never situation.

special fire delay float
  • Unit: seconds

How long the actor must wait between uses of special fire mode.

melee range float
  • Unit: world units

Sets how close an enemy must get to trigger a melee charge by the actor.

melee abort range float
  • Unit: world units

The actor will stop trying to melee the enemy goes outside this range.

berserk firing ranges Bounds?
  • Unit: world units

When berserking and outside the maximum range, the actor will advance towards the target and stop at the minimum range.

berserk melee range float
  • Unit: world units

Similar to melee range, but used when the actor is berserking.

berserk melee abort range float
  • Unit: world units

Similar to melee abort range, but used when the actor is berserking.

grenade type enum

Sets which type of grenade the actor throws, assuming grenade stimulus is not never.

Option Value Comments
human fragmentation 0x0
covenant plasma 0x1
trajectory type enum
Option Value Comments
toss 0x0
lob 0x1
bounce 0x2
grenade stimulus enum

What causes the actor to consider throwing a grenade. It is still dependent upon grenade chance.

Option Value Comments
never 0x0

The actor never throws grenades.

visible target 0x1
seek cover 0x2
minimum enemy count uint16

How many enemies must be within the grenade's radius before the actor considers throwing there.

enemy radius float
  • Unit: world units

Only enemies within this radius of the actor are considered when choosing where to throw a grenade.

grenade velocity float
  • Unit: world units per second

This is responsibile for giving the grenade it's thrown velocity, rather than the projectile initial velocity or the unit grenade velocity.

grenade ranges Bounds?
  • Unit: world units

The minimum and maximum ranges that the actor will consider throwing a grenade.

collateral damage radius float
  • Unit: world units

If there are friendlies within this radius of the target, grenades will not be thrown.

grenade chance float
  • Min: 0
  • Max: 1

How likely the actor is to throw a grenade when a grenade stimulus applies.

grenade check time float
  • Unit: seconds

How often to consider throwing a grenade while a continuous grenade stimulus, like visible target, applies.

encounter grenade timeout float
  • Unit: seconds

The AI will not throw a grenade if another AI in the encounter threw one within this timeout. This prevents AI from all throwing grenades at the same time.

equipment

TagDependency: equipment

References equipment that the actor will drop on death. Note that their weapon will already be dropped and does not need to be repeated here.

grenade count Bounds

Determines how many grenades the actor spawns with, with the type determined by the grenade type field. The actor will use up these grenades unless has unlimited grenades is true. On death, the grenades are dropped.

Field Type Comments
min uint16
max uint16
don't drop grenades chance float
  • Min: 0
  • Max: 1

The chance that the actor drops no grenades on death, even if they have some.

drop weapon loaded Bounds?
  • Unit: fractions of a clip
  • Min: 0
  • Max: 1

A random range for how loaded the dropped weapon is, as a fraction of its magazine size or charge. Plasma weapons are dropped at 100% charge no matter this field's value under special circumstances: * If a model region was destroyed and that region's forces drop weapon flag is enabled, such as shooting the arm off a Flood actor. * If the actor has a chance of feigning death and reviving, but not if the damage exceeds the hard death threshold. ---

drop weapon ammo Bounds?
  • Unit: rounds

The total number of reserve ammo rounds included with the dropped weapon. Ignored for energy weapons.

body vitality float

Overrides the biped's collision geometry maximum body vitality for a different amount of health.

shield vitality float

Overrides the biped's collision geometry maximum shield vitality for a different amount of shields.

shield sapping radius float
  • Unit: world units
forced shader permutation uint16

If non-zero, forces the bitmap index for any shader the biped uses. For example, the Elite major uses the value 1 which forces its shaders to use the second (red) cubemap in characters\elite\bitmaps\cubemaps.bitmap. Bitmap tags which do not have a bitmap for this index will instead use the first map (index 0).

change colors Block
  • HEK max count: 4

Overrides the bipeds color change permutations.

Field Type Comments
color lower bound ColorRGB
Field Type Comments
red float
green float
blue float
color upper bound ColorRGB?

Acknowledgements

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

  • Jakey (Providing descriptions for all tag fields, further researching Rosy's discovery)
  • Kavawuvi (Invader tag definitions)
  • MosesOfEgypt (Tag structure research)
  • Rosy (Discovering actors drop 100% charge weapons on no-grenade deaths)