|
1 #summary Lua library documentation: Animate |
|
2 #labels LuaLibrary |
|
3 |
|
4 = Lua library: `Animate` = |
|
5 |
|
6 This library provides functions that aid cinematic/cut-scene creation and functions for handling events. |
|
7 |
|
8 In order to use its full potential, the following lines need to be at the beginning of `onGameTick`. |
|
9 |
|
10 <code language="lua">function onGameTick() |
|
11 AnimUnWait() |
|
12 if ShowAnimation() == false then |
|
13 return |
|
14 end |
|
15 ExecuteAfterAnimations() |
|
16 CheckEvents() |
|
17 end</code> |
|
18 |
|
19 Also, `AnimInit()` needs to be called in `onGameInit()`. |
|
20 Each of these functions will be explained below. |
|
21 |
|
22 Note: The Animate library will direclty overwrite the input mask with `SetInputMask`. If you already use this function in your script, it might lead to conflicts. Use `AnimSetInputMask` to set the input mask in a manner that is compatible with the Animate library. |
|
23 |
|
24 == Cinematic handling == |
|
25 |
|
26 === `ShowAnimation()` === |
|
27 Performs the current action in the cinematic and returns `true` if finished, otherwise `false`. It needs to be used in `onGameTick`. Cut-scenes need to be added with `AddAnim(steps)`. |
|
28 |
|
29 === `AddAnim(steps)` === |
|
30 Adds `steps` to the array of animations, where `steps` is a table with numbers as keys and elements of the following form. Each step is a table having the following keys: `func`, `args`, `swh`. |
|
31 |
|
32 * `func` is the function to be executed. It can be any function that returns false when it needs to be called again in following game ticks (e.g. `AnimMove`). It can be one of the cinematic functions. |
|
33 |
|
34 * `args` is a table containing the arguments that need to be passed to the function given |
|
35 |
|
36 * `swh` is an optional boolean value that defaults to `true` and denotes whether the current hedgehog should be switched to the hog given as argument. |
|
37 Example: |
|
38 <code language="lua">cinem = { |
|
39 {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}}, |
|
40 {func = AnimMove, args = {myhog, "Left", 2000, 0}}, |
|
41 {func = AddCaption, swh = false, args = {"But he found no more snails..."}} |
|
42 } |
|
43 AddAnim(cinem)</code> |
|
44 |
|
45 === `RemoveAnim(steps)` === |
|
46 Removes `steps` from the animations array. |
|
47 |
|
48 === `AddSkipFunction(anim, func, args)` === |
|
49 Adds `func` to the array of functions used to skip animations, associating it with `anim`. When the animation is skipped (see below), the function is called with `args` as arguments. |
|
50 Example: |
|
51 <code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code> |
|
52 |
|
53 === `RemoveSkipFunction(anim)` === |
|
54 Removes the skip function associated with `anim`. |
|
55 |
|
56 === `SetAnimSkip(bool)` === |
|
57 Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation. |
|
58 |
|
59 Example: |
|
60 <code language="lua">function onPrecise() |
|
61 if AnimInProgress() then |
|
62 SetAnimSkip(true) |
|
63 end |
|
64 end</code> |
|
65 |
|
66 === `AnimInProgress()` === |
|
67 Returns `true` if a cinematic is currently taking place, `false` otherwise. |
|
68 |
|
69 === `ExecuteAfterAnimations()` === |
|
70 Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. The best location for this function call is in `onGameTick`. |
|
71 |
|
72 === `AddFunction(element)` === |
|
73 Adds `element` to the functions array that are to be called after the cinematic. `element` is a table with the keys: `func`, `args`. |
|
74 |
|
75 Example: |
|
76 <code language="lua">AddFunction({func = AfterCinem, args = {2}})</code> |
|
77 |
|
78 === `RemoveFunction()` === |
|
79 Removes the first function from the aforementioned list. |
|
80 |
|
81 === `AnimInit([startAnimating])` === |
|
82 Initializes variables used by the other functions. Needs to be called in `onGameInit`. |
|
83 |
|
84 Since 0.9.23, an optional convenience parameter `startAnimating` is available; if set to `true`, the game will start in “animation” mode which enables cinematic mode and disables all controls except precise for skipping. This is useful if you want to indicate that an animation will be played right at the start and the player must not be allowed to use any controls before the animation is over. If you set this parameter to `true`, you also *must* play at least one animation after this, otherwise the game will be stuck. |
|
85 |
|
86 === `AnimUnWait()` === |
|
87 Decreases the wait time used by cinematics. It is best called in `onGameTick`. |
|
88 |
|
89 == Cinematic functions == |
|
90 |
|
91 === `AnimSwitchHog(gear)` === |
|
92 Switches to `gear` and follows it. |
|
93 |
|
94 === `AnimWait(gear, time)` === |
|
95 Increases the wait time by `time`. `gear` is just for compatibility with `ShowAnimation`. |
|
96 |
|
97 === `AnimSay(gear, text, manner, time` === |
|
98 Calls `HogSay` with the first three arguments and increses the wait time by `time`. |
|
99 |
|
100 Example: |
|
101 <code language="lua">cinem = { |
|
102 {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}}, |
|
103 {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}} |
|
104 }</code> |
|
105 |
|
106 === `AnimSound(gear, sound, time)` === |
|
107 Plays the sound `sound` and increases the wait time by `time`. |
|
108 |
|
109 === `AnimTurn(hog, dir)` === |
|
110 Makes `hog` face in direction `dir`, where `dir` equals either `"Right"` or `"Left"`. |
|
111 |
|
112 === `AnimMove(hog, dir, x, y)` === |
|
113 Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`. |
|
114 |
|
115 === `AnimJump(hog, jumpType)` === |
|
116 Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`. |
|
117 |
|
118 === `AnimSetGearPosition(gear, x, y, fall)` === |
|
119 Sets the position of `gear` to (`x`, `y`). If the optional argument `fall` does not equal `false` then the gear is given a small falling velocity in order to get around exact positioning. |
|
120 |
|
121 === `AnimDisappear(gear, x, y)` === |
|
122 Teleports the gear to (`x`, `y`), adding some effects at the previous position and sounds. Doesn’t follow the gear. |
|
123 |
|
124 === `AnimOutOfNowhere(gear, x, y)` === |
|
125 Teleports the gear to (`x`, `y`), adding effects and sounds at the final position. Follows gear. |
|
126 |
|
127 === `AnimTeleportGear(gear, x, y)` === |
|
128 Teleports the gear to (`x`, `y`), adding effects and sounds both at the starting position and the final position. Follows gear. |
|
129 |
|
130 === `AnimVisualGear(gear, x, y, vgType, state, critical, follow)` === |
|
131 Calls `AddVisualGear` with arguments second to sixth. If the optional argument `follow` equals `true` then the gear is followed. `gear` is for compatibility only. |
|
132 |
|
133 === `AnimCaption(gear, text, time)` === |
|
134 Adds `text` as caption and increases wait time by `time`. |
|
135 |
|
136 === `AnimCustomFunction(gear, func, args)` === |
|
137 Calls the function `func` with `args` as arguments. This function is useful, for instance, when the cinematic uses the position of a gear at the moment of execution. If `func` needs to be called in following game ticks then it should return false. |
|
138 |
|
139 Example: |
|
140 <code language="lua">function NeedToTurn(hog1, hog2) |
|
141 if GetX(hog1) < GetX(hog2) then |
|
142 HogTurnLeft(hog1, false) |
|
143 HogTurnLeft(hog2, true) |
|
144 else |
|
145 HogTurnLeft(hog2, false) |
|
146 HogTurnLeft(hog1, true) |
|
147 end |
|
148 end |
|
149 |
|
150 cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code> |
|
151 |
|
152 === `AnimInsertStepNext(step)` === |
|
153 Inserts `step` after the current step (read: action) in the cinematic array. Useful when an action depends on variables (e.g. positoins). It can be used mostly with `AnimCustomFunction`. Note: In case of multiple consecutive calls, steps need to be added in reverse order. |
|
154 |
|
155 Example: |
|
156 <code language="lua">function BlowHog(deadHog) |
|
157 AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false}) |
|
158 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false}) |
|
159 AnimInsertStepNext({func = AnimWait, args = {deadHog, 1200}}) |
|
160 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) |
|
161 AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}}) |
|
162 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) + 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) |
|
163 AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}}) |
|
164 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 10, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) |
|
165 AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}}) |
|
166 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) |
|
167 end |
|
168 cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code> |
|
169 |
|
170 == Event handling == |
|
171 |
|
172 Events are pairs of functions that are used to check for various conditions. One of them is for verification and, if it returns `true`, the second function is called. |
|
173 |
|
174 === `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` === |
|
175 Adds the functions `condFunc` and `doFunc` to the events list. They get called with the respective args (`condArgs` and `doArgs`). `condFunc` will get called in every game tick until it returns `true` or is removed. Once it returns `true`, `doFunc` is called and they are or are not removed from the list, depending on `evType` (`0` for removal, `1` for keeping). An `evType` of `1` is useful for repeating actions (e.g. every time a hog gets damaged, do something). |
|
176 |
|
177 Example: |
|
178 <code language="lua">function CheckPos() |
|
179 return GetX(myHog) > 1500 |
|
180 end |
|
181 function CheckAmmo() |
|
182 return GetAmmoCount(myHog, amGrenade) == 0 |
|
183 end |
|
184 function DoPos() |
|
185 ShowMission("Scooter", "Mover", "Nice Work", 0, 0) |
|
186 end |
|
187 function DoAmmo() |
|
188 AddAmmo(myHog, amGrenade, 5) |
|
189 end |
|
190 AddEvent(CheckPos, {}, DoPos, {}, 0) -- Add event that gets removed on completion |
|
191 AddEvent(CheckAmmo, {}, DoAmmo, {}, 1) -- Add repeating event</code> |
|
192 |
|
193 === `AddNewEvent(condFunc, condArgs, doFunc, doArgs, evType)` === |
|
194 Does the same as `AddEvent`, but first checks if the event is already in the list so that it isn’t added twice. |
|
195 |
|
196 === `RemoveEventFunc(cFunc, cArgs)` === |
|
197 Removes the event or events that have `cFunc` as the condition checking function. If `cArgs` does not equal `nil` then only those events get removed that have `cArgs` as arguments for `cFunc`, too. |
|
198 |
|
199 Example: |
|
200 <code language="lua">AddEvent(condFunc1, condArgs1, doFunc, doArgs) |
|
201 AddEvent(condFunc1, condArgs2, doFunc, doArgs) |
|
202 AddEvent(condFunc1, condArgs2, doFunc, doArgs) |
|
203 AddEvent(condFunc2, condArgs1, doFunc, doArgs) |
|
204 AddEvent(condFunc2, condArgs2, doFunc, doArgs) |
|
205 RemoveEventFunc(condFunc1) --Removes all three events that have condFunc1 |
|
206 RemoveEventFunc(condFunc2, condArgs1) --Removes a single event</code> |
|
207 |
|
208 === `CheckEvents` === |
|
209 Verifies all the condition functions in the events list and calls the respective ‘action’ functions if the conditions are met. If the `evType` of a completed event equals `0` then it is removed from the list. This function is best placed in `onGameTick`. |
|
210 |
|
211 === `AnimSetInputMask(inputMask)` (0.9.23) === |
|
212 Call this function instead of `SetInputMask` if you want to set the input mask in a way that does not conflict with the Animate library. |
|
213 |
|
214 Internally, the input mask you provide is simply AND-ed with the input mask used by the Animate library. Otherwise, this function works lik `SetInputMask`. |
|
215 |
|
216 If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animatel library! |