VCD

Valve Choreography Data (VCD) is a proprietary file format used to store choreography data.

VCDs are authored in HLFaceposer and played in your map via the logic_choreographed_scene entity.

Warning:The filename should contain only one period before the file extension; otherwise, the scene file cannot be found.

Note:VCD files must be compiled into scenes.image before they can be used (in all games since ).

Format

VCD uses a plain-text format that superficially resembles a simplified version of  JSON and can be edited with any text editor. Each file contains a nested list of objects that each have properties of their own. Properties can be text, numbers, or other objects and are denoted using a simple system of key-value pairs without separators.

The basic notation is as follows:

// comment
object_type (object subtype) "name" (parameters)
{
  property "value"
  property value
  object_type (name) (parameters)
  {
    property "value"
  }
}

Objects

Each object is denoted using the syntax type (subtype) "name" (parameters). Names, subtypes and paremeters may be optional depending on object type; the most simple declaration possible consists solely of an object type, such as with event_ramp. Common objects are actors, channels, and events.

Object types

Type	Function	Takes a name ?	Parameters	Example
actor	A single actor, with channels as children	Yes	none	actor "Alyx" { ... }
channel	A single channel, with events as children	Yes	none	channel "look at" { ... }
event	A single event, possibly with an event ramp or tags as children	Yes	none	event lookat "look_player" { ... }
event_ramp	Used for storing ramp data for blending events	No	none	event_ramp { ... }
tags	Used for event timing tags	No	none	tags { ... }
absolutetags	Used for gestures	No	playback_time or shifted_time	absolutetags shifted_time{ ... }
relativetags	Unimplemented, meant to be used for WAV events	No	Unknown	Unknown
flexanimations	Used for flex animation data	No	See its dedicated section	flexanimations defaultcurvetype=curve_catmullrom_normalize_x_to_curve_catmullrom_normalize_x { ... }
flextimingtags	Used for flex animation tags	No	none	flextimingtags { ... }
scalesettings	Obsolete way of saving UI data	No	none	scalesettings { "CChoreoView" "25" "ExpressionTool" "100" "GestureTool" "100" "RampTool" "52" "SceneRampTool" "100" }

Object hierarchy/order

• Actor(s)

• Channel(s)

• Event(s)

• Event properties
• Timing tags

• Channel properties

• Actor properties

• Scene properties

Properties

Properties of objects are denoted using their name (key) without parentheses, followed by a one or more values separated by spaces. Text is enclosed in double quotes (" "), numbers are not. Properties may be other objects, each with their own properties. The amount and type of available or required properties depend on the object type.

A few properties are common across many object types, such as time (float) (float) and param (string), indicating time codes and parameters that are to be passed to certain events. One such example is the lookat type event, which takes two time values for its position and duration or end point on the timeline and one param value to determine the entity an actor should look at:

Properties not followed by any value are flags. For instance : fixedlength. Every flag is optional, but they might be forced to appear by HLFaceposer.

 // from scenes/eli_lab/al_cmon.vcd
 ...
 event lookat "look_player"
 {
   time 0.053333 2.553333
   param "!player"
   ...
 }

Comments

Single-line comments may be created by prefacing a line with two slashes, for example:

// this is a comment
channel "look_at"
{
   ...
}

Scene properties

Map name

mapname <string>

It is the name of the tied .bsp, which is used for loading entity names. It should be a relative path starting from the maps/ folder.

Window settings

scalesettingsis ab obsolete way of storing UI preferences, it doesn't have any effect on the UI as this data is stored in registry keys. It is however always written in VCD files by HLFaceposer.

Confirm:Does it work in Source 2004 HLFaceposer ?

Format :

 scalesettings
 {
 "CChoreoView" "scale"
 <string> <string>
 }

Note:Window names are written in function of their names in the "View" tab.

Note:While every other window setting is optional, CChoreoView settings (the timeline window) are always written.

Fps

fps <int>

