Manual:DIL Manual/Making a Program
A DIL program is written in a zone file, compiled with the zone by vmc, and run by the game server on a unit: a room, an object, an NPC or a player. This page goes through a whole program from nothing: where it is written, its parts, how it gets onto a unit, how it runs and waits, and how to compile it. A complete example is at the end.
Contents
Templates
A program is written once, as a template, between dilbegin and dilend. Each unit that runs it gets its own copy: the copy has its own variables and its own place in the code, while the code itself is shared. Ten guards with the same template are ten programs that know nothing of each other's variables.
A template's full name is name@zone: its name (at most 15 characters) and the zone it is written in. Templates are also called by other templates, as procedures or as functions (see Functions).
Where DIL is written
- The
%dilsection of a zone, after%zoneand before%rooms, holds the zone's templates. Any unit of any zone can use them by their full name. - Inside a unit's definition: a
dilbegin ... dilendwritten among a room's, object's or mobile's fields is a template of the zone too, and that unit gets a copy every time it is loaded. Such a template takes no arguments. dilcopy name@zone(arguments);in a unit's definition gives every unit loaded from that definition a copy of the template. The arguments are constants: numbers, strings, and lists in braces ({"a", "b"},{1, 2}). A unit can have severaldilcopylines. The%resetsection has nodilcopyof its own: the program comes with the definition of the unit the reset loads.- At run time, dilcopy() puts a copy on any unit:
dilcopy("name@zone(arg1,arg2)", u);, with string and integer arguments only. - As a player command: a template named with
func = name@zoneinvme/etc/commands.defruns when the command is typed. It takes one string argument, the rest of the line, andselfis the character who typed it. Spells are templates named the same way invme/etc/spells.def.
The zone must start with #include <macros.h>: dilend, pause and on_activation are macros from it, and vmc needs the ^ that dilend adds to find the end of each program.
The parts of a template
dilbegin [options] [type] name(arg : type, ...);
external
other templates it calls
var
its variables
code
{
statements
}
dilend
- The header names the template and its arguments. The options are aware, recall, unique and fnpri. A type before the name makes the template a function that returns a value of that type. See dilbegin.
- external declares the templates this one calls, also those in the same zone.
- var declares the variables, each with one of the eight data types. They start empty: 0, "", an empty list or null.
- code holds the statements in one pair of braces. Labels for goto are written
:name:.
Every function, field and built-in variable of DIL is a reserved word, so name, target, level, key and many more can't be variable names. vmc then reports a syntax error with that word as the token.
How a program runs
A copy starts at the first statement of code soon after its unit is loaded (or, for dilcopy(), at the unit's next tick). It runs until it waits, and waits most of its life:
- wait(events, condition) stops the program until an event of one of the given kinds comes for which the condition is true. The events are the
SFB_values: a command typed nearby (SFB_CMD), a command done (SFB_DONE), a message from another program (SFB_MSG), the program's timer (SFB_TICK), and others; see Messages. pause;waits for the program's next tick. The tick comes every heartbeat, which the program sets:heartbeat := PULSE_SEC * 30;is every 30 seconds.- interrupt() and on_activation() make the program react to some events whatever it is waiting for.
When an event wakes the program, the built-in variables activator, argument, medium, target and power describe it, and command(...) tells which command it was. self is always the program's own unit.
Two rules make DIL different from most languages:
- At every wake, every
unitptrandextraptrvariable becomes null, unless the unit was kept with secure(). The unit may have left or been destroyed while the program slept. Copy what you need right after thewait, and find units again after apause. Integers, strings and lists keep their values. - A program can't run forever without waiting. After about 52,000 statements without a wait (about 17,000 rounds of a one-line
whileloop) the server stops it and writes "had endless loop" to the zone's log.
The usual shape is a loop: a label, a wait, the work, and goto back to the label. A program ends for good with quit, or when its unit is destroyed. One that runs past the closing brace of code starts again from the top, with its variables as they were.
Programs on a player, and on the things a player carries, are saved with the player. Their integer, string and list variables are saved too; with recall the program also goes on from where it waited, instead of starting again.
Compiling
Zone files are in vme/zone/. Compile a zone with vmc, the zone compiler:
cd vme/zone ../bin/vmc -m -d ../etc/ -I../include/ myzone.zon
-m compiles only zones that have changed; -s checks the syntax without writing any files. vmc writes myzone.data and myzone.reset, which the server reads, and myzone.dh, a list of the zone's templates ready to copy into another template's external section. An error is reported with the line number and the token where vmc stopped:
30: syntax error
Token: 'name'
A new zone is listed in vme/etc/zonelist. The server reads zones only when it starts, so restart it after compiling. Errors while a program runs, such as a template that isn't found, a type error or an endless loop, are written to the zone's log in vme/bin/vme.log.
A complete example
#include <macros.h>
%zone mytown
lifespan 20
reset RESET_ANYHOW
creators {"manual"}
%dil
dilbegin town_crier(news : stringlist);
var
i : integer;
code
{
heartbeat := PULSE_SEC * 60;
:start:
wait(SFB_TICK | SFB_CMD, command(CMD_AUTO_TICK) or
(command("say") and (activator.type == UNIT_ST_PC)
and ("news" in argument)));
if (length(news) == 0)
quit;
if (i >= length(news))
i := 0;
exec("say Hear ye! " + news.[i], self);
i := i + 1;
goto start;
}
dilend
%rooms
square
title "The Town Square"
descr "Cobbled streets meet here around an old well."
dilbegin no_sleep();
code
{
:start:
wait(SFB_CMD, command("sleep") and (activator.type == UNIT_ST_PC));
act("Not in the middle of the square, please.",
A_ALWAYS, activator, null, null, TO_CHAR);
block;
goto start;
}
dilend
end
%mobiles
crier
names {"town crier", "crier"}
title "the town crier"
descr "The town crier stands by the well with a big bell."
M_AVG_HUMAN(5, SEX_MALE)
dilcopy town_crier@mytown({"The bridge is mended.", "Taxes are due on Friday."});
end
%reset
load crier into square max 1
%end
town_crieris a template in%dilthat takes a list of news. The crier's definition copies it onto every crier with two pieces of news. Every minute, and whenever a player says something with "news" in it, the crier says the next piece. The wait wakes for two kinds of event (SFB_TICK | SFB_CMD), and the condition lets ticks through withcommand(CMD_AUTO_TICK)and commands only when a player says "news". The crier doesn't hear its ownsay: a program isn't woken by its own unit's commands unless it is aware.no_sleepis written inside the room, so the room runs it. It wakes before a player'ssleepcommand runs, answers, and blocks the command so that it never happens.- The reset loads one crier into the square.
To try it, save it as vme/zone/mytown.zon, compile it, add mytown to vme/etc/zonelist and restart the server; a god can then goto square@mytown. Started as vme -w, the server lets the ticks pass without waiting (see Ending Notes).