scenario

🚧 This incomplete article needs help! Please submit tips and info by pull requests or issues or contacting a maintainer.

Scenarios are the main "root" tag representing a playable level. It is essential for defining all gameplay elements such as AI encounters, item spawns, multiplayer flags, scenery locations, and other objects. It may reference one or multiple scenario_structure_bsp. Level scripts, cinematics, and trigger volumes are also defined in this tag.

A scenarios can be compiled with its dependencies into a map. Though Tool will also will include globals, tag collections, and some UI tags automatically, the majority of a map's tags are direct or indirect dependencies of the scenario.

Child scenarios

It is known that Bungie did not originally author singleplayer scenarios as a single tag, but used child scenarios to break them up into multiple tags. Child scenarios are other scenario tags referenced by a parent scenario. During map compilation, Tool merges child scenarios together.

It is impossible to recreate child scenarios though tag extraction tools like Refinery and invader-extract, which can only extract the single merged scenario. This can result in issues:

  • For c10's scenario, Sapien's limits are exceeded and a garbage collection message is spammed in the console
  • Camera points, cutscene flags, and recorded animations may be duplicated if the extraction tool did not deduplicate them. This will prevent scripts from compiling. When extracting with Refinery, use the "Rename duplicate camera points, ..." option to avoid this problem.

Encounters

...

Structure and fields

Field Type Comments
don't use

TagDependency: scenario_structure_bsp

  • Unused
won't use

TagDependency: scenario_structure_bsp

  • Unused
can't use

TagDependency: sky

  • Unused
skies Block
  • HEK max count: 8
Field Type Comments
sky

TagDependency: sky

A reference to a sky tag which can be used by a BSP in this scenario.

type enum

Determines the type of map this scenario represents. This also causes map compilers like Tool and invader to apply certain hardcoded tag patches.

Option Value Comments
singleplayer 0x0

The map is meant to be used for singleplayer and loaded with the map_name command. Cannot be played in multiplayer.

multiplayer 0x1

The map is meant for multiplayer and can be loaded with sv_map.

user interface 0x2

The map is meant to serve as ui.map for the game's main menu.

flags bitfield
Flag Mask Comments
cortana hack 0x1
use demo ui 0x2
child scenarios Block
  • HEK max count: 16
Field Type Comments
child scenario

TagDependency: scenario

This scenario tag will be merged into the main scenario tag (and dereferenced) on map build.

local north float
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
functions Block
  • HEK max count: 32
Field Type Comments
flags bitfield
Flag Mask Comments
scripted 0x1
invert 0x2
additive 0x4
always active 0x8
name TagString
Field Type Comments
buffer char[32]
period float
  • Unit: seconds
scale period by enum
Option Value Comments
none 0x0
a in 0x1
b in 0x2
c in 0x3
d in 0x4
a out 0x5
b out 0x6
c out 0x7
d out 0x8
function enum
Option Value Comments
one 0x0
zero 0x1
cosine 0x2
cosine variable period 0x3
diagonal wave 0x4
diagonal wave variable period 0x5
slide 0x6
slide variable period 0x7
noise 0x8
jitter 0x9
wander 0xA
spark 0xB
scale function by enum?
wobble function enum?
wobble period float
  • Unit: seconds
wobble magnitude float
  • Unit: percent
square wave threshold float
step count uint16
map to enum
Option Value Comments
linear 0x0
early 0x1
very early 0x2
late 0x3
very late 0x4
cosine 0x5
sawtooth count uint16
scale result by enum?
bounds mode enum
Option Value Comments
clip 0x0
clip and normalize 0x1
scale to fit 0x2
bounds Bounds
Field Type Comments
min float
max float
turn off with enum?
editor scenario data TagDataOffset
Field Type Comments
size uint32
external uint32
file offset uint32
pointer ptr64
comments Block
  • HEK max count: 1024
