Understanding VGUI2 Animation

Introduction

VGUI2 has a pretty powerful animation system for animating both HUD elements and VGUI panels. Not that this overview is incomplete: you will find "^[Todo]" items at various spots that you may investigate yourself if you so wish.

Architecture Overview

The animation system is defined in AnimationController.cpp, which can be found under vgui2/vgui_controls. It is very extensive, but the main concept is as follows:

• Add animations through several methods
• Run these animations each tick, using an interpolator function to calculate the intermediate value.

There are two main ways to add animations, which are script-defined events and dynamic animations, which are done during run-time.

Events

Animation events can be loaded from two sources, both of which are located in the scripts folder:

• The animation script manifest: hudanimations_manifest.txt. If this isn't found, the latter is loaded:
• A single script file: HudAnimations.txt.

The manifest expects a KeyValue file, and will load each file in the manifest:

"HudAnimationManifest"
{
	"file" "scripts/HudAnimations.txt"
	// You can add more here
}

Tip:Neither the hudanimations_manifest.txt nor the HudAnimations.txt file will most likely be present. You can find the latter in the base source engine 2.gcf GCF file.

File Layout

Opening up HudAnimations.txt, you will see many events used in Half-Life 2. Here's the syntax of an event:

event <EVENTNAME>
{
	<COMMAND>	<ARGUMENTS>
}

Event overview

At the top of the file, you'll see a lovely overview of possible commands and their arguments. Here is an updated overview (there's some new stuff in the code):

• Animate
  • Arguments: <panel name> <variable> <target value(s)> <interpolator> <start time> <duration>
    • Valid panel names: Any VGUI or HUD panel.
    • Valid variables:
      Note:Italic values only work for HUD panels and/or weapon selection
      • Unary (1 argument): Xpos, Ypos, Wide, Tall, Blur, Alpha, SelectionAlpha
      • Binary (2 arguments): Position, Size
      • More than two: FgColor, BgColor, TextColor, Ammo2Color
        Tip:Color variables can also reference a scheme-defined color instead of an RGBA value, e.g. FgColor "BrightDamagedFg"
      • Unknown: TextScan
      • Variables defined in code
        Todo: Make a section about this, link it here
    • Valid target values: Any floating-point value. Up to four values are possible. Put multiple values between quotes (e.g. "255 0 0 255" or "512 512")
    • Valid interpolators:
      • Linear
      • Accel - starts moving slow, ends fast
      • Deaccel - starts moving fast, ends slow
      • Todo: In AnimationController::ParseScriptFile, the code also supports parsing Spline, Pulse and Flicker interpolators. Have a look at what they do.
    • Valid start times: Any floating-point value. Essentially a delay factor.
    • Valid durations: Any floating-point value.

• RunEvent: starts another event running at the specified time.
  • Arguments: <event name> <start time>
    • Valid event names: Any event defined in the animation files.

• StopEvent: stops another event that is currently running at the specified time.
  • Arguments: <event name> <start time>

• StopAnimation: stops all animations referring to the specified variable in the specified panel.
  • Arguments: <panel name> <variable> <start time>

• StopPanelAnimations: stops all active animations operating on the specified panel.
  • Arguments: <panel name> <start time>

• SetFont:
  Todo: Look up what this does.
  • Arguments: <panel name> <font parameter> <font name from scheme> <set time>

• SetTexture:
  Todo: Look up what this does.
  • Arguments: <panel name> <texture ID> <material name> <set time>

• SetString:
  Todo: Look up what this does.
  • Arguments: <panel name> <string variable name> <value to set> <set time>

Todo: Not done yet!