Difference between revisions of "Manual:DIL Manual/attack spell()"

From DikuMUD Wiki
Jump to navigation Jump to search
(XML import)
(checked against the compiler and the interpreter; example compiles)
 
Line 1: Line 1:
−
<span id="bpatt_s"></span>
+
= attack_spell() =
−
integer attack_spell( n : integer, caster : unitptr, medium : unitptr,
+
'''Function''' (integer). Hits a target with an offensive spell and returns the damage.
−
                      target : unitptr, bonus : integer)
 
−
    Returns : The amount of damage given.
 
−
    n : The spell index of the offensive spell (SPL_XXX)
 
−
    caster : The caster of the spell.
 
−
    medium : The medium, with which the spell is cast, might be caster.
 
−
    target : The target of the spell.
 
−
    bonus  : Possible (+) advantage or (-) penalty.
 
  
−
    This is low-level internal spell stuff used to develop new spells. Do not
+
  attack_spell(spell : integer, caster : unitptr, medium : unitptr, target : unitptr,
−
    use unless you know what you are doing and have been allowed to do so by
+
              bonus : integer, effect : string)
−
    your Admin.
 
−
<span id="bpatt_s"></span>
 
−
  integer attack_spell( n : integer, caster : unitptr, medium : unitptr,
 
−
                      target : unitptr, bonus : integer)
 
−
    Returns : The amount of damage given.
 
−
    n : The spell index of the offensive spell (SPL_XXX)
 
−
    caster : The caster of the spell.
 
−
    medium : The medium, with which the spell is cast, might be caster.
 
−
    target : The target of the spell.
 
−
    bonus  : Possible (+) advantage or (-) penalty.
 
  
−
    This is low-level internal spell stuff used to develop new spells. Do not
+
The building block of the attack spells in <code>spells.zon</code>. It rolls the spell against
−
    use unless you know what you are doing and have been allowed to do so by
+
the target the way the server rolls any offensive spell: the caster's and target's spell
−
    your Admin.
+
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 constant null. 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, with activator the caster and
 hm 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

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.

See also