8 == Getting started ==

     8 == Structure of an Animate script ==

     9 

     9 

    10 In order to use its full potential, the following lines need to be at the beginning of `onGameTick`:

    10 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.

    11 

    12 === Initial code ===

    13 

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

    29 Note: The Animate library will directly 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.

    33 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.

    34 

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

    36 

    37 === Steps ===

    38 

    39 The 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:

    40 

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

    42 * `args` is a list containing the arguments that need to be passed to the function given, in the same order

    43 * `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 hog or the argument list is empty.

    44 

    45 Example 1:

    46 <code language="lua">

    47     -- This calls `AnimSay(myHog, "Snails! SNAILS!", SAY_SAY, 3000)`,

    48     -- meaning the hedgehog gear `myHog` will say "Snails!" and set the animation delay to 3000 milliseconds

    49     -- Because `swh` is not set, it is true, so `myHog` also becomes the current hedgehog

    50     local step1 = {func = AnimSay, args = {myHog, "Snails!", SAY_SAY, 3000}}

    51 </code>

    52 

    53 Example 2:

    54 <code language="lua">

    55     -- Moves myHog to the left

    56     local step2 = {func = AnimMove, args = {myHog, "Left", 2000, 0}}

    57 </code>

    58 

    59 Example 3:

    60 <code language="lua">

    61     -- Shows the caption "Hello, world!". Because argument 1 is not a hedgehog, `swh` is false

    62     local step3 = {func = AddCaption, swh = false, args = {"Hello, world!"}}

    63 </code>

    64 

    65 === How animation works ===

    66 

    67 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.

    68 

    69 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.)

    70 

    71 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.

    72 

    73 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.

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

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

   203 <code language="lua">function CheckPos()

   248 <code language="lua">

   249 --[[

   250 This code shows the mission text "Nice Work" if the hog `myHog` has an X coordinate above 1500, but only once.

   251 Also, it immediately gives `myHog` 5 grenades once it runs out of grenades. It does that every time this happens.

   252 ]]

   253 function CheckPos()

   216 AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code>

   266 AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event

   267 </code>