Scripting with sequence files Last edited 5 years ago2019-01-30 21:08:19 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.

Syntax

Blocks

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:

%Opening_Sequence
{
    #firetargets = "start_music"
    #firetargets = "hud"
    #firetargets = "freeze_me"
    @TitleStyle
    #pause = 1
    #firetargets = "start_dark"
}

This is an entry block, the primary type of block. More information about that can be found below.

Comments

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
!sentences
{
    //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
}

Sentences

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`:

!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`:

%Opening_Sequence
{
    #firetargets = "start_music"
    #firetargets = "hud"
    #firetargets = "freeze_me"
    @TitleStyle
    #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, ... ] ]`

#

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:

Command	Purpose
noop	Explicitly does nothing
firetargets	Triggers the entities with the given name
killtargets	Removes the entities with the given name
pause	Pauses execution of all commands to follow by the given time in seconds
setdefaults	Sets the current modifiers as the default values for the remainder of the block
repeat	Indicates whether this block should repeat execution or not. Defaults to 0, a setting of -1 will repeat infinitely
sound	Specifies a sound or sentence to play
sentence	Never used
gosub	Obsolete, replaced by macros
modifier	Not used directly
postmodifier	Not used directly
text	Sets the text to display on the HUD. This can be a localized string (starts with #)

$

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:

Modifier	Purpose	Parameters
speaker	Name of the NPC that should speak a sentence	1 targetname
listener	Name of the entity that the speaker should speak to	1 targetname

These modifiers are based off of the game_text entity, and the values found in the FGD for it should be used here:

Modifier	Purpose	Parameters
effect	Sets the effect type	Integer value
position	Position on screen, as normalized coordinates in the range [ 0, 1 ], or -1 for center	2 float values (x, y)
color	Text color as an RGB value, in the range [ 0, 255 ]	3 integer values
color2	Effect color as an RGB value, in the range [ 0, 255 ]	3 integer values
fadein	Fade in time, in seconds	1 float value
fadeout	Fade out time, in seconds	1 float value
holdtime	Text hold time, in seconds	1 float value
fxtime	Effect hold time, in seconds	1 float value
channel	Channel to display on	1 integer value

@

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:
@TitleStyle

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.