LuaLibraryAnimate.wiki
author Wuzzy
Wed, 21 Jun 2023 13:56:48 +0000
changeset 2248 de14b46c7c16
parent 2247 fdd314eb697f
child 2249 dd8b0bad793a
permissions -rw-r--r--
LuaLibraryAnimate: Rename cinem variable to animation
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
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    37
=== Data structures ===
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    38
==== Animation step ====
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    39
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    40
The animation step step is the primary data structure of this library. A step is a single action in an animation specified in table form. A step table must have the following fields:
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    41
2238
b559153c707a LuaLibraryAnimate: fix format
Wuzzy
parents: 2237
diff changeset
    42
 * `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
    43
 * `args` is a list containing the arguments that need to be passed to the function given, in the same order
2244
e8e1c0dd32e5 LuaLibraryAnimate: Add AnimFollowGear
Wuzzy
parents: 2243
diff changeset
    44
 * `swh` is an optional boolean value that defaults to `true` and denotes whether the current hedgehog should be switched to the hog given as argument 1 in `args`. You *must* set this to `false` if argument 1 is not a hedgehog.
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    45
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    46
Example 1:
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    47
<code language="lua">
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    48
-- This calls `AnimSay(myHog, "Snails! SNAILS!", SAY_SAY, 3000)`,
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    49
-- meaning the hedgehog gear `myHog` will say "Snails!" and set the animation delay to 3000 milliseconds
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    50
-- Because `swh` is not set, it is true, so `myHog` also becomes the current hedgehog
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    51
local step1 = {func = AnimSay, args = {myHog, "Snails!", SAY_SAY, 3000}}
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    52
</code>
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    53
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    54
Example 2:
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    55
<code language="lua">
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    56
-- Moves myHog to the left
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    57
local step2 = {func = AnimMove, args = {myHog, "Left", 2000, 0}}
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    58
</code>
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    59
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    60
Example 3:
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    61
<code language="lua">
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    62
-- Shows the caption "Hello, world!". Because argument 1 is not a hedgehog, `swh` is false
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    63
local step3 = {func = AddCaption, swh = false, args = {"Hello, world!"}}
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    64
</code>
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    65
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    66
==== Animation ====
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    67
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    68
An animation is a data structure that is a sequence of animation steps. It is specified as a table of steps. The steps will be executed in the specified order.
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    69
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    70
==== Animation list ====
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    71
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    72
The animation list is a list of all animations that were added but not performed so far. This is an internal table, you can not access it directly. You add to the list with `AddAnim`.
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    73
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    74
=== How animation works ===
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    75
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    76
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
    77
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    78
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
    79
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    80
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
    81
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
    82
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
    83
2242
031a5b86e533 LuaLibraryAnimate: Say what happens after animation ends
Wuzzy
parents: 2241
diff changeset
    84
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
    85
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    86
== Function reference ==
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    87
=== Cinematic handling ===
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    88
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    89
==== `AnimInit([startAnimating])` ====
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    90
Initializes variables used by the other functions. Needs to be called in `onGameInit`.
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    91
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 1985
diff changeset
    92
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
    93
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
    94
==== `AnimInsertStepNext(step)` ====
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
    95
Inserts `step` after the current step (read: action) in the animation list. Useful when an action depends on variables (e.g. positions). It can be used mostly with `AnimCustomFunction`. Note: In case of multiple consecutive calls, steps need to be added in reverse order.
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    96
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    97
Example:
2246
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
    98
<code language="lua">-- Show explosion effects around hedgehog `liveHog`, then delete it
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
    99
function BlowHog(deadHog)
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   100
    AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   101
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   102
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   103
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   104
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   105
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   106
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   107
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   108
    AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
9cee5aab336d LuaLibraryAnimate: Explain BlowHog example better
Wuzzy
parents: 2245
diff changeset
   109
    AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false})
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   110
end
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   111
animation = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   112
AddAnim(animation)</code>
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   113
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   114
==== `ShowAnimation()` ====
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   115
Performs the first animation (if possible) in the animation list and removes it once it’s done. Returns `true` if the animation list was empty and no animation was played or `false` if an animation was played.
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   116
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   117
It needs to be used in `onGameTick`. Cut-scenes need to be added with `AddAnim(animation)`.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   118
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   119
==== `Animate(animation)` ====
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   120
Performs the specified animation manually. Returns `true` if the animation was performed successfully, `false` otherwise. This function is internally used; its use in scripts is not recommended.
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   121
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   122
==== `AddAnim(animation)` ====
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   123
Adds `animation` to the animation list. `animation` is a list of animation steps; see data structures above for details.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   124
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   125
Example:
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   126
<code language="lua">
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   127
-- 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 ..."
2248
de14b46c7c16 LuaLibraryAnimate: Rename cinem variable to animation
Wuzzy
parents: 2247
diff changeset
   128
animation = {
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   129
    {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}},
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   130
    {func = AnimMove, args = {myHog, "Left", 2000, 0}},
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   131
    {func = AddCaption, swh = false, args = {"But he found no more snails ..."}}
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   132
}
2248
de14b46c7c16 LuaLibraryAnimate: Rename cinem variable to animation
Wuzzy
parents: 2247
diff changeset
   133
AddAnim(animation)</code>
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   134
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   135
==== `RemoveAnim(animation)` ====
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   136
Removes `animation` from the animation list.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   137
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   138
==== `AddSkipFunction(animation, func, args)` ====
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   139
Adds `func` to the array of functions used to skip animations, associating it with `animation`. When the animation is skipped (see below), the function is called with `args` as arguments.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   140
Example:
2248
de14b46c7c16 LuaLibraryAnimate: Rename cinem variable to animation
Wuzzy
parents: 2247
diff changeset
   141
<code language="lua">AddSkipFunc(animation, myAnimationSkipFunction, {})</code>
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   142
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   143
==== `RemoveSkipFunction(animation)` ====
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   144
Removes the skip function associated with `animation`.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   145
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   146
==== `SetAnimSkip(bool)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   147
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
   148
