Difference between revisions of "Manual:Zone Manual/The Room Section/DIL functions for rooms"

From DikuMUD Wiki
Jump to navigation Jump to search
(checked against the current code (wiki review 2026-11-15))
Line 1: Line 1:
 +
=== DIL functions for rooms ===
 +
 +
DIL is the language for giving rooms, NPCs and objects behaviour of their own. This manual is about building zones, so it doesn't teach you to write DIL; the [[Manual:DIL Manual|DIL manual]] does. The zones that come with the server contain many DIL templates you can use without writing any DIL yourself. This page lists the ones made for rooms.
 +
 +
You put a template on a room with <code>dilcopy</code>, the template's name, the zone it is in, and its arguments:
 +
<pre>
 +
dilcopy death_room@function(PULSE_SEC * 15, 60, "Flames shoot up from the floor.");
 +
</pre>
 +
The <code>;</code> at the end is required. vmc checks neither the name nor the arguments: a wrong name or a missing argument compiles without a word and shows up only at boot or when the script runs, in <code>vme.log</code>. Check them against the template's <code>dilbegin</code> line in its zone file (in <code>vme/zone/</code>).
 +
 +
Times are given in ticks of a quarter of a second. <code>PULSE_SEC</code> (4) from <code>vme.h</code> makes them easier to read: <code>PULSE_SEC * 15</code> is 15 seconds.
 +
 +
==== Death room ====
 +
<pre>
 +
dilbegin death_room(tick : integer, damage : integer, act_s : string);    // function.zon
 +
</pre>
 +
Hurts the players in the room: every <code>tick</code> ticks (at least 12, three seconds), each player in it loses <code>damage</code> hit points and sees <code>act_s</code> (or "You bleed from your wounds." when it is <code>""</code>). A player whose hit points run out dies. It can kill slowly, like a smoky cave, or at once, like open space. Gods are not hurt.
 +
 +
NPCs are spared, unless the room has an extra named <code>$death room for mobs</code>; then NPCs are hurt too, except those with an extra <code>$no death room</code>.
 +
<pre>
 +
dilcopy death_room@function(PULSE_SEC * 60, 60,
 +
  "Flames shoot up from the floor, burning your feet.");
 +
</pre>
 +
This does 60 hit points of damage every minute.
 +
 +
==== Force move ====
 +
<pre>
 +
dilbegin force_move(tick : integer, strings : string, random : integer);    // function.zon
 +
</pre>
 +
Moves everything in the room to another room without anyone typing a command: rivers, quicksand, transporters.
 +
* <code>tick</code>: how often, in ticks (at least 12, three seconds).
 +
* <code>strings</code>: one string with the destination room as <code>symbol@zone</code>, a <code>!</code>, and the message shown to whoever is moved: <code>"river2@riverzon!You float down the river."</code>. Without the <code>!</code> and a message, or with a room that doesn't exist, the script writes an error to <code>vme.log</code> and stops.
 +
* <code>random</code>: <code>FALSE</code> (0) moves at a steady rate; <code>TRUE</code> varies each wait by up to half of <code>tick</code> either way.
 +
Players, NPCs and objects in the room are all moved, except rooms inside it and anything with an extra named <code>$no force move</code>. Each sees the message, players see the new room, and the others there see "''Someone'' has arrived."
 +
<pre>
 +
dilcopy force_move@function(PULSE_SEC * 30, "river2@riverzon!You float down the river.", FALSE);
 +
</pre>
 +
Keep the string on one line in the zone file, and put <code>&lt;br/&gt;</code> in the message where it should break. The old <code>&amp;n</code> code doesn't work in DIL arguments.
  
−
=== DIL functions for rooms ===
+
==== Water current ====
 +
<pre>
 +
dilbegin watercurrent(dir : integer, messages : stringlist, beats : integer);    // basemove.zon
 +
</pre>
 +
A river or stream that carries players, NPCs and objects downstream, a little at a time. About every five seconds everything in the room counts one beat; after <code>beats</code> beats it is carried out through the exit <code>dir</code> (<code>DIR_EAST</code> and so on from <code>vme.h</code>; the exit must exist). Players and NPCs make a swimming check against that exit's <code>difficulty</code> first and swallow water, losing hit points, when they fail; they are carried along either way. Whoever sits in a boat drifts with the boat.
  
