Choreo Generator

A lot of files and steps are involved in making choreo scenes. This generator tries to automate as much of the process as possible, designed for the perculuarities of Portal 2's style of choreo (one scene per WAV, controlled by VScript, no animation and consistent actor names). However it can still be used for any other game.

The generator operates by looking at all WAV files and defined subtitles. Then for each line, it generates a soundscript and choreo scene. If a WAV is present its duration is used, otherwise it estimates an approximate duration then configures the choreo scene to display subtitles only. This way you can test scenes without any voice acting at all.

Naming conventions

To be able to match scenes, soundscripts and WAVs to each other, the generator expects a certain naming scheme:

• Sounds: sound/npcs/char/path/file.wav
• Soundscripts/subtitles: npc.char.path.file
• Choreo: scenes/char/path/file.vcd char must be present, and is used to identify which character this corresponds to for picking the actor entity.

Manual files

It may be desirable to customise a few soundscripts, choreo scenes, or disable specific lines. Each generated choreo scene starts with a special // comment. If the generator finds a scene without that, it'll leave it untouched, and also avoid generating anything for any lines it uses.

Configuration

The generator uses a config file to ensure consistency. The location can be specified by command line argument, or alternatively is assumed to be gen_choreo.vdf in the folder above the choreo generator's. The format is like so:

"GameDir" "path/to/game/directory/"
"WPM" "125"
"use_operator_stacks" "1"

"ActorNames"
	{
	"person1" "@first_person"
	"guard" "guard1"

	"ignore" ""
	}

"ActorOverrides"
	{
	"guard2" "guard.some_line"
	"guard5" "guard.another_line"
	"@guard_tv" "guard.somemap.*"

	"" "this.is.ignored"
	}

"mixgroups"
	{
	"guard" "npcVO"
	"nomix" ""
	}

"soundlevels"
	{
	"@guard_tv" "SNDLVL_NONE"
	"guard1" "SNDLVL_TALKING"
	}


"image_imports"
	{
	"scenes/some_scenes.image" 
		{
		"" "scenes/npc/glados_manual/ding_off.vcd"
		"" "scenes/npc/glados_manual/ding_on.vcd"
		}
	"scenes/include_all.image" "*"
	}

Options:

• GameDir is required, and must be the location relative to the config file that gameinfo.txt is placed in.
• WPM is used for subtitle files without any WAVs - the word count is used with this to estimate a duration.
• If use_operator_stacks is disabled, no stacks will be produced. This is necessary for pre-Portal 2 games. Without stacks, the mixgroups has no effect, and any subtitle-only scenes will make a slight noise (common/null.wav).
• ActorNames needs to be specified for each actor, it defines the default entity each choreo scene uses. An empty string disables any generation for the actor.
• ActorOverrides allows overriding the entity for a specific line. The name goes first to make organisation easier. If it ends with *, it acts like a wildcard. Longer wildcards override shorter ones, and non-wildcards override all wildcards.
• MixGroups allows setting the sound mixing group, via operator stacks. A blank option disables this, and if unspecified actornameVO is used. See scripts/soundmixers.txt for more info about this.
• MixGroupOverrides allows overriding sound mixing groups for specific lines. This functions the same as ActorOverrides.
• SoundLevels allows overriding the sound level (attenuation, or max range), per actor entity. It defaults to SNDLVL_NONE, or infinite range. For reference, Wheately uses SNDLVL_110dB when core.
• SoundLevelOverrides allows overriding sound levels for specific lines. This functions the same as ActorOverrides.
• image_imports allows merging certain scenes from an existing image file. This is useful for mods which want to keep existing dialog. Unfortunately due to how scenes.image works, either all scenes must be merged, or each scene must be explicitly specified.