Field Type Comments
position Point3D
Field Type Comments
x float
y float
z float
comment TagDataOffset?
object names Block
  • HEK max count: 512
  • Max: 65534
  • Read-only

Contains the names of all named objects in the scenario. These names are referenced by index for each type of placed object if that object is named. The console command debug_objects_names can display these.

Field Type Comments
name TagString?
object type enum
  • Cache only
Option Value Comments
biped 0x0
vehicle 0x1
weapon 0x2
equipment 0x3
garbage 0x4
projectile 0x5
scenery 0x6
device machine 0x7
device control 0x8
device light fixture 0x9
placeholder 0xA
sound scenery 0xB
object index uint16
  • Cache only
scenery Block
  • HEK max count: 2000
  • Max: 65535
Field Type Comments
type uint16
name uint16
not placed bitfield
Flag Mask Comments
automatically 0x1
on easy 0x2
on normal 0x4
on hard 0x8
desired permutation uint16
position Point3D?
rotation Euler3D
Field Type Comments
yaw float
pitch float
roll float
bsp indices uint16
  • Cache only

unused in Halo PC; bitmask

scenery palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: scenery

  • Non-null
bipeds Block
  • HEK max count: 128
  • Max: 65535

Special-purpose bipeds placed in the map, typically used for scripted characters and cutscenes. AI should instead be spawned using encounters, since the actors will be properly difficulty-scaled. Although there is technically a very high limit to this block, unmodified Sapien only supports up to 128 bipeds being placed.

Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
body vitality modifier float
  • Min: 0
flags bitfield
Flag Mask Comments
dead 0x1
biped palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: biped

  • Non-null
vehicles Block
  • HEK max count: 80
  • Max: 65535
Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
body vitality float
  • Min: 0
  • Max: 1
flags bitfield?
multiplayer team index int8

Determines which team the vehicle belongs to for gametype settings. Index 0 is for red team, and index 1 is blue.

multiplayer spawn flags bitfield
Flag Mask Comments
slayer default 0x1

The vehicle will spawn in Slayer when the gametype specifies default vehicle settings.

ctf default 0x2

The vehicle will spawn in CTF when the gametype specifies default vehicle settings.

king default 0x4

The vehicle will spawn in King of the Hill when the gametype specifies default vehicle settings.

oddball default 0x8

The vehicle will spawn in Oddball when the gametype specifies default vehicle settings.

unused 0x10
unused1 0x20
unused2 0x40
unused3 0x80
slayer allowed 0x100

The vehicle spawn is permitted in Slayer when the gametype is using custom vehicle settings.

ctf allowed 0x200

The vehicle spawn is permitted in CTF when the gametype is using custom vehicle settings.

king allowed 0x400

The vehicle spawn is permitted in King of the Hill when the gametype is using custom vehicle settings.

oddball allowed 0x800

The vehicle spawn is permitted in Oddball when the gametype is using custom vehicle settings.

unused4 0x1000
unused5 0x2000
unused6 0x4000
unused7 0x8000
vehicle palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: vehicle

  • Non-null
equipment Block
  • HEK max count: 256
  • Max: 65535
Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
flags bitfield
Flag Mask Comments
initially at rest 0x1
obsolete 0x2
does accelerate 0x4
equipment palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: equipment

  • Non-null
weapons Block
  • HEK max count: 128
  • Max: 65535

Weapon placements for singeplayer. Multiplayer weapon spawns should be placed using netgame equipment instead.

Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
rounds reserved uint16

does not include loaded rounds; cannot go above maximum rounds

rounds loaded uint16
flags bitfield?
weapon palette Block
  • HEK max count: 100
  • Max: 65534

The types of weapons that can be placed throughout a singeplayer scenario.

Field Type Comments
name

TagDependency: weapon

  • Non-null
device groups Block
  • HEK max count: 128
  • Max: 65534
Field Type Comments
name TagString?
  • Non-null
initial value float
  • Min: 0
  • Max: 1
