Difference between revisions of "Manual:DIL Manual"

From DikuMUD Wiki
Jump to navigation Jump to search
m (Adding getaffects)
 
(14 intermediate revisions by 3 users not shown)
Line 1: Line 1:
+
 
<H2>DIL DOCUMENTATION</H2>
+
 
'''Version 4.0'''
+
'''You can view a full listing of the DIL manual at [[Manual:DIL_Manual_(Full_Listing)]] or browse by topic using the links below.'''
+
 
'''Current Version by: Whistler@valhalla.com'''
+
<h3>Index</h3>
+
 
<h3>Index</h3>
+
[[Manual:DIL_Manual/Making a Program|Making a Program]]
[[#making|Making a Program]]
+
 
[[#types|Data Types]]
+
[[Manual:DIL_Manual/Data Types|Data Types]]
  [[#str|string]]
+
  [[Manual:DIL_Manual/string|string]]
  [[#strl|stringlist]]
+
  [[Manual:DIL_Manual/stringlist|stringlist]]
  [[#int|integer]]
+
  [[Manual:DIL_Manual/integer|integer]]
  [[#intlist|integerlist]]
+
  [[Manual:DIL_Manual/integerlist|integerlist]]
  [[#eptr|extraptr]]
+
  [[Manual:DIL_Manual/extraptr|extraptr]]
  [[#uptr|unitptr]]
+
  [[Manual:DIL_Manual/cmdptr|cmdptr]]
  [[#cptr|cmdptr]]
+
  [[Manual:DIL_Manual/unitptr|unitptr]]
  [[#zptr|zoneptr]]
+
  [[Manual:DIL_Manual/zoneptr|zoneptr]]
[[#messies|Messages]]
+
 
  [[#sfbcmd|SFB_CMD]]
+
[[Manual:DIL_Manual/Messages|Messages]]
  [[#sfbdone|SFB_DONE]]
+
  [[Manual:DIL_Manual/
  [[#sfbtick|SFB_TICK]]
 
  [[#sfbcom|SFB_COM]]
 
  [[#sfbdead|SFB_DEAD]]
 
  [[#sfbmsg|SFB_MSG]]
 
  [[#sfbpre|SFB_PRE]]
 
[[#built_in|Built-In Variables]]
 
  [[#cmdstr|cmdstr]]
 
  [[#excmdstr|excmdstr]]
 
  [[#excmdstr_case|excmdstr_case]]
 
  [[#self|self]]
 
  [[#activator|activator]]
 
  [[#targ|target]]
 
  [[#medium|medium]]
 
  [[#power|power]]
 
  [[#argu|argument]]
 
  [[#hb|heartbeat]]
 
  [[#null|null]]
 
  [[#weather|weather]]
 
  [[#mmmm|mud(day,month,..)]]
 
  [[#bvrealtime|realtime]]
 
[[#const|DIL Constructs]]
 
  [[#dcif|if()]]
 
  [[#dcgoto|goto]]
 
  [[#dcwhile|while()]]
 
  [[#dcbreak|break]]
 
  [[#dccont|continue]]
 
  [[#ongoto|on ... goto ...]]
 
  [[#forea|foreach()]]
 
[[#assgn|Assignment]]
 
[[#express|Expressions]]
 
[[#ops|Operators]]
 
  [[#ein|in]]
 
  [[#esins|string in string]]
 
  [[#esinsl|string in stringlist]]
 
  [[#esine|string in extraptr]]
 
[[#funcs|Functions]]
 
  [[#fquit|quit]]
 
  [[#fret|return]]
 
  [[#fret2|return()]]
 
[[#fields|Fields]]
 
  [[#extra|extraptr]]
 
  [[#unit|unitptr]]
 
  [[#uobj|UNIT_ST_OBJ]]
 
  [[#uroom|UNIT_ST_ROOM]]
 
  [[#upcnpc|UNIT_ST_PC and UNIT_ST_NPC]]
 
  [[#unpc|UNIT_ST_NPC]]
 
  [[#upc|UNIT_ST_PC]]
 
[[#built_func|Built-In Functions]]
 
  [[#bfasctime|asctime()]]
 
  [[#bfatoi|atoi()]]
 
  [[#bfcancarry|cancarry()]]
 
  [[#bfcheckpassword|check_password()]]
 
  [[#bfcomm|command()]]
 
  [[#bfdelstr|delstr()]]
 
  [[#bfdelunit|delunit()]]
 
  [[#bfdd|dildestroy()]]
 
  [[#bfdf|dilfind()]]
 
  [[#bfeq|equipment()]]
 
  [[#bffilesize|filesize()]]
 
  [[#bffindr|findroom()]]
 
  [[#bffindru|findrndunit()]]
 
  [[#bffinds|findsymbolic()]]
 
  [[#bffindu|findunit()]]
 
  [[#bffits|fits()]]
 
  [[#bfgcolor|getcolor()]]
 
  [[#bfgword|getword()]]
 
  [[#bfgwords|getwords()]]
 
  [[#bfghead|ghead()]]
 
  [[#bfisaff|isaff()]]
 
  [[#bfislight|islight()]]
 
  [[#bfisplayer|isplayer()]]
 
  [[#bfisset|isset()]]
 
  [[#bfitoa|itoa()]]
 
  [[#bfleft|left()]]
 
  [[#bflen|length()]]
 
  [[#bfload|load()]]
 
  [[#bfloadstr|loadstr()]]
 
  [[#bfmelee|meleeattack()]]
 
  [[#bfmeleedamage|meleedamage()]]
 
  [[#bfmid|mid()]]
 
  [[#bfmonstr|moneystring()]]
 
  [[#bfop|opponent()]]
 
  [[#bforoll|openroll()]]
 
  [[#bfpathto|pathto()]]
 
  [[#bfpaychk|paycheck()]]
 
  [[#bfpurse|purse()]]
 
  [[#bfreplace|replace()]]
 
  [[#bfrestore|restore()]]
 
  [[#bfright|right()]]
 
  [[#bfrnd|rnd()]]
 
  [[#bfsavestr|savestr()]]
 
  [[#bfsend_pre|send_pre()]]
 
  [[#bfskill_name|skill_name()]]
 
  [[#bfsplind|spellindex()]]
 
  [[#bfsplinf|spellinfo()]]
 
  [[#bfsplit|split()]]
 
  [[#bfstrdir|strdir()]]
 
  [[#bfstrcmp|strcmp()]]
 
  [[#bfstrncmp|strncmp()]]
 
  [[#bftextformat|textformat()]]
 
  [[#bftolower|tolower()]]
 
  [[#bftoupper|toupper()]]
 
  [[#bftranmon|transfermoney()]]
 
  [[#bfvis|visible()]]
 
  [[#bfweapon_name|weapon_name()]]
 
  [[#bfweapon_info|weapon_info()]]
 
[[#biproc|Built-In Procedures]]
 
  [[#bpacc_mod|acc_modify()]]
 
  [[#bpact|act()]]
 
  [[#bpaddaff|addaff()]]
 
  [[#bpaddcolor|addcolor()]]
 
  [[#bpaddeq|addequip()]]
 
  [[#bpaddex|addextra()]]
 
  [[#bpadds|addstring()]]
 
  [[#bpatt_s|attack_spell()]]
 
  [[#bpbeginedit|beginedit()]]
 
  [[#bpblock|block]]
 
  [[#bpcast_s|cast_spell()]]
 
  [[#bpchangecolor|changecolor()]]
 
  [[#bpchngs|change_speed()]]
 
  [[#bpclear|clear()]]
 
  [[#bpdc|dilcopy()]]
 
  [[#bpdelcolor|delcolor()]]
 
  [[#bpdp|delete_player()]]
 
  [[#bpdest|destroy()]]
 
  [[#bpexec|exec()]]
 
  [[#bpexp|experience()]]
 
  [[#bpflog|flog()]]
 
  [[#bpfol|follow()]]
 
  [[#bpgamestate|gamestate()]]
 
  [[#bpinsert|insert()]]
 
  [[#bpinterr|interrupt()]]
 
  [[#bpkilledit|killedit]]
 
  [[#bplink|link()]]
 
  [[#bplog|log()]]
 
  [[#bplogcrime|logcrime()]]
 
  [[#bpnopri|nopriority]]
 
  [[#bpona|on_activation()]]
 
  [[#bppagestring|pagestring()]]
 
  [[#bpp_u|position_update()]]
 
  [[#bppri|priority]]
 
  [[#bpreboot|reboot]]
 
  [[#bpremove|remove()]]
 
  [[#bpresetlevel|reset_level()]]
 
  [[#bpresetvlevel|reset_vlevel()]]
 
  [[#bpresetrace|reset_race()]]
 
  [[#bpsec|secure()]]
 
  [[#bpsend|send()]]
 
  [[#bpsendall|sendtoall()]]
 
  [[#bpsendalld|sendtoalldil()]]
 
  [[#bpsendt|sendtext()]]
 
  [[#bpsendto|sendto()]]
 
  [[#bpsend_done|send_done()]]
 
  [[#bpset|set()]]
 
  [[#bpsetbright|setbright()]]
 
  [[#bpsetfight|set_fighting()]]
 
  [[#bpsetweight|setweight()]]
 
  [[#bpsetpassword|set_password()]]
 
  [[#bpstore|store()]]
 
  [[#bpstopfighting|stop_fighting()]]
 
  [[#bpsubaff|subaff()]]
 
  [[#bpsubex|subextra()]]
 
  [[#bpsubs|substring()]]
 
  [[#bpuneq|unequip()]]
 
  [[#bfunitdir|unitdir()]]
 
  [[#bpunsec|unsecure()]]
 
  [[#bpunset|unset()]]
 
  [[#bpwait|wait()]]
 
  [[#bpwalkto|walkto()]]
 
[[#note|Ending Notes]]
 
 
---~---~---~---~---~---~---~---~---
 
<center>
 
  This documentation is designed for people with some experience in programming.
 
Experience in C is recommended, but PASCAL or BASIC in some form or other
 
will do just fine too.
 
 
  DIL is a simple programming language with fixed types reflecting the types
 
used in Valhalla Mud. The language gives you almost endless possibilities in
 
designing your adventures and quests. It gives you the control you need for
 
making the game interesting and intelligent.
 
</center>
 
<!--LINK--><span id="making" />
 
 
<h3>'''Making a program:'''</h3>
 
 
  You define your DIL programs within your zone file. Each program you make is a
 
*template*. Such a template must be equipped with a unique name (for that zone).
 
Templates can either be defined in a new %dil section, just below the %zone
 
section in the zone file, or directly attached to units defined in your zonefile.
 
 
  If you define your DIL templates inside a unit definition, that unit is
 
automatically assigned a program using that template. If you want to use an
 
already designed template, either in your own, or another zone, you use a
 
special function named "dilcopy", that takes the name of a template, and any
 
optional parameters in parenthesis. The parameters of a template called with
 
'dilcopy' may only be of types integer, strings and stringlists.
 
 
'''Example:'''
 
 
dilcopy myfunc@myzone("say Hello, my friend!", 1, CMD_SAY, {"name1", "name2"});
 
 
  DIL templates can always be reused. In fact, with version 2.0 of DIL, programs
 
are no longer saved with equipment, but only a symbolic reference is used. That
 
way, if you make a change in your zone, ALL units using that program are changed.
 
This however requires you keep the name. Upon loading, if a template is not
 
found, the program is halted and rendered useless until such a reference can be
 
found during loading.
 
 
Technical note:
 
 
  When you use several 'dilcopy' in your zonefile, only one instance is present
 
game-time, thus saving tremendous amounts of memory.  It is similar to a shared
 
library, in which code is shared  but variables are not.
 
 
You may use your templates to define both procedure and functions for your other
 
templates to call.
 
 
A template is defined by beginning with 'dilbegin' and ending with 'dilend'.
 
Inside the template your program section is defined, marked by the keyword 'code',
 
followed by the program itself;
 
 
<nowiki>
 
 
dilbegin myprogram();
 
var
 
  i : integer;
 
  j : integer;
 
 
code
 
{
 
  heartbeat:=PULSE_SEC*5;
 
  :start:
 
  exec("say Hello world", self);
 
  pause;
 
  goto start;
 
}
 
dilend</nowiki>
 
 
  This simple template does nothing but making its owner say 'Hello world' once
 
every 5 seconds. The template is called 'myprogram' and takes no arguments. The
 
'pause' command waits for the program to receive a timer message, whose interval
 
is set by the 'inline' variable 'heartbeat'. The 'self' variable is a unitptr
 
referring to the unit owning the DIL program. Other inline variables will be
 
explained later.
 
 
  For a DIL program to work, it must be part of a *unit*: a room, player, non-player
 
or object. The program uses *messages* to operate.  Your program gets activated
 
when it receives a message that some command is being executed, or a certain amount
 
of time has passed. You decide yourself in the program, what to wait for, before
 
the program continues executing.
 
 
  Supposing you want your program to contain variables, you have to put them in a
 
section before the 'code' section marked 'var'. The variables are declared by
 
their type and their name, separated by a ':' and ended by a ';'
 
 
  For an example, see the program above. Variables of type 'string', 'stringlist'
 
and 'integer' are saved, if the unit the program is attached to is saved with
 
player inventory. Variables of type 'unitpr' and 'extraptr' are 'volatile'. This
 
means that they are cleared whenever there is a chance that their contents may
 
have been rendered non usable.  This ensures that you do not have any 'loose'
 
pointers. However it is possible to 'secure' the contents of a 'unitptr' type
 
variable of a unit located in your local environment (the units directly 'visible'
 
to the unit who owns the DIL program) (see the secure / unsecure functions).
 
 
<!--LINK--><span id="types" />
 
<h3>'''Data Types:'''</h3>
 
 
DIL supports a fixed set of types you can use and manipulate. Through these, you
 
can get and manipulate information about almost anything in the game. The types
 
are listed below:
 
 
---~---~---~---~---~---~---~---~---
 
<!--LINK--><span id="str" />
 
'''String:'''
 
 
    A string is some text. They are used for a lot of things such as command
 
arguments, room descriptions etc. String variables are automatically resized and
 
allocated when you assign them, so you do not have to worry about the string
 
length nor allocation in your DIL programs. Strings may be compared either with
 
'==' (equal to),
 
'!=' (not equal),
 
'<=' (less than or equal to),
 
'>=' (greater than or equal to)
 
'<' (less than),
 
  '>' (greater than.
 
 
  Static strings are defined just as in the rest of the zone, within double
 
quotations.  Strings may be searched easily with the 'in' operator.  Variables
 
of type string are saved with DIL programs, if attached to a saved unit.
 
 
'''Example:'''
 
 
  "This is a static string"
 
 
Strings may also be added to each other, in an expression.
 
 
'''Example:'''
 
 
  "say "+itoa(42)+" is the answer!"
 
 
'''Example:'''
 
 
  if (self.name == self.names.[1]) ...
 
 
  Elements of the string can also be accessed by referencing them by their position.
 
 
  '''Example'''
 
  if (str.[3]==f])
 
  {
 
  exec ("say The 4th element is a F.",self);
 
  }
 
 
  '''Note'''
 
  Currently you can only access the single elements of a string you can not set
 
them.  In the future this will be possible.  You can still accomplish this by
 
copying one string to the other one element at a time and changing any that you
 
want something like this.
 
 
'''Example'''
 
i:=0;
 
ln:=length (str);
 
while (str.[i]<ln)
 
{
 
if (str.[i]=="f")
 
newstr.[i]:="b";
 
else
 
newstr:=str.[i];
 
i:=i+1;
 
}
 
str:=newstr;
 
 
  This snip of Dil would replace any 'f' in a string with a 'b' remember dil is
 
not case sensitive so it will also replace an 'F'.
 
 
---~---~---~---~---~---~---~---~---
 
<!--LINK--><span id="strl" />
 
'''Stringlist:'''
 
 
  A stringlist is a list of separate strings. This is used for things such as
 
(multiple) names or keywords. You may request a specified word in a stringlist
 
by its number.
 
'''Example:'''
 
 
  mystring := self.names.[2];
 
 
  Returning null if out of bounds of the stringlist (see 'length()'). Static
 
stringlists are defined just as in the rest of the zonefile, as a comma separated
 
list of static strings within curly brackets.
 
 
'''Example:'''
 
 
  mysrtringlist := {"Some string","another string","the last string"}
 
 
  Stringlists are modified through the 'addstring()' and 'substring()' procedures.
 
Stringlists are searched easily by the 'in' operator. See documentation below.
 
They can also be set directly (see example above).  Variables of type string are
 
saved with DIL programs, if attached to a saved unit.
 
 
  Elements of each separate string in a stringlist can be accessed by appending
 
a separate position at the end of the request for a string as follows:
 
 
'''Example'''
 
if (strlist.[5].[3]=="b"){
 
do something
 
}
 
 
'''Note'''
 
  See the strings for more information on accessing a single element.
 
 
---~---~---~---~---~---~---~---~---
 
<!--LINK--><span id="int" />
 
'''Integer:'''
 
 
  Non-fraction numbers can be used throughout your DIL programs.  They are given
 
normally, or in normal C style hexadecimal, preceded with '0x'. Integers are
 
signed 32-bit integers.  Variables of type string are saved with DIL programs,
 
if attached to a saved unit.
 
 
'''Example:'''
 
 
  0x10
 
 
'''Example:'''
 
 
  2
 
 
  Integers are used within expressions as both number value and boolean(true/false)
 
values. You may use comparison between integers through the comparison operators:
 
'==' (equality),
 
'<' (less than),
 
'>' (greater than),
 
'<=' (less or equal),
 
'>=' (greater or equal)
 
'!=' (not equal).
 
 
 
'''Example:'''
 
 
  if (42<12) ...
 
 
  Returning the boolean value (true/false) depending on the comparison between
 
integers. The result may be stored in an integer variable, and tested later, or
 
used directly in an 'if' or 'while', etc.  You may also operate on boolean
 
expression themselves, using LOGICAL operators 'and','not','or', which allows
 
you to combine the expressions.
 
 
'''Example:'''
 
 
  if ( not ( (self.hp<42) or (self.level>10) ) ) ..
 
 
Integer expressions may also use a number of other operators:
 
'+' (addition)
 
'-' (subtraction/negation),
 
'*' (multiplication),
 
'/' (division),
 
'|' (bitwise or, for flags),
 
'&' (bitwise and, for flags)
 
 
Precedence rules for using these operators are still somewhat messed up.  You'd
 
better use parenthesis where ever possible.
 
 
---~---~---~---~---~---~---~---~---
 
<!--LINK--><span id="intlist" />
 
'''Intlist:'''
 
 
  Intlists are an array of integer types.  They can be set directly as follows:
 
 
'''Example'''
 
 
wpn:={5,3,6,9,3,9};
 
 
The intlists can be accessed in the same way stringlist are accessed as follows.
 
 
'''Example'''
 
 
if (wpn.[5]==5)
 
{
 
do something
 
}
 
 
The intlists are saved on savable units.
 
 
'''Type:  '''<i><!--CODE-->intlist</i><!--ENDCODE-->
 
 
  This variable type allows you to keep an ordered list of integers with out
 
having to create a variable for each integer.
 
'''Example:'''  <i><!--CODE-->Setting an intlist</i><!--ENDCODE-->
 
<i>
 

Latest revision as of 22:07, 6 March 2022


You can view a full listing of the DIL manual at Manual:DIL_Manual_(Full_Listing) or browse by topic using the links below.

Index

Making a Program

Data Types

 string
 stringlist
 integer
 integerlist
 extraptr
 cmdptr
 unitptr
 zoneptr

Messages

 SFB_CMD
 SFB_DONE
 SFB_TICK
 SFB_COM
 SFB_DEAD
 SFB_MSG
 SFB_PRE

Built-In Variables

 cmdstr
 excmdstr
 excmdstr_case
 self
 activator
 target
 medium
 power
 argument
 heartbeat
 null
 weather
 realtime
 mud(day,month,..)

DIL Constructs

 if()
 goto
 while()
 break
 continue
 on ... goto ...
 foreach()

Assignment

Expressions

Operators

 in
 string in string
 string in stringlist
 string in extraptr

Functions

 quit
 return
 return()

Fields

 extraptr
 unitptr
 UNIT_ST_OBJ
 UNIT_ST_ROOM
 UNIT_ST_PC and UNIT_ST_NPC
 UNIT_ST_NPC
 UNIT_ST_PC

Built-In Functions

 asctime()
 strcmp()
 strncmp()
 textformat()
 spellindex()
 spellinfo()
 beginedit()
 cancarry()
 fits()
 replace()
 restore()
 meleeattack()
 meleedamage()
 mid()
 moneystring()
 equipment()
 tolower()
 toupper()
 visible()
 opponent()
 purse()
 atoi()
 check_password()
 command()
 delstr()
 delunit()
 dildestroy()
 dilfind()
 itoa()
 isaff()
 islight()
 isplayer()
 isset()
 paycheck()
 filesize()
 findunit()
 findrndunit()
 findroom()
 findsymbolic()
 getword()
 getwords()
 ghead()
 split()
 left()
 length()
 load()
 loadstr()
 openroll()
 pathto()
 pagestring()
 right()
 rnd()
 Built-In Procedures
 follow()
 flog()
 logcrime()
 acc_modify()
 strdir()
 set_password()
 store()
 position_update()
 send_done()
 send_pre()
 set()
 unset()
 addcolor()
 delcolor()
 getcolor()
 changecolor()
 gamestate()
 addextra()
 addstring()
 subextra()
 substring()
 stop_fighting()
 subaff()
 addaff()
 destroy()
 walkto()
 link()
 weapon_name()
 weapon_info()
 skill_name()
 reboot
 killedit
 experience()
 act()
 exec()
 wait()
 savestr()
 remove()
 reset_level()
 reset_vlevel()
 reset_race()
 secure()
 unitdir()
 unsecure()
 block
 priority
 nopriority
 addequip()
 unequip()
 delete_player()
 dilcopy()
 sendtext()
 change_speed()
 transfermoney()
 set_fighting()
 set_weight_base()
 set_weight()
 setbright()
 log()
 send()
 sendto()
 sendtoall()
 sendtoalldil()
 cast_spell()
 attack_spell()
 insert()
 interrupt()
 clear()
 on_activation()
 shell()
 getaffects()

Ending Notes