20 |
20 |
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. |
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. |
22 |
22 |
23 == Cinematic handling == |
23 == Cinematic handling == |
24 |
24 |
25 === `ShowAnimation()` === |
|
26 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)`. |
|
27 |
|
28 === `Animate(steps)` === |
|
29 *THIS FUNCTION IS UNDOCUMENTED!* |
|
30 |
|
31 === `AddAnim(steps)` === |
|
32 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`. |
|
33 |
|
34 * `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. |
|
35 |
|
36 * `args` is a table containing the arguments that need to be passed to the function given |
|
37 |
|
38 * `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. |
|
39 Example: |
|
40 <code language="lua">cinem = { |
|
41 {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}}, |
|
42 {func = AnimMove, args = {myhog, "Left", 2000, 0}}, |
|
43 {func = AddCaption, swh = false, args = {"But he found no more snails..."}} |
|
44 } |
|
45 AddAnim(cinem)</code> |
|
46 |
|
47 === `RemoveAnim(steps)` === |
|
48 Removes `steps` from the animations array. |
|
49 |
|
50 === `AddSkipFunction(anim, func, args)` === |
|
51 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. |
|
52 Example: |
|
53 <code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code> |
|
54 |
|
55 === `RemoveSkipFunction(anim)` === |
|
56 Removes the skip function associated with `anim`. |
|
57 |
|
58 === `SetAnimSkip(bool)` === |
|
59 Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation. |
|
60 |
|
61 Example: |
|
62 <code language="lua">function onPrecise() |
|
63 if AnimInProgress() then |
|
64 SetAnimSkip(true) |
|
65 end |
|
66 end</code> |
|
67 |
|
68 === `AnimInProgress()` === |
|
69 Returns `true` if a cinematic is currently taking place, `false` otherwise. |
|
70 |
|
71 === `ExecuteAfterAnimations()` === |
|
72 Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. The best location for this function call is in `onGameTick`. |
|
73 |
|
74 === `AddFunction(element)` === |
|
75 Adds `element` to the functions array that are to be called after the cinematic. `element` is a table with the keys: `func`, `args`. |
|
76 |
|
77 Example: |
|
78 <code language="lua">AddFunction({func = AfterCinem, args = {2}})</code> |
|
79 |
|
80 === `RemoveFunction()` === |
|
81 Removes the first function from the aforementioned list. |
|
82 |
|
83 === `AnimInit([startAnimating])` === |
25 === `AnimInit([startAnimating])` === |
84 Initializes variables used by the other functions. Needs to be called in `onGameInit`. |
26 Initializes variables used by the other functions. Needs to be called in `onGameInit`. |
85 |
27 |
86 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. |
28 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. |
87 |
29 |
88 === `AnimUnWait()` === |
|
89 Decreases the wait time used by cinematics. It is best called in `onGameTick`. |
|
90 |
|
91 == Cinematic functions == |
|
92 |
|
93 === `AnimSwitchHog(gear)` === |
|
94 Switches to `gear` and follows it. |
|
95 |
|
96 === `AnimGiveState(gear, state)` === |
|
97 Adds the [GearStates gear state] `state` to `gear`. |
|
98 |
|
99 === `AnimRemoveState(gear, state)` === |
|
100 Removes the [GearStates gear state] `state` from `gear`. |
|
101 |
|
102 === `AnimWait(gear, time)` === |
|
103 Increases the wait time by `time`. `gear` is just for compatibility with `ShowAnimation`. |
|
104 |
|
105 === `AnimSay(gear, text, manner, time` === |
|
106 Calls `HogSay` with the first three arguments and increses the wait time by `time`. |
|
107 |
|
108 Example: |
|
109 <code language="lua">cinem = { |
|
110 {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}}, |
|
111 {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}} |
|
112 }</code> |
|
113 |
|
114 === `AnimSound(gear, sound, time)` === |
|
115 Plays the sound `sound` and increases the wait time by `time`. |
|
116 |
|
117 === `AnimTurn(hog, dir)` === |
|
118 Makes `hog` face in direction `dir`, where `dir` equals either `"Right"` or `"Left"`. |
|
119 |
|
120 === `AnimMove(hog, dir, x, y)` === |
|
121 Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`. |
|
122 |
|
123 === `AnimJump(hog, jumpType)` === |
|
124 Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`. |
|
125 |
|
126 === `AnimSetGearPosition(gear, x, y, fall)` === |
|
127 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. |
|
128 |
|
129 === `AnimDisappear(gear, x, y)` === |
|
130 Teleports the gear to (`x`, `y`), adding some effects at the previous position and sounds. Doesn’t follow the gear. |
|
131 |
|
132 === `AnimOutOfNowhere(gear, x, y)` === |
|
133 Teleports the gear to (`x`, `y`), adding effects and sounds at the final position. Follows gear. |
|
134 |
|
135 === `AnimTeleportGear(gear, x, y)` === |
|
136 Teleports the gear to (`x`, `y`), adding effects and sounds both at the starting position and the final position. Follows gear. |
|
137 |
|
138 === `AnimVisualGear(gear, x, y, vgType, state, critical, follow)` === |
|
139 Calls `AddVisualGear` with arguments second to sixth. If the optional argument `follow` equals `true` then the gear is followed. `gear` is for compatibility only. |
|
140 |
|
141 === `AnimCaption(gear, text, time)` === |
|
142 Adds `text` as caption and increases wait time by `time`. |
|
143 |
|
144 === `AnimCustomFunction(gear, func, args)` === |
|
145 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. |
|
146 |
|
147 Example: |
|
148 <code language="lua">function NeedToTurn(hog1, hog2) |
|
149 if GetX(hog1) < GetX(hog2) then |
|
150 HogTurnLeft(hog1, false) |
|
151 HogTurnLeft(hog2, true) |
|
152 else |
|
153 HogTurnLeft(hog2, false) |
|
154 HogTurnLeft(hog1, true) |
|
155 end |
|
156 end |
|
157 |
|
158 cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code> |
|
159 |
|
160 === `AnimInsertStepNext(step)` === |
30 === `AnimInsertStepNext(step)` === |
161 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. |
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. |
162 |
32 |
163 Example: |
33 Example: |
164 <code language="lua">function BlowHog(deadHog) |
34 <code language="lua">function BlowHog(deadHog) |
165 AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false}) |
35 AnimInsertStepNext({func = DeleteGear, args = {deadHog}, swh = false}) |
166 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false}) |
36 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog), GetY(deadHog), vgtBigExplosion, 0, true}, swh = false}) |
173 AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}}) |
43 AnimInsertStepNext({func = AnimWait, args = {deadHog, 100}}) |
174 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) |
44 AnimInsertStepNext({func = AnimVisualGear, args = {deadHog, GetX(deadHog) - 20, GetY(deadHog), vgtExplosion, 0, true}, swh = false}) |
175 end |
45 end |
176 cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code> |
46 cinem = {{func = AnimCustomFunction, args = {liveHog, BlowHog, {deadHog}}}}</code> |
177 |
47 |
|
48 === `ShowAnimation()` === |
|
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)`. |
|
50 |
|
51 === `Animate(steps)` === |
|
52 *THIS FUNCTION IS UNDOCUMENTED!* |
|
53 |
|
54 === `AddAnim(steps)` === |
|
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`. |
|
56 |
|
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. |
|
58 |
|
59 * `args` is a table containing the arguments that need to be passed to the function given |
|
60 |
|
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. |
|
62 Example: |
|
63 <code language="lua">cinem = { |
|
64 {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}}, |
|
65 {func = AnimMove, args = {myhog, "Left", 2000, 0}}, |
|
66 {func = AddCaption, swh = false, args = {"But he found no more snails..."}} |
|
67 } |
|
68 AddAnim(cinem)</code> |
|
69 |
|
70 === `RemoveAnim(steps)` === |
|
71 Removes `steps` from the animations array. |
|
72 |
|
73 === `AddSkipFunction(anim, func, args)` === |
|
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. |
|
75 Example: |
|
76 <code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code> |
|
77 |
|
78 === `RemoveSkipFunction(anim)` === |
|
79 Removes the skip function associated with `anim`. |
|
80 |
|
81 === `SetAnimSkip(bool)` === |
|
82 Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation. |
|
83 |
|
84 Example: |
|
85 <code language="lua">function onPrecise() |
|
86 if AnimInProgress() then |
|
87 SetAnimSkip(true) |
|
88 end |
|
89 end</code> |
|
90 |
|
91 === `AnimInProgress()` === |
|
92 Returns `true` if a cinematic is currently taking place, `false` otherwise. |
|
93 |
|
94 === `ExecuteAfterAnimations()` === |
|
95 Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. The best location for this function call is in `onGameTick`. |
|
96 |
|
97 === `AddFunction(element)` === |
|
98 Adds `element` to the functions array that are to be called after the cinematic. `element` is a table with the keys: `func`, `args`. |
|
99 |
|
100 Example: |
|
101 <code language="lua">AddFunction({func = AfterCinem, args = {2}})</code> |
|
102 |
|
103 === `RemoveFunction()` === |
|
104 Removes the first function from the aforementioned list. |
|
105 |
|
106 === `AnimUnWait()` === |
|
107 Decreases the wait time used by cinematics. It is best called in `onGameTick`. |
|
108 |
|
109 === `AnimSetInputMask(inputMask)` === |
|
110 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. |
|
111 |
|
112 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`. |
|
113 |
|
114 If you call `SetInputMask` directly, note that it might get quickly overwritten by the Animatel library! |
|
115 |
|
116 == Cinematic functions == |
|
117 |
|
118 === `AnimSwitchHog(gear)` === |
|
119 Switches to `gear` and follows it. |
|
120 |
|
121 === `AnimGiveState(gear, state)` === |
|
122 Adds the [GearStates gear state] `state` to `gear`. |
|
123 |
|
124 === `AnimRemoveState(gear, state)` === |
|
125 Removes the [GearStates gear state] `state` from `gear`. |
|
126 |
|
127 === `AnimWait(gear, time)` === |
|
128 Increases the wait time by `time`. `gear` is just for compatibility with `ShowAnimation`. |
|
129 |
|
130 === `AnimSay(gear, text, manner, time` === |
|
131 Calls `HogSay` with the first three arguments and increses the wait time by `time`. |
|
132 |
|
133 Example: |
|
134 <code language="lua">cinem = { |
|
135 {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}}, |
|
136 {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}} |
|
137 }</code> |
|
138 |
|
139 === `AnimSound(gear, sound, time)` === |
|
140 Plays the sound `sound` and increases the wait time by `time`. |
|
141 |
|
142 === `AnimTurn(hog, dir)` === |
|
143 Makes `hog` face in direction `dir`, where `dir` equals either `"Right"` or `"Left"`. |
|
144 |
|
145 === `AnimMove(hog, dir, x, y)` === |
|
146 Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`. |
|
147 |
|
148 === `AnimJump(hog, jumpType)` === |
|
149 Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`. |
|
150 |
|
151 === `AnimSetGearPosition(gear, x, y, fall)` === |
|
152 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. |
|
153 |
|
154 === `AnimDisappear(gear, x, y)` === |
|
155 Teleports the gear to (`x`, `y`), adding some effects at the previous position and sounds. Doesn’t follow the gear. |
|
156 |
|
157 === `AnimOutOfNowhere(gear, x, y)` === |
|
158 Teleports the gear to (`x`, `y`), adding effects and sounds at the final position. Follows gear. |
|
159 |
|
160 === `AnimTeleportGear(gear, x, y)` === |
|
161 Teleports the gear to (`x`, `y`), adding effects and sounds both at the starting position and the final position. Follows gear. |
|
162 |
|
163 === `AnimVisualGear(gear, x, y, vgType, state, critical, follow)` === |
|
164 Calls `AddVisualGear` with arguments second to sixth. If the optional argument `follow` equals `true` then the gear is followed. `gear` is for compatibility only. |
|
165 |
|
166 === `AnimCaption(gear, text, time)` === |
|
167 Adds `text` as caption and increases wait time by `time`. |
|
168 |
|
169 === `AnimCustomFunction(gear, func, args)` === |
|
170 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. |
|
171 |
|
172 Example: |
|
173 <code language="lua">function NeedToTurn(hog1, hog2) |
|
174 if GetX(hog1) < GetX(hog2) then |
|
175 HogTurnLeft(hog1, false) |
|
176 HogTurnLeft(hog2, true) |
|
177 else |
|
178 HogTurnLeft(hog2, false) |
|
179 HogTurnLeft(hog1, true) |
|
180 end |
|
181 end |
|
182 |
|
183 cinem = {{func = AnimCustomFunction, args = {hog1, NeedToTurn, {hog1, hg2}}}}</code> |
|
184 |
178 == Event handling == |
185 == Event handling == |
179 |
186 |
180 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. |
187 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. |
181 |
188 |
182 === `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` === |
189 === `AddEvent(condFunc, condArgs, doFunc, doArgs, evType)` === |