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

=== DIL functions for objects ===

	The DIL language is the language a builder can use to make his own
	special functions on rooms, NPCs, objects, PCs, and much more.  This
	manual is for basic zone writing and therefore will not go into how to
	write your own DIL functions.  The VME however is released with many
	functions for you as an Administrator and your builders to use to make
	special rooms, NPCs, and objects.  The following sections contain a full list of all object
	functions released with the VME 2.0 server.
==== Restriction functions ====

	The desire to have different equipment comes from every players
	desire to be different.  The restrict functions were designed to help
	make this a reality by only allowing certain groups of players to wear
	some items.  The restrict functions can be used alone or together to
	make a greater restricted item.  for example you could make an item,
	restricted to only females or you could make an item, restricted to females that had a strength greater than 20 and who have
	done a certain quest.

	All restrict functions have a name that describes what the
	restriction function is for and four other arguments.  the 2nd, 3rd, and
	4th argument is the exact same for all restrict functions only the name
	of the restrict and the first argument changes.  The format for the
	restrict functions is as follows.
 <nowiki>
	dilcopy &lt;function name&gt; (arg 1, &lt;max damage&gt;,
	    &lt;percentage&gt;,&lt;Optional DIL&gt;);</nowiki>
We will skip the function name and the first argument and get back
	to them later.

;max damage and percentage
: The second and third arguments set the damage done when the wrong player wears an object. The reason we are explaining them together is they can work together or separately depending on how you set them.
	The second argument is the max damage the third argument is the
	percentage damage.

	When both arguments are set to 0 no damage will be
	done when the item is illegally worn.  When the second argument is set
	to a number like 100 and the third argument is set to 0, exactly 100
	damage will be done to the player no matter how many hit points he/she
	has.  So by setting the second argument to a number and setting the
	third to 0 you could possibly kill your victim since it will remove the
	amount specified no matter how much the player has.

	 If you do not want
	to possibly kill your victim the Third argument should be used.  If you
	set the second argument to 0 and the third argument to a number it will
	do a percent of damage to the player. for example if The third argument
	was set to 25 it would do 25 % damage to a player.

	  You can also use the second and third argument together if you want to set a max amount of
	damage without possibly killing them.  for example if you set the second
	argument to 100 and third to 25.  The item will do 25% damage up to 100
	hit points of damage. This all might be a bit confusing so let me show
	you a few examples and tell you what they would do.

;second= 0 third = 25
: This would do 25% damage to a player. second =100 third = 0 this would do 100 damage to a player no matter his amount of hit points.
;second = 25 third = 25
: This would do 25 % damage to a player up to 25 hit points.
	So if a player had 150 hit points the max that could be removed is 25
	hit points.

;optional DIL
: All restrict DIL functions have a default set of acts.  If you want to make your own set of acts you have to create your own DIL that does nothing more than act.  If you don't understand how this works.  You may want to look in the DIL manual about passing DIL functions as arguments.

Now we should get back to the first argument and function name
	since they are what control the restricts.  The function name has been
	chosen so you can easily tell what the restrict was created for
	while the first argument changes depending on which restrict you use.
	The following are what each function restricts name is and what the function
	name and first argument are.

