Commentary System

The Commentary System is a special feature introduced in which allows DVD-like director's commentary to be embedded inside levels.
In most games, users enable commentary mode through a "Developer Commentary" (or "Community Commentary") menu which launches levels with commentary enabled. Commentary can also be enabled directly with the serverside 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.
==Games==
===Official===
# (added in 20th Anniversary Update)
# 
# 
# 
# 
# 
# 
# 
# 
# 
===Third-party===
# 
# (Community Commentary)
==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:
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.
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.
===Advanced Usage===
You can specify outputs in your commentary entities by embedding a connections subsection within the entity chunk. The format is as follows:
====Example====
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 , 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 . 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:
==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 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.
 with 
*Scroll to the very bottom and delete the Cordon and camera section, but keep the last }.
*Some entities will have "Editor" Data.
Which can be replaced with 
 
*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 
to
*Scroll to the end and delete the extra } at the very end.
*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 commentary files with 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.
The commentary file can be embedded inside a VPK file.
==External links==
* Example of custom made commentary node (closed captions)
==See also==
* :Category:Commentary SystemCategory:Source
Category:File formats
Category:Files
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