Debian Codegraph @

doc/scripts/magic.html

raw
1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2 <html><head>
3 <!--
4 ---- (c) Copyright 2002-2007 by Lutz Sammer, Russell Smith
5
6 ---- This program is free software; you can redistribute it and/or modify
7 ---- it under the terms of the GNU General Public License as published by
8 ---- the Free Software Foundation; only version 2 of the License.
9 ----
10 ---- This program is distributed in the hope that it will be useful,
11 ---- but WITHOUT ANY WARRANTY; without even the implied warranty of
12 ---- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 ---- GNU General Public License for more details.
14 ----
15 ---- You should have received a copy of the GNU General Public License
16 ---- along with this program; if not, write to the Free Software
17 ---- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
18 ---- 02111-1307, USA.
19 -->
20 <title>Bos Wars Scripting API: Magic</title>
21 <meta http-equiv="Content-Type" content="text/html; CHARSET=iso-8859-1">
22 <link rel="stylesheet" type="text/css" href="scripts.css">
23 </head>
24 <body>
25 <h1>Bos Wars: Magic</h1>
26 <hr>
27 <a href="../index.html">Bos Wars</a>
28 <a href="../faq.html">FAQ</a>
29 <a href="game.html">PREV</a>
30 <a href="mappresentation.html">NEXT</a>
31 <a href="index.html">LUA Index</a>
32 <hr>
33 <a href="#DefineMissileType">DefineMissileType</a>
34 <a href="#DefineSpell">DefineSpell</a>
35 <hr>
36 <h2>Intro - Introduction to spells and missiles.</h2>
37 This containts everything around spells and missiles. Though it might not be
38 obvious at start missiles are also suited for complex behaviour and included here.
39
40 <h2>Functions</h2>
41 <a name="DefineMissileType"></a>
42
43
44 <h3>DefineMissileType( "missile-name", { tag = value, ...} )</h3>
45
46 This is the function to define a missile type.
47 <dl>
48 <dt>missile-name</dt>
49 <dd>This is the unique identifier of the missile.
50 </dd>
51 </dl>
52 Possible tags:
53 <dl>
54 <dt id="DefineMissileType.File">File = "file-path"</dt>
55 <dd>This is followed by the path of the file with the missile graphics.
56 </dd>
57 <dt>Size = {x, y}</dt>
58 <dd>This if followed by a list of X and Y sizes of the missile sprite.
59 F.E. 'size '(32 32)
60 </dd>
61 <dt id="DefineMissileType.Frames">Frames = number</dt>
62 <dd>The number of animation steps, multiplied with
63 (<a href="#DefineMissileType.NumDirections">NumDirections</a> / 2 + 1).
64 Thus, if <a href="#DefineMissileType.Flip">Flip</a> = true,
65 then Frames is the number of frames in the graphic file.
66 Missiles lack complicated animation scripts and just have a bunch
67 of frames with equal duration.
68 </dd>
69 <dt id="DefineMissileType.Flip">Flip = boolean</dt>
70 <dd>Please see <a href="unittype.html#frame_numbers">Frame numbers and flipping</a>.
71 The default is true, unlike in <a href="unittype.html#DefineUnitType">DefineUnitType</a>.
72 </dd>
73 <dt id="DefineMissileType.NumDirections">NumDirections = number</dt>
74 <dd>Define the number of directions a missile can face.
75 If <a href="#DefineMissileType.Flip">Flip</a> = true,
76 not all of these directions are actually in the graphic file.
77 </dd>
78 <dt>DrawLevel = Number</dt>
79 <dd>The draw level of the missile. Missiles and units are sorted by this
80 value to determine the draw order.
81 </dd>
82 <dt>FiredSound = "Sound-file"</dt>
83 <dd>Name of the sound played when the missile is fired.
84 </dd>
85 <dt>ImpactSound = "Sound-file"</dt>
86 <dd>Name of the sound played when the missile hits it's target.
87 </dd>
88 <dt id="DefineMissileType.Class">Class = "class-type"</dt>
89 <dd>Various missiles can have wierd behaviours. This tag is followed by an
90 identifier that specifies some of that behaviour. Here is a list of currently
91 supported missile classes:
92 <dl>
93 <dt>"missile-class-none"</dt>
94 <dd>Missile does nothing. Shouldn't really be used.
95 </dd>
96 <dt>"missile-class-point-to-point" </dt>
97 <dd>Missile flies straight to destination animating on the way
98 </dd>
99 <dt>"missile-class-point-to-point-with-hit" </dt>
100 <dd>Missile flies straight to destination keeping the first frame and
101 the finishes the animation when hitting
102 </dd>
103 <dt>"missile-class-point-to-point-cycle-once" </dt>
104 <dd>Missile flies straight to destination and animates ONCE from first
105 to last and back again. To be used for catapult and the like to make a
106 projectile bigger mid-way to the target
107 </dd>
108 <dt>"missile-class-point-to-point-bounce"</dt>
109 <dd>Missile flies straight to destination, and the "bounces" by hitting
110 every other tile on the path onward. This will also add one aditional flag:
111 <dl><dt>num-bounces</dt>
112 <dd>This if folowed by an integer, representing the number of bounces(hits)</dd>
113 </dl></dd>
114 <dt>"missile-class-stay"</dt>
115 <dd>Missile will just go through it's animation once and vanish. booooring.
116 </dd>
117 <dt>"missile-class-cycle-once" </dt>
118 <dd>Missile will just go through it's animation from start to and and back
119 again, then vanish.
120 </dd>
121 <dt>"missile-class-fire" </dt>
122 <dd>Missile is used for fire. More documentation?
123 </dd>
124 <dt id="DefineMissileType.Class.hit">"missile-class-hit" </dt>
125 <dd>The missile does not use a graphics <a href="#DefineMissileType.File">File</a>
126 but instead shows the number of hit points lost by a unit.
127 For use with <a href="config.html#SetDamageMissile">SetDamageMissile</a>.
128 </dd>
129 <dt>"missile-class-parabolic"</dt>
130 <dd>Missile flies to destination with a parabolic path. It used the same
131 animation as cycle-once
132 </dd>
133 </dl>
134 </dd>
135 <dt id="DefineMissileType.Delay">Delay = number</dt>
136 <dd>Delay in game cycles after the missile generation, until the missile
137 animation and effects starts. Delay denotes the number of display cycles to
138 skip before drawing the first sprite frame and only happens once at start.
139 </dd>
140 <dt id="DefineMissileType.Sleep">Sleep = number</dt>
141 <dd>This are the number of game cycles to wait for the next animation or the
142 sleeping between the animation steps. All animations steps use the same delay.
143 0 is the fastest and 255 the slowest animation. Perhaps we should later we
144 will use animation scripts for more complex animations.
145 </dd>
146 <dt id="DefineMissileType.Speed">Speed = number</dt>
147 <dd>The speed how fast the missile moves. 0 the missile didn't move, 1 is the
148 slowest speed and 32 s the fastest supported speed. This is how many pixels
149 the missiles moves with each animation step. The real use of this member
150 depends on the missile class. This is currently only used by the point-to-point
151 missiles.
152 </dd>
153 <dt id="DefineMissileType.Range">Range = number</dt>
154 <dd>Determines the range in which a projectile will deal its damage. A range of
155 0 will mean that the damage will be limited to the targetted unit only. So if
156 you shot a missile at a unit, it would only damage that unit. A value of 1 only
157 affects the field where the missile hits. A value of 2 would mean that the
158 damage for that particular missile would be dealt for a range of 1 around the
159 impact spot. All fields that aren't the center get only 1/SpashFactor of the damage.
160 Fields 2 away get 1/(SplashFactor*2), and following...
161 </dd>
162 <dt>SplashFactor = number</dt>
163 <dd>The Splash divisor for damage done with range
164 </dd>
165 <dt>ImpactMissile = "missile-type"</dt>
166 <dd>You can use this to spawn another missile on impact. F.E. ImpactMissile = "missile-explosion"
167 </dd>
168 <dt>SmokeMissile = "missile-type"</dt>
169 <dd>The name of the next (other) missile to generate a trailing smoke. So it
170 can be used to generate a chain of missiles.
171 </dd>
172 <dt>CanHitOwner = boolean</dt>
173 <dd>Determines if the missile will affect the caster or not.
174 </dd>
175 <dt>FriendlyFire = boolean</dt>
176 <dd>Determines if the missile will damage
177 units belonging to the same player of the caster or to an ally.
178 </dd>
179 </dl>
180
181 <h4>Example</h4>
182
183 <pre class="lua">
184 DefineMissileType("missile-fireball",
185 { File = "missiles/fireball.png", Size = {32, 32}, Frames = 5, NumDirections = 5,
186 ImpactSound = "fireball hit",
187 DrawLevel = 50, Class = "missile-class-point-to-point-bounce", NumBounces = 5,
188 Sleep = 1, Speed = 16, Range = 1,
189 ImpactMissile = "missile-explosion" } )
190 </pre>
191
192 <a name="DefineSpell"></a>
193 <h3>DefineSpell( "spell-ident", tag, value, ... )</h3>
194 This is the function to define a spell, including it's effects and targetting
195 conditions. Be very carefull, defining random flags will probably make the game crash.
196
197 <dl>
198 <dt>"showname", "name"</dt>
199 <dd>A neatly formatted string to be shown by the engine on the screen.
200 </dd>
201 <dt>"manacost", number</dt>
202 <dd>The mana cost of the spell. But some actions (AdjustVitals, Summon, Polymorph) use it
203 for their own mana calculation and so. If spell use at least of these actions, mana is computed
204 by these action (which use manacost also),else it was substract from caster mana.
205 </dd>
206 <dt>"repeat-cast" </dt>
207 <dd>If specified, the caster will cast it again. To be used with spells like
208 area-bombardment to cast it again (area-bombardment is stackable)
209 </dd>
210 <dt>"range", number or "infinite"</dt>
211 <dd>The casting range of the spell, do not confuse this with area effect range.
212 It's normally an integer value, but you can specify a special value "infinite" to
213 let the spell be casted on the entire map.
214 </dd>
215 <dt>"target", "self" or "position" or "unit"</dt>
216 <dd>Target type information. The following values are acceptable:
217 <ul>
218 <li>"self": The spell will only affect the caster or the area around him, no targetting at all.
219 <li>"position": The unit will target a position.
220 <li>"unit": The unit will target an unit. The spell will be aborted if the target dies.
221 </ul>
222 You can still use position spells on units, it will target the unit's position.
223 If the unit dies however the caster will stop. (Some spells get casted until
224 there is no more mana left).
225 </dd>
226 <dt id="DefineSpell.conditions">"conditions", {flag, value, ...}</dt>
227 <dd>This is the condition for being able to cast the spell. Think of it as a
228 function that takes an unit as a parameter and return either yes or no depending
229 on the unit properties. Here is how a condition looks like:
230 <pre>"condition", {
231 "building", "false"
232 "max-slow-ticks", 10}</pre>
233 Here are the supported parameters:
234 <dl>
235 <dt>"alliance", "true" or "false" or "only"</dt>
236 <dd>This is one of the bool parameters (can't think of a better name). It is
237 followed by "true", "false" or "only". Imagine this as a question, is the target in
238 alliance? The answer is yes/no. A "true" parameter makes it always pass(and
239 it's the default.), "false" parameter passes when the answer is NO, and "only"
240 passes only when the answer is yes.<br>
241 It doesn't really makes sense to ever say true, since you might just as well
242 ommit it. "alliance false" means the spell won't work on allied units. "alliance
243 only" will make a spell that works only on allied units (can't think of any though).
244 Your own units are considered allied too.
245 </dd>
246 <dt>"opponent", "true" or "false" or "only"</dt>
247 <dd>This is a bool parameter too, just like alliance. I specifies the behaviour
248 for opponent units. Neutral units are neither allied unit nor opponent units.
249 </dd>
250 <dt>"self", "true" or "false" or "only"</dt>
251 <dd>This is a bool parameter too, just like alliance. I it a bit more special,
252 since it specifies the behaviour for casting on yourself. <b>A LOT</b> of
253 spells specify "self false", to disallow casting on yourself.
254 </dd>
255 <dt>variable, {flag = value}</dt>
256 <dd>There is no parameter called variable. You can however use variables defined
257 by <a href="unittype.html#DefineVariables">DefineVariables()</a>
258 <dl>
259 <dt>Enable = "true" or "false" or "only"</dt>
260 <dd>variable is enable ?</dd>
261 <dt>MinValue = number </dt>
262 <dd>minimal value allowed.</dd>
263 <dt>MaxValue = number </dt>
264 <dd>maximal value allowed.</dd>
265 <dt>MinMax = number</dt>
266 <dd>minimal maximum-value (the field Max of the variable) allowed.</dd>
267 <dt>MinValuePercent = number</dt>
268 <dd>minimal value allowed in percent with Max value.</dd>
269 <dt>MaxValuePercent = number</dt>
270 <dd>maximal value allowed in percent with Max value.</dd>
271 <dt>ConditionApplyOnCaster = boolean</dt>
272 <dd>if true, check caster instead of target.</dd>
273 </dl></dd>
274 </dl>
275 </dd>
276 <dt id="DefineSpell.autocast">"autocast", {flag, value}</dt>
277 <dd>Autocast works very closely with conditions.
278 It functions by selecting every unit in range and trying to check of they fit the
279 condition. If they do, the spell is casted. Of course, this is a very primitive
280 mechanism, but it works for simple spells like heal. As you might have noticed, some
281 of the finer restrictions in conditions are designed for autocast (like not casting
282 buffs on cowards). Autocasting position target spells is not supported, sorry.
283 Here is a formal list of parameters:
284 <dl>
285 <dt>"range", number</dt>
286 <dd>The range in which autocast runs. I think it's square?
287 </dd>
288 <dt>"combat", "only" or "true" or "false"</dt>
289 <dd>This is a bool parameter, like in condition. It's autocast-specific and NOT
290 part of conditions due to technical considerations. Combat is not unit-specific,
291 it only depends on caster location. combat mode is when there are non-coward
292 enemy units in range. most offensive spells obviousely only should be used in
293 combat. (can you say offensive buffs?)
294 </dd>
295 <dt>"condition", {flag, value}</dt>
296 <dd>This is followed by a list exactly like in "condition". As it was said
297 before, this is evaluated for each and every unit in range, and if a unit
298 passes, the spell gets casted.
299 </dd>
300 </dl>
301 </dd>
302 <dt id="DefineSpell.ai-cast">"ai-cast", {flag, value}</dt>
303 <dd>This is identical to autocast in syntax. It's used by the AI (computer controller
304 player) rather then by a human players units. In general this should be a little better
305 than autocast (and make human players think some more). There no reason to repeat the
306 syntax of autocast here.
307 </dd>
308 <dt>"action", {{"operation-name", flag, value, ...} , ...}</dt>
309 <dd>The effect of the spells. You can add multiple actions.
310 Here are the supported operations, their paramenters, and what they do.
311 <dl>
312 <dt>"area-bombardment"</dt>
313 <dd>This will a number of missiles to be thrown in a square area. Here are
314 the available tags:
315 <dl><dt>"fields", number</dt>
316 <dd>The size of the affected square. This will get centered on the target
317 It should really be an odd number, or it will look wierd (not centered.)
318 </dd>
319 <dt>"shards", number</dt>
320 <dd>The amount of missiles to throw at random in the square.
321 </dd>
322 <dt>"damage", number</dt>
323 <dd>The damage of each individual missile.
324 </dd>
325 <dt>"start-offset-x", number</dt>
326 <dt>"start-offset-y", number</dt>
327 <dd>A missile hitting x,y will start at x + start-offset-x, y + start-offset-y.
328 This value is in pixels, for better precision.
329 </dd>
330 </dl></dd>
331 <dt>"adjust-variable", {VariableName = {tag = value, ...} or number, ...}</dt>
332 <dd>This will adjust variable "VariableName" of the unit
333 (defined by <a href="unittype.html#DefineVariables">DefineVariables().</a>)<br>
334 Using number n is equivalent to {Value = n, Max = n, Enable = (n == 0)}
335 <dl>
336 <dt>Enable = boolean</dt>
337 <dd>Set Enable value.</dd>
338 <dt>Value = number</dt>
339 <dd>Set Value value.</dd>
340 <dt>Max = number</dt>
341 <dd>Set Max value.</dd>
342 <dt>Increase = number</dt>
343 <dd>Set Increase value.</dd>
344 <dt>InvertEnable = boolean</dt>
345 <dd>Invert Enable value.</dd>
346 <dt>AddValue = number</dt>
347 <dd>Add to Value value.</dd>
348 <dt>AddMax = number</dt>
349 <dd>Add to Max value.</dd>
350 <dt>AddIncrease = number</dt>
351 <dd>Add to Increase value.</dd>
352 <dt>IncreaseTime = number</dt>
353 <dd>add number time Increase to the value.</dd>
354 <dt>TargetIsCaster = "target" or "caster"</dt>
355 <dd>Apply to target or caster.</dd>
356 </dl></dd>
357 <dt>"adjust-vitals", tag, ...</dt>
358 <dd>This will adjust vitals of the unit. Vitals are health, mana, and on a sunny
359 day maybe even shield. mana of caster is modified like this :
360 newmana = oldmana - manacost * castcount.
361 Where castcount is the number of time vitals are inc/decreased.
362 Possible tags:
363 <dl><dt>"hit-points", number</dt>
364 <dd>Unit hit-point gain, or loss if negative.
365 </dd>
366 <dt>"mana", number</dt>
367 <dd>Unit mana gain, or loss if negative.
368 </dd>
369 <dt>"max-multi-cast", number</dt>
370 <dd>This spell usually has some very small limits (like heal 2 hit-points
371 for 1 caster mana), and will get casted multiple times at once, until the
372 hp/mana limit for the unit is reached. You can set this to a reasonable
373 value so the spell can only get casted so many times at once. Like heal
374 2 hit-points for 1 caster mana up to 20 hit-points/10 mana per cast
375 </dd>
376 </dl></dd>
377 <dt id="DefineSpell.action.demolish">"demolish", tag, ...</dt>
378 <dd>This will remove any trees/rocks/walls in and inflict a fixed damage
379 to a fixed area. Possible tags:
380 <dl><dt>"damage", number</dt>
381 <dd>Each and every unit in range will receive that damage. FIXME: no
382 support for dampening damage.
383 </dd>
384 <dt>"range", number</dt>
385 <dd>The range of the terrain and unit damage.
386 </dd>
387 </dl></dd>
388 <dt>"summon", tag, ...</dt>
389 <dd>This will summon a new unit.
390 Manacost is substracted if action success (failed when no corpse or no place).
391 Possible tags:
392 <dl><dt>"unit-type", "unit-type-name"</dt>
393 <dd>Type of the unit to summon. Must be already defined.</dd>
394 <dt>"ttl", number</dt>
395 <dd>Time to live. The unit will only survive for that time, afterward it
396 will receive 1 damage every game cycle, ending it's life. If this is 0
397 or ommited then the summoned unit is permanent
398 </dd>
399 <dt>"require-corpse"</dt>
400 <dd>This flag does not take a value. When specified, the caster will
401 summon an unit from a corpse, and consume the corpse in the process.
402 You should make sure the summoned unit dies without a corpse.
403 </dd></dl>
404 How to do a reveal-map spell: define a special unit, give it the
405 revealer flag, and set the spell's range to "infinite". Please see
406 <a href="unittype.html#DefineUnitType">DefineUnitType()</a>
407 </dd>
408 <dt>"polymorph", tag, ...</dt>
409 <dd>This will tranform the unit, giving it a new unit type. Before you
410 ask, temporary polymorphing is not supported, but it would be a nice
411 feature to add in the future. Mana is substracted if action sucess (fail if no place for the new unit)
412 There is only one tag:
413 <dl><dt>"new-form", "unit-type-name"</dt>
414 <dd>Type of the unit to transform to. Must be already defined. This spell
415 can be used as an instant-kill spell by polymorphing into a harmless unit,
416 like a chicken.
417 </dd>
418 </dl></dd>
419 <dt>"spawn-missile", tag, ...</dt>
420 <dd>This will spawn a missile in the game. It's one of the most versatile
421 spell variants. Here are the paramenters:
422 <dl><dt>"ttl", number</dt>
423 <dd>Time to live for the missile. Usually means that the missile is
424 gone after this time, but for some missile classes it means something else.
425 </dd>
426 <dt>"damage", number</dt>
427 <dd>This is the damage for this missile, overriding the standard damage
428 defined for the missile.
429 </dd>
430 <dt>"delay", number</dt>
431 <dd>This is the delay for the missile. it means the missile will only
432 appear after this many ticks.
433 </dd>
434 <dt>"start-point", {flag, value, ...}</dt>
435 <dt>"end-point", {flag, value, ...}</dt>
436 <dd>Point to point-ish missiles need a start and an end point for the
437 trajectory.
438 <dl><dt>"base", "caster" or "target"</dt>
439 <dd>The base for the location calculation. Can be either caster or target.
440 </dd>
441 <dt>"add-x", number</dt>
442 <dt>"add-y", number</dt>
443 <dd>How much to add to the x or y coordinate, in pixels
444 </dd>
445 <dt>"add-rand-x", number</dt>
446 <dt>"add-rand-y", number</dt>
447 <dd>Add a random from 0 to number to the x or y coordinate, in pixels
448 </dd>
449 </dl></dd>
450 </dl></dd>
451 <dt>"capture", tag, ...</dt>
452 <dd>This will convert the target unit to the casters side.
453 Very useful for capturing enemy buildings and controling enemy units.
454 None of these tags need to be specified.
455 <dl><dt>"damage", number</dt>
456 <dd>The amount of damage the unit takes before it is converted.
457 Usually used with percent below</dd>
458 <dt>"percent", number</dt>
459 <dd>The precent of the target's total HP it has to be reduced below before
460 it will be converted.</dd>
461 <dt>"sacrifice"</dt>
462 <dd>If this tag is given the caster will die after casting the spell.</dd></dl></dd>
463 </dl>
464 </dd>
465 </dl>
466
467 <h4>Example</h4>
468
469 <pre class="lua">
470 DefineSpell("spell-healing",
471 "showname", "Healing",
472 "manacost", 6,
473 "range", 6,
474 "target", "unit",
475 "action", {{"adjust-vitals", "hit-points", 1},
476 {"spawn-missile", "missile", "missile-heal-effect",
477 "start-point", {"base", "target"}}},
478 "condition", {
479 "organic", "only", -- it is a defined-flag
480 "Building", "false",
481 "HitPoints", {MaxValuePercent = 100}
482 },
483 "sound-when-cast", "healing",
484 "autocast", {"range", 6, "condition", {"alliance", "only", "HitPoints", {MaxValuePercent = 90}}}
485 )
486 </pre>
487
488 <hr>
489 All trademarks and copyrights on this page are owned by their respective owners.
490 <address>(c) 2002-2007 by <a href="http://stratagus.org">
491 The Bos Wars Project</a></address></body></html>