Tutorial 7: Animators
In this tutorial you will learn how to use animators.
Before starting this tutorial be sure to setup an empty project with the Setup Tutorial.
what are animators?
Animators are objects that animate renderable entities. for example, the AnimatorFaderOut object takes an entity and gradually decrease its opacity until completely invisible. when done, the animator may also remove the entity completely from its node.
Animators must be registered to the renderer object (or other 'AnimatorsQueue' object, as we'll see later), and usually they remove themselves once done.
Let's create an animator for example:
and that's it. when the sprite is removed all the animators will be removed with it.
More about Animators!
You can learn more about Animators with the following Advance Animators Tutorial!
That's it. :)
Now that you know about animators, it's time to learn about text!
First we create a sprite to run the attach an animator on. note that we set the blending mode of the sprite to BLEND_MODE_BLEND, because our chosen animator is a fader that works on opacity and without blending we will not see the transition.
Next we create the animator instance. note the usage of ness_make_ptr<>(...), which is an alias for make_shared<> and is faster then using 'new()' statement for Ness-engine pointers type. you can read more about this subject here.
AnimatorFaderOut constructor gets the following parameters:
target - the entity the animator animates.
removeTargetWhenDone - if true will remove the entity from its node when opacity hit 0.
fadeSpeed - how fast to fadeout the object. if 1.0f it will take the animator exactly 1 second to complete the fading transition, so 0.5f will take it two seconds.
timeUntilFadeOut - timer in seconds until the fading begins. 1.0f means waiting 1 second.
That's it. last thing we do is to register the animator to the renderer. note that this animator removes itself once done, but some animators don't have a clear ending (animators that go in loops) so you will need to remove those manually.
If you run the code above or the example code here you should see the sprite entity fading away after 1 second.
Can animators only animate Sprites?
No, Animators can animate any renderable entity and even nodes!
The following are some useful built-in animators you can use on your entities:
AnimatorColorShifter: change the color of the entity from color A to color B over a given period of time. remove itself from animators queue once done.
AnimatorFaderIn: fade the entity into the screen, from opacity 0 to opacity 1. remove itself from animators queue once done.
AnimatorFaderOut: fade the entity out of the screen, from opacity 1 to opacity 0. remove itself from animators queue once done, can also remove the entity itself when reach opacity 0.
AnimatorSprite: the animator we've seen in this tutorial, animate spritesheet steps.
AnimatorRotator: animator to rotate the entity over time.
AnimatorScaler: animator to scale the entity over time.
AnimatorMover: move the entity and can even support acceleration and max speed.
AnimatorsQueue is an entity that hold and manage a list of animators, and animate them when called. the main Animators Queue object you'll use is the renderer itself. You can inherit from this object to create a customized Animator Queues of your own.
From version 1.4 and above ness-engine comes with a built-in entity called AnimatedSprite, which is a sprite that is also an animators queue and you can register animators directly to it.
The advantage of this object is that all the animators related to the sprite are attached directly to it and are easier to manage. for example you can pause all the animators with one command or config them to stop when the entity is outside the screen. also, removing the animated sprite will also remove all the animators attached to it automatically.
another advantage is that the Animated Sprite is registered automatically when created from a scene node, so you don't need to register or remove it from any animators queue.
Here's an example of how to use an animated sprite:
// add the hello-world sprite to it
Ness::SpritePtr sprite = scene->create_sprite("hello_world.png");
// create the animator
// params: target, bool removeTargetWhenDone, float fadeSpeed, float timeUntilFadeOut
Ness::Animators::AnimatorFaderOutPtr anim = ness_make_ptr<Ness::Animators::AnimatorFaderOut>(sprite, true, 0.5f, 1.0f);
// create animated sprite example
Ness::AnimatedSpritePtr AnimSprite = scene->create_animated_sprite("hello_world.png");
AnimSprite->register_animator(ness_make_ptr<Ness::Animators::AnimatorColorShifter>(AnimSprite, Ness::Color::BLACK, Ness::Color::WHITE, 5.0f, 1.0f));