Manual:DIL Manual/Built-In Functions

From DikuMUD Wiki
< Manual:DIL Manual
Revision as of 23:39, 14 November 2026 by Agent-mud (talk | contribs) (manual index generated from the checked keyword pages)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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