ESOUI - Animation Tutorial Request

ESOUI (https://www.esoui.com/forums/index.php)

- Lua/XML Help (https://www.esoui.com/forums/forumdisplay.php?f=175)

- - Animation Tutorial Request (https://www.esoui.com/forums/showthread.php?t=2236)

Animation Tutorial Request

Hey folks, I'd like to put a bounty out for a simple tutorial on using the ESO AnimationManager and/or AnimationObjects. If anyone is familiar with these functions, I would love to see a brief code snippet that explains the how to instantiate an animation object, associate it with a control, and fire the animation.

For example, maybe a quick how-to on transitioning the alpha of control from 0 to 1 over a 2 second duration?

This would be really helpful if anyone understands it enough to share some tricks!

Quote:

Originally Posted by Atropos (Post 12131)

A while back acies sent this information:
http://www.esoui.com/forums/showthread.php?t=1191

I use a simple alpha animation in Bloody Screen addon, but I do not use AnimationManager directly, I'm using ZO_AlphaAnimation object.

Lua Code:

ZO_AlphaAnimation:New(animatedControl)
ZO_AlphaAnimation:GetControl()
ZO_AlphaAnimation:FadeIn(delay, duration, fadeOption, callback, shownOption)
ZO_AlphaAnimation:FadeOut(delay, duration, fadeOption, callback, shownOption)
ZO_AlphaAnimation:PingPong(initialAlpha, finalAlpha, duration, loopCount, callback)
ZO_AlphaAnimation:SetPlaybackLoopsRemaining(loopCount)
ZO_AlphaAnimation:IsPlaying()
ZO_AlphaAnimation:SetMinMaxAlpha(minAlpha, maxAlpha)
ZO_AlphaAnimation:Stop(stopOption)

Code:

Arguments:

delay, duration - milliseconds

fadeOption - ZO_ALPHA_ANIMATION_OPTION_USE_CURRENT_ALPHA or ZO_ALPHA_ANIMATION_OPTION_FORCE_ALPHA

callback - function which will be called when animation finishes

showOption - ZO_ALPHA_ANIMATION_OPTION_USE_CURRENT_SHOWN or ZO_ALPHA_ANIMATION_OPTION_FORCE_SHOWN

stopOption - ZO_ALPHA_ANIMATION_OPTION_PREVENT_CALLBACK or nil

A small example:

Lua Code:

local tlw, texture, animation
 
local function OnMouseUp(self, button, upInside)
   local currentAlpha = control:GetAlpha()
   local delay = 0         -- milliseconds before animation starts
   local duration = 2000   -- milliseconds for full animation. Actual duration will be duration * currentAlpha.
   local fadeOption = ZO_ALPHA_ANIMATION_OPTION_USE_CURRENT_ALPHA
   local callback          -- I will leave callback nil, it is function which will be called when animation finishes
   local showOption = ZO_ALPHA_ANIMATION_OPTION_USE_CURRENT_SHOWN 
 
   if currentAlpha < 0.5 then
      animation:FadeIn(delay, duration, fadeOption, callback, shownOption)
   else
      animation:FadeOut(delay, duration, fadeOption, callback, shownOption)
   end
end
 
tlw = WINDOW_MANAGER:CreateTopLevelWindow()
tlw:SetDimensions(128,128)
tlw:SetAnchor(CENTER, GuiRoot, CENTER, 0, 0)
tlw:SetHandler("OnMouseUp", OnMouseUp)
tlw:SetMouseEnabled(true)
tlw:SetAlpha(1)
tlw:SetHidden(false)
texture = WINDOW_MANAGER:CreateControl(nil, tlw, CT_TEXTURE)
texture:SetTexture("/esoui/art/icons/poi/poi_groupboss_complete.dds")
texture:SetAnchorFill(tlw)
animation = ZO_AlphaAnimation:New(tlw)

(I didn't test this code, so there could be some typos)

You are in luck as this is exactly what I did yesterday. :D
I tried to make a small addon that allows my actionbar to fade to 20% instead of completely vanishing from screen when I set it to automatic in the settings.

First we need to create a timeline. This can either be done in lua or xml, but I personally think xml might bit a bit more readable for animations.

Code:

<GuiXml>

        <Animations>

                <AnimationTimeline name="MyActionBarFadeAnimation">

                        <Animations>

                                <AlphaAnimation duration="200" startAlpha="0.0" endAlpha="1.0" />

                        </Animations>

                </AnimationTimeline>

        </Animations>

</GuiXml>

This should be pretty self explanatory. We define a timeline and tell it to change the alpha value over a certain time.

Next step is to instantiate this timeline. We also need to get a reference to the alpha animation as we want to set the alpha values in lua so we can add a settings panel in the future.

Code:

        local startAlpha, endAlpha = 0.2, 0.8 -- we also set it to 80% transparency so it is see through when it is active

        local animation = ANIMATION_MANAGER:CreateTimelineFromVirtual("MyActionBarFadeAnimation")

        local alphaAnimation = animation:GetFirstAnimation()

        alphaAnimation:SetAlphaValues(startAlpha, endAlpha)

With this the animation is ready for use, but we have not connected it to the actionbar yet.
The actionbar already uses a fade animation and calls SetHidden once it has finished fading out.
So in order to get this animation to work there are some things we have to do:

Replace the default animation with our custom animation
Prevent the actionbar from hiding with SetHidden
Hide the actionbar when a menu is shown

Replacing the animation is not hard. The action bar uses a ZO_HUDFadeSceneFragment which has a method GetAnimation that returns self.animation, so all we have to do is set the animation field and apply the animation to the control element.

Code:

        ACTION_BAR_FRAGMENT.animation = animation

        animation:ApplyAllAnimationsToControl(ACTION_BAR_FRAGMENT.control)

With this we still see nothing in game. We have to take control over SetHidden first.
The ZO_HUDFadeSceneFragment calls SetHidden in two places ACTION_BAR_FRAGMENT.animationReverseOnStop and ACTION_BAR_FRAGMENT.Show.

We simply replace animationReverseOnStop with a custom method:

Code:

        local hidden = true -- we use this to replace the logic of SetHidden, otherwise the action bar will behave weirdly

        ACTION_BAR_FRAGMENT.animationReverseOnStop = function(timeline, completed)

                if(completed) then

                        hidden = true

                        control:SetAlpha(startAlpha)

                        ACTION_BAR_FRAGMENT:OnHidden()

                end

        end

The Show method does some more stuff, so we add a PreHook and only change what we need:

Code:

        ZO_PreHook(ACTION_BAR_FRAGMENT, "Show", function(self, customShowDuration)

                if(not animation:IsPlaying()) then

                        if(hidden) then

                                hidden = false

                                animation:SetHandler("OnStop", self.animationOnStop)

                                alphaAnimation:SetDuration(customShowDuration or self.showDuration)

                                animation:PlayFromStart()

                        end

                        return true -- this prevents the original method from running

                end

        end)

And set the initial values:

Code:

        control:SetHidden(false)

        control:SetAlpha(startAlpha)

Now the actionbar will fade from 80% to 20% opacity, but when we open a menu we still see it.
To fix this we add a callback to scenemanager and listen for the hud changing its state:

Code:

        local hud = SCENE_MANAGER:GetScene("hud") -- default hud scene

        local hudui = SCENE_MANAGER:GetScene("hudui") -- mouse enabled hud scene

        SCENE_MANAGER:RegisterCallback("SceneStateChanged", function(scene, oldState, newState)

                if(scene == hud or scene == hudui) then

                        control:SetHidden(not (hud:IsShowing() or hudui:IsShowing()))

                end

        end)

Voila! The actionbar now always stays visible but does not distract from the scenery when we are out of combat. :)

As you can see from this example, animations are quite simple to use.

Create a template in xml
Instantiate the template in lua with CreateTimelineFromVirtual
Apply the timeline to a control with ApplyAllAnimationsToControl
Set custom values as needed
Start the animation on certain events (OnMouseEnter, OnMouseExit)

Warning: Spoiler

Code:

        local startAlpha, endAlpha = 0.2, 0.8

        local control = ACTION_BAR_FRAGMENT.control



        local animation = ANIMATION_MANAGER:CreateTimelineFromVirtual("MyActionBarFadeAnimation")

        local alphaAnimation = animation:GetFirstAnimation()

        alphaAnimation:SetAlphaValues(startAlpha, endAlpha)



        local hidden = true



        ACTION_BAR_FRAGMENT.animationReverseOnStop = function(timeline, completed)

                if(completed) then

                        hidden = true

                        control:SetAlpha(startAlpha)

                        ACTION_BAR_FRAGMENT:OnHidden()

                end

        end



        ZO_PreHook(ACTION_BAR_FRAGMENT, "Show", function(self, customShowDuration)

                if(not animation:IsPlaying()) then

                        if(hidden) then

                                hidden = false

                                animation:SetHandler("OnStop", self.animationOnStop)

                                alphaAnimation:SetDuration(customShowDuration or self.showDuration)

                                animation:PlayFromStart()

                        end

                        return true

                end

        end)



        animation:ApplyAllAnimationsToControl(control)

        control:SetHidden(false)

        control:SetAlpha(startAlpha)



        ACTION_BAR_FRAGMENT.animation = animation



        local hud = SCENE_MANAGER:GetScene("hud")

        local hudui = SCENE_MANAGER:GetScene("hudui")

        SCENE_MANAGER:RegisterCallback("SceneStateChanged", function(scene, oldState, newState)

                if(scene == hud or scene == hudui) then

                        control:SetHidden(not (hud:IsShowing() or hudui:IsShowing()))

                end

        end)

Thank you both very much, extremely helpful!