Difference between revisions of "Manual:DIL Manual/dildestroy()"
Jump to navigation
Jump to search
(XML import) |
(checked against the compiler and the interpreter; example compiles) |
||
| Line 1: | Line 1: | ||
| − | + | = 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 <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.