Ru/Understanding VGUI2 Animation

Вступление

VGUI2 имеет довольно мощную систему анимации для анимации как элементов HUD, так и панелей VGUI. Вот относительно полный обзор того, что с ним можно делать.

Обзор архитектуры

Система анимации определена в AnimationController.cpp, который можно найти в vgui2/vgui_controls. Он очень обширный, но основная концепция такова:

• Добавлять анимацию можно несколькими способами
• Запускайте эти анимации каждый тик, используя функцию интерполятора для вычисления промежуточного значения.

Есть два основных способа добавления анимации, которые представляют собой определяемые сценарием события и динамические анимации, которые выполняются во время выполнения.

События

События анимации могут быть загружены из двух источников, оба из которых находятся в папке scripts:

• Манифест сценария анимации: hudanimations_manifest.txt. Если он не найден, загружается последний:
• Один файл сценария: HudAnimations.txt.

Манифест это обычный файл KeyValue. Он будет загружать каждый файл в манифесте:

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

Макет файла

Открыв HudAnimations.txt, вы увидите множество событий, используемых в Half-Life 2. Вот синтаксис события:

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

Обзор событий

Вверху файла вы увидите прекрасный обзор возможных команд и их аргументов. Вот обновленный обзор (в коде есть кое-что новое):

• Animate
  • Аргументы: <panel name> <variable> <target value(s)> <interpolator> <start time> <duration>
    • Допустимые названия панелей: любая панель VGUI или HUD.
    • Допустимые значения: Template:Note:ru
      • Унарный (1 аргумент): Xpos, Ypos, Ширина, Высота, Блюр, Прозрачность(Альфа), Прозрачность при выборе элемента
      • Двоичный (2 аргумента): Позиция, Размер
      • Более двух: FgColor, BgColor, TextColor, Ammo2Color Template:Tip:ru
      • Неизвестный: TextScan
      • Любые значения типов KeyValues ​​::TYPE_FLOAT и KeyValues ​​::TYPE_COLOR, которые доступны при вызове RequestInfo на панели, также можно изменять. ¹
      • Variables defined in code
    • 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
      • Spline - very smooth interpolation
      • Pulse - uses a sine pulse to interpolate. Expects a frequency value.
      • Flicker - uses the PRNG to determine whether to be at original value or at the final value, which causes a flicker effect. Expects a noise amount value.
        Совет: Both Pulse and Flicker take an extra value, so be sure to put one in the scripts.
    • 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:
  Нужно сделать: Look up what this does.
  • Arguments: <panel name> <font parameter> <font name from scheme> <set time>

• SetTexture:
  Нужно сделать: Look up what this does.
  • Arguments: <panel name> <texture ID> <material name> <set time>

• SetString:
  Нужно сделать: Look up what this does.
  • Arguments: <panel name> <string variable name> <value to set> <set time>

Executing Animations

Accessing the controller

First off, you'll need some includes. If you're working in a class that uses the vgui namespace, you can call the animation controller by including vgui_controls/AnimationController.h and calling it like so:

 vgui::GetAnimationController()

If you're not using the vgui namespace, you'll need to include both clientmode.h and vgui_controls/AnimationController.h, and call the animation controller like so:

 g_pClientMode->GetViewportAnimationController()

Executing Events

An event can be executed using the StartAnimationSequence method, which has two overloads. One simply takes the event name and looks up panels by itself, starting from the root panel, and the other takes the event name and a pointer to a panel that houses the controls that will be animated.

 vgui::GetAnimationController()->StartAnimationSequence( "ShowCommentary" ); // Just the event name
 vgui::GetAnimationController()->StartAnimationSequence( this, "MapZoomToLarge" ); // Event name + parent panel (example from CS:S)

Defining animation variables in code

