GUI Animations

Revision as of 19:09, 19 October 2011 by Alex (Talk | contribs)
Jump to: navigation, search


GUI Animations are a mechanism for modifying the appearance of a GUI Control over time. This could mean anything from playing actual frames of an animation (like a stick figure walking around), to causing other types of changes such as modifying the texture, position, or size of the GUI Control. Animations can be set to run immediately when the Control is first created, or they can be set to trigger upon certain events such as a mouse click.

Note: It is perfectly legitimate to specify more than one animation on a control, or to set multiple events on a control, each of which has one or more different animations, as long as all of those animations can run at the same time without a conflict.

This page explains how GUI Animations work, how to add existing animations to a GUI Control, and how to create entirely new animation effects.

Setting a GUIControl to Use an Animation

To cause a GUIControl to animate, simply link it to an animation type. This can be done either via HSL, or by setting the Control's animation field in the Properties panel. Note that not all animation types can be linked to any GUIControl -- some, such as GUIA_ButtonClicks were written to work specifically with one type of Control. Others, however, can be run on pretty much any Control.

Each animation has a set of arguments. These arguments vary in quantity and type, depending on the animation. Please see the section on Animation Types for details on each one's syntax. An animation's arguments are entered as one large string, with the arguments delimited by commas.

Immediate Run

via HSL

GUIAnimation:addAnimation(<animation>,<animation args>);

To cause an animation to play immediately via HSL, a call should be made to the addAnimation() function in the GUIAnimation script:

control as nodeRef of class GUIControl = createNodeFromProtoType("example")
GUIAnimation:addAnimation(control, "glow", "1,2,3,smooth")
TestWindow as nodeRef of class GUIControl = createNodeFromProtoType("example")
GUIAnimation:addAnimation(TestWindow, "sparkle", "blue")

via HeroBlade


To cause an animation to play immediately via HeroBlade, enter the animation type into the animation field of the Control's Property panel:


Note: If the above were entered into the animation field of a GUI Control prototype that was being created via the GUIEditor, it would not run in the editor. Instead, any Control then created from that prototype in the future, would have the animation play immediately, when the Control was first rendered on the screen.

The trailing semicolon is required. To list multiple animations, separate each one by a semicolon.

Event-Triggered Animations

Most commonly, an animation is set to trigger upon a GUIEvent such as a mouse click.

Note: Not all GUIEvents can have an associated animation. Only the ones in the following list will work:

Valid Event Triggers for an Animation