−
The DIL language is the language a builder can use to make his own
+
<code>messages</code> holds four messages:
−
special functions on rooms, NPCs, objects, PCs, and much more. This
+
# to the one carried away;
−
manual is for basic zone writing and therefore will not go into how to
+
# to the others in the room left behind;
−
write your own DIL functions. The VME however is released with many
+
# to the one being carried, every second beat while waiting;
−
functions for you as an Administrator and your builders to use to make
+
# to the others in the room it arrives in.
−
special rooms, NPCs, and objects.  The following is a list of all room
+
<pre>
−
functions released with the VME 2.0 server.
+
dilcopy watercurrent@basemove(DIR_EAST,
 +
  {"The river current gently takes you east.", "$1n gently flows away to the east.",
 +
    "You gently flow further eastwards.", "$1n flows in from the west."}, 6);
 +
</pre>
 +
This, from <code>cypress.zon</code>, carries everything east after about 30 seconds. Give the room <code>movement SECT_WATER_SWIM</code> so that walking in and out of it means swimming too.
  
 +
==== Scrambled exits ====
 +
<pre>
 +
dilbegin scramble(a_exit : string);    // function.zon
 +
</pre>
 +
For mazes: when a player types one of the directions named in <code>a_exit</code>, they are taken out through a random exit of the room instead, together with their followers. Only <code>north</code>, <code>east</code>, <code>south</code>, <code>west</code>, <code>up</code> and <code>down</code> are used, also for the random pick, and a closed door doesn't stop it. Gods and NPCs walk normally.
 +
<pre>
 +
dilcopy scramble@function("north east south west");
 +
</pre>
 +
The template also means to refuse <code>drag</code> and <code>ride</code> in the room, but doesn't: those commands still work.
  
−
;Death room
+
==== Blocking commands ====
−
: This function is a simple function that allows you to create a room to do damage to a player. The death_room can kill them slowly like a fire cave would or it can kill them quickly as if you stuck them in a microwave it is all up to how you set the arguments.  It also lets you see the acts the players see so this function can be used on any number of death style rooms.  There is no need to understand how the function works just how to use it so with that in mind the following is the functions header.
+
<pre>
−
<nowiki>
+
dilbegin block_cmd(blockcmds : stringlist, actvict : string, actrest : string);   // function.zon
−
//In function.zon
+
</pre>
−
dilbegin death_room(tick: integer, damage: integer, act_s: string);</nowiki>
+
Made for guards, but it works on a room too: the commands in <code>blockcmds</code> do nothing in the room, for anyone. <code>actvict</code> is shown to the one who tried, <code>actrest</code> to the others in the room; either can be <code>""</code>.
−
As with any function all you have to do is 'dilcopy' the function
+
<pre>
−
onto your room with the correct zone name and arguments and it will do
+
dilcopy block_cmd@function({"bury", "dig"}, "The floor is solid rock.", "");
−
the rest.  In this DIL you have three arguments to pass The first is the
+
</pre>
−
'tick' or time which in this DIL is broken down into 'ticks' which are 4
 
−
ticks per second.  Thus if you wanted to get something to do damage
 
−
every minute you would put '60*4' in that spot.  The next is the amount
 
−
of damage you want done per your time.  If for example you want '60' hit
 
−
+points damage done each round you just put '60' as that argument.
 
−
Finally is the act shown to the character as a string in quotes.  So a
 
−
finished death room on your room would look like this.
 
−
<nowiki>
 
−
dilcopy death_room@function(4*60,60,
 
−
"Flames shoot up from the floor burning your butt.");</nowiki>
 
−
;Force move
 
−
: This function allows you to move a player or NPC from a room to another room with out having the player or NPC type or do anything.
 
  
−
The following is the definition of the force move DIL
+
==== Seasonal zones ====
−
<nowiki>
+
<pre>
−
dilbegin force_move (tick: integer, strings: string, random: integer);</nowiki>
+
dilbegin season(startm : integer, startd : integer, endm : integer, endd : integer,
−
The 'tick' parameter is how fast you want the force move to be
+
                minutes : integer, syms : stringlist, hook : string);   // function.zon
