UI/Animations

UI ANIMATIONS

What are UI Animations?

UI Animations allow you to animate UI elements in general ways for all frames, or specific ways for some types of frame. UI animations are made up primarily of two components, "Events" and "Controllers". Events trigger the animation to do something, and Controllers manage what the animation actually does. Animations just sit inside a frame, similar to a StateGroup.

Known Bugs

Animation frames (and StateGroup frames) do not compile correctly when using the UI editor so the map needs to be saved as a .sc2components file and the animation frames edited using a text editor (eg.Notepad++).

Example UI Animation

Here is a quick example of a UI animation that fades in an image frame. When the frame becomes visible the "Show" animation starts playing the frame will go from 0 alpha to 255 alpha over the course of 0.2 seconds.

<Frame type="Image" name="Image">
    <Anchor relative="$parent"/>
  
    <Animation name="Show">
        <Event event="OnShown" action="Reset,Play"/>
         
        <Controller type="Fade" end="Pause">
            <Key type="Curve" time="0" value="0" out="Slow"/>
            <Key type="Curve" time=".2" value="255" in="Slow"/>
        </Controller>
    </Animation>
</Frame>

Naming an Animation

Animations can be named whatever you want, but the names must at least be unique to other animations or frames that are 'siblings' within the frame it resides in.

Events

Events themselves are made up of three different components, the "Event" itself, the "Action" and the "Frame". The "Event" is what our event responds to, the "Action" is what the event will do when it responds, and the "Frame" is target for what our event is listening to in order to fire off. Here is an example event that will tell the animation to reset itself and then play when a child frame called "Button" gets clicked:

<Event event="OnClick" action="Reset,Play" frame="$this/Button"/>

Event Types

Custom Events: Custom events are events which can be sent through code, triggers, stategroups or animations and they can have any name not already associated with a standard event. The following event would reset and play the animation it is inside of when the parent frame receives the "YourCustomEventName" event from one of the previously listed sources.

<Event event="YourCustomEventName" action="Reset,Play" frame="$parent"/>

Standard Events: In addition to custom events you can setup, animations can also respond to a number of standard events based on player or UI actions.

Standard events for any type of frame:

Type	Description
OnShown	When the target frame becomes "Visible". This can occur by the frame itself becoming visible or a parent of this frame becoming visible as visibility is inherited.
OnHidden	When the target frame becomes not visible. This can occur by the frame itself becoming not visible or a parent of this frame becoming not visible as visibility is inherited.
OnEnabled	When the target frame becomes "Enabled". This can occur by the frame itself becoming enabled or a parent of this frame becoming enabled as enabling/disabling is inherited.
OnDisabled	When the target frame becomes "Disabled". This can occur by the frame itself becoming disabled or a parent of this frame becoming disabled as enabling/disabling is inherited.
OnMouseDown	When the user clicks down on the mouse on the target frame (fires immediately when they click, does not wait for release).
OnMouseUp	When the user releases the mouse button after clicking down on the target frame.
OnMouseEnter	When the user's mouse enters the clickable area of the target frame (no clicking or releasing required, just hovering over).
OnMouseExit	When the user's mouse exits the clickable area of the target frame (no clicking or releasing required, just hovering).
OnMouseWheelIncrement	-
OnMouseWheelDecrement	-

Standard events for "Control" frames or subtypes such as "Button":

Type	Description
OnClick	When the user clicks the target frame. Can only target "Control" frames or subtypes such as "Button".
OnDoubleClick	When the user doubleclicks the target frame. Can only target "Control" frames or subtypes such as "Button".
OnDragStart	Fires off the first time the user moves the mouse while holding down a click on the target control frame. Can only target "Control" frames or subtypes such as "Button".
OnDrag	Fires off every time the user moves the mouse while holding down a click on the target control frame. Can only target "Control" frames or subtypes such as "Button".
OnDragEnd	Fires off once the user lets go of the mouse click after executing a drag on the target control frame. Can only target "Control" frames or subtypes such as "Button".
OnKeyDown	NMI. Can only target "Control" frames or subtypes such as "Button".
OnKeyUp	NMI. Can only target "Control" frames or subtypes such as "Button".
OnKeyRepeat	NMI. Can only target "Control" frames or subtypes such as "Button".
OnFocusGained	-
OnFocusLost	-
OnEnterPressed	CEditBox only

Standard events for "Button" frames:

Type	Description
Toggled	When the target frame's "Toggled" property enters the "True" state. Can only target frames with the "Toggled" property such as "Button".
Normal	When the target frame's "Toggled" property enters the "False" state. Can only target frames with the "Toggled" property such as "Button".
Pushed	When the target frame's "Pushed" property enters the "True" state. Can only target frames with the "Pushed" property such as "Button".

