#summary Lua library documentation of Animate; for cinematics, cut-scenes and other nice animations
#labels !LuaLibrary

= Lua library: `Animate` =
<wiki:toc max_depth="3" />
This library provides functions that aid cinematic/cut-scene creation and functions for handling events.

== Structure of an Animate script ==

The Animate library is somewhat complex, so this section explains how scripts using the Animate library are supposed to look like and how the functions interact.

=== Initial code ===

For every script using this library, the following lines need to be at the beginning of `onGameTick`:

<code language="lua">function onGameTick()
    AnimUnWait()
    if ShowAnimation() == false then
        return
    end
    ExecuteAfterAnimations()
    CheckEvents()
end</code>

Also, `AnimInit()` needs to be called in `onGameInit()`:

<code language="lua">function onGameInit()
    AnimInit()
end</code>

Each of these functions will be explained below.

Also, if your script calls `SetInputMask`, you *must* replace each call of it with `AnimSetInputMask` (see function description below). Failing to do so may lead to bugs.

Also, you *must not* call `SetCinematicMode` ever in your script.

=== Data structures ===
==== Animation step ====

The animation step step is the primary data structure of this library. A step is a single action in an animation specified in table form. A step table must have the following fields:

 * `func` is the function to be executed. It can be any function that returns false when it needs to be called again in following game ticks (e.g. `AnimMove`). It could theoretically be any function, but usually you want to use one of the cinematic functions here.
 * `args` is a list containing the arguments that need to be passed to the function given, in the same order
 * `swh` is an optional boolean value that defaults to `true` and denotes whether the current hedgehog should be switched to the hog given as argument 1 in `args`. You *must* set this to `false` if argument 1 is not a hedgehog.

Example 1:
<code language="lua">
-- This calls `AnimSay(myHog, "Snails! SNAILS!", SAY_SAY, 3000)`,
-- meaning the hedgehog gear `myHog` will say "Snails!" and set the animation delay to 3000 milliseconds
-- Because `swh` is not set, it is true, so `myHog` also becomes the current hedgehog
local step1 = {func = AnimSay, args = {myHog, "Snails!", SAY_SAY, 3000}}
</code>

Example 2:
<code language="lua">
-- Moves myHog to the left
local step2 = {func = AnimMove, args = {myHog, "Left", 2000, 0}}
</code>

Example 3:
<code language="lua">
-- Shows the caption "Hello, world!". Because argument 1 is not a hedgehog, `swh` is false
local step3 = {func = AddCaption, swh = false, args = {"Hello, world!"}}
</code>

==== Animation ====

An animation is a data structure that is a sequence of animation steps. It is specified as a table of steps. The steps will be executed in the specified order.

==== Animation list ====

The animation list is a list of all animations that were added but not performed so far. This is an internal table, you can not access it directly. You add to the list with `AddAnim`.

=== How animation works ===

The Animation library has two states: *Animating* and *Not Animating*. By default, the game starts in the *Not Animating* state, meaning the game behaves normally. In *Animating* state, the library looks at the list of registered animations and executes them one by one, in that order.

You are expected to add to the list of animatinons with `AddAnim`. If the script is animating, this animation will be played after all the others have been played. If the script is not animating, the animation will be played immediately. (Assuming you have correctly added the boilerplate code mentioned at the beginning of this page.)

Animations are basically cut scenes. During animation, Cinematic Mode is enabled (see `SetCinematicMode` which is part of the main Lua API) and most player input is blocked. Animations can cause various things to happen, like move hedgehogs, show speech bubbles, explode the landscape or just call (almost) any function. During an animation, the player can only watch or optionally skip (details later). The player can still move the camera.

There is also an internal wait time. It starts at 0 and a few cinematic functions as well as `AnimWait` can increase this time. The wait time counts down to 0, during which the script waits to execute the next animation step. Adding to the wait time is important to time your animation correctly.

Once all animations in the animation list have been played, the game returns to the *Not Animating* state and behaves normally again.

== Function reference ==
=== Cinematic handling ===

==== `AnimInit([startAnimating])` ====
Initializes variables used by the other functions. Needs to be called in `onGameInit`.

An optional convenience parameter `startAnimating` is available; if set to `true`, the game will start in “animation” mode which enables cinematic mode and disables all controls except precise for skipping. This is useful if you want to indicate that an animation will be played right at the start and the player must not be allowed to use any controls before the animation is over. If you set this parameter to `true`, you also *must* play at least one animation after this, otherwise the game will be stuck.

