LuaLibraryAnimate.wiki
author Wuzzy <almikes@aol.com>
Wed, 30 Oct 2019 11:59:37 +0100
changeset 2077 514babfbad9e
parent 1985 39daa8abac0b
child 2103 612f6f103787
permissions -rw-r--r--
Remove outdated legacy hints as clutter
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
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     3
= Lua library: `Animate` =
1383
75735c1890c7 LuaLibraryAnimate: Add TOC
Wuzzy
parents: 1382
diff changeset
     4
<wiki:toc max_depth="2" />
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     5
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
     6
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     7
In order to use its full potential, the following lines need to be at the beginning of `onGameTick`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     8
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
     9
<code language="lua">function onGameTick()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    10
    AnimUnWait()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    11
    if ShowAnimation() == false then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    12
        return
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    13
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    14
    ExecuteAfterAnimations()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    15
    CheckEvents()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    16
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    17
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    18
Also, `AnimInit()` needs to be called in `onGameInit()`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    19
Each of these functions will be explained below.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    20
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    21
Note: The Animate library will direclty overwrite the input mask with `SetInputMask`. If you already use this function in your script, it might lead to conflicts. Use `AnimSetInputMask` to set the input mask in a manner that is compatible with the Animate library.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    22
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    23
== Cinematic handling ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    24
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    25
=== `AnimInit([startAnimating])` ===
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    26
Initializes variables used by the other functions. Needs to be called in `onGameInit`.
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    27
2077
514babfbad9e Remove outdated legacy hints as clutter
Wuzzy <almikes@aol.com>
parents: 1985
diff changeset
    28
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
    29
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    30
=== `AnimInsertStepNext(step)` ===
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    31
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
    32
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    33
Example:
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    34
<code language="lua">function BlowHog(deadHog)
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    35
  AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    36
  AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    37
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    38
  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
    39
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    40
  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
    41
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    42
  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
    43
  AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}})
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    44
  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
    45
end
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    46
cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code>
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
    47
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    48
=== `ShowAnimation()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    49
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
    50
1383
75735c1890c7 LuaLibraryAnimate: Add TOC
Wuzzy
parents: 1382
diff changeset
    51
=== `Animate(steps)` ===
75735c1890c7 LuaLibraryAnimate: Add TOC
Wuzzy
parents: 1382
diff changeset
    52
*THIS FUNCTION IS UNDOCUMENTED!*
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
    53
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    54
=== `AddAnim(steps)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    55
Adds `steps` to the array of animations, where `steps` is a table with numbers as keys and elements of the following form. Each step is a table having the following keys: `func`, `args`, `swh`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    56
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    57
  * `func` is the function to be executed. It can be any function that returns false when it needs to be called again in following game ticks (e.g. `AnimMove`). It can be one of the cinematic functions.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    58
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    59
  * `args` is a table containing the arguments that need to be passed to the function given
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    60
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    61
  * `swh` is an optional boolean value that defaults to `true` and denotes whether the current hedgehog should be switched to the hog given as argument.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    62
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    63
<code language="lua">cinem = {
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    64
    {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}},
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    65
    {func = AnimMove, args = {myhog, "Left", 2000, 0}},
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    66
    {func = AddCaption, swh = false, args = {"But he found no more snails..."}}
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    67
    }
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    68
AddAnim(cinem)</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    69
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    70
=== `RemoveAnim(steps)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    71
Removes `steps` from the animations array.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    72
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    73
=== `AddSkipFunction(anim, func, args)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    74
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
    75
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    76
<code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    77
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    78
=== `RemoveSkipFunction(anim)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    79
Removes the skip function associated with `anim`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    80
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    81
=== `SetAnimSkip(bool)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    82
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
    83
1866
0b12f567dfe3 LuaLibraryAnimate: Update SetAnimSkip for 1.0.0
Wuzzy
parents: 1517
diff changeset
    84
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
    85
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    86
Example:
1866
0b12f567dfe3 LuaLibraryAnimate: Update SetAnimSkip for 1.0.0
Wuzzy
parents: 1517
diff changeset
    87