Defining a variable that can be used in the event files is easy, and uses the following macro:

 #define CPanelAnimationVar( type, name, scriptname, defaultvalue )\
 	CPanelAnimationVarAliasType( type, name, scriptname, defaultvalue, #type )

Looking through code references, this appears to work fine for: ²

• Colors: CPanelAnimationVar( Color, m_cChangableColor, "Changable_Color", "0 0 0 0" );
• Fonts: CPanelAnimationVar( vgui::HFont, m_hChangableFont, "FontOverride", "DefaultSmall" );
• Floats: CPanelAnimationVar( float, m_fChangableFloat, "FloatAnimation", "0" );
• Integers: CPanelAnimationVar( int, m_iChangableInt, "IntOverride", "0" );
• Booleans: CPanelAnimationVar( bool, m_bChangableBool, "BoolOverride", "0" );

Executing dynamic animations

Events are handy for static animations, but if you want to load any argument on the fly, you'll need dynamic animations. It's surprisingly simple!

Preparing for running animations

The method we are interested in is called RunAnimationCommand, and takes arguments similarly to the events defined above.

Примечание:If you're accessing the controller via g_pClientMode, you'll want to call the UpdateAnimations method manually in the OnThink() method of your panel.

The RunAnimationCommand has two overloads: one for a single value, and another for multiple values. Unfortunately, the multiple-valued one uses the Color class to load any values, which means the values will be truncated to integers AND wrap around very quickly! To mitigate this, let's create a new overload:

Copy this under the other RunAnimationCommand overloads in AnimationController.cpp:

 //-----------------------------------------------------------------------------
 // Purpose: Runs a custom command from code, not from a script file
 //-----------------------------------------------------------------------------
 void AnimationController::RunAnimationCommand(vgui::Panel *panel, const char *variable, PublicValue_t targetValue, float startDelaySeconds, float duration, Interpolators_e interpolator, float animParameter /* = 0 */ )
 {
 	// clear any previous animations of this variable
 	UtlSymId_t var = g_ScriptSymbols.AddString(variable);
 	RemoveQueuedAnimationByType(panel, var, UTL_INVAL_SYMBOL);
 
 	// build a new animation
 	AnimCmdAnimate_t animateCmd;
 	memset(&animateCmd, 0, sizeof(animateCmd));
 	animateCmd.panel = 0;
 	animateCmd.variable = var;
 	animateCmd.target.a = targetValue.a;
 	animateCmd.target.b = targetValue.b;
 	animateCmd.target.c = targetValue.c;
 	animateCmd.target.d = targetValue.d;
 	animateCmd.interpolationFunction = interpolator;
 	animateCmd.interpolationParameter = animParameter;
 	animateCmd.startTime = startDelaySeconds;
 	animateCmd.duration = duration;
 
 	// start immediately
 	StartCmd_Animate(panel, 0, animateCmd);
 }

And copy this above the prototype of RunAnimationCommand in AnimationController.h:

 struct PublicValue_t
 {
 	float a, b, c, d;
 };
 void RunAnimationCommand(vgui::Panel *panel, const char *variable, PublicValue_t targetValue, float startDelaySeconds, float durationSeconds, Interpolators_e interpolator, float animParameter = 0 );

Примечание:I know, there's a perfectly fine Value_t struct that we can also use, but when I made it public, the entire class went haywire. Feel free to find a correct implementation.

Running animations

Now we're in business! You can call animations though the controller very easily. Here's an example as to how you would programmatically change the size of an ImagePanel:

Let's say we have an ImagePanel called "overviewImage ", which is defined in our panel's .res file. First, we get the panel:

 m_pOverviewImage = dynamic_cast<ImagePanel*>( FindChildByName( "overviewImage ", false ) );

Примечание:Put this in the class constructor right after you've loaded the Resource file. If you're confused, read this: Loading a Resource File.

You can then resize the ImagePanel as follows:

 AnimationController::PublicValue_t newSize;
 newSize.a = 256;
 newSize.b = 256;
 newSize.c = 0; // Unused
 newSize.d = 0; // Unused

 float totalAnimationTime = 3.0f;
 vgui::GetAnimationController()->RunAnimationCommand( m_pOverviewImage , "size", newSize, 0.0f, totalAnimationTime , vgui::AnimationController::INTERPOLATOR_LINEAR );

Footnotes

1. AnimationController::GetValue(ActiveAnimation_t& anim, Panel *panel, UtlSymId_t var) houses the according code.

2. You may also have noticed that CPanelAnimationVarAliasType is also a define, and takes an extra parameter: a type alias.

 // Only the first line
 #define CPanelAnimationVarAliasType( type, name, scriptname, defaultvalue, typealias ) \

This type alias is a string, and is used when converting the string-based default values into proper ones, and can also be used for custom processing. This processing is done in Panel::InitPropertyConverters(). This might be a good place to start if you want to extend this functionality to other variable types.