flags bitfield
Flag Mask Comments
can change only once 0x1
machines Block
  • HEK max count: 400
  • Max: 65535
Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
power group uint16
position group uint16
device flags bitfield
Flag Mask Comments
initially open 0x1
initially off 0x2
can change only once 0x4
position reversed 0x8
not usable from any side 0x10
machine flags bitfield
Flag Mask Comments
does not operate automatically 0x1
one sided 0x2
never appears locked 0x4
opened by melee attack 0x8
machine palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: device_machine

  • Non-null
controls Block
  • HEK max count: 100
  • Max: 65535
Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
power group uint16
position group uint16
device flags bitfield?
control flags bitfield
Flag Mask Comments
usable from both sides 0x1
no name int16
control palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: device_control

  • Non-null
light fixtures Block
  • HEK max count: 500
  • Max: 65535
Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
bsp indices uint16
  • Cache only

unused in Halo PC; bitmask

power group uint16
position group uint16
device flags bitfield?
color ColorRGB
Field Type Comments
red float
green float
blue float
intensity float
falloff angle float
cutoff angle float
light fixture palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: device_light_fixture

  • Non-null
sound scenery Block
  • HEK max count: 256
  • Max: 65535
Field Type Comments
type uint16
name uint16
not placed bitfield?
desired permutation uint16
position Point3D?
rotation Euler3D?
sound scenery palette Block
  • HEK max count: 100
  • Max: 65534
Field Type Comments
name

TagDependency: sound_scenery

  • Non-null
player starting profile Block
  • HEK max count: 256
Field Type Comments
name TagString?
starting health modifier float
  • Min: 0
  • Max: 1
starting shield modifier float
  • Min: 0
  • Max: 3
primary weapon

TagDependency: weapon

primary rounds loaded uint16
primary rounds reserved uint16

does not include loaded ammo; can go above maximum rounds

secondary weapon

TagDependency: weapon

secondary rounds loaded uint16
secondary rounds reserved uint16

does not include loaded ammo; can go above maximum rounds

starting fragmentation grenade count int8
starting plasma grenade count int8
starting unknown grenade count 1 int8
starting unknown grenade count 2 int8
player starting locations Block
  • HEK max count: 256
Field Type Comments
position Point3D?
facing float
team index uint16
bsp index uint16
type 0 enum
Option Value Comments
none 0x0
ctf 0x1
slayer 0x2
oddball 0x3
king of the hill 0x4
race 0x5
terminator 0x6
stub 0x7
ignored1 0x8
ignored2 0x9
ignored3 0xA
ignored4 0xB
all games 0xC
all except ctf 0xD
all except race ctf 0xE
type 1 enum?
type 2 enum?
type 3 enum?
trigger volumes Block
  • HEK max count: 256
  • Max: 65534

Cuboid volumes which can be used in scripts to test for the presence an object: (volume_test_object "volume_name" <object>). An example use case is kill volumes.

Field Type Comments
unknown uint16
name TagString?

The name of the volume which can be used in scripts.

float 1 float
float 2 float
float 3 float
float 4 float
float 5 float
float 6 float
float 7 float
float 8 float
float 9 float
starting corner Point3D?

The 3D world-unit coordinates of one corner of the volume.

ending corner offset Point3D?

The offset distances from the starting corner to the opposite corner.

recorded animations Block
  • HEK max count: 1024
Field Type Comments
name TagString?
version int8
raw animation data int8
unit control data version int8
length of animation uint16
recorded animation event stream TagDataOffset?
netgame flags Block
  • HEK max count: 200

Multiplayer game mode markers like flag locations, oddball spawns, and teleporters.

Field Type Comments
position Point3D?

The location in 3D space of this netgame flag.

facing float

The direction that the netgame flag faces (yaw). How this is used depends on the type of the flag.

type enum

Determines which purpose this netgame flag serves.

Option Value Comments
ctf flag 0x0