==== `AnimInsertStepNext(step)` ====
Inserts `step` after the current step (read: action) in the animation list. Useful when an action depends on variables (e.g. positions). It can be used mostly with `AnimCustomFunction`. Note: In case of multiple consecutive calls, steps need to be added in reverse order.

Example:
<code language="lua">-- Show explosion effects around hedgehog `liveHog`, then delete it
function BlowHog(deadHog)
    AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false})
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false})
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
end
animation = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}
AddAnim(animation)</code>

==== `ShowAnimation()` ====
Performs the first animation (if possible) in the animation list and removes it once it’s done. Returns `true` if the animation list was empty and no animation was played or `false` if an animation was played.

It needs to be used in `onGameTick`. Cut-scenes need to be added with `AddAnim(animation)`.

==== `Animate(animation)` ====
Performs the specified animation manually. Returns `true` if the animation was performed successfully, `false` otherwise. This function is internally used; its use in scripts is not recommended.

==== `AddAnim(animation)` ====
Adds `animation` to the animation list. `animation` is a list of animation steps; see data structures above for details.

Example:
<code language="lua">
-- Makes myHog say "Snails! SNAILS!, wait 3 seconds, move it to the left until its X coordinate equals 2000, then show the caption "But he found no more snails ..."
cinem = {
    {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}},
    {func = AnimMove, args = {myHog, "Left", 2000, 0}},
    {func = AddCaption, swh = false, args = {"But he found no more snails ..."}}
}
AddAnim(cinem)</code>

==== `RemoveAnim(animation)` ====
Removes `animation` from the animation list.

==== `AddSkipFunction(animation, func, args)` ====
Adds `func` to the array of functions used to skip animations, associating it with `animation`. When the animation is skipped (see below), the function is called with `args` as arguments.
Example:
<code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>

==== `RemoveSkipFunction(animation)` ====
Removes the skip function associated with `animation`.

==== `SetAnimSkip(bool)` ====
Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation.

By convention, a cut scene in a singleplayer mission should be skipped when the player presses the Precise key. In this case, use the `onPreciseLocal` callback for this.

Example:
<code language="lua">function onPreciseLocal()
    if AnimInProgress() then
        SetAnimSkip(true)
    end
end</code>

==== `AnimInProgress()` ====
Returns `true` if a amimation is currently taking place, `false` otherwise.

==== `ExecuteAfterAnimations()` ====
Calls the functions (added with `AddFunction`) that need to be executed after the animation. The best location for this function call is in `onGameTick`.

==== `AddFunction(element)` ====
Adds `element` to the functions array that are to be called after the animation. `element` is a table with the keys: `func`, `args`.

Example:
<code language="lua">AddFunction({func = AfterCinem, args = {2}})</code>

==== `RemoveFunction()` ====
Removes the first function from the aforementioned list.

==== `AnimUnWait()` ====
Decreases the wait time used by animations. It is best called in `onGameTick`.

==== `AnimSetInputMask(inputMask)` ====
Call this function instead of `SetInputMask` if you want to set the input mask in a way that does not conflict with the Animate library.

Internally, the input mask you provide is simply AND-ed with the input mask used by the Animate library. Otherwise, this function works like `SetInputMask`.

If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animate library!

=== Cinematic functions ===
These are the functions you can specify in animation steps. Unless specified otherwise, the `gear` argument of each function switches the `CurrentHedgehog` to `gear` and follows it. This behavior can be disabled with `swh=false` (see definition of animation steps above).

==== `AnimSwitchHog(gear)` ====
Switches the `CurrentHedgehog` to `gear` and follows it.

==== `AnimFollowGear(gear)` ====
Follows `gear`.

==== `AnimGiveState(gear, state)` ====
Sets the [States gear state] of `gear` to `state` (full bitmask).

==== `AnimRemoveState(gear, state)` ====
Removes the [States gear state] `state` from `gear`.