It is the fps number used for snapping. Its default value is 60. In HLFaceposer, the minimum value acceptable is 1 and the maximum is the 32 bit signed integer limit (2'147'483'647). But when loaded, the values will be snapped to 10 and 240 respectively.

Snap

snap <on/off>

It is used by HLFaceposer to save if the user wants snapping enabled, it is disabled by default.

Ignore phonemes

^[Todo]

Confirm: Source 2007/2009 addition, doesn't seem to have any effect on HLFaceposer or the game. Cannot be toggled in HLFaceposer

Note:Off by default

ignorePhonemes <on/off>

Actor properties

Model

faceposermodel <string>

It is the tied model name.

Note:It is stored as an absolute path, unlike mapname.

Activity

active <bool>

It is used for the actor disabling feature.

Note:If it is 1, it will simply not be written.

Channel properties

Activity

active <bool>

It is used for the channel disabling feature.

Note:If it is 1, it will simply not be written.

Event subtypes

Subtype table

"1D events" are events with an end time of -1.

Faceposer event type	VCD subtype	Is 1D ?
Unspecified	unspecified	---
Expression	expression	No
WAV File	speak	No
Gesture	gesture	No
Look at actor	lookat	No
Move to actor	moveto	No
Face actor	face	No
Fire Trigger	firetrigger	Yes
Generic(AI)	generic	No
Sequence	sequence	No
Flex animation	flexanimation	No
Sub-scene	subscene	No
Interrupt	interrupt	No
Permit Responses	permitresponses	No
Camera (in all games since )	camera	No
Script (in all games since )	script	Yes
The following subtypes are not treated as regular events by Faceposer	---	---
Section Pause	section	Yes
Loop	loop	Yes
Fire Completion	stoppoint	Yes

Common properties

Every event share these properties :

time <float> <float>

Note:If the second float is 0 (it is always written -1 by HLFaceposer) or lower, the event will act like a single point. It will disable the "End time" checkbox.

param <string>

[param2 <string>]

[param3 <string>]

fixedlength

Makes resizing the event in HLFaceposer impossible.

resumecondition

[active <bool>]

active is simply nonexistent if set to 1.

[tags { ... }]

<string> <float>

...

The string represents a name, and the float a timestamp.

Note:There can only be 128 tags for one event.

[event_ramp { ... }]

<float> <float>

...

The first float represents a timestamp, and the second a ratio.

Note:There can only be 128 ramp values for one event.

Unspecified and unhandled events

These events cannot be edited or exported, but can be moved and imported in HLFaceposer. The "Unspecified" event should never appear in HLFaceposer in normal circumstances. Every unhandled event (such as the "Script" event) will acts in the same way in HLFaceposer, but they might function properly in-game.

Expression

param <string>

Takes a phoneme class.

Note:The most common phoneme classes to exist are phonemes, phoneme_weak, phoneme_strong because they are always precached.

Note:The Half-Life 2 series additionaly precaches random and randomAlert.

param2 <string>

Takes a phoneme.

Example :

expression "Expression event 1"
{
  time 0.000000 1.000000
  param "phonemes"
  param2 "w"
}

WAV File

param <string>

Takes a soundscript or a raw sound name.

param2 <string>

Takes a float (in text form, between quotes) or VOL_NORMfor its sound volume.

Note:In Source 2004, param2 has to take one of these following dB values :

• 60dB
• 65dB
• 70dB
• 75dB
• 80dB
• 85dB
• 90dB

Confirm:Does it still work in games made after Source 2006 ?

fixedlength

Is always set by HLFaceposer because sounds cannot be stretched.

cctype <string>

Is used for closed captions, it can be cc_master, cc_slave or cc_disabled.

Note:cc_slave <string> is related to combined audio files, it doesn't emit captions.

Note:It can be changed in HLFaceposer with the "change selector" curved line pointing to one of the WAV events.

Note:cc_disabled <string> is tied to the "Disable Captions" feature.

cctoken <string>

Can be used to override caption tokens. It is most notably used for combined auido files.

[cc_noattenuate]

Is tied to the "Don't attenuate captions" checkbox.

[cc_usingcombinedfile]

Example :

speak "Sound event 1"
{
  time 0.000000 3.407483
  param "npc_citizen.question06"
  param2 "VOL_NORM"
  fixedlength
  cc_type "cc_master"
  cctoken ""
  cc_noattenuate
}

Gesture

param <string>

Takes a sequence name.

[synctofollowingestures]

absolutetags playback_time

It is the data in the playback time section.

apex <float>

accent <float>

loop <float>

end <float>

<string> <float>

absolutetags shifted_time

It is the data in the original time section. It shouldn't be modifiable in HLFaceposer.

Note:It stores the data taken directly from the sequences' $keyvalues' block. See Creating Faceposer gestures for more information.

apex <float>

accent <float>

loop <float>

end <float>

<string> <float>

Note:Tags have to be defined in both blocks.

sequenceduration <float>

Defines the duration of the currently used sequence, it is read-only.

Example :

event gesture "Gesture event 1"
{
  time 1.000000 4.502899
  param "G_shrug"
  synctofollowinggesture
  absolutetags playback_time
  {
    "apex" 0.077650
    "accent" 0.116475
    "loop" 0.155300
    "end" 0.728225
    "exampletag" 0.165000
  }
  absolutetags shifted_time
  {
    "apex" 0.160000
    "accent" 0.240000
    "loop" 0.320000
    "end" 0.440000
    "exampletag" 0.150000
  }
}

NULL gesture

Null gestures are simple gestures with NULL as their name. They can take every property regular gestures can take, but those will not be parsed.

Example :

event gesture "NULL"
{
  time 0.000000 1.000000
  param ""
}

Look at actor

param <string>

Takes an actor name.

[pitch <float>]

[yaw <float>]

Todo: What is the lowest and highest accepted value for both ?

Example 1 :

event lookat "Look at player"
{
  time 0.000000 1.0000000
  param "!player"
}

Example 2 :

event lookat "Look at desk"
{
  time 0.000000 1.000000
  param "target_desk01"
}

Example 3 :

event lookat "Look at marker"
{
  time 0.000000 1.000000
  param "target_desk01"
  pitch 10
  yaw -10
}

Move at actor

param <string>

Takes an actor name.

param2 <string>

Takes a move type, it can be Walk, Run or CrouchWalk.

Note:If a sequence name is specified, it will be used instead.

[param3 <string>]

Takes an actor name.

Todo: Find what param3 really does

distancetotarget <float>

Note:The maximum stop distance in HLFaceposer is 200, higher values are still valid, however

[forceshortmovement]

Example 1 :

event moveto "Run to player"
{
  time 0.000000 1.0000000
  param "!player"
  param2 "Run"
}

Example 2 :

event moveto "Crouch-walk to desk"
{
  time 0.000000 1.0000000
  param "target_desk02"
  param2 "CrouchWalk"
  distancetotarget 15.00
  forceshortmovement
}

Face actor

param <string>

Takes an actor name.

[lockbodyfacing]

Makes the actor's legs not move.

Example :

event moveto "Face player"
{
  time 0.000000 1.0000000
  param "!player"
  lockbodyfacing
}

Fire Trigger

param <string>

Takes a number ranging from 1 to 16. It is meant to be used in conjunction with logic_choreographed_scene's OnTriggerX output.

Example :

event firetrigger "Fire Trigger event"
{
  time 0.000000 -1.000000
  param "5"
}

Generic(AI)

param <string>

Takes an AI action.

The AI actions can be :

Action name	Takes a target ?
AI_BLINK	No
AI_HOLSTER	No
AI_UNHOLSTER	No
AI_AIM	Yes
AI_RANDOMLOOK	No
AI_RANDOMFACEFLEX	No
AI_RANDOMHEADFLEX	No
AI_IGNORECOLLISION	Yes
AI_DISABLEAI	No
debugtext	No

Note:debugtext takes one parameter in an untraditional way, it is taken after its name. param "debugtext Hi !" for instance.

[param2 <string>

Takes an actor name used as a target.

Example 1 :

event generic "Holster event"
{
  time 0.000000 1.000000
  param "AI_HOLSTER"
}

Example 2 :

event generic "Aim at Alyx"
{
  time 0.000000 1.000000
  param "AI_AIM"
  param2 "Alyx"
}

Example 3 :

event generic "Show debug text"
{
  time 0.000000 1.000000
  param "debugtext Hi !"
}

Sequence

param <string>

Takes a sequence name.

fixedlength

Is always set by HLFaceposer because only gestures can be resized.

Example :

event generic "Play animation"
{
  time 0.000000 1.833334
  param "ThrowItem"
  fixedlength
}

Flex animation

Before starting with the suvtype definition, let's define what curvetypes are.

• A curve type always starts with curve_.
• A curvetype takes two curve types separated by _to_
• They can be :

default

catmullrom_normalize_x

easein

easeout

easeinout

bspline

linear_interp

kochanek

kochanek_early

kochanek_late

simple_cubic

catmullrom

catmullrom_normalize

catmullrom_tangent

exponential_decay

hold

Example : "curve_catmullrom_normalize_x_to_curve_catmullrom_normalize_x"

param <string>

Is unused, it is therefore left as empty quotes.

flexanimations samples_use_time defaultcurvetype=<curvetype>

Note:defaultcurvetype will always be set to curve_catmullrom_normalize_x_to_curve_catmullrom_normalize_x by default.

Confirm:Is samples_use_time optional ?

<string> [disabled] [leftedge <curvetype> <float>] [rightedge <curvetype> <float>] [combo]

The first string is a flex controller name.

Note:There can only be 128 flex animation keyframes.

<float> <float> [<curvetype>]

[<float> <float> [<curvetype>]]

Note:The second block is only created if the flex controller supports combo editing.

flextimingtags

<string> <float> <bool>

The string is the tag name, the float is a duration, and the boolean a lock state.

Note:There can only be 128 flex timing tags.

Example :

event flexanimation "Flex event"
{
  time 0.000000 5.000000
  param ""
  flexanimations samples_use_time defaultcurvetype=curve_catmullrom_normalize_x_to_curve_catmullrom_normalize_x
  {
    "lid_tightener" combo 
    {
      0.4000 0.6100 "curve_easein_to_curve_easeout"
      2.4000 0.1200 "curve_linear_interp_to_curve_linear_interp"
      4.4000 0.5900 "curve_easein_to_curve_easeout"
      }
      {
        1.0000 0.7700 "curve_bspline_to_curve_bspline"
        1.8000 0.2700 "curve_bspline_to_curve_bspline"
        3.0000 0.7500 "curve_bspline_to_curve_bspline"
        4.0000 0.2900 "curve_bspline_to_curve_bspline"
      }
      "smile" leftedge curve_default_to_curve_hold 0.500 rightedge curve_kochanek_late_to_curve_default 0.250 
      {
        0.8000 0.7100
        1.6000 0.2700 "curve_easein_to_curve_easeout"
        2.2000 0.6000 "curve_easein_to_curve_easein"
        3.0000 0.2600 "curve_easeout_to_curve_easeout"
        3.6000 0.5900 "curve_linear_interp_to_curve_linear_interp"
      }
    }
  }
}

Sub-scene

param <string>

Takes a path.

fixedlength

Is always set by HLFaceposer because the length of the sub-scene is defined by the scene itself.

Confirm:Is the sub-scene path absolute ? I didn't see a single sub-scene in all of the first party games VCDs

Interrupt

param <string>

Takes no parameter, it isn't parsed.

Note:Even if param doesn't need to be specified, an empty dropdown exists for it in HLFaceposer.

Example :

event generic "Interrupt event"
{
  time 0.000000 1.000000
  param ""
}

Permit Responses

param <string>

Takes no parameter, it isn't parsed.

Example :

event permitresponses "Permit responses event"
{
  time 0.000000 1.000000
  param ""
}

Camera

(in all games since )

param <string>

Is a "shot type", it is meant to be used as a simple string. Called "Camera AI event" by HLFaceposer.

param2 <string>

Takes an actor name.

param3 <string>

Takes an actor name.

This event finds the first point_viewcontrol (NOT the closest, the first entity in the entity list) and call the ScriptCameraShot() Vscript function on it. This function has the following syntax : void ScriptCameraShot(string pszShotType, handle pSceneEntity, handle pActor1, handle pActor2, float duration).

Note:While it is not used anywhere in or , it is still functional.

Example :

event camera "Camera event"
{
  time 1.000000 5.000000
  param "Hi !"
  param2 "!target1"
  param3 "!target2"
}

Script

(in all games since )

Warning:This event is not handled by HLFaceposer ! It must be added in with a text editor.

param <string>

Takes a targetname.

param2 <string>

Takes a Vscript function name.

param3 <string>

Takes a string meant to be used as a function argument.

This event triggers the function referenced in param2 from the entity scripts of the entity referenced in param with the arguements written in param3 as it follows : void FunctionName(handle pActor, handle pThisSceneEntity, string param3, float duration).

Note:While it is not used anywhere in or , it is still functional.

Example :

event script "Script event"
{
  time 1.000000 -1.000000
  param "scriptent"
  param2 "TestFunc"
  param3 "Hi !"
}

Section Pause

param <string>

Takes options, they can diverge in two different branches in function of if HLFaceposer's "Automatically" flag is checked :

If the flag is not checked :

param "noaction"

If the flag is checked :

param "automate Resume/Cancel <float>"

The float is a duration.

Example 1 :

event section "Pause point 1"
{
  time 1.000000 -1.000000
  param "automate Resume 2.000000"
}

Example 2 :

event section "Pause point 2"
{
  time 1.000000 -1.000000
  param "noaction"
}

Loop

param <string>

Takes a timestamp, which is the loop back point.

loopcount <string>

Is infinite if set to -1.

Example :

event loop "Loop"
{
  time 1.000000 -1.000000
  param "2.000000"
  loopcount "5"
}

Fire Completion

param <string>

Doesn't take any parameter, it is only written as noaction.

Example :

event stoppoint "Fire Completion"
{
  time 1.000000 -1.000000
  param "noaction"
}