1866
0b12f567dfe3 LuaLibraryAnimate: Update SetAnimSkip for 1.0.0
Wuzzy
parents: 1517
diff changeset
   149
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
   150
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   151
Example:
1866
0b12f567dfe3 LuaLibraryAnimate: Update SetAnimSkip for 1.0.0
Wuzzy
parents: 1517
diff changeset
   152
<code language="lua">function onPreciseLocal()
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   153
    if AnimInProgress() then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   154
        SetAnimSkip(true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   155
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   156
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   157
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   158
==== `AnimInProgress()` ====
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   159
Returns `true` if a amimation is currently taking place, `false` otherwise.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   160
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   161
==== `ExecuteAfterAnimations()` ====
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   162
Calls the functions (added with `AddFunction`) that need to be executed after the animation. The best location for this function call is in `onGameTick`.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   163
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   164
==== `AddFunction(element)` ====
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   165
Adds `element` to the functions array that are to be called after the animation. `element` is a table with the keys: `func`, `args`.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   166
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   167
Example:
2248
de14b46c7c16 LuaLibraryAnimate: Rename cinem variable to animation
Wuzzy
parents: 2247
diff changeset
   168
<code language="lua">AddFunction({func = myAfterAnim, args = {2}})</code>
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   169
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   170
==== `RemoveFunction()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   171
Removes the first function from the aforementioned list.
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
==== `AnimUnWait()` ====
2247
fdd314eb697f LuaLibraryAnimate: Explain Animate and more consistent wording
Wuzzy
parents: 2246
diff changeset
   174
Decreases the wait time used by animations. It is best called in `onGameTick`.
1329
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
==== `AnimSetInputMask(inputMask)` ====
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   177
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
   178
2235
19ffaf4bf91a LuaLibraryAnimate: Fix some typos and grammar
Wuzzy
parents: 2103
diff changeset
   179
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
   180
2235
19ffaf4bf91a LuaLibraryAnimate: Fix some typos and grammar
Wuzzy
parents: 2103
diff changeset
   181
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
   182
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   183
=== Cinematic functions ===
2245
3e97c75aaddc LuaLibraryAnimate: Clarify hog switching
Wuzzy
parents: 2244
diff changeset
   184
These are the functions you can specify in animation steps. Unless specified otherwise, the `gear` argument of each function switches the `CurrentHedgehog` to `gear` and follows it. This behavior can be disabled with `swh=false` (see definition of animation steps above).
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   185
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   186
==== `AnimSwitchHog(gear)` ====
2243
e58371e25834 LuaLibraryAnimate: Add AnimGearWait
Wuzzy
parents: 2242
diff changeset
   187
Switches the `CurrentHedgehog` to `gear` and follows it.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   188
2244
e8e1c0dd32e5 LuaLibraryAnimate: Add AnimFollowGear
Wuzzy
parents: 2243
diff changeset
   189
==== `AnimFollowGear(gear)` ====
e8e1c0dd32e5 LuaLibraryAnimate: Add AnimFollowGear
Wuzzy
parents: 2243
diff changeset
   190
Follows `gear`.
e8e1c0dd32e5 LuaLibraryAnimate: Add AnimFollowGear
Wuzzy
parents: 2243
diff changeset
   191
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   192
==== `AnimGiveState(gear, state)` ====
1909
4bf4dda860e2 LuaLibraryAnimate: Clarify AnimGiveState
Wuzzy
parents: 1866
diff changeset
   193
Sets the [States gear state] of `gear` to `state` (full bitmask).
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   194
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   195
==== `AnimRemoveState(gear, state)` ====
1385
93a09090d23f LuaLibraryAnimate: fix link
Wuzzy
parents: 1384
diff changeset
   196
Removes the [States gear state] `state` from `gear`.
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   197
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   198
==== `AnimWait(gear, time)` ====
2243
e58371e25834 LuaLibraryAnimate: Add AnimGearWait
Wuzzy
parents: 2242
diff changeset
   199
Increases the wait time by `time` (in milliseconds) without changing the `CurrentHedgehog`. The `gear` argument is ignored (it exists for compability with `ShowAnimation).
e58371e25834 LuaLibraryAnimate: Add AnimGearWait
Wuzzy
parents: 2242
diff changeset
   200
