CCAutoVCD

Introduction

Automatic writer for Soundscripts, Scene files and Subtitles.

This program is used as a convenience tool to automatically write Soundscripts, Scene files (VCDs) and Subtitles (txt/dat) for your mod, based on template files.

It was written purely with Portal: Singularity Collapse in mind, so it doesn't offer extreme amounts of flexibility, but it should work for most projects just fine.

Usage Instructions

For invoke options, please run CCAutoVCD.exe -h, this will view the help message.

General usage is CCAutoVCD.exe -game <path> <template_path>. These two arguments are required for this program to work.

• -game <path> is used to determine the main folder of your mod. Any internal file writing/reading will happen only to that folder and its subfolders.
• <template_path> is the path to template files (.template) that contain definitions for CCAutoVCD to work with. This can be located anywhere and it's not required to be inside the game directory.

Prerequisites

CCAutoVCD assumes that you have a specific filestructure, and it's been designed with (I believe) the best one you can have. It also assumes some files are configured in a specific way.

1. Soundscripts:

   1. Soundscripts will get written to <game>/scripts/soundscripts/vo/<actor_name>/<template_name>.txt. Remember to include that directory in your game_sounds_manifest.txt!

   2. CCAutoVCD assumes that there are certain operator stacks available. For spatialized VO it assumes the update_dialog_spatial_<actor_name> is available, and for unspatialized: update_dialog_<actor_name>. If the game doesn't have that sound operator stack defined it will silently fail to load the sound! Sound operator stack creation won't be covered here, however it is recommended to just look at the original stacks such as update_dialog_spatial_cave or other. Remember to add definitions to soundmixers.txt for soundmixers to work properly (since the paths to sound files are different based on the actor)!

2. Scenes (VCDs):

   1. Scenes will get written to <game>/scenes/<actor_name>/<scene_name>.vcd

   2. NOTE: Periods are not allowed in the scene names (in order to not confuse the engine). CCAutoVCD will automatically convert any period in the name to an underscore (_).

3. Subtitles:

   1. Subtitles are only written in the English language.

   2. By default they already compiled using PyCaptionCompiler. The file location is <game>/resource/subtitles_english.dat

   3. You can choose to not compile subtitles (the -ncc invoke argument), then the output file will be the raw uncompiled subtitles in <game>/resource/cc_src/subtitles_english.txt

Template file syntax

Template files hold multiple definitions of dialogue scene/soundscript/subtitle. There is no strict saying in what definitions should be in which file, however, because template files are a representative of soundscript files, it's best to guide yourself by what you want in what soundscript file. An example of such definition is:

"my.sound.name"
{
	"actor" "elie"
	"cc_actor" "Elie Simons"
	"cc" "Hey there my name is elie!"
	"cc_color" "255,255,255"
	"map" "sp_a5_mymap"
	"speaker" "@speaker_elie"
	"wave" "vo/elie/elie_intro.flac"
}

Let's go over it line by line:

"my.sound.name"

REQUIRED | This is the name of the soundscript that corresponds to this dialogue line. It is also the name of the scene file, however as mentioned above please note that periods will get replaced by underscores, so in this case the actual scene file will be: my_sound_name.vcd.

"actor" "elie"

REQUIRED | This specifies which actor this line belongs to (<actor_name> mentioned above). In game the actor entity should be named @<actor_name>, in this example @elie.

"cc_actor" "Elie Simons"

OPTIONAL | This is a convenience feature. If specified, this will get inserted at the start of the subtitle, in bold text. In this example you can imagine the line as: "Elie Simons: Hey there my name is elie!". If not specified there will be no actor at the start of the line: "Hey there my name is elie!".

"cc" "..."

OPTIONAL | The actual subtitle that will be shown when this scene plays. If not specified, will be replaced with a placeholder.

"cc_color" "255,255,255"

OPTIONAL | The color of the whole line. If not specified defaults to white.

"map" "sp_a5_mymap"

OPTIONAL | Used in combination with the "speaker" key. CCAutoVCD will automatically load the compiled map if this is specified and look for the speakers.

"speaker" "@speaker_elie"

OPTIONAL | Used in combination with "map" key. When a map is specified and this is set to a targetname of a valid entity in a compiled map, CCAutoVCD will automatically spatialize the sound to come out of the entities with this targetname. Maximum count of such entities is 7. This information is baked into soundscript definitions directly, so remember to re-run CCAutoVCD whenever you update the location of such entities!

"wave" "vo/elie/elie_intro.flac"

REQUIRED | This is the actual sound file of this line. This file's duration is then used to determine how long the scene lasts and how long the subtitles show in game. This file will only be searched for in the <game> directory, it won't be searched for in any other mounted content!