LuaLibraryAnimate.wiki
author Wuzzy
Wed, 21 Jun 2023 12:50:32 +0000
changeset 2242 031a5b86e533
parent 2241 20ed85eb3d29
child 2243 e58371e25834
permissions -rw-r--r--
LuaLibraryAnimate: Say what happens after animation ends
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
1374
ec15ffae2f19 LuaLibraryAnimate: summary
Wuzzy
parents: 1347
diff changeset
     1
#summary Lua library documentation of Animate; for cinematics, cut-scenes and other nice animations
1347
6f4593e46a93 LuaLibraryAnimate: labels
Wuzzy
parents: 1338
diff changeset
     2
#labels !LuaLibrary
2103
612f6f103787 LuaLibraryAnimate: add newline
Wuzzy
parents: 2077
diff changeset
     3
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     4
= Lua library: `Animate` =
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
     5
<wiki:toc max_depth="3" />
1329
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
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
     8
== Structure of an Animate script ==
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
     9
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    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.
2236
47493b26d4ee LuaLibraryAnimate: "Getting started" section
Wuzzy
parents: 2235
diff changeset
    11
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    12
=== Initial code ===
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    13
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    14
For every script using this library, the following lines need to be at the beginning of `onGameTick`:
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
<code language="lua">function onGameTick()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
    AnimUnWait()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
    if ShowAnimation() == false then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
        return
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
    ExecuteAfterAnimations()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
    CheckEvents()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    23
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
2236
47493b26d4ee LuaLibraryAnimate: "Getting started" section
Wuzzy
parents: 2235
diff changeset
    25
Also, `AnimInit()` needs to be called in `onGameInit()`:
47493b26d4ee LuaLibraryAnimate: "Getting started" section
Wuzzy
parents: 2235
diff changeset
    26
47493b26d4ee LuaLibraryAnimate: "Getting started" section
Wuzzy
parents: 2235
diff changeset
    27
<code language="lua">function onGameInit()
47493b26d4ee LuaLibraryAnimate: "Getting started" section
Wuzzy
parents: 2235
diff changeset
    28
    AnimInit()
47493b26d4ee LuaLibraryAnimate: "Getting started" section
Wuzzy
parents: 2235
diff changeset
    29
end</code>
47493b26d4ee LuaLibraryAnimate: "Getting started" section
Wuzzy
parents: 2235
diff changeset
    30
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    31
Each of these functions will be explained below.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    32
2238
b559153c707a LuaLibraryAnimate: fix format
Wuzzy
parents: 2237
diff changeset
    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.
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    34
2238
b559153c707a LuaLibraryAnimate: fix format
Wuzzy
parents: 2237
diff changeset
    35
Also, you *must not* call `SetCinematicMode` ever in your script.
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    36
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    37
=== Steps ===
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    38
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    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:
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    40
2238
b559153c707a LuaLibraryAnimate: fix format
Wuzzy
parents: 2237
diff changeset
    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.
b559153c707a LuaLibraryAnimate: fix format
Wuzzy
parents: 2237
diff changeset
    42
 * `args` is a list containing the arguments that need to be passed to the function given, in the same order
b559153c707a LuaLibraryAnimate: fix format
Wuzzy
parents: 2237
diff changeset
    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.
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    44
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    45
Example 1:
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    46
<code language="lua">
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    47
    -- This calls `AnimSay(myHog, "Snails! SNAILS!", SAY_SAY, 3000)`,
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    48
    -- meaning the hedgehog gear `myHog` will say "Snails!" and set the animation delay to 3000 milliseconds
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    49
    -- Because `swh` is not set, it is true, so `myHog` also becomes the current hedgehog
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    50
    local step1 = {func = AnimSay, args = {myHog, "Snails!", SAY_SAY, 3000}}
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    51
</code>
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    52
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    53
Example 2:
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    54
<code language="lua">
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    55
    -- Moves myHog to the left
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    56
    local step2 = {func = AnimMove, args = {myHog, "Left", 2000, 0}}
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    57
</code>
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    58
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    59
Example 3:
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    60
<code language="lua">
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    61
    -- Shows the caption "Hello, world!". Because argument 1 is not a hedgehog, `swh` is false
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    62
    local step3 = {func = AddCaption, swh = false, args = {"Hello, world!"}}
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    63
</code>
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    64
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    65
=== How animation works ===
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    66
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    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.
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    68
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    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.)
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    70
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    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.
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    72
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    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.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    74
2242
031a5b86e533 LuaLibraryAnimate: Say what happens after animation ends
Wuzzy
parents: 2241
diff changeset
    75
