Chapter 8

The world Data Object

Is it a dream?
Nay but the lack of it the dream,
And failing it life's lore and wealth a dream,
And all the world a dream.
--Walt Whitman, Song of the Universal

The object types you have seen so far are mob, obj, turf, and area. These are the atomic objects seen and manipulated by players. There are other types of data objects which only you, the programmer, can manipulate. To distinguish between the two, we either use the term atom or datum. The atoms are the physical building blocks for the world and the datums are intangible creatures consisting purely of data.

(Yes, I know the plural of datum is data. But that doesn't rhyme with atoms. In programming, poetic concerns outweigh linguistic trifles. However, I may occasionally slip and refer to them as data objects.)

DM provides datums for world and player information, lists, and save files. You can also define your own data objects to manage information in whatever manner you like. These topics will all be discussed in the following chapters.

The world object is created when the server starts and destroyed when it finishes. The global variable world contains a reference to this object. The variables and procedures belonging to this object are defined under /world. By changing these, you can modify the behavior of the game as a whole.

1. world variables

The variables of the world data object are described in the following list.

  • name

    is the name of the world. By default it is the same name as the dmb file without the extension. Players will see this as the name of the world they are connected to.

  • mob

    is the type of mob created for new players when they log in. By default it is /mob.

  • turf

    is the default turf to be placed on the map when none other is specified. By default it is /turf.

  • area

    is the default area placed on the map when none other is specified. By default it is /area.

  • maxx,maxy,maxz

    are the size of the map. Normally, you would not set this in the code but would let the map file produced by the map editor do the job. However, if you only want a map with the default turf and area, you can create it by specifying the size here. These variables all default to 0 (no map at all) but if you set any one of them, the others will default to 1. So, for example, you can set maxx and maxy without bothering to set maxz to get a one-level map.

  • view

    is the maximum view range. The default value of 5 gives you an 11x11 map viewport. The maximum value of 10 yields a 21x21 map. More will be said about this in chapter 14.

  • contents

    is a list of all the real objects in the world (that is mobs, objs, turfs, and areas). When the world is used where a list is expected, this list will be used.

  • log

    is a useful destination for debugging output. Text sent here is displayed by the server program in its output. When running a world directly inside the client (the local server), the text is displayed on the client terminal. Internal errors, like proc crashes, are all reported to world.log.

  • params

    is a list of user-defined parameters supplied to the world before it was started. More will be said about this in section 10.9.

  • realtime

    is the time in 10$^ths$ of seconds since 00:00:00 GMT, January 1, 2000 (also known as BYOND time). The principal use for this is when you need to record when something happened (like when a user last logged in).

  • time

    is the length in 10$^ths$ of seconds that the world has been running (also known as game time). This is actually a measure of cpu time rather than real time. For example, if the server sleeps when no players are logged in, that time is not counted.

  • sleep_offline

    if set to 1 will cause the world to be suspended when there are no players. The default value is 0, which means the world will only be suspended if nothing is going on. Use this variable if you don't want your NPCs to get up to mischief while the humans are away.

  • tick_lag

    controls the length of time between one moment and the next. It is the smallest meaningful unit of time (measured in 10$^ths$ of seconds). The default value is 1, which means all events in the world happen in increments of 0.1 seconds. The smaller this value, the more precise timings will be, the faster players can issue commands, etc. The cost of this, however, is in extra load on the cpu. If it gets too high, the extra overhead can actually make the game run slower as a result. More will be said on the subject of event timing in chapter 13.

  • cpu

    is the percentage of time being used up by the server in running the world. It is normally close to 0, indicating that the server is getting everything done ahead of schedule and then twiddling its thumbs for the rest of the tick. A value over 100 would indicate that the server is not able to get everything done in the allocated amount of time (i.e. tick_lag). Usually, you don't need the cpu variable to tell you when this is happening. When the game becomes sluggish (and its not a matter of network traffic) it probably means the cpu is overloaded.

  • address

    is the network address of the machine hosting the world or null if this cannot be determined.

  • port

    is the port number of the world or 0 if the world has no open network port. The full address of the world is formed by combining the world address and port like this: "[address]:[port]".

    2. world procs

    The various world procs provide control over the server and allow you to respond to events which affect it. They are described in the following sections.

    2.1 New and Del

    Like all data objects, world has New and Del procs, which are called at creation and destruction of the world. They do not take any arguments. The only thing to happen before New gets called is initialization of global variables and creation of the map and its contents. Similarly, Del is called prior to destroying the map and other existing objects.

    You could use these procs to perform any initialization while loading and cleanup when shutting down. One common task would be to read and write information about the state of the world to a save file, which will be covered in chapter 12.

          world.log << "[name] started at [realtime]."
          world.log << "[name] shutdown at [realtime]."

    In this example output is sent to world.log. Since it may be true that no players are connected at the time, that is a useful destination for output in procs of this nature.

    2.2 Repop proc

    The Repop proc re-populates the map. Any objects (that is mobs or objs) which have been destroyed and which were on the initial map will be recreated in their original positions.

    This simple example gives the DM mob a command to restore the world's depleted population.


    Any objects which one does not want re-populated could be created dynamically (that is using new) instead of with the map editor. Otherwise, one could just avoid deleting them by moving them to the null location instead. Only deleted objects created with the map editor will be restored by Repop.

    In many cases, you might want to automatically call Repop every so often. That will be covered later in chapter 13 on scheduling events.

    2.3 Reboot proc

    The Reboot proc causes the entire world to be recreated from scratch. Any players who are connected will automatically re-login once the world has finished loading.

    This could be used to restart the server when you have recompiled the dmb file with revised code. In that case, a simple command could give the DM power to cause the reboot.


    If you need to save any information about the state of the world, you could do so by overriding the Reboot proc. This would first save the information and then call the parent proc to perform the reboot.

    2.4 Inter-world Communication

    It is possible for two worlds running on the network to communicate with each other. This opens up some very interesting possibilities, including mega-worlds distributed across the network, taking advantage of the parallelism of multiple machines. It is a large topic, worthy of its own chapter, and it shall have one. However, this section briefly introduces the procs which make it possible, just to give you a complete introduction to the world data object. For the conclusion of this story, see section 12.6.

    2.4.1 Topic proc

    The Topic proc receives messages from other worlds. When worlds communicate, they must pick a topic of conversation--hence the name of the proc. Often the topic itself is the entire message, but you will see in a following section how to send more data.

    Topic (Topic,Addr,Master)
    Topic is the topic text string.
    Addr is the address of the remote world.
    Master is true if the sender is this world's parent.
    Return value is passed back to the remote world.

    The return value of the Topic proc gets sent back to the remote world. It is therefore possible to ask simple questions, by sending a message and getting back a response.

    The most basic question is, "are you there?" This example shows how you might handle it.

       if(Topic == "ping") return 1

    Actually, the "ping" topic is such a common one that it is built in to the default Topic proc. The only difference is that it returns one plus the number of players, a useful piece of information which is always true. The reason we want to return a true value is that the remote world will get null back if it tries to send a message to a non-existent address.

    2.4.2 Export proc

    The Export proc is used to send (or export) a message to another world. It may be used to send a file, but may also just access a topic. The proc returns the value passed back by the world receiving the message. If the message cannot be sent, null is returned.

    Export (Addr,File)
    Addr is the address and topic.
    File is the file to send.
    Returns the remote Topic() result.

    The format for the address is ip:port#topic. Here is an example that uses the "ping" topic described in the previous section.

       var/p = world.Export("")
       usr << "Ping returned '[p]'."

    2.4.3 Import proc

    The Import proc is used to receive a file which was sent from another world using Export. It may only be used while handling a call to the Topic proc.

    Import ()
    Returns the downloaded file.

    This proc is normally used to transfer a save file and will be discussed in greater detail in section 12.6. However, it could be used to send resource files too. The following example defines a topic that receives and plays a sound file to everyone in the world.

       if(Topic == "sound")
          world << Import()

    Not bad for a few lines of code! Of course, why you would want to do this is another question.