A function computes a value and returns it, so it is used inside an expression: n := rnd(1, 6);. Functions that change things (such as load() or transfermoney()) return a value as well, and the value can be ignored. For writing your own functions, see Functions.
Each line gives the call with its arguments, the type of the value it returns, and what it does. Click a name for the full page: arguments, return values on failure, notes and an example that compiles. The Full Listing has every keyword on one page.
Strings
Text in and out of strings, and numbers as text.
| Function |
Returns |
What it does
|
atoi(s : string) |
integer |
The number written at the start of a string.
|
itoa(i : integer) |
string |
An integer written as text.
|
length(s : string)
length(sl : stringlist)
length(il : intlist) |
integer |
The length of a string, or the number of entries in a list.
|
left(s : string, n : integer) |
string |
Returns the first characters of a string.
|
right(s : string, n : integer) |
string |
Returns the last characters of a string.
|
mid(s : string, first : integer, last : integer) |
string |
Returns the characters from one position to another.
|
getword(s : string) |
string |
Takes the first word off a string.
|
getwords(s : string) |
stringlist |
Splits a string into its words.
|
split(s : string, sep : string) |
stringlist |
Cuts a string into pieces at a separator.
|
replace(old : string, new : string, s : string) |
string |
Replaces every occurrence of one text in a string with another.
|
tolower(s : string) |
string |
Returns a string in lower case.
|
toupper(s : string) |
string |
Returns a string in upper case.
|
strcmp(s1 : string, s2 : string) |
integer |
Compares two strings, minding upper and lower case.
|
strncmp(s1 : string, s2 : string, n : integer) |
integer |
Compares the first characters of two strings, minding upper and lower case.
|
textformat(s : string) |
string |
Turns the escapes \n and \r in a text into real line breaks.
|
Numbers and bits
| Function |
Returns |
What it does
|
rnd(from : integer, to : integer) |
integer |
A random whole number in a range.
|
openroll(dice : integer, end : integer) |
integer |
Rolls an open-ended die: high rolls add another roll, low rolls subtract one.
|
isset(value : integer, bits : integer) |
integer |
Tells whether any of some bits are set in an integer.
|
Finding units
Units by name, symbolic name or kind, and the game's global lists.
| Function |
Returns |
What it does
|
findunit(u : unitptr, s : string, flags : integer, list : unitptr)
findunit(u : unitptr, s : string, flags : integer, list : unitptr, type : integer) |
unitptr |
Finds a unit by name, the way commands find what a player names.
|
findrndunit(u : unitptr, where : integer, types : integer) |
unitptr |
Picks a random unit of the wanted kinds in one place.
|
findroom(sym : string) |
unitptr |
Finds a room by its symbolic name.
|
findsymbolic(sym : string)
findsymbolic(sym : string, idx : integer)
findsymbolic(u : unitptr, sym : string, flags : integer) |
unitptr |
Finds a unit by its symbolic name, the name@zone it was defined with.
|
findzone(zname : string) |
zoneptr |
Finds a zone by its name.
|
getcmd(s : string) |
cmdptr |
Finds a command from its name or an abbreviation.
|
ghead() |
unitptr |
The first unit in the game's global unit list.
|
global_head() |
unitptr |
Another name for ghead(): the first unit in the game's global unit list.
|
npc_head() |
unitptr |
The first NPC in the game's global unit list.
|
obj_head() |
unitptr |
The first object in the game's global unit list.
|
pc_head() |
unitptr |
The first player in the game's global unit list.
|
room_head() |
unitptr |
The first room in the game's global unit list.
|
zhead() |
zoneptr |
The first zone in the game.
|
zone_head() |
zoneptr |
Another name for zhead(): the first zone in the game.
|
chead() |
cmdptr |
The first command in the game's command table.
|
command_head() |
cmdptr |
Another name for chead(): the first command in the game's command table.
|
Making and testing units
| Function |
Returns |
What it does
|
load(sym : string) |
unitptr |
Makes a new NPC or object from its zone definition.
|
clone(u : unitptr) |
unitptr |
Makes a copy of an existing NPC or object.
|
equipment(ch : unitptr, pos : integer) |
unitptr |
The object a character wears or wields in a given position.
|
visible(ch : unitptr, u : unitptr) |
integer |
Tells whether a character can see a unit.
|
islight(u : unitptr) |
integer |
Tells whether there is light in a room.
|
fits(ch : unitptr, obj : unitptr, pos : integer) |
string |
Tells whether an object is the right size for a character.
|
can_carry(ch : unitptr, u : unitptr, n : integer) |
integer |
Tells whether a character can carry more of something, and if not, why.
|
pathto(from : unitptr, to : unitptr) |
integer |
Gives the first step of the shortest way from one unit's room to another's.
|
isaff(u : unitptr, id : integer) |
integer |
Tells whether a unit carries an affect with a given id.
|
getaffects(u : unitptr) |
stringlist |
Lists the affects on a unit, one string of numbers each.
|
Characters and combat
| Function |
Returns |
What it does
|
meleeattack(att : unitptr, def : unitptr, bonus : integer, wtype : integer, primary : integer) |
integer |
Makes a character attack another once in melee, starting a fight.
|
meleedamage(att : unitptr, def : unitptr, bonus : integer, wtype : integer) |
integer |
Makes a character strike another once, without first putting it into combat.
|
opponent(ch : unitptr, vict : unitptr) |
integer |
Tells whether two characters are fighting each other.
|
getopponent(ch : unitptr, i : integer) |
unitptr |
Gets one of a character's opponents by its place in the list.
|
getfollower(ch : unitptr, i : integer) |
unitptr |
Gets one of a character's followers by its place in the list.
|
getinteger(what : integer, u : unitptr, i : integer) |
integer |
Gets one of several numbers that the server computes, chosen by an index.
|
Spells, skills and weapons
| Function |
Returns |
What it does
|
attack_spell(spell : integer, caster : unitptr, medium : unitptr, target : unitptr, bonus : integer, effect : string) |
integer |
Hits a target with an offensive spell and returns the damage.
|
cast_spell(spell : integer, caster : unitptr, medium : unitptr, tgt : unitptr, effect : string)
cast_spell(spell : integer, caster : unitptr, medium : unitptr, tgt : unitptr) |
integer (or none, as a procedure) |
Casts a spell without mana or the caster's own casting.
|
spellindex(s : string) |
integer |
Finds a spell's number from its name or an abbreviation of it.
|
spellinfo(i : integer, realm : integer, sphere : integer, mana : integer, offensive : integer, resist : integer, media : integer, targets : integer) |
string |
Returns a spell's name and puts its properties in seven integer variables.
|
skill_name(i : integer) |
string |
Gives the name of a skill from its number.
|
weapon_name(i : integer) |
string |
Gives the name of a weapon type from its number.
|
weapon_info(i : integer) |
intlist |
The figures etc/weapons.def gives a weapon type.
|
Money
| Function |
Returns |
What it does
|
moneystring(amt : integer, verbose : integer) |
string |
Writes an amount of money out in coins.
|
purse(u : unitptr, coin : string) |
integer |
Counts the coins of one kind that a unit carries.
|
transfermoney(from : unitptr, to : unitptr, amount : integer) |
integer |
Moves money from one character to another, or creates or destroys it.
|
paycheck(pc : unitptr, place : unitptr) |
integer |
Tells whether a player's account allows them into the zone of a unit.
|
Players
| Function |
Returns |
What it does
|
isplayer(pname : string) |
integer |
Tells whether a player character of that name exists.
|
check_password(pc : unitptr, pwd : string) |
integer |
Tells whether a password is a player's password.
|
getcolor(key : string) |
string |
Returns the HTML tag that starts text in a named colour.
|
addcolor(pc : unitptr, key : string, colour : string) |
integer |
Gives a player their own colour for a colour name.
|
changecolor(pc : unitptr, key : string, colour : string) |
integer |
Changes one of a player's own colours.
|
delcolor(pc : unitptr, key : string) |
integer |
Removes one of a player's own colours.
|
Files
Strings and units saved on the server, and the server's logs and programs.
| Function |
Returns |
What it does
|
loadstr(filename : string, s : string) |
integer |
Reads a whole file into a string variable.
|
savestr(filename : string, s : string, mode : string) |
integer |
Writes a string to a file, to read back later with loadstr().
|
delstr(filename : string) |
integer |
Deletes a string file.
|
strdir(pattern : string) |
stringlist |
Lists the string files that DIL has saved, by a pattern.
|
restore(filename : string, u : unitptr) |
unitptr |
Loads units saved with store() back into the game.
|
delunit(filename : string) |
integer |
Deletes a unit file.
|
unitdir(pattern : string) |
stringlist |
Lists the unit files that DIL has stored, by a pattern.
|
flog(filename : string, s : string, mode : string) |
integer |
Writes a string to a file of its own in the server's log directory.
|
shell(cmd : string) |
integer |
Starts a program from the server's allow directory.
|
Time
| Function |
Returns |
What it does
|
asctime(t : integer) |
string |
Writes a time in seconds as a date, such as "Mon Nov 18 18:49:08 1996".
|
Events and messages
Which event woke the program, and what other programs say.
| Function |
Returns |
What it does
|
command(name : string)
command(no : integer) |
integer |
Tells whether the event that woke the program is a given command.
|
interrupt(flags : integer, condition, label) |
integer |
Sets up a jump to a label when a certain event wakes the program, whatever it is waiting for.
|
on_activation(condition, label)
on_activation(condition, skip) |
integer |
Sets a check that runs every time the program is woken, by any event, before the event reaches the program's wait() or pause.
|
send_pre(cmd : string, who : unitptr, med : unitptr, tgt : unitptr, pwr : integer, arg : string, other : unitptr) |
integer |
Asks the programs around a character whether a command may go ahead.
|
sact(text : string, show : integer, a1 : unitptr or string, a2 : unitptr or string, a3 : unitptr or string, to : integer) |
string |
Gives the text an act() would show, instead of sending it.
|
DIL programs
Programs on units, and calling functions by name.
| Function |
Returns |
What it does
|
dilfind(tmpl : string, u : unitptr) |
integer |
Tells whether a unit runs a DIL program from a given template.
|
dildestroy(tmpl : string, u : unitptr) |
integer |
Stops a DIL program on a unit and removes it.
|
dilcall(tmpl : string)(u : unitptr, i : integer, s : string) |
integer |
Calls a DIL function whose name is only known when the program runs.
|
See also