Manual:Zone Manual/The Objects Section/DIL functions for objects

From DikuMUD Wiki
< Manual:Zone Manual‎ | The Objects Section
Revision as of 06:14, 15 November 2026 by Agent-mud (talk | contribs) (checked against the current code (wiki review 2026-11-15))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

DIL functions for objects

DIL is the language for writing your own special behaviour for rooms, NPCs and objects. This manual is about writing zones, so it doesn't teach DIL (that is the DIL Manual); but the zones that come with the server contain many ready-made DIL functions that you can put on your objects without writing any DIL. This page describes the ones made for objects: the restrictions, the Tuborg drink, the message board and blowaway.

You put a function on an object with a dilcopy line in the object, ending in a semicolon:

dilcopy abi_restrict@function(ABIL_STR, 40, 0, 25, "");

abi_restrict is the name of the function and function the zone it is in (function.zon). vmc checks that the constants you use exist, but it doesn't check the function's name, nor the number or types of its arguments: a mistake there shows up only when the server boots or the function runs, in the server log. So copy the argument lists below carefully. See also dilcopy().

Restriction functions

The restriction functions keep an item away from players who shouldn't use it: only paladins, only players who have done a quest, only players strong enough, and so on. An item may have several; the player then has to pass all of them.

They all work the same way. When a player has worn, wielded or held the item (they wait for SFB_DONE after those commands) and fails the test:

  • the player is told so ("Your item burns you and you drop it to the ground.", and a line that says what is wrong, such as "Being in the right guild might help.");
  • the player loses hit points (see below);
  • the item is taken off and put on the floor of the room.

The test is made only at that moment: a player who stops qualifying later keeps the item on until he wears it again.

Not tested:

  • immortals (level 200, IMMORTAL_LEVEL, and up);
  • NPCs, unless they serve a player (their master is a player). A reset can therefore equip an NPC with a restricted item. vlevel_restrict and anti_guild never test NPCs.

The last three arguments are the same for every restriction:

..., damage, percent, action);
damage, percent
Meant as the damage done to a player who fails: percent percent of his current hit points, at most damage points; with percent 0, exactly damage points; -1 for a random amount. In the current code these two arguments are ignored: every restriction sets them to 0 and 25 before it tests, so a failing player always loses a quarter of his current hit points. Many zones write 0, 25.
action
"" for the standard messages. Otherwise the name of a DIL procedure, as "name@zone", which is called instead of the messages (the damage and the drop still happen). It runs on the item, so self is the item and self.outside the player. Some restrictions pass it an argument, listed in the table below; it must take exactly those arguments, or the call stops the restriction program (see calling a template by a name in a string).

An example of an action, in the %dil section of a zone called ex, and the line that uses it:

dilbegin too_weak(needed : integer);
code
{
   act("You need a strength of " + itoa(needed) + " to wear $2n.",
       A_ALWAYS, self.outside, self, null, TO_CHAR);
   act("$1n can't carry the weight of $2n and drops it.",
       A_SOMEONE, self.outside, self, null, TO_REST);
   return;
}
dilend
dilcopy abi_restrict@function(ABIL_STR, 40, 0, 25, "too_weak@ex");

The restrictions, all in function.zon:

Restriction functions
Function and arguments Who may use the item The action gets
guild_restrict(guilds : stringlist, damage, percent, action) members of any of the guilds nothing
anti_guild(guilds : stringlist, damage, percent, action) players in none of the guilds nothing
prof_restrict(prof : integer, damage, percent, action) players of that profession nothing
quest_restrict(quest : string, damage, percent, action) players who have the quest nothing
nquest_restrict(quests : stringlist, damage, percent, action) players who have any one of the quests nothing
quests_restrict(quests : stringlist, damage, percent, action) the same as nquest_restrict: any one of the quests nothing
ali_restrict(max : integer, min : integer, damage, percent, action) players with an alignment from min to max max, min
level_restrict(level : integer, damage, percent, action) players of at least that level the levels missing
vlevel_restrict(vlevel : integer, damage, percent, action) players of at least that virtual level the levels missing
mvlev_restrict(vlevel : integer, damage, percent, action) players of at most that virtual level the levels too many, as a negative number
race_restrict(race : integer, damage, percent, action) everyone except that race nothing
sex_restrict(sex : integer, damage, percent, action) players of that sex nothing
ply_restrict(name : string, damage, percent, action) the player with that name nothing
abi_restrict(ability : integer, min : integer, damage, percent, action) players with at least min in the ability min
ski_restrict(skill : integer, min : integer, damage, percent, action) players with at least min in the skill min
sp_restrict(spell : integer, min : integer, damage, percent, action) players with at least min in the spell min
weap_restrict(weapon : integer, min : integer, damage, percent, action) players with at least min in the weapon skill min

The constants for the first argument come from the headers that macros.h includes. The values.h appendices list several of them.

guild_restrict and anti_guild

The guilds are given by name, with the GUILD_* macros in values.h (GUILD_PALADIN is "Midgaard Paladin", GUILD_SORCERER is "Midgaard Sorcerer", and so on). An item only paladins and sorcerers can use:

dilcopy guild_restrict@function({GUILD_PALADIN, GUILD_SORCERER}, 0, 25, "");

An item that paladins and sorcerers can't use:

dilcopy anti_guild@function({GUILD_PALADIN, GUILD_SORCERER}, 0, 25, "");

There is no anti_guild_restrict; the function is called anti_guild.

prof_restrict

The profession is one of the PROFESSION_* constants in values.h:

dilcopy prof_restrict@function(PROFESSION_BARBARIAN, 0, 25, "");
quest_restrict, nquest_restrict and quests_restrict

The quest is the name of an entry in the player's quests. One quest:

dilcopy quest_restrict@function("Eagles quest complete", 0, 25, "");