−
triggered.  The 'tick' is in 1/4 second increments so to get a one
+
</pre>
−
second wait you would place a four.  The second parameter is two strings
+
Put on one room of a zone with <code>reset RESET_NEVER</code>, it resets the zone every <code>minutes</code> minutes between two dates of the real calendar (a Christmas or Halloween event), and removes the units in <code>syms</code> when the season ends. The comment above it in <code>function.zon</code> explains the arguments; <code>hallows23.zon</code> uses it.
−
the first being the symbolic name of the room you are forcing the
 
−
character to. The second string is the act you want shown to the player
 
−
or NPC when it is moved. The final parameter is either a one or a zero.
 
−
The one stands for true and it would make the timer trigger randomly
 
−
fifty percent of the time, while a zero would make it not random.
 
  
−
The following is what the force move would look like if you wanted it to trigger every 30 seconds and give acts of a river.
+
==== Templates you won't find ====
−
<nowiki>
+
Older versions of this page and of the manual list templates that are gone or never existed:
−
dilcopy force_move@function(4*30,{"river2@riverzon","You float down the river."},0);</nowiki>
+
* <code>safe_room@function</code>, a room where nobody can fight, doesn't exist.
−
;Safe room
+
* <code>death@function</code> is <code>death_room@function</code>, and its damage is in hit points, not percent.
−
: This function creates a safe room where combat is not allowed.
+
* <code>climb@function</code> still exists but does nothing: climbing is now set with the <code>EX_CLIMB</code> exit flag, see [[Manual:Zone_Manual/The_Room_Section/Climbing|Climbing]].
−
The following is the definition and an example of how to use it.
+
* The old <code>special SFUN_DEATH_ROOM</code> and <code>SFUN_FORCE_MOVE</code> were replaced by the two templates above.
−
<nowiki>
 
−
//Safe room DIL definition
 
−
dilbegin safe_room ();
 
  
−
//Example use of Safe room
+
To write a template of your own, start with [[Manual:DIL Manual/dilbegin|dilbegin]] and the room's events: a room script is woken by the commands typed in it ([[Manual:DIL Manual/SFB CMD|SFB_CMD]]) and by its [[Manual:DIL Manual/heartbeat|heartbeat]] ([[Manual:DIL Manual/SFB TICK|SFB_TICK]]), and moves units about with [[Manual:DIL Manual/link()|link()]].
−
dilcopy safe_room@function ();</nowiki>
 
  
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: left;float:left;width:50%;'>[[Manual:Zone_Manual/The_Room_Section/Compiling_and_debugging_your_first_room|Previous: Compiling and debugging your first room]]</div>
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: left;float:left;width:50%;'>[[Manual:Zone_Manual/The_Room_Section/Compiling_and_debugging_your_first_room|Previous: Compiling and debugging your first room]]</div>
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: right;float:right;width:50%;'>[[Manual:Zone_Manual/The_Room_Section/A_more_complex_set_of_rooms|Next: A more complex set of rooms]]</div>
 
<div style='padding-top: 30px; padding-bottom: 20px; text-align: right;float:right;width:50%;'>[[Manual:Zone_Manual/The_Room_Section/A_more_complex_set_of_rooms|Next: A more complex set of rooms]]</div>

Revision as of 06:20, 15 November 2026

DIL functions for rooms

DIL is the language for giving rooms, NPCs and objects behaviour of their own. This manual is about building zones, so it doesn't teach you to write DIL; the DIL manual does. The zones that come with the server contain many DIL templates you can use without writing any DIL yourself. This page lists the ones made for rooms.

You put a template on a room with dilcopy, the template's name, the zone it is in, and its arguments:

dilcopy death_room@function(PULSE_SEC * 15, 60, "Flames shoot up from the floor.");

The ; at the end is required. vmc checks neither the name nor the arguments: a wrong name or a missing argument compiles without a word and shows up only at boot or when the script runs, in vme.log. Check them against the template's dilbegin line in its zone file (in vme/zone/).

Times are given in ticks of a quarter of a second. PULSE_SEC (4) from vme.h makes them easier to read: PULSE_SEC * 15 is 15 seconds.

Death room

dilbegin death_room(tick : integer, damage : integer, act_s : string);    // function.zon

Hurts the players in the room: every tick ticks (at least 12, three seconds), each player in it loses damage hit points and sees act_s (or "You bleed from your wounds." when it is ""). A player whose hit points run out dies. It can kill slowly, like a smoky cave, or at once, like open space. Gods are not hurt.

