GUI animation types

Revision as of 21:38, 14 November 2011 by Alex (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search


There are several different pre-existing GUI animation types which can be applied to a GUIControl, each of which has its own specific use and arguments. This page gives details on the different types and a simple tutorial for creating a new GUI Animation.

Existing Types

To see a complete list of all available animation types, open the script editor and look for scripts that start with the prefix "GUIA_". To create a new type, see the section on GUIAnimations or the Create a New Animation tutorial on this page. Following is a list of the Clean Engine GUI Animations. For detailed arguments please see the appropriate section further down on the page, or open the appropriate script and look at its comments. For example, to learn the details of the Interpolate animation, you could examine the client-side script GUIA_Interpolate.

Each of the above animations can be set on a control either by directly adding a reference to the "animation" field of the control's properties, or via a script.


This animation takes two different values for some field on the target GUIControl, and then animates the Control by moving from one value to the other. For example, if a minimum and maximum values were indicated for the Control's size field, this animation would cause the Control to appear to grow from one size to another.

//1 field(string), the field on the GUIControl to modify, such as size.x or defaultStatePresentation.color.a
//2 min(float)
//3 max(float)
//4 duration in seconds(float)
//5 repeat count(integer)
//6 reverse(boolean), forward and backward(true), or just forward(false)
//7 curve(Enum of type interpolation curve), LINEAR, HOLD, EASE_IN, EASE_OUT, SMOOTH
//8 restore(boolean), restores the orignal value after the animation is finished
//9 delay in seconds(float), the amount of time to wait before actually starting the animation
//10 id(string), the ID of the animation


This is the value of the animation field on an "Action Mark" icon (such as when a character approaches an object that they can sit down on) which causes the icon to solidify as the mouse cursor passes over it:


HSL Syntax

GUIAnimation:addAnimation(getReady, "Interpolate", "size.y, getReady.size.y, 0, 0.5, 1, false, smooth, false, 0, readyshrink")

Though the above would be acceptable, it would be difficult to read. A better way to send the arguments would be as follows:

aa as String
aa = aa + "size.y"                               // field to change
aa = aa + "," + getReady.size.y                  // Minimum value
aa = aa + "," + "0"                              // Maximum value
aa = aa + "," + "0.5"                            // duration of effect
aa = aa + "," + "1"                              // repeat count
aa = aa + "," + "false"                          // reverse direction when max achieved
aa = aa + "," + "SMOOTH"                         // interpolation curve
aa = aa + "," + "false"                          // restore value when done
aa = aa + "," + "0"                              // delay start by seconds
aa = aa + "," + "readyshrink"                    // name for this animation
animationNode as NodeRef of Class GUIAnimation = GUIAnimation:addAnimation(getReady, "Interpolate", aa)

Create a New Animation

This tutorial will provide step by step instructions for creating a simple Fade GUI Animation. The result of the animation (given the animation parameters below) will cause a GUI Control to fade from 1.0 alpha to 0.5 alpha over 0.5 seconds when the mouse hovers over the control, then fade from 0.5 alpha to 1.0 alpha over 0.5 seconds when the mouse leaves the control.

Fade Animation Script

Below is the full contents of the "GUIA_Fade" GUI Animation script:

// The following args are enclosed in one string
//1 startAlpha(float) - what value of alpha to start the animation at
//2 endAlpha(float) - what value of alpha to end the animation at
//3 duration(float) - over how much time (in seconds) to fade from startAlpha to endAlpha
shared function GUIAnimation_init(animation as NodeRef of Class GUIAnimation) as Boolean
  where animation is kindof GUIA_Fade
    //this will split the single argument string into a list of the arguments
    SplitBy(animation.GUIanimationArgs, ",", animation.argsList)
    if animation.argsList.length != 3
      println("Invalid number of arguments for the fade animation, arguments=" + animation.GUIanimationArgs)
      return false
    //record when this animation started
    animation.timeIndex = SYSTEM.TIME.NOW
  return true
shared function GUIAnimation_stop(animation as NodeRef of Class GUIAnimation)
  if(animation != None)
shared function GUIAnimation_tick(animation as NodeRef of Class GUIAnimation)
  where animation is kindof GUIA_Fade
    //copy the animation arguments into readable variables
    start_alpha as Float = animation.argsList[1]
    end_alpha as Float = animation.argsList[2]
    duration as Float = animation.argsList[3]
    //this is how much time has elapsed since the animation started
    elapsed as TimeInterval = SYSTEM.TIME.NOW - animation.timeIndex
    //if the animation has been running the desired amount of time stop it
    if elapsed.secondsTotal > duration
    //calculate what the alpha should be based on how far along in the animtion it is
    alpha as Float = (end_alpha - start_alpha) * (elapsed.secondsTotal / duration) + start_alpha
    animation.controlToAnimate.hoverStatePresentation.color.a = FABS(alpha)
    animation.controlToAnimate.defaultStatePresentation.color.a = FABS(alpha)

See also

Personal tools