Any one of several quests:

dilcopy nquest_restrict@function({"Eagles quest complete",
                                  "Feather fall quest complete"}, 0, 25, "");

quests_restrict does the same as nquest_restrict. To require several quests, add one quest_restrict line for each.

ali_restrict

The first two arguments are the highest and the lowest alignment that may use the item (if you swap them, the function swaps them back). Alignment goes from -1000 to 1000. An item for good players only:

dilcopy ali_restrict@function(1000, 350, 0, 25, "");
level_restrict, vlevel_restrict and mvlev_restrict

level_restrict tests the level, which for players stops at 50; above that only the virtual level, vlevel, goes up. So use vlevel_restrict for a minimum above 50. mvlev_restrict sets a maximum instead, for items meant for low level players.

dilcopy level_restrict@function(20, 0, 25, "");
dilcopy vlevel_restrict@function(100, 0, 25, "");
dilcopy mvlev_restrict@function(50, 0, 25, "");
race_restrict

This one works the other way round: it keeps one race out. The race is a RACE_* constant from values.h. An item humans can't use:

dilcopy race_restrict@function(RACE_HUMAN, 0, 25, "");
sex_restrict

The sex is SEX_NEUTRAL, SEX_MALE or SEX_FEMALE (vme.h). An item only female players can use:

dilcopy sex_restrict@function(SEX_FEMALE, 0, 25, "");
ply_restrict

The item belongs to one player. Looking at it also shows "Whistler owns this ...". It is mostly put on an item by a quest, from DIL, when the player is known; in a zone file it is for an item made for a player you know in advance.

dilcopy ply_restrict@function("Whistler", 0, 25, "");
abi_restrict, ski_restrict, sp_restrict and weap_restrict

The first argument is the ability, skill, spell or weapon, the second the least the player must have of it. The abilities are ABIL_MAG, ABIL_DIV, ABIL_STR, ABIL_DEX, ABIL_CON, ABIL_CHA, ABIL_BRA and ABIL_HP (vme.h); skills are SKI_*, spells SPL_* and weapons WPN_*, all in values.h (see Skill definitions, Spell definitions and weapon definitions).

dilcopy abi_restrict@function(ABIL_STR, 50, 0, 25, "");
dilcopy ski_restrict@function(SKI_TURN_UNDEAD, 50, 0, 25, "");
dilcopy sp_restrict@function(SPL_LOCK, 50, 0, 25, "");
dilcopy weap_restrict@function(WPN_BATTLE_AXE, 50, 0, 25, "");

For more than one ability, add a line for each. An item for players with at least 50 divinity and 30 brains:

dilcopy abi_restrict@function(ABIL_DIV, 50, 0, 25, "");
dilcopy abi_restrict@function(ABIL_BRA, 30, 0, 25, "");
The *_RESTRICT macros

values.h also has macros such as LEVEL_RESTRICT(...) and ABILITY_RESTRICT(...). They only add a hidden extra to the item, and nothing in the current game reads those extras, so they restrict nothing. Use the functions above.

Tuborg

tuborg@function turns a drink into a Tuborg that gives endurance:

dilcopy tuborg@function("");

The argument isn't used; give it an empty string. Put it on a drink container (made with a LIQ_* macro, the liquid's name last in its names). When a player drinks from it, the whole container is emptied in one go: the player's thirst and fullness go up by 5 (to at most 24) and his endurance by 25 (to at most his maximum). A player whose thirst is above 20 is told "You are not thirsty."; sip and taste only give a message. After one drink the function ends, so a refilled container is an ordinary drink again.

Message board

Boards let players and administrators leave messages for each other. A board is an object with board@boards on it, from boards.zon:

dilbegin board(idxfile : string, l_res : string, r_res : string, p_res : string, bmax : integer);

The function makes the object an ITEM_BOARD itself. Players look at the board for the list of posts, and use read, write, reply and remove.

idxfile
The name the posts are saved under. Every board with the same name shows the same posts, so choose a name no other board uses, unless you want two boards to share their posts. The function also adds this name to the board's names.
l_res
Who may look at the board and read its posts: the name of a DIL function, or "" for everyone.
r_res
Who may remove other players' posts: a function, or "" for everyone. A player can always remove his own posts.
p_res
Who may post: a function, or "" for every player of level 10 or higher.
bmax
How many posts the board holds. When it is full, a player who tries to write is told "The board is full."

The three checks are DIL functions that get the player and the board and return a string: "" to allow, or the message to show when the player isn't allowed. boards.zon has two:

// only administrators (level 200 and up)
dilbegin string admin_res(u : unitptr, v : unitptr);

// administrators, and players who have the quest "Valhalla Editor"
dilbegin string rem_res(u : unitptr, v : unitptr);

Use admin_res to keep a board for administrators and rem_res to let only administrators clean a public board. A function of your own needs the same arguments and return type, and its name as "name@zone".

A board where anyone can read, post and remove, for 50 posts:

dilcopy board@boards("free", "", "", "", 50);

A board everyone can read and post on, where only administrators remove other people's posts:

dilcopy board@boards("citizen", "", "rem_res@boards", "", 100);

A board only administrators can use at all:

dilcopy board@boards("wizard", "admin_res@boards", "admin_res@boards",
                     "admin_res@boards", 100);

A complete board object is on More complex objects.

Blowaway

blowaway@function(seconds, message) makes an object disappear when it has been lying on the floor for a while. Every seconds seconds it looks where the object is; if it is lying in a room, the room sees the message and the object is destroyed. Carried, or inside a container, it is left alone until the next look. In the message, $1n is the object.

dilcopy blowaway@function(120, "$1n is eaten by a passing mouse.");
Previous: Compiling and Debugging your first object
Next: More complex objects