; Guild Restrict
*
This function restricts an object to players in a certain
	guild or guilds.  Anyone not in the guild or guilds, will have the damage done as set in the
	2nd and 3rd arguments unless none is set.  Even if no damage is set the
	object will be removed off of the players equipment and placed in their
	inventory.  The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin guild_restrict
	(guilds:stringlist,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is a stringlist.  This
	means you can restrict this item to more than one guild.  All guilds in
	the string list will be able to wear this object.  If we wanted to make
	an item that only Paladins and sorcerers could wear it would look like
	this.
 <nowiki>
	dilcopy guild_restrict@function ({"Midgaard Paladin",
	                         "Midgaard Sorcerer"},0,25,"");</nowiki>
;Anti-guild Restrict
: This function restricts an object to players not in a certain guild or guilds.  Anyone not in the guild or guilds listed, will have the damage done as set in the 2nd and 3rd arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.  The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin anti_guild_restrict
	(guilds:stringlist,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is a stringlist.  This
	means you can restrict this item from more than one guild.  All guilds in
	the string list will not be able to wear this object.  If we wanted to make
	an item that only Paladins and sorcerers could not wear it would look like
	this.
 <nowiki>
	dilcopy anti_guild_restrict@function ({"Midgaard Paladin",
	                              "Midgaard Sorcerer"},0,25,"");</nowiki>
;Quest Restrict
: This function restricts an object to players who have done a certain quest.  Any  player who has not done the quest,
	will have the damage done as set in the 2nd and 3rd arguments unless
	none is set.  Even if no damage is set the object will be removed off of
	the players equipment and placed in their inventory.  The following is
	the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin quest_restrict
	(qst:string,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is a string.  The
	quest restrict is only made to restrict the by one quest at a time.  If
	you want the item to have multiple quests restrictions you just add
	another dilcopy to it.  The following Would be an object
	restricted to one quest.
 <nowiki>
	dilcopy quest_restrict@function ("Eagles quest complete",0,25,"");</nowiki>
;Quests Restrict
: This function restricts an object to players who have a certain quest or quests.  Anyone not having all quests in the list of quests, will have the damage done as set in the 2nd and 3rd arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.  The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin quests_restrict
	(qsts:stringlist,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is a stringlist.  This
	means you can restrict this item to more than one quest.  Players that
	have not done every quest will not be able to use the object.
	If we wanted to make an item that only players that have finished both
	the 'Eagles quest complete' and the 'Feather fall quest complete' could
	wear.  It would look like this.
 <nowiki>
	dilcopy quests_restrict@function ({"Eagles quest complete",
	                          "Feather fall quest complete"},0,25,"");</nowiki>
;Alignment Restrict
: This function restricts an object to players with a certain alignment range.
	Anyone not in the alignment range,
	will have the damage done as set in the 3nd and 4th arguments unless
	none is set.  Even if no damage is set the object will be removed off of
	the players equipment and placed in their inventory.

	We said at the beginning of this section that all restricts have
	only 4 arguments.  This was a bit of a lie since this restrict has five
	arguments.  The reason we didn't count this one is because the first and
	second argument in the alignment restrict function are used together and
	thus are only really one argument. The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin ali_restrict
	(max:integer,min:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first and second arguments are two
	integers.  the first is the max alignment that can wear or use this
	object and the second is the minimum alignment.  So if we wanted to
	restrict an item to only good players it would look like this.
 <nowiki>
	dilcopy ali_restrict@function (1000,350,0,25,"");</nowiki>
;Level restrict
: This function restricts an object to players above or equal to a certain level.  Any player not at least the level or higher, will have the damage done as set in the 2nd and 3rd arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.  This restrict works in the old level system from one to fifty which means if the level restrict is set higher than fifty no player will be able to wear or use this object.  This is good if you have objects that only your administrators should be able to use.  If you want to restrict an object to greater than level fifty for players you need to use the 'vlevel' restrict.  The following is the definition of the DIL as found in ''function.zon''.
 <nowiki>
	dilbegin level_restrict
	(lvl:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is an integer.  The
	integer for the level restrict can range from 1 to 255.  Thus if we
	wanted to make an object that only administrator could wear or use it would
	look like this
 <nowiki>
	dilcopy level_restrict@function (51, 0,25,"");</nowiki>
;Virtual Level Restrict
: This function restricts an object to players above or equal to a certain level.  Any player not at least the level or higher, will have the damage done as set in the 2nd and 3rd arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.  This restrict works in the new level system from one to infinity.
	The following is the definition of the DIL as found in ''function.zon''.
 <nowiki>
	dilbegin vlevel_restrict
	(lvl:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is an integer.  The
	integer for the level restrict can range from 1 to infinite.  Thus if we
	wanted to make an object that only players that have reached the level
	of 5000 could wear or use, it would look like this.
 <nowiki>
	dilcopy vlevel_restrict@function (5000, 0,25,"");</nowiki>
;Race restrict
: This function restricts an object from players of a certain race. Any player not of the selected race, will have the damage done as set in the 2nd and 3rd arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.  The following is the definition of the DIL as found in ''function.zon''.
 <nowiki>
	dilbegin race_restrict
	(rc:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is an integer.  The
	integer being passed in should be the race you want to restrict the
	object from.  You can pass in the defines as listed in (Link to app-c) or if you have added races you will find the list of
	races in ''values.h''.  If we wanted to restrict an
	object from humans the following is what it would look like.
 <nowiki>
	dilcopy race_restrict@function (RACE_HUMAN,0,25,"");</nowiki>
;Gender restrict
: This function restricts an object to players of a certain gender.  Anyone not of the gender, will have the damage done as set in the 2nd and 3rd arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.  The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin sex_restrict
	(sx:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is an integer.  The
	integer you should pass in is one of the defines from
	''vme.h''.  The gender defines are as follows.
 <nowiki>
	#define SEX_NEUTRAL   0
	#define SEX_MALE      1
	#define SEX_FEMALE    2</nowiki>
If we wanted to make an item that could only be worn by a female
	player, it would look like this.
 <nowiki>
	dilcopy sex_restrict (SEX_FEMALE,0,25,"");</nowiki>
;Player restrict
: This function restricts an object to players who have a specific name. Any player of the wrong name, will have the damage done as set in the 2nd and 3rd arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.  The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin ply_restrict
	(pname:string,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first argument is a string.  The
	quest restrict is only made to restrict the quest to one person at a
	time.  While this DIL was designed to be put on when a player receives a
	quest item and thus was made to be dilcopied in a DIL you can still put
	it on when you first create the object if you are making special items
	for administrators or players that you know in advance.  If you want more
	information about copying a DIL from with in another DIL you will have
	to read the DIL manual If however you want to restrict this to a single
	player at compile time of your zone it would look something like
	this.
 <nowiki>
	dilcopy ply_restrict@function ("Whistler",0,25,"");</nowiki>
;Ability restrict
: This function restricts an object from a player with less than a certain amount of a certain ability. Any player not having the correct amount of a certain ability, will have the damage done as set in the 3nd and 4th arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.

	We said at the beginning of this section that all restricts have
	only 4 arguments.  This was a bit of a lie since this restrict has five
	arguments.  The reason we didn't count this one is because the first and
	second argument in the ability restrict function are used together and
	thus are only really one argument. The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin abi_restrict
	(abi:integer,min_abi:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first and second arguments are two
	integers.  the first is the ability type and the second is the amount of
	that ability the player needs to have or greater to wear or use the
	item.  the ability types can be found in ''vme.h'' and
	are listed here for convenience.
 <nowiki>
	#define ABIL_MAG               0
	#define ABIL_DIV               1
	#define ABIL_STR               2
	#define ABIL_DEX               3
	#define ABIL_CON               4
	#define ABIL_CHA               5
	#define ABIL_BRA               6
	#define ABIL_HP                7</nowiki>
If you wanted to restrict an object to people having more than 50%
	strength it would look like this:
 <nowiki>
	dilcopy abi_restrict@function (ABIL_STR,50,0,25,"");</nowiki>
If you want to restrict an object to more than one ability you
	only need to add another restrict to the item.  For example if you
	wanted to restrict it to people having greater than or equal to 50%
	divine and 30% brain.  The item would have these two lines.
 <nowiki>
	dilcopy abi_restrict@function (ABIL_DIV,50,0,25,"");
	dilcopy abi_restrict@function (ABIL_BRA,30,0,25,"");</nowiki>
;Skill restrict
: This function restricts an object from a player with less than a certain amount of a certain skill. Any player not having the correct amount of a certain skill, will have the damage done as set in the 3nd and 4th arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.

	We said at the beginning of this section that all restricts have
	only 4 arguments.  This was a bit of a lie since this restrict has five
	arguments.  The reason we didn't count this one is because the first and
	second argument in the skill restrict function are used together and
	thus are only really one argument. The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin ski_restrict
	(ski:integer,min_ski:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first and second arguments are two
	integers.  the first is the skill and the second is the amount of
	that skill the player needs to have or greater to wear or use the
	item.  the skills can be found in (Link to app-g) and
	''values.h''. We have also included the first five skills
	here for convenience in explaining how the function works.
 <nowiki>
	#define SKI_TURN_UNDEAD        0
	#define SKI_SCROLL_USE         1
	#define SKI_WAND_USE           2
	#define SKI_CONSIDER           3
	#define SKI_DIAGNOSTICS        4</nowiki>
If you wanted to restrict an object to people having more than 50%
	'turn undead' it would look like this:
 <nowiki>
	dilcopy ski_restrict@function (ASKI_TURN_UNDEAD,50,0,25,"");</nowiki>
If you want to restrict an object to more than one skill you
	only need to add another restrict to the item.  For example if you
	wanted to restrict it to people having greater than or equal to 50%
	 in 'turn undead' and 30% in 'scroll use'.  The item would have these two lines.
 <nowiki>
	dilcopy ski_restrict@function (SKI_TURN_UNDEAD,50,0,25,"");
	dilcopy ski_restrict@function (SKI_SCROLL_USE,30,0,25,"");</nowiki>
;Spell restrict
: This function restricts an object from a player with less than a certain amount of a certain spell. Any player not having the correct amount of a certain spell, will have the damage done as set in the 3nd and 4th arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.

	We said at the beginning of this section that all restricts have
	only 4 arguments.  This was a bit of a lie since this restrict has five
	arguments.  The reason we didn't count this one is because the first and
	second argument in the spell restrict function are used together and
	thus are only really one argument. The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin sp_restrict
	(spl:integer,min_sp:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first and second arguments are two
	integers.  the first is the spell and the second is the amount of
	that spell the player needs to have or greater to wear or use the
	item.  the spells can be found in (Link to app-h) and
	''values.h''. We have also included the first five
	spells here for convenience in explaining how the function works.
 <nowiki>
	#define SPL_LOCK              52
	#define SPL_UNLOCK            53
	#define SPL_DROWSE            54
	#define SPL_SLOW              55
	#define SPL_DUST_DEVIL        56</nowiki>
If you wanted to restrict an object to people having more than 50%
	'lock' spell, it would look like this:
 <nowiki>
	dilcopy sp_restrict@function (ASPL_LOCK,50,0,25,"");</nowiki>
If you want to restrict an object to more than one spell you
	only need to add another restrict to the item.  For example if you
	wanted to restrict it to people having greater than or equal to 50%
	 in 'lock' and 30% in 'unlock' spells.  The item would have these two lines.
 <nowiki>
	dilcopy sp_restrict@function (SPL_LOCK,50,0,25,"");
	dilcopy SPL_restrict@function (SPL_LOCK,30,0,25,"");</nowiki>
;Weapon restrict
: This function restricts an object from a player with less than a certain amount of a certain weapon. Any player not having the correct amount of a certain weapon, will have the damage done as set in the 3nd and 4th arguments unless none is set.  Even if no damage is set the object will be removed off of the players equipment and placed in their inventory.

	We said at the beginning of this section that all restricts have
	only 4 arguments.  This was a bit of a lie since this restrict has five
	arguments.  The reason we didn't count this one is because the first and
	second argument in the weapon restrict function are used together and
	thus are only really one argument. The following is the definition of the DIL as found in
	''function.zon''.
 <nowiki>
	dilbegin weap_restrict
	(wpn:integer,min_wpn:integer,damage:integer,percent:integer,action:string);</nowiki>
As the definition indicates the first and second arguments are two
	integers.  the first is the weapon and the second is the amount of
	that weapon the player needs to have or greater to wear or use the
	item.  the weapons can be found in (Link to app-d) and
	''values.h''. We have also included the first five
	weapons here for convenience in explaining how the function works.
 <nowiki>
	#define WPN_BATTLE_AXE    7  /* Two Handed */
	#define WPN_HAND_AXE      8
	#define WPN_WAR_MATTOCK   9  /* Two Handed */
	#define WPN_WAR_HAMMER   10
	#define WPN_GREAT_SWORD  11  /* Two Handed */</nowiki>
If you wanted to restrict an object to people having more than 50%
	'battle axe', it would look like this:
 <nowiki>
	dilcopy weap_restrict@function (WPN_BATTLE_AXE,50,0,25,"");</nowiki>
If you want to restrict an object to more than one weapon you
	only need to add another restrict to the item.  For example if you
	wanted to restrict it to people having greater than or equal to 50%
	 in 'hand axe' and 30% in 'battle axe' spells.  The item would have these two lines.
 <nowiki>
	dilcopy weap_restrict@function (WPN_HAND_AXE,50,0,25,"");
	dilcopy weap_restrict@function (WPN_BATTLE_AXE,30,0,25,"");</nowiki>
==== Tuborg function ====

	What game would be complete with out the Denmark water!  With that
	in mind the VME 2.0 has a tuborg function that makes a drink give
	endurance and health when drank.  The function is defined in
	''function.zon'' as follows:
 <nowiki>
	dilbegin tuborg (s:string);</nowiki>
As the definition indicates the tuborg function only has one
	argument.  The real surprise is that the argument is not used yet in the
	DIL so no matter what you set it to it doesn't matter.  In the future
	this argument is going to allow different kinds of tuborgs to be made
	but for now its just a place holder and all that is needed is a set of
	double quotes.

	To create a tuborg you just add the following line to your drink
	container.
 <nowiki>
	dilcopy tuborg@function ("");</nowiki>
==== Message board ====

	Every game needs a way for Administrators and players to exchange
	ideas.  The message boards have been designed for this purpose.  The
	boards function can be easy to use or more difficult depending on what
	all you want them to do.  The board function is defined in
	''boards.zon'' as follows.
 <nowiki>
	dilbegin board
	(idxfile:string,l_res:string,r_res:string,p_res:string,bmax:integer);</nowiki>
This looks pretty hard I know but to make a normal board we have
	made it as simple as possible while allowing for the boards to be used
	in almost any situation.  After you make your first board it is pretty
	much block and copy and change the first argument.  The arguments are as
	follows:

;idxfile
: The first argument is the board index filename.  It tells the board DIL what name to store the board under so if you create more boards with the same name they will all be pointing to the same messages.  You can put any legal symbolic name in this string and it will work with no problems.
;l_res
: the second argument is a DIL you pass in that does any checks to see if the player looking at the board is allowed to.  This requires some knowledge in DIL but we have given some example DIL functions in the
	''boards.zon''.
 <nowiki>
	//used to restrict players access to a board
	dilbegin string admin_res (u:unitptr,v:unitptr);

	//used to restrict non-admin from removing posts
	dilbegin string rem_res (u:unitptr, v:unitptr);</nowiki>
So with the 'admin_res' you could do something like
	this:
 <nowiki>
	dilcopy board@boards ("wizbrd","admin_res@boards"...);</nowiki>
Putting the 'admin_res' function in the second argument would make
	it so only administrators could look at the board.  If you put an empty
	string or two double quotes as the argument it will let anyone look at
	the board.
;r_res
: the third argument is a DIL you pass in that does any checks to see if the player trying to remove a post at the board is allowed to.  This requires some knowledge in DIL but we have given some example DIL functions in the
	''boards.zon''
 <nowiki>
	//used to restrict players access to a board
	dilbegin string admin_res (u:unitptr,v:unitptr);

	//used to restrict non-admin from removing posts
	dilbegin string rem_res (u:unitptr, v:unitptr);</nowiki>
So with the 'rem_res' you could do something like
	this:
 <nowiki>
	dilcopy board@boards ("citizen","","rem_res@boards",...);</nowiki>
With the 'rem_res' in the third argument only administrators can
	now remove from this board but anyone can look at it because of the empty
	string in the second argument.  Putting an empty string in the third
	argument will make it so anyone can remove from this board.
;p_res
: the forth argument is a DIL you pass in that does any checks to see if the player trying to post at the board is allowed to.  This requires some knowledge in DIL but we have given some example DIL functions in the
	''boards.zon''.
 <nowiki>
	//used to restrict players access to a board
	dilbegin string admin_res (u:unitptr,v:unitptr);

	//used to restrict non-admin from removing posts
	dilbegin string rem_res (u:unitptr, v:unitptr);</nowiki>
As you can see we haven't made a post restriction DIL because as of
	yet we haven't found a need for one.  If you have a need for one just
	look over the two restrict DIL functions we have already mentioned and you will
	find it is really easy to make.  We want to allow anyone to post so our
	dilcopy looks like this:
 <nowiki>
	dilcopy board@boards ("citizen","","rem_res@boards","",...);</nowiki>
With the 'rem_res' in the third argument only administrators can
	now remove from this board but anyone can post to it because of the empty
	string in the forth argument.  The empty string again in the second
	argument also allows everyone to look at the board.
;max
: The fifth argument is simply the amount of posts that you want to allow to be posted before the board is full.

To make a free for all board where everyone can post, remove
	posts, look at what posts are on the board, and have a max of 50 posts it would simply be as
	follows:
 <nowiki>
	dilcopy board@boards("citizen","","","",50);</nowiki>
When making a board for players to post concerns to the
	administrators and only have the administrators be able to remove them,
	wile still allowing everyone to read them it would look like
	this.
 <nowiki>
	dilcopy board@boards("citizen","","rem_res@boards","",100);</nowiki>

<div style='padding-top: 30px; padding-bottom: 20px; text-align: left;float:left;width:50%;'>[[Manual:Zone_Manual/The_Objects_Section/Compiling_and_Debugging_your_first_object|Previous: Compiling and Debugging your first object]]</div>
<div style='padding-top: 30px; padding-bottom: 20px; text-align: right;float:right;width:50%;'>[[Manual:Zone_Manual/The_Objects_Section/More_complex_objects|Next: More complex objects]]</div>