View source for Commentary System

{{LanguageBar}}
<!-- for page history, see base page -->
The '''Commentary System''' is a special feature introduced in {{hl2lc|4}} 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 <code>commentary</code> 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|3.1}} adds new Commentary Nodes, but they cannot be placed by the [[Commentary Editor]]}}

==Games==
===Official===
# {{Half-Life 2: Lost Coast|4}}
# {{Half-Life 2: Episode One|4}}
# {{Half-Life 2: Episode Two|4}}
# {{Portal|4}}
# {{Team Fortress 2|4}}
# {{Left 4 Dead|4}}
# {{Left 4 Dead 2|4}}
# {{Portal 2|4}}
# {{Half-Life: Alyx|4}}

===Third-party===
# {{Cry of Fear|4}}
# {{hl2u|4}}

==File format==
Commentary data is stored separately from the [[BSP]] in a [[KeyValues class|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 <code>maps</code> 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:

{{pre|1=<nowiki>Commentary
{
	entity
 	{
 		''<key>''	''<value>''
 		''<key>''	''<value>''
 		''etc...''
 	}
 	entity
 	{
 		''<key>''	''<value>''
 		''<key>''	''<value>''
 		''etc...''
 	}
  	''etc...''
}</nowiki>}}

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 <code>"classname"</code>, 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 (<code>func_*</code>, <code>trigger_*</code>, 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 <code>connections</code> subsection within the <code>entity</code> chunk. The format is as follows:
{{pre|1=<nowiki>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)>''"
	}
}</nowiki>}}

====Example====
{{pre|1=<nowiki>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"
	}
}</nowiki>}}
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 '''{{ent|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 {{ent|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:

{{pre|1=<nowiki>"lang"
{
	"Language" "English"
	"Tokens"
	{
		"#lostcoast\commentary\comm_tone.wav" "[Developer's Name] Bla Bla Bla Bla"
	}
}</nowiki>}}
==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 {{l4d2|3.1}} 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.
{{pre|1=<nowiki>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"
}</nowiki>}}  with 
{{pre|1=<nowiki>"Entities"
{</nowiki>}}
*Scroll to the very bottom and delete the Cordon and camera section, but keep the last '''}'''.
{{pre|1=<nowiki>cameras
{
	"activecamera" "-1"
}
cordons
{
	"active" "0"
} //Keep this curly bracket. It closes the { added at the top by "entities".</nowiki>}}
*Some entities will have "Editor" Data.
{{pre|1=<nowiki>editor
{
	"color" "255 100 100"
	"visgroupshown" "1"
	"visgroupautoshown" "1"
	"logicalpos" "[0 500]"
}</nowiki>}}
Which can be replaced with 
{{pre|1=<nowiki> "mapupdate" "1"</nowiki>}} 
{{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.<br>
You can convert a commentary file back to a VMF by doing the following:
*Swap the beginning part of 
{{pre|1=<nowiki>"Entities"
{</nowiki>}}
to
{{pre|1=<nowiki>world
{
	"id" "1"
	"mapversion" "1"
}</nowiki>}}
*Scroll to the end and delete the extra '''}''' at the very end.
{{pre|1=<nowiki>	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</nowiki>}}
*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|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 <code>maps</code> directory. The commentary file must be a [[Wikipedia:.txt|TXT]] file with a name matching that of the map's appended with "_commentary".

E.g. if your map file is <code>maps/d2_lostcoast.bsp</code>, then the commentary file must be <code>maps/d2_lostcoast_commentary.txt</code>.

==External links==
* [https://www.youtube.com/watch?v=h6ZEbHnqMa8 Example of custom made commentary node (closed captions)]

==See also==
* [[:Category:Commentary System]][[Category:Source]]

[[Category:File formats]]<!--Use more specific if possible-->
[[Category:Files]]<!--Use more specific if possible-->

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