Once all animations in the animation list have been played, the game returns to the *Not Animating* state and behaves normally again.
031a5b86e533 LuaLibraryAnimate: Say what happens after animation ends
Wuzzy
parents: 2241
diff changeset
    76
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    77
== Function reference ==
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    78
=== Cinematic handling ===
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    79
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    80
==== `AnimInit([startAnimating])` ====
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    81
Initializes variables used by the other functions. Needs to be called in `onGameInit`.
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    82
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 1985
diff changeset
    83
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.
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    84
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    85
==== `AnimInsertStepNext(step)` ====
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    86
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.
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    87
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    88
Example:
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    89
<code language="lua">function BlowHog(deadHog)
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    90
  AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    91
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    92
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    93
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    94
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    95
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    96
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    97
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    98
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    99
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   100
end
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   101
cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code>
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   102
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   103
==== `ShowAnimation()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   104
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
   105
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   106
==== `Animate(steps)` ====
1383
75735c1890c7 LuaLibraryAnimate: Add TOC
Wuzzy
parents: 1382
diff changeset
   107
*THIS FUNCTION IS UNDOCUMENTED!*
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   108
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   109
==== `AddAnim(steps)` ====
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   110
Adds `steps` to the array of animations, where `steps` is a table with numbers as keys and the values are animation steps. See the introduction above for the syntax of animation steps.
1329
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
Example:
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   113
<code language="lua">
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   114
-- 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 ..."
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   115
cinem = {
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   116
    {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}},
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   117
    {func = AnimMove, args = {myHog, "Left", 2000, 0}},
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   118
    {func = AddCaption, swh = false, args = {"But he found no more snails ..."}}
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   119
}
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   120
AddAnim(cinem)</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   121
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   122
==== `RemoveAnim(steps)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   123
Removes `steps` from the animations array.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   124
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   125
==== `AddSkipFunction(anim, func, args)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   126
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
   127
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   128
<code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   129
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   130
==== `RemoveSkipFunction(anim)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   131
Removes the skip function associated with `anim`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   132
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   133
==== `SetAnimSkip(bool)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   134
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
   135
1866
0b12f567dfe3 LuaLibraryAnimate: Update SetAnimSkip for 1.0.0
Wuzzy
parents: 1517
diff changeset
   136
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.
0b12f567dfe3 LuaLibraryAnimate: Update SetAnimSkip for 1.0.0
Wuzzy
parents: 1517
diff changeset
   137
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   138
Example:
1866
0b12f567dfe3 LuaLibraryAnimate: Update SetAnimSkip for 1.0.0
Wuzzy
parents: 1517
diff changeset
   139
<code language="lua">function onPreciseLocal()
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   140
    if AnimInProgress() then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   141
        SetAnimSkip(true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   142
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   143
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   144
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   145
==== `AnimInProgress()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   146
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
   147
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   148
==== `ExecuteAfterAnimations()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   149
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
   150
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   151
==== `AddFunction(element)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   152
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
   153
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   154
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   155
<code language="lua">AddFunction({func = AfterCinem, args = {2}})</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   156
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   157
==== `RemoveFunction()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   158
Removes the first function from the aforementioned list.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   159
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   160
==== `AnimUnWait()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   161
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
   162
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   163
==== `AnimSetInputMask(inputMask)` ====
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   164
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.
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   165
2235
19ffaf4bf91a LuaLibraryAnimate: Fix some typos and grammar
Wuzzy
parents: 2103
diff changeset
   166
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`.
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   167
2235
19ffaf4bf91a LuaLibraryAnimate: Fix some typos and grammar
Wuzzy
parents: 2103
diff changeset
   168
If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animate library!
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   169
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   170
=== Cinematic functions ===
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   171
These are the functions you can specify in animation steps.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   172
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   173
==== `AnimSwitchHog(gear)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   174
Switches to `gear` and follows it.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   175
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   176
==== `AnimGiveState(gear, state)` ====
1909
4bf4dda860e2 LuaLibraryAnimate: Clarify AnimGiveState
Wuzzy
parents: 1866
diff changeset
   177
