Difference between revisions of "Manual:DIL Manual/dildestroy()"

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="bfdd"></span>
+
= dildestroy() =
−
integer dildestroy( s : string, u : unitptr )
+
'''Function''' (integer). Stops a DIL program on a unit and removes it.
−
    s : name of dil template to delete.
 
−
    u : unit to remove program from.
 
−
    return: Whether a program using a template with same name as in 's'
 
−
            attached to unit 'u' was deleted.
 
  
−
  ---~---~---~---~---~---~---~---~---
+
  dildestroy(tmpl : string, u : unitptr) : integer
−
<span id="bfdd"></span>
 
−
integer dildestroy( s : string, u : unitptr )
 
−
    s : name of dil template to delete.
 
−
    u : unit to remove program from.
 
−
    return: Whether a program using a template with same name as in 's'
 
−
            attached to unit 'u' was deleted.
 
  
−
---~---~---~---~---~---~---~---~---
+
Finds the first running program on <code>u</code> made from the template <code>tmpl</code> and removes it. Just before, that program gets an <code>SFB_DILDESTROY</code> event, so it can tidy up (a <code>wait</code> or an [[Manual:DIL Manual/interrupt()|interrupt()]] on <code>SFB_DILDESTROY</code>); then it is stopped as if it had run <code>quit</code>.
 +
 
 +
== Parameters ==
 +
{| class="wikitable"
 +
! Name !! Type !! Meaning
 +
|-
 +
| tmpl || string || The template's name with its zone, <code>"name@zone"</code>. Without the <code>@zone</code> nothing is found.
 +
|-
 +
| u || unitptr || The unit the program is on.
 +
|}
 +
 
 +
== Returns ==
 +
TRUE when a program was found and removed, FALSE when <code>u</code> has none from that template (or the template doesn't exist). The call fails when <code>u</code> is null.
 +
 
 +
== Notes ==
 +
* Only one program is removed per call. A unit can carry several copies of the same template (spells put on twice, for example); to remove them all, loop with [[Manual:DIL Manual/dilfind()|dilfind()]] as in the example.
 +
* It looks at the template each program was started from. A program that is busy in a template it called still counts as its starting template.
 +
* Programs that have already ended are skipped.
 +
 
 +
== Example ==
 +
<pre>
 +
dilbegin cure_all(u : unitptr);
 +
var
 +
  i : integer;
 +
code
 +
{
 +
  while (dilfind("spl_poison@spells", u))
 +
      i := dildestroy("spl_poison@spells", u);
 +
  while (dilfind("spl_sleep@spells", u))
 +
      i := dildestroy("spl_sleep@spells", u);
 +
  quit;
 +
}
 +
dilend
 +
</pre>
 +
Removes every poison and magical sleep program from a character, as <code>remove_aff</code> in death.zon does.
 +
 
 +
== See also ==
 +
* [[Manual:DIL Manual/dilfind()|dilfind()]]
 +
* [[Manual:DIL Manual/dilcopy()|dilcopy()]]
 +
* [[Manual:DIL Manual/quit|quit]]
 +
* [[Manual:DIL Manual/interrupt()|interrupt()]]

Revision as of 23:18, 14 November 2026

dildestroy()

Function (integer). Stops a DIL program on a unit and removes it.

dildestroy(tmpl : string, u : unitptr) : integer

Finds the first running program on u made from the template tmpl and removes it. Just before, that program gets an SFB_DILDESTROY event, so it can tidy up (a wait or an interrupt() on SFB_DILDESTROY); then it is stopped as if it had run quit.

Parameters

Name Type Meaning
tmpl string The template's name with its zone, "name@zone". Without the @zone nothing is found.
u unitptr The unit the program is on.

Returns

TRUE when a program was found and removed, FALSE when u has none from that template (or the template doesn't exist). The call fails when u is null.

Notes

  • Only one program is removed per call. A unit can carry several copies of the same template (spells put on twice, for example); to remove them all, loop with dilfind() as in the example.
  • It looks at the template each program was started from. A program that is busy in a template it called still counts as its starting template.
  • Programs that have already ended are skipped.

Example

dilbegin cure_all(u : unitptr);
var
   i : integer;
code
{
   while (dilfind("spl_poison@spells", u))
      i := dildestroy("spl_poison@spells", u);
   while (dilfind("spl_sleep@spells", u))
      i := dildestroy("spl_sleep@spells", u);
   quit;
}
dilend

Removes every poison and magical sleep program from a character, as remove_aff in death.zon does.

See also