Two netgame flags should be placed for the CTF flags, with red team's flag using team index 0, and blue team 1. The facing value is not used to orient the flag pole (the skull faces in the world's +X direction). Be careful not to place the CTF flags on the wrong side of the map or it may prevent players from spawning.

ctf vehicle 0x1

Unused.

oddball ball spawn 0x2

Halo's oddball gamemode settings allow up to 16 simultaneous oddballs, so maps should include 16 unique oddball spawns. The oddball will spawn facing the world +X direction regardless of the facing field. Use team index 0 for the first oddball spawn, which should be in a team-neutral location of the map. Increment the team index for each subsequent oddball spawn (up to index 15). Halo will spawn balls at each flag in order of their index, so ensure flags are alternated across the map to prevent an unfair advantage to a team already occupying an area.

race track 0x3

Determines the checkpoints for race game modes. The game supports up to 32 race track points. The team index should be numbered sequentially without gaps, starting at 0 in a team-neutral location. In Rally mode, checkpoints will be selected in random order.

race vehicle 0x4

Used by Halo to spawn vehicles near players at the start of Race games, so you should place up to 16 of them near player spawn points used for Race. Team index is not used. The green marker handle should be pointed in the direction the vehicle will face forward.

vegas bank 0x5

Unused.

teleport from 0x6

Teleporter entry node. Team index determines the "channel" and links entry and exit nodes together.

teleport to 0x7

Teleporter exit node. Team index determines the "channel" and links entry and exit nodes together. The difference in facing direction (yaw) between the entry and exit nodes is added to the player's yaw to determine their facing direction on exit. For example, if the entry node's facing is -90 degrees and the exit's is 0 degrees (a difference of +90 degrees), then a player entering the teleporter facing North would exit facing East.

hill flag 0x8

Defines the boundaries of a King mode hill. Each hill should be placed as a series of 3-8 hill flags with the same team index, with index 0 being the default for non-moving hill mode. At least two hills should be placed to support moving hill mode. The facing field is not used.

team index uint16

The meaning of this field depends on the netgame flag type, and is not necessarily about teams. See the above type descriptions for more details on usage.

weapon group

TagDependency: item_collection

Unused.

netgame equipment Block
  • HEK max count: 200
  • Processed during compile
Field Type Comments
flags bitfield
Flag Mask Comments
levitate 0x1
type 0 enum?
type 1 enum?
type 2 enum?
type 3 enum?
team index uint16
spawn time uint16
  • Unit: seconds

0 = use default spawn time in item_collection

unknown ffffffff uint32
  • Cache only: true

always 0xFFFFFFFF?

position Point3D?
facing float
item collection

TagDependency: item_collection

starting equipment Block
  • HEK max count: 200
Field Type Comments
flags bitfield
Flag Mask Comments
no grenades 0x1
plasma grenades 0x2
type 0 enum?
type 1 enum?
type 2 enum?
type 3 enum?
item collection 1

TagDependency: item_collection

item collection 2

TagDependency: item_collection

item collection 3

TagDependency: item_collection

item collection 4

TagDependency: item_collection

item collection 5

TagDependency: item_collection

item collection 6

TagDependency: item_collection

bsp switch trigger volumes Block
  • HEK max count: 256
  • Cache only
Field Type Comments
trigger volume uint16
source uint16
destination uint16
unknown uint16
decals Block
  • HEK max count: 65536
Field Type Comments
decal type uint16
yaw int8
pitch int8
position Point3D?
decal palette Block
  • HEK max count: 128
Field Type Comments
reference

TagDependency: decal

detail object collection palette Block
  • HEK max count: 32
Field Type Comments
reference

TagDependency: detail_object_collection

actor palette Block
  • HEK max count: 64
Field Type Comments
reference

TagDependency: actor_variant

encounters Block
  • HEK max count: 128
