DoD Documentation

GSM Entities
The bulk of level scripting in Dawn of Darkness is managed using target_gsm entites. These entities are able to set and check game flags, in turn controlling quest progression, gameplay scripts, and offering a way for these events to interact with the conversation system. Every game flag has a 'main' and 'minor' value associated with it, e.g. '2-34' represents a 'main' flag of '2', and a 'minor' flag of '34'.

The 'target_gsm' key allows any entity to be linked to a target_gsm entity. When the main/minor game flags listed in the GSM entity become true, any specified effects are applied to the linked entities. (These effects can be set through the use of the target_gsm entity's spawn flags, each flag represents a different effect type.)

Contrary to this, when using a target_gsm entity to set main/minor flags (using spawnflags of 0, 64, or 16384), a target_gsm entity should just be targeted using its 'targetname' as a standard entity would be.

Main/minor flags can also be reset or disabled. For information on this refer to the section on Resetting Flags.

When testing levels, GSM flags can be triggered from the console by typing 'gsm [Main] [Minor]' (e.g. 'gsm 2 34'), or be deactivated with 'gsm_reset [Main] [Minor]'. 'gsm_test [Main] [Minor]' can be used to display the state of a GSM flag, while 'gsm_test all' and 'gsm_reset all' can also be entered to see or reset all flags at once.

GSM Entity Spawnflags
Target_gsm entities include a number of spawnflags which change their function depending on which is set. These spawnflags are described in more detail below. (Refer to the official GSM documentation for additional information.)

I am also unsure if setting multiple flags between 1 and 128 on a single GSM entity works. It was done on occasion in official maps (such as the side room door inside dod1_1's temple), but when tested in a user map, only one of these flags ever functions at a time. The same effect can be achieved by either chaining GSMs, or using other entities however.

GSM_Spawn (1) - Triggers or spawns an object. (This was left untouched in the DoD demo, and instead flag 32 is used instead.)
GSM_Free (2) - Destroys an object. (Similar to calling killtarget.)
GSM_Kill (4) - Kills an enemy, npc, or animal. (Plays the death animation, but the character will not emit their death sound.)
GSM_Lock (8) - Re-enables the 'message' key and the locked spawnflag for a door or chest.
GSM_Unlock (16) - Disables the 'message' key and the locked spawnflag for a door or chest.
GSM_Use (32) - Triggers an object, spawns an object or character (such as a npc or trigger), and can relay a moodname or other mood information set in the target_gsm entity to a character. Spawning a character at the same time as setting its moodname from the GSM entity seems to cause the character to not appear at all.
GSM_Use_Set (64) - Tells the GSM entity to set its specified 'main' and 'minor' game flag to true when triggered. A target_gsm with this flag can be connected to most standard entities by giving the GSM a targetname and then targeting it.
GSM_Lock_Set (128) - Captures a players first use action on a door and sets its specified 'main' and 'minor' game flag to true. Connect to a door by giving the GSM a targetname, and the same name to the door as a target_gsm.

GSM_Free_Set (8192) - Tells the GSM entity to set its specified 'main' and 'minor' game flag to true when the linked character is killed. Not used in the DoD demo as this can simply be done with the 'deathtarget' key and a GSM entity with flag 64 instead.
GSM_Release (16384) - Causes a GSM entity to set its specified 'main' and 'minor' game flags to false. A target_gsm with this flag can be connected to most standard entities by giving the GSM a targetname and then targeting it.
GSM_Multiple (32768) - Allows a GSM entity to be activated more than once, as opposed to being single use. (Note, using this flag on a GSM entity that's checking for a game flag as opposed to setting one will cause it to repeatedly activate until that flag has been disabled.)

GSM Entity Chains
An entity/object set up to be affected by multiple target_gsm entites using the same targetname will not work as expected. The way to correct this is by building a 'chain' of target_gsm entities instead. For more complex GSM sequences, one or more trigger_relays might also be used.

E.g. A door has a 'target_gsm' key referring to the first GSM entity. The first GSM entity then has a 'target_gsm' key referring to a second GSM entity. This way the second GSM entity 'passes down' it's specified effect to the first GSM entity which once again passes it onwards to the door. In this case, either GSM entity will correctly execute its specified effect.
[Image: GSM example]

E.g. Expanding on the above, this chain can be extended to have a third GSM entity which passes an effect through both prior GSM entities before reaching door. Sometimes GSM entities can also be passing information in both directions. An example would be a door that intercepts the players first use action to set game flags from a linked GSM entity, and then additional GSM entities that pass effects through this first GSM and on to the door.
[Image: GSM example]

Moodnames
Moodnames in DoD can be used to control a characters state. (E.g. Making a character run to a point, draw their weapon, and attack the player.) Not only can a character have moodnames specified to start with, but a number of additional ways to change moodnames during gameplay are also present.

A character can begin with a set moodname using the 'moodname' key.
A moodname can be specified on another entity (such as a trigger or relay) and will be inherited by any targeted character.
The character can inherit a moodname set on a path_corner, point_flee, point_combat, etc.
A target_gsm entity can set a characters moodname using a spawnflag of 32.
The key 'alert_mood' can be used to change a characters mood when it enters an alerted state.

Other related keys include 'moodtime', 'lastmoodname', and 'lastmoodtime', however they don't seem to be used in the demo apart from a couple instances. I've been unable to discover any effect from these during testing although they are described in the official documentation.

Below is a full moodname list for DoD. Note that some moodnames only work with certain characters. Only the top selection of moods as well as 'Attacking' were used in the demo maps. Refer to the official documentation on AI & moods for more information.

Patrolling - The character will walk around the area with their weapon drawn.
Standing - Commonly used to keep a character in place until activated, the character will turn to face the player if approached.
Running - The character will run with their weapon drawn, usually to a specified point.
Wandering - The character will walk around the area, stopping occasionally.
Guarding - The character won't move outside a radius of its starting area, and will return to its original position once the player is outside of this area. The radius can be changed with the characters 'guard_distance' key.
Dormant - A dormant state, the character won't react until attacked or the mood is changed.
Partying - Partying animation, used for the blacksmith guards in dod2_2.
Fleeing - Flee from the player.
Dead - Collapse and act dead.

Waiting - Unknown. (Causes DoD to crash when the map loads.)
Mission - Causes a character to walk to its 'target'. A 'combattarget' can also be specified which the character will run to when alerted. Unlike patrolling or running, the character will not draw their weapon.
Critical Mission - The same as Mission, but the character runs instead of walking.
Hunting - Similar to wandering.
Talking - Standard animation similar to standing, the character will not turn to face the player if approached.
Attacking - The character will be alerted and will look for a target.
Defending - Similar to wandering.
Retreating - Unknown. (Results in the character standing still while the player can walk through them.)
Searching - The character runs around looking for a target. When a searching enemy spots the player, they will attack.
Working - The character walks until reaching a target, and then enters a working animation. (Only functions with slaves and workers, unsure if fully functional.)

Removing Character Keys
As described in the official documentation, certain keys can also be removed from a character. This was only used once in the DoD demo, with a trigger_relay entity that removes the 'alert_target' key from an enemy. In this case, the trigger_relay has the key of 'alert_target' with a value of '^' specified. When triggered, this removes the alert_target from the enemy set in its 'target' field.

This works for removing the 'combattarget', 'fleetarget', 'datafile', and 'alert_target' keys from a character.

Character Spawnflags
The following spawnflags exist for characters and monsters in Dawn of Darkness.

Ambush (1) - Will not activate or attack if the characters view to the player is blocked. (Ignores sound unless the player is in sight.)
Trigger (2) - Sets the character to be spawned when targeted normally, or through a GSM entity.
Sight (4) - Same as flag 1.
Team_Leader (8) - When a character with this flag set is alerted to the players presence, all other characters on the same team (using the 'team' flag) will also be alerted.
Init_Talk (16) - Causes the specified datafile to be activated the first time the player is within a radius of the character. (As opposed to needing to use action on the character to speak to them.)
Fearless (32) - The character will never enter a fleeing state, this causes friendly characters to stay in place when attacked, and enemy characters to not run away when low on health.
Attack (64) - Makes a monster attack immediately when spawned. (Often used in conjunction with flag 2.)

Interactions
Target_interactions are used for objects or scenes that the player can examine when a simple 'message' key won't do. These usually come in two types, interactions that are triggered as the player enters an area (the default), or interactions that are triggered when the player presses the use key (set with a spawnflag of 2).

Interactions may also use a camera to give the player a different view of the event. This is controlled by adding the 'camtype' key with a value of '2' to the target_interaction entity. The default camera view will be from the target_interaction entity's location and will focus on the player, but the camera direction can also be changed by placing a cam_aim entity and linking it with the target_interactions 'target' key.

Note that if no target is supplied to a target_interaction, an error will display when the interaction is triggered in game. This can be avoided by simply giving the target_interaction a target that does not exist if needed. You may also notice that when a target_interaction with a static camera is triggered, the camera sometimes appears to quickly reorient itself. This issue is present in the DoD demo as well.

Items can be given to an interaction entity with the 'inventory' key. This can be used with the conversation system to allow the player to be able to take a specified item, such as a key, from the interaction.

Books
Books are items that can be picked up by the player which display text found in '..\roarke\texts\books.txt' based on the index number given for the 'book' key. Text specified under 'index:0' will only ever be displayed if it is the first book that the player has picked up, and this index can never be viewed once the player has collected additional books.

All book entries are collected under the same book item in the player's inventory.

Conversations
A core element of Dawn of Darkness is its conversations. These are stored in the '..\roarke\texts\' directory and can interact with target_gsm entities through the use of 'main' and 'minor' flags. Refer to the official conversation documentation for more information on conversation basics.

Conversations are broken down into two main parts, init sections which are used when the conversation first starts, and level sections which are numbered and can be jumped to using 'next'.

Datafile - A text file that contains a conversation for Dawn of Darkness. Referenced from a character or interaction entity in a level.

Init Sections - (Those that start with 'level:0') Are loaded when the conversation begins, when this happens, the last init section where there are no 'i_flags', or the 'i_flags' are true will be displayed. Init sections are limited to one set of i_flags and s_flags (and/or operators may be used) and will always display a text box even if no text is specified. Other than these differences, init sections contain the same elements (listed below) as levels.

Levels - (E.g 'level:1') Numbered sections which can be jumped to using 'next' (sort of like a go-to command).

Init Char - (E.g. 'init_char:player') Determines who is saying the first line, use either 'player', or 'monster'. Anything which is not the player, such as NPCs or interactions, are considered to be a 'monster'.
Sentences - Each line starting with either 'first_char' or 'second_char' is considered a sentence. Sentences contain text to be displayed as part of the conversation.
Init Flags - (E.g. 'i_flags:1-1') Flags that must be true for a sentence to show up, or for a command such as 'event' or 'next' to be triggered. Can also use the # character to do an and/or operation (see below for more on this).
Set Flags - (E.g. 's_flags:1-1') Flags that should be set to true when this part of the conversation takes place, can also use the # character to do an and operation to set multiple flags at once (see below for more on this).
All Flags - (E.g. 'all_flags:true') Used when checking multiple 'i_flags', changes the default or operator to an and operator (see below for more on this).
Item - (E.g. 'item1:item_bread') Defines items that might be given or taken by the player during the conversation (see below for more on this).
Event - (E.g. 'event:quit') The type of event when this part of the conversation is reached (see below for more on this).
Next - (E.g. 'next:1') Effectively a go-to command, this will jump to the specified conversation level.

Basic Structure
DoD's conversation system works on the idea that each level of the conversation has an initiating character, or 'first_char' (either the 'player' or a 'monster') which may followed by a reply from the 'second_char'. The initiating character's text, also called a sentence, may affect the direction of the conversation through the use of the commands including 's_flags', 'event', 'next', and others.

Every sentence belonging to the 'player' within a conversation level will be shown as a list of choices that can be picked from, while every sentence belonging to a 'monster' is treated as a single line of text. In either case, an initiating character's sentences can result in either a reply from the other character, an event, or both.

Each conversation begins with an init section. Generally, init sections contain a greeting or description, serving as an introduction to the character or interaction. If at least one sentence isn't included in the init section, an empty text box will appear when the conversation begins.

level:0
init_char:monster
first_char:`This is an init section.`
event:none
next:1

Each part of the conversation is then broken into levels, usually including either a sentence from the 'player' or the 'monster', and (optionally) a reply from the opposite.

level:1
init_char:monster
first_char:`This is the monster's sentence.`
event:none
next:2

level:2
init_char:player
first_char:`This is the player's sentence.`
second_char:`And this is the monster's reply.`
event:quit

As soon as two or more sentences belonging to the 'player' appear in that same level, they will then be displayed as a list where the player can scroll between the different options. If the initiating character is the 'player', a reply from the 'monster' may be specified for each of these list options, but is not required. 'i_flags', 's_flags', 'all_flags', 'event', and 'next' commands can be given for each option as well, separated using a comma. In this situation, 'i_flags' could also be used to determine which options would be available to or hidden from the player.

level:3
init_char:player
first_char:`This is option 1.`
first_char:`This is option 2.`
second_char:`You chose option 1!`
second_char:`You chose option 2!`
s_flags:0-1,0-2
event:quit,quit

If the initiating character is a 'monster', only one line of text will be shown. A reply from the 'player' may be specified, but this reply is unable to have an affect on the conversation or events. In this situation, 'i_flags' cannot be used.

level:4
init_char:monster
first_char:`This is the monster's sentence.`
second_char:`This is option 1.`
second_char:`This is option 2.`
s_flags:0-1#02
event:quit

Specifying sentences outside of init sections is entirely optional, so you can create a level within a conversation that only exists to activate an event, further the conversation, or change GSM flags. The below is an example that would change conversation levels based on the first flag that evaluates as true (so if both '0-1' and '0-2' are true, '0-1' will be the one to trigger as it comes first in the list). Note that '0-0' with an event of 'quit' was used as a third option. If neither '0-1' or '0-2' is true, this still allows a way to exit the conversation.

level:5
i_flags:0-1,0-2,0-0
next:2,3,0
event:none,none,quit

'0-0' can also be used as a placeholder when checking or setting multiple flags. By default it is always true. Similarly, '0' can be used as a placeholder when using multiple 'next' values, and 'none' when using multiple 'event' values.

level:6
init_char:player
first_char:`This is option 1 and will show up all the time.`
first_char:`This is option 2 and will only show if flag 0-1 is true.`
second_char:`You chose option 1, nothing will happen!`
second_char:`You chose option 2, flag 0-2 will now be set to true and the conversation will advance to level 6!`
i_flags:0-0,0-1
s_flags:0-0,0-2
next:0,6
event:quit,none

See the sections below for more information on additional features of the conversation system. It's also always good to refer to the files in the '..\roarke\texts\' directory for examples of how conversations are laid out, and additional tricks that may be used.

Local flags
Any flag used in a conversation that has a main of '0' is considered a local flag, and will only be set or checked within that conversation alone. E.g. Setting flag '0-1' in a conversation with one character to true will not affect the status of flag '0-1' with another character (local flags are unique to each entity which has a datafile). Flag '0-0' is always considered to be true by default.

Comments
Comments can be added by placing '//' before them. e.g. '//This is a comment'. Note that comments cannot be used on the same line as one for 'first_char', 'second_char', 'item1', or 'event'.

Event Types
Additional event types that can be used in conversations are listed below.

none - No event.
quit - Exits the conversation.
attack- Exits the conversation and causes the character recoil as if they've been hit. If you need a character to attack the player, you will need to change their moodname (such as with a GSM entity).
heal - Heals the player by a portion of their hp.
strength - Upgrades the players strength. Usually accompanied by the text '>>> STRENGTH +1 <<<'.
p_take - Used to allow the player the option to take an item that has been specified as 'item1' through 'item5' E.g. 'item1:key_metal'. The specified item must also exist in the characters or target_interactions 'inventory' key.
p_give - Used to allow the player the option to give an item that has been specified as 'item1' through 'item5'. E.g. 'item1:item_bread'. If the player does not have the item, the conversation line that is tied to the 'p_give' event will not be displayed. For this reason, it is good to have a secondary conversation choice in the event the player is missing the item (look at '1_1_feori.txt' from DoD for a good example).

Items (Continued)
'item1' through 'item5' can be used with the take and give events. Each number relates to a different event in the conversation level. E.g. a conversation has the events 'p_give,none,p_give', so 'item1' would relate to the first 'p_give' event, and 'item3' to the second 'p_give' event. (Note that 'item2' is not being used, as it would be linked to the second event, 'none' with no effect.)

When using 'p_take' and 'p_give', you should also ensure that there is a conversation level with at least once sentence following the event. If there isn't, the conversation will end and the inventory will remain on screen until the player completes the action.

Flags (Continued)
Flags that are changed using 's_flags' will be evaluated by GSM entites once that conversation init section or level is completed. This means that if a flag is set mid conversation, any related GSM entities will trigger at that time.

Be aware that when using a GSM entity to change flags, those flags will not be updated until after the next conversation level has loaded. This is the cause of an issue with the Ramada NPC in Manawyd ('1_1_ramada.txt') where asking about the cook uses a GSM to disable the flag for that conversation option at the same time it returns the player to the list of questions they may ask. This causes the conversation option to still be visible but vanish when selected. Issues like this can be avoided either by adding another conversation level (this can even be a blank level which just forwards to the next part of the conversation) or by changing the flags earlier in the conversation.

Also important to note is that (uncertain if by design) the first flag listed in 's_flags' will be enabled if the player ever exits that level of the conversation prematurely (such as by pressing the escape key). It is recommended to take this into consideration when planning a conversation as it may cause unexpected issues. This affects init sections as well.

A further limitation is that 'i_flags' can only be used together with 'init_char:monster' within init sections (and will in fact crash DoD if used elsewhere and the first flag given is not true). If you need to display different text from a 'monster' based on flags, try using a conversation level without any sentences specified to redirect to a level of your choosing (see the above example).

And/Or Operators

As described in the official conversation doc, the # character can be used as an and/or operator when checking or setting flags.

Placing a # in an 'i_flags' line is treated as an or operator by default, but can be used as an and operator by including 'all_flags:true'. For example:

'i_flags:1-1' checks if the '1-1' flag is true.

'i_flags:1-1#1-2' checks if *either* the '1-1' or the '1-2' flag is true.

'i_flags:1-1#1-2' with 'all_flags:true' checks if *both* the '1-1' and '1-2' flags are true.

If working with a conversation where there are multiple 'i_flags' for the same level, an 'all_flags' value can be given for each set of flags, separated using a comma. This allows some choices to require that only one of the flags be active, while others can require all flags.

level:1
init_char:player
first_char:'This is option 1 and is only displayed if either 0-1 or 0-2 are true.'
first_char:'This is option 2 and is only displayed if both 0-1 and 0-2 are true.'
second_char:'You chose option 1!'
second_char:'You chose option 2!'
i_flags:0-1#0-2,0-1#0-2
all_flags:false,true
event:quit,quit

Using the # in a 's_flags' line is always considered an and operator. For example:

's_flags:1-1#1-2' would set both flag '1-1' and '1-2' to true.

Resetting Flags
While setting flags to true from a conversation is simple (using 's_flags'), setting them to false requires the use of target_gsm entities in the map. A method to reset flags is described below. In these examples, assume that we want to set flag '1-2' back to false.

For a setup that disables a flag once, but is never repeatable, two target_gsm entities, and a trigger_relay entity will be required. You'll need to set aside a GSM flag that can be used to trigger this with, in this example, that's '1-1'. When flag '1-1' becomes true, the trigger relay activates another target_gsm entity which disables the flag '1-2'.
[Image: GSM example]

For a repeatable way to disable a flag, the setup is similar to the above, but with the addition of a third target_gsm entity and use of the GSM_Multiple flag. When flag '1-1' becomes true, the trigger relay activates two other target_gsm entities which disable both flag '1-1' and flag '1-2'. This means that every time '1-1' is set to true, it will re-disable '1-2' as well as reset itself for another use.
[Image: GSM example]

Limitations
A number of limitations exist for the conversation files in DoD. Although most are unlikely to be surpassed in most normal usage, it is good to keep them in mind.

Only 10 init sections (sections using 'level:0') may be used in a conversation.
Only 1 set of init flags ('i_flags') or set flag ('s_flags') can be used within an init section (sections using 'level:0').
Only 32 level sections can be used in a conversation (does not include init 'level:0' sections).
Using a level over the value of '35' causes DoD to crash.
Only 10 player sentences and 10 monster sentences can be used in a single conversation level.
Only 10 'event' or 'next' items can be set within a single conversation level.
Only 5 init flags ('i_flags') can be checked together at one time, e.g. 'i_flags:1-1#1-2#1-3#1-4#1-5'
The conversation window can display roughly 345 characters before the player needs to scroll.
A single sentence has a maximum length of 1023 characters.
A single word has a maximum length of 29 characters.