Commentary System

Template:Otherlang2The 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.

Overview

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.

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.

Games utilizing the Commentary System

Valve has used the Commentary System to create developer commentary for most game releases since 2005, starting with Half-Life 2: Lost Coast .

• Half-Life 2: Lost Coast
• Half-Life 2: Episode One
• Half-Life 2: Episode Two
• Portal
• Team Fortress 2
• Left 4 Dead
• Left 4 Dead 2
• Portal 2
• Half-Life: Alyx

The Commentary File

Commentary data is stored separately from the BSP in regular plain-text TXT files, 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 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.

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

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"
	}
}

External Links

Example of custom made commentary node (closed captions)

See Also

• Commentary Editor
• point_commentary_node
• commentary_auto
• commentary_zombie_spawner (only in )
• commentary_dummy (only in )