Sets the [States gear state] of `gear` to `state` (full bitmask).
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   178
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   179
==== `AnimRemoveState(gear, state)` ====
1385
93a09090d23f LuaLibraryAnimate: fix link
Wuzzy
parents: 1384
diff changeset
   180
Removes the [States gear state] `state` from `gear`.
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   181
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   182
==== `AnimWait(gear, time)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   183
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
   184
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   185
==== `AnimSay(gear, text, manner, time)` ====
2235
19ffaf4bf91a LuaLibraryAnimate: Fix some typos and grammar
Wuzzy
parents: 2103
diff changeset
   186
Calls `HogSay` with the first three arguments and increases the wait time by `time`.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   187
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   188
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   189
<code language="lua">cinem = {
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   190
    {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
   191
    {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
   192
   }</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   193
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   194
==== `AnimSound(gear, sound, time)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   195
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
   196
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   197
==== `AnimTurn(hog, dir)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   198
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
   199
2241
20ed85eb3d29 LuaLibraryAnimate: Add maxMoveTime to AnimMove
Wuzzy
parents: 2240
diff changeset
   200
==== `AnimMove(hog, dir, x, y, maxMoveTime)` ====
20ed85eb3d29 LuaLibraryAnimate: Add maxMoveTime to AnimMove
Wuzzy
parents: 2240
diff changeset
   201
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.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   202
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   203
==== `AnimJump(hog, jumpType)` ====
2240
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   204
Makes `hog` perform a jump of type `jumpType`, where `jumpType` is one of:
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   205
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   206
 * `"long"`: Long jump
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   207
 * `"high"`: High jump
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   208
 * `"back"`: Backjump
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   209
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   210
==== `AnimSetGearPosition(gear, x, y, fall)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   211
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
   212
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   213
==== `AnimDisappear(gear, x, y)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   214
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
   215
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   216
==== `AnimOutOfNowhere(gear [, x, y])` ====
1985
39daa8abac0b LuaLibraryAnimate: Optional args in AnimOutOfNowhere
Wuzzy
parents: 1909
diff changeset
   217
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.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   218
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   219
==== `AnimTeleportGear(gear, x, y)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   220
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
   221
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   222
==== `AnimVisualGear(gear, x, y, vgType, state, critical)` ====
1517
b614c9c0898c LuaLibraryAnimate: AnimVisualGear: fix param count
Wuzzy
parents: 1516
diff changeset
   223
Calls `AddVisualGear` with arguments second to sixth. `gear` is for compatibility only.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   224
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   225
==== `AnimCaption(gear, text, time)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   226
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
   227
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   228
==== `AnimCustomFunction(gear, func, args)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   229
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
   230
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   231
Example:
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   232
<code language="lua">
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   233
-- Make hog1 and hog2 look at each other
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   234
function NeedToTurn(hog1, hog2)
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   235
   if GetX(hog1) < GetX(hog2) then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   236
      HogTurnLeft(hog1, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   237
      HogTurnLeft(hog2, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   238
   else
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   239
      HogTurnLeft(hog2, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   240
      HogTurnLeft(hog1, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   241
   end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   242
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   243
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   244
cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hog2}}}}</code>
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   245
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   246
=== Event handling ===
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   247
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   248
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
   249
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   250
==== `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   251
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
   252
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   253
Example:
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   254
<code language="lua">
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   255
--[[
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   256
This code shows the mission text "Nice Work" if the hog `myHog` has an X coordinate above 1500, but only once.
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   257
Also, it immediately gives `myHog` 5 grenades once it runs out of grenades. It does that every time this happens.
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   258
]]
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   259
function CheckPos()
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   260
   return GetX(myHog) > 1500
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   261
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   262
function CheckAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   263
   return GetAmmoCount(myHog, amGrenade) == 0
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   264
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   265
function DoPos()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   266
   ShowMission("Scooter", "Mover", "Nice Work", 0, 0)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   267
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   268
function DoAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   269
   AddAmmo(myHog, amGrenade, 5)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   270
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   271
AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   272
AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   273
</code>
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   274
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   275
==== `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   276
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
   277
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   278
==== `RemoveEventFunc(cFunc, cArgs)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   279
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
   280
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   281
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   282
<code language="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   283
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   284
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   285
AddEvent(condFunc2, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   286
AddEvent(condFunc2, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   287
RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   288
RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   289
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   290
==== `CheckEvents()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   291
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
   292
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   293
=== Misc. ===
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   294
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   295
==== `StoppedGear(gear)` ====
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   296
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.