Tutorial: Scripting with sequence files Last edited 2 years ago2021-08-11 23:53:53 UTC

With the release of Condition Zero Deleted Scenes the engine now has support for sequence files. This is a simple scripting language that allows some game events to be scripted and triggered using the trigger_sequence entity.



Sequence file syntax revolves around blocks. A block is a list of commands to execute, or a list of sentence groups. Each block has a name that is used to refer to the commands from other blocks or map entities.

Block syntax depends slightly on the type of block, but it generally looks like this:
    #firetargets = "start_music"
    #firetargets = "hud"
    #firetargets = "freeze_me"
    #pause = 1
    #firetargets = "start_dark"
This is an entry block, the primary type of block. More information about that can be found below.


There are two comment styles supported, single line and multi-line comments.

Single line comments start with a // and last until the end of the line.

Multi-line comments start with a /* and last until the first */. Any text after a */ will be treated as regular commands.
//This is a single line comment
    //This is an example of a multiline comment. It can also be used to comment out parts of commands
    Training_Rec_talk0 /*cz_training/rec_theyarew*/ cz_training/rec_latest


Sentence blocks allow you to define sentence groups that can be referenced much like sentences in sentences.txt, only without the overall limit of 500 sentences. There is no defined limit to how many sentences can be defined using a sentence block, and these are available in addition to sentences in sentences.txt.

To define a sentence block, start a block with !sentences:
    Training_Rec_talk0 cz_training/rec_theyarew
    Training_Rec_talk1 cz_training/rec_latest
    Training_Rec_talk2 cz_training/rec_elepast
This defines a sentence group named Training_Rec_talk with 3 sentences that are randomly selected whenever this sentence is played.

Multiple sentence blocks can be present in the same sequence file, but it is recommended to use a single block, typically at the beginning of the file to keep things organized.

Entry blocks

This is the primary type of block, used to define lists of commands to execute.

An entry block starts with a % followed by the name of the block, used to refer to it from a trigger_sequence:
    #firetargets = "start_music"
    #firetargets = "hud"
    #firetargets = "freeze_me"
    #pause = 1
    #firetargets = "start_dark"
This defines an entry that triggers the entities with a targetname of start_music, hud and freeze_me, then applies the commands defined in the entry block TitleStyle, waits a second and then triggers start_dark.

Command types

There are a few different types of commands, all sharing the same syntax for usage:
<symbol><Command name> [ = arg1 [, arg2, ... ] ]

# command

A command starting with # is a regular command and will be interpreted directly.

Commands are used like this: #firetargets = "start_dark"

The following are commands that can be used:
noopExplicitly does nothing
firetargetsTriggers the entities with the given name
killtargetsRemoves the entities with the given name
pausePauses execution of all commands to follow by the given time in seconds
setdefaultsSets the current modifiers as the default values for the remainder of the block
repeatIndicates whether this block should repeat execution or not. Defaults to 0, a setting of -1 will repeat infinitely
soundSpecifies a sound or sentence to play
sentenceNever used
gosubObsolete, replaced by macros
modifierNot used directly
postmodifierNot used directly
textSets the text to display on the HUD. This can be a localized string (starts with #)

$ command

A command starting with '$' is a modifier. Unlike a # command modifiers will affect all commands that follow, until the modifier is changed.

Modifiers are used like this: $speaker = "my_npc"

The following modifiers can be used:
speakerName of the NPC that should speak a sentence1 targetname
listenerName of the entity that the speaker should speak to1 targetname
These modifiers are based off of the game_text entity, and the values found in the FGD for it should be used here:
effectSets the effect typeInteger value
positionPosition on screen, as normalized coordinates in the range [ 0, 1 ], or -1 for center2 float values (x, y)
colorText color as an RGB value, in the range [ 0, 255 ]3 integer values
color2Effect color as an RGB value, in the range [ 0, 255 ]3 integer values
fadeinFade in time, in seconds1 float value
fadeoutFade out time, in seconds1 float value
holdtimeText hold time, in seconds1 float value
fxtimeEffect hold time, in seconds1 float value
channelChannel to display on1 integer value

@ command

A command starting with @ is a macro expansion, also referred to as a "gosub" by error messages.

A macro expansion allows one entry block to be applied to another, effectively allowing you to group commands together and reuse them.

Since macro expansions reference entry blocks defining a macro to reuse is the same as defining an entry block.

Using a macro is straightforward:

This will expand the contents of the TitleStyle entry block at the current position in the current entry block.

Writing sequence files for your maps

Sequence files are automatically loaded by the engine based on the map name. The sequence file should be placed in <gamedir>/sequences and have the extension .seq to be loaded correctly.

The sequence file global.seq is automatically loaded and all its contents shared with all sequence files, making it easy to share common definitions.


You must log in to post a comment. You can login or register a new account.