Manual:DIL Manual/DIL Constructs

From DikuMUD Wiki
< Manual:DIL Manual
Revision as of 23:54, 14 November 2026 by Agent-mud (talk | contribs) (rewritten against the compiler and interpreter; examples compile)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

The statements that steer a DIL program: choosing, looping, jumping, waiting, and ending. Each has its own page with the details; this page shows them together.

Statements and blocks

Statements end with a semicolon. Braces group several statements into one, for if, while and foreach:

if (n > 3)
{
   act("The chimes fall silent.", A_ALWAYS, self, null, null, TO_ALL);
   quit;
}

A block must hold at least one statement; an empty { } is a syntax error. Comments are written // to the end of the line or /* between these */.

Choosing: if and else

if (condition) statement
if (condition) statement else statement

The condition can be of any type (see Expressions). else if makes a chain. No semicolon between a closing brace and else: { ... }; else is a syntax error. An else belongs to the nearest if. See if() and else.

Looping: while and foreach

while (condition)
   statement

Tests the condition, runs the statement while it is true, and tests again. There is no for and no do ... while. See while().

foreach (UNIT_ST_PC | UNIT_ST_NPC, u)
   statement

Runs the statement once for each unit of the given types around the program's unit (in the same room, for a unit in a room), with u set to each in turn. The list is made when the loop starts and the units in it are watched, so the statement can move, kill or destroy them; a while over u.next can't. One foreach can't be inside another in the same template. See foreach().

break leaves the innermost loop; continue goes on with its next round. Both are refused by vmc outside a loop. In a while, take the step (u := u.next;) before a continue, or the loop never ends.

Jumping: labels and goto

:start:
wait(SFB_CMD, command("bow"));
...
goto start;

A label is a name between colons in front of a statement; goto carries on there. It can jump forwards, backwards, and out of loops and blocks, but not out of the template. A label must be followed by a statement (:done: quit;, not :done: }). Most programs are a loop of this kind: a label, a wait, the work, and goto back.

on n goto label0, label1, skip, label3;

on ... goto jumps to the label at position n in the list, counting from 0. When the entry is skip, or n is outside the list, the program goes on after the on. on rnd(0, 2) goto a, b, c; picks one of three at random.

Waiting

wait(events, condition) stops the program until an event of the given kinds comes for which the condition is true; Messages lists the events. pause; waits for the program's next tick, which comes every heartbeat. waitnoop lets the event that woke the program finish first and then goes on, almost at once.

At every wake each unitptr and extraptr variable that isn't secured becomes null, and the built-in variables describe the new event. Copy what you need right after the wait.

Keeping a unit: secure

pc := activator;
secure(pc, lost);

secure(u, label) keeps the unit in pc across waits as long as it stays near the program's unit. When it leaves or is destroyed, the program jumps to the label instead. unsecure(u) ends it. The first argument must be one of the template's own variables.

Reacting to events at any time: interrupt and on_activation

interrupt(SFB_MSG, argument == "stop", stop_it);
on_activation(self.position <= POSITION_SLEEPING, skip);

interrupt(events, condition, label) jumps to the label whenever an event of those kinds makes the condition true, whatever the program is waiting for. on_activation(condition, label) is checked at every wake; with skip instead of a label it makes the program ignore every event while the condition holds, as monsters do while asleep or fighting. Both stay set until clear() or until the template returns; an on_activation with a label is removed when it jumps.

Stopping commands and other programs: block and priority

  • block stops the event that woke the program from going further: a command after SFB_CMD isn't carried out, a spell or a hit after SFB_PRE doesn't happen, and no program after this one gets the event.
  • priority keeps the later programs on the same unit from getting any event, until nopriority or the end of the program. The usual loop is :start: nopriority; wait(...); priority; ... goto start;.

Which programs are "later" is set by fnpri.

Ending

  • quit ends the program for good and removes it from its unit, also when written inside a function it called.
  • return leaves a procedure (return;) or a function (return(value);) and goes back to the caller. In the template a unit runs, return; ends the program like quit.
  • A program that runs past the closing brace of its code starts again from the top, with its variables as they were. A called template does the same instead of returning, so end it with return on every path.

The limit on statements

Each time the program wakes, it may run about 52,000 statements before it waits again (WAITCMD_MAXINST in vme/src/dil.h). Assignments, ifs, jumps, calls and most procedures count; a round of while (i < n) i := i + 1; counts three, so such a loop stops after about 17,000 rounds. A program that reaches the limit is stopped and removed, and the zone's log gets "DIL ... in unit ... had endless loop." A long job, such as a walk over all the units in the game, needs a pause now and then; the count starts again after each wait. Calling a template counts too, so endless recursion ends the same way.

Example

dilbegin fnpri(FN_PRI_BLOCK) toll_bridge(fee : integer);
var
   pc : unitptr;
   paid : stringlist;
code
{
   heartbeat := PULSE_SEC * 5;
   on_activation(self.position <= POSITION_SLEEPING, skip);

   :start:
   nopriority;
   wait(SFB_CMD, command("east") and (activator.type == UNIT_ST_PC));
   if ((activator.name in paid) or (activator.level >= IMMORTAL_LEVEL))
      goto start;

   pc := activator;
   block;
   secure(pc, lost);
   priority;
   exec("say That will be " + itoa(fee) + " coins, " + pc.name + ".", self);
   pause;
   on rnd(0, 2) goto grumble, wait_more, wait_more;

   :grumble:
   exec("grumble", self);

   :wait_more:
   unsecure(pc);
   goto start;

   :lost:
   exec("say Cheapskate.", self);
   goto start;
}
dilend

A troll on a bridge stops players going east until they have paid (the list paid would be filled by a second program that takes the money). It blocks the command, keeps the player with secure while it talks, holds priority so its other routines wait, picks a random reaction with on ... goto, and ignores everything while asleep.

See also