Bos Wars: Magic

Intro - Introduction to spells and missiles.

Functions

DefineMissileType( "missile-name", { tag = value, ...} )

missile-name

This is the unique identifier of the missile.

File = "file-path"

This is followed by the path of the file with the missile graphics.

Size = {x, y}

This if followed by a list of X and Y sizes of the missile sprite. F.E. 'size '(32 32)

Frames = number

The number of animation steps, multiplied with (NumDirections / 2 + 1). Thus, if Flip = true, then Frames is the number of frames in the graphic file. Missiles lack complicated animation scripts and just have a bunch of frames with equal duration.

Flip = boolean

Please see Frame numbers and flipping. The default is true, unlike in DefineUnitType.

NumDirections = number

Define the number of directions a missile can face. If Flip = true, not all of these directions are actually in the graphic file.

DrawLevel = Number

The draw level of the missile. Missiles and units are sorted by this value to determine the draw order.

FiredSound = "Sound-file"

Name of the sound played when the missile is fired.

ImpactSound = "Sound-file"

Name of the sound played when the missile hits it's target.

Class = "class-type"

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:

"missile-class-none"

Missile does nothing. Shouldn't really be used.

"missile-class-point-to-point"

Missile flies straight to destination animating on the way

"missile-class-point-to-point-with-hit"

Missile flies straight to destination keeping the first frame and the finishes the animation when hitting

"missile-class-point-to-point-cycle-once"

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

"missile-class-point-to-point-bounce"

Missile flies straight to destination, and the "bounces" by hitting every other tile on the path onward. This will also add one aditional flag:

num-bounces

This if folowed by an integer, representing the number of bounces(hits)

"missile-class-stay"

Missile will just go through it's animation once and vanish. booooring.

"missile-class-cycle-once"

Missile will just go through it's animation from start to and and back again, then vanish.

"missile-class-fire"

Missile is used for fire. More documentation?

"missile-class-hit"

The missile does not use a graphics File but instead shows the number of hit points lost by a unit. For use with SetDamageMissile.

"missile-class-parabolic"

Missile flies to destination with a parabolic path. It used the same animation as cycle-once

Delay = number

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.

Sleep = number

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.

Speed = number

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.

Range = number

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...

SplashFactor = number

The Splash divisor for damage done with range

ImpactMissile = "missile-type"

You can use this to spawn another missile on impact. F.E. ImpactMissile = "missile-explosion"

SmokeMissile = "missile-type"

The name of the next (other) missile to generate a trailing smoke. So it can be used to generate a chain of missiles.

CanHitOwner = boolean

Determines if the missile will affect the caster or not.

FriendlyFire = boolean

Determines if the missile will damage units belonging to the same player of the caster or to an ally.

Example

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" } )

DefineSpell( "spell-ident", tag, value, ... )

"showname", "name"

A neatly formatted string to be shown by the engine on the screen.

"manacost", number

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.

"repeat-cast"

If specified, the caster will cast it again. To be used with spells like area-bombardment to cast it again (area-bombardment is stackable)

"range", number or "infinite"

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.

"target", "self" or "position" or "unit"

Target type information. The following values are acceptable:

• "self": The spell will only affect the caster or the area around him, no targetting at all.
• "position": The unit will target a position.
• "unit": The unit will target an unit. The spell will be aborted if the target dies.

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).

"conditions", {flag, value, ...}

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:

"condition", {
  "building", "false"
  "max-slow-ticks", 10}

Here are the supported parameters:

"alliance", "true" or "false" or "only"

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.
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.

"opponent", "true" or "false" or "only"

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.

"self", "true" or "false" or "only"

This is a bool parameter too, just like alliance. I it a bit more special, since it specifies the behaviour for casting on yourself. A LOT of spells specify "self false", to disallow casting on yourself.

variable, {flag = value}

There is no parameter called variable. You can however use variables defined by DefineVariables()

Enable = "true" or "false" or "only"

variable is enable ?

MinValue = number

minimal value allowed.

MaxValue = number

maximal value allowed.

MinMax = number

minimal maximum-value (the field Max of the variable) allowed.

MinValuePercent = number

minimal value allowed in percent with Max value.

MaxValuePercent = number

maximal value allowed in percent with Max value.

ConditionApplyOnCaster = boolean

if true, check caster instead of target.

"autocast", {flag, value}

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:

"range", number

The range in which autocast runs. I think it's square?

"combat", "only" or "true" or "false"

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?)

"condition", {flag, value}

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.

"ai-cast", {flag, value}

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.

"action", {{"operation-name", flag, value, ...} , ...}

The effect of the spells. You can add multiple actions. Here are the supported operations, their paramenters, and what they do.

"area-bombardment"

This will a number of missiles to be thrown in a square area. Here are the available tags:

"fields", number

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.)

"shards", number

The amount of missiles to throw at random in the square.

"damage", number

The damage of each individual missile.

"start-offset-x", number

"start-offset-y", number

A missile hitting x,y will start at x + start-offset-x, y + start-offset-y. This value is in pixels, for better precision.

"adjust-variable", {VariableName = {tag = value, ...} or number, ...}

This will adjust variable "VariableName" of the unit (defined by DefineVariables().)
Using number n is equivalent to {Value = n, Max = n, Enable = (n == 0)}

Enable = boolean

Set Enable value.

Value = number

Set Value value.

Max = number

Set Max value.

Increase = number

Set Increase value.

InvertEnable = boolean

Invert Enable value.

AddValue = number

Add to Value value.

AddMax = number

Add to Max value.

AddIncrease = number

Add to Increase value.

IncreaseTime = number

add number time Increase to the value.

TargetIsCaster = "target" or "caster"

Apply to target or caster.

"adjust-vitals", tag, ...

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:

"hit-points", number

Unit hit-point gain, or loss if negative.

"mana", number

Unit mana gain, or loss if negative.

"max-multi-cast", number

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

"demolish", tag, ...

This will remove any trees/rocks/walls in and inflict a fixed damage to a fixed area. Possible tags:

"damage", number

Each and every unit in range will receive that damage. FIXME: no support for dampening damage.

"range", number

The range of the terrain and unit damage.

"summon", tag, ...

This will summon a new unit. Manacost is substracted if action success (failed when no corpse or no place). Possible tags:

"unit-type", "unit-type-name"

Type of the unit to summon. Must be already defined.

"ttl", number

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

"require-corpse"

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.

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 DefineUnitType()

"polymorph", tag, ...

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:

"new-form", "unit-type-name"

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.

"spawn-missile", tag, ...

This will spawn a missile in the game. It's one of the most versatile spell variants. Here are the paramenters:

"ttl", number

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.

"damage", number

This is the damage for this missile, overriding the standard damage defined for the missile.

"delay", number

This is the delay for the missile. it means the missile will only appear after this many ticks.

"start-point", {flag, value, ...}

"end-point", {flag, value, ...}

Point to point-ish missiles need a start and an end point for the trajectory.

"base", "caster" or "target"

The base for the location calculation. Can be either caster or target.

"add-x", number

"add-y", number

How much to add to the x or y coordinate, in pixels

"add-rand-x", number

"add-rand-y", number

Add a random from 0 to number to the x or y coordinate, in pixels

"capture", tag, ...

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.

"damage", number

The amount of damage the unit takes before it is converted. Usually used with percent below

"percent", number

The precent of the target's total HP it has to be reduced below before it will be converted.

"sacrifice"

If this tag is given the caster will die after casting the spell.

Example

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}
	},
	"sound-when-cast", "healing",
	"autocast", {"range", 6, "condition", {"alliance", "only", "HitPoints", {MaxValuePercent = 90}}}
)