NPCs are spared, unless the room has an extra named $death room for mobs; then NPCs are hurt too, except those with an extra $no death room.

dilcopy death_room@function(PULSE_SEC * 60, 60,
   "Flames shoot up from the floor, burning your feet.");

This does 60 hit points of damage every minute.

Force move

dilbegin force_move(tick : integer, strings : string, random : integer);    // function.zon

Moves everything in the room to another room without anyone typing a command: rivers, quicksand, transporters.

  • tick: how often, in ticks (at least 12, three seconds).
  • strings: one string with the destination room as symbol@zone, a !, and the message shown to whoever is moved: "river2@riverzon!You float down the river.". Without the ! and a message, or with a room that doesn't exist, the script writes an error to vme.log and stops.
  • random: FALSE (0) moves at a steady rate; TRUE varies each wait by up to half of tick either way.

Players, NPCs and objects in the room are all moved, except rooms inside it and anything with an extra named $no force move. Each sees the message, players see the new room, and the others there see "Someone has arrived."

dilcopy force_move@function(PULSE_SEC * 30, "river2@riverzon!You float down the river.", FALSE);

Keep the string on one line in the zone file, and put <br/> in the message where it should break. The old &n code doesn't work in DIL arguments.

Water current

dilbegin watercurrent(dir : integer, messages : stringlist, beats : integer);    // basemove.zon

A river or stream that carries players, NPCs and objects downstream, a little at a time. About every five seconds everything in the room counts one beat; after beats beats it is carried out through the exit dir (DIR_EAST and so on from vme.h; the exit must exist). Players and NPCs make a swimming check against that exit's difficulty first and swallow water, losing hit points, when they fail; they are carried along either way. Whoever sits in a boat drifts with the boat.

messages holds four messages:

  1. to the one carried away;
  2. to the others in the room left behind;
  3. to the one being carried, every second beat while waiting;
  4. to the others in the room it arrives in.
dilcopy watercurrent@basemove(DIR_EAST,
   {"The river current gently takes you east.", "$1n gently flows away to the east.",
    "You gently flow further eastwards.", "$1n flows in from the west."}, 6);

This, from cypress.zon, carries everything east after about 30 seconds. Give the room movement SECT_WATER_SWIM so that walking in and out of it means swimming too.

Scrambled exits

dilbegin scramble(a_exit : string);    // function.zon

For mazes: when a player types one of the directions named in a_exit, they are taken out through a random exit of the room instead, together with their followers. Only north, east, south, west, up and down are used, also for the random pick, and a closed door doesn't stop it. Gods and NPCs walk normally.

dilcopy scramble@function("north east south west");

The template also means to refuse drag and ride in the room, but doesn't: those commands still work.

Blocking commands

dilbegin block_cmd(blockcmds : stringlist, actvict : string, actrest : string);    // function.zon

Made for guards, but it works on a room too: the commands in blockcmds do nothing in the room, for anyone. actvict is shown to the one who tried, actrest to the others in the room; either can be "".

dilcopy block_cmd@function({"bury", "dig"}, "The floor is solid rock.", "");

Seasonal zones

dilbegin season(startm : integer, startd : integer, endm : integer, endd : integer,
                minutes : integer, syms : stringlist, hook : string);    // function.zon

Put on one room of a zone with reset RESET_NEVER, it resets the zone every minutes minutes between two dates of the real calendar (a Christmas or Halloween event), and removes the units in syms when the season ends. The comment above it in function.zon explains the arguments; hallows23.zon uses it.

Templates you won't find

Older versions of this page and of the manual list templates that are gone or never existed:

  • safe_room@function, a room where nobody can fight, doesn't exist.
  • death@function is death_room@function, and its damage is in hit points, not percent.
  • climb@function still exists but does nothing: climbing is now set with the EX_CLIMB exit flag, see Climbing.
  • The old special SFUN_DEATH_ROOM and SFUN_FORCE_MOVE were replaced by the two templates above.

To write a template of your own, start with dilbegin and the room's events: a room script is woken by the commands typed in it (SFB_CMD) and by its heartbeat (SFB_TICK), and moves units about with link().

Previous: Compiling and debugging your first room
Next: A more complex set of rooms