Animation
Introduction
AnimationRuntime is a class containing a list of keyframes (of type KeyframeRuntimeInstance). AnimationRuntime instances can be used to modify variables on a GraphicalUiElement over time .
AnimationRuntime instances can be created from animations defined in the Gum tool or by hand in code. For information on how to create an animation in the Gum Tool, see the Animation Tutorials section.
Code Example - Loading Animations from Gum Project
Animations defined in the Gum tool can be loaded at runtime. To load and play an animation, the following calls are needed:
Call
GumService.LoadAnimations. This loads all animation files for all screens and components in the current Gum project.Obtain an
AnimationRuntimeinstance from yourGraphicalUiElement. This could be a screen or component.Call
PlayAnimationto begin the animation.
Animations can be played on an entire screen, entire component, or an individual instance within a screen or component.
For this example, the project has a screen called AnimatedScreen which contains an animation named SlideOnAndOff.

AnimatedScreen also contains an instance of a component named PleaseWaitPopup which has its own animation called Spinning. Note that the Spinning animation is marked as repeating, so once it starts it will play until it is stopped in code.

The following code shows how to load all animations, create the AnimatedScreen, and play animations according to keyboard commands.

AnimationController
Every GraphicalUiElement owns an AnimationController (accessed via Visual.AnimationController) which tracks playback state and raises OnStarted, OnCompleted, OnStopped, OnPaused, and OnResumed events. PlayAnimation and StopAnimation are convenience wrappers around this controller.
Waiting for an Animation to Finish with PlayAnimationAsync
Use PlayAnimationAsync to await an animation's completion instead of subscribing to OnCompleted/OnStopped and manually unsubscribing. New to async/await? See async Programming.
An optional System.Threading.CancellationToken can also be passed to stop the animation and cancel the task from outside code, for example an unfocus or a scene change:
Playing Animations on Hover or Highlight
Forms controls such as Button change their visual state (for example Enabled, Highlighted, Pushed, and Disabled) automatically as the user interacts with them. These state changes are applied instantly — they are not keyframe animations, and they do not call PlayAnimation.
Keyframe animations never play on their own. To run an animation when a control is highlighted, subscribe to the visual's RollOn event (raised when the cursor first moves over the control) and RollOff event (raised when the cursor leaves), then call PlayAnimation:
When the cursor moves directly from one control to another, the first control's RollOff is raised before the second control's RollOn, so its Unhighlight starts before the other control's Highlight.
The animations named above must exist on the control — either authored in the Gum tool and loaded with LoadAnimations, or created in code as shown in the next section. The control still applies its built-in Highlighted state on RollOn, so use animations for additional effects on top of that state rather than as a replacement for it.
Code Example - Animations in Code-Only Projects
Animations can be defined and executed in a code-only environment. The steps for creating an animation in a code only project are:
Creating an object which will be animated (such as a Button).
Creating the states for the animation. For example, a Button may have a larger size when highlighted, and a smaller size when not highlighted.
Create keyframes which define the time when each state should display and how to interpolate (tween) between each of the keyframes.
Define the animation using the states (keyframes) defined earlier.
Play the animation in response to an event, such as a Button highlight.

Named Events
An animation can carry named events on its timeline — markers with a name and a time. When playback crosses a marker's time, Gum raises an event so your game can react: play a sound effect, enable a hitbox, spawn a particle, and so on. Named events are authored in the Gum tool's animation editor (see the Animation Tutorials) or added in code.
Subscribe through the visual's AnimationController. The NamedEventOccurred event passes a NamedAnimationEventArgs whose Name you typically switch on:
The same AnimationController also exposes playback events such as OnStarted, OnCompleted, OnStopped, OnPaused, and OnResumed.
For looping animations, NamedEventOccurred fires once each loop. An event fires when playback passes its time, so it does not fire if the animation is stopped or restarted before reaching it.
To add a named event to an animation created in code, add a KeyframeRuntime with its EventName and Time set (leave StateName unset — an event keyframe carries no state):
Playing Multiple Animations on the Same Instance
The PlayAnimation method performs the following logic:
Internally stores the animation that is played
Internally resets the time on the animation back to 0
Each instance can store a separate animation and time, allowing a single animation to be played on multiple instances.
Since each instance only stores one value for the current animation and time, an instance cannot play multiple animations at one time.
To play multiple animations, we can keep track of each animation time and apply it manually in our update function.
The following code assumes that Animation1 and Animation2 are valid animations. The following code also assumes that MyInstance is a valid visual instance.
Last updated
Was this helpful?