Field Type Comments
name TagString?
flags bitfield
Flag Mask Comments
not initially created 0x1
respawn enabled 0x2
initially blind 0x4
initially deaf 0x8
initially braindead 0x10
3d firing positions 0x20
manual bsp index specified 0x40
team index enum
Option Value Comments
default by unit 0x0
player 0x1
human 0x2
covenant 0x3
flood 0x4
sentinel 0x5
unused6 0x6
unused7 0x7
unused8 0x8
unused9 0x9
one int16
  • Cache only
search behavior enum
Option Value Comments
normal 0x0
never 0x1
tenacious 0x2
manual bsp index uint16
respawn delay Bounds?
  • Unit: seconds
precomputed bsp index uint16
  • Cache only
squads Block
  • HEK max count: 64
Field Type Comments
name TagString?
actor type uint16
platoon uint16
Tinitial state enum
Option Value Comments
none 0x0
sleeping 0x1
alert 0x2
moving repeat same position 0x3
moving loop 0x4
moving loop back and forth 0x5
moving loop randomly 0x6
moving randomly 0x7
guarding 0x8
guarding at guard position 0x9
searching 0xA
fleeing 0xB
Treturn state enum?
flags bitfield
Flag Mask Comments
unused 0x1
never search 0x2
start timer immediately 0x4
no timer delay forever 0x8
magic sight after timer 0x10
automatic migration 0x20
unique leader type enum
Option Value Comments
normal 0x0
none 0x1
random 0x2
sgt johnson 0x3
sgt lehto 0x4
maneuver to squad uint16
squad delay time float
attacking bitfield
Flag Mask Comments
a 0x1
b 0x2
c 0x4
d 0x8
e 0x10
f 0x20
g 0x40
h 0x80
i 0x100
j 0x200
k 0x400
l 0x800
m 0x1000
n 0x2000
o 0x4000
p 0x8000
q 0x10000
r 0x20000
s 0x40000
t 0x80000
u 0x100000
v 0x200000
w 0x400000
x 0x800000
y 0x1000000
z 0x2000000
attacking search bitfield?
attacking guard bitfield?
defending bitfield?
defending search bitfield?
defending guard bitfield?
pursuing bitfield?
normal diff count uint16
insane diff count uint16
major upgrade enum
Option Value Comments
normal 0x0
few 0x1
many 0x2
none 0x3
all 0x4
respawn min actors uint16
respawn max actors uint16
respawn total uint16
respawn delay Bounds?
  • Unit: seconds
move positions Block
  • HEK max count: 64
Field Type Comments
position Point3D?
facing float
weight float
time Bounds?
  • Unit: seconds
animation uint16
sequence id int8
cluster index uint16
  • Cache only
surface index uint32
  • Cache only
starting locations Block
  • HEK max count: 32
Field Type Comments
position Point3D?
facing float
cluster index uint16
  • Cache only
sequence id int8
flags bitfield
Flag Mask Comments
required 0x1
return state enum?
initial state enum?
actor type uint16
command list uint16
platoons Block
  • HEK max count: 32
Field Type Comments
name TagString?
flags bitfield
Flag Mask Comments
flee when maneuvering 0x1
say advancing when maneuver 0x2
start in defending state 0x4
change attacking defending state when enum
Option Value Comments
never 0x0
75 strength 0x1
50 strength 0x2
25 strength 0x3
anybody dead 0x4
25 dead 0x5
50 dead 0x6
75 dead 0x7
all but one dead 0x8
all dead 0x9
happens to uint16
maneuver when enum?
happens to 1 uint16
firing positions Block
  • HEK max count: 512
  • Processed during compile
Field Type Comments
position Point3D?
group index enum
Option Value Comments
a 0x0
b 0x1
c 0x2
d 0x3
e 0x4
f 0x5
g 0x6
h 0x7
i 0x8
j 0x9
k 0xA
l 0xB
m 0xC
n 0xD
o 0xE
p 0xF
q 0x10
r 0x11
s 0x12
t 0x13
u 0x14
v 0x15
w 0x16
x 0x17
y 0x18
z 0x19
cluster index uint16
  • Cache only