Action Types

There are a number of "Actions" that an event can execute to affect the animation.

Type	Description
Play	Start playing the animation from its current position.
Stop	Stop playing the animation and reset all values to the frame’s original values.
Pause	Stop playing the animation and hold all values.
TogglePause	Toggles the paused state of the animation.
Restart	Sets the animation's time to 0 and direction to forward.
Reset	Set the animation’s time to 0 and direction to forward and sets the original value back onto the frame.
RefreshBaseValue	Resets the "starting value" of a controller. This is normally the original value that is reset to when an animation stops and the value used as the base for relative anchors.
DirectionForward	Set the animation’s direction to forward.
DirectionReverse	Set the animation’s direction to reverse.
ToggleDirection	Flip the direction the animation is playing.

You can execute multiple actions within a single event but just separating them with commas. They should be in the order you want them to execute. Here is an example where it will reset all of an animations values and then start playing it when the frame the animation is inside of becomes visible:

<Event event="OnShown" action="Reset,Play" frame="$this"/>

Target/Frame

An event can target a specific frame to listen to by using the "Frame" attribute. Here is an example of an animation listening for a custom event on the parent of the frame the animation is inside of.

<Event event="CustomEventName" action="Reset,Play" frame="$parent"/>

If you leave out the "Frame" attribute the event will just listen to the frame it is inside of by default, the same as if you set the frame attribute to "$this".

Controllers

Controllers drive what the animation actually does, whether it shows/hides something, moves it around the screen or changes its color. There are many different controllers to achieve different things and the list continues to grow over time. There are quite a few components to individual controllers, but the primary attributes are "Type", "End" and "Frame". You can also give controllers a "Name" which is useful for overriding templated animations. Many controllers will have additional attributes specific to that type of controller. Inside a controller you will find a sequence of "Keys" which perform specific actions at specific times in the controller's timeline.

End Types

Setting the "End" attribute on a controller determines what the controller will do when it reaches the end of its timeline when playing.

Type	Description
Stop	Stop the animation and reset to the original values.
Pause	Stop the animation and hold the final value.
Loop	Continue playing the animation from the beginning.
PingPong	Reverse the direction and continue playing.
Reset	Reset the animation's time and direction then pause.

Key Types

Keys are what you use to determine the actions of a controller along its timeline. All keys must specify a time in seconds. Most controllers will only accept one type of key. Most controllers use Curve keys, but many do not. Reference the specific type of controller you are looking for to see what key it accepts in the next section.

Type	Description
Animation	Send an action to the target animation of this controller.
Bool	Set a true/false value.
Curve	Change a value on a curve (easing).
Cutscene	Send a cutscene action to the cutscene frame.
Event	Send an event to the target frame.
Image	Set an image.
Sound	Play a sound.
Text	Set the text.

Controller Types

• ActorMsg (UnitModelFrame and maybe Portrait? Only)
• Anchor
• Animation
• AnimationSpeed
• AdjustmentColor
• Blur
• Color
• Counter (CountdownLabel Only)
• Cutscene (CutsceneFrame Only)
• Desaturation
• Dimension
• Event
• Fade
• LayerUV (Image Only)
• Property
• Rotation (Image Only)
• Skew (Image Only)
• Sound
• StartAngleOffset / EndAngleOffset
• State
• Style (Label Only)
• Text (Label Only)
• Texture (Image Only)
• Visibility

Anchor

Anchor controllers allow you to move a frame's anchor point(s). This is used to create the effect (and the reality) of a frame moving. Anchor controllers accept curve keys.

There a few attributes specific to Anchor controllers and they are:

• side: The anchor point to move. Valid values: Top, Left, Right, Bottom. Required.
• relative: When true, interpret the value as relative to the anchor point’s original offset. Defaults to true.
• unclip: When true, the frame will be unclipped from its parent. When false it will remain clipped by its parent.

Here are a couple of example anchor controllers:

<!-- Move the parent frame left and right back and forth forever -->
<Controller type="Anchor" end="PingPong" side="Left" relative="true" frame="$parent">
    <Key type="Curve" time="0" value="0" out="Slow"/>
    <Key type="Curve" time="1" value="100" in="Slow"/>
</Controller>

<!-- Move the parent frame left -->
<Controller type="Anchor" end="Pause" side="Left" relative="true">
    <Key type="Curve" time="0" value="0" out="Fast"/>
    <Key type="Curve" time="1" value="100" in="Slow"/>
</Controller>

Animation

