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

#labels !LuaLibrary

= Lua library: `Animate` =

<wiki:toc max_depth="2" />

This library provides functions that aid cinematic/cut-scene creation and functions for handling events.

In order to use its full potential, 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()`.

Each of these functions will be explained below.

Note: The Animate library will direclty overwrite the input mask with `SetInputMask`. If you already use this function in your script, it might lead to conflicts. Use `AnimSetInputMask` to set the input mask in a manner that is compatible with the Animate library.

== Cinematic handling ==

=== `AnimInit([startAnimating])` ===

Initializes variables used by the other functions. Needs to be called in `onGameInit`.

=== `AnimInsertStepNext(step)` ===

Inserts `step` after the current step (read: action) in the cinematic array. 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">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

cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code>

=== `ShowAnimation()` ===

Performs the current action in the cinematic and returns `true` if finished, otherwise `false`. It needs to be used in `onGameTick`. Cut-scenes need to be added with `AddAnim(steps)`.

=== `Animate(steps)` ===

*THIS FUNCTION IS UNDOCUMENTED!*

=== `AddAnim(steps)` ===

Adds `steps` to the array of animations, where `steps` is a table with numbers as keys and elements of the following form. Each step is a table having the following keys: `func`, `args`, `swh`.

  * `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 can be one of the cinematic functions.

  * `args` is a table containing the arguments that need to be passed to the function given

  * `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.

Example:

<code language="lua">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(steps)` ===

Removes `steps` from the animations array.

=== `AddSkipFunction(anim, func, args)` ===

Adds `func` to the array of functions used to skip animations, associating it with `anim`. When the animation is skipped (see below), the function is called with `args` as arguments.

Example:

<code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>

=== `RemoveSkipFunction(anim)` ===

Removes the skip function associated with `anim`.

=== `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 cinematic is currently taking place, `false` otherwise.

=== `ExecuteAfterAnimations()` ===

Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. 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 cinematic. `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 cinematics. 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 lik `SetInputMask`.

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

== Cinematic functions ==

=== `AnimSwitchHog(gear)` ===

Switches to `gear` and follows it.

=== `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`. `gear` is just for compatibility with `ShowAnimation`.

=== `AnimSay(gear, text, manner, time)` ===

Calls `HogSay` with the first three arguments and increses 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)` ===

Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`.

=== `AnimJump(hog, jumpType)` ===

Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`.

=== `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">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, hg2}}}}</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">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.