GUIEvent Description
onMouseDown animation starts on Mouse Down
onMouseUp animation starts on Mouse Up
onMouseClick animation starts on Mouse Click
onMouseDblClick animation starts on Mouse Double-Click
onMouseWheel(args references class GUIMouseEvent animation starts on Mouse Wheel. args.wheelDelta is an integers, positive or negative depending on wheel direction
onClickedAway animation starts on Clicked Away
onGotFocus animation starts on Got Focus
onLostFocus animation starts on Lost Focus
onMousePressed animation starts on Mouse Down and stops on Mouse Up
onMouseEnter animation starts on Mouse Enter
onMouseLeave animation starts on Mouse Leave
onMouseHover animation starts on Mouse Enter and stops on Mouse Leave


Suppose it is desired to make a GUIControl exhibit the following animations:

The above could be set on the Control either via HeroBlade (the Properties panel or GUIEditor), or via HSL:

Triggering an Animation via HeroBlade

<event>=<animation>(<arguments); <event>=<animation>(<arguments>); . . . (etc)

Via the Properties panel, the following string could be added to the animation field of a particular Control.

onMouseHover=Glow(1,2,3,smooth); onMouseClick=PlaySound(tada.wav); onMouseClick=CoolThing(abc, realcool, 123);

Another way of doing it, would be via the GUIEditor, where the string could be added to the animation field of the control prototype, and then any node that was created from that prototype would have the respective behaviors. Note that if the string included just an animation, and not a GUIEvent to trigger it, then the animation would be triggered upon the creation of the Control.

To set the animation directly in the GUIXML file, the syntax would be:

animation='onMouseHover=Glow(1,2,3,smooth); onMouseClick=PlaySound(tada.wav); onMouseClick=CoolThing(abc, realcool, 123);'

Setting an event trigger on an animation via HSL

Via HSL, the Control's animation field could be set to the same value as it might via HeroBlade:

control.animation = "onMouseHover=Glow(1,2,3,smooth); onMouseClick=PlaySound(tada.wav); onMouseClick=CoolThing(abc, realcool, 123);"

Note that the above method can be cumbersome if it is desired to have many possible animations, as each time the control.animation field is modified, it wipes out what may have been there before. A way to get around this is make it additive:

control.animation = control.animation + " onMouseClick=PlaySound(tada.wav);"

Creating a custom animation effect - How Animations Work

An animation is caused by the commands in an individualized client-side animation script. Once this new script is created, it can be used on any GUIControl as appropriate.

To check what animation types are currently available, see the section on Animation Types.

If a scripter desires to create a custom effect (also known as an animation "type"), it is necessary to create both the special script for that effect, and a special node class for the animation.

For example: Suppose it is desired to create a new kind of "Sparkle" animation. A scripter must then create two things:

The Central GUIAnimation Script

The GUIAnimation.hsl client-side script manages animations. Functions in this script are called when it is desired to add or remove animations from a GUIcontrol via HSL. This central script also runs a timer which tells animations when to "tick" (i.e. do the next frame of animation).

GUIAnimation:AddAnimation() Function

GUIAnimation:addAnimation(control as NodeRef, animationName as String, args as String) as NodeRef of Class GUIAnimation

When the central GUIAnimation script's function addAnimation() is called, it creates an animation node from the two classes "GUIAnimation" and GUIA_<animation-name>.

It then calls the individual animation script's GUIAnimation_init() function, and passes the animation node to it. The individual animation script attempts to initialize the animation -- It validates the arguments and performs any other checks it needs to make sure it can perform the animation on the GUIControl. If all is good, it will return a value of TRUE. If there is a problem, it returns a value of FALSE, so that the animation can be cancelled.

The Animation Node Class

When the GUIAnimation's AddAnimation() function is called, a special animation node is created, with two different classes: the generic "GUIAnimation" class, and the appropriate individual class, such as "GUIA_Sparkle".

The GUIAnimation class gives the node the following fields:

Field Name Datatype Description
name string The name of the animation
controlToAnimate noderef A reference to the control that is to be animated
args string A string that instructs which part of the animation is to be performed

The animation node also has that specific animation's class, such as any fields specific to GUIA_Sparkle.

The Animation Script

In the individualized animation script (such as "GUIA_Sparkle.hsl"), there exist three standard animation functions, plus anything unique to the "sparkle" animation.

The standard functions handle the animation initalization, the stopping of the animation, and the "tick" or routine timed behavior of the animation:

shared function GUIAnimation_init(animation as NodeRef of Class GUIAnimation) as Boolean
shared function GUIAnimation_stop(animation as NodeRef of Class GUIAnimation)
shared function GUIAnimation_tick(animation as NodeRef of Class GUIAnimation)

GUIAnimation_init() - Initalizing an Animation

This function is called by the central GUIAnimation script. It receives a the animation node as an argument, and through that node's fields can determine the control to be modified, which animation to run, and, if there are multiple variations of that animation, exactly which version to run. If everything is successful, it returns a value of TRUE.

GUIAnimation_tick() - The "tick" timer

The central GUIAnimation script calls the individual {GUIAnimation_tick() functions for each animation(currently every 0:00:00.05) so they can do their work. For example, if it's desired to make a Control fade over time, the "tick" functions can mark off the time increments. The function receives a reference to the animation node, so it can determine which animation to change, if any. It can also store a counter in one of the animation fields, if it is trying to change a particular animation over time. For example, if an animation is supposed to make a window gradually fade away over the course of a few seconds, the "stop" function might set a timer to 100, and on each count of the tick, the window's opacity could be decreased by 1%.

GUIAnimation_stop() - Stop Animation

The central GUIAnimation script also calls the individual GUIAnimation_stop() function if appropriate. For example, if an animation is supposed to run while the mouse is hovering over that Control, and the mouse is then moved away, then the "stop" function is called, which should then end the animation. Note that the animation is not required to stop immediately -- it can keep running as long as is needed in order to create a smooth ending to the animation, if that is desired (see the "tick" function above).

IMPORTANT: Once an animation is completed, the individual animation's script is responsible for destroying the animation node (not the GUIcontrol!). The script MUST do this, otherwise this causes a "memory leak", and the extra nodes will pile up and eventually result in decreased game performance!

See also

For further examples, please examine any client-side script which starts with the prefix GUIA_.

Personal tools