<code language="lua">function onPreciseLocal()
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    88
    if AnimInProgress() then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    89
        SetAnimSkip(true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    90
    end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    91
end</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    92
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    93
=== `AnimInProgress()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    94
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
    95
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    96
=== `ExecuteAfterAnimations()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    97
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
    98
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
    99
=== `AddFunction(element)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   100
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
   101
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   102
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   103
<code language="lua">AddFunction({func = AfterCinem, args = {2}})</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   104
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   105
=== `RemoveFunction()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   106
Removes the first function from the aforementioned list.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   107
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   108
=== `AnimUnWait()` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   109
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
   110
1384
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   111
=== `AnimSetInputMask(inputMask)` ===
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   112
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
   113
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   114
Internally, the input mask you provide is simply AND-ed with the input mask used by the Animate library. Otherwise, this function works lik `SetInputMask`.
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   115
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   116
If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animatel library!
1edf2e41b626 LuaLibraryAnimate: Move stuff around
Wuzzy
parents: 1383
diff changeset
   117
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   118
== Cinematic functions ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   119
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   120
=== `AnimSwitchHog(gear)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   121
Switches to `gear` and follows it.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   122
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   123
=== `AnimGiveState(gear, state)` ===
1909
4bf4dda860e2 LuaLibraryAnimate: Clarify AnimGiveState
Wuzzy
parents: 1866
diff changeset
   124
Sets the [States gear state] of `gear` to `state` (full bitmask).
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   125
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   126
=== `AnimRemoveState(gear, state)` ===
1385
93a09090d23f LuaLibraryAnimate: fix link
Wuzzy
parents: 1384
diff changeset
   127
Removes the [States gear state] `state` from `gear`.
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   128
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   129
=== `AnimWait(gear, time)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   130
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
   131
1386
3a6e995ec041 LuaLibraryAnimate: fix missing bracket
Wuzzy
parents: 1385
diff changeset
   132
=== `AnimSay(gear, text, manner, time)` ===
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   133
Calls `HogSay` with the first three arguments and increses the wait time by `time`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   134
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   135
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   136
<code language="lua">cinem = {
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   137
    {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
   138
    {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
   139
   }</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   140
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   141
=== `AnimSound(gear, sound, time)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   142
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
   143
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   144
=== `AnimTurn(hog, dir)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   145
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
   146
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   147
=== `AnimMove(hog, dir, x, y)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   148
Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   149
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   150
=== `AnimJump(hog, jumpType)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   151
Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`.
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   152
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   153
=== `AnimSetGearPosition(gear, x, y, fall)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   154
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
   155
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   156
=== `AnimDisappear(gear, x, y)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   157
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
   158
1985
39daa8abac0b LuaLibraryAnimate: Optional args in AnimOutOfNowhere
Wuzzy
parents: 1909
diff changeset
   159
=== `AnimOutOfNowhere(gear [, x, y])` ===
39daa8abac0b LuaLibraryAnimate: Optional args in AnimOutOfNowhere
Wuzzy
parents: 1909
diff changeset
   160
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
   161
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   162
=== `AnimTeleportGear(gear, x, y)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   163
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
   164
1516
4b3e233e5ac0 LuaLibraryAnimate: Remove follow argument from AnimVisualGear
Wuzzy
parents: 1387
diff changeset
   165
=== `AnimVisualGear(gear, x, y, vgType, state, critical)` ===
1517
b614c9c0898c LuaLibraryAnimate: AnimVisualGear: fix param count
Wuzzy
parents: 1516
diff changeset
   166
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
   167
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   168
=== `AnimCaption(gear, text, time)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   169
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
   170
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   171
=== `AnimCustomFunction(gear, func, args)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   172
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
   173
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   174
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   175
<code language="lua">function NeedToTurn(hog1, hog2)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   176
   if GetX(hog1) < GetX(hog2) then
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   177
      HogTurnLeft(hog1, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   178
      HogTurnLeft(hog2, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   179
   else
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   180
      HogTurnLeft(hog2, false)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   181
      HogTurnLeft(hog1, true)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   182
   end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   183
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   184
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   185
cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   186
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   187
== Event handling ==
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   188
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   189
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
   190
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   191
=== `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   192
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
   193
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   194
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   195
<code language="lua">function CheckPos()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   196
   return GetX(myHog) > 1500
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   197
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   198
function CheckAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   199
   return GetAmmoCount(myHog, amGrenade) == 0
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   200
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   201
function DoPos()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   202
   ShowMission("Scooter", "Mover", "Nice Work", 0, 0)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   203
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   204
function DoAmmo()
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   205
   AddAmmo(myHog, amGrenade, 5)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   206
end
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   207
AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   208
AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   209
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   210
=== `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   211
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
   212
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   213
=== `RemoveEventFunc(cFunc, cArgs)` ===
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   214
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
   215
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   216
Example:
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   217
<code language="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   218
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   219
AddEvent(condFunc1, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   220
AddEvent(condFunc2, condArgs1, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   221
AddEvent(condFunc2, condArgs2, doFunc, doArgs)
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   222
RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   223
RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code>
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   224
1387
8d095c221b3d LuaLibraryAnimate: add CheckEvents brackets
Wuzzy
parents: 1386
diff changeset
   225
=== `CheckEvents()` ===
1329
bd781e19a52d Split Lua libraries into several sub-pages
Wuzzy <almikes@aol.com>
parents:
diff changeset
   226
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
   227
1382
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   228
== Misc. ==
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   229
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   230
=== `StoppedGear(gear)` ===
8d6310a05033 LuaLibraryAnimate: StoppedGear and other funcs
Wuzzy
parents: 1374
diff changeset
   231
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.