Difference between revisions of "Manual:DIL Manual/attack spell()"
(XML import) |
(checked against the compiler and the interpreter; example compiles) |
||
| (One intermediate revision by one other user not shown) | |||
| Line 1: | Line 1: | ||
| + | = attack_spell() = | ||
| + | '''Function''' (integer). Hits a target with an offensive spell and returns the damage. | ||
| + | attack_spell(spell : integer, caster : unitptr, medium : unitptr, target : unitptr, | ||
| + | bonus : integer, effect : string) | ||
| − | < | + | The building block of the attack spells in <code>spells.zon</code>. It rolls the spell against |
| − | + | the target the way the server rolls any offensive spell: the caster's and target's spell | |
| − | + | skills, the target's armour and shield, an open roll, then the spell's damage chart. Then it | |
| − | + | deals the damage as a spell hit. That is an attack: the target fights back, and the caster may | |
| − | + | commit a crime. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | + | A spell's own template (the <code>func</code> of the spell in <code>spells.def</code>) normally | |
| − | + | calls it with the arguments it was given, as in the example. | |
| − | + | ||
| + | == Parameters == | ||
| + | {| class="wikitable" | ||
| + | ! Name !! Type !! Meaning | ||
| + | |- | ||
| + | | spell || integer || The spell, an <code>SPL_</code> constant from <code>vme/include/values.h</code>. Only spells from <code>SPL_GROUP_MAX</code> (12) to 499 that have a C function or a DIL template count. | ||
| + | |- | ||
| + | | caster || unitptr || Who casts it. Must be a character. | ||
| + | |- | ||
| + | | medium || unitptr || What it is cast through: the caster, a wand, a scroll... Must not be null. | ||
| + | |- | ||
| + | | target || unitptr || Who is hit. Must be a character (see Notes). | ||
| + | |- | ||
| + | | bonus || integer || Added to the attack roll: positive helps the caster, negative hinders. | ||
| + | |- | ||
| + | | effect || string || <code>""</code> for the usual hit messages, or the name of a DIL template (<code>name@zone</code>) that shows the effect instead. | ||
| + | |} | ||
| + | |||
| + | == Returns == | ||
| + | Integer: the damage dealt. 0 or less is a miss; 0 also when the target's shield blocked the | ||
| + | spell. A spell number outside the range, or one without a function, gives 0 and does nothing. | ||
| + | |||
| + | It fails when <code>caster</code> is null or not a character, when <code>medium</code> or | ||
| + | <code>target</code> is null, or when an argument is itself a failed value. | ||
| + | |||
| + | == Notes == | ||
| + | * '''The target must be a character.''' Only null is checked: an object or a room as the | ||
| + | target stops the server at once. | ||
| + | * Pass a string as <code>effect</code>, never the constant <code>null</code>. vmc accepts | ||
| + | <code>null</code>, but at run time the result is then a type error and the program stops | ||
| + | ("DIL SERIOUS ... Type error in ..."). | ||
| + | * The effect template must take <code>(medium : unitptr, target : unitptr, hm : integer)</code>. | ||
| + | It is copied onto the caster and run at once, with <code>activator</code> the caster and | ||
| + | <code>hm</code> the damage. While it is found, the standard hit and miss messages are not | ||
| + | shown; the damage is dealt either way. A template with other arguments is logged and ignored. | ||
| + | * Immortal targets take no damage, nor do two characters who may not attack each other | ||
| + | (player killing rules). | ||
| + | * If a secured unit died or left during the hit, the program jumps to that secure's label | ||
| + | straight after the call. | ||
| + | |||
| + | == Example == | ||
| + | <pre> | ||
| + | dilbegin holy_word_1(med : unitptr, targ : unitptr, arg : string, | ||
| + | hm : integer, effect : string); | ||
| + | code | ||
| + | { | ||
| + | if ((targ.alignment >= 0) or (hm <= 0)) | ||
| + | { | ||
| + | act("Nothing happens.", A_ALWAYS, self, null, null, TO_CHAR); | ||
| + | quit; | ||
| + | } | ||
| + | |||
| + | if (targ.alignment >= -350) | ||
| + | hm := attack_spell(SPL_HOLY_WORD, self, med, targ, 0, effect); | ||
| + | else | ||
| + | hm := attack_spell(SPL_HOLY_WORD, self, med, targ, +10, effect); | ||
| + | quit; | ||
| + | } | ||
| + | dilend | ||
| + | </pre> | ||
| + | The holy word spell from spells.zon: it hurts only evil targets, and the very evil ones more. | ||
| + | |||
| + | == See also == | ||
| + | * [[Manual:DIL Manual/cast spell()|cast_spell()]] | ||
| + | * [[Manual:DIL Manual/spellindex()|spellindex()]] | ||
| + | * [[Manual:DIL Manual/spellinfo()|spellinfo()]] | ||
| + | * [[Manual:DIL Manual/meleeattack()|meleeattack()]] | ||
| + | * [[Manual:DIL Manual/secure()|secure()]] | ||
Latest revision as of 23:19, 14 November 2026
attack_spell()
Function (integer). Hits a target with an offensive spell and returns the damage.
attack_spell(spell : integer, caster : unitptr, medium : unitptr, target : unitptr,
bonus : integer, effect : string)
The building block of the attack spells in spells.zon. It rolls the spell against
the target the way the server rolls any offensive spell: the caster's and target's spell
skills, the target's armour and shield, an open roll, then the spell's damage chart. Then it
deals the damage as a spell hit. That is an attack: the target fights back, and the caster may
commit a crime.
A spell's own template (the func of the spell in spells.def) normally
calls it with the arguments it was given, as in the example.
Parameters
| Name | Type | Meaning |
|---|---|---|
| spell | integer | The spell, an SPL_ constant from vme/include/values.h. Only spells from SPL_GROUP_MAX (12) to 499 that have a C function or a DIL template count.
|
| caster | unitptr | Who casts it. Must be a character. |
| medium | unitptr | What it is cast through: the caster, a wand, a scroll... Must not be null. |
| target | unitptr | Who is hit. Must be a character (see Notes). |
| bonus | integer | Added to the attack roll: positive helps the caster, negative hinders. |
| effect | string | "" for the usual hit messages, or the name of a DIL template (name@zone) that shows the effect instead.
|
Returns
Integer: the damage dealt. 0 or less is a miss; 0 also when the target's shield blocked the spell. A spell number outside the range, or one without a function, gives 0 and does nothing.
It fails when caster is null or not a character, when medium or
target is null, or when an argument is itself a failed value.
Notes
- The target must be a character. Only null is checked: an object or a room as the
target stops the server at once.
- Pass a string as
effect, never the constantnull. vmc accepts
null, but at run time the result is then a type error and the program stops
("DIL SERIOUS ... Type error in ...").
- The effect template must take
(medium : unitptr, target : unitptr, hm : integer).
It is copied onto the caster and run at once, withactivatorthe caster andhmthe damage. While it is found, the standard hit and miss messages are not shown; the damage is dealt either way. A template with other arguments is logged and ignored.
- Immortal targets take no damage, nor do two characters who may not attack each other
(player killing rules).
- If a secured unit died or left during the hit, the program jumps to that secure's label
straight after the call.
Example
dilbegin holy_word_1(med : unitptr, targ : unitptr, arg : string,
hm : integer, effect : string);
code
{
if ((targ.alignment >= 0) or (hm <= 0))
{
act("Nothing happens.", A_ALWAYS, self, null, null, TO_CHAR);
quit;
}
if (targ.alignment >= -350)
hm := attack_spell(SPL_HOLY_WORD, self, med, targ, 0, effect);
else
hm := attack_spell(SPL_HOLY_WORD, self, med, targ, +10, effect);
quit;
}
dilend
The holy word spell from spells.zon: it hurts only evil targets, and the very evil ones more.