LuaLibraryAnimate.wiki
author Wuzzy
Wed, 02 May 2018 22:50:27 +0100
changeset 1334 d8462452d5e3
parent 1329 bd781e19a52d
child 1338 97ac5f54bc7f
permissions -rw-r--r--
LuaLibraryLocale: Edited via web interface
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     1
#summary Lua library documentation: Animate
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     2
#labels LuaLibrary
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     3
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     4
= Lua library: `Animate` =
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     6
This library provides functions that aid cinematic/cut-scene creation and functions for handling events.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     7
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     8
In order to use its full potential, the following lines need to be at the beginning of `onGameTick`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     9
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    10
<code language="lua">function onGameTick()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    11
    AnimUnWait()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    12
    if ShowAnimation() == false then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
        return
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
    ExecuteAfterAnimations()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
    CheckEvents()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
Also, `AnimInit()` needs to be called in `onGameInit()`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
Each of these functions will be explained below.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    23
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
== Cinematic handling ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    25
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    26
=== `ShowAnimation()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    27
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)`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    28
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    29
=== `AddAnim(steps)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    30
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`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
  * `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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    33
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    34
  * `args` is a table containing the arguments that need to be passed to the function given
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    35
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    36
  * `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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    37
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    38
<code language="lua">cinem = {
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    39
    {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}},
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    40
    {func = AnimMove, args = {myhog, "Left", 2000, 0}},
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    41
    {func = AddCaption, swh = false, args = {"But he found no more snails..."}}
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    42
    }
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    43
AddAnim(cinem)</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    44
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    45
=== `RemoveAnim(steps)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    46
Removes `steps` from the animations array.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    47
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    48
=== `AddSkipFunction(anim, func, args)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    49
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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    50
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    51
<code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    52
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    53
=== `RemoveSkipFunction(anim)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    54
Removes the skip function associated with `anim`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    55
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    56
=== `SetAnimSkip(bool)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    57
Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    58
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    59
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    60
<code language="lua">function onPrecise()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    61
    if AnimInProgress() then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    62
        SetAnimSkip(true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    63
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    64
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    65
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    66
=== `AnimInProgress()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    67
Returns `true` if a cinematic is currently taking place, `false` otherwise.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    68
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    69
=== `ExecuteAfterAnimations()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    70
Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. The best location for this function call is in `onGameTick`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    71
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    72
=== `AddFunction(element)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    73
Adds `element` to the functions array that are to be called after the cinematic. `element` is a table with the keys: `func`, `args`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    74
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    75
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    76
<code language="lua">AddFunction({func = AfterCinem, args = {2}})</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    77
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    78
=== `RemoveFunction()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    79
Removes the first function from the aforementioned list.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    80
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    81
=== `AnimInit([startAnimating])` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    82
Initializes variables used by the other functions. Needs to be called in `onGameInit`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    83
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    84
Since 0.9.23, 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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    85
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    86
=== `AnimUnWait()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    87
Decreases the wait time used by cinematics. It is best called in `onGameTick`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    88
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    89
== Cinematic functions ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    90
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    91
=== `AnimSwitchHog(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    92
Switches to `gear` and follows it.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    93
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    94
=== `AnimWait(gear, time)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    95
Increases the wait time by `time`. `gear` is just for compatibility with `ShowAnimation`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    96
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    97
=== `AnimSay(gear, text, manner, time` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    98
Calls `HogSay` with the first three arguments and increses the wait time by `time`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    99
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   100
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   101
<code language="lua">cinem = {
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   102
    {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}},
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   103
    {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}}
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   104
   }</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   105
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   106
=== `AnimSound(gear, sound, time)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   107
Plays the sound `sound` and increases the wait time by `time`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   108
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   109
=== `AnimTurn(hog, dir)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   110
Makes `hog` face in direction `dir`, where `dir` equals either `"Right"` or `"Left"`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   111
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   112
=== `AnimMove(hog, dir, x, y)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   113
Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   114
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   115
=== `AnimJump(hog, jumpType)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   116
Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   117
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   118
=== `AnimSetGearPosition(gear, x, y, fall)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   119
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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   120
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   121
=== `AnimDisappear(gear, x, y)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   122
Teleports the gear to (`x`, `y`), adding some effects at the previous position and sounds. Doesn’t follow the gear.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   123
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   124
=== `AnimOutOfNowhere(gear, x, y)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   125
Teleports the gear to (`x`, `y`), adding effects and sounds at the final position. Follows gear.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   126
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   127
=== `AnimTeleportGear(gear, x, y)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   128
Teleports the gear to (`x`, `y`), adding effects and sounds both at the starting position and the final position. Follows gear.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   129
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   130
=== `AnimVisualGear(gear, x, y, vgType, state, critical, follow)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   131
Calls `AddVisualGear` with arguments second to sixth. If the optional argument `follow` equals `true` then the gear is followed. `gear` is for compatibility only.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   132
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   133
=== `AnimCaption(gear, text, time)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   134
Adds `text` as caption and increases wait time by `time`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   135
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   136
=== `AnimCustomFunction(gear, func, args)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   137
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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   138
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   139
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   140
<code language="lua">function NeedToTurn(hog1, hog2)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   141
   if GetX(hog1) < GetX(hog2) then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   142
      HogTurnLeft(hog1, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   143
      HogTurnLeft(hog2, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   144
   else
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   145
      HogTurnLeft(hog2, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   146
      HogTurnLeft(hog1, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   147
   end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   148
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   149
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   150
cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   151
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   152
=== `AnimInsertStepNext(step)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   153
Inserts `step` after the current step (read: action) in the cinematic array. Useful when an action depends on variables (e.g. positoins). It can be used mostly with `AnimCustomFunction`. Note: In case of multiple consecutive calls, steps need to be added in reverse order.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   154
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   155
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   156
<code language="lua">function BlowHog(deadHog)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   157
  AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   158
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   159
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   160
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   161
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   162
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   163
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   164
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   165
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   166
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   167
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   168
cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   169
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   170
== Event handling ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   171
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   172
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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   173
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   174
=== `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   175
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).
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   176
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   177
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   178
<code language="lua">function CheckPos()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   179
   return GetX(myHog) > 1500
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   180
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   181
function CheckAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   182
   return GetAmmoCount(myHog, amGrenade) == 0
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   183
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   184
function DoPos()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   185
   ShowMission("Scooter", "Mover", "Nice Work", 0, 0)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   186
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   187
function DoAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   188
   AddAmmo(myHog, amGrenade, 5)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   189
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   190
AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   191
AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   192
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   193
=== `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   194
Does the same as `AddEvent`, but first checks if the event is already in the list so that it isn’t added twice.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   195
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   196
=== `RemoveEventFunc(cFunc, cArgs)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   197
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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   198
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   199
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   200
<code language="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   201
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   202
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   203
AddEvent(condFunc2, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   204
AddEvent(condFunc2, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   205
RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   206
RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   207
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   208
=== `CheckEvents` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   209
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`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   210
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   211
=== `AnimSetInputMask(inputMask)` (0.9.23) ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   212
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.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   213
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   214
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`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   215
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   216
If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animatel library!