# Commentary System

The commentary system allows you to embed DVD-like director's commentary inside your levels. An example of its use can be seen in the Lost Coast level.

## Overview

Users enable commentary mode inside their Audio options. Whenever commentary is turned on, or a level is loaded while the commentary option is on, the game searches for a commentary file inside your MOD/maps directory. Commentary data is stored separately from the BSP so that commentary can be done after a map has finished playtesting, and not force maps to be retested. The commentary file must be a TXT file with a name matching that of the map's appended with "_commentary".

• e.g. if your map file is d2_lostcoast.bsp, then the commentary file must be d2_lostcoast_commentary.txt.

If a commentary file is found, the game is put into commentary mode, where the following happens:

• The entities contained within the commentary file are parsed and spawned.
• The player is put into a semi-god mode: immune to everything except falling damage and trigger_waterydeath. This prevents players easily bypassing map barriers.

Players can turn commentary mode on & off at any time. The entities described inside the commentary file will be destroyed and recreated dynamically to match.

The main entity found in commentary files is the point_commentary_node, which is the actual commentary speech bubble that is used by players to listen to commentary.

## The Commentary File

The commentary file is a KeyValues-formatted text file that lists a set of entities that should be created whenever the player is in commentary mode. It is essentially the same as the entity data block stored in VMF files by Hammer. The format of the file is as follows:

Commentary
{
entity
{
<key>	<value>
<key>	<value>
etc...
}
entity
{
<key>	<value>
<key>	<value>
etc...
}
etc...
}


Each entity section simply contains a list of keys and values to pass in to the Game DLL to spawn that entity. These keys and values are identical to the ones stored inside the VMF, and as a result are fully described inside the Hammer FGD file. Note that one of the keys must be "classname", so the Game DLL knows what type of entity is being described.

Any type of entity can be spawned via the commentary file, but not all entities will work properly. In particular, you can't easily spawn entities that use brushes (func_*, trigger_*, etc) as their visual and/or collision representation. If you want some of those entity type's functionality, it's not terribly hard to get it with some work in the Game DLL. For example, if you wanted the commentary view to track a moving func_tracktrain entity that you plan to spawn inside the commentary file, your Game DLL coder could add the capability for func_tracktrain entities to have non-brush models.

If you want more complex entity setups in commentary mode, you might find it easier to set up the entities inside your map in Hammer, and then open the VMF with a text editor and copy the entity data out and into your commentary file.

The main entity found in commentary files is the point_commentary_node.

You can specify outputs in your commentary entities by embedding a connections subsection within the entity chunk. The format is as follows:

entity
{
<key>	<value>
<key>	<value>
etc...

"connections"
{
<output name>	"<targetname>,<input name>,<parameter>,<delay in seconds>,<number of times the output can fire (-1 = infinite)>"
}
}


### Example

entity
{
"classname" "point_commentary_node"
"origin" "1214 4787 2356"
"angles" "0 90 0"
"commentaryfile" "#lostcoast\commentary\comm_tone.wav"
"speakers" "Chris Green"
"targetname" "comm_node_9"
"connections"
{
"OnCommentaryStarted" "comm_clientcommand,Command,mat_show_histogram 1,42,-1"
"OnCommentaryStopped" "comm_clientcommand,Kill,,0,-1"
}
}


The OnCommentaryStarted output of the point_commentary_node is connected to the Command input of the entity with a targetname of "comm_clientcommand" (in this case, a point_clientcommand). The parameter specified is "mat_show_histogram 1", with a delay of 42 seconds, and it is allowed to fire an infinite number of times. The OnCommentaryStopped output is connected to the Kill input of the same entity, with no parameter or delay.

Note: "commentaryfile" assumes your commentary sound is in a "sound" subdirectory of your mod (C:\Steam\steamapps\SourceMods\(mod name)\sound). Assuming "commentary.wav" is in that sound directory you would reference it like this: "commentaryfile" "commentary.wav"

Note: 44100Hz 16bit files are required, Higher bit rate files will not play correctly.

## Subtitles

It is possible to have subtitles display while a commentary node is playing. Doing so will hide the commentary panel (the one with the speaker's name, the duration bar, etc).

Let's say we wish to add subtitles to the example above. What we will need is the value from the "commentaryfile" key, namely "#lostcoast\commentary\comm_tone.wav".

Next, we'll have to go the the resource folder of the game/mod and edit the text file closecaption_english.txt. If this file does not exist, create it.

Note: IMPORTANT: The text file must be saved in the UCS-2 Little Endian format.

Here is an example of what it might look like:

"lang"
{
"Language" "English"
"Tokens"
{
soundscript.example "This is a closed caption for sound script files."
"path\to\file" "This is a closed caption for a file path. These will not play automatically unless used for hint subtitles."
}
}


"lang"
{
"Language" "English"
"Tokens"
{
soundscript.example "This is a closed caption for sound script files."
"path\to\file" "This is a closed caption for a file path. These will not play automatically unless used for hint subtitles."
"#lostcoast\commentary\comm_tone.wav" "Bla Bla Bla Bla"
}
}


Next, we will have to compile our subtitle file. You can find more information on how to do this in the Closed Captions article.

Note:You will have to recompile your subtitle file every time you make changes to it.

Lastly, ensure that these commands are set to 1: closecaption, cc_subtitles.

Your text bubbles will now display subtitles when played.

## Todo

Describe the harder, but do-able method of using brush-built entities inside commentary files.