surface index uint32
  • Cache only
player starting locations Block?
  • HEK max count: 256
command lists Block
  • HEK max count: 256
Field Type Comments
name TagString?
flags bitfield
Flag Mask Comments
allow initiative 0x1
allow targeting 0x2
disable looking 0x4
disable communication 0x8
disable falling damage 0x10
manual bsp index 0x20
manual bsp index uint16
precomputed bsp index uint16
  • Cache only
commands Block
  • HEK max count: 64
  • Max: 65534
Field Type Comments
atom type enum
Option Value Comments
pause 0x0
go to 0x1
go to and face 0x2
move in direction 0x3
look 0x4
animation mode 0x5
crouch 0x6
shoot 0x7
grenade 0x8
vehicle 0x9
running jump 0xA
targeted jump 0xB
script 0xC
animate 0xD
recording 0xE
action 0xF
vocalize 0x10
targeting 0x11
initiative 0x12
wait 0x13
loop 0x14
die 0x15
move immediate 0x16
look random 0x17
look player 0x18
look object 0x19
set radius 0x1A
teleport 0x1B
atom modifier int16
parameter1 float
parameter2 float
point 1 uint16
point 2 uint16
animation uint16
script uint16
recording uint16
command uint16
object name uint16
points Block
  • HEK max count: 64
  • Max: 65534
Field Type Comments
position Point3D?
surface index uint32
  • Cache only
ai animation references Block
  • HEK max count: 128
Field Type Comments
animation name TagString?
animation graph

TagDependency: model_animations

ai script references Block
  • HEK max count: 128
Field Type Comments
script name TagString?
ai recording references Block
  • HEK max count: 128
Field Type Comments
recording name TagString?
ai conversations Block
  • HEK max count: 128
Field Type Comments
name TagString?
flags bitfield
Flag Mask Comments
stop if death 0x1
stop if damaged 0x2
stop if visible enemy 0x4
stop if alerted to enemy 0x8
player must be visible 0x10
stop other actions 0x20
keep trying to play 0x40
player must be looking 0x80
trigger distance float
  • Unit: seconds
run to player dist float
  • Unit: seconds
participants Block
  • HEK max count: 8
Field Type Comments
flags bitfield
Flag Mask Comments
optional 0x1
has alternate 0x2
is alternate 0x4
selection type enum
Option Value Comments
friendly actor 0x0
disembodied 0x1
in player s vehicle 0x2
not in a vehicle 0x3
prefer sergeant 0x4
any actor 0x5
radio unit 0x6
radio sergeant 0x7
actor type enum
Option Value Comments
elite 0x0
jackal 0x1
grunt 0x2
hunter 0x3
engineer 0x4
assassin 0x5
player 0x6
marine 0x7
crew 0x8
combat form 0x9
infection form 0xA
carrier form 0xB
monitor 0xC
sentinel 0xD
none 0xE
mounted weapon 0xF
use this object uint16
set new name uint16
variant numbers uint16[6]
  • Cache only

Determines which kind of variant gets a given line. By default, this matches by tag path (bisenti = 2, fitzgerald/jenkins = 4, aussie = 5, mendoza = 6, sarge/johnson = 100, sarge2/lehto = 101, everything else = 0, null = 65535)

encounter name TagString?
encounter index uint32
  • Cache only
lines Block
  • HEK max count: 32
Field Type Comments
flags bitfield
Flag Mask Comments
addressee look at speaker 0x1
everyone look at speaker 0x2
everyone look at addressee 0x4
wait after until told to advance 0x8
wait until speaker nearby 0x10
wait until everyone nearby 0x20
participant uint16
addressee enum
Option Value Comments
none 0x0
player 0x1
participant 0x2
addressee participant uint16
line delay time float
variant 1

TagDependency: sound