==== `AnimWait(gear, time)` ====
Increases the wait time by `time` (in milliseconds) without changing the `CurrentHedgehog`. The `gear` argument is ignored (it exists for compability with `ShowAnimation).

==== `AnimGearWait(gear, time)` ====
Increases the wait time by `time` (in milliseconds) and changes the `CurrentHedgehog` to `gear`.

==== `AnimSay(gear, text, manner, time)` ====
Calls `HogSay` with the first three arguments and increases the wait time by `time`.

Example:
<code language="lua">cinem = {
    {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}},
    {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}}
   }</code>

==== `AnimSound(gear, sound, time)` ====
Plays the sound `sound` and increases the wait time by `time`.

==== `AnimTurn(hog, dir)` ====
Makes `hog` face in direction `dir`, where `dir` equals either `"Right"` or `"Left"`.

==== `AnimMove(hog, dir, x, y, maxMoveTime)` ====
Makes `hog` walk in direction `dir` (`"Right"` or `"Left"`) until either its horizontal coordinate equals `x` or its vertical coordinate equals `y`. `maxMoveTime` is optional. If specified, the animation will automatically end if this number of milliseconds have passed.

==== `AnimJump(hog, jumpType)` ====
Makes `hog` perform a jump of type `jumpType`, where `jumpType` is one of:

 * `"long"`: Long jump
 * `"high"`: High jump
 * `"back"`: Backjump

==== `AnimSetGearPosition(gear, x, y, fall)` ====
Sets the position of `gear` to (`x`, `y`). If the optional argument `fall` does not equal `false` then the gear is given a small falling velocity in order to get around exact positioning.

==== `AnimDisappear(gear, x, y)` ====
Teleports the gear to (`x`, `y`), adding some effects at the previous position and sounds. Doesn’t follow the gear.

==== `AnimOutOfNowhere(gear [, x, y])` ====
Teleports the gear to (`x`, `y`), adding effects and sounds at the final position. Follows gear. If `x` and `y` are not specified, gear will not teleport, only the animation is played.

==== `AnimTeleportGear(gear, x, y)` ====
Teleports the gear to (`x`, `y`), adding effects and sounds both at the starting position and the final position. Follows gear.

==== `AnimVisualGear(gear, x, y, vgType, state, critical)` ====
Calls `AddVisualGear` with arguments second to sixth. `gear` is for compatibility only.

==== `AnimCaption(gear, text, time)` ====
Adds `text` as caption and increases wait time by `time`.

==== `AnimCustomFunction(gear, func, args)` ====
Calls the function `func` with `args` as arguments. This function is useful, for instance, when the cinematic uses the position of a gear at the moment of execution. If `func` needs to be called in following game ticks then it should return false.

Example:
<code language="lua">
-- Make hog1 and hog2 look at each other
function NeedToTurn(hog1, hog2)
   if GetX(hog1) < GetX(hog2) then
      HogTurnLeft(hog1, false)
      HogTurnLeft(hog2, true)
   else
      HogTurnLeft(hog2, false)
      HogTurnLeft(hog1, true)
   end
end

cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hog2}}}}</code>

=== Event handling ===

Events are pairs of functions that are used to check for various conditions. One of them is for verification and, if it returns `true`, the second function is called.

==== `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
Adds the functions `condFunc` and `doFunc` to the events list. They get called with the respective args (`condArgs` and `doArgs`). `condFunc` will get called in every game tick until it returns `true` or is removed. Once it returns `true`, `doFunc` is called and they are or are not removed from the list, depending on `evType` (`0` for removal, `1` for keeping). An `evType` of `1` is useful for repeating actions (e.g. every time a hog gets damaged, do something).

Example:
<code language="lua">
--[[
This code shows the mission text "Nice Work" if the hog `myHog` has an X coordinate above 1500, but only once.
Also, it immediately gives `myHog` 5 grenades once it runs out of grenades. It does that every time this happens.
]]
function CheckPos()
   return GetX(myHog) > 1500
end
function CheckAmmo()
   return GetAmmoCount(myHog, amGrenade) == 0
end
function DoPos()
   ShowMission("Scooter", "Mover", "Nice Work", 0, 0)
end
function DoAmmo()
   AddAmmo(myHog, amGrenade, 5)
end
AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion
AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event
</code>

==== `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
Does the same as `AddEvent`, but first checks if the event is already in the list so that it isn’t added twice.

==== `RemoveEventFunc(cFunc, cArgs)` ====
Removes the event or events that have `cFunc` as the condition checking function. If `cArgs` does not equal `nil` then only those events get removed that have `cArgs` as arguments for `cFunc`, too.

Example:
<code language="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs)
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
AddEvent(condFunc2, condArgs1, doFunc, doArgs)
AddEvent(condFunc2, condArgs2, doFunc, doArgs)
RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1
RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>

==== `CheckEvents()` ====
Verifies all the condition functions in the events list and calls the respective ‘action’ functions if the conditions are met. If the `evType` of a completed event equals `0` then it is removed from the list. This function is best placed in `onGameTick`.

=== Misc. ===

==== `StoppedGear(gear)` ====
Returns `true` if the gear is considered to be resting (not moving). (dX and dY are very small) or if the gear does not exist.