<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html><head>
<!--
---- (c) Copyright 2002-2007 by Lutz Sammer, Russell Smith
---- This program is free software; you can redistribute it and/or modify
---- it under the terms of the GNU General Public License as published by
---- the Free Software Foundation; only version 2 of the License.
----
---- This program is distributed in the hope that it will be useful,
---- but WITHOUT ANY WARRANTY; without even the implied warranty of
---- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
---- GNU General Public License for more details.
----
---- You should have received a copy of the GNU General Public License
---- along with this program; if not, write to the Free Software
---- Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA
---- 02111-1307, USA.
-->
<title>Bos Wars Scripting API: Magic</title>
<meta http-equiv="Content-Type" content="text/html; CHARSET=iso-8859-1">
</head>
<body>
<h1>Bos Wars: Magic</h1>
<hr>
<a href="../index.html">Stratagus</a>
<a href="../faq.html">FAQ</a>
<a href="game.html">PREV</a>
<a href="mappresentation.html">NEXT</a>
<a href="index.html">LUA Index</a>
<hr>
<a href="#DefineMissileType">DefineMissileType</a>
<a href="#DefineSpell">DefineSpell</a>
<!-- <a href="#missile">missile</a> -->
<hr>
<h2>Intro - Introduction to spells and missiles.</h2>
This containts everything around spells and missiles. Though it might not be
obvious at start missiles are also suited for complex behaviour and included here.
<h2>Functions</h2>
<a name="DefineMissileType"></a>
<h3>DefineMissileType( "missile-name", { tag = value, ...} )</h3>
This is the function to define a missile type.
<dl>
<dt>missile-name</dt>
<dd>This is the unique identifier of the missile.
</dd>
</dl>
Possible tags:
<dl>
<dt>File = "file-path"</dt>
<dd>This is followed by the path of the file with the missile graphics.
</dd>
<dt>Size = {x, y}</dt>
<dd>This if followed by a list of X and Y sizes of the missile sprite.
F.E. 'size '(32 32)
</dd>
<dt>Frames = number</dt>
<dd>This is the number of frames in the file. Missiles lack complicated
animation scripts and just have a bunch of frames with equal duration.
</dd>
<dt>NumDirections = number</dt>
<dd>The number of directions in the file for the missile. Should be 8 (or 5 for flipped missiles).
</dd>
<dt>DrawLevel = Number</dt>
<dd>The draw level of the missile. Missiles and units are sorted by this
value to determine the draw order.
</dd>
<dt>FiredSound = "Sound-file"</dt>
<dd>Name of the sound played when the missile is fired.
</dd>
<dt>ImpactSound = "Sound-file"</dt>
<dd>Name of the sound played when the missile hits it's target.
</dd>
<dt>Class = "class-type"</dt>
<dd>Various missiles can have wierd behaviours. This tag is followed by an
identifier that specifies some of that behaviour. Here is a list of currently
supported missile classes:
<dl>
<dt>"missile-class-none"</dt>
<dd>Missile does nothing. Shouldn't really be used.
</dd>
<dt>"missile-class-point-to-point" </dt>
<dd>Missile flies straight to destination animating on the way
</dd>
<dt>"missile-class-point-to-point-with-hit" </dt>
<dd>Missile flies straight to destination keeping the first frame and
the finishes the animation when hitting
</dd>
<dt>"missile-class-point-to-point-cycle-once" </dt>
<dd>Missile flies straight to destination and animates ONCE from first
to last and back again. To be used for catapult and the like to make a
projectile bigger mid-way to the target
</dd>
<dt>"missile-class-point-to-point-bounce"</dt>
<dd>Missile flies straight to destination, and the "bounces" by hitting
every other tile on the path onward. This will also add one aditional flag:
<dl><dt>num-bounces</dt>
<dd>This if folowed by an integer, representing the number of bounces(hits)</dd>
</dl></dd>
<dt>"missile-class-stay"</dt>
<dd>Missile will just go through it's animation once and vanish. booooring.
</dd>
<dt>"missile-class-cycle-once" </dt>
<dd>Missile will just go through it's animation from start to and and back
again, then vanish.
</dd>
<dt>"missile-class-fire" </dt>
<dd>Missile is used for fire. More documentation?
</dd>
<dt>"missile-class-parabolic"</dt>
<dd>Missile flies to destination with a parabolic path. It used the same
animation as cycle-once
</dd>
<dt>"missile-class-land-mine"</dt>
<dd>Missile is a landmine, it will sit quietly and wait for someone to step
on it. You can use time-to-live as a timeout.<b>FIXME more configurable</b>
</dd>
<dt>"missile-class-whirlwind" </dt>
<dd>Missile for the whirlwind effect <b>FIXME more configurable</b>
</dd>
<dt>"missile-class-flame-shield" </dt>
<dd>Missile rotates around target unit and damages everything it touches
<b>FIXME more configurable</b>
</dd>
<dt>"missile-class-death-coil"</dt>
<dd>Missile is death coil, will drain health from target or enemy units
in the area and feed it to the caster.<b>FIXME more configurable</b>
</dd>
</dl>
</dd>
<dt>Delay = number</dt>
<dd>Delay in game cycles after the missile generation, until the missile
animation and effects starts. Delay denotes the number of display cycles to
skip before drawing the first sprite frame and only happens once at start.
</dd>
<dt>Sleep = number</dt>
<dd>This are the number of game cycles to wait for the next animation or the
sleeping between the animation steps. All animations steps use the same delay.
0 is the fastest and 255 the slowest animation. Perhaps we should later we
will use animation scripts for more complex animations.
</dd>
<dt>Speed = number</dt>
<dd>The speed how fast the missile moves. 0 the missile didn't move, 1 is the
slowest speed and 32 s the fastest supported speed. This is how many pixels
the missiles moves with each animation step. The real use of this member
depends on the missile class. This is currently only used by the point-to-point
missiles.
</dd>
<dt>Range = number</dt>
<dd>Determines the range in which a projectile will deal its damage. A range of
0 will mean that the damage will be limited to the targetted unit only. So if
you shot a missile at a unit, it would only damage that unit. A value of 1 only
affects the field where the missile hits. A value of 2 would mean that the
damage for that particular missile would be dealt for a range of 1 around the
impact spot. All fields that aren't the center get only 1/SpashFactor of the damage.
Fields 2 away get 1/(SplashFactor*2), and following...
</dd>
<dt>SplashFactor = number</dt>
<dd>The Splash divisor for damage done with range
</dd>
<dt>ImpactMissile = "missile-type"</dt>
<dd>You can use this to spawn another missile on impact. F.E. ImpactMissile = "missile-explosion"
</dd>
<dt>SmokeMissile = "missile-type"</dt>
<dd>The name of the next (other) missile to generate a trailing smoke. So it
can be used to generate a chain of missiles.
</dd>
<dt>CanHitOwner = boolean</dt>
<dd>Determines if the missile will affect the caster or not.
</dd>
<dt>FriendlyFire = boolean</dt>
<dd>Determines if the missile will damage
units belonging to the same player of the caster or to an ally.
</dd>
</dl>
<h4>Example</h4>
<pre>
DefineMissileType("missile-fireball",
{ File = "missiles/fireball.png", Size = {32, 32}, Frames = 5, NumDirections = 5,
ImpactSound = "fireball hit",
DrawLevel = 50, Class = "missile-class-point-to-point-bounce", NumBounces = 5,
Sleep = 1, Speed = 16, Range = 1,
ImpactMissile = "missile-explosion" } )
</pre>
<a name="DefineSpell"></a>
<h3>DefineSpell( "spell-ident", tag, value, ... )</h3>
This is the function to define a spell, including it's effects and targetting
conditions. Be very carefull, defining random flags will probably make the game crash.
<dl>
<dt>"showname", "name"</dt>
<dd>A neatly formatted string to be shown by the engine on the screen.
</dd>
<dt>"manacost", number</dt>
<dd>The mana cost of the spell. But some actions (AdjustVitals, Summon, Polymorph) use it
for their own mana calculation and so. If spell use at least of these actions, mana is computed
by these action (which use manacost also),else it was substract from caster mana.
</dd>
<dt>"repeat-cast" </dt>
<dd>If specified, the caster will cast it again. To be used with spells like
area-bombardment to cast it again (area-bombardment is stackable)
</dd>
<dt>"range", number or "infinite"</dt>
<dd>The casting range of the spell, do not confuse this with area effect range.
It's normally an integer value, but you can specify a special value "infinite" to
let the spell be casted on the entire map.
</dd>
<dt>"target", "self" or "position" or "unit"</dt>
<dd>Target type information. The following values are acceptable:
<ul>
<li>"self": The spell will only affect the caster or the area around him, no targetting at all.
<li>"position": The unit will target a position.
<li>"unit": The unit will target an unit. The spell will be aborted if the target dies.
</ul>
You can still use position spells on units, it will target the unit's position.
If the unit dies however the caster will stop. (Some spells get casted until
there is no more mana left).
</dd>
<dt>"conditions", {flag, value, ...}</dt>
<dd>This is the condition for being able to cast the spell. Think of it as a
function that takes an unit as a parameter and return either yes or no depending
on the unit properties. Here is how a condition looks like:
<pre>"condition", {
"building", "false"
"max-slow-ticks", 10}</pre>
Here are the supported parameters:
<dl>
<dt>"alliance", "true" or "false" or "only"</dt>
<dd>This is one of the bool parameters (can't think of a better name). It is
followed by "true", "false" or "only". Imagine this as a question, is the target in
alliance? The answer is yes/no. A "true" parameter makes it always pass(and
it's the default.), "false" parameter passes when the answer is NO, and "only"
passes only when the answer is yes.<br>
It doesn't really makes sense to ever say true, since you might just as well
ommit it. "alliance false" means the spell won't work on allied units. "alliance
only" will make a spell that works only on allied units (can't think of any though).
Your own units are considered allied too.
</dd>
<dt>"opponent", "true" or "false" or "only"</dt>
<dd>This is a bool parameter too, just like alliance. I specifies the behaviour
for opponent units. Neutral units are neither allied unit nor opponent units.
</dd>
<dt>"self", "true" or "false" or "only"</dt>
<dd>This is a bool parameter too, just like alliance. I it a bit more special,
since it specifies the behaviour for casting on yourself. <b>A LOT</b> of
spells specify "self false", to disallow casting on yourself.
</dd>
<dt>bool-flags, "true" or "false" or "only"</dt>
<dd>There is no parameter called bool-flags. You can however use flags defined
by <a href="unittype.html#DefineBoolFlags">DefineBoolFlags()</a> just like a
bool parameter. For instance "organic", "only" will make a spell work only on
units marked with the "organic" flag.
</dd>
<dt>variable, {flag = value}</dt>
<dd>There is no parameter called variable. You can however use variables defined
by <a href="unittype.html#DefineVariables">DefineVariables()</a>
<dl>
<dt>Enable = "true" or "false" or "only"</dt>
<dd>variable is enable ?</dd>
<dt>MinValue = number </dt>
<dd>minimal value allowed.</dd>
<dt>MaxValue = number </dt>
<dd>maximal value allowed.</dd>
<dt>MinMax = number</dt>
<dd>minimal maximum-value (the field Max of the variable) allowed.</dd>
<dt>MinValuePercent = number</dt>
<dd>minimal value allowed in percent with Max value.</dd>
<dt>MaxValuePercent = number</dt>
<dd>maximal value allowed in percent with Max value.</dd>
<dt>ConditionApplyOnCaster = boolean</dt>
<dd>if true, check caster instead of target.</dd>
</dl></dd>
</dl>
</dd>
<dt>"autocast", {flag, value}</dt>
<dd>Autocast works very closely with conditions.
It functions by selecting every unit in range and trying to check of they fit the
condition. If they do, the spell is casted. Of course, this is a very primitive
mechanism, but it works for simple spells like heal. As you might have noticed, some
of the finer restrictions in conditions are designed for autocast (like not casting
buffs on cowards). Autocasting position target spells is not supported, sorry.
Here is a formal list of parameters:
<dl>
<dt>"range", number</dt>
<dd>The range in which autocast runs. I think it's square?
</dd>
<dt>"combat", "only" or "true" or "false"</dt>
<dd>This is a bool parameter, like in condition. It's autocast-specific and NOT
part of conditions due to technical considerations. Combat is not unit-specific,
it only depends on caster location. combat mode is when there are non-coward
enemy units in range. most offensive spells obviousely only should be used in
combat. (can you say offensive buffs?)
</dd>
<dt>"condition", {flag, value}</dt>
<dd>This is followed by a list exactly like in "condition". As it was said
before, this is evaluated for each and every unit in range, and if a unit
passes, the spell gets casted.
</dd>
</dl>
</dd>
<dt>"ai-cast", {flag, value}</dt>
<dd>This is identical to autocast in syntax. It's used by the AI (computer controller
player) rather then by a human players units. In general this should be a little better
than autocast (and make human players think some more). There no reason to repeat the
syntax of autocast here.
</dd>
<dt>"action", {{"operation-name", flag, value, ...} , ...}</dt>
<dd>The effect of the spells. You can add multiple actions.
Here are the supported operations, their paramenters, and what they do.
<dl>
<dt>"area-bombardment"</dt>
<dd>This will a number of missiles to be thrown in a square area. Here are
the available tags:
<dl><dt>"fields", number</dt>
<dd>The size of the affected square. This will get centered on the target
It should really be an odd number, or it will look wierd (not centered.)
</dd>
<dt>"shards", number</dt>
<dd>The amount of missiles to throw at random in the square.
</dd>
<dt>"damage", number</dt>
<dd>The damage of each individual missile.
</dd>
<dt>"start-offset-x", number</dt>
<dt>"start-offset-y", number</dt>
<dd>A missile hitting x,y will start at x + start-offset-x, y + start-offset-y.
This value is in pixels, for better precision.
</dd>
</dl></dd>
<dt>"adjust-variable", {VariableName = {tag = value, ...} or number, ...}</dt>
<dd>This will adjust variable "VariableName" of the unit
(defined by <a href="unittype.html#DefineVariables">DefineVariables().</a>)<br>
Using number n is equivalent to {Value = n, Max = n, Enable = (n == 0)}
<dl>
<dt>Enable = boolean</dt>
<dd>Set Enable value.</dd>
<dt>Value = number</dt>
<dd>Set Value value.</dd>
<dt>Max = number</dt>
<dd>Set Max value.</dd>
<dt>Increase = number</dt>
<dd>Set Increase value.</dd>
<dt>InvertEnable = boolean</dt>
<dd>Invert Enable value.</dd>
<dt>AddValue = number</dt>
<dd>Add to Value value.</dd>
<dt>AddMax = number</dt>
<dd>Add to Max value.</dd>
<dt>AddIncrease = number</dt>
<dd>Add to Increase value.</dd>
<dt>IncreaseTime = number</dt>
<dd>add number time Increase to the value.</dd>
<dt>TargetIsCaster = "target" or "caster"</dt>
<dd>Apply to target or caster.</dd>
</dl></dd>
<dt>"adjust-vitals", tag, ...</dt>
<dd>This will adjust vitals of the unit. Vitals are health, mana, and on a sunny
day maybe even shield. mana of caster is modified like this :
newmana = oldmana - manacost * castcount.
Where castcount is the number of time vitals are inc/decreased.
Possible tags:
<dl><dt>"hit-points", number</dt>
<dd>Unit hit-point gain, or loss if negative.
</dd>
<dt>"mana", number</dt>
<dd>Unit mana gain, or loss if negative.
</dd>
<dt>"max-multi-cast", number</dt>
<dd>This spell usually has some very small limits (like heal 2 hit-points
for 1 caster mana), and will get casted multiple times at once, until the
hp/mana limit for the unit is reached. You can set this to a reasonable
value so the spell can only get casted so many times at once. Like heal
2 hit-points for 1 caster mana up to 20 hit-points/10 mana per cast
</dd>
</dl></dd>
<dt>"demolish", tag, ...</dt>
<dd>This will remove any trees/rocks/walls in and inflict a fixed damage
to a fixed area. Possible tags:
<dl><dt>"damage", number</dt>
<dd>Each and every unit in range will receive that damage. FIXME: no
support for dampening damage.
</dd>
<dt>"range", number</dt>
<dd>The range of the terrain and unit damage.
</dd>
</dl></dd>
<dt>"summon", tag, ...</dt>
<dd>This will summon a new unit.
Manacost is substracted if action success (failed when no corpse or no place).
Possible tags:
<dl><dt>"unit-type", "unit-type-name"</dt>
<dd>Type of the unit to summon. Must be already defined.</dd>
<dt>"ttl", number</dt>
<dd>Time to live. The unit will only survive for that time, afterward it
will receive 1 damage every game cycle, ending it's life. If this is 0
or ommited then the summoned unit is permanent
</dd>
<dt>"require-corpse"</dt>
<dd>This flag does not take a value. When specified, the caster will
summon an unit from a corpse, and consume the corpse in the process.
You should make sure the summoned unit dies without a corpse.
</dd></dl>
How to do a reveal-map spell: define a special unit, give it the
revealer flag, and set the spell's range to "infinite". Please see
<a href="unittype.html#DefineUnitType">DefineUnitType()</a>
</dd>
<dt>"polymorph", tag, ...</dt>
<dd>This will tranform the unit, giving it a new unit type. Before you
ask, temporary polymorphing is not supported, but it would be a nice
feature to add in the future. Mana is substracted if action sucess (fail if no place for the new unit)
There is only one tag:
<dl><dt>"new-form", "unit-type-name"</dt>
<dd>Type of the unit to transform to. Must be already defined. This spell
can be used as an instant-kill spell by polymorphing into a harmless unit,
like a chicken.
</dd>
</dl></dd>
<dt>"spawn-missile", tag, ...</dt>
<dd>This will spawn a missile in the game. It's one of the most versatile
spell variants. Here are the paramenters:
<dl><dt>"ttl", number</dt>
<dd>Time to live for the missile. Usually means that the missile is
gone after this time, but for some missile classes it means something else.
</dd>
<dt>"damage", number</dt>
<dd>This is the damage for this missile, overriding the standard damage
defined for the missile.
</dd>
<dt>"delay", number</dt>
<dd>This is the delay for the missile. it means the missile will only
appear after this many ticks.
</dd>
<dt>"start-point", {flag, value, ...}</dt>
<dt>"end-point", {flag, value, ...}</dt>
<dd>Point to point-ish missiles need a start and an end point for the
trajectory.
<dl><dt>"base", "caster" or "target"</dt>
<dd>The base for the location calculation. Can be either caster or target.
</dd>
<dt>"add-x", number</dt>
<dt>"add-y", number</dt>
<dd>How much to add to the x or y coordinate, in pixels
</dd>
<dt>"add-rand-x", number</dt>
<dt>"add-rand-y", number</dt>
<dd>Add a random from 0 to number to the x or y coordinate, in pixels
</dd>
</dl></dd>
</dl></dd>
<dt>"capture", tag, ...</dt>
<dd>This will convert the target unit to the casters side.
Very useful for capturing enemy buildings and controling enemy units.
None of these tags need to be specified.
<dl><dt>"damage", number</dt>
<dd>The amount of damage the unit takes before it is converted.
Usually used with percent below</dd>
<dt>"percent", number</dt>
<dd>The precent of the target's total HP it has to be reduced below before
it will be converted.</dd>
<dt>"sacrifice"</dt>
<dd>If this tag is given the caster will die after casting the spell.</dd></dl></dd>
</dl>
</dd>
<dt>"depend-upgrade", "upgrade-name"</dt>
<dd>The dependency of the spell. Spell is available only once the upgrade is searched.
Upgrade must be already declare.</dd>
</dl>
<h4>Example</h4>
<pre>
DefineSpell("spell-healing",
"showname", "Healing",
"manacost", 6,
"range", 6,
"target", "unit",
"action", {{"adjust-vitals", "hit-points", 1},
{"spawn-missile", "missile", "missile-heal-effect",
"start-point", {"base", "target"}}},
"condition", {
"organic", "only", -- it is a defined-flag
"Building", "false",
"HitPoints", {MaxValuePercent = 100}
},
"depend-upgrade", "upgrade-healing",
"sound-when-cast", "healing",
"autocast", {"range", 6, "condition", {"alliance", "only", "HitPoints", {MaxValuePercent = 90}}}
)
</pre>
<!-- Useful to explain save format ?
<a name="missile"></a>
<h3>(missile tag 'value ... )</h3>
This function will define a mid-game missile, and it is mostly used in savegames.
<dl>
<dt>type</dt>
<dd>The type of the missile. Declared with
<a href=#define-missile-type>(define-missile-type)</a>
</dd>
<dt>pos</dt>
<dd>The current position of the missile. It's list of and y values. Coordinates are
in pixels, not tiles. F.E 'pos (4500 3450)
</dd>
<dt>origin-pos</dt>
<dd>The starting position of the missile. It's list of and y values. Coordinates are
in pixels, not tiles. F.E 'pos (4505 3455)
</dd>
<dt>goal</dt>
<dd>The position of the missile's destination. It's list of and y values. Coordinates are
in pixels, not tiles. F.E 'gold (4510 3460)
</dd>
<dt>local</dt>
<dd>This unit is marked as local, and it's visible only to the player. This
is used for instance for cursor marks on the map. Either local or global must be specified.
</dd>
<dt>global</dt>
<dd>This unit is marked as global, and it's visible to all players. Either
local or global must be specified.
</dd>
<dt>frame</dt>
<dd>Current sprite frame of the missile. The range is from 0 to the
<a href="#FRAMES-Define-missile-type">type:frames</a>-1
The topmost bit (128) is used as flag to mirror the sprites in the X direction.
</dd>
<dt>state</dt>
<dd>Current state of the missile. Used for a simple state machine, dependand on
the missile class.
</dd>
<dt>wait</dt>
<dd>Wait this number of game cycles until the next state or animation of this
missile is handled. This counts down from type:sleep to 0.
</dd>
<dt>delay</dt>
<dd>Number of game cycles left until the missile is first shown on the map.
Please see <a href="#delay-define-missile-type">delay in (define-missile-type)</a>
</dd>
<dt>source<dt>
<dd>Number of the owner of the missile. Normally the one who fired the missile.
Used to check units, to prevent hitting the owner. Also used for kill and
experience points, and for giving the owning player score.
</dd>
<dt>target<dt>
<dd>Number of the missile's target. Normally the unit which should be
hit by the missile.
</dd>
<dt>damage<dt>
<dd>Damage done by missile. Units next to it can receive some reduced splash
damage, this is the full damage.
</dd>
<dt>ttl</dt>
<dd>Time to live in game cycles of the missile, if it reaches zero
the missile is automatically removed from the map. If -1 the
missile lives for ever and the lifetime is handled by other means.
</dd>
<dt>hidden</dt>
<dd>This marks the unit as hidden, until the unit is shown again in the
controlling function. No parameters.
</dd>
</dl>
<h4>Example</h4>
<pre>
(missile 'type-fireball 'pos '(10 10) 'goal '(10 50)
'global 'state 0 'wait 5 'damage 5000 'source 45 'ttl -1)
</pre>
-->
<hr>
All trademarks and copyrights on this page are owned by their respective owners.
<address>(c) 2002-2007 by <a href="http://stratagus.org">
The Bos Wars Project</a></address></body></html>
