Manual:Zone Manual/The Objects Section/DIL functions for objects
Contents
- 1 DIL functions for objects
- 1.1 Restriction functions
- 1.1.1 guild_restrict and anti_guild
- 1.1.2 prof_restrict
- 1.1.3 quest_restrict, nquest_restrict and quests_restrict
- 1.1.4 ali_restrict
- 1.1.5 level_restrict, vlevel_restrict and mvlev_restrict
- 1.1.6 race_restrict
- 1.1.7 sex_restrict
- 1.1.8 ply_restrict
- 1.1.9 abi_restrict, ski_restrict, sp_restrict and weap_restrict
- 1.1.10 The *_RESTRICT macros
- 1.2 Tuborg
- 1.3 Message board
- 1.4 Blowaway
- 1.1 Restriction functions
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_restrictandanti_guildnever 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:
percentpercent of his current hit points, at mostdamagepoints; withpercent0, exactlydamagepoints; -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 write0, 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, soselfis the item andself.outsidethe 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:
| 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.");