18 = Locale = |
18 = Locale = |
19 |
19 |
20 This library allows you to translate string and should be used whenever a script has text. It loads the appropriate locale file and check automatically. |
20 This library allows you to translate string and should be used whenever a script has text. It loads the appropriate locale file and check automatically. |
21 |
21 |
22 === lang(text) === |
22 === lang(text) === |
23 <blockquote> |
23 |
24 Returns the localised string of text or if it is not found it returns text. |
24 Returns the localised string of text or if it is not found it returns text. |
25 </blockquote> |
25 |
26 |
26 |
27 |
27 |
28 = Utils = |
28 = Utils = |
29 |
29 |
30 This library includes miscellaneous functions to use, they are all independent of each other and can be used everywhere. |
30 This library includes miscellaneous functions to use, they are all independent of each other and can be used everywhere. |
31 |
31 |
32 === gearIsInBox(gear, x, y, w, h) === |
32 === `gearIsInBox(gear, x, y, w, h)` === |
33 <blockquote> |
33 |
34 Returns whether the gear is inside (centre point of the gear) a box with x and y as the top left corner and having the width and height of w and h respectively. |
34 Returns whether the gear is inside (centre point of the gear) a box with x and y as the top left corner and having the width and height of w and h respectively. |
35 </blockquote> |
35 |
36 |
36 |
37 === gearIsInCircle(gear, x, y, r, useRadius) === |
37 === `gearIsInCircle(gear, x, y, r, useRadius)` === |
38 <blockquote> |
38 |
39 Returns whether the gear is inside a circle with x and y being the centre point and r being the radius of the circle. The boolean useRadius determine whether only the centre point of the gear will be used or the radius of the gear will be checked too. |
39 Returns whether the gear is inside a circle with x and y being the centre point and r being the radius of the circle. The boolean useRadius determine whether only the centre point of the gear will be used or the radius of the gear will be checked too. |
40 </blockquote> |
40 |
41 |
41 |
42 |
42 |
43 = Tracker = |
43 = Tracker = |
44 |
44 |
45 This library is intended to be used if you need to keep track of gears. It can also keep track of teams and clans and as an extra functionality it can also store variables for a gear, team or clan. |
45 This library is intended to be used if you need to keep track of gears. It can also keep track of teams and clans and as an extra functionality it can also store variables for a gear, team or clan. |
46 |
46 |
47 To set it up you need to add some hooks in different events. The hooks trackGear and trackDeletion to onGearAdd and onGearDelete respectively. It is strongly recommended to only track the gears you are interested in as, especially with snow on, the amount of gears can go up high and that will slow down the script. To keep track of teams you need to keep track of gtHedgehog and gtResurrector (if resurrection might be used) and add trackTeams to onGameStart. |
47 To set it up you need to add some hooks in different events. The hooks `trackGear` and `trackDeletion` to `onGearAdd` and `onGearDelete` respectively. It is strongly recommended to only track the gears you are interested in as, especially with snow on, the amount of gears can go up high and that will slow down the script. To keep track of teams you need to keep track of `gtHedgehog` and `gtResurrector` (if resurrection might be used) and add `trackTeams` to `onGameStart`. |
48 |
48 |
49 If you want to call a function on a couple of gears you will have to call the "runOn" functions. To these you will pass the function you want to be run as a variable to the function. The function must take a gear as a parameter, nothing else, for example: |
49 If you want to call a function on a couple of gears you will have to call the “`runOn`” functions. To these you will pass the function you want to be run as a variable to the function. The function must take a gear as a parameter, nothing else, for example: |
50 <code language="lua"> |
50 <code language="lua">function killall(gear) |
51 function killall(gear) |
|
52 SetHealth(gear, 0) |
51 SetHealth(gear, 0) |
53 end |
52 end |
54 |
53 |
55 function onGearDelete(gear) |
54 function onGearDelete(gear) |
56 if GetGearType(gear) == gtTarget then |
55 if GetGearType(gear) == gtTarget then |
57 runOnHogs(killall) |
56 runOnHogs(killall) |
58 end |
57 end |
59 end |
58 end</code> |
60 </code> |
|
61 This will kill all hogs if a target is destroyed. |
59 This will kill all hogs if a target is destroyed. |
62 |
60 |
63 To see a commented example of the tracker in use by a script you can look at |
61 To see a commented example of the tracker in use by a script you can look at |
64 [http://code.google.com/p/hedgewars/source/browse/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons] |
62 [http://code.google.com/p/hedgewars/source/browse/share/hedgewars/Data/Scripts/Multiplayer/Random_Weapon.lua Random Weapons]. |
65 |
63 |
66 == Tracking functions == |
64 == Tracking functions == |
67 |
65 |
68 === trackGear(gear) === |
66 === `trackGear(gear)` === |
69 <blockquote> |
67 |
70 Will keep track of the gear. |
68 Will keep track of the gear. |
71 </blockquote> |
69 |
72 |
70 |
73 === trackDeletion(gear) === |
71 === `trackDeletion(gear)` === |
74 <blockquote> |
72 |
75 Will stop keeping track of the gear (gears not tracked will be ignored). |
73 Will stop keeping track of the gear (gears not tracked will be ignored). |
76 </blockquote> |
74 |
77 |
75 |
78 === trackTeams() === |
76 === `trackTeams()` === |
79 <blockquote> |
77 |
80 Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this). |
78 Will start the tracking of teams, clans and hedgehogs (hogs can be tracked without this). |
81 </blockquote> |
79 |
82 |
80 |
83 == "runOn" functions == |
81 == “`runOn`” functions == |
84 |
82 |
85 === runOnGears(func) === |
83 === `runOnGears(func)` === |
86 <blockquote> |
84 |
87 Runs the function func on all gears. |
85 Runs the function `func` on all gears. |
88 </blockquote> |
86 |
89 |
87 |
90 === runOnHogs(func) === |
88 === `runOnHogs(func)` === |
91 <blockquote> |
89 |
92 Runs the function func on all hedgehogs. |
90 Runs the function `func` on all hedgehogs. |
93 </blockquote> |
91 |
94 |
92 |
95 === runOnHogsInTeam(func, team) === |
93 === `runOnHogsInTeam(func, team)` === |
96 <blockquote> |
94 |
97 Runs the function func on all hedgehogs in the specified team. |
95 Runs the function `func` on all hedgehogs in the specified team. |
98 </blockquote> |
96 |
99 |
97 |
100 === runOnHogsInOtherTeams(func, team) === |
98 === runOnHogsInOtherTeams(func, team) === |
101 <blockquote> |
99 |
102 Runs the function func on all hedgehogs but those in the specified team. |
100 Runs the function `func` on all hedgehogs but those in the specified team. |
103 </blockquote> |
101 |
104 |
102 |
105 === runOnHogsInClan(func, clan) === |
103 === `runOnHogsInClan(func, clan)` === |
106 <blockquote> |
104 |
107 Runs the function func on all hedgehogs in the specified clan. |
105 Runs the function `func` on all hedgehogs in the specified clan. |
108 </blockquote> |
106 |
109 |
107 |
110 === runOnHogsInOtherClans(func, clan) === |
108 === `runOnHogsInOtherClans(func, clan)` === |
111 <blockquote> |
109 |
112 Runs the function func on all hedgehogs but those in the specified clan. |
110 Runs the function `func` on all hedgehogs but those in the specified clan. |
113 </blockquote> |
111 |
114 |
112 |
115 == Variable functions == |
113 == Variable functions == |
116 |
114 |
117 to be continued... |
115 _To be continued …_ |
118 |
116 |
119 |
117 |
120 = Animate = |
118 = Animate = |
121 |
119 |
122 This library provides functions that aid cinematic/cut-scene creation and functions for handling events. |
120 This library provides functions that aid cinematic/cut-scene creation and functions for handling events. |
123 |
121 |
124 In order to use it's full potential, the following lines need to be at the beginning of onGameTick. |
122 In order to use its full potential, the following lines need to be at the beginning of `onGameTick`. |
125 |
123 |
126 <code language="lua">function onGameTick() |
124 <code language="lua">function onGameTick() |
127 !AnimUnWait() |
125 AnimUnWait() |
128 if !ShowAnimation() == false then |
126 if ShowAnimation() == false then |
129 return |
127 return |
130 end |
128 end |
131 !ExecuteAfterAnimations() |
129 ExecuteAfterAnimations() |
132 !CheckEvents() |
130 CheckEvents() |
133 end</code> |
131 end</code> |
134 |
132 |
135 Also, !AnimInit() needs to be called in !onGameInit(). |
133 Also, `AnimInit()` needs to be called in `onGameInit()`. |
136 Each of these functions will be explained below. |
134 Each of these functions will be explained below. |
137 |
135 |
138 == Cinematic Handling == |
136 == Cinematic Handling == |
139 |
137 |
140 === !ShowAnimation() === |
138 === `ShowAnimation()` === |
141 <blockquote>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).</blockquote> |
139 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)`. |
142 |
140 |
143 === !AddAnim(steps) === |
141 === `AddAnim(steps)` === |
144 <blockquote>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. |
142 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`. |
145 |
143 |
146 * _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. |
144 * `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. |
147 |
145 |
148 * _args_ is a table containing the arguments that need to be passed to the function given |
146 * `args` is a table containing the arguments that need to be passed to the function given |
149 |
147 |
150 * _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.</blockquote> |
148 * `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. |
151 Example: |
149 Example: |
152 <code language="lua">cinem = { |
150 <code language="lua">cinem = { |
153 {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}}, |
151 {func = AnimSay, args = {myHog, "Snails! SNAILS!", SAY_SAY, 3000}}, |
154 {func = AnimMove, args = {myhog, "Left", 2000, 0}}, |
152 {func = AnimMove, args = {myhog, "Left", 2000, 0}}, |
155 {func = AddCaption, swh = false, args = {"But he found no more snails..."}} |
153 {func = AddCaption, swh = false, args = {"But he found no more snails..."}} |
156 } |
154 } |
157 AddAnim(cinem)</code> |
155 AddAnim(cinem)</code> |
158 |
156 |
159 === !RemoveAnim(steps) === |
157 === `RemoveAnim(steps)` === |
160 <blockquote>Removes steps from the animations array.</blockquote> |
158 Removes `steps` from the animations array. |
161 |
159 |
162 === !AddSkipFunction(anim, func, args) === |
160 === `AddSkipFunction(anim, func, args)` === |
163 <blockquote>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.</blockquote> |
161 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. |
164 Example: |
162 Example: |
165 <code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code> |
163 <code language="lua">AddSkipFunc(cinem, SkipCinem, {})</code> |
166 |
164 |
167 === !RemoveSkipFunction(anim) === |
165 === `RemoveSkipFunction(anim)` === |
168 <blockquote> Removes the skip function associated with _anim_.</blockquote> |
166 Removes the skip function associated with `anim`. |
169 |
167 |
170 === !SetAnimSkip(bool) === |
168 === `SetAnimSkip(bool)` === |
171 <blockquote> Sets the state of animation skipping to _bool_. It is useful in case the player is allowed to skip the animation.</blockquote> |
169 Sets the state of animation skipping to `bool`. It is useful in case the player is allowed to skip the animation. |
|
170 |
172 Example: |
171 Example: |
173 <code language="lua">function onPrecise() |
172 <code language="lua">function onPrecise() |
174 if !AnimInProgress() then |
173 if AnimInProgress() then |
175 SetAnimSkip(true) |
174 SetAnimSkip(true) |
176 end |
175 end |
177 end</code> |
176 end</code> |
178 |
177 |
179 === !AnimInProgress() === |
178 === `AnimInProgress()` === |
180 <blockquote> Returns true if a cinematic is currently taking place, false otherwise.</blockquote> |
179 Returns `true` if a cinematic is currently taking place, `false` otherwise. |
181 |
180 |
182 === !ExecuteAfterAnimations() === |
181 === `ExecuteAfterAnimations()` === |
183 <blockquote> Calls the functions (added with !AddFunction) that need to be executed after the cinematic. The best location for this function call is in onGameTick.</blockquote> |
182 Calls the functions (added with `AddFunction`) that need to be executed after the cinematic. The best location for this function call is in `onGameTick`. |
184 |
183 |
185 === !AddFunction(element) === |
184 === `AddFunction(element)` === |
186 <blockquote> Adds _element_ to the functions array that are to be called after the cinematic. _element_ is a table with the keys: func, args.</blockquote> |
185 Adds `element` to the functions array that are to be called after the cinematic. `element` is a table with the keys: `func`, `args`. |
|
186 |
187 Example: |
187 Example: |
188 <code language="lua">AddFunction({func = AfterCinem, args = {2}})</code> |
188 <code language="lua">AddFunction({func = AfterCinem, args = {2}})</code> |
189 |
189 |
190 === !RemoveFunction() === |
190 === `RemoveFunction()` === |
191 <blockquote> Removes the first function from the aforementioned list.</blockquote> |
191 Removes the first function from the aforementioned list. |
192 |
192 |
193 === !AnimInit() === |
193 === `AnimInit()` === |
194 <blockquote> Initializes variables used by the other functions. Needs to be called in onGameInit.</blockquote> |
194 Initializes variables used by the other functions. Needs to be called in `onGameInit`. |
195 |
195 |
196 === !AnimUnWait() === |
196 === !AnimUnWait() === |
197 <blockquote> Decreases the wait time used by cinematics. It is best called in onGameTick</blockquote> |
197 Decreases the wait time used by cinematics. It is best called in `onGameTick`. |
198 |
198 |
199 == Cinematic Functions == |
199 == Cinematic Functions == |
200 |
200 |
201 === !AnimSwitchHog(gear) === |
201 === `AnimSwitchHog(gear)` === |
202 <blockquote> Switches to _gear_ and follows it. </blockquote> |
202 Switches to `gear` and follows it. |
203 |
203 |
204 === !AnimWait(gear, time) === |
204 === `AnimWait(gear, time)` === |
205 <blockquote> Increases the wait time by _time_. _gear_ is just for compatibility with !ShowAnimation.</blockquote> |
205 Increases the wait time by `time`. `gear` is just for compatibility with `ShowAnimation`. |
206 |
206 |
207 === !AnimSay(gear, text, manner, time) === |
207 === `AnimSay(gear, text, manner, time` === |
208 <blockquote> Calls HogSay with the first three arguments and increses the wait time by _time_.</blockquote> |
208 Calls `HogSay` with the first three arguments and increses the wait time by `time`. |
|
209 |
209 Example: |
210 Example: |
210 <code language="lua">cinem = { |
211 <code language="lua">cinem = { |
211 {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}}, |
212 {func = AnimSay, args = {gear1, "You're so defensive!", SAY_SAY, 2500}}, |
212 {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}} |
213 {func = AnimSay, args = {gear2, "No, I'm not!", SAY_SAY, 2000}} |
213 }</code> |
214 }</code> |
214 |
215 |
215 === !AnimSound(gear, sound, time) === |
216 === `AnimSound(gear, sound, time)` === |
216 <blockquote> Plays the sound _sound_ and increases the wait time by _time_.</blockquote> |
217 Plays the sound `sound` and increases the wait time by `time`. |
217 |
218 |
218 === !AnimTurn(hog, dir) === |
219 === `AnimTurn(hog, dir)` === |
219 <blockquote> Makes _hog_ face in direction _dir_, where _dir_ is either "Right" or "Left".</blockquote> |
220 Makes `hog` face in direction `dir`, where `dir` equals either `"Right"` or `"Left"`. |
220 |
221 |
221 === !AnimMove(hog, dir, x, y) === |
222 === `AnimMove(hog, dir, x, y)` === |
222 <blockquote> Makes _hog_ move in direction _dir_ until either his horizontal coordinate is _x_ or his vertical coordinate is _y_.</blockquote> |
223 Makes `hog` move in direction `dir` until either his horizontal coordinate is `x` or his vertical coordinate is `y`. |
223 |
224 |
224 === !AnimJump(hog, jumpType) === |
225 === `AnimJump(hog, jumpType)` === |
225 <blockquote> Makes _hog_ perform a jump of type _jumpType_, where _jumpType_ is either "long", "high" or "back".</blockquote> |
226 Makes `hog` perform a jump of type `jumpType`, where `jumpType` equals either `"long"`, `"high"` or `"back"`. |
226 |
227 |
227 === !AnimSetGearPosition(gear, x, y, fall) === |
228 === `AnimSetGearPosition(gear, x, y, fall)` === |
228 <blockquote> Sets the position of _gear_ to (x, y). If the optional argument _fall_ is not false then the gear is given a small falling velocity in order to get around exact positioning.</blockquote> |
229 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. |
229 |
230 |
230 === !AnimDisappear(gear, x, y) === |
231 === `AnimDisappear(gear, x, y)` === |
231 <blockquote> Teleports the gear to (x, y), adding some effects at the previous position and sounds. Doesn't follow the gear.</blockquote> |
232 Teleports the gear to (`x`, `y`), adding some effects at the previous position and sounds. Doesn’t follow the gear. |
232 |
233 |
233 === !AnimOutOfNowhere(gear, x, y) === |
234 === `AnimOutOfNowhere(gear, x, y)` === |
234 <blockquote> Teleports the gear to (x, y), adding effects and sounds at the final position. Follows gear.</blockquote> |
235 Teleports the gear to (`x`, `y`), adding effects and sounds at the final position. Follows gear. |
235 |
236 |
236 === !AnimTeleportGear(gear, x, y) === |
237 === `AnimTeleportGear(gear, x, y)` === |
237 <blockquote> Teleports the gear to (x, y), adding effects and sounds both at the starting position and the final position. Follows gear.</blockquote> |
238 Teleports the gear to (`x`, `y`), adding effects and sounds both at the starting position and the final position. Follows gear. |
238 |
239 |
239 === !AnimVisualGear(gear, x, y, vgType, state, critical, follow) === |
240 === `AnimVisualGear(gear, x, y, vgType, state, critical, follow)` === |
240 <blockquote> Calls AddVisualGear with arguments second to sixth. If the optional argument _follow_ is true then the gear is followed. _gear_ is for compatibility only.</blockquote> |
241 Calls `AddVisualGear` with arguments second to sixth. If the optional argument `follow` equals `true` then the gear is followed. `gear` is for compatibility only. |
241 |
242 |
242 === !AnimCaption(gear, text, time) === |
243 === `AnimCaption(gear, text, time)` === |
243 <blockquote> Adds _text_ as caption and increases wait time by _time_.</blockquote> |
244 Adds `text` as caption and increases wait time by `time`. |
244 |
245 |
245 === !AnimCustomFunction(gear, func, args) === |
246 === `AnimCustomFunction(gear, func, args)` === |
246 <blockquote> 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.</blockquote> |
247 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. |
|
248 |
247 Example: |
249 Example: |
248 <code language="lua">function NeedToTurn(hog1, hog2) |
250 <code language="lua">function NeedToTurn(hog1, hog2) |
249 if GetX(hog1) < GetX(hog2) then |
251 if GetX(hog1) < GetX(hog2) then |
250 HogTurnLeft(hog1, false) |
252 HogTurnLeft(hog1, false) |
251 HogTurnLeft(hog2, true) |
253 HogTurnLeft(hog2, true) |