Commentary System

The Commentary System is a special feature introduced in Half-Life 2: Lost Coast which allows DVD-like director's commentary to be embedded inside levels.

In most games, users enable commentary mode through a "Developer Commentary" menu which launches levels with commentary enabled. Commentary can also be enabled directly with the serverside commentary cvar. When commentary mode is enabled, the game searches for a respective commentary file for the loaded level. If a commentary file is found, the entities contained within the commentary file are parsed and spawned.

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.

Note:Mapbase adds new Commentary Nodes, but they cannot be placed by the Commentary Editor

Games

Official

1. Half-Life 2 (added in 20th anniversary update)
2. Half-Life 2: Lost Coast
3. Half-Life 2: Episode One
4. Half-Life 2: Episode Two
5. Portal
6. Team Fortress 2
7. Left 4 Dead
8. Left 4 Dead 2
9. Portal 2
10. Half-Life: Alyx

Third-party

1. Cry of Fear
2. Half-Life 2: Update

File format

Commentary data is stored separately from the BSP in a KeyValues-formatted text file, making them completely independent from the map's default content and allowing commentary to be created without directly modifying and recompiling a map.

Whenever commentary is turned on, or a level is loaded while the commentary option is on, the game searches for a commentary file inside the game or mod's maps directory.

The commentary file 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: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.

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

Advanced Usage

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.

Header

Commentary Nodes

The principal entity in commentary mode is point_commentary_node, which composes the actual commentary speech bubbles used by players to listen to commentary.

While listening to commentary from a node, 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.

Subtitles

While playing a commentary node, the commentary system checks whether or not the user has subtitles enabled. If subtitles are enabled, the node can automatically display a subtitle for the audio file. If subtitles are disabled, the system will instead display a unique commentary panel which shows the speaker's name and a duration bar.

To add a subtitle to a commentary node, add a new line to the closed captioning file which uses the exact value from the "commentaryfile" key. For more information on how to edit or create subtitles and closed captioning, see the Closed Captions article.

Here is an example of what a commentary subtitle might look like:

"lang"
{
	"Language" "English"
	"Tokens"
	{
		"#lostcoast\commentary\comm_tone.wav" "[Developer's Name] Bla Bla Bla Bla"
	}
}

Creating commentary files with Hammer

Because the commentary files are so similar to VMF files, you can make a VMF file and turn it into a commentary file.

In some games, like Left 4 Dead 2 commentary files are used to add point entities to a map without recompiling the map. Usually they add info_remarkable and env_player_blocker entities. Should you want to create such a commentary with Hammer, you can do so by following these steps:

• Start by placing the entities you want into your map. Only point entities are allowed.
• Copy the newly placed entities, create a new empty map and use "Paste Special" to paste all entities exactly where they were.
• Save this map and open the VMF in a text editor.
• Replace everything from the very beginning to the first entity.

versioninfo
{
	"editorversion" "400"
	"editorbuild" "9153"
	"mapversion" "1"
	"formatversion" "100"
	"prefab" "0"
}
visgroups
{
}
viewsettings
{
	"bSnapToGrid" "1"
	"bShowGrid" "1"
	"bShowLogicalGrid" "0"
	"nGridSpacing" "128"
	"bShow3DGrid" "0"
}
world
{
	"id" "1"
	"mapversion" "1"
	"classname" "worldspawn"
	"detailmaterial" "detail/detailsprites"
	"detailvbsp" "detail.vbsp"
	"maxpropscreenwidth" "-1"
	"musicpostfix" "mall"
	"skyname" "sky_l4d_c1_1_hdr"
	"timeofday" "3"
}

with

"Entities"
{

• Scroll to the very bottom and delete the Cordon and camera section, but keep the last }.

cameras
{
	"activecamera" "-1"
}
cordons
{
	"active" "0"
} //Keep this curly bracket. It closes the { added at the top by "entities".

• Some entities will have "Editor" Data.

editor
{
	"color" "255 100 100"
	"visgroupshown" "1"
	"visgroupautoshown" "1"
	"logicalpos" "[0 500]"
}

Which can be replaced with

 "mapupdate" "1"

Tip:This is easily done by selecting the entire "Editor" section and using Notepad++'s "Replace all" option to replace all these lines with "mapupdate" "1".

• Save this edited vmf as <mapname>_commentary.txt and put it into the maps folder.

Converting Commentary back to VMF

In some cases, you may need to reverse engineer commentary files. Usually when you want to decompile a map and want to include all the entities saved in a commentary file.
You can convert a commentary file back to a VMF by doing the following:

• Swap the beginning part of

"Entities"
{

to

world
{
	"id" "1"
	"mapversion" "1"
}

• Scroll to the end and delete the extra } at the very end.

	entity
	{
		"id" "4426202"
		"classname" "env_player_blocker"
		"BlockType" "0"
		"initialstate" "1"
		"maxs" "8 8 8"
		"mins" "-4 -56 -570"
		"origin" "2346 5648 2472"
		"mapupdate" "1"
	}

} // This here

• Save the commentary file as a VMF and open it in hammer.
• Select all entities, copy them and "Paste Special" them in the map they belong to. This way they'll be placed exatly where they need to be.

Creating commenary files with Commentary Editor

Main article:  Commentary Editor

Files

Whenever commentary is turned on, or a level is loaded while the commentary option is on, the game searches for a commentary file inside the game or mod's maps directory. 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 maps/d2_lostcoast.bsp, then the commentary file must be maps/d2_lostcoast_commentary.txt.

External links

• Example of custom made commentary node (closed captions)

See also

• Category:Commentary System