e58371e25834 LuaLibraryAnimate: Add AnimGearWait
Wuzzy
parents: 2242
diff changeset
   201
==== `AnimGearWait(gear, time)` ====
e58371e25834 LuaLibraryAnimate: Add AnimGearWait
Wuzzy
parents: 2242
diff changeset
   202
Increases the wait time by `time` (in milliseconds) and changes the `CurrentHedgehog` to `gear`.
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   203
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   204
==== `AnimSay(gear, text, manner, time)` ====
2235
19ffaf4bf91a LuaLibraryAnimate: Fix some typos and grammar
Wuzzy
parents: 2103
diff changeset
   205
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
   206
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   207
Example:
2248
de14b46c7c16 LuaLibraryAnimate: Rename cinem variable to animation
Wuzzy
parents: 2247
diff changeset
   208
<code language="lua">animation = {
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   209
    {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
   210
    {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}}
2248
de14b46c7c16 LuaLibraryAnimate: Rename cinem variable to animation
Wuzzy
parents: 2247
diff changeset
   211
}</code>
1329
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
==== `AnimSound(gear, sound, time)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   214
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
   215
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   216
==== `AnimTurn(hog, dir)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   217
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
   218
2241
20ed85eb3d29 LuaLibraryAnimate: Add maxMoveTime to AnimMove
Wuzzy
parents: 2240
diff changeset
   219
==== `AnimMove(hog, dir, x, y, maxMoveTime)` ====
20ed85eb3d29 LuaLibraryAnimate: Add maxMoveTime to AnimMove
Wuzzy
parents: 2240
diff changeset
   220
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
   221
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   222
==== `AnimJump(hog, jumpType)` ====
2240
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   223
Makes `hog` perform a jump of type `jumpType`, where `jumpType` is one of:
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   224
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   225
 * `"long"`: Long jump
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   226
 * `"high"`: High jump
c387af3810c6 LuaLibraryAnimate: Clarify AnimMove
Wuzzy
parents: 2239
diff changeset
   227
 * `"back"`: Backjump
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   228
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   229
==== `AnimSetGearPosition(gear, x, y, fall)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   230
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
   231
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   232
==== `AnimDisappear(gear, x, y)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   233
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
   234
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   235
==== `AnimOutOfNowhere(gear [, x, y])` ====
1985
39daa8abac0b LuaLibraryAnimate: Optional args in AnimOutOfNowhere
Wuzzy
parents: 1909
diff changeset
   236
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
   237
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   238
==== `AnimTeleportGear(gear, x, y)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   239
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
   240
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   241
==== `AnimVisualGear(gear, x, y, vgType, state, critical)` ====
1517
b614c9c0898c LuaLibraryAnimate: AnimVisualGear: fix param count
Wuzzy
parents: 1516
diff changeset
   242
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
   243
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   244
==== `AnimCaption(gear, text, time)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   245
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
   246
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   247
==== `AnimCustomFunction(gear, func, args)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   248
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
   249
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   250
Example:
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   251
<code language="lua">
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   252
-- Make hog1 and hog2 look at each other
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   253
function NeedToTurn(hog1, hog2)
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   254
   if GetX(hog1) < GetX(hog2) then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   255
      HogTurnLeft(hog1, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   256
      HogTurnLeft(hog2, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   257
   else
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   258
      HogTurnLeft(hog2, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   259
      HogTurnLeft(hog1, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   260
   end
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
2248
de14b46c7c16 LuaLibraryAnimate: Rename cinem variable to animation
Wuzzy
parents: 2247
diff changeset
   263
animation = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hog2}}}}</code>
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   264
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   265
=== Event handling ===
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   266
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   267
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
   268
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   269
==== `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   270
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
   271
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   272
Example:
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   273
<code language="lua">
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   274
--[[
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   275
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
   276
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
   277
]]
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   278
function CheckPos()
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   279
   return GetX(myHog) > 1500
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   280
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   281
function CheckAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   282
   return GetAmmoCount(myHog, amGrenade) == 0
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   283
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   284
function DoPos()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   285
   ShowMission("Scooter", "Mover", "Nice Work", 0, 0)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   286
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   287
function DoAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   288
   AddAmmo(myHog, amGrenade, 5)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   289
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   290
AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion
2237
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   291
AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event
dd92ebc28957 LuaLibraryAnimate: Extend the introduction
Wuzzy
parents: 2236
diff changeset
   292
</code>
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   293
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   294
==== `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   295
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
   296
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   297
==== `RemoveEventFunc(cFunc, cArgs)` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   298
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
   299
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   300
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   301
<code language="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   302
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   303
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   304
AddEvent(condFunc2, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   305
AddEvent(condFunc2, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   306
RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   307
RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   308
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   309
==== `CheckEvents()` ====
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   310
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
   311
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   312
=== Misc. ===
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   313
2239
fdf6721339eb LuaLibraryAnimate: Add new section for functions
Wuzzy
parents: 2238
diff changeset
   314
==== `StoppedGear(gear)` ====
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   315
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.