Animation controllers allow you to execute an action on a specific animation. So without an event you can tell an animation to reset, play, stop etc. Animation controllers accept "Animation" keys.

There is one unique attribute to animation controllers:

• animation: The name of the animation you want to target in the target frame. Required.

Animation keys take an action. The action can be any valid action that would be used for an event.

Here is an example of an animation controller:

<!-- After 5 seconds, tell the animation to reset itself and start playing -->
<Controller type="Animation" end="Stop" frame="$parent/TitleLabel" animation="PulseIn">
    <Key type="Animation" time="5" action="Reset"/>
    <Key type="Animation" time="5" action="Play"/>
</Controller>

Blur

Blur controllers allow you to set a frame's blur factor. Value 0.0 means not blurred and value 1.0 is fully blurred. When used on a BlurFrame, it will blur all rendering below the frame. When used on other frames, will blur that frame only. Blur frames accept "Curve" keys.

Here is an example of a blur controller:

<!-- Blur from fully clear to fully blurred over 1 second -->
<Controller type="Blur" end="Pause">
    <Key type="Curve" time="0" value="0" out="Fast"/>
    <Key type="Curve" time="1" value="100" in="Slow"/>
</Controller>

Color

Color controllers allow you to set the color tint of a frame. Takes RGB values separated by a semi-color. See AdjustmentColor if you want to set the color for the ColorAdjustMode. Color controllers accept "Curve" keys.

Here is an example of a blur controller:

<!-- Set the color tinting -->
<Controller type="Color" end="Pause">
    <Key type="Curve" time="0" value="86;82;115" out="Fast"/>
    <Key type="Curve" time=".01" value="255;255;255" out="Slow"/>
</Controller>

Counter (CountdownLabel Only)

Counter controllers allow you to control the value of a CountdownLabel. Key values must be between 0.0 and 1.0, which represents a percentage between the starting value and target value of that CountdownLabel. Counter controllers accept "Curve" Keys.

Here is an example of a counter controller:

<!-- Quickly ramp up to 90% then slow down for the final 10% -->
<Controller type="Counter" end="Pause">
    <Key type="Curve" time="0" value="0" out="Fast"/>
    <Key type="Curve" time="1.5" value=".9" inOut="Fast,Slow"/>
    <Key type="Curve" time="2" value="1" in="Slow"/>
</Controller>

Cutscene (CutsceneFrame Only)

Cutscene controllers allow you to send numerous types of actions to a cutscene to manage it through UI. Cutscene controllers accept "Cutscene" keys.

Cutscene keys have several different parameters, some parameters:

• action: What action to take on the cutscene, possible actions:
  • SetCutscene: Set the cutscene file path.
  • Play: Play the cutscene.
  • Pause: Pause the cutscene.
  • Stop: Stop the cutscene. A stopped cutscene is no longer loaded and will need a new SetCutscene file to play again.
  • Bookmark: Jump the cutscene's time to the specified bookmark.
  • AddFilter: Add the filter to the cutscene.
  • RemoveFilter: Remove the filter from the cutscene.
  • TimeScale: Sets the playback speed of the cutscene where 1.0 is normal speed..
• file: The filepath used when the action is SetCutscene.
• bookmark: The bookmark to jump to when the action is Bookmark.
• value: The time scale value to use when the action is TimeScale.
• filter: The filter to add or remove when the action is AddFilter or RemoveFilter.

Here is an example of a cutscene controller:

<!-- Tell a cutscene to change the cutscene file, jump to a bookmark, then play -->
<Controller type="Cutscene" end="Stop">
    <Key type="Cutscene" time="0" action="SetCutscene" file="Cutscenes/UI_Screens_League_Promotion_Celebration.SC2Cutscene"/>
    <Key type="Cutscene" time="0" action="Bookmark" bookmark="BirthBegin"/>
    <Key type="Cutscene" time="0" action="Play"/>
    <Key type="Cutscene" time="0" action="AddFilter" filter="Bronze1Birth"/>
    <Key type="Cutscene" time="5" action="RemoveFilter" filter="Bronze1Birth"/>
</Controller>

Desaturation

Desaturation controllers allow you to toggle a frame's desaturation state. Accepts "Bool" keys.

Here is an example of a desaturation controller:

<!-- After .1 seconds set Desaturation to "True" -->
<Controller type="Desaturation" end="Pause">
    <Key type="Bool" time="0" value="False"/>
    <Key type="Bool" time=".1" value="True"/>
</Controller>

Dimension

Dimension controllers allow you to set the width or height of a frame. Accepts "Curve" keys. WARNING: Dimension controllers do not play nice with anchor controllers (dimensions effectively set anchors).