variant 2

TagDependency: sound

variant 3

TagDependency: sound

variant 4

TagDependency: sound

variant 5

TagDependency: sound

variant 6

TagDependency: sound

script syntax data TagDataOffset?
script string data TagDataOffset?
scripts Block
  • HEK max count: 512
  • Read-only
  • Read-only
Field Type Comments
name TagString?
script type enum
Option Value Comments
startup 0x0
dormant 0x1
continuous 0x2
static 0x3
stub 0x4
return type enum
Option Value Comments
unparsed 0x0
special form 0x1
function name 0x2
passthrough 0x3
void 0x4
boolean 0x5
real 0x6
short 0x7
long 0x8
string 0x9
script 0xA
trigger volume 0xB
cutscene flag 0xC
cutscene camera point 0xD
cutscene title 0xE
cutscene recording 0xF
device group 0x10
ai 0x11
ai command list 0x12
starting profile 0x13
conversation 0x14
navpoint 0x15
hud message 0x16
object list 0x17
sound 0x18
effect 0x19
damage 0x1A
looping sound 0x1B
animation graph 0x1C
actor variant 0x1D
damage effect 0x1E
object definition 0x1F
game difficulty 0x20
team 0x21
ai default state 0x22
actor type 0x23
hud corner 0x24
object 0x25
unit 0x26
vehicle 0x27
weapon 0x28
device 0x29
scenery 0x2A
object name 0x2B
unit name 0x2C
vehicle name 0x2D
weapon name 0x2E
device name 0x2F
scenery name 0x30
root expression index int32
globals Block
  • HEK max count: 128
  • Read-only
  • Read-only
Field Type Comments
name TagString?
type enum?
initialization expression index int32
references Block
  • HEK max count: 256
  • Read-only
  • Read-only
Field Type Comments
reference

TagDependency: (any)

source files Block
  • HEK max count: 8
  • Non-cached
  • Volatile
  • Read-only
  • Read-only
Field Type Comments
name TagString?
source TagDataOffset?
cutscene flags Block
  • HEK max count: 512
Field Type Comments
unknown uint32
  • Cache only
name TagString?
position Point3D?
facing Euler2D
Field Type Comments
yaw float
pitch float
cutscene camera points Block
  • HEK max count: 512
Field Type Comments
unknown uint32
  • Cache only
name TagString?
position Point3D?
orientation Euler3D?
field of view float
cutscene titles Block
  • HEK max count: 64
  • Processed during compile
Field Type Comments
unknown uint32
  • Cache only
name TagString?
text bounds Rectangle2D
Field Type Comments
top int16
left int16
bottom int16
right int16
string index uint16
text style enum
Option Value Comments
plain 0x0
bold 0x1
italic 0x2
condense 0x3
underline 0x4
justification enum
Option Value Comments
left 0x0
right 0x1
center 0x2
text color ColorARGBInt

RGB Color with alpha, with 8-bit color depth per channel (0-255)

Field Type Comments
alpha uint8
red uint8
green uint8
blue uint8
shadow color ColorARGBInt?
fade in time float
up time float
fade out time float
custom object names

TagDependency: unicode_string_list

ingame help text

TagDependency: unicode_string_list

hud messages

TagDependency: hud_message_text

structure bsps Block
  • HEK max count: 32
  • Max: 16

The list of BSPs belonging to this scenario that can be switched between. Multiplayer scenarios typically have just one, while singleplayer scenarios often have multiple. This block also contains information used during map loading.

Field Type Comments
bsp start uint32
  • Cache only
bsp size uint32
  • Cache only
bsp address uint32
  • Cache only
structure bsp

TagDependency: scenario_structure_bsp

Acknowledgements

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

  • Jakey (Sharing knowledge on child scenarios)
  • Kavawuvi (Invader tag definitions)
  • Masterz1337 (Encounters vs bipeds)
  • MosesOfEgypt (Tag structure research)