Commentary System

From Valve Developer Community
Revision as of 23:54, 31 October 2005 by Robin Walker (talk | contribs) (Created (from AndrewNeo's Commentary Configuration File))

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

The commentary system allows you to embed DVD-like directors 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 separate from the .bsp so that commentary can be done after a map has finished playtesting, and not force maps to be restested. The commentary file must 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 & spawned.
  • The player is put into a semi-god mode: immune to everything except falling damage & 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 & 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 & values to pass in to the Game DLL to spawn that entity. These keys & 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_track entity that you plan to spawn inside the commentary file, your Game DLL coder could add the capability for func_track 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.

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" "1213.953735 4787.380371 2356.031250"
	"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 amount of times. The OnCommentaryStopped output is connected to the Kill input of the same entity, with no parameter or delay.

Todo

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