Dimension controllers have a handful of specific attributes:

• relative:
  • TRUE = For percentage values, allows you to scale +/- from 100% (10 would be 110% total, -10 would be 90% total). For non-percentage values, adds the value to the current dimension.
  • FALSE = For percentage values makes the value absolute (10 would be 10% of normal). For non-percentage values, sets the value as the current dimension.
• dimension:
  • WIDTH = Modify the width.
  • HEIGHT = Modify the height.
• percentage:
  • TRUE = Treats the curve values as 100 based percentage values.
  • FALSE = The curve values are the actual dimension.
• unclip:
  • TRUE = Sets the frame to be unclipped from its parent.
  • FALSE = Sets the frame to be clipped by its parent.

Here is an example of a dimension controller:

<!-- Scale a frame to 200% over two seconds -->
<Controller type="Dimension" dimension="Width" relative="False" percentage="True" unclip="False" end="PingPong">
    <Key type="Curve" time="0" value="100"/>
    <Key type="Curve" time="1" value="150"/>
    <Key type="Curve" time="2" value="200"/>
</Controller>

Event

Event controllers allow you to send animation events to a frame. Accepts "Event" keys.

Event keys have one special parameter:

• event: What event to send to the target frame at this point in the timeline.

Here is an example of an event controller:

<!-- Immediately send an event to the parent frame -->
<Controller type="Event" end="Stop" frame="$parent">
    <Key type="Event" time="0" event="Begin"/>
</Controller>

Here is an example of an event controller in context:

Expand this example

<Frame type="Frame" name="ParentFrame">
	<Frame type="Frame" name="ChildFrame">
		<Animation name="Show">
			<Event event="OnShown" action="Reset,Play"/>
			<Controller type="Event" end="Stop" frame="$parent">
				<Key type="Event" time="4" event="Pulse"/>
			</Controller>
		</Animation>
	</Frame>
	
	<Animation name="PulseAnim">
		<Event event="Pulse" action="Reset,Play"/>
		 
		<Controller type="Fade" end="PingPong">
			<Key type="Curve" time="0" value="255" out="Slow"/>
			<Key type="Curve" time="1.5" value="100" in="Slow"/>
		</Controller>
	</Animation>
</Frame>

Fade

Fade controllers allow you to set a frame's alpha value. Value 255 is fully visible and value 0 is fully invisible. Accepts "Curve" keys.

Here is an example of a fade controller:

<!-- Fade in from invisible to visible over half a second -->
<Controller type="Fade" end="Pause">
    <Key type="Curve" time="0" value="0" out="Fast"/>
    <Key type="Curve" time=".5" value="255" in="Slow"/>
</Controller>

LayerUV (Image Only)

LayerUV controllers allow you to use image layering to create sweet effects. Unfortunately they are complicated enough that they probably require their own wiki page.

Property

Property controllers allow you to set most properties on a frame. Accepts "Property" keys.

Property controllers have one special attribute:

• property: Which property you actually want to change.

Here is an example of a property controller:

<!-- Set Visible property on the frame to be false. -->
<Controller type="Property" property="Visible" end="Pause">
    <Key type="Property" time="0" value="false"/>
</Controller>

Rotation (Image Only)

Rotation controllers allow you to set the rotation value for an image. Accepts "Curve" keys.

Rotation controllers have one special attribute:

• relative:
  • TRUE = Rotation should add to the initial rotation value.
  • FALSE = Rotations are absolute from 0.

Here is an example of a rotation controller:

<!-- Rotate an image in a perfectly smooth circle over 4 seconds -->
<Controller type="Rotation" relative="False" end="Loop">
    <Key type="Curve" time="0" value="0" out="linear"/>
    <Key type="Curve" time="4" value="360" in="linear"/>
</Controller>

Skew (Image Only)

HSkew controllers allow you to skew an image horizontally, and VSkew allow you to skew images vertically. Accepts "Curve" keys.

Skew controllers have one special attribute:

• relative:
  • TRUE = Skew should add to the initial skew value.
  • FALSE = Skews are absolute from 0.

Here is an example of an HSkew controller:

<!-- Skew an image horizontally over three seconds and then PingPong. -->
<Controller type="HSkew" relative="false" end="PingPong">
    <Key type="Curve" time="0" value="0" out="slow"/>
    <Key type="Curve" time="3" value="-20" in="fast"/>
</Controller>

StartAngleOffset/EndAngleOffset (Image Only)

These controllers allow you to animate the circular mask on an "Image" with the "Circular" TextureType. Accepts "Curve" keys.

Here is an example of an EndAngleOffset controller:

<!-- Rotate the end angle offset around the entire circle over 1 second. -->
<Controller type="EndAngleOffset" end="Loop" relative="false">
    <Key type="Curve" time="0" value="0" out="Linear"/>
    <Key type="Curve" time="1" value="360" in="Linear"/>
</Controller>

State

State controllers allow you to set the state of a Stategroup which does not have any "When" conditions in it. Accepts "Identifier" keys.

State controllers have one special attribute:

• stateGroup: The name of the StateGroup you want to change.

Here is an example of a state controller:

<!-- Set state of SomeStateGroupName to be SomeStateName. -->
<Controller type="State" stateGroup="SomeStateGroupName" end="Pause">
    <Key type="Identifier" time="0" value="SomeStateName"/>
</Controller>

Style (Label Only)

Style controllers allow you to blend a lebl's font style between two different font styles. A value of 0.0 means 100% Style 1, and a value of 1.0 means 100% Style 2. Values in between are a blend of the two styles. Accepts "Curve" keys.

Style controllers have two special attributes:

• style1: The first font style you want to use (0.0). Required.
• style2: The second font style you want to use (1.0). Required.

Here is an example of a style controller:

<!-- Blend the font style from DialogHeaderLabel to DialogHeaderLabelRed then back again -->
<Controller type="Style" end="Pause" style1="DialogHeaderLabel" style2="DialogHeaderLabelRed">
    <Key type="Curve" time="0" value="0"/>
    <Key type="Curve" time="2" value="1"/>
    <Key type="Curve" time="4" value="0"/>
</Controller>

Sound

Sound controllers allow you to play sounds in an animation. They also allow you to specify whether a sound plays while the animation is moving forward or reverse. Accepts "Sound" keys.

Sound keys two special parameters:

• sound: The sound you want to play.
• direction: Which direction(s) the animation can be playing when you want to play. Legal values are Both, Forward, and Reverse. Both is default. (Optional)

Here is an example of a sound controller:

<!-- Play one sound half a second into the animation then another 1.5 seconds in -->
<Controller type="Sound" end="Stop">
    <Key type="Sound" time=".5" sound="@UI_ActionButtonSelect"/>
    <Key type="Sound" time="1.5" sound ="@UI_OtherSound"/>
</Controller>

Text (Label Only)

Text controllers allow you to set the text of a label. Accepts "Text" keys.

Here is an example of a text controller:

<!-- Cycle the text of a label for "Waiting..." where the dots disappear each half second -->
<Controller type="Text" end="Loop">
    <Key type="Text" time="0" text="@UI/Waiting1"/>
    <Key type="Text" time=".5" text="@UI/Waiting2"/>
    <Key type="Text" time="1" text="@UI/Waiting3"/>
    <Key type="Text" time="1.5" text="@UI/Waiting3"/>
</Controller>

Texture (Image Only)

Texture controllers allow you to set the texture of an image or image layer. Accepts "Image" keys.

Image controllers have one special attribute:

• layer: Specify the layer of the image you want to change. (Optional, defaults to 0)

Here are a couple examples of texture controllers:

<!-- Loop through three images, changing each frame every 0.2 seconds -->
<Controller type="Texture" end="Loop">
   <Key type="Image" time="0" image="@UI/BAS_HeroSelect_Waiting1"/>
   <Key type="Image" time=".2" image="@UI/BAS_HeroSelect_Waiting2"/>
   <Key type="Image" time=".4" image="@UI/BAS_HeroSelect_Waiting3"/>
</Controller>

<!-- Immediately change the texture for layer 1 of the image -->
<Controller type="Texture" end="Loop" layer="1">
   <Key type="Image" time="0" image="@UI/TextureYouWant"/>
</Controller>

Visibility

Visibility controllers allow you to set whether a frame is visible. Accepts "Bool" keys.

Here is an example of a visibility controller:

<!-- Start invisible, then change to visible two seconds later -->
<Controller type="Visibility" end="Pause">
    <Key type="Bool" time="0" value="False"/>
    <Key type="Bool" time="2" value="True"/>
</Controller>

Animation Flags & Speed

Animations can be given flags and the animation speed can be altered.

Animation Flags

Type	Description
NoEventsWhileHidden	The animation wont respond to animation events unless it's parent is visible. (Not tested)

<Animation name="PulseFade" flags="NoEventsWhileHidden">
</Animation>

Animation Speed

Animation speed can be a negative value, which makes it play in reverse.

<Animation name="AnimationName" speed="1">
	<Controller type="AnimationSpeed" end="Pause" animation="AnimationName">
		<Key type="Curve" time="0.0" value="1.00" inout="Linear"/>
	</Controller>
</Animation>