DM Reference


DM language details

The DM (Dream Maker) language uses a syntax similar to C/C++ to build networked multi-user worlds. This reference and the accompanying guide discuss the structure and function of DM.


cache

See also:
FILE_DIR definition
cache_lifespan var (world)
fcopy_rsc proc
file proc
icons
sounds

Files specified in single quotes are loaded (at compile time) into the world cache file (ending in .rsc). These are referred to as resource files. At runtime these files are downloaded by players into their byond.rsc file for future use. With the appropriate verbs or through savefiles, players may also upload files into the world cache.

If a resource file is not used for a long time, it will be automatically removed from the cache file to save space. If a cache file gets too bulky, however, you may manually delete it and start from scratch.

To make compilation faster and to make it easier to distribute code, the compiler will use an existing cache file if possible. That means you could compile up a world, and send people the .dm and .rsc files without any need to package all the individual resource files. It is also possible to include additional supplementary .rsc files by using the #include statement.


comment

Comments may be used to explain code. They can also be used to turn off a line or block of code. All text inside a comment is ignored by the compiler.

The single line comment begins with // and runs to the end of the line.

The multi-line comment begins with /* and runs until */.

Multi-line comments may be nested.

Example:

// single line comment /* multi-line comment */

garbage collection

At runtime, data objects are garbage collected. That means data which is no longer in use gets automatically deleted to free up system memory. This applies to text strings, lists, savefiles, datum objects, and so on.

The garbage collector works by using an efficient reference counting system. Once an item is no longer referenced by any variable, it gets deleted. For the most part, that frees you from having to think about memory allocation, which is wonderful, especially in the case of text strings, which tend to be allocated on the fly all over the place.

There are a couple provisos that you should note. One is that circular references will never be deleted by the garbage collector. By circular reference, I mean a pair of objects with variables that point to each other, or even an object with a variable that points to itself. In rare cases, you may even depend on this behavior. When you are done with such objects, you should either null out the circular reference, or you should forcibly destroy each object with the del instruction.

An object with running or sleeping procs is referenced by the src variable of those procs and will therefore not be thrown out.

Another note is that the world.contents list does not count as a reference. Otherwise, /mob and /obj objects would never be deleted, which is not the case. Note that objects which are contained by another object or which contain objects themselves are referenced and will not be deleted. That means an object must be at loc=null with no contents and, of course, no other references anywhere in order to get deleted by the garbage collector.

Mobs with a non-empty key and all objects with non-empty tags are also immortal.

Turfs and areas do not currently get garbage collected.

When the world shuts down, all objects are destroyed, whether they are referenced or not. You don't have to worry about system memory getting consumed by persistent objects. That doesn't happen.

In general, people who do not like reference counting garbage collection should be happy that DM provides a del instruction, allowing you to take charge and delete things whether they are referenced or not. Another nicety is that this automatically nulls out any existing references to the object, so you don't end up with dangling references to a deleted object, which can otherwise be a great source of instability and mysterious bugs.


icons

See also:
FILE_DIR definition
cache
flick proc
icon
icon var (atom)
icon_state var (atom)
image objects

An icon file may be referenced by putting single quotes around the filename. The file extension determines the type of icon. Currently supported icon types are .dmi, .bmp, .png, .jpg, and .gif. To create dmi icons, use the Dream Maker icon editor. This allows you to make animations, 4 or 8 directional icons, and icons with different states (such as "live" and "dead").

Example:

mob icon = 'monster.dmi'

You can also load icons into memory at run-time and manipulate the graphical data to produce new icons dynamically. This is done by creating an /icon object.


icon arithmetic

See also:
icon proc
icon_states proc
icons
rgb proc
turn proc (applied to an icon)

NOTE: the following "arithmetical" methods of icon manipulation are being phased out in favor of the new /icon object, which can be directly manipulated and which provides a wider variety of operations.

There are several ways in which icons can be manipulated at runtime. They can be rotated, added together, and the colors components may be altered.

One purpose for such operations is to make players look different. Other interesting uses (and abuses) will undoubtedly follow.

Addition and Subtraction

The result of adding two icons is an arithmetic combination of the color components of each individual pixel. At positions where either icon is transparent, the result is also transparent. Subtraction, instead of increasing the intensity, decreases it by the amount in each pixel of the icon being subtracted.

Suppose you wanted to add together different bodies and heads. You could do that by making a few of each type with black backgrounds. When these add together, the black contributes nothing but prevents pixels in the other icon from getting clipped.

Example:

mob/verb addicon(I as icon) icon += I subicon(I as icon) icon -= I

If you need to add the same color to every pixel, you can do so using a color value. Color values have the same format as in HTML: "#RRGGBB" with two hexadecimal digits for each color component. That gives you a range in color from 0 to FF (which is 255 in decimal).

You can also specify a color value as "#RGB". The single digit is automatically repeated, so "#F00" is the same as "#FF0000", which is bright red. For certain pre-defined color values, you can also specify a name, such as "red". See HTML colors for a list of color names.

If you prefer base 10, you can create color values with the rgb(R,G,B) instruction. Each parameter is in the range 0 to 255.

Multiplication

To increase (or decrease) the intensity of an icon multiplicatively, you can use the '*' operator.

Example:

mob/verb/multicon(factor as num) icon *= factor

mouse control

Various mouse actions may be handled by defining procedures either on the client object or on the atomic object being manipulated. Any of the following procedures may be defined:

In general, define only the procedures you need, because extra communication overhead may be avoided when the compiler detects that you do not care about certain events.

The arguments used in mouse procs generally follow one of two forms:

For Click(), DblClick(), MouseDown(), MouseUp(), MouseEntered(), MouseExited(), and MouseMove():
client/Click(object, location, control, params)
atom/Click(location, control, params)
For MouseDrag() and MouseDrop():
client/MouseDrag(src_object, over_object, src_location, over_location, src_control, over_control, params)
atom/MouseDrag(over_object, src_location, over_location, src_control, over_control, params)

The location argument varies with the type of control. For the map, it will be the turf where the mouse action happened. For info controls (statpanels), it will be the name of the statpanel where the action happened. For grid controls, it will be the cell where the action happened. For others controls it may vary, but most will leave this blank.

The control argument is the ID of the skin control where the action happened, such as "mappane.map" or "mainwindow.banner".

The params argument is text, and can be converted to a list using params2list(). It may contain any of the following properties, which will only be set if they are used:

The mouse pointer may be customized as well. The following variables all deal with the appearance of the pointer. They do not control what actions may be taken by the user, but they provide hints to the user about what actions may work.

When selecting a mouse pointer, you may provide your own custom icon or use one of the built-in pointers.

Note: Older games compiled prior to BYOND 4.0 had a different format for the MouseDown() and MouseUp() procs. These used icon_x and icon_y as arguments, but control and params have replaced them.


mouse pointers

See also:
mouse control
mouse_drag_pointer var (atom)
mouse_drop_pointer var (atom)
mouse_drop_zone var (atom)
mouse_opacity var (atom)
mouse_over_pointer var (atom)
mouse_pointer_icon var (client)

The following mouse pointers are built-in and may be assigned to any of the mouse pointer variables. Of course, you can also define your own custom mouse pointers using an icon file.

MOUSE_INACTIVE_POINTER (0)
MOUSE_ACTIVE_POINTER (1)
MOUSE_DRAG_POINTER
Same as mouse_drag_pointer = MOUSE_ACTIVE_POINTER.
MOUSE_DROP_POINTER
Same as mouse_drop_pointer = MOUSE_ACTIVE_POINTER.
MOUSE_ARROW_POINTER
Same as mouse_over_pointer = MOUSE_INACTIVE_POINTER.
MOUSE_CROSSHAIRS_POINTER
Same as mouse_over_pointer = MOUSE_ACTIVE_POINTER.
MOUSE_HAND_POINTER

null

Variables that are not initialized have the value null. This value is distinct from 0 and "". If you compare it to these, using the == operator, it is not equal. However, in a numeric context (like a mathematical operation), null evaluates to 0 and in a text context (like insertion into a text expression), null evaluates to "". In a logical expression, null, 0, and "" evaluate to false and all other values are true.

In an embedded text expression, null behaves like "". That means, if you are expecting a variable to display a 0, you should explicitly initialize it to 0 rather than leaving it as null.


preprocessor

The preprocessor performs various transformations on source code as the DM compiler reads the file. It may be used to define macros--that is words which are replaced by other fragments of code. It is also possible to insert other source code files and to conditionally compile or not compile sections of code.

Preprocessor commands are called directives. They are placed on a line by themselves and always begin with a hash symbol #. The preprocessor directives recognized by DM are the same as standard C compilers:

#define
#if
#elif
#ifdef
#ifndef
#else
#endif
#include
#error
#warn

DM_VERSION macro

See also:
byond_version var (world)
byond_version var (client)
preprocessor

This macro indicates the version of the compiler. This could be useful when distributing code that uses new language features that would not compile in older compilers.

Example:

#if DM_VERSION < 230 #error This compiler is too far out of date! #endif

__FILE__ macro

See also:
ASSERT proc
DEBUG definition
__LINE__ macro
__MAIN__ macro

The __FILE__ macro expands to a string containing the name of the current source file. This may be useful when generating debugging error messages.


__LINE__ macro

See also:
ASSERT proc
DEBUG definition
__FILE__ macro

The __LINE__ macro is replaced by the line number in the current source file. This may be useful when generating debugging error messages.


__MAIN__ macro

See also:
preprocessor

The __MAIN__ macro is defined in the main .dme file being compiled. In all other files included by this file, __MAIN__ is not defined.

The purpose of this is for library writers to package a small demo of their library directly in the library source code. When users compile the library directly, the library's own .dme is the main file and can include extra files that are not normally part of the library.

Example:

#ifdef __MAIN__ #include "demo.dm" #include "demo.dmm" #endif

If the demo requires a lot of extra resources, it is probably better to package the demo as a separate project. Small demos, however, are nice and convenient using this "auto-demo" technique--especially since Dream Seeker automatically launches Dream Maker after installing a library containing a .dme file.


#define directive

See also:
preprocessor
Format:
#define Name Value
#define Name(Parameters) Value
Args:
Name: A macro definition.
Value: The value to substitute for Name.
Parameters: Arguments to pass into the macro.

The #define statement creates a macro that is substituted for Name. Substitution only applies to whole words. Text inside of double or single quotes is not processed for substitution, so "This is BIG." would not be modified even if a macro named BIG were defined. That is different from "This is [BIG].", where BIG is an embedded expression, which does get processed for macro substitution.

Example:

#define DAY 0 #define NIGHT 1 var/daytime = NIGHT //daytime = 1

Example:

#define SQR(X) ((X)*(X)) var/x = SQR(2) //x = ((2)*(2)) = 4

Note that it's usually important to use parentheses around any arguments you use in a macro. Otherwise strange results may occur if you use an expression such as 2+3. In the SQR(X) example, if there were no parentheses around each X then the expansion of the macro would be (2+3*2+3). Since the * operator has a higher precedence than + the result is 11, not 25 as expected. It's equally important to put parentheses around the entire macro for the same reason.


DEBUG definition

See also:
#define directive
Format:
#define DEBUG

If DEBUG is defined, source file and line number information will be stored in the compiled .dmb file. If a proc crashes during execution and DEBUG information is present, the current source file name and line number will be indicated in the error output.

This option increases the size of the .dmb, typically by about 10%. Execution of the code may also be a tiny bit slower.

If you are distributing the .dmb to players and you do not want them to have debug access at runtime, you should not compile in debug mode.

If you want to use the run-time profiler (see the debugging options in Dream Seeker), you must compile in debug mode. Then you can get a report of CPU usage by your various procs.


FILE_DIR definition

See also:
cache
icons
Format:
#define FILE_DIR Path
Args:
Path: A search path on the current filesystem.

This macro defines a search path to be used in evaluating resource files (icons and sounds). First the current directory is searched, then the first FILE_DIR path, then the next, etc.

Example:

#define FILE_DIR icons #define FILE_DIR icons/mobs mob/clown icon = 'clown.dmi'

This searches for the file at the paths "./clown.dmi", "./icons/clown.dmi", and "./icons/sounds/clown.dmi", where "." is the directory of the current source file.


#elif directive

See:
#if directive

#else directive

See:
#if directive

#endif directive

See:
#if directive

#error directive

See also:
preprocessor
#warn directive
Format:
#error Text
Args:
Text: an error message to display

The #error directive halts compilation and displays the specified message.

Example:

#if DM_VERSION < 4 #error This compiler is too far out of date! #endif

#if directive

See also:
#define directive
#ifdef directive
Format:
#if Val
...
#elif Val2
...
#else
...
#endif
Args:
Val: A logical expression.

The #if statement is used to conditionally compile code. If Val is true (non-zero), the code following the #if statement will be compiled. Otherwise, compilation skips to the next #elif, #else, or #endif statement.

The function defined() can be used in the conditional expression. It is true if its argument is a defined macro (with #define) and false otherwise.

Example:

#if defined(DEBUG) // This code will be compiled if DEBUG is // defined #else // This code will be compiled if DEBUG is // not defined #endif

#ifdef directive

See also:
#define directive
#if directive
#ifndef directive
Format:
#ifdef Name
Args:
Name: A macro definition.

The #ifdef statement is used to conditionally compile code. It is equivalent to #if defined(Name).


#ifndef directive

See also:
#define directive
#if directive
#ifdef directive
preprocessor
Format:
#ifndef Name
Args:
Name: A macro definition.

The #ifndef statement is used to conditionally compile code. It is equivalent to #if !defined(Name).


#include directive

Format:
#include "Filename"
#include <Filename>
Args:
"Filename": The path to the filename to include, from the current directory.
<Filename>: The path inside the BYOND lib directory.

The #include statement causes the compiler to process another file before continuing in the current source file.

If a file is included multiple times, only the first occurrence will be processed. That is a convenient addition to the standard C preprocessor, which DM otherwise emulates quite closely.

The file <stddef.dm> is automatically included before all other source code.

Example:

#include "test.dm" // checks ./test.dm #include <test.dm> // checks lib-path/test.dm

The BYOND lib directory is called "lib" and is located in the BYOND system directory (typically "\Program Files\Byond\lib"). If the file is not found there, it also looks in the user lib directory, which would typically be "...\Byond\user\login-name\lib".

Note that the compiler interface allows you to include files graphically by simply clicking the checkbox next to the file. This creates an include statement for you in the .dme project environment file. The only time you would still want to manually include files is when you need to ensure a certain order of processing. For example, if file "MyCode.dm" overrides procedure definitions of an object defined in "LibCode.dm", you should include "LibCode.dm" at the top of "MyCode.dm". Most other DM code is independent of order, but overriding procedure definitions is not. The compiler will warn you in such cases if you forget.

Another case in which you should manually include files is if you are writing a library to be used by other programmers. Since the .dme file is not distributed with a library, all necessary inclusions must be made in the .dm files.


#undef directive

See also:
#define directive
preprocessor
Format:
#undef Name
Args:
Name: A macro definition.

The #undef statement removes a macro definition.


#warn directive

See also:
preprocessor
#error directive
Format:
#warn Text
Args:
Text: a warning message to display

The #warn directive displays the specified message as a warning, but does not prevent the project from compiling.

Example:

#ifdef USE_LIGHTING #warn The lighting feature in MyLibrary is experimental. #endif

sounds

See also:
FILE_DIR definition
cache
sound proc
/sound datum

A sound stored in a file may be referenced by putting single quotes around the filename. The file extension determines the type of sound. Currently supported music types include MIDI (.mid or .midi), and module formats .mod, .it, .s3m, .xm, and .oxm. Supported sound effect formats include .wav, .ogg, .raw, .wma, and .aiff.*

Example:

world << sound('fugue.midi')

This example plays the specified midi file to all players.

Notes

*The MP3 format is not presently supported by BYOND due to licensing issues. Ogg-Vorbis, however, is a good alternative. For music the module formats are also a good choice, and tend to be smaller.


text

See also:
<< output operator
entities (text)
macros (text)
tags (text)
text proc

Text consists of a string of characters enclosed in double quotes. To place a quote inside a string, escape it with \.

Example:

usr << "He said, \"Hi.\""

This example sends some text to the usr: He said, "Hi."

To insert a variable expression into a string, enclose it in brackets []. These are referred to as embedded text expressions. An object expression will display the object's name preceded by the text macro \the or \The if no other article has been specified. Capitalization of the article is inferred from context.

Example:

mob/verb/shout(T as text) world << "[usr]: [T]"

If this example is called by a mob named "Bill" with the text "hi everybody!", it will display "Bill: hi everybody!".

On the other hand, if it is called by a mob named "cat", it would display "The cat: hi everybody!".

For lengthy text strings, DM provides a special text document syntax. This begins with {" and ends with "}. It may include multiple lines and even un-escaped double quotes.

Example:

mob/verb/end() usr << {" This is the way the world ends This is the way the world ends This is the way the world ends Not with a bang but a whimper. --T.S. Eliot "Hollow Men" "} del world //the end!

entities (text)

See also:
macros (text)
tags (text)
text

Special characters may be inserted into text using HTML syntax. Such characters are known as entities. They start with an ampersand and end with a semicolon. The main reason for doing this is to insert characters that otherwise have a special meaning. The most common entities have names. The rest must be referred to by their ASCII number (e.g. &#38; is the same as &amp;). The common ones are listed in the following table. Note that the same effect may be achieved by simply escaping the special character (like \<). The full entity syntax is included for generality.

&amp; &
&lt; <
&gt; >
&quot; "
&copy; ©

macros (text)

See also:
icon text macro
text
text proc

Text macros start with '\' (a backslash) and end with a space or other punctuation.

\the, \The // insert 'the' (if needed) \a, \an, // insert 'a(n)' or 'some' (if needed) \A, \An \he, \He // insert 'he/she/they/it' \she, \She // same \his, \His // insert 'his/her/their/its' \him // insert 'him/her/them/it' \himself // insert 'himself/herself/themself/itself' \herself // same \hers // insert 'his/hers/theirs/its' \proper // used in an object name to force proper-noun behavior \improper // used in an object name to force improper-noun behavior \th // insert 1st, 2nd, 5th etc. \s // insert 's' if [] was plural \icon // insert icon of following [] \ref // insert a unique id for following [] \roman // insert following [] as a lower-case roman numeral \Roman // insert following [] as an upper-case roman numeral \... // suppress final new line \n // insert new line \" // insert double quote \\ // insert backslash \< // insert &amp;lt; (less than) \> // insert &amp;gt; (greater than) \(space) // skip a space \(newline) // skip a newline (and following space)

Example:

mob/verb/steal(M as mob,obj/O as obj in M) O.loc = usr view() << "[usr] finds \himself \an [O]."

Example:

var/DayCount proc/NewDay() DayCount++ world << "The [DayCount]\th day dawns."

Example:

obj/CPU name = "\improper CPU" //prevent capitalization from causing proper-noun behavior

icon text macro

See also:
icon_state var (atom)
macros (text)
style sheets
tags (text)

The \icon macro is used to treat the following embedded expression (in []'s) as an icon rather than as text. An object, for example, would be replaced by its icon rather than by its name.

Example:

usr << "You look like this: \icon[usr]!"

The \icon macro expands internally to the <IMG> tag. The above example, could be rewritten like this:

usr << "You look like this: \ <IMG CLASS=icon SRC=\ref[usr.icon] ICONSTATE='[usr.icon_state]'>!"

Note that the current icon state of the object is automatically used. Also note that the image belongs to a class called icon. That allows you to configure the way icons are displayed by using a style sheet. The following default style rule causes icons to be shrunk to 16 by 16 pixels so they fit in better with surrounding text:

IMG.icon {width: 16px; height: 16px}

You could override this setting globally in your own style sheet. You could even define rules to allow individual icons to be formatted differently from the rest.

Example:

BIG IMG.icon {width: 32px; height: 32px} SMALL IMG.icon {width: 16px; height: 16px}

With those rules in place, you could output a full sized icon by using the <BIG> tag:

usr << "You look like this: <BIG>\icon[usr]</BIG>!"

The one time that one might want to use the <IMG> tag directly is to specify the ALT text to be displayed on clients which don't support graphical icons.

Specific states, directions, and frames of an icon can be displayed in lieu of the default through use of the following tags:

  • ICONSTATE='[state]'
  • ICONDIR=[dir], where dir is one of NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, SOUTHWEST
  • ICONFRAME=[frame], where frame is the animation frame, starting with 1

    Example:

    usr << "You look like this: \ <IMG CLASS=icon SRC=\ref[usr.icon] ICONSTATE='glowing' ICONDIR=NORTH ICONFRAME=2>!"

    Note that the \icon macro does not work in the mini-browser; it is only for text output. To make icons appear in an HTML document, use browse_rsc() to send an icon to the client before using browse() to display it.


    ref text macro

    See also:
    Topic proc (client)
    icon text macro
    locate proc
    macros (text)
    tag var (datum)

    The \ref text macro inserts a unique identification number or text string for the following embedded object (inside []'s). If the object has a tag, that will be used. Otherwise, an internal id number is used. In either case, the embedded reference is surrounded by [] brackets.

    The reason the tag is preferred is that it stands a better chance of still being valid if the object is deleted and recreated (like in a world reboot). The internal id number, on the other hand, is transient and should only be expected to remain the same for the duration of the object's existence. If you want a more permanent reference, you must assign and save the object's tag variable.

    The primary use for object references embedded in text is in topic links. This allows you to encode a reference to an object in the href value of a hyperlink. (Just make sure the object does not get deleted before the user executes the link. See garbage collection.)

    Topic links that contain a parameter "src" assigned to an object reference are treated somewhat specially. Unless you override client.Topic() to do otherwise, the default behavior is to call the referenced object's own Topic() procedure.

    Example:

    mob/verb/test() usr << "Click <a href=?src=\ref[src];action=start>here</a>!" mob/Topic(href,href_list[]) switch(href_list["action"]) if("start") usr << "Starting the game..." else return ..()

    The above example uses an embedded reference to the player's own mob to create a link to a topic handled by that mob's Topic() proc. The href_list parameter is simply the result of params2list(href).

    In that example, the embedded reference was automatically converted back into an object (dereferenced) for you. If you embed references to additional objects in the href data, you would have to dereference those yourself using the locate() instruction.


    style sheets

    See also:
    entities (text)
    macros (text)
    script var (client)
    tags (text)
    text

    HTML tags, such as <FONT> may be used to directly format output text. Another approach, however, is to use HTML tags to specify purely structural information and use a style sheet to define how various elements within that structure should be treated. DM uses a subset of the Cascading Style Sheet (CSS) language, which was introduced for this purpose in HTML documents.

    This section discusses the syntax of style sheets as an independent element. For information on how to include the style sheets in your DM code, see the section on client.script.

    As an example of a style sheet, one might want combat and conversational messages to appear differently--perhaps using different colors. Instead of using the <FONT> tag to color the text, you could use <SPAN> to mark the beginning and ending of the text and to specify what kind of message it is. The result might be text such as the following:

    "[usr] <SPAN CLASS=combat>spanks</SPAN> [targ]!" "[usr] says, '<SPAN CLASS=chat>[msg]</SPAN>'"

    The CLASS attribute may be used with any tag, but SPAN and DIV are often convenient because they have no other side-effect but defining the style class. SPAN is for text within a single paragraph and DIV is for whole paragraphs. The way text belonging to a particular class is formatted may be controlled in a style sheet such as the following:

    .combat {color: red} .chat {color: green}

    This says that text in the 'combat' class should be colored red and text in the 'chat' class should be colored green. These classes are not pre-defined; you can create whatever new style classes you need.

    The advantage of using style sheets instead of direct formatting tags is that you can cleanly separate structural information (such as combat and conversational messages) from formatting information (such as red and green text). By separating the two, you or the player can easily plug in different formatting schemes without changing any of the actual content.

    A style sheet is composed of a list of rules, such as the two rules in the preceding example. Each rule contains one or more selectors followed by a body of attribute assignments (in braces). The selector specifies the context of the rule and the body specifies the format.

    A selector may specify a container tag (such as SPAN, BODY, or P) and a class. The above example could have been written with a selector of SPAN.chat. However, by leaving out the tag, it applies to any tag with CLASS=chat. It is also possible to only specify the tag and not the class. In that case, the selector applies to any matching tag, regardless of class.

    To specify a nested context, several simple selectors may be listed one after the other. For example, emphasized text within a combat message could be enlarged with the following rule:

    .combat EM {font-size: larger}

    It is also possible to list several selectors separated by commas in order to make them all apply to the same body. For example, this next rule is equivalent to the two following ones:

    .combat EM, .chat EM {font-size: larger} .combat EM {font-size: larger} .chat EM {font-size: larger}

    The style rule body contains a list of attribute assignments, delimited by semicolons. Each assignment takes the form of an attribute name, followed by a colon, followed by the value of the attribute. The following table summarizes the recognized attributes and their possible values.

    color #F00, #FF000, red, rgb(255,0,0), rgb(100%,0%,0%)
    background
    font-size 10pt, 1.5em, 150%
    font-style normal or italic
    font-weight normal, bold, lighter, darker, or 100 to 900
    font-family monospace, sans-serif, serif, cursive, ...
    font style weight size family
    text-decoration none or underline
    text-align right, left, or center
    text-indent 0.25in, 3em, 20pt
    margin-left
    margin-right
    width 16px, 32px, auto
    height

    fonts

    The font attribute is a special short-hand for assigning font-size, font-style, font-weight, and font-family in one statement. Any properties that are not specified in the font statement are assigned to their default values.

    The font family may be a specific font name or a more general category such as monospace or sans-serif. Since not all users necessarily have the same fonts installed, it is a good idea to list alternate fonts. The desired font is placed first, followed by other possible fall-backs, each separated by a comma. Usually a general family such as monospace is listed last of all. Any font names containing a space should have quotes around them.

    The following example sets the font for the <BODY> tag. Even if you don't explicitly use <BODY> in output text, it is applied implicitly.

    BODY {font: 12pt 'Times New Roman', sans-serif}

    This sets the font to 12 point and selects Times New Roman if it is available and otherwise falls back on a system-determined sans-serif font. This command also implicitly specifies not to use italics and to use a normal font weight (not bold).

    Font sizes may be specified in points (1pt = 1/72 of an inch), picas (1pc = 12pt), pixels (px), inches (in), centimeters (cm), and millimeters (mm). There are also various levels corresponding to the traditional 1 to 7 HTML scale. These are xx-small, x-small, small, medium, large, x-large, and xx-large. In addition to these absolute font sizes, it is possible to use a relative size, such as 150% or equivalently 1.5em. This scales the font relative to the currently active font setting.

    In addition to regular classes, there are special pseudo-classes for handling embedded hyperlinks. These are specified in the selector with the class starting with a colon rather than a dot. They are :link, :visited, and :active. These only apply to the <A> tag. The :link class applies to hyperlinks in their normal state. Once a link has been clicked, it belongs instead to the :visited class. When the user holds the mouse over a link, it temporarily belongs to the :active class. The only attribute that may change in an active or visited link is the text color.

    margins and indents

    Paragraphs can be given different margins according to your preferences. The margin-left attribute controls the left margin, and margin-right is the right margin. You can use specific sizes like inches or points, or a relative size unit like em or ex. (A percentage is interpreted so that 100% is 1em, not the width of the window.) Using the text-indent attribute will indent the first line of a paragraph from the left margin. It is possible to create a hanging indent by using a negative value for text-indent, like so:

    BODY {text-indent: -0.5in; margin-left: 0.5in}

    background colors

    The background attribute is only relevant to the BODY context. It causes the entire terminal background to change color. When doing this, it is usually necessary to change the foreground colors of text or it may become unreadable. The various standard classes of output generated by DreamSeeker are in the following table.

    system colors

    system notice general notices from the client
    system command echo command echoing
    system command expansion command-line expansion list
    system pager pager messages
    system irc IRC command prefix

    The value of the CLASS attribute may contain a list of classes separated by spaces. This permits client output to be in the 'system' class as well as more specific ones. That allows you to change all of these colors in one shot if you are too lazy to change them each individually. For example, if you define a style sheet that changes the background color, you might need to redefine the various foreground colors like this:

    BODY {background: aqua; color: black} .system {color: red; font-weight: bold} .command {color: green}

    In this example, the background color of the terminal will be aqua, normal text from the server will be black, and all output from the client will be bold and red, except echoed commands and expansion lists, which will be bold and green. The more specific .command rule is placed after the general .system rule so that its color takes precedence. This is how style sheets are composed--you write general rules first followed by any exceptions.

    style rule precedence

    The order in which rules are specified is one of the factors that determines precedence of style sheet commands. The language is known as Cascading Style Sheets because of its ability to handle several layers of stylistic rules, intermingling the configurations of the user and the designer in an ordered fashion.

    Rules are selected by first finding all matching candidates for a given attribute in the current HTML tag being processed. If there is more than one, rules from a higher level style sheet take precedence over lower level ones. That means the basic user configurable settings in DreamSeeker are the lowest priority, followed by a style sheet in the user's .dms script file, followed by a style sheet from the designer's client.script setting, because that is the order in which these are read by the style sheet manager.

    Rules from the same style sheet are ordered by specificity. The selector SPAN.chat is more specific than .chat and .chat EM is more specific than EM. In general, the more classes referenced by a selector, the more specific it is. When that results in a tie, the selector with the greater number of tags takes precedence.

    If two rules about the same attribute come from the same sheet and have the same specificity, the final one to be defined takes precedence.

    In the rare event that a rule needs to break out of the normal order of precedence, it can be flagged as important. In this case it will take precedence over all other "unimportant" rules. However, if more than one rule is important, the normal rules of precedence will be used to resolve the conflict.

    The important flag is applied after the attribute assignment like this:

    BODY {background: white ! important; font: serif}

    In the above example, only the background color is important, not the font specification.

    STYLE attribute

    Style commands may also be inserted directly in an html tag to control its appearance. This does not have the advantages of style sheets, which separate content from presentation, but it does allow you to use the style sheet syntax when formatting text.

    The following example uses the style attribute to color some text:

    usr << "That <SPAN STYLE='color: red'>HURT</SPAN>!"

    As you can see, the STYLE attribute of any tag can be assigned to a text string containing a list of attribute assignments. Just the body of the style rule is given, since no selector is needed to match the current context.


    tags (text)

    See also:
    entities (text)
    macros (text)
    style sheets
    text

    Text tags (also known as elements by snooty HTML purists) control how the text is formatted. HTML syntax is used, so all tags start with < and end with >. The tags which are currently supported by Dream Seeker, are listed below:

    <A></A>              // anchor (hyperlink)
    <ACRONYM></ACRONYM>  // acronym or abbreviation
    <B></B>              // bold text
    <BIG></BIG>          // one size bigger text
    <BODY></BODY>        // body of html document
    <BR>                 // line break
    <CITE></CITE>        // citation reference
    <CODE></CODE>        // program source code
    <DFN></DFN>          // definition
    <DIV></DIV>          // used in conjunction with style sheets
    <EM></EM>            // emphasized text
    <FONT></FONT>        // font face, color, and size
    <H1></H1>            // heading level
    <H2></H2>
    <H3></H3>
    <H4></H4>
    <H5></H5>
    <H6></H6>
    <HEAD></HEAD>        // document head section
    <HTML></HTML>        // html document
    <I></I>              // italic text
    <IMG></IMG>          // display icons
    <KBD></KBD>          // keyboard input
    <P></P>              // paragraph
    <PRE></PRE>          // pre-formatted text
    <S></S>              // overstrike text
    <SAMP></SAMP>        // sample output
    <SMALL></SMALL>      // one size smaller text
    <SPAN></SPAN>        // used in conjunction with style sheets
    <STRONG></STRONG>    // strongly emphasized text
    <STYLE></STYLE>      // contains a style sheet
    <TITLE></TITLE>      // document title
    <TT></TT>            // typewriter style
    <U></U>              // underline
    <VAR></VAR>          // variable name
    <XMP></XMP>          // preformatted (tags ignored)
    

    In addition to these, the <BEEP> tag, which is not standard HTML, may be used to beep the terminal.

    Some tags take additional parameters, known as attributes. The most common ones are <FONT> and <A>. The syntax for these is illustrated by the following two examples:

    "How about <FONT FACE=Arial COLOR=red SIZE=+1>this</FONT>!" "Click <A HREF=byond.com TITLE=BYOND!>here</A>!"

    As many attributes may be specified as desired. The attribute value may have quotes around it, but this is only necessary if the value contains spaces. It is usually more convenient to use single quotes so you don't have to escape the double quotes, but you can also embed the HTML in a text document to avoid the need for escaping quotes.

    Text colors may be specified by name or RGB value. The named colors and their corresponding RGB value are listed in the following table:

    black #000000
    silver #C0C0C0
    gray #808080
    grey #808080
    white #FFFFFF
    maroon #800000
    red #FF0000
    purple #800080
    fuchsia #FF00FF
    magenta #FF00FF
    green #00C000
    lime #00FF00
    olive #808000
    gold #808000
    yellow #FFFF00
    navy #000080
    blue #0000FF
    teal #008080
    aqua #00FFFF
    cyan #00FFFF

    The hexadecimal colors above are written with 8 bits (two hex digits) for each color. It is also possible to use 4 bit values by using only one hex digit per color. The full 8 bit color is produced by repeating each digit. For example, #F00 (red) is the same as #FF0000.

    Text sizes range from 1 to 7, 1 being the smallest and 7 being the largest. In addition to absolute sizes, relative sizes may be specified (like +1 for one size bigger or -1 for one size smaller).


    area

    See also:
    atom
    procs (area)
    rooms
    vars (area)

    Areas are derived from /area. Regions on the map may be assigned to an area by painting it onto the map. Areas off the map serve as rooms that objects may enter and exit.

    For each area type defined, one area object is created at runtime. So for areas on the map, all squares with the same area type belong to the same instance of the area.

    Additional instances of rooms may be created from the same type by explicitly creating them with null as the initial location. That is, the first argument to new() should either be null or left unspecified.

    The following example defines the area prototype /area/outside. It also defines an action to be taken when somebody enters an area, namely to display its description.

    Example:

    area Entered(O) if(desc) O << desc return ..() outside desc = "Ah! A breath of fresh air!"

    procs (area)

    Built-in area procs:

    area/proc
    Click
    DblClick
    Del
    Enter
    Entered
    Exit
    Exited
    MouseDown
    MouseDrag
    MouseDrop
    MouseEntered
    MouseExited
    MouseMove
    MouseUp
    New
    Read
    Stat
    Topic
    Write

    rooms

    Areas that are not located on the map are referred to as rooms. When a player enters one, the map goes away and you have something like a text MUD. By default, there would be no way for players to move from one room to another, so you have to handle movement yourself.

    You can check the variable area.x to see if a given area is on the map or not.

    The following example puts players in a room when they log in and provides a single exit.

    Example:

    mob/Login() if(!loc) Move(locate(/area/birthing_hut)) return ..() area/birthing_hut Entered(O) O << "Waaaaah! You land in a pile of straw." return ..() verb/exit() if(Move(locate(1,1,1))) //jump to the map or whatever usr << "You crawl into the open air..." else usr << "The hut door is blocked. You cannot get out."

    vars (area)

    Built-in area vars:

    area/var
    alpha
    blend_mode
    color
    contents
    density
    desc
    dir
    gender
    icon
    icon_state
    invisibility
    underlays
    overlays
    layer
    luminosity
    maptext
    maptext_width
    maptext_height
    mouse_over_pointer
    mouse_drag_pointer
    mouse_drop_pointer
    mouse_drop_zone var
    mouse_opacity var
    name
    opacity
    parent_type
    suffix
    tag
    text
    transform
    type
    vars
    verbs

    parent_type var (area)

    See also:
    parent_type var

    The default parent_type of /area is /atom.


    atom

    See also:
    area
    datum
    mob
    movable atoms
    obj
    procs (atom)
    turf
    vars (atom)

    The /atom object type is the ancestor of all mappable objects in the game. The types /area, /turf, /obj, and /mob are all derived from /atom. You should not create instances of /atom directly but should use /area, /turf, /obj, and /mob for actual objects. The /atom object type exists for the purpose of defining variables or procedures that are shared by all of the other "physical" objects. These are also the only objects for which verbs may be accessible to the user.

    /atom is derived from /datum, so it inherits the basic properties that are shared by all DM objects.


    movable atoms

    See also:
    atom
    mob
    obj
    procs (movable atoms)
    vars (movable atoms)

    The /atom/movable object type is the ancestor of all mappable objects that are capable of motion. The types /obj and /mob are derived from /atom/movable. You should not create instances of /atom/movable but should use /obj and /mob for actual objects. This object definition exists solely to define variables and procedures related to motion.


    procs (movable atoms)

    Built-in movement procs:

    atom/movable/proc
    Bump
    Move
    Cross proc
    Crossed proc
    Uncross proc
    Uncrossed proc

    Bump proc (movable atom)

    See also:
    Move proc (movable atom)
    Pixel movement
    Format:
    Bump(atom/Obstacle)
    When:
    Called when a movement fails due to a dense blockage.
    Args:
    Obstacle: The blocking object.
    Default action:
    If the obstacle is a mob and src is in its group, swap their positions. This is only done if the mobs both move by full tiles and do not use pixel movement, to preserve the behavior of older games.

    Cross proc (movable atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    Move proc (movable atom)
    group var (mob)
    Pixel movement
    Format:
    Cross(atom/movable/O)
    Returns:
    1 to permit; 0 to deny.
    When:
    Called when another object attempts to overlap this one.
    Args:
    O: the object attempting to overlap.
    Default action:
    Allow overlap unless both atoms are dense. If both atoms are mobs, the behavior depends partly on whether they are in the same group.

    If src completely covers the turf it is standing on, Cross() is called as part of turf.Enter(). This is to preserve the behavior of older games, which expect turf.Enter() to care about its contents.

    If src and O are both mobs, and O is in src's group, overlap is allowed unless neither of them use pixel movement. Older games that do not use pixel movement expect that Bump() will be called, and by default Bump() will swap the mobs' positions. Swapping obviously only works in situations where a mob takes up a whole tile and only moves by tiles; for all other situations, allowing an overlap makes more sense.


    Crossed proc (movable atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Cross proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    Move proc (movable atom)
    group var (mob)
    Pixel movement
    Format:
    Crossed(atom/movable/O)
    When:
    Called when an object has overlapped this one through Move(). Directly setting the object's loc or step_x/y vars does not result in a call to Crossed() or any other movement side-effects. The same goes for creation or deletion of an object at a location.
    Args:
    O: the object that moved and is now overlapping.
    Default action:
    none

    Example:

    obj/landmine Crossed(O) O << "You stepped on a land mine!" Explode()

    Move proc (movable atom)

    See also:
    Bump proc (movable atom)
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    loc var (atom)
    locs list var (movable atom)
    walk proc
    Gliding
    Pixel movement
    Format:
    Move(NewLoc,Dir=0,step_x=0,step_y=0)
    Returns:
    Success (jump): 1
    Success (slide): Number of pixels moved
    Failure: 0
    When:
    Called to move the object. By default, client.Move() calls this proc when players use direction keys. The automated movement functions (like walk()) also call this proc. Directly setting the loc variable does not call this procedure.
    Args:
    NewLoc: The new location.
    Dir: The direction of movement (or 0).
    step_x: The new step_x value, relative to NewLoc
    step_y: The new step_y value, relative to NewLoc

    Any Move() is either a slide or a jump. Normal walking around is a slide; it can be stopped partway. A jump is pass/fail. See more information below.

    This is what happens by default:

    1. oldloc.Exit(src) is called for any turfs or areas being vacated, or the container if moving out of an obj or mob. neighbor.Uncross(src) is called for any movable atoms that will no longer be overlapping this object. If any of these return 0 (failure), movement fails.

    2. newloc.Enter(src) is called for any turfs or areas that may be entered for the first time, or the container if moving into an obj or mob. neighbor.Cross(src) is called for any movable atoms that may be in collision with this object if the move fully succeeds. If any of these return 0 (failure), then a slide can be cut short but a jump will fail completely.

    3. If any obstacles were encountered via Enter() or Cross() failing, then src.Bump(obstacle) will be called for each of them.

    4. If movement did not fail completely, then loc and step_x/y, will be changed, and the following calls will be made: oldloc.Exited() for any turfs, areas, or other containers vacated; neighbor.Uncrossed() for any movable atoms no longer overlapping; newloc.Entered() for any turfs, areas, or other containers being entered for the first time; and neighbor.Crossed() for any movable atoms now overlapping the object.

    A movement is considered a slide if src is moving from one turf to another on the same z level, and the total pixel distance is less than either src.step_size or a full tile size (whichever is largest). Any other movement is a jump. Movement to the same turf with no step_x/y change is also considered a jump.


    Uncross proc (movable atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncrossed proc (movable atom)
    Move proc (movable atom)
    group var (mob)
    Pixel movement
    Format:
    Uncross(atom/movable/O)
    Returns:
    1 to permit; 0 to deny.
    When:
    Called when another object attempts to stop overlapping this one.
    Args:
    O: the object attempting to get away.
    Default action:
    Allow the object to get away (returning 1)

    Uncrossed proc (movable atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Move proc (movable atom)
    group var (mob)
    Pixel movement
    Format:
    Uncrossed(atom/movable/O)
    When:
    Called when an object has stopped overlapping this one through a call to Move(). Directly setting the object's loc or step_x/y vars does not result in a call to Uncrossed() or any other movement side-effects. The same goes for deletion of an object.
    Args:
    O: the object that moved and is no longer overlapping.
    Default action:
    none

    Example:

    obj/pressure_plate Uncrossed(O) // if no other mobs are standing on it... if(!(locate(/mob) in bounds())) // do something Release()

    vars (movable atoms)

    Built-in movement vars:

    atom/movable/var
    animate_movement
    bound_x
    bound_y
    bound_width
    bound_height
    locs
    screen_loc
    glide_size
    step_size
    step_x
    step_y

    animate_movement var (movable atoms)

    See also:
    Move proc (movable atom)
    glide_size var (movable atoms)
    Gliding
    Default value:
    FORWARD_STEPS (1)
    Possible values:
    NO_STEPS (0)
    FORWARD_STEPS (1)
    SLIDE_STEPS (2)
    SYNC_STEPS (3)

    Deprecated. This setting has no impact when used with pixel movement. See Gliding for more details.

    Setting this to 0 causes movement between two adjacent positions to be displayed as a single discrete jump. Otherwise, objects will be made to glide from one position to another, using the movement animation defined in the icon file if one is defined.

    By default, movement animation avoids cutting corners, since this can look very bad in some games. If you want objects to take the shortest (and smoothest) visual path when moving around, use SLIDE_STEPS instead of the default FORWARD_STEPS. This also allows the object to be facing in a different direction than it is moving, so make sure this is what you want.

    SYNC_STEPS is intended for objects that move in unison as part of a larger "conglomerate" object. You should set the movement animation to SYNC_STEPS on all but a single "head" object, which will serve as the leader when choosing pixel step sizes. If you do not use SYNC_STEPS, there are cases where the pixel offsets of objects may get out of sync during motion, causing the object to visually break up.


    bound_x var (movable atom)

    See also:
    bound_y var (movable atom)
    bound_width var (movable atom)
    bound_height var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    locs list var (movable atom)
    Pixel movement
    Default value:
    0

    This var defines the left side of the physical atom's bounding box, in pixels. By default all atoms are assumed to be one tile in physical size.

    The left edge of the bounding box starts bound_x pixels inward from the left edge of the atom's icon (as affected by step_x). A bound_x value of 4 means the atom has 4 pixels of empty space to its left.

    Example: A 16×16 smiley face centered in a 32×32 icon should have a bound_x value of 8, since there are 8 pixels of empty space to the left.


    bound_y var (movable atom)

    See also:
    bound_x var (movable atom)
    bound_width var (movable atom)
    bound_height var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    locs list var (movable atom)
    Pixel movement
    Default value:
    0

    This var defines the bottom side of the physical atom's bounding box, in pixels. By default all atoms are assumed to be one tile in physical size.

    The bottom edge of the bounding box starts bound_y pixels inward from the bottom edge of the atom's icon (as affected by step_y). A bound_y value of 4 means the atom has 4 pixels of empty space below it.

    Example: A 16×16 smiley face centered in a 32×32 icon should have a bound_y value of 8, since there are 8 pixels of empty space below.


    bound_width var (movable atom)

    See also:
    bound_x var (movable atom)
    bound_y var (movable atom)
    bound_height var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    locs list var (movable atom)
    icon_size var (world)
    Pixel movement
    Default value:
    32 (width of default icon; depends on world.icon_size)

    This var defines the width of the physical atom's bounding box, in pixels. By default all atoms are assumed to be one tile in physical size.

    Example: A 16×16 smiley face centered in a 32×32 icon should have a bound_width value of 16.


    bound_height var (movable atom)

    See also:
    bound_x var (movable atom)
    bound_y var (movable atom)
    bound_width var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    locs list var (movable atom)
    icon_size var (world)
    map_format var (world)
    Pixel movement
    Default value:
    32 (depends on world.icon_size)

    This var defines the height of the physical atom's bounding box, in pixels. By default all atoms are assumed to be one tile in physical size.

    Example: A 16×16 smiley face centered in a 32×32 icon should have a bound_height value of 16.

    The default value depends on world.icon_size and world.map_format. In a topdown or tiled map_format, the icon height specified in world.icon_size is used. In other modes, height is irrelevant and tile "footprints" are square, so the icon width is used.


    glide_size var (movable atoms)

    See also:
    animate_movement var (movable atoms)
    glide_size var (client)
    pixel_x var (atom)
    pixel_y var (atom)
    icon_size var (world)
    Gliding
    Default value:
    0

    Deprecated. This setting has no impact when used with pixel movement. See Gliding for more details.

    This controls the number of pixels an object is moved in each footstep during animated movement. The default value of 0 chooses automated control over this value, which generally results in a minimum footstep of 4 pixels that is increased when necessary to keep up with motion on the turf grid.

    Be careful about using small step sizes. Icons with high contrast pixel-level detail can look pretty ugly when displaced by short distances.

    This was renamed from pixel_step_size.


    locs list var (movable atom)

    See also:
    bound_x var (movable atom)
    bound_y var (movable atom)
    bound_width var (movable atom)
    bound_height var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    loc var (atom)
    contents list var (atom)
    Default value:
    list(src.loc)

    This read-only var tells which turfs are being physically covered by the atom's bounding box. The purpose of this is for cases where you set the atom's bounds to change its physical size so that it ends up covering more than one turf.

    This is different from the loc var in that every atom still has only one "true" location. A movable atom may cover multiple turfs, but only one turf is its loc. The loc var can be thought of as an anchor point, while the actual physical footprint is in locs.

    For every turf in locs, this atom will also be in that turf's contents list.

    If loc is not a turf, it will be the only item in the locs list. If loc is null, locs will be empty.


    pixel_step_size var (movable atoms)

    Renamed to glide_size.


    screen_loc var (movable atoms)

    See also:
    HUD / screen objects
    layer var (atom)
    screen var (client)
    view var (client)
    map_format var (world)

    This is a text string that controls where an object that is listed in client.screen will appear on the user's screen. The format is:

    "x,y" "x1,y1 to x2,y2"

    The bottom left corner of the map viewport (southwest) is "1,1". If the view is 11x11, then the top-right corner (northeast) is "11,11". (Changing world.map_format may change the range for screen_loc.)

    A range of coordinates (the second format above) causes a square region to be filled with the object at each position. The southwest and northeast corners of the box are indicated in the screen_loc value.

    The edges of the map may also be referenced by using directions, such as "3,NORTH". For convenience, the order of coordinates is arbitrary when using directions, so one may specify y before x as in "NORTH,WEST". In expressions such as the latter, you may also leave out the comma.

    The CENTER keyword can also be used. This can be used alone to completely center the object, or as either the x or y component. If the map covers an even number of tiles in either direction, pixel offsets will be applied automatically.

    In addition to objects inside of the map view, one may create border objects. Borders are automatically created when screen objects are placed at coordinates outside of the inner map view. For example, objects placed at y=0 fall on a border directly below the map and y=-1 is one tile below that. (The CENTER keyword is based on normal viewport bounds and not any extra borders.)

    Offsets may be applied to screen_loc coordinates. For example, "NORTH+1,WEST" is in a border above the map. "CENTER+2,CENTER-1" will appear 2 units right, 1 unit down from the center of the map.

    It is also possible to specify a pixel offset. Screen objects do not use pixel_x and pixel_y for this purpose, because it is intended that an object could exist on the map and in the screen object list simultaneously, so positioning must be independent. Pixel offsets are specified after a colon like this: "1:16,1:16". In this case the object is shifted to the northeast by 16 pixels.

    Normal layering rules apply to screen objects when using a default top-down world.map_format (TOPDOWN_MAP or TILED_ICON_MAP), so to color the background of the map (visible at least when regions of the map are blocked from view), one could create an object with a drawing layer below all other map objects and set its screen_loc to cover the whole map (e.g. "1,1 to 11,11"). To achieve this affect in other map modes like isometric, you will have to add BACKGROUND_LAYER to the layer.

    You can use HUD objects in any additional map controls that might appear in game's skin file. If you have a second map named "map2" for instance, then you can use "map2:1,1" or something similar as a screen_loc. If the map control is set to automatically scale to fit its contents, it will try to show every object you put there. (NOTE: You should not use the full window.control name, just the name of the control itself. Map controls should always have unique names.)


    step_size var (movable atom)

    See also:
    step_x var (movable atom)
    step_y var (movable atom)
    Move proc (movable atom)
    locs list var (movable atom)
    fps var (world)
    icon_size var (world)
    Gliding
    Pixel movement
    Default value:
    32 (width of default icon; depends on world.icon_size)

    This var defines how fast, in pixels, an atom will move by default. If you use lower values of step_size for most items in your world, you may want to consider raising world.fps (at higher performance cost).

    When Move() is called by a step or walk, or by the built-in client movement verbs, a change of step_size is applied to step_x and/or step_y. Any movement within the speed of step_size, or up to one tile in distance (whichever is greater), is considered a slide and may partially succeed if an obstacle is bumped before reaching the final position.


    step_x var (movable atom)

    See also:
    step_y var (movable atom)
    step_size var (movable atom)
    bound_x var (movable atom)
    Move proc (movable atom)
    locs list var (movable atom)
    Pixel movement
    Default value:
    0

    This var defines the position of the atom (in pixels) relative to its tile, on the x axis. A step_x of 5 means the atom actually is shown 5 pixels east of the tile's western edge.

    The atom's actual bounding box may not begin at step_x, but can be set even further in via bound_x.

    Example: A 16×16 smiley face centered in a 32×32 icon should have the following bounds:

    For the smiley to appear at the left edge of the tile it is standing on, it would need a step_x value of -8. A step_x value of 8 takes it all the way to the rightmost edge of the tile. Anything outside of the range -8 to 8 will have the atom straddling multiple turfs.


    step_y var (movable atom)

    See also:
    step_x var (movable atom)
    step_size var (movable atom)
    bound_y var (movable atom)
    Move proc (movable atom)
    locs list var (movable atom)
    Pixel movement
    Default value:
    0

    This var defines the position of the atom (in pixels) relative to its tile, on the y axis. A step_y of 5 means the atom actually is shown 5 pixels north of the tile's southern edge.

    The atom's actual bounding box may not begin at step_y, but can be set even further in via bound_y.

    Example: A 16×16 smiley face centered in a 32×32 icon should have the following bounds:

    For the smiley to appear at the bottom edge of the tile it is standing on, it would need a step_y value of -8. A step_y value of 8 takes it all the way to the top edge of the tile. Anything outside of the range -8 to 8 will have the atom straddling multiple turfs.


    procs (atom)

    Built-in atom procs:

    atom/proc
    Click
    DblClick
    Del
    Enter
    Entered
    Exit
    Exited
    MouseDown
    MouseDrag
    MouseDrop
    MouseEntered
    MouseExited
    MouseMove
    MouseUp
    New
    Read
    Stat
    Topic
    Write

    Click proc (atom)

    See also:
    Click proc (client)
    DblClick proc (atom)
    MouseDown proc (atom)
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (atom)
    MouseUp proc (atom)
    show_popup_menus var (client)
    Format:
    Click(location,control,params)
    When:
    Called when the object is clicked.
    Args:
    location: the turf, stat panel, grid cell, etc. in which the object was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This proc is called by the default client.Click() procedure.

    The following example allows the player to walk to a position by clicking it.

    Example:

    turf/Click() walk_to(usr,src)

    DblClick proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (client)
    MouseDown proc (atom)
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (atom)
    MouseUp proc (atom)
    show_popup_menus var (client)
    Format:
    DblClick(location,control,params)
    When:
    Called when the object is double-clicked.
    Args:
    location: the turf, stat panel, grid cell, etc. in which the object was double-clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This proc is called by the default client.DblClick() procedure.

    This example allows the player to teleport to a position by double clicking it.

    Example:

    turf/DblClick() usr.Move(src)

    Enter proc (atom)

    See also:
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    Move proc (movable atom)
    Pixel movement
    Format:
    Enter(atom/movable/O, atom/oldloc)
    Returns:
    1 to permit; 0 to deny.
    When:
    Called when an object attempts to enter the contents list.
    Args:
    O: the object attempting to enter.
    oldloc: the old (current) loc of the object attempting to enter.
    Default action:
    Explained below.

    Areas, objs, and mobs will always permit anything to enter by default.

    Turfs will return 1 (permit) or 0 (deny) based on density. In simple terms, if the atom that is entering is dense, then the turf will deny entry if the turf itself or its contents (any that take up the full tile) are dense.

    What actually happens in turf.Enter() is more detailed: The turf's density is checked against the object's density first. If this check succeeds (movement is permitted), then Cross() is called for any atoms in turf.contents that cover the entire tile. If any Cross() call fails, Enter() fails too and will return 0.

    If a mob is standing on a turf but its bounding box does not cover the whole tile, it is ignored by Enter(). Instead, its Cross() proc is called if there is a danger of the object overlapping it.


    Entered proc (atom)

    See also:
    Enter proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    Move proc (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    Format:
    Entered(atom/movable/Obj,atom/OldLoc)
    When:
    Called when an object has entered the contents list through Move(). Directly setting the object's loc or step_x/y vars does not result in a call to Entered() or any other movement side-effects. The same goes for creation or deletion of an object at a location.
    Args:
    Obj: the object that entered (a mob or obj).
    OldLoc: the previous location of the object.
    Default action:
    none

    Example:

    turf/pit Entered(O) O << "OUCH. You fell in a pit!"

    The mob's Entered() and Exited() procs can be used to control what happens when objects are added or removed from the mob's inventory. Of course that could all be done within get() and drop() verbs, but the following code separates user interface from lower-level functions.

    Example:

    obj var weight = 10 verb get() set src in oview(1) if(Move(usr)) usr << "You pick up \a [src]." else usr << "You cannot pick up [src]." drop() set src in usr if(Move(usr.loc)) usr << "You drop \a [src]." mob var weight max_weight = 50 Entered(obj/O) weight += O.weight Exited(obj/O) weight -= O.weight Enter(obj/O) //only allow entrance if weight is within the limit if(O.weight + weight <= max_weight) return ..()

    To see the advantages of this arrangement, imagine that there are certain situations in which an object may be created directly within the mob's inventory without the mob picking it up. You can still run it through your normal movement rules without calling get().

    Example:

    mob/verb/wish() var/obj/O = new() //create it with loc=null if(O.Move(usr)) //and then move it into inventory usr << "Your wish has been granted!" else usr << "You are too greedy!" del O

    Exit proc (atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exited proc (atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    Move proc (movable atom)
    Format:
    Exit(atom/movable/O)
    Returns:
    1 to permit; 0 to deny.
    When:
    Called when an object attempts to exit the contents list.
    Args:
    O: the object attempting to exit.
    Default action:
    Allow the object to exit (returning 1).

    By default, every atom returns 1 to allow exit.

    If a turf allows exit, Uncross() will be called for any atoms in turf.contents that cover the entire tile. If any Uncross() call fails, Exit() fails too and will return 0. In games using pixel movement, Uncross() is usually called separately, but this allows projects using tile-based movement instead to benefit from Cross() and Uncross().


    Exited proc (atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    Move proc (movable atom)
    Format:
    Exited(atom/movable/Obj)
    When:
    Called when an object has exited from the contents list through a call to Move(). Directly setting the object's loc or step_x/y vars does not result in a call to Exited() or any other movement side-effects. The same goes for deletion of an object.
    Args:
    Obj: the object that exited (a mob or obj).
    Default action:
    none

    MouseDown proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (atom)
    MouseDown proc (client)
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (atom)
    MouseUp proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    MouseDown(location,control,params)
    Args:
    location: the turf, stat panel, grid cell, etc. in which the object was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This is called when a mouse button is pressed while pointing to this object.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Most operations can be done through Click(), DblClick(), and MouseDrop(). The other procedures are simply available for completeness.

    Note: In BYOND 3.5 this procedure took three different arguments: location, icon_x, and icon_y. Since icon_x and icon_y have been replaced, old code will need to be modified. Games compiled before this change will still work normally.


    MouseDrag proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (atom)
    MouseDown proc (atom)
    MouseDrag proc (client)
    MouseDrop proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (atom)
    MouseUp proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_drop_zone var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    MouseDrag(over_object,src_location,over_location,src_control,over_control,params)
    Args:
    over_object: the object under the mouse pointer
    src_location: the turf, stat panel, grid cell, etc. from where the src object was dragged
    over_location: the turf, stat panel, grid cell, etc. containing the object under the mouse pointer
    src_control: The id of the skin control the object was dragged from
    over_control: The id of the skin control the object was dragged over
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This is called while dragging this object by pressing and holding the left mouse button over the object and moving the mouse. The over_object may be null if dragging over a stat panel or over other empty space.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Most operations can be done through Click(), DblClick(), and MouseDrop(). The other procedures are simply available for completeness.


    MouseDrop proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (atom)
    MouseDown proc (atom)
    MouseDrag proc (atom)
    MouseDrop proc (client)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (atom)
    MouseUp proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_drop_zone var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    MouseDrop(over_object,src_location,over_location,src_control,over_control,params)
    Args:
    over_object: the object under the mouse pointer
    src_location: the turf, stat panel, grid cell, etc. from where the src object was dragged
    over_location: the turf, stat panel, grid cell, etc. containing the object under the mouse pointer
    src_control: The id of the skin control the object was dragged from
    over_control: The id of the skin control the object was dropped onto
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This is called when the a mouse button is released after dragging this object. The over_object may be null if dropping over a stat panel or over other empty space.


    MouseEntered proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (atom)
    MouseDown proc (atom)
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    MouseEntered proc (client)
    MouseExited proc (atom)
    MouseMove proc (atom)
    MouseUp proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    MouseEntered(location,control,params)
    Args:
    location: the turf, stat panel, grid cell, etc. containing the object
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This is called when the mouse moves onto the object with no buttons pressed.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Defining it on only the objects that require it reduces overhead.


    MouseExited proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (atom)
    MouseDown proc (atom)
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (client)
    MouseMove proc (atom)
    MouseUp proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    MouseExited(location,control,params)
    Args:
    location: the turf, stat panel, grid cell, etc. containing the object
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This is called when the mouse moves off of an object with no buttons pressed.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Defining it on only the objects that require it reduces overhead.


    MouseMove proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (atom)
    MouseDown proc (atom)
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (client)
    MouseUp proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    MouseMove(location,control,params)
    Args:
    location: the turf, stat panel, grid cell, etc. containing the object
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This is called when the mouse moves over the object with no buttons pressed. When the mouse moves over for the first time, MouseEntered() is called instead.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Defining it on only the objects that require it reduces overhead.


    MouseUp proc (atom)

    See also:
    Click proc (atom)
    DblClick proc (atom)
    MouseDown proc (atom)
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (atom)
    MouseUp proc (client)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_drop_zone var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    MouseUp(location,control,params)
    Args:
    location: the turf, stat panel, grid cell, etc. in which the object was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control

    This is called when a mouse button is released while pointing to this object.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Most operations can be done through Click(), DblClick(), and MouseDrop(). The other procedures are simply available for completeness.

    Note: In BYOND 3.5 this procedure took three different arguments: location, icon_x, and icon_y. Since icon_x and icon_y have been replaced, old code will need to be modified. Games compiled before this change will still work normally.


    New proc (atom)

    See also:
    New proc (datum)
    new proc
    Format:
    New(loc)
    (supports named arguments)
    When:
    Called when the object is created.
    Args:
    loc: The initial location.
    Default action:
    None.

    By the time New() is called, the object has already been created at the specified location and all of its variables have been initialized. You can perform additional initialization by overriding this procedure.

    Since the initial location parameter passed to new() is applied before New() is even called, there is some special handling of the loc variable when using named arguments in a call. Normally, if a procedure is overridden, named arguments in a call are matched against those in the the overridden definition. In this case, however, the loc parameter name is hard-coded. Regardless of what you call the first argument in your definition of New(), the initial location will be taken from the first positional argument, or from the argument named loc if there are no positional arguments.

    The following example does some extra initialization that is not possible in the variable definition section, because it requires a runtime evaluation. This is a common reason to use New().

    Example:

    mob var birthdate //time stamp New() birthdate = world.realtime return ..() verb/look() set src in view() usr << "[src] was born on [time2text(birthdate,"DD-MMM-YYYY")]."

    Stat proc (atom)

    See also:
    Stat proc (client)
    stat proc
    Format:
    Stat()
    When:
    Called periodically by the client to update the stat window.
    Default action:
    none.

    The following code could be used to display a player's current status.

    Example:

    mob/var health = 100 mob/Stat() stat("health",health) statpanel("Inventory",contents)

    vars (atom)

    Built-in atom vars:

    atom/var
    alpha
    blend_mode
    color
    contents
    density
    desc
    dir
    gender
    icon
    icon_state
    invisibility
    infra_luminosity
    loc
    layer
    luminosity
    maptext
    maptext_width
    maptext_height
    mouse_over_pointer
    mouse_drag_pointer
    mouse_drop_pointer
    mouse_drop_zone var
    mouse_opacity var
    name
    opacity
    overlays
    override
    parent_type
    pixel_x
    pixel_y
    pixel_z
    suffix
    tag
    text
    transform
    type
    underlays
    vars
    verbs
    x
    y
    z

    alpha var (atom)

    See also:
    vars (atom)
    blend_mode var (atom)
    color var (atom)
    Default value:
    255 (opaque)
    Possible values:
    0 (transparent) through 255 (opaque)

    Controls the opacity of the icon displayed on players' screens. A value of 128 means the atom is half-transparent, so it will have a ghostly appearance. This can be used to fade an atom in and out, especially when combined with animation. Alpha is also applied to maptext.


    blend_mode var (atom)

    See also:
    vars (atom)
    alpha var (atom)
    color var (atom)
    Default value:
    0 (none/overlay)
    Possible values:
    BLEND_DEFAULT (0)
    BLEND_OVERLAY
    BLEND_ADD
    BLEND_SUBTRACT*
    BLEND_MULTIPLY*

    [* This blend type appears only when using graphics hardware mode. It is also not visible in the map editor.]

    Controls the way the atom's icon is blended onto the icons behind it. The blend mode used by an atom is inherited by any attached overlays, unless they override it. BLEND_DEFAULT will use the main atom's blend mode; for the atom itself, it's the same as BLEND_OVERLAY.

    BLEND_OVERLAY will draw an icon the normal way.

    BLEND_ADD will do additive blending, so that the colors in the icon are added to whatever is behind it. Light effects like explosions will tend to look better in this mode.

    BLEND_SUBTRACT is for subtractive blending. This may be useful for special effects.

    BLEND_MULTIPLY will multiply the icon's colors by whatever is behind it. This is typically only useful for applying a colored light effect; for simply darkening, using a translucent black icon with normal overlay blending is a better option.


    color var (atom)

    See also:
    vars (atom)
    alpha var (atom)
    blend_mode var (atom)
    rgb proc
    Default value:
    null (white)
    Possible values:
    null (white) or any color generated by rgb()

    Controls the color of the icon displayed on players' screens. This color is multiplied by the icon, so that a white icon will become this color. The color multiplier is also applied to maptext.

    If you include an alpha component in the color, the atom's alpha var will be set at the same time.


    contents list var (atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    locs list var (movable atom)
    Pixel movement
    list
    loc var (atom)
    Default value:
    List of contained objects.

    Except in the case of areas, this list is always restricted to objs and mobs (ie movable objects). Only direct contents are listed. Items inside of a bag object, for example, would not show up in the mob's contents list.

    The contents of areas are a little different. The turfs contained in the area are in the list along with any objs or mobs directly contained by those turfs.

    If a movable atom uses the bound vars to change its physical size, or step_x/y to change its position, it may cover more than one turf. In that case, those turfs' contents won't just contain anything directly in them, but also any atoms overhanging them. I.e., if a turf is in a mob's locs list, then the mob is in that turf's contents list. (See locs for more information.)


    density var (atom)

    See also:
    Enter proc (atom)
    Entered proc (atom)
    Exit proc (atom)
    Exited proc (atom)
    Default value:
    0 (1 for mobs)

    This turns the object's density on or off (1 or 0). Two dense objects may not occupy the same space in the standard movement system.


    desc var (atom)

    Default value:
    null

    This is the description of the object.

    Example:

    mob/verb/look(atom/O in view()) if(O.desc) usr << O.desc else usr << "It's just \an [O]."

    dir var (atom)

    See also:
    Move proc (movable atom)
    icon var (atom)
    turn proc
    Default value:
    SOUTH
    Possible values:
    NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, SOUTHWEST

    This is the direction that the object is facing. This has little effect unless the object's icon is directional. In the case of a directional icon, this selects the corresponding orientation from the icon file.

    An icon file with only four (cardinal) directions makes the choice of orientation ambiguous when the true direction is a diagonal. In that case, of the two possibilities, the one closest to the previous orientation is displayed. Sounds complicated, but it's what one would naturally expect.


    gender var (atom)

    See also:
    macros (text)
    name var (atom)
    Default value:
    "neuter"

    This sets the object's gender. This influences text macros like \he, which may expand to "it", "he", "she", or "they". Valid values are:

    "neuter" "male" "female" "plural" These are also defined as constants, which may help prevent typos, since the compiler will complain if it doesn't recognize what you type: NEUTER MALE FEMALE PLURAL

    icon var (atom)

    See also:
    icon proc
    icon_state var (atom)
    icons
    overlays var (atom)
    underlays var (atom)
    Default value:
    null

    This is the icon file that will be used to represent the object on graphical clients.

    Example:

    turf/wall icon = 'wall.dmi'

    You can also assign this to an external file at run-time with an expression such as file("wall.dmi"), but you would only want to do that when the other method is not possible, because it requires addition of the file to the resource cache, which can take a little time.

    When this variable is assigned to any dynamically created icon object, that object gets dumped into the world's resource cache (the .rsc file), and a reference to that cached file is assigned to atom.icon. In other words, don't expect comparisons such as usr.icon == MyDynamicallyCreatedIcon to work unless you have used fcopy_rsc() to get a cache reference to your dynamically created icon first. This is almost never an issue, so don't worry about it if none of that made any sense to you!


    icon_state var (atom)

    See also:
    flick proc
    icon var (atom)
    icon_states proc
    Default value:
    null

    Icons may appear differently depending on the icon state. For example, turf door icons could have "open" and "closed" states. If a state is specified that does not exist in the icon file, the default null state will be displayed if it exists.

    Example:

    turf/door icon_state = "closed" density = 1 verb open() set src in view(1) icon_state = "open" density = 0 close() set src in view(1) icon_state = "closed" density = 1

    infra_luminosity var (atom)

    See also:
    luminosity var (atom)
    see_infrared var (mob)
    sight var (mob)
    view proc
    Default value:
    0

    This causes the object to be visible in the dark to mobs that can see infrared light. Nothing but the object itself is lit up by the infrared emission. The scale is identical to luminosity: 1 makes it visible only from the same location; 2 makes it visible from a neighboring position; and so on.


    invisibility var (atom)

    See also:
    invisibility setting (verb)
    opacity var (atom)
    see_invisible var (mob)
    sight var (mob)
    view proc
    Default value:
    0
    Possible values:
    0 to 101

    This determines the object's level of invisibility. The corresponding mob variable see_invisible controls the maximum level of invisibility that the mob may see.

    A value of 101 is absolutely invisible, no matter what, and it is filtered from all lists of possible values for verb arguments. This is intended for objects that exist purely for some internal purpose, such as "verb containers".


    layer var (atom)

    See also:
    overlays var (atom)
    z var (atom)
    map_format var (world)
    BACKGROUND_LAYER
    EFFECTS_LAYER
    TOPDOWN_LAYER
    Default value:
    1 (AREA_LAYER)
    2 (TURF_LAYER)
    3 (OBJ_LAYER)
    4 (MOB_LAYER)

    This numerical value determines the layer in which the object is drawn on the map. By default, the order is area, turf, obj, mob, followed by missiles and images (in FLY_LAYER, which is 5).

    Example:

    turf archway layer = MOB_LAYER+1 //overhead

    When making objects to be used as graphical overlays, you should also be aware of the special FLOAT_LAYER value. This causes the overlay (or underlay) to be in the same drawing layer as the base object, no matter how that layer changes after the addition of the overlay. Otherwise, the overlay object's own drawing layer is used.

    The actual drawing order of icons may change depending on world.map_format. An isometric map for instance has to display tiles that are "closer" to the viewer in front of tiles that are in the back, so the layer var takes a backseat to the needs of the map. If you use the TOPDOWN_MAP or TILED_ICON_MAP map formats, the layer is more important.

    If you are using a world.map_format that does not display topdown, such as ISOMETRIC_MAP or SIDE_MAP, then you can use a special layer for showing certain portions of the map in topdown mode. For those parts of the map, you can add TOPDOWN_LAYER to every atom's layer to make the atom appear in topdown mode. This is for special cases, like for instance a battle map in an RPG, where a regular topdown view is preferable to the special mapping used by the rest of the game. It is recommended that you use TOPDoWN_LAYER with every atom in that portion of the map, since topdown and isometric maps for instance don't mix. If you use TOPDOWN_LAYER, it is best to use a square size in world.icon_size if any of these atoms will be moving around.

    Another special layer, EFFECTS_LAYER, is also available in non-topdown mode. Icons that use this layer will display above icons that don't. TOPDOWN_LAYER will then display above that. This layer is useful for situations such as using a floating name or health meter overlay on a mob in isometric mode. When using EFFECTS_LAYER, other icons on the regular map won't cover the overlay.

    Finally there is BACKGROUND_LAYER which is also available when using a non-topdown map_format. Adding this to an atom's layer will make it appear below any atoms that do not use BACKGROUND_LAYER.


    loc var (atom)

    See also:
    contents list var (atom)
    x var (atom)
    y var (atom)
    z var (atom)
    Default value:
    The location of the object or null if there is none.

    The container is always an atom (or null). For areas, this value is always null, since an area may not be contained by any other object.


    luminosity var (atom)

    Default value:
    0
    1 (areas)

    This sets the object's luminosity (how far it casts light). It must be an integer in the range 0 to 6.

    Areas are a little different. Any non-zero value in an area results in all objects within the area being bathed in light.


    maptext var (atom)

    See also:
    maptext_width var (atom)
    maptext_height var (atom)
    overlays var (atom)
    image objects
    pixel_x var (atom)
    pixel_y var (atom)
    pixel_z var (atom)
    Default value:
    null

    This is optional text that will be displayed in the same position as the atom. If an atom has both an icon and maptext, the text will be displayed in front of the icon. Usually however, this is something that would be added to an overlay or image object, which can then be positioned with pixel offsets.

    Map text is constrained to the bounds set by maptext_width and maptext_height, which default to a single icon in size.

    Text can use HTML and CSS, mostly the same limited subset supported by regular text output, and different styles can be used in the same block of text. In addition, alpha colors can also be used, by specifying a color as #rrggbbaa instead of just #rrggbb. (Alpha transparency will be ignored when the map is drawn without hardware rendering, so anything below 50% opacity is not displayed in those cases.)


    maptext_width var (atom)

    See also:
    maptext var (atom)
    maptext_height var (atom)
    icon_size var (world)
    Default value:
    32 (depends on world.icon_size)

    This is the width of the text shown in the maptext var. By default, it uses the icon width provided in world.icon_size.


    maptext_height var (atom)

    See also:
    maptext var (atom)
    maptext_width var (atom)
    icon_size var (world)
    map_format var (world)
    Default value:
    32 (depends on world.icon_size)

    This is the height of the text shown in the maptext var. The default value depends on world.icon_size and world.map_format. In a topdown (default) or tiled map_format, the icon height is used. In other map views, tile "footprints" are square and height is irrelevant, so the default will be the icon width instead.)


    mouse_drag_pointer var (atom)

    See also:
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    mouse_drop_pointer var (atom)
    mouse_drop_zone var (atom)
    mouse_over_pointer var (atom)
    mouse_pointer_icon var (client)
    Default value:
    MOUSE_INACTIVE_POINTER (0)

    This defines how the mouse looks when dragging this object. Assigning this to MOUSE_ACTIVE_POINTER (1) enables the default dragging indicator.

    This variable may also be assigned to any of the other built-in mouse pointers, or a custom icon or icon state. If an icon state is specified, this is applied against the object's main icon to find a custom pointer.

    Note that all mouse pointers are purely visual indicators. They do not effect what objects may actually be manipulated with the mouse. You control all of the real behavior in the associated procedures.


    mouse_drop_pointer var (atom)

    See also:
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    mouse_drop_pointer var (atom)
    mouse_drop_zone var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    mouse_pointer_icon var (client)
    Default value:
    MOUSE_ACTIVE_POINTER (1)

    This defines how the mouse looks when dragging this object over another object that has mouse_drop_zone set. The default value enables the addition of a standard "droppable" indicator to whatever mouse_drag_pointer is (unless mouse_drag_pointer is turned off).

    This variable may also be assigned to any of the other built-in mouse pointers, or a custom icon or icon state. If an icon state is specified, this is applied against the object's main icon to find a custom pointer.

    Note that all mouse pointers are purely visual indicators. They do not effect what objects may actually be manipulated with the mouse. You control all of the real behavior in the associated procedures.


    mouse_drop_zone var (atom)

    See also:
    MouseDrag proc (atom)
    MouseDrop proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    mouse_pointer_icon var (client)
    Default value:
    0

    Setting this to 1 indicates that this object is a valid site on which to drop other objects. While dragging, mouse_drop_cursor of the object being dragged will become active in this case. Note that this is a purely visual effect. It does not control what the user may do with the mouse. You control the real behavior with the associated procedures.


    mouse_opacity var (atom)

    See also:
    mouse control
    Default value:
    1
    Possible values:
    0 //transparent to mouse
    1 //opaque where icon is also opaque
    2 //completely opaque

    This may be used to control how mouse operations on an object are interpreted. A click or mouse movement over an object's icon normally applies to that object only if it is the top-most object that is not transparent at the position of the mouse. Setting mouse_opacity to 0 would cause the object to be ignored completely, and setting it to 2 causes it to always be chosen over any lower-level objects, regardless of the transparency of its icon.


    mouse_over_pointer var (atom)

    See also:
    Click proc (atom)
    MouseEntered proc (atom)
    MouseExited proc (atom)
    MouseMove proc (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_pointer var (atom)
    mouse_drop_zone var (atom)
    mouse_opacity var (atom)
    mouse_pointer_icon var (client)
    Default value:
    MOUSE_INACTIVE_POINTER (0)

    This defines how the mouse looks when no buttons are pressed and it is held over this object. Assigning this to MOUSE_ACTIVE_POINTER (1) enables the default indicator that there is something special under the mouse (crosshairs).

    This variable may also be assigned to any of the other built-in mouse pointers, or a custom icon or icon state. If an icon state is specified, this is applied against the object's main icon to find a custom pointer.

    Note that all mouse pointers are purely visual indicators. They do not effect what objects may actually be manipulated with the mouse. You control all of the real behavior in the associated procedures.


    name var (atom)

    See also:
    gender var (atom)
    Default value:
    The name of the object type with underscores converted to spaces.

    opacity var (atom)

    Default value:
    0

    This turns the object's opacity on or off (1 or 0). Opaque objects block light.


    overlays var (atom)

    See also:
    icon var (atom)
    layer var (atom)
    list
    underlays var (atom)
    Default value:
    empty list

    This is a list of icons which are displayed on top of the object's main icon.

    The individual items in the list may not be directly accessed, since they are stored in a special internal format. However, the list operators +=, -=, and the procedures Add, Remove, and Cut work normally.

    Example:

    turf/verb/AddOverlay(I as icon) overlays += I turf/verb/RemoveOverlay(I as icon) overlays -= I

    The data types that may be used as overlays are icons, icon states (text strings), objects, and object types. When an icon state is used, the corresponding image in the object's icon is displayed. When another object is used as an overlay, a static "snapshot" of the object is taken at the time when the overlay is created. Future changes to the object will not change the appearance of the overlay.

    Overlays have their own independent drawing layer. It is normally the special value FLOAT_LAYER, which makes them float above the base object. If the overlay is a snapshot of another object, the drawing layer of that object is used. The important advantage of using FLOAT_LAYER is that if the layer of the base object changes, the overlays will move with it into the new layer.

    Any negative number may be used in place of FLOAT_LAYER (which happens to be -1). They all cause the same "floating" behavior. However, the overlays are ordered amongst themselves according to their own relative layer values (-2 below -1 and so on). This may be useful if you have several classes of overlays that should always appear in a certain order, because you would not have to worry about the order in which you add them to the list.

    Example:

    var/const ARMOR_LAYER = FLOAT_LAYER-1 CLOTHES_LAYER = FLOAT_LAYER-2 obj/overlay armor icon = 'armor.dmi' layer = ARMOR_LAYER clothes icon = 'clothes.dmi' layer = CLOTHES_LAYER mob/verb wear_clothes() overlays += /obj/overlay/clothes wear_armor() overlays += /obj/overlay/armor remove_clothes() overlays -= /obj/overlay/clothes remove_armor() overlays -= /obj/overlay/armor

    That example used object types, but you can use instances of objects as well. Rather than using different "float" layers, you can also just make your own list of overlays with the order you want and assign that to the actual overlays list.

    Example:

    mob/var boots clothes armor mob/proc ShowOverlays() var/L[0] if(boots) L += boots if(clothes) L += clothes if(armor) L += armor overlays = L

    override var (atom)

    Default value:
    0

    Currently this only applies to images.

    If you attach an image to an atom, normally it is seen only in addition to the atom's regular icon. If the image's override var is 1, it will be seen in place of the original atom (and its overlays).

    Presently, flick() will not affect an image.


    pixel_x var (atom)

    See also:
    animate_movement var (movable atoms)
    glide_size var (movable atoms)
    pixel_y var (atom)
    pixel_z var (atom)
    icon_size var (world)
    map_format var (world)
    Pixel movement
    Default value:
    0

    This displaces the object's icon on the x-axis by the specified number of pixels. In a project with a standard 32x32 tile size, this can range from -32 to +32. (You can get away with larger displacements, but they are not guaranteed to work for objects off the edge of the map.)

    Since overlays and images can each have their own additional displacements, this makes it possible to create visual effects that extend beyond the object's own cell in the turf grid, but which automatically move around with the object.

    This effect is purely visual and does not influence such things as movement bumping or view() range calculations.


    pixel_y var (atom)

    See also:
    animate_movement var (movable atoms)
    glide_size var (movable atoms)
    pixel_x var (atom)
    pixel_z var (atom)
    icon_size var (world)
    map_format var (world)
    Pixel movement
    Default value:
    0

    This displaces the object's icon on the y-axis by the specified number of pixels. In a project with a standard 32x32 tile size, this can range from -32 to +32. (You can get away with larger displacements, but they are not guaranteed to work for objects off the edge of the map.)

    Since overlays and images can each have their own additional displacements, this makes it possible to create visual effects that extend beyond the object's own cell in the turf grid, but which automatically move around with the object.

    This effect is purely visual and does not influence such things as movement bumping or view() range calculations.


    pixel_z var (atom)

    See also:
    animate_movement var (movable atoms)
    glide_size var (movable atoms)
    pixel_x var (atom)
    pixel_y var (atom)
    icon_size var (world)
    map_format var (world)
    Default value:
    0

    This displaces the object's icon vertically by the specified number of pixels. This is meant to be used in situations where world.map_format is used to display something other than a top-down form, for instance in an isometric or side-view display. In a top-down mode pixel_z behaves the same as pixel_y, except that it does not rotate with changes to client.dir.

    Since overlays and images can each have their own additional displacements, this makes it possible to create visual effects that extend beyond the object's own cell in the turf grid, but which automatically move around with the object.

    This effect is purely visual and does not influence such things as movement bumping or view() range calculations.


    suffix var (atom)

    Default value:
    null

    This is an optional text string that follows the object's name in the stat panels. For example, items in an inventory list are displayed as an icon, a name, and a suffix.


    text var (atom)

    Default value:
    The first letter of the object's name.

    This is the character used to represent the object on text clients.

    Entering several characters produces a text movie (the state of the art!). In that case, each character is displayed for a 10th of a second.

    HTML tags in the text can be used to modify the colors of the text characters. As a convenience, the <font> tag may include a bgcolor attribute, so you don't have to do a CSS style setting to accomplish the same thing.

    Example:

    world maxx = 10 maxy = 10 area text = "<font bgcolor=blue> " turf text = "<font color=#F00>....<font color=#C00>.."

    The example above produces a map with a blue background (from the area) and turfs (depicted by ".") that flash from bright red to a shorter span of light red.

    Note that in order to see text icons, the user must switch to the text map in Dream Seeker. If your DM code never does anything with the icon variable, then this is the default configuration. Such applications are known as advanced iconic text games:)


    transform var (atom)

    See also:
    vars (atom)
    matrix

    An atom can be made to appear rotated, scaled, and/or translated (moved) by using affine transforms. This takes a matrix and multiplies the x and y positions of the icon's corners like so:

    a d 0 x y 1 * b e 0 = x' y' 1 c f 1

    This is equivalent to:

    x' = a*x + b*y + c y' = d*x + e*y + f

    You do not need to understand matrix math to use transforms, because you can use the matrix datum to do this for you.

    Transformations are relative to the center of the icon. They do not apply to maptext.

    Examples:

    // Rotate the atom by 45 clockwise src.transform = turn(src.transform, 45) // OR var/matrix/M = matrix() M.Turn(45) src.transform = M // Scale the atom by 2x2 src.transform *= 2 // OR var/matrix/M = matrix() M.Scale(2,2) src.transform = M

    Whenever you read the atom.transform var, you will get a copy of the atom's current transformation. Whenever you assign a value to the var, you will update the transformation.

    Assigning null to atom.transform will revert the atom to using no transformation at all. It is also legal to assign a list with six values, which is equivalent to using a matrix.


    underlays var (atom)

    See also:
    icon var (atom)
    list
    overlays var (atom)
    Default value:
    empty list

    This is a list of icons which are displayed underneath the object's main icon.

    The individual items in the list may not be directly accessed, since they are stored in a special internal format. However, the list operators +=, -=, and the procedures Add, Remove, and Cut work normally.

    Example:

    turf/verb/AddUnderlay(I as icon) underlays += I turf/verb/RemoveUnderlay(I as icon) underlays -= I

    The data types that may be used as underlays are icons, icon states (text strings), objects, and object types. When an icon state is used, the corresponding image in the object's icon is displayed. When another object is used as an underlay, a static "snapshot" of that object is taken at the time when the underlay is created. Future changes to the object will not change the appearance of the underlay.

    Underlays have their own independent drawing layer. It is normally the special value FLOAT_LAYER, which makes them float directly below the base object. If the underlay is a snapshot of another object, the drawing layer of that object is used.

    See the discussion of FLOAT_LAYER for overlays, because the same applies here.


    verbs list var (atom)

    See also:
    list
    typesof proc
    Default value:
    The list of verbs defined for the object's prototype.

    This is a list of the object's verbs. Initially, it contains all of the verbs defined in the prototype. It may be used to add and remove verbs at runtime.

    Note that this variable is not automatically saved when the object is written to a savefile. That behavior may change in the future. In the mean time, you must save any necessary changes yourself or they will not be preserved when the object is loaded.

    Example:

    mob/proc/kazaam() usr << "Kazaam!" mob/verb/add_kazaam() verbs += /mob/proc/kazaam mob/verb/remove_kazaam() verbs -= /mob/proc/kazaam

    x var (atom)

    See also:
    loc var (atom)
    Default value:
    The x coordinate of the object on the map.

    You may assign the coordinates of movable objects (mobs and objs), but this is not advisable. It is better to compute the new location (with locate()) and move them to that. Then you can use the normal Move() procedure, which enables all the normal movement behavior.

    For areas that are on the map, this is the coordinate of the turf with the lowest z, y, and x coordinate (in that order) that is contained by the area.


    y var (atom)

    See also:
    loc var (atom)
    Default value:
    The y coordinate of the object on the map.

    You may assign the coordinates of movable objects (mobs and objs), but this is not advisable. It is better to compute the new location (with locate()) and move them to that. Then you can use the normal Move() procedure, which enables all the normal movement behavior.

    For areas that are on the map, this is the coordinate of the turf with the lowest z, y, and x coordinate (in that order) that is contained by the area.


    z var (atom)

    See also:
    layer var (atom)
    loc var (atom)
    Default value:
    The z coordinate of the object on the map.

    The z coordinate is how objects move between maps. When you include several maps in a project, they are placed on different z levels so that the full map is a single 3-dimensional space. It is also possible for a single map file to contain multiple z levels.

    Do not confuse this with drawing layer. The z coordinate moves an object between different maps. The layer variable determines the order in which an object is drawn graphically relative to other objects at the same position on the map.

    You may assign the coordinates of movable objects (mobs and objs), but this is not advisable. It is better to compute the new location (with locate()) and move them to that. Then you can use the normal Move() procedure, which enables all the normal movement behavior.

    For areas that are on the map, this is the coordinate of the turf with the lowest z, y, and x coordinate (in that order) that is contained by the area.


    client

    See also:
    client var (mob)
    key var (mob)
    procs (client)
    vars (client)

    Each connected player has a corresponding client object. It has variables and procedures which control aspects of player input/output. This object is also responsible for linking the player up to a mob.

    The client can be reassigned from its original mob M to a new mob N by setting N.client = M.client. This process disconnects the player from M (calling M.Logout()) and connects the player to N (calling N.Login()). Setting the mob's key has the same effect.

    Additional vars, procs, and verbs may be added to the client in order to give the player properties that are independent of the mob.


    procs (client)

    Built-in client procs:

    client/proc
    AllowUpload
    Center
    CheckPassport
    Click
    Command
    DblClick
    Del
    East
    Export
    Import
    IsByondMember
    MouseDown
    MouseDrag
    MouseDrop
    MouseEntered
    MouseExited
    MouseMove
    MouseUp
    Move
    New
    North
    Northeast
    Northwest
    SendPage
    South
    Southeast
    Southwest
    Stat
    Topic
    West

    AllowUpload proc (client)

    See also:
    input proc
    Format:
    AllowUpload(filename, filelength)
    When:
    Called when the player attempts to upload a file to the server, through input() or a command.
    Default action:
    Allows the upload by returning 1.

    The client who owns this proc (src) is the one trying to upload the file. If this proc returns a true value, the upload will be allowed. Otherwise, it will be rejected.

    Example:

    client AllowUpload(filename, filelength) if(filelength >= 524288) // 512K (0.5M) src << "[filename] is too big to upload!" return 0 return 1

    Center proc (client)

    See also:
    walk proc
    Format:
    Center()
    When:
    Called when the player presses the "center" key or cursor.
    Default action:
    Cancels any automated movement by calling walk(usr,0).

    CheckPassport proc (client)

    Format:
    CheckPassport(passport_identifier)
    Args:
    passport_identifier: a text string assigned to you by BYOND Hub.

    This built-in procedure checks to see if the user is subscribed to a particular BYOND Hub entry. If the user is subscribed, the result is the number of days left (rounded up) on their subscription, or -1 for lifetime subscribers.

    Example:

    world hub = "My.Hub" //change this to your own hub entry mob/var full_access mob/Login() if(client.CheckPassport("0123456789abcdef")) full_access = 1 else src << "For full access, <a href=\ 'http://www.byond.com/hub/[world.hub]' >subscribe</a>!" return ..()

    Note that in general the value of world.hub has nothing to do with the passport you happen to check. This example assumes the passport number belongs to world.hub just for the purpose of forwarding the user to the appropriate subscription page.


    Click proc (client)

    See also:
    Click proc (atom)
    DblClick proc (client)
    MouseDown proc (client)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (client)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    Click(object,location,control,params)
    When:
    Called when the player clicks on the map or in the stat panels.
    Args:
    object: the object clicked
    location: the client stat panel, location (turf) of object on map, grid cell, or other control-specific info
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.Click(location,control,params).

    Example:

    client Click(O) usr << "You clicked [O]" ..() // do default action

    Note that due to network lag, it is possible when clicking on moving objects for the location of those objects to have changed by the time the Click() proc is executed. That is the reason for the location argument. It tells you where the click originally took place.


    Command proc (client)

    Format:
    Command(command as command_text)
    When:
    Called when the player types in something that is not understood as a valid command, or if the player is connected via telnet.
    Default action:
    None.

    If this proc is used, players will be able to connect to your world via telnet. All telnet users' commands are routed through this proc instead of being parsed into verbs. Players who join the world through Dream Seeker will have their commands parsed as verbs first, and those commands will end up here only if there is no applicable verb.

    Note that text received by this proc is not interpreted beforehand, so quotes " and backslashses \ should come through unaltered.

    This proc is primarily useful if you want to handle parsing yourself (like for a MUD), or if your world is a chat server and verbs are not used much.


    DblClick proc (client)

    See also:
    Click proc (client)
    DblClick proc (atom)
    MouseDown proc (client)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (client)
    mouse_opacity var (atom)
    mouse_over_pointer var (atom)
    show_popup_menus var (client)
    Format:
    DblClick(object,location,control,params)
    When:
    Called when the player double-clicks on the map or in the stat panels.
    Args:
    object: the object double-clicked
    location: the client stat panel, location (turf) of object on map, grid cell, or other control-specific info
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.DblClick(location,control,params).

    Example:

    client DblClick(O) usr << "You double-clicked [O]" ..() // do default action

    Note that due to network lag, it is possible when clicking on moving objects for the location of those objects to have changed by the time the DblClick() proc is executed. That is the reason for the location argument. It tells you where the click originally took place.


    Del proc (client)

    See also:
    Logout proc (mob)
    Format:
    Del()
    When:
    Called when the player disconnects from the world.
    Default action:
    If the player is connected to a mob, call mob.Logout() to disconnect. If the player's connection to the world is still not dead, kill it.

    Note that this does not automatically delete the player's mob. If you want to do that, you could do so in mob.Logout().


    East proc (client)

    See also:
    Move proc (client)
    Format:
    East()
    Returns:
    1 on success; 0 on failure.
    When:
    Called when the player presses the "right" key or cursor.
    Default action:
    Calls src.Move() towards the east.

    Export proc (client)

    See also:
    Import proc (client)
    New proc (client)
    hub var (world)
    savefile
    Format:
    client.Export(file)
    Args:
    file: file to send to client

    This stores the file on the user's computer in a special location unique to each registered world.hub setting. This is most useful for writing a client-side savefile, but any type of file may be stored. The purpose of this is to exchange information between different worlds running under the same hub path.

    When a file is exported to the player's computer, it replaces any previous file stored by a game with the same world.hub value. This should not be used for anything requiring high security, because any other world could make use of the same hub path and access the file. It is also possible for the user to tinker with the file, since it resides on their computer.

    To delete the client-side file completely, call client.Export() with no argument at all.

    Example:

    mob/verb/save() var/savefile/F = new() F << usr //write the player's mob usr.client.Export(F) client/New() var/client_file = Import() if(client_file) var/savefile/F = new(client_file) //open it as a savefile F >> usr //read the player's mob return ..()

    Import proc (client)

    See also:
    Export proc (client)
    New proc (client)
    savefile
    Format:
    client.Import(Query)
    Args:
    Query: optional query parameters

    When no query parameters are given, this returns the client-side file last exported with client.Export(). This comes as an entry in the resource cache, which can be opened as a savefile among other things. If there is no file, null is returned. For an example, see client.Export.

    When there are query parameters, these may be used to import a file from some alternate source. Currently this is not supported.


    IsByondMember proc (client)

    Format:
    IsByondMember()
    Args:
    None.

    This built-in procedure checks to see if the user is a BYOND Member. Use it to give special in-game rewards to those who support BYOND.

    If the user is a Member, the result is the number of days left (rounded up) on their Membership, or -1 for lifetime Members.

    Example:

    mob/var special_features mob/Login() if(client.IsByondMember()) special_features = 1 else src << "For special features, <a href=\ 'http://members.byond.com/' >become a BYOND Member</a>!" return ..()

    MouseDown proc (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDown proc (atom)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (client)
    mouse_opacity var (atom)
    mouse_pointer_icon var (client)
    show_popup_menus var (client)
    Format:
    MouseDown(object,location,control,params)
    Args:
    object: the object under the mouse pointer
    location: the turf, stat panel, grid cell, etc. containing the object where it was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.MouseDown(location,control,params).

    This is called when the a mouse button is pressed while pointing to the object. Note that MouseUp() will always be called after MouseDown() is called, even if over empty space. That means object and location may be null.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Most operations can be done through Click(), DblClick(), and MouseDrop(). The other procedures are simply available for completeness.

    Note: In BYOND 3.5 this procedure took four different arguments: object, location, icon_x, and icon_y. Since icon_x and icon_y have been replaced, old code will need to be modified. Games compiled before this change will still work normally.


    MouseDrag proc (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDown proc (client)
    MouseDrag proc (atom)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (client)
    mouse_pointer_icon var (client)
    show_popup_menus var (client)
    Format:
    MouseDrag(src_object,over_object,src_location,over_location,src_control,over_control,params)
    Args:
    src_object: the object being dragged
    over_object: the object under the mouse pointer
    src_location: the turf, stat panel, grid cell, etc. from where the src object was dragged
    over_location: the turf, stat panel, grid cell, etc. containing the object under the mouse pointer
    src_control: The id of the skin control the object was dragged from
    over_control: The id of the skin control the object was dragged over
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.MouseDrag(over_object,src_location,over_location,src_control,over_control,params).

    This is called while dragging an object by pressing and holding the left mouse button over the object and moving the mouse. The over_object may be null if dragging over a stat panel or over other empty space.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Most operations can be done through Click(), DblClick(), and MouseDrop(). The other procedures are simply available for completeness.


    MouseDrop proc (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDown proc (client)
    MouseDrag proc (client)
    MouseDrop proc (atom)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (client)
    mouse_pointer_icon var (client)
    show_popup_menus var (client)
    Format:
    MouseDrop(src_object,over_object,src_location,over_location,src_control,over_control,params)
    Args:
    src_object: the object being dropped
    over_object: the object under the mouse pointer
    src_location: the turf, stat panel, grid cell, etc. from where the src object was dragged
    over_location: the turf, stat panel, grid cell, etc. containing the object under the mouse pointer
    src_control: The id of the skin control the object was dragged from
    over_control: The id of the skin control the object was dropped onto
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.MouseDrop(over_object,src_location,over_location,src_control,over_control,params).

    This is called when a mouse button is released after dragging an object. The over_object may be null if dropping over a stat panel or over other empty space.


    MouseEntered proc (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (atom)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (client)
    mouse_opacity var (atom)
    mouse_pointer_icon var (client)
    show_popup_menus var (client)
    Format:
    MouseEntered(object,location,control,params)
    Args:
    object: the object under the mouse pointer
    location: the turf, stat panel, grid cell, etc. containing the object where it was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.MouseEntered(location,control,params).

    This is called when no mouse buttons are pressed while pointing to the object.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Defining it on only the objects that require it reduces overhead.


    MouseExited proc (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (atom)
    MouseMove proc (client)
    MouseUp proc (client)
    mouse_opacity var (atom)
    mouse_pointer_icon var (client)
    show_popup_menus var (client)
    Format:
    MouseExited(object,location,control,params)
    Args:
    object: the object under the mouse pointer
    location: the turf, stat panel, grid cell, etc. containing the object where it was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.MouseExited(location,control,params).

    This is called when the mouse moves off of an object.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Defining it on only the objects that require it reduces overhead.


    MouseMove proc (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (atom)
    MouseUp proc (client)
    mouse_opacity var (atom)
    mouse_pointer_icon var (client)
    show_popup_menus var (client)
    Format:
    MouseMove(object,location,control,params)
    Args:
    object: the object under the mouse pointer
    location: the turf, stat panel, grid cell, etc. containing the object where it was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.MouseMove(location,control,params).

    This is called when no mouse buttons are pressed while pointing to the object, and the mouse has moved. The first time the mouse moves over the object, MouseEntered() is called instead.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Defining it on only the objects that require it reduces overhead.


    MouseUp proc (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDown proc (client)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (atom)
    mouse_opacity var (atom)
    mouse_pointer_icon var (client)
    show_popup_menus var (client)
    Format:
    MouseUp(object,location,control,params)
    Args:
    object: the object under the mouse pointer
    location: the turf, stat panel, grid cell, etc. containing the object where it was clicked
    control: the name of the skin control involved
    params: other parameters including mouse/keyboard flags, icon offsets, etc.; see mouse control
    Default action:
    Call object.MouseUp(location,control,params).

    This is called when a mouse button is released while pointing to an object.

    Don't define this unless you need it, because it generates extra communication that is otherwise avoided. Most operations can be done through Click(), DblClick(), and MouseDrop(). The other procedures are simply available for completeness.

    Note: In BYOND 3.5 this procedure took four different arguments: object, location, icon_x, and icon_y. Since icon_x and icon_y have been replaced, old code will need to be modified. Games compiled before this change will still work normally.


    Move proc (client)

    See also:
    East proc (client)
    Move proc (movable atom)
    North proc (client)
    Northeast proc (client)
    Northwest proc (client)
    South proc (client)
    Southeast proc (client)
    Southwest proc (client)
    West proc (client)
    Format:
    Move(loc,dir)
    Returns:
    1 on success; 0 on failure
    When:
    Called by the direction procs.
    Default action:
    Calls src.mob.Move(). Also cancels any automated movement by calling walk(usr,0).

    New proc (client)

    See also:
    Export proc (client)
    Import proc (client)
    Login proc (mob)
    New proc (datum)
    Topic proc (client)
    mob var (world)
    savefile
    Format:
    New(TopicData)
    Returns:
    The newly connected mob, client.mob, or null to disallow the connection.
    When:
    Called when the player first tries to connect to the world.
    Args:
    usr: The mob in the world with the same key as the player, if it exists.
    TopicData: If the player accessed the world with a "connection topic", this is the topic text. Otherwise it is null.
    Default action:
    Look for an existing mob with the same key as the player. If found, connect the player to that mob (mob.Login()). Otherwise, look for a prototype mob with the same key as the player. If found, create a mob of that type and connect the player to it. Otherwise, create a mob of type world.mob, give it the same name and gender as the player's key, and connect the player to it. If TopicData is not null, call client.Topic(TopicData). Finally, the player's mob is returned.

    This is a fairly low-level procedure that you would only want to override if you cannot accomplish the same thing in mob/Login() or mob/New(). One reason to override client/New() is if player mobs are created from a savefile. In that case, you don't need a temporary mob to be created first.

    Example:

    client/New() if(usr) return ..() //reconnecting to existing mob else var/player_sav = "players/[ckey].sav" if(length(file(player_sav))) //if player savefile exists var/savefile/F = new(player_sav) //open it F >> usr //create saved mob return ..() //creates a new mob if necessary mob/Logout() var/player_sav = "players/[ckey].sav" var/savefile/F = new(player_sav) F << src del src

    If you want to do any user-interaction before loading the saved mob, you will have to create a temporary mob first in order to interact with the player. In that case, you are better off doing things in mob/Login(), rather than client/New().

    Note that for the above example to work, you must make proper use of the tmp flag when defining new object variables. Otherwise, this can end up sucking large portions of your world into each player savefile, which can have all sorts of unexpected consequences!


    North proc (client)

    See also:
    Move proc (client)
    Format:
    North()
    Returns:
    1 on success; 0 on failure.
    When:
    Called when the player presses the "up" key or cursor.
    Default action:
    Calls src.Move() towards the north.

    Northeast proc (client)

    See also:
    Move proc (client)
    Format:
    Northeast()
    Returns:
    1 on success; 0 on failure.
    When:
    Called when the player presses the "up-right" key or cursor.
    Default action:
    Calls src.Move() towards the northeast.

    Northwest proc (client)

    See also:
    Move proc (client)
    Format:
    Northwest()
    Returns:
    Returns 1 on success; 0 on failure.
    When:
    Called when the player presses the "up-left" key or cursor.
    Default action:
    Calls src.Move() towards the northwest.

    SendPage proc (client)

    Format:
    SendPage(msg,recipient,options)
    Returns:
    Returns number of recipients successfully contacted.
    Args:
    msg: text to send
    recipient: key or list of keys to page
    options: text string containing key=value options

    The user is prompted to authorize sending of the pager message. The recipient may easily respond or jump to the sender's location by clicking on the link in the pager message. The effect is identical to that of the sending a page through the Dream Seeker pager.

    The options are encoded in the same format read by text2params(). The valid options are:

    summon (0/1)
    If not included in the options, this is 0. If included in the options without assigning it to anything, it is 1. A value of 1 sends the recipient the sender's location so they can join by clicking on the message.
    email (0/1)
    If not included in the options, this is 0. If included in the options without assigning it to anything, it is 1. A value of 1 sends causes the message to be delivered as email. If this is not possible, it is delivered as a long-lived pager message. Normally, pager messages expire within a short time after being sent (half an hour).
    subject
    For email messages, this specifies the subject to use.

    South proc (client)

    See also:
    Move proc (client)
    Format:
    South()
    Returns:
    Returns 1 on success; 0 on failure.
    When:
    Called when the player presses the "down" key or cursor.
    Default action:
    Calls src.Move() towards the south.

    Southeast proc (client)

    See also:
    Move proc (client)
    Format:
    Southeast()
    Returns:
    1 on success; 0 on failure.
    When:
    Called when the player presses the "down-right" key or cursor.
    Default action:
    Calls src.Move() towards the southeast.

    Southwest proc (client)

    See also:
    Move proc (client)
    Format:
    Southwest()
    Returns:
    Returns 1 on success; 0 on failure.
    When:
    Called when the player presses the "down-left" key or cursor.
    Default action:
    Calls src.Move() towards the southwest.

    Stat proc (client)

    See also:
    Stat proc (atom)
    stat proc
    statobj var (client)
    statpanel proc
    statpanel var (client)
    Format:
    Stat()
    When:
    Called periodically by the client to update the stat window.
    Default action:
    Call statobj.Stat().

    If this procedure sleeps (or engages in some other waiting operation), it will not be called again until it finally returns. This allows you to effectively decrease the frequency of calls to the proc. You might want to do that if it is a fairly lengthy procedure, and frequent calls are slowing things down.

    To increase the frequency of stat updates, you can lower world.tick_lag.


    Topic proc (client)

    See also:
    New proc (client)
    Topic proc (datum)
    link proc
    ref text macro
    Format:
    Topic(href,href_list[],hsrc)
    When:
    Called when a player connects to a world with a "connection topic" or when the player runs a hyperlink in the current world by clicking one embedded in text or generated by the link() instruction.
    Args:
    href: The topic text (everything after the '?' in the full href).
    href_list: List of key/value pairs in href (produced from params2list(href)).
    hsrc: The object referenced by the "src" parameter in href or null if none.
    Default action:
    Call the hsrc object's own Topic() proc.

    The following example uses a very simple href value.

    Example:

    mob/Login() src << "Click <a href=?source>here</a> to download the source code." return ..() client/Topic(href) if(href == "source") usr << file("world.dm") usr << file("world.rsc") else ..()

    Be sure to call the default handler unless you want to prevent rerouting of topics to other objects. For security reasons, you might want to control which objects a player has access to, since a player could spoof a topic link containing any arbitrary object reference. (Never trust those sneaky players!)

    The next example demonstrates an href that gets handled by another object. This is how you would normally want to do things. It is best not to override client/Topic() (as in the example above) unless you need to intervene in the low-level details of routing the request to the right object.

    You specify the object that will handle the request by using a parameter called "src".

    Example:

    mob/Login() src << "Click <a href='?src=\ref[src];action=startgame'>here</a> to start." return ..() mob/Topic(href,href_list[]) switch(href_list["action"]) if("startgame") usr << "Starting game..." else return ..()

    Although it is slightly more complex, the use of the parameter list allows you to easily include extra data and new functionality. Just remember that the data in the list is always stored as text, so if you are expecting a number of an object, you must convert it yourself (with text2num(), locate(), or whatever).


    West proc (client)

    See also:
    Move proc (client)
    Format:
    West()
    Returns:
    Returns 1 on success; 0 on failure.
    When:
    Called when the player presses the "left" key or cursor.
    Default action:
    Calls src.Move() towards the west.

    vars (client)

    Built-in client vars:

    client/var
    address
    authenticate
    byond_version
    CGI
    ckey
    command_text
    connection
    control_freak
    computer_id
    default_verb_category
    dir
    edge_limit
    eye
    gender
    images
    inactivity
    key
    lazy_eye
    mob
    mouse_pointer_icon
    perspective
    pixel_x
    pixel_y
    pixel_z
    glide_size
    preload_rsc
    screen
    script
    show_map
    show_popup_menus var
    show_verb_panel
    statobj
    statpanel
    verbs
    view
    virtual_eye

    CGI var (client)

    In CGI mode, DreamDaemon is normally being executed by a web server and accessed by a web browser. The CGI object is an add-on to the basic client object for handling this case.

    The CGI object is defined and documented in a separate code library html/CGI.dm. You can find the current version at www.byond.com.


    address var (client)

    Default value:
    The network address of the player's client.

    This is a read-only value which contains the player's network address.


    authenticate var (client)

    This value may be set to 0 at compile-time to disable BYOND hub-based authentication of users. The default value is 1, which enables authentication. Hub authentication provides an additional level of assurance that the user is really the owner of the BYOND key in question.

    When a world requests certification, Dream Seeker generates a random password and passes it through the hub (for certification) to the world. The certificate is saved for faster access in the future and for protection against possible hub outages.

    Some applications do not depend on the validity of the user's identity. In that case, it would be more efficient to turn off the extra level of authentication. In other situations, the hub may not be available, such as from behind a firewall or on a LAN without internet access. In those cases, all hub access (including authentication) can be disabled by entering the command ".configuration hub-address none" in Dream Seeker.

    Connections to worlds on the same machine are not hub-authenticated to allow for convenient offline testing.


    byond_version var (client)

    See also:
    DM_VERSION macro
    byond_version var (world)
    system_type var (world)

    This is the version of BYOND being run by this client. A game designed to work around known bugs in older versions could use this to adapt its behavior accordingly. It is also possible to prevent players with much older versions from joining the game.


    ckey var (client)

    See also:
    ckey proc
    key var (client)

    This is a read-only value that is the canonical form of the player's key (ie the value returned by ckey()). Among other things, this could be used as a unique directory name in a server-side save file for storing player information. See the ckey() proc for an example.


    command_text (client)

    See also:
    arguments (verb)
    Skin reference
    macros (client script)
    Default value:
    null

    This text is placed onto the command line, to be followed by whatever the user may type. It is usually the name of a verb followed by a space, such as "say ". The user can clear this and enter a different command by hitting backspace, escape, delete, or '/'.

    (Note: In BYOND 4.0 this var is deprecated. The command parameter for an Input control can be set to !command which does the same thing. See the skin reference for details.)

    Example:

    client command_text = "say " verb/say(T as text) world << "[usr] says, '[T]'"

    It is also possible to turn on macro mode, in which each keypress executes a keyboard macro, by setting command_text to ".alt ". That stands for the Alt key, which can be used to execute macros in normal mode.

    This variable could also be used to create a specialized command prompt. For example, a traditional style MUD command-line could be implemented like this:

    Example:

    client command_text = "> " verb/command(C as command_text) set name = ">" usr << "Your command: [C]"

    This example uses the command_text input type, which accepts raw text, with no quoting, escaping, or translating, so that you can invent whatever syntax you want.


    computer_id var (client)

    Default value:
    A unique numerical identifier for the player's computer. The value is in text form.

    This is a read-only text value which contains a unique numerical identifier for the player's computer. Its primary purpose is to detect if players are connecting to a server with multiple accounts on the same machine, while still allowing for multiple accounts on the same network (eg, through a router).


    connection

    This is a read-only var describing the type of client that is connected.

    Possible values:
    "seeker" - The player is connected through Dream Seeker
    "telnet" - The player is connected through telnet
    "world" - The client is actually a world.Export() connection from another server
    "cgi" - The client is connected via CGI (irrelevant to most worlds)

    Other values may be supported in the future.

    An empty value means the connection type is unknown because a full handshake hasn't been completed yet.


    control_freak (client)

    See also:
    Skin reference
    macros (client script)
    Default value:
    0

    This var lets you set flags to turn off options that are normally present for the end user. You can combine these flags with the | operator. The value 1 is equivalent to CONTROL_FREAK_ALL and will disable everything.

    CONTROL_FREAK_ALL
    If this value is used, it affects all the options below.
    • User-defined macros may not be used.
    • Only the world's skin or the default BYOND skin will be loaded, not a user-customized version.
    • The Options & Messages window in Dream Seeker is inaccessible. It will only come up while first connecting to a remotely hosted world, or if a world takes a long time to load. The .options command will not make it appear.
    • The menu items from Options & Messages are unavailable in Dream Seeker's system menu.
    • The default F2 macro for the .screenshot command is turned off. The command is then only accessible through the skin you create.
    CONTROL_FREAK_SKIN
    Toggles the ability to create a custom version of the skin.
    CONTROL_FREAK_MACROS
    Toggles the ability to use and define custom macros.

    Using CONTROL_FREAK_ALL will default to disabling everything, and the other flags will reenable only the features you want. For example, CONTROL_FREAK_MACROS alone will disable the ability to use your own macros but nothing else. CONTROL_FREAK_ALL | CONTROL_FREAK_MACROS will disable everything except macros.

    This value can be changed at runtime. However any changes made at runtime will not affect users running old BYOND versions. Users whose versions only recognize "all enabled" or "all disabled" will have everything disabled if you use any value other than 0.

    Important: If you define your own skin for the world, and disable the ability to use a custom skin or user-defined macros, you must be sure to define any macros your world may need. For instance, arrow keys may be needed for movement.


    default_verb_category var (client)

    See also:
    category setting (verb)
    show_verb_panel var (client)
    Default value:
    "Commands"

    All verbs with category "" (the default value) are treated as though they had this category setting instead. In other words, this is the name of the panel that contains them. You could even turn that panel off by setting this value to null.


    dir var (client)

    Default value:
    NORTH

    This defines the relationship between the world's coordinate system and the player's screen. The default means that the player sees the map exactly as it was created (in the map-editor or at runtime). Changing it to one of the other directions causes the player to see the map as if it were rotated to that direction. This means that a player with client.dir = SOUTH would see the map inverted relative to a person with client.dir = NORTH. That's handy in two-player board games where you want both players to see their side in the same place.

    Note that this does not turn icons upside down! The map is rotated, but the icons on the map remain in their normal orientation.

    Movement keys are remapped so that a player with client.dir = SOUTH hitting the up arrow will generate a call to client.South() rather than the usual client.North().


    edge_limit var (client)

    See also:
    eye var (client)
    lazy_eye var (client)
    perspective var (client)
    view var (client)
    screen_loc var (movable atoms)
    Default value:
    null

    This value determines the limits that a client's eye will display. If client.perspective uses the EDGE_PERSPECTIVE flag, the view shouldn't scroll beyond the bounds set by edge_limit. If the bounds of edge_limit are as big as or smaller than the client's view, no scrolling will occur even if EDGE_PERSPECTIVE is not used. Normally this value is null, which provides freedom for the eye to move anywhere on the map. It may be changed to a text value describing the limits in more detail.

    The format is similar to atom.screen_loc which uses "[x1],[y1] to [x2],[y2]". It can also use directions such as "SOUTHWEST to NORTHEAST", which refer to the limits of the map.

    Example:

    area/house var/x1,x2,y1,y2 Entered(mob/M) if(ismob(M) && M.client) M.client.edge_limit = "[x1],[y1] to [x2],[y2]" Exited(mob/M) if(ismob(M) && M.client) M.client.edge_limit = null

    eye var (client)

    See also:
    edge_limit var (client)
    lazy_eye var (client)
    mob var (client)
    perspective var (client)
    glide_size var (client)
    view var (client)
    virtual_eye var (client)
    view var (world)
    step_x var (movable atom)
    step_y var (movable atom)
    Default value:
    The connected mob, client.mob.

    This value determines the center of the player's map. The default value simply means that the visible region is normally centered on the player's mob. Effects such as setting perspective to EDGE_PERSPECTIVE or using lazy_eye can move the map off-center temporarily. The eye is the ideal center, not necessarily the actual center; to find the actual center, use virtual_eye.

    The eye's step_x/y vars, if present, are also used to allow smooth scrolling of the map. These also obey lazy_eye and edge_limit.

    Note that the visibility of objects is still computed from the point of view of the mob rather than the eye. This allows the use of lazy_eye or similar effects that control the panning of the map while still having the player see only what the mob can see. To determine visibility from the eye, you can change the value of client.perspective.

    If a player connects to a new mob M, client.eye automatically changes to M.

    Example:

    client eye = locate(5,5,1)

    This fixes the center of the player's map at the turf coordinate (5,5,1). Since the eye is fixed, the map will not scroll even as the player's mob moves out of the visible range.


    gender var (client)

    See also:
    New proc (client)
    gender var (atom)
    key var (client)
    macros (text)

    This is the client's gender, which is an attribute of the player's key. By default, when a new mob is made for a player (in client.New()), the new mob gets the same name and gender as the player's key. This influences text macros like \he, which may expand to "it", "he", "she", or "they". Valid values are:

    "neuter" "male" "female" "plural"

    glide_size var (client)

    See also:
    eye var (client)
    glide_size var (movable atoms)
    Default value:
    0

    Deprecated. This setting has no impact when used with pixel movement. See Gliding for more details.

    This controls the number of pixels the map is moved in each step during scrolling of the map. The default value of 0 chooses automated control over this value, which generally results in a minimum step of 4 pixels that is increased when necessary to keep up with motion of the map.

    Be careful about using small step sizes. Icons with high contrast pixel-level detail can look pretty ugly when displaced by short distances.

    This was renamed from pixel_step_size.


    images var (client)

    See also:
    image objects
    image proc

    This is a list of images that are displayed to the user. The output operator is one way to add entries to this list. Deleting an image object will automatically remove it from the display, but if you want to retain an image (so other people can still see it), it can be removed by directly modifying this list.

    Example:

    var/image/I = new('image.dmi',usr) usr.client.images += I //display it sleep(50) usr.client.images -= I //remove it from the display Displaying the image can also be achieved like this: usr << I

    inactivity var (client)

    See also:
    tick_lag var (world)

    This is equal to the amount of time (in 10ths of seconds) since the player's last action (such as executing a verb, moving, clicking an object, or selecting a topic link). This value is reset to 0 after each new action so you can use it to determine the time that has passed since the last one.

    Example:

    mob/verb/inactivity() usr << "You have been inactive for [client.inactivity/10] seconds."

    key var (client)

    See also:
    key var (mob)
    Default value:
    The player's key identity.

    This is a read-only value that contains the player's key. Once the player is attached to a mob M, M.key == M.client.key.


    lazy_eye var (client)

    See also:
    view var (client)
    view var (world)
    Default value:
    0

    This is the maximum "lag" between client.eye and client.mob. The mob can stray up to this many tiles before the eye will move to keep it in view. The default value of 0 means that the eye always moves as the mob moves, keeping the mob at the center of the player's map.

    Setting this value to a non-zero value automatically initializes client.eye to client.mob.loc (or to the center of the full map if that is possible). Thereafter, client.eye will stray from the mob as it moves about the map, making one big jump to catch up whenever the mob gets out of range.

    Example:

    client lazy_eye = 5

    This setting allows client.mob to move onto the entire 11x11 visible region without changing the value of client.eye. The moment it steps out of this region, the entire region will shift 5 tiles in the direction of motion.

    You can assign lazy_eye to any value valid as a view size, so, for example, if you have a non-square setting for client.view, say, "17x11", you could apply a similar setting to lazy_eye. You can even make one dimension lazy and the other one strictly centered: "0x5".


    mob var (client)

    Default value:
    Determined in client.New(), by default world.mob.

    This is the mob to which the client is connected. The client and its connected mob have the following symmetry:

    client == mob.client client.mob == mob client.key == mob.key

    mouse_pointer_icon var (client)

    See also:
    Click proc (client)
    MouseDown proc (client)
    MouseDrag proc (client)
    MouseDrag proc (client)
    MouseUp proc (client)
    mouse_drag_pointer var (atom)
    mouse_drag_pointer var (atom)
    mouse_drop_zone var (atom)
    mouse_over_pointer var (atom)
    Default value:
    null

    This is an icon file (.dmi) containing custom mouse cursors to use in place of the standard ones. The different possible mouse states are distinguished by special icon state names:

    ""
    Activated when over empty space or an object with mouse_over_pointer = MOUSE_INACTIVE_POINTER.
    "over"
    Activated when over an object with mouse_over_pointer = MOUSE_ACTIVE_POINTER.
    "drag"
    Activated when dragging an object with mouse_drag_pointer = MOUSE_ACTIVE_POINTER.
    "drop"
    Activated when dragging an object over with mouse_drop_pointer = MOUSE_ACTIVE_POINTER and the object underneath has mouse_drop_zone set.
    "all"
    Always activated, no matter what the state of the mouse.

    perspective var (client)

    See also:
    eye var (client)
    mob var (client)
    Default value:
    MOB_PERSPECTIVE
    Possible values:
    • MOB_PERSPECTIVE
    • EYE_PERSPECTIVE
    • EDGE_PERSPECTIVE

    This controls the eye's apparent center and what can be seen by the client.

    EYE_PERSPECTIVE determines how visibility calculations are performed when client.eye and client.mob are different. Normally, visibility is done from the position of the mob, rather than from the eye (which is actually just the center of the map view). The alternative flag is MOB_PERSPECTIVE, the default.

    EDGE_PERSPECTIVE limits scrolling to the bounds of the map (1,1 to world.maxx,world.maxy), and does not keep the mob centered if it strays near the edge.

    The above values can be used together via the | operator.


    pixel_x var (client)

    See also:
    glide_size var (client)
    pixel_y var (client)
    pixel_z var (client)
    Default value:
    0

    This displaces the player's viewpoint on the x-axis by the specified number of pixels.


    pixel_y var (client)

    See also:
    glide_size var (client)
    pixel_x var (client)
    pixel_z var (client)
    Default value:
    0

    This displaces the player's viewpoint on the y-axis by the specified number of pixels.


    pixel_z var (client)

    See also:
    glide_size var (client)
    pixel_x var (client)
    pixel_y var (client)
    map_format var (world)
    Default value:
    0

    This displaces the player's viewpoint vertically by the specified number of pixels. This value is meant to be used when world.map_format is not set to a default top-down view.


    pixel_step_size var (client)

    Renamed to glide_size.


    preload_rsc var (client)

    Default value:
    1.

    This variable controls whether resource files (icons and sounds) are automatically downloaded by Dream Seeker when first connecting, or whether they should be downloaded as needed. Resource files are cached (in byond.rsc) for future use, so this should only affect people who have not played the game before or who have not played it for some time.

    The three possible settings are:

    0
    do not preload any resources
    1
    preload compiled-in resources only
    2
    preload all resources including those uploaded by players
    URL
    preload resources from specified file

    Preloading resource files will eliminate delays later on, but may cause a very long initial delay when logging in.

    Resources may also be distributed from a website to save bandwidth on the machine hosting the game. Simply zip up the .rsc file, upload it to a web site, and put the URL here.

    Example:

    client/preload_rsc = "http://dan.byond.com/mygame_rsc.zip"

    Instead of putting the .rsc file in the .zip, you can also put the individual resource files there. This would allow you to select specific files that you would like to be preloaded. For example, you could create a different resource package for different parts of the game world and assign client.preload_rsc dynamically as the player moves into each different area.

    Once Dream Seeker has downloaded a resource package, it caches it and will not download it again, even if you upload a new version of the file. This allows you to make small changes without forcing a complete refresh. Any files which are not found in the preload package are simply downloaded from the game server directly.

    If you want to force a complete refresh, simply change the name of the resource package. For example, you could put a version number in the name of the file: mygame_rsc_01.zip, mygame_rsc_02.zip, and so on.


    screen var (client)

    See also:
    HUD / screen objects
    screen_loc var (movable atoms)

    This is a list of objects that are displayed on the user's screen. The object's screen_loc variable controls where it appears (if it appears at all). This allows one to create the elements of a graphical user interface, with such features as buttons, drag/drop areas, and stat monitors.

    Screen objects (visible or otherwise) may also be used to make verbs available to users. To make them accessible, define verbs on the screen object like this:

    set src in usr.client.screen

    script var (client)

    See also:
    #include directive
    PASSWORD_TRIGGER (client script)
    URL (client script)
    aliases (client script)
    browser configuration
    command_text (client)
    macros (client script)
    style sheets
    style sheets (in scripts)
    Default value:
    none

    Client scripts are mini-programs used to configure the client. The language they use is called DM Script, and will undoubtedly expand in the future. Currently, client scripts can be used to define style sheets, command aliases, and macros. When executed directly by a player, they can also be used to specify an initial URL to open and a password trigger (for some ancient telnet worlds that don't suppress password echo).

    For the specific syntax of DM Script, see the relevant reference sections listed above.

    The client.script variable may be assigned to script code in a text string (double quotes) or in a file (single quotes). You can also simply include the file in your project or explicitly use the #include statement. Files containing DM Script should have the extension .dms.

    Example:

    client/script = "<STYLE>BODY {font: monospace}</STYLE>"

    This example selects a default monospace font for all output to the terminal.

    In addition to scripts loaded via client.script, the player may have client-side scripts. These are either called connection scripts or post-connection scripts depending on whether they are used to automatically connect to a world or whether they are executed automatically after connecting to a world. In either case, the player's scripts are always executed before the designer's client.script script, so style sheets from the designer have higher precedence by default.

    There are three post-connection client-side scripts for the three types of worlds the client can connect to: byond.dms, telnet.dms, and irc.dms. These are automatically executed if the player connects directly to a world without using a connection script to do so. The intention is to load any standard configurations such as style sheets and command aliases.


    PASSWORD_TRIGGER (client script)

    Format:
    #define PASSWORD_TRIGGER "assword:"

    This defines a special text trigger used to detect when the user is being prompted for a password in telnet mode. Most MUDs automatically suppress password echo, but if they do not, it is necessary to use this setting to hide it. Multiple triggers may be defined as necessary.

    The example above is more robust than the more polite version because it works whether they capitalize the 'P' or not...


    URL (client script)

    Format:
    #define URL "byond://byond.com:6000"

    Defining a URL in a script, specifies the world to connect to when the script is executed by the player. This is referred to as a connection script, because the player uses it to connect to a world. Other post-connection scripts such as byond.dms or a script loaded through client.script are only used to configure the client after it has connected to a world. In those cases, the URL setting has no effect.

    It is important to enclose the URL in double quotes. Otherwise, the // symbol would be mistaken for a comment.


    browser configuration

    See also:
    URL (client script)

    DM Script can be used to effectively make a hyperlink in a web document to a BYOND world. This is done by making a DM Script file that defines the desired URL. It need do nothing more than that. When a user clicks on the link in a web browser, DreamSeeker will pop up, execute the script, and connect to the specified URL.

    Some browsers may need to be configured to know what to do with a DM Script file. For example, in Netscape, you can add an entry to the list of helper applications. You should add a MIME type called 'application/x-dms' with the description 'DM Script' and the extension dms. Have this execute DreamSeeker with the .dms file as an argument.

    Example:

    myworld.dms

    /*If your browser shows you this, you either need to install BYOND (it's free!) from www.byond.com, or you need to configure your browser to execute DreamSeeker with DM Script (.dms) files. */ #define URL "byond://myworld"

    myworld.html

    <html> <head><title> Welcome to My World </title></head> <body> <p>You can connect to my world <a href=myworld.dms>here</a>. </body> </html>

    aliases (client script)

    See also:
    macros (client script)
    script var (client)
    verbs

    Command aliases have a syntax similar to verbs. They define a command and a series of arguments which can then be used to execute a new command. The most common use for this is in a telnet world like a MUD. By defining aliases corresponding to the MUD commands, the player can have primitive command expansion and help.

    The syntax of an alias definition is best illustrated by the following example:

    alias/say(msg as text) set desc = "speak your mind" return "say [msg]"

    As you can see, it is just like a verb. Alias have all the same properties as verbs, except the src setting is always equal to the player.

    The value returned by an alias is executed as a command. In telnet mode, the command to execute is often simply the same as the command that was entered (since the alias was only defined to provide command expansion and help). Since that is such a common case, the return value defaults to the alias name followed by each of the arguments. The example above, for instance, would have the same effect without an explicit return statement.

    Note that commands executed via an alias are never interpreted as aliases. Otherwise, examples such as the one above would result in an infinite loop.


    macros (client script)

    See also:
    aliases (client script)
    command_text (client)
    script var (client)
    verbs

    Macros are just like aliases, except that they are triggered by a single key (or combination of keys) instead of a full command. When a macro is executed, it returns a text string which is then executed as a command. So a macro is just a short-cut for entering a command.

    The following example illustrates the syntax for entering a typical set of macros.

    Example;

    macro i return "inventory" I return "inventory\nequipment" //multiple commands s return "say \..." //command to be edited

    style sheets (in scripts)

    See also:
    script var (client)
    style sheets

    Style sheets may be included in DM Script by putting the style sheet inside the HTML tags <STYLE> and </STYLE>. In general, any text enclosed in start and end tags will be sent to the player's terminal, so you could use client.script to output a welcome message as well as loading a style sheet.

    Example:

    client/script = "<STYLE>BODY {background: black; color: aqua}</STYLE>"

    This example style sheet makes the player's terminal have a black background and aqua colored text. When changing the background color, it is important to change the color of system and link text as well. See the section on style sheets for an example.


    show_map var (client)

    See also:
    show_verb_panel var (client)
    view var (client)
    view var (world)
    Default value:
    1

    This variable may be used to turn off the view of the map in Dream Seeker. This could be useful for making text MUDs where the rooms are turfs (ie most rooms can be laid out on a grid but you don't want the user interface to show the map in any way).

    The following example shows one useful combination of settings. Note that setting world.view=-1 also disables the map, but it also sets the default value of the view() depth in such a way as to always return an empty list.

    Example:

    client show_map = 0 //Text is best! world view = 0 //You can interact only with objects in same turf. mob density = 0 //Allow multiple mobs in a room.

    show_popup_menus var (client)

    See also:
    Click proc (client)
    DblClick proc (client)
    MouseDown proc (client)
    MouseDrag proc (client)
    MouseDrop proc (client)
    MouseEntered proc (client)
    MouseExited proc (client)
    MouseMove proc (client)
    MouseUp proc (client)
    Default value:
    1

    This variable may be used to turn off the popup "context" menus that are displayed by default when an object on the map or stat panels is right-clicked. If client.show_popup_menus==0, then right-clicks will instead be passed to the various mouse functions.


    show_verb_panel var (client)

    See also:
    category setting (verb)
    default_verb_category var (client)
    show_map var (client)
    Default value:
    1

    Setting this to 0 turns off the verb panel in Dream Seeker. You might want to do that, for instance, if you've only got one verb (like "say") and the panel looks stupid with just one verb in it.

    Example:

    client show_verb_panel = 0

    statobj var (client)

    See also:
    Stat proc (client)
    stat proc
    statpanel proc
    statpanel var (client)
    Default value:
    client.mob (the player's mob).

    This value indicates which object the player currently has loaded in the stat panels.


    statpanel var (client)

    See also:
    Stat proc (client)
    stat proc
    statobj var (client)
    statpanel proc
    Default value:
    null

    This value indicates which stat panel is currently visible to the player. You can assign it to force a different panel to become the top panel. The special value "verbs" activates the panel of commands.


    verbs list var (client)

    See also:
    list
    Default value:
    The list of verbs defined for the client.

    This is a list of the client's verbs. Initially, it contains all of the verbs defined for the client. It may be used to add and remove verbs at runtime.


    view var (client)

    See also:
    lazy_eye var (client)
    show_map var (client)
    view proc
    view var (world)
    Default value:
    world.view (which is 5 by default)
    Possible values:
    -1 to 34 or "WIDTHxHEIGHT"

    This controls the size of the map window in Dream Seeker. Normally, you would simply compile with world/view assigned to whatever you want, but in some cases, you might want to customize the map size for different players, such as admins or subscribed users.

    Like all other view sizes in DM, this may either be a view depth or an absolute size. A view depth is a single number that determines how far from a center point the edges of a square viewable region extend. A value of 5 creates edges which are 2*5+1 = 11 tiles long.

    The newer, more flexible syntax is a text string of the form "WIDTHxHEIGHT". For example, a view depth of 5 corresponds to "11x11". Using this syntax, you can create non-square views as well.

    The maximum view size is about 5000 tiles, or roughly 70x70.


    virtual_eye var (client)

    See also:
    edge_limit var (client)
    eye var (client)
    lazy_eye var (client)
    mob var (client)
    perspective var (client)
    view var (client)
    Default value:
    client.eye

    This value determines the actual center of the player's map display. It is based on client.eye and whenever possible matches it; however it may instead be a turf, or null, when the eye is off-center.

    The value of virtual_eye is read-only.


    datum

    See also:
    atom
    procs (datum)
    vars (datum)

    The datum object is the ancestor of all other data types in DM. (The only exceptions are currently /world, /client, /list, and /savefile, but those will be brought into conformance soon.) That means that the variables and procedures of /datum are inherited by all other types of objects.

    When you define a new "top level" object, if you do not specify a parent_type, it defaults to /datum.

    Example:

    datum //definitions to be shared by all object types proc/DebugMe() world.log << "/datum properties:" world.log << "type: [type]" world.log << "parent_type: [parent_type]" return ..() MyType var myvar = "test" DebugMe() world.log << "/MyType properties:" world.log << "myvar: [myvar]" return ..() //this calls /datum/proc/DebugMe()

    procs (datum)

    Built-in datum procs:

    datum/proc
    New
    Del
    Write
    Read
    Topic

    Del proc (datum)

    See also:
    del proc
    garbage collection
    Format:
    Del()
    When:
    Called when the object is destroyed, for example by using the del instruction.
    Default action:
    Delete the object. The contents of atomic objects are also destroyed at this time, as though del were called on each one of them.

    When the world is destroyed, the Del() proc is not automatically called. The only object for which it is called is /world. If you need the Del() proc for a particular object to be called at that time, you should explicitly call it from world/Del().


    New proc (datum)

    See also:
    New proc (atom)
    New proc (client)
    new proc
    Format:
    New()
    When:
    Called when the datum is created, for example by using new, when reading an object that was stored in a savefile, or when the world is initially created.
    Default action:
    None.

    You can use the New() procedure to do more complicated initializations than are possible in the object definition where you assign the initial value of variables to constants.

    The following example makes use of the "Location" parameter that is passed to objects of type /atom. You can pass any number of additional arguments to New() by passing them to the new instruction which creates the object.

    Example:

    mob/night var/mob/squire/my_squire New(Location) my_squire = new(Location) return ..()

    Also note that the type of object being created in this case was automatically inferred from the variable type on the left-hand side of the assignment. That's a handy little DM short-cut.


    Read proc (datum)

    See also:
    >> operator (savefile)
    Write proc (datum)
    tmp vars
    Format:
    Read(savefile/F)
    When:
    Called when the object is read from a save file.
    Args:
    F: the save file being read
    Default action:
    Read the value of each variable from a directory by the same name as the variable. Variables marked tmp, global, or const and variables for which there is no directory are skipped.

    Topic proc (datum)

    See also:
    Topic proc (client)
    ref text macro
    Format:
    Topic(href,href_list[])
    Args:
    href: the hyperlink data (following ? in the URL).
    href_list: key/value list (from params2list(href)).

    This procedure is called by the default client.Topic() proc when the href contains a parameter called "src" containing an object reference.

    Example:

    mob/verb/test() usr << "Click <a href='?src=\ref[src];action=startgame'>here</a>!" mob/Topic(href,href_list[]) switch(href_list["action"]) if("startgame") usr << "Starting game..."

    The above example uses an embedded reference to the player's own mob to create a hyperlink to that mob's Topic() proc. You can easily add different actions, parameters, and so forth. Just remember that the parameter values are always stored as text, so you need to convert those to whatever data format you need using procedures such as text2num(), locate(), etc.


    Write proc (datum)

    See also:
    << operator (savefile)
    Read proc (datum)
    initial proc
    issaved proc
    tmp vars
    Format:
    Write(savefile/F)
    When:
    Called when the object is written to a save file.
    Args:
    F: the save file being written to
    Default action:
    Write the value of each variable to a directory by the same name as the variable. Variables marked tmp, global, or const and variables which are equal to their initial value are skipped.

    vars (datum)

    Built-in datum vars:

    datum/var
    type
    parent_type
    tag
    vars

    parent_type var

    Default value:
    The path of the object definition that contains this one.

    This variable is set at compile-time to specify the inheritance of an object type. Normally, a new type of object inherits its variables and procedures from the object type that contains it. For example:

    obj var weight color sword //parent type of 'sword' defaults to /obj weight = 30 color = "black"

    Explicitly setting the parent type allows you to put the object definition any place you want. That often means putting it at the top "root" level. Example:

    Armor parent_type = /obj var strength plate //parent type is /Armor, which in turn inherits from /obj weight = 100 color = "rusty" strength = 10

    If you don't specify the parent_type for an object defined at the top level, it defaults to /datum, which (with just a couple exceptions) is the ultimate ancestor of all object types. You could use that fact to define procedures or variables that you need all of your objects to share.

    Example:

    datum proc/Copy(datum/O) MyType var foo Copy(MyType/O) foo = O.foo return ..()

    tag var (datum)

    See also:
    locate proc
    Default value:
    null

    This may be assigned to a unique text string identifying a particular object. A reference to the object can then be obtained by using locate().

    One reason to use tags is when making references in the code to objects and locations that will be created on the map. You can simply edit the object in the map editor, set its tag, and then use that in the code relating to the object.

    The following example demonstrates how to set a tag and use it to obtain a reference to an object.

    Example:

    mob/verb/test() var/obj/O = new() O.tag = "My Object" var/obj/O2 = locate("My Object") ASSERT(O == O2) //this should always be true

    Setting a tag to "" or null removes it. Any object with a non-empty tag is immune to garbage collection, since the tag is treated as an implicit reference to that object.


    type var (datum)

    Default value:
    The "type path" of the object definition.

    This variable is read-only.

    mob/verb/test() usr << type //displays "/mob"

    vars list var (datum)

    See also:
    initial proc
    issaved proc
    list
    list associations

    This is a list of all the variables belonging to an object. The items in the list are the variable names. If the variable name is used as an index into the list, the value of that variable is accessed.

    Example:

    mob/verb/dump() var/V for(V in vars) usr << "[V] = [vars[V]]"

    This example displays all the variables belonging to your mob.


    icon

    See also:
    icon procs
    icons
    image objects

    An /icon object is created by loading an icon file into memory for direct access and manipulation. In order to be displayed, an /icon object always gets converted back into an icon file; this happens automatically when you assign atom.icon to an /icon object, since that variable may only refer to a static icon file, rather than a dynamic memory object.

    To create an /icon object, simply use new/icon(), or the short-cut icon() instruction. The following example loads an icon file, reddens it, and then assigns it back to the player's icon, which implicitly creates a new icon file.

    Example:

    mob/verb/test() var/icon/I = new('player.dmi') I.Blend(rgb(40,0,0)) usr.icon = I

    Note that merely displaying different icon states or directions can generally be achieved without any icon manipulation, which is good, because it saves quite a bit of overhead. For example, the variables atom.icon_state and atom.dir can be used to control how atom.icon is displayed, without any need for generating a new icon file.


    icon procs

    See also:
    icon
    icon/proc
    New
    IconStates
    Turn
    Flip
    Shift
    SetIntensity
    Blend
    SwapColor
    DrawBox
    Insert
    MapColors
    Scale
    Crop
    GetPixel
    Width
    Height

    Blend proc (icon)

    See also:
    icon
    icon procs
    overlays var (atom)
    rgb proc
    Format:
    Blend(icon,function=ICON_ADD,x=1,y=1)
    Args:
    icon: an icon file, /icon object, or color
    function: the blending operation to use
    x, y: the position to blend the icon

    The valid blending operations are:

    The result is a combination of each corresponding pixel in the two icons. In all but ICON_OVERLAY, ICON_UNDERLAY, and ICON_OR, the transparent regions of the two icons are ORed together. That means if either icon is transparent on a given pixel, the result will be transparent. With ICON_OVERLAY or ICON_UNDERLAY, on the other hand, the original icon shows through wherever the top icon is transparent, giving the same effect as an overlay object, but resulting in only a single icon. In ICON_OR, the transparent regions are ANDed together; solid pixels are added together where they exist in both icons, or just pass through if the other icon is transparent at that pixel.

    In addition to blending with an icon, an rgb() value may also be specified. This is treated identically to an icon of that same solid color, except that the x and y arguments will be ignored. Blending with a color blends the whole icon.

    By default, the icons will line up at their lower left corners. If you want to position the second icon in a different place for blending, use the x and y arguments to specify where its lower left corner will be. 1,1 is the default, which is the lower left. 11,1 for instance would be 10 pixels to the right, and 1,21 would be 20 pixels up.


    Crop proc (icon)

    See also:
    icon
    icon procs
    icon_size var (world)
    map_format var (world)
    Big icons
    Tiled icons
    Format:
    Crop(x1,y1,x2,y2)
    Args:
    x1,y1: Coordinates of one corner of the rectangle (1,1 is the lower left)
    x2,y2: Coordinates of the other corner

    A portion of the current icon is cropped (cut). If the crop region extends outside the icon, it will be padded with transparent pixels.

    If using the TILED_ICON_MAP value for map_format, all icons must be even multiples of world.tile_size, so the icon will be padded with transparent pixels to the top and right as needed.

    Example:

    // start with a simple icon var/icon/I = new('circle.dmi') // take the upper right 16x16 chunk I.Crop(17,17,32,32) // that chunk now appears in the lower left corner icon = I

    DrawBox proc (icon)

    See also:
    icon
    icon procs
    rgb proc
    Format:
    DrawBox(rgb,x1,y1,x2=x1,y2=y1)
    Args:
    rgb: rgb(red,green,blue) or null
    x1,y1: Coordinates of one corner of the rectangle (1,1 is the lower left)
    x2,y2: (optional) Coordinates of the other corner

    A rectangle (filled) of the given color is drawn over every frame in the icon. If x2 and/or y2 are omitted, a line or a single pixel is drawn. To draw a transparent box instead of an opaque color, use null as the color.


    Flip proc (icon)

    See also:
    Turn proc (icon)
    dir var (atom)
    icon
    icon procs
    Format:
    Flip(dir)
    Args:
    dir: direction in which to flip over the icon

    This flips the icon over in the specified direction. For example, Flip(NORTH) would be like turning the icon upside down by grabbing the bottom edge and flipping it up over the top edge. You would get the same result by doing Flip(SOUTH). In general, this is not the same as turning the icon by 180 degrees, because it produces a mirror image.

    If an icon is square, it may be flipped diagonally.


    GetPixel proc (icon)

    See also:
    icon
    icon procs
    rgb proc
    Format:
    GetPixel(x, y, icon_state, dir=0, frame=0, moving=-1)
    Args:
    x,y: coordinates of the pixel to grab; 1,1 is the lower left corner
    icon_state: a specific icon_state to use (may be null)
    dir: a specific direction of this icon to use
    frame: a specific animation frame to use (1 is the 1st frame)
    moving: non-zero for only movement states, 0 for non-movement states, or null (default) for either

    This finds the icon_state and the right animation/direction frame of your choosing (it will pick the first one available if you don't specify) and returns the rgb() value of a pixel at that location, in "#RRGGBB" form. If the pixel is totally transparent, it returns null. If the pixel is partially transparent, an alpha component is also returned in "#RRGGBBAA" form.


    Width proc (icon)

    See also:
    icon
    icon procs
    Height proc
    Format:
    Width()

    This finds the width, in pixels, of the icon.


    IconStates proc (icon)

    See also:
    icon
    icon procs
    icon_states proc
    Format:
    IconStates(mode=0)
    Args:
    mode: see icon_states proc

    This returns a list of all icon state text strings that exist in the /icon object. This works in exactly the same way as icon_states(icon).


    Insert proc (icon)

    See also:
    icon procs
    New proc
    map_format var (world)
    Big icons
    Tiled icons
    Format:
    Insert(new_icon,icon_state,dir,frame,moving,delay)
    (supports named arguments)
    Args:
    new_icon: an icon file or /icon object to insert
    icon_state: an optional text string, specifying a single icon state to change or add to this icon
    dir: an optional direction; the inserted icon will only be added for this direction
    frame: an optional animation frame (starting at 1); the inserted icon will only be added for this frame
    moving: Non-zero to insert as a movement state, 0 for a regular non-movement state
    delay: 0 or null to leave unchanged; positive to set delay for a frame and turn rewind off; negative to set delay and rewind

    This adds additional states or images to an existing icon, allowing you to build directional, animated, and multi-state icons on the fly. If the state you wish to insert already exists in the file, it will be altered; otherwise it will be added. An animation may be built a piece at a time, for example by inserting an icon into the NORTH direction for animation frame 3.

    Example:

    // start with a non-animated arrow icon var/icon/I = new('arrow.dmi') // make a new state called "blink" var/icon/J = new('arrow.dmi') I.Insert(J, "blink", delay=-1) // set rewind flag // create darker shades of the arrow var/n = 2 for(var/light=9, light>=5, light--) J = new('arrow.dmi') J.SetIntensity(light/10) I.Insert(J, "blink", frame=n++) // congratulations, you have a pulsating arrow icon = I

    The icon resulting from this example has two states: The original arrow, and a new state called "blink" that pulsates between full and ½ luminance. To use the blinking state after that, set the atom's icon_state to "blink".

    (Note for animations: When building an animated icon_state from scratch, you can only add 16 new animation frames at a time; i.e., frame<=total_frames+16. Higher values for frame will be ignored. This is a safety precaution.)

    If you insert an icon of a different size, the src icon will be resized to match the size of new_icon. (The only exception is if you are using the TILED_ICON_MAP map_format, and new_icon is a single tile being inserted as a chunk into a larger icon. If icon_state, such as "2,0" or "open 0,0", already exists in src as one of its smaller pieces, then new_icon will be inserted in its place.)

    When inserting an individual animation frame, you can change the delay for just that frame only. If you don't specify a delay, the nearest frame's delay will be used. If this is the first frame being inserted into an icon, then the delay will default to 1 tick. Remember, if your delay is positive, it will turn off the rewind flag for that entire icon state; negative will turn it on.


    MapColors proc (icon)

    See also:
    icon
    icon procs
    rgb proc
    Format:
    MapColors(rr, rg, rb, gr, gg, gb, br, bg, bb, r0=0, g0=0, b0=0)
    or
    MapColors(r_rgb, g_rgb, b_rgb, rgb0=rgb(0,0,0))
    or
    MapColors(rr, rg, rb, ra, gr, gg, gb, ga, br, bg, bb, ba, ar, ag, ab, aa, r0=0, g0=0, b0=0, a0=0)
    or
    MapColors(r_rgba, g_rgba, b_rgba, a_rgba, rgba0)
    Args:
    rr: portion of old red component -> new red component
    rg: portion of old red component -> new green component
    rb: portion of old red component -> new blue component
    ra: portion of old red component -> new alpha component
    r0: new base red component
    ...
    or
    r_rgb: red component is converted to this color
    g_rgb: green component is converted to this color
    b_rgb: blue component is converted to this color
    rgb0: this color is added to the result

    This is used for complex color mapping that can be used for many special effects. For the number form, values usually range from 0 to 1, but you can use anything you like, including negative numbers. 1 means 100% of the original color will be used. If rg=1, for example, then the amount of red in the original icon becomes the same amount of green in the new icon's colors.

    There is also an alternate form that can use rgb() values instead, though it is less flexible. r_rgb is the color that will be used in place of 100% red; any darker shades of red will become a darker shade of that color. g_rgb converts green to another color, and b_rgb converts blue to still another color, and all of them are added together.

    Either of these calls change the icon to grayscale:

    icon.MapColors(0.3,0.3,0.3, 0.59,0.59,0.59, 0.11,0.11,0.11, 0,0,0) // or... icon.MapColors(rgb(77,77,77), rgb(150,150,150), rgb(28,28,28), rgb(0,0,0))

    The calculations are as follows:

    Or this will make a nice moonlight effect:

    icon.MapColors(0.2,0.05,0.05, 0.1,0.3,0.2, 0.1,0.1,0.4, 0,0,0) // or... icon.MapColors(rgb(51,13,13), rgb(26,77,51), rgb(26,26,102), rgb(0,0,0))

    Or a negative icon (invert all colors):

    MapColors(-1,0,0, 0,-1,0, 0,0,-1, 1,1,1)

    The longer formats of MapColors() will allow you to also change alpha colors.


    New proc (icon)

    See also:
    icon
    icon procs
    image proc
    new proc
    Format:
    New(icon,icon_state,dir,frame,moving)
    (supports named arguments)
    Args:
    icon: an icon file or /icon object
    icon_state: an optional text string, specifying a single icon state to load
    dir: an optional direction to extract
    frame: an optional animation frame to extract
    moving: Non-zero to extract only movement states, 0 for non-movement states, or null (default) for both

    You generally don't call this directly but via new(). The specified icon file is loaded into memory for direct access and manipulation.

    If the icon state is not specified, all icon states are loaded. Ditto for the direction, animation frame, or preference for movement states. Animation frames are numbered from 1 and up, so frame=4 is the 4th frame.

    (Movement states are special versions of an existing icon_state with the same name, but appear in the Dream Maker editor with an "M" indicator. These states are used for animation when the atom using the icon_state moves from one tile to the next; otherwise only the normal non-moving state is displayed.)

    The following contrived example, loads the EAST facing default icon state "" from the user's icon file, rotates that a bit, and then creates a new icon file for the user.

    Example:

    mob/verb/test() var/icon/I = new(usr.icon,icon_state = "",dir = EAST) I.Turn(90) //rotate clockwise 90 degrees usr.icon = I

    Note that merely displaying different icon states or directions can generally be achieved without any icon manipulation, which is good, because it saves quite a bit of overhead. For example, the variables atom.icon_state and atom.dir can be used to control how atom.icon is displayed, without any need for generating a new icon file.


    Scale proc (icon)

    See also:
    icon
    icon procs
    icon_size var (world)
    map_format var (world)
    Big icons
    Tiled icons
    Format:
    Scale(width, height)
    Args:
    width,height: size of the new icon

    The current icon is scaled to a new size.

    If world.map_format is set to TILED_ICON_MAP and the new size is not in multiples of world.icon_size, the icon will be padded with transparent pixels to the top and right as needed. See map_format for more information.

    Scale() automatically performs antialiasing to avoid unwanted artifacts.


    SetIntensity proc (icon)

    See also:
    icon
    icon procs
    MapColors() proc (icon)
    Format:
    SetIntensity(r,g=r,b=r)
    Args:
    r: red component
    g: green component
    b: blue component

    This multiplies the pixel intensities by the specified amounts. A value greater than 1.0 increases the intensity and a value less than 1.0 decreases the intensity.


    Shift proc (icon)

    See also:
    dir var (atom)
    icon
    icon procs
    Format:
    Shift(dir,offset,wrap=0)
    Args:
    dir: direction in which to shift the icon
    offset: distance to shift the pixels
    wrap: if true, causes shifted pixels to wrap around to the other side

    This moves all of the pixels by the specified amount in a direction. For example, Shift(NORTH,1) would move everything one pixel to the north.

    By default, pixels that move off the edge are not wrapped around; transparent pixels are shifted onto the other side. Calling with wrap=1 causes it to shift the pixels around to the other side.


    SwapColor proc (icon)

    See also:
    icon
    icon procs
    rgb proc
    Format:
    SwapColor(old_rgb,new_rgb)
    or
    SwapColor(old_rgba,new_rgba)
    Args:
    old_rgba: the old rgba value to be replaced
    new_rgba: the new rgba value to use in its place

    This causes a color value in the icon's palette to be changed. You can use null in place of an RGB or RGBA value.

    If the old color is a full RGBA color with an alpha value, such as rgb(1,2,3,4) or "#01020304", then that exact color is the only one changed.

    If the old color is an RGB value with no alpha specified, such as rgb(1,2,3) or "#010203", then that color will change to the new one regardless of its alpha value, and the original icon's alpha will be kept intact. (If the new color is totally transparent, however, then the old color will be replaced with full transparency.)


    Turn proc (icon)

    See also:
    Flip proc (icon)
    dir var (atom)
    icon
    icon procs
    Format:
    Turn(angle)
    Args:
    angle: an angle in degrees

    This rotates the icon clockwise by the specified amount.

    Example:

    mob/verb/drink() //this effect is very confusing! var/icon/I = new(usr.icon) I.Turn(90) usr.icon = I usr << "You feel a little tipsy!" sleep(200) I.Turn(-90) //turn it back usr.icon = I //should have just saved original value

    If an icon is not square, it cannot be turned.


    Height proc (icon)

    See also:
    icon
    icon procs
    Width proc
    Format:
    Height()

    This finds the height, in pixels, of the icon.


    image objects

    See also:
    icon var (atom)
    image proc
    image vars
    images var (client)
    overlays var (atom)
    override var (atom)

    The /image type contains data used to create a virtual image. Unlike other atomic objects, this object is a purely visual effect. It always appears attached to some other object and it behaves in every way as though it were part of that object (e.g. if the user clicks on it, this counts as a click on the atomic object, not the image).

    One reason for creating images is player-by-player control over visibility. Images only become visible when they are explicitly output to players:

    Example:

    var/image/I = image('icon.dmi',usr) //make an image attached to usr usr << I //allow usr to see it

    Images are also useful in the creation of overlays. Overlays are like images, since they are always attached to another object, but overlays obey the normal rules of visibility, so they are more convenient when you do not want to hide the effect from anybody. An overlay can be created directly from an icon file (or icon state), but when one wishes to override some additional parameter, the image() instruction is a convenient way to do it.

    Example:

    usr.overlays += image('shirt.dmi',icon_state = "red")

    In the above example, the icon state of an overlay was set by creating the overlay from an image with the desired icon state. Note that after the creation of an overlay, no link remains between the overlay and the object that was used to create it. If you change the image after that time, it will not change the overlay, which is simply a "snapshot" of the original image.

    Currently images are not affected by flick().


    image vars

    /image/var
    alpha
    blend_mode
    color
    icon
    icon_state
    text
    dir
    overlays
    underlays
    loc
    layer
    maptext
    maptext_width
    maptext_height
    pixel_x
    pixel_y
    pixel_z
    x
    y
    z
    override
    transform
    type
    parent_type
    tag

    loc var (image)

    The location of an image specifies the object to which the image is attached. Unless the image drawing layer is specified, the default will make it appear above this object, as though it were an overlay.

    Note that the image is not inside the specified location. In other words, this loc variable does not behave like /atom/movable/var/loc which specifies the container object. It is more like the image is on top of the specified object. If the object moves, the image will automatically move around with it.


    list

    See also:
    list associations
    list proc
    procs (list)
    vars (list)

    Lists are used to represent groups of objects. Like objects, they have vars and procs associated with them. In order to access these attributes, list vars must be declared of type /list. These may then be assigned to existing lists, or used to create new lists.

    Example:

    var/list/L // list reference L = world.contents // assign to existing list L = new/list() // make a new list L = new() // make a new list (implicit type) L.Add("futz") // L contains: "futz" del(L) // delete L

    Lists created with 'new()' have a default length of 0; this can be overridden by specifying the size; that is, new/list(size) creates a list with size (null) elements.

    The 'list()' proc may be used to more easily initialize list data.

    Example:

    var/list/L L = list("futz",3) // L contains: ("futz", 3)

    Alternatively, lists may be declared by using brackets, '[]'. Empty brackets indicate a list reference, exactly as /list does, so list/L is equivalent to L[]. Setting an initial size within the brackets, for instance, L[10], creates a list of that initial size.

    Example:

    var/L[] // same as var/list/L: list reference var/M[10] // initially empty list of size 10 L = M // L is now an empty list of size 10

    Once a list L is declared, a specific item can be accessed by putting its index in the brackets: L[index].

    Indices range from 1 to len. If the length of the list is changed, existing elements in the list will be preserved if they are less than the new length. New elements in the list will be given the initial value of null.

    Example:

    var/L[5] // initial length of 5 var/i for(i=1, i<=L.len, i++) L[i] = i // L contains: (1,2,3,4,5) L.len = 7 // expand list // L contains: (1,2,3,4,5,null,null) del(L) // destroy list

    Multi-dimensional lists may be created by making a list of lists.

    Example:

    var/grid[10][5] grid[1][1] = 1 grid[1][2] = 2 ...

    Such a list may also be created by using new(). As in the previous example, the next one creates a list of 10 lists each having 5 elements.

    Example:

    var/grid = new/list(10,5)

    list associations

    See also:
    list
    list proc
    list2params proc
    params var (world)
    params2list proc
    vars list var (datum)

    Each unique text string or object in a list may be associated with another value. This is done by using the item as an index into the list.

    Example:

    var/params[0] params["player"] = "James Byond" params["score"] = 2000 //List now contains ("player","score") //These are associated with ("James Byond",2000) usr << "Looping through list items:" var/p for(p in params) usr << "[p] = [params[p]]" usr << "Looping through array indices:" var/i for(i=1,i<=params.len,i++) p = params[i] usr << "[p] = [params[p]]"

    The above example illustrates the typical way in which list associations are managed. Note that an item in the list may be added by assigning its associated value. The example could have started by doing params.Add("player","score"), but that would have been redundant.

    Both for loops in the example have the same effect. The first one loops through each item in the list, and displays it along with its associated value. The second loop achieves the same thing by looping through the numerical indices (referred to as array indices as opposed to associative indices).

    Since numerical indices are treated differently, you may not assign an associated value to a numerical list item. Associations must have a text string or object reference as the index item.

    Associated values default to null if none is assigned. This is also the value returned when the supplied index item does not exist in the list. The list defined above, for example, would return null for params["time"].

    The list() instruction may also be used to create associative lists.

    Example:

    var/list/lst = list("player" = "James Byond", "score" = 2000)

    When the index values happen to be text strings that satisfy all the requirements for variable names, this may also be written in a convenient short-hand:

    var/list/lst = list(player = "James Byond", score = 2000)

    In other words, this is exactly the same syntax as for named arguments.


    list operators

    See also:
    + operator
    += operator
    - operator
    -= operator
    | operator
    |= operator
    & operator
    &= operator
    ^ operator
    ^= operator
    in operator

    The operators listed above have special meaning when applied to lists.


    procs (list)

    See also:
    list
    list operators

    Built-in list procs:

    list/proc
    Add
    Copy
    Cut
    Find
    Insert
    Remove
    Swap

    Add proc (list)

    See also:
    + operator
    Remove proc (list)
    Format:
    list.Add(Item1,Item2,...)
    Args:
    One or more items to add to the list.

    Appends the specified items to the list. If an argument is itself a list, each item in the list will be added.


    Copy proc (list)

    See also:
    Cut proc (list)
    Format:
    list.Copy(Start=1,End=0)
    Returns:
    A new list.
    Args:
    Start: The list position in which to begin the copy.
    End: The list position immediately following the last element to be copied.

    Copy list[Start] through list[End-1] into a new list. The default end position of 0 stands for the position immediately after the end of the list, so by default the entire list is copied.


    Cut proc (list)

    See also:
    Copy proc (list)
    Insert proc (list)
    Format:
    list.Cut(Start=1,End=0)
    Args:
    Start: The list position in which to begin the cut.
    End: The list position immediately following the last element to be removed.

    Remove the elements between list[Start] and list[End-1], decreasing the size of the list appropriately. The default end position of 0 stands for the position immediately after the end of the list, so by default the entire list is deleted.


    Find proc (list)

    Format:
    list.Find(Elem,Start=1,End=0)
    Returns:
    The first position of elem in list, or 0 if not found.
    Args:
    Elem: The element to find.
    Start: The list position in which to begin the search.
    End: The list position immediately following the end of the search.

    Find the first position of Elem in the list. Elements between Start and End are searched. The default end position of 0 stands for the position immediately after the end of the list, so by default the entire list is searched.


    Insert proc (list)

    See also:
    Cut proc (list)
    Copy proc (list)
    Swap proc (list)
    Format:
    list.Insert(Index,Item1,Item2...)
    Returns:
    The index following the inserted items.
    Args:
    Index: The index where the new item will be inserted. Any value already at that index will be pushed forward.
    Item1: A value or list of values to insert.
    Item2...: (optional) Additional items to insert, immediately after the previous item(s).

    Insert values into a list at a specific point. Using Index=0 or Index=list.len+1 is the same as adding to the list.

    Note: This proc doesn't work with many special lists such as contents.


    Remove proc (list)

    See also:
    - operator
    Add proc (list)
    Format:
    list.Remove(Item1,Item2,...)
    Returns:
    1 if any items removed, 0 if not.
    Args:
    One or more items to remove from the list.

    Removes the specified items from the list. If an argument is itself a list, each item contained in it will be removed. Removal starts at the end of the list (highest index) so that this operation is an exact reversal of Add().


    Swap proc (list)

    See also:
    Cut proc (list)
    Copy proc (list)
    Insert proc (list)
    Format:
    list.Swap(Index1,Index2)
    Returns:
    Nothing.
    Args:
    Index1: The index (1 to list.len) of one of the items to swap.
    Index2: The index of the other item.

    Swap two items in a list. If the list has associated values, they will be preserved. This is most useful for user-defined sorting routines.

    Example:

    var/item var/list/L = list("orange" = 3, "green" = 2, "blue" = 5) for(item in L) world << "[item] -> [L[item]]" world << "" L.Swap(1, 3) for(item in L) world << "[item] -> [L[item]]"

    Result:

    orange -> 3 green -> 2 blue -> 5 blue -> 5 green -> 2 orange -> 3

    Note: This proc doesn't work with many special lists such as contents.


    vars (list)

    Built-in list vars:

    list/var
    len

    len var (list)

    See also:
    + operator
    += operator
    - operator
    -= operator

    This is the length of the list. Increasing it expands the list, initializing all new elements with null. Decreasing it contracts the list, making old elements inaccessible.


    map

    See also:
    #include directive
    area var (world)
    maxx var (world)
    turf var (world)
    Format:
    #include "mapname.dmm"

    One or more map files may be loaded into the world's map. These are loaded into successive z-levels. If no map files are specified, the default project map file will be used. This file has the same name as the project but has the extension .dmm.

    If no map files are loaded, the world's map size is determined by the world variables maxx, maxy, and maxz. The default content of this map is determined by the world variables turf and area.

    Example:

    #include "level1.dmm" #include "level2.dmm" #include "level3.dmm"

    matrix

    See also:
    matrix operators
    matrix procs
    transform var (atom)
    matrix proc

    To display rotation, scaling, and other transformations on atoms, DM uses matrices. The /matrix datum is a convenient way of handling the numbers involved, as it can be easily manipulated. There are six vars, a through f, laid out like so:

    a d 0 x y 1 * b e 0 = x' y' 1 c f 1

    When an x,y point is multiplied by the matrix, it becomes the new point x',y'. This is equivalent to:

    x' = a*x + b*y + c y' = d*x + e*y + f

    The default matrix is:

    1 0 0 0 1 0 0 0 1

    Matrices are created with the matrix() proc, or by calling new/matrix(). (See the matrix() proc for examples.) They are also created as needed whenever you read from atom.transform or use certain operators.

    Manipulation of matrices can be done with operators, or with procs. You can do the following with them:

    When you've built your matrix, you can assign it to atom.transform to change the way that atom is displayed.


    matrix operators

    See also:
    matrix
    matrix procs
    See also:
    + operator
    += operator
    - operator
    -= operator
    * operator
    *= operator
    / operator
    /= operator
    ~ operator

    The operators listed above have special meaning when applied to matrices.

    The assignment operators will modify an existing matrix, and can also be used directly with atom.transform. Other operators will create a new matrix.


    matrix procs

    See also:
    matrix
    matrix operators
    turn proc (applied to a matrix)
    matrix/proc
    New
    Add
    Interpolate
    Invert
    Multiply
    Scale
    Subtract
    Translate
    Turn

    Add proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    += operator
    Format:
    Add(Matrix2)
    Args:
    Matrix2: another matrix
    Return value:
    src

    This adds Matrix2 to the current matrix.


    Interpolate proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    Format:
    Interpolate(Matrix2, t)
    Args:
    Matrix2: Another matrix
    t: The interpolation factor: from 0 (src) to 1 (Matrix2). Usually this is a value between 0 and 1.

    Calculates and returns a new matrix between src and Matrix2. If t is 0.5, then the result will be exactly halfway between both matrices.

    There are many ways to interpolate matrices. Whenever possible, DM will interpolate by doing scaling and/or shearing first, then rotation, then translation. This is done by trying to find the angle of rotation of each matrix first; a rotation of 180 is counted as a flip rather than a rotation.

    It is not strictly necessary for t to be between 0 and 1. Using a value out of bounds will extrapolate a matrix, continuing the change as far as t.


    Invert proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    ~ operator
    Format:
    Invert()
    Return value:
    src

    This inverts the current matrix, if possible.

    Not all matrices can be inverted. If it's not possible, the matrix is said to be degenerate. This happens if, for example, all of the values in the matrix are zero. A degenerate matrix will not be changed by this proc.


    Multiply proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    *= operator
    Format:
    Multiply(Matrix2)
    or
    Multiply(n)
    Args:
    Matrix2: another matrix
    n: a number
    Return value:
    src

    This multiplies the current matrix by Matrix2 or n. If the n format is used, this is just like scaling the whole matrix. If another matrix is multiplied, then it is like doing the two transformations in order: src, then Matrix2.

    Multiplication of one matrix by another depends on the order. You may get a different result multiplying A * B vs. B * A.


    Scale proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    Format:
    Scale(x,y)
    Args:
    x: The amount of scaling to do in the x direction
    y: The amount of scaling to do in the y direction
    Return value:
    src

    The matrix is scaled by the appropriate amounts.

    If y is omitted, x is used for both. E.g., Scale(2) is equivalent to Scale(2,2).


    Subtract proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    -= operator
    Format:
    Subtract(Matrix2)
    Args:
    Matrix2: another matrix
    Return value:
    src

    This subtracts Matrix2 from the current matrix.


    Translate proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    Format:
    Translate(x,y)
    Args:
    x: The amount of scaling to do in the x direction
    y: The amount of scaling to do in the y direction
    Return value:
    src

    The matrix is translated (moved) by the appropriate amounts. The x and y offsets applied by translation are in pixels.

    If y is omitted, x is used for both. E.g., Translate(2) is equivalent to Translate(2,2).


    Turn proc (matrix)

    See also:
    matrix
    matrix operators
    matrix procs
    turn proc (applied to a matrix)
    Format:
    Turn(angle)
    Args:
    angle: The angle of clockwise rotation, in degrees
    Return value:
    src

    The matrix is rotated clockwise, by the angle given.


    mob

    See also:
    atom
    movable atoms
    procs (mob)
    vars (mob)

    Mobs are "mobile objects" derived from /mob. Human players are associated with a mob when they log on.

    Example:

    mob guzzler desc = "Mean, mad, and wicked bad."

    This example defines the mob type /mob/guzzler.


    procs (mob)

    Built-in mob procs:

    mob/proc
    Bump
    Click
    DblClick
    Del
    Enter
    Entered
    Exit
    Exited
    Login
    Logout
    MouseDown
    MouseDrag
    MouseDrop
    MouseEntered
    MouseExited
    MouseMove
    MouseUp
    Move
    New
    Read
    Stat
    Topic
    Write

    Login proc (mob)

    See also:
    Logout proc (mob)
    client var (mob)
    Format:
    Login()
    When:
    Called when a player's client tries to connect to a mob. This is called by default from client.New(), when the player logs into the world.
    Default action:
    If the mob has no location, place it near (1,1,1) if possible. Change the player's stat object (client.statobj) to the mob.

    One can typically tell if a player is connecting to a fresh mob versus reconnecting to an existing one by testing if the mob's location is null.


    Logout proc (mob)

    See also:
    Login proc (mob)
    client var (mob)
    key var (mob)
    Format:
    Logout()
    When:
    Called when a player's client has disconnected from a mob. This happens in client.Del() when the player logs out of the world. It may also happen when the player switches from one mob to another.
    Default action:
    None.

    One may wish to distinguish between a player who has disconnected from the game and one who is simply switching from one mob to another. In the case of a player switching to another mob, by the time Logout() is called, the original mob's key will be null, whereas the key will still be non-null in the case of a player disconnecting from the game.


    vars (mob)

    Built-in mob vars:

    mob/var
    alpha
    blend_mode
    ckey
    client
    color
    contents
    density
    desc
    dir
    gender
    group
    icon
    icon_state
    invisibility
    underlays
    overlays
    key
    layer
    luminosity
    maptext
    maptext_width
    maptext_height
    animate_movement
    loc
    mouse_over_pointer
    mouse_drag_pointer
    mouse_drop_pointer
    mouse_drop_zone var
    mouse_opacity var
    name
    opacity
    parent_type
    see_infrared
    see_invisible
    see_in_dark
    sight
    suffix
    tag
    text
    transform
    type
    vars
    verbs
    x
    y
    z

    ckey var (mob)

    See also:
    ckey proc
    key var (mob)
    Default value:
    null

    This is the value of mob.key converted to canonical form (ie the form returned by the ckey() proc). Among other things, this could be used as a unique directory name in a server-side save file for storing player information. See the ckey() proc for an example.


    client var (mob)

    See also:
    client
    Default value:
    null

    This is a reference to a set of properties specific to the player. Therefore non-player mobs (NPCs) do not have a client (client = null).

    Setting a mob's client connects that player's client to the mob.


    group list var (mob)

    See also:
    Bump proc (movable atom)
    list
    Default value:
    (empty list)

    This is a list of mobs in the same group. By default, a mob will swap positions with another mob in its group if bumped. It is also possible to make verbs that are accessible only to members of the group.

    The following example handles addition of somebody else to your group.

    Example:

    mob/verb/join(mob/M) usr.group.Add(M) // add M to usr's group view() << "[usr] joins [M]." mob/verb/disband(mob/M) usr.group.Remove(M) // remove M from group view() << "[usr] disbands [M]."

    Note that group lists may be asymmetric. Mob A may have mob B in his group list, but mob B may or may not. It is up to you to define whether mobs are added into both lists or not.

    Here is an example of a verb accessible to a group:

    Example:

    mob/verb/summon() set src in usr.group loc = usr.loc view() << "[usr] summons [src]."

    key var (mob)

    See also:
    ckey var (mob)
    client
    key var (client)
    Default value:
    null

    For player mobs (PCs) this is the value of the player's key. For non-player mobs (NPCs), this is the value of the "desired" key. This means that if a player with that key logs into the world, he will be connected to that mob (as opposed to a new one of type world.mob).

    Setting the mob's key will cause a client with the same key to connect to the mob. Any other mob with the same key will lose it.

    Key values are always compared in canonical form (ie the form returned by ckey()) so setting a mob's key to "Dan", "dan" are equivalent as far as controlling player linkage.


    parent_type var (mob)

    See also:
    parent_type var

    The default parent_type of /mob is /atom/movable.


    see_in_dark var (mob)

    See also:
    luminosity var (atom)
    see_infrared var (mob)
    see_invisible var (mob)
    sight var (mob)
    view proc
    Default value:
    2

    This determines how far the mob can see in the dark. The scale is just like luminosity: a value of 1 illuminates the mob and its location; 2 illuminates the immediate surrounds; and so on.


    see_infrared var (mob)

    See also:
    infra_luminosity var (atom)
    see_in_dark var (mob)
    see_invisible var (mob)
    sight var (mob)
    view proc
    Default value:
    0

    Setting this to 1 enables infravision, allowing the mob to see infrared objects in the dark.


    see_invisible var (mob)

    See also:
    invisibility var (atom)
    see_in_dark var (mob)
    see_infrared var (mob)
    sight var (mob)
    view proc
    Default value:
    0

    This is the maximum level of invisibility that the mob can see.


    sight var (mob)

    See also:
    invisibility setting (verb)
    invisibility var (atom)
    see_in_dark var (mob)
    see_infrared var (mob)
    see_invisible var (mob)
    view proc
    Default value:
    0

    This controls which objects on the map the mob can see. The default value of 0 means that the mob can see all objects that are visible and lit. Different flags in this var can be set to extend or limit this range.

    The following bit flags are encoded in mob.sight:

    SEE_INFRA // can see infra-red objects SEE_SELF // can see self, no matter what SEE_MOBS // can see all mobs, no matter what SEE_OBJS // can see all objs, no matter what SEE_TURFS // can see all turfs (and areas), no matter what SEE_PIXELS// if an object is located on an unlit area, but some of its pixels are // in a lit area (via pixel_x,y or smooth movement), can see those pixels BLIND // can't see anything

    Example:

    usr.sight |= BLIND // turn on the blind bit usr.sight &= ~BLIND // turn off the blind bit usr.sight |= (SEE_MOBS|SEE_OBJS|SEE_TURFS) // turn on several bits at once usr.sight &= ~(SEE_MOBS|SEE_OBJS|SEE_TURFS) // turn off several bits at once

    obj

    See also:
    atom
    movable atoms
    procs (obj)
    vars (obj)

    Objects are derived from /obj.

    The following example defines the obj type /obj/scooper.

    Example:

    obj scooper desc = "Super pooper scooper."

    procs (obj)

    Built-in obj procs:

    obj/proc
    Bump
    Click
    DblClick
    Del
    Enter
    Entered
    Exit
    Exited
    MouseDown
    MouseDrag
    MouseDrop
    MouseEntered
    MouseExited
    MouseMove
    MouseUp
    Move
    New
    Read
    Stat
    Topic
    Write

    vars (obj)

    Built-in obj vars:

    obj/var
    alpha
    blend_mode
    color
    contents
    density
    desc
    dir
    gender
    icon
    icon_state
    invisibility
    underlays
    overlays
    layer
    luminosity
    maptext
    maptext_width
    maptext_height
    animate_movement
    loc
    mouse_over_pointer
    mouse_drag_pointer
    mouse_drop_pointer
    mouse_drop_zone var
    mouse_opacity var
    name
    opacity
    parent_type
    suffix
    tag
    text
    transform
    type
    vars
    verbs
    x
    y
    z

    parent_type var (obj)

    See also:
    parent_type var

    The default parent_type of /obj is /atom/movable.


    operators

    Operators are used extensively in DM to compute numerical values.

    The DM operators are:

    [] () . / : ~ ! - ++ -- ** * / % + - < <= > >= << >> == != <> & ^ | && || ? = += -= *= /= &= |= ^= <<= >>=

    Each line has higher order of operations than the next. Operators within a line have equal precedence and therefore are processed from left to right as they occur in an expression.

    To see an individual reference section, look up /operator/=, /operator/!, etc.

    Expressions of the form: A #= B are shorthand for: A = A # B

    Example:

    var/N N = 0 // 0 N += 1+1*2 // 3 if(1 + 1 == 2) N = 2 // 2 if(N==2 && 1/2==0.5) N = 0.5 // 0.5

    ! operator

    See also:
    && operator
    operators
    || operator
    Format:
    !A
    Returns:
    1 if A is zero; 0 otherwise.

    != operator

    See also:
    > operator
    < operator
    <> operator
    == operator
    operators
    Format:
    A != B
    Returns:
    1 if A is not equal to B; 0 otherwise

    This is identical to the <> operator.


    % operator

    See also:
    %= operator
    operators
    Format:
    A % B
    Returns:
    The remainder of A / B.

    A % B is read "A modulo B", which stands for the remainder of A divided by B.


    %= operator

    See also:
    % operator
    operators
    Format:
    A %= B

    Set A equal to A % B. It is shorthand for A = A % B.

    A % B is read "A modulo B", which stands for the remainder of A divided by B.


    & operator

    See also:
    &= operator
    operators
    | operator
    Format:
    A & B
    Returns:
    The binary "and" of A and B.

    A and B must be between 0 and 65535 (2**16 - 1), giving an effective width of 16 bits.

    If A and B are lists, the result is a list that contains only items that were in both lists, in the order of list A.

    If A is an icon or /icon datum, it is blended with B which can be either a color or another icon. This is identical to the + operator. Transparent areas in either icon will be transparent in the result.


    && operator

    See also:
    ! operator
    operators
    || operator
    Format:
    A && B
    Returns:
    true value if both A and B are nonzero; false value otherwise

    The first false value from left to right completes the evaluation (a practice known as short-circuiting). The return value is equal to the last argument to be evaluated.


    &= operator

    See also:
    & operator
    operators
    |= operator
    Format:
    A &= B

    Set A equal to A & B. It is shorthand for A = A & B.

    This is commonly used to turn off certain bitfields in a word.

    Example:

    usr.sight &= ~BLIND // turn off the blind bit

    If A and B are lists, items in A that are not in B are removed.

    If A is an /icon or /matrix datum, the datum will be changed rather than creating a new one and re-assigning it to A.


    > operator

    See also:
    >= operator
    < operator
    == operator
    operators
    sorttextEx proc
    Format:
    A > B
    Returns:
    1 if A is greater than B; 0 otherwise.

    If A and B are text strings, a case sensitive comparison is performed (like sorttextEx()).


    >> operator

    See also:
    >> input operator
    >> operator (savefile)
    >> shift operator

    >> input operator

    See also:
    >> operator (savefile)
    file proc
    Format:
    F >> Var

    Cause input to be read from a file into a variable. The file may be a savefile or a file object corresponding to a text file.


    >> shift operator

    See also:
    >>= operator
    << shift operator
    operators
    Format:
    A >> B
    Returns:
    The bits of A shifted right B times.

    A and B must be between 0 and 65535 (2**16 - 1), giving an effective width of 16 bits.

    Bits shifted below the 16 low bits are lost.


    >>= operator

    See also:
    >> shift operator
    <<= operator
    operators
    Format:
    A >>= B

    Set A equal to A >> B. It is shorthand for A = A >> B.


    >= operator

    See also:
    > operator
    < operator
    == operator
    operators
    sorttextEx proc
    Format:
    A >= B
    Returns:
    1 if A is greater or equal to B; 0 otherwise.

    If A and B are text strings, a case sensitive comparison is performed (like sorttextEx()).


    < operator

    See also:
    < operator
    <= operator
    == operator
    operators
    sorttextEx proc
    Format:
    A < B
    Returns:
    1 if A is less than B; 0 otherwise.

    If A and B are text strings, a case sensitive comparison is performed (like sorttextEx()).


    <> operator

    See also:
    != operator
    > operator
    < operator
    == operator
    operators
    sorttextEx proc
    Format:
    A <> B
    Returns:
    1 if A is not equal to B; 0 otherwise

    This is identical to the != operator.


    << operator

    See also:
    << operator (savefile)
    << output operator
    << shift operator

    << output operator

    See also:
    << operator (savefile)
    output proc
    browse proc
    browse_rsc proc
    file proc
    ftp proc
    image proc
    link proc
    run proc
    sound proc
    Format:
    A << B

    Cause the value B to be output to any players connected to mobs specified in A.

    B may be an image, sound, or text. A may be a mob, the whole world, or any list containing mobs.

    Example:

    usr << "Hi, [usr.name]" view() << "To all in view" world << "Hi everybody!" usr << 'giggle.wav' view() << image(/obj/Fireball,usr)

    << shift operator

    See also:
    >> operator
    <<= operator
    operators
    Format:
    A << B
    Returns:
    The bits of A shifted left B times.

    A and B must be between 0 and 65535 (2**16 - 1), giving an effective width of 16 bits.

    Bits shifted beyond the 16 low bits are lost.


    <<= operator

    See also:
    >>= operator
    << shift operator
    operators
    Format:
    A <<= B

    Set A equal to A << B. It is shorthand for A = A << B.


    <= operator

    See also:
    > operator
    < operator
    == operator
    operators
    sorttextEx proc
    Format:
    A <= B
    Returns:
    1 if A is less than or equal to B; 0 otherwise.

    If A and B are text strings, a case sensitive comparison is performed (like sorttextEx()).


    () operator

    See also:
    operators
    procs
    verbs

    This is used to call procs and verbs. It may also be used in expressions to force the contained expression to be evaluated first.

    Example:

    usr << 2 + 3 * 2 //8 usr <<(2 + 3)* 2 //10

    * operator

    See also:
    *= operator
    + operator
    - operator
    / operator
    operators
    Format:
    A * B
    Returns:
    The product of A and B.

    If A is an icon, the result is a new icon with B (a number, color, or another icon) multiplied. This works with the /icon datum as well.

    If A is a /matrix datum, the result is a new matrix. B can be a number (which scales the whole matrix) or another matrix. Multiplying two matrices together can have different results depending on the order.


    ** operator

    See also:
    log proc
    operators
    Format:
    A ** B
    Returns:
    A to the power of B.

    Example:

    usr << 2 ** 3 // outputs 8

    *= operator

    See also:
    * operator
    += operator
    -= operator
    /= operator
    = operator
    operators
    Format:
    A *= B

    Set A equal to A * B. It is shorthand for A = A * B.

    If A is an /icon or /matrix datum, the datum will be changed rather than creating a new one and re-assigning it to A.


    + operator

    See also:
    * operator
    += operator
    - operator
    / operator
    Add proc (list)
    operators
    Format:
    A + B
    Returns:
    If A is a number, returns the sum of A and B.
    If A is null, returns B.
    If A is a list, a new list is returned with B appended to the contents of A. If B is a list as well, its contents are appended rather than the list itself.
    If A is a text string, returns a new string with A and B concatenated.
    If A is an icon, returns a new icon with B (a color or another icon) added. Areas that are transparent in either icon are transparent in both; for more opacity use | (OR) instead. This works with the /icon datum as well.
    If A and B are both /matrix datums, returns a new matrix with their components added together.

    ++ operator

    See also:
    + operator
    += operator
    -- operator
    operators
    Format:
    ++A // pre-increment
    A++ // post-increment

    The pre-increment has the value (A+1) and the effect of adding 1 to A.

    The post-increment has the value (A) and has the effect of adding 1 to A.

    Example:

    var/A = 0 world << "A++ = [A++]" // outputs "A++ = 0" world << "++A = [++A]" // outputs "++A = 2"

    += operator

    See also:
    *= operator
    + operator
    -= operator
    /= operator
    = operator
    operators
    Format:
    A += B

    Set A equal to A + B. It is shorthand for A = A + B.

    If A is an /icon or /matrix datum, the datum will be changed rather than creating a new one and re-assigning it to A.


    - operator

    See also:
    * operator
    + operator
    -= operator
    / operator
    Remove proc (list)
    operators
    Format:
    A - B
    -B
    Returns:
    If A is a number, returns A minus B.
    If A is a list, a new list is returned with B removed from the contents of A. If B is a list as well, each of its contents are removed rather than the list itself.
    If A is an icon, returns a new icon with B (a color or another icon) subtracted. Areas that are transparent in either icon are transparent in both. This works with the /icon datum as well.
    If A and B are both /matrix datums, returns a new matrix with their components subtracted.

    -- operator

    See also:
    ++ operator
    - operator
    -= operator
    operators
    Format:
    --A // pre-decrement
    A-- // post-decrement

    The pre-decrement has the value (A-1) and the effect of subtracting 1 from A.

    The post-decrement has the value (A) and has the effect of subtracting 1 from A.

    Example:

    var/A = 0 world << "A-- = [A--]" // outputs "A = 0" world << "--A = [--A]" // outputs "A = -2"

    -= operator

    See also:
    *= operator
    += operator
    - operator
    /= operator
    = operator
    operators
    Format:
    A -= B

    Set A equal to A - B. It is shorthand for A = A - B.

    If A is an /icon or /matrix datum, the datum will be changed rather than creating a new one and re-assigning it to A.


    / operator

    See also:
    * operator
    + operator
    - operator
    / path operator
    /= operator
    operators
    Format:
    A / B
    Returns:
    A divided by B.

    If A is an icon, the result is a new icon whose color values (except alpha) are divided by B, which must be a number. This works with the /icon datum as well.

    If A is a /matrix datum, the result is a new matrix. B can be a number (which scales the whole matrix) or another matrix. Dividing by matrix B is the same as multiplyng by its inverse. That is, A / B is identical to A * ~B.


    /= operator

    See also:
    *= operator
    += operator
    -= operator
    / operator
    = operator
    operators
    Format:
    A /= B

    Set A equal to A / B. It is shorthand for A = A / B.

    If A is an /icon or /matrix datum, the datum will be changed rather than creating a new one and re-assigning it to A.


    : operator

    See also:
    . operator
    : path operator
    operators

    This is the runtime search operator. It is used to access a property of a var that is not explicitly prototyped. If the variable doesn't have the specified variable, a run-time error occurs.

    Example:

    var/M M = usr M:name = "futz" // access a mob property from a non-mob var

    = operator

    See also:
    *= operator
    += operator
    -= operator
    /= operator
    operators
    Format:
    A = B

    Set A equal to B.

    Note that this is not the same as the equality test (==), which tests if A is equal to B.


    == operator

    See also:
    != operator
    >= operator
    <= operator
    operators
    Format:
    A == B
    Returns:
    1 if A and B are equal; 0 otherwise

    Note that this is not the same as the assignment operator (=), which sets A equal to B.


    . operator

    See also:
    : operator
    operators

    This is used to access the procs and vars of a prototyped object. The variable need not actually contain a value with the specified type, but must at least be a type with the specified variable or a run-time error will occur, causing the proc to crash.

    Example:

    var/mob/M M.name = "futz" // assign 'name' mob var M.Move(0) // call 'Move()' mob proc

    ? operator

    See also:
    operators
    Format:
    Expr ? TrueExpr : FalseExpr

    If Expr is true, this evaluates and returns TrueExpr. Otherwise, it evaluates and returns FalseExpr.


    [] operator

    See also:
    list
    operators

    This is used to access an element of a list.

    Example:

    var/L[2] // declares list of size 2 L[1] = 10 // assign first element

    ^ operator

    See also:
    ^= operator
    operators
    Format:
    A ^ B
    Returns:
    The binary "xor" of A and B.

    A and B must be between 0 and 65535 (2**16 - 1), giving an effective width of 16 bits.

    If A and B are lists, the result is a list containing items that are in either list but not both. list(1,2) ^ list(2,3) is equivalent to list(1,3). The items found only in A come first in the result, followed by any items found only in B.


    ^= operator

    See also:
    ^ operator
    operators
    Format:
    A ^= B

    Set A equal to A ^ B. It is shorthand for A = A ^ B.

    If A and B are lists, any items that are found in both lists are removed from A, and then any items found only in B are added to A.


    in operator

    Format:
    A in List
    Returns:
    1 if A exists in List; 0 if not

    path operators

    See also:
    . path operator
    / path operator
    : path operator
    procs
    vars

    A "path" in DM is a constant value that identifies a particular definition in the code tree (i.e. an object, procedure, or variable definition). An example of this is the default mob type for new players /mob.

    Paths are used in two contexts. One is to "get to" a particular point in the code tree in order to modify the definition. The other is to reference a particular definition made elsewhere in the code tree. The syntax of a path is similar in both cases.

    When you are making a definition, you simply put the path at the beginning of a line like this:

    obj/clothes/gloves

    That automatically creates that path in the code tree if it does not already exist. When starting at the beginning of the line (no indentation) there is no need to begin the path with '/', but that is perfectly acceptable.

    When making definitions, DM equates the path separator '/' with indentation, so the above example is really just a more compact way of writing:

    obj clothing gloves

    One generally uses indentation when you have several things to define with a common parent path:

    obj clothing gloves sandals

    An important element of DM is that you can get to the same path in the code tree from multiple places in the source code. For example, given the above definition of gloves and sandals, you could modify a property of one of them from somewhere else using any path syntax you like:

    obj/clothing/sandals name = "Winged Sandals"

    While that was not a useful thing to do in this case, it can be a very powerful tool when organizing source code in large projects. Also note that the use of "/" can save your source code from getting too deeply indented, which may sound mundane, but which is quite important!

    The above examples used paths to make definitions. The other time when you use paths is when you need to refer to a particular definition. Creation of an object is one example:

    mob/Login() if(length(contents) == 0) //poor fellow has nothing //create sandals in his contents list new /obj/clothing/sandals (src) return ..()

    Another common use of paths is to declare the data type of a variable. In DM, variable types do not affect what type of data the variable may contain--variables that you define may contain any type of value. Instead, the variable type affects what properties of the data you can attempt to access.

    The following example defines variables for clothing that is occupying various positions on the body.

    mob var/clothing feet hands torso

    Since there were several variables of the same type, they were grouped under var/clothing. It can be done any number of ways, depending on the situation. The same path syntax applies to variable definitions as it does to anything else. This example produces the same effect:

    mob/var/clothing/feet mob/var clothing hands torso

    Provisos

    Just do not make a mistake like the following:

    mob/var /clothing/feet

    Beginning a path with '/' effectively ignores whatever indentation may precede it. That is why it is called an absolute path. The above example would therefore be the same as the following, which is not what you want:

    mob/var //empty variable definition clothing/feet //definition of object type /clothing/feet

    On a related note, parameter definitions in procedures should not begin with a "/".

    mob/Move(atom/Dest) //correct src << "Moving to [Dest.x],[Dest.y]." return ..() mob/Move(var/atom/Dest) //ok mob/Move(/atom/Dest) //WRONG

    Essentially, "var/" is prepended to each entry in the parameter list.


    / path operator

    See also:
    . path operator
    : path operator

    This is used to delimit paths in the DM code tree. A path beginning with '/' is an absolute path (which is independent of where in the code it is used). Otherwise, a path is relative, meaning it starts from the current position in the code.

    The following example uses a path in the code tree to define the type of object to create when leaving a corpse behind.

    Example:

    obj var poison nutrition corpse frog nutrition = 10 spider nutrition = 6 poison = 5 mob var corpse = /obj/corpse Die() new corpse(src.loc) //create the corpse here del src spider corpse = /obj/corpse/spider frog corpse = /obj/corpse/frog

    : path operator

    See also:
    . path operator
    / path operator

    The colon operator may be used as a short-cut when specifying a path in the DM code tree. Instead of specifying the full path, you can insert a colon and the compiler will search down in the tree with the node you specify. This is known as a "downward" search. You should only use it when the target node is unique.

    The following example demonstrates the principle but it obviously doesn't save much typing!

    Example:

    world mob = :player //short-cut to /mob/player mob/player Login() src << "Welcome, [name]."

    . path operator

    See also:
    / path operator
    : path operator

    The dot operator may be used as a short-cut when specifying a path in the DM code tree. Instead of specifying the full path, you can start a path with a dot and the compiler will search up in the code tree for the following node. This is known as a relative path with an "upward" search.

    Here are the beginnings of a text MUD that allows you to walk around between rooms using the arrow keys. The links between rooms are created in this example by referencing the object type of the destination room. Since there could potentially be a lot of rooms, they are grouped into sub-classes, and to avoid lengthy type paths such as /area/Village/Square, they are referenced using a relative path from the point of reference.

    Example:

    area var/area north_exit south_exit east_exit west_exit Entered(O) O << name return ..() Castle Main_Gate north_exit = .Castle_Entryway south_exit = .Moat_Bridge Castle_Entryway south_exit = .Main_Gate Moat_Bridge north_exit = .Main_Gate south_exit = .Village/Guard_Post Village Guard_Post north_exit = .Castle/Moat_Bridge south_exit = .Square Square north_exit = .Guard_Post //handle movement client/Move(Dest,Dir) var/area/room = usr.loc if(istype(room)) //in a room switch(Dir) if(NORTH) Dest = room.north_exit if(SOUTH) Dest = room.south_exit if(EAST) Dest = room.east_exit if(WEST) Dest = room.west_exit return ..() //set the starting position for new logins mob/Login() if(!loc) Move(locate(/area/Castle/Main_Gate)) return ..()

    | operator

    See also:
    & operator
    operators
    |= operator
    Format:
    A | B
    Returns:
    The binary "or" of A and B.

    A and B must be between 0 and 65535 (2**16 - 1), giving an effective width of 16 bits.

    If A and B are lists, the result is a list containing items that are in either list. list(1,2) | list(2,3) is equivalent to list(1,2,3). The items from A come first in the result, followed by any extra items from B.

    If A is an icon or /icon datum, it is blended with B which can be either a color or another icon. Unlike the + or & operation, the result is transparent only in places where both icons were transparent.


    |= operator

    See also:
    &= operator
    operators
    | operator
    Format:
    A |= B

    Set A equal to A | B. It is shorthand for A = A | B.

    This is commonly used to turn on certain bitfields in a word.

    Example:

    usr.sight |= BLIND // turn on the blind bit

    If A and B are lists, any items in B that are not already in A are added to A.

    If A is an /icon or /matrix datum, the datum will be changed rather than creating a new one and re-assigning it to A.


    || operator

    See also:
    ! operator
    && operator
    operators
    Format:
    A || B
    Returns:
    true value if either A or B is nonzero; false value otherwise

    The first true value from left to right completes the evaluation (a practice known as short-circuiting). The entire expression takes the value of the last argument to be evaluated.


    ~ operator

    See also:
    operators
    Format:
    ~ A
    Returns:
    The binary "not" of A.

    A must be between 0 and 65535 (2**16 - 1), giving an effective width of 16 bits.

    If A is a /matrix datum, the result is a new matrix which is the inverse of A.


    procs

    See also:
    arguments (proc)
    procs (area)
    procs (mob)
    procs (obj)
    procs (turf)
    vars (procs)

    Procs may be derived from /proc. These procs are "global", in that they can be called anywhere in the code.

    Example:

    proc/poof() world << "POOF!"

    The proc 'poof()' may now be called anywhere in the code.

    Procs may also be attached to objects by defining them under the appropriate object/proc subnode. Currently DM allows procs to be defined or overridden for /mob, /obj, /turf, /area, and /client, as well as for data objects derived from /. Predefined procs are discussed under the "procs" entry for the object type.

    Example:

    mob/proc/poof() world << "POOF!"

    This can be called by a mob var M, using 'M.poof()'.


    . proc

    See also:
    .. proc
    Format:
    .(Args)
    Returns:
    The return value of the current proc.
    Args:
    The arguments to pass to the new invocation of the current proc. This defaults to current arguments.

    Call the current proc. A proc that calls itself is said to be recursive.

    Example:

    proc/factorial(N as num) if(N<=0) return 1 return .(N-1)*N

    This computes the factorial N! by calling itself recursively.


    .. proc

    See also:
    . proc
    Format:
    ..(Args)
    Returns:
    The return value of the parent proc.
    Args:
    The arguments to pass to the parent proc. This defaults to the arguments to the current proc.

    If object O is derived from object P, P is called the parent of O. If a proc (or verb) is defined in both O and P, O can call P's version by using ..().

    Example:

    mob P verb/history() world << "P" O verb/history() world << "O" ..() // call P.history()

    Here O is derived from P. When P calls "history", his name is displayed. When O calls "history", his name is displayed, followed by the name of his parent, P.

    ..() can also be used for predefined procs.

    Example:

    mob/Move() // override proc world << "moving..." return ..() // call default

    This proc will print "moving..." whenever the mob moves.


    ASSERT proc

    See also:
    CRASH proc
    DEBUG definition
    Format:
    ASSERT(expression)
    Args:
    expression: an expression which should always be true

    This is used to make a sanity check. If the given expression is false, the current procedure crashes, generating diagnostic debugging output, which includes the expression, a stack dump, and so forth.


    CRASH proc

    See also:
    ASSERT proc
    DEBUG definition
    Format:
    CRASH(msg)

    Crashes the current procedure, displaying the specified message and generating diagnostic debugging output, such as a stack dump.


    abs proc

    Format:
    abs(A)
    Returns:
    The absolute value of A.
    Args:
    A: A number.

    Example:

    usr << abs(1) // outputs 1 usr << abs(-1) // outputs 1

    addtext proc

    See also:
    + operator
    Format:
    addtext(Arg1,Arg2,...)
    Returns:
    A text string with the arguments concatenated.
    Args:
    Any number of text strings.

    This instruction returns text containing the first argument followed by the second, followed by the third, etc. The arguments may be constants or variables containing text.

    Example:

    var/T T = "1" T = addtext(T,"*1 = ",T) // T = "1*1 = 1" world << "The answer is: [T]"

    This instruction exists primarily for backwards-compatibility. You can accomplish the same thing with the + operator or by using embedded expressions.


    alert proc

    See also:
    input proc
    Format:
    alert(Usr=usr,Message,Title,Button1="Ok",Button2,Button3)
    Returns:
    Selected button

    This sleeps the current proc until the user clicks one of the named buttons. As with input(), the first argument may be entirely left out.

    Example:

    mob/verb/self_destruct() alert("Prepare to die.") del usr

    A slightly more complicated example provides the user with a choice in the matter:

    Example:

    mob/verb/self_destruct() switch(alert("Would you like to die?",,"Yes","No","Maybe")) if("Yes") del usr if("No") usr << "You have second thoughts." if("Maybe") usr << "You flip a coin..." if(rand(0,1)) usr << "Heads -- you lose." del usr else usr << "Tails -- you win!"

    animate proc

    See also:
    vars (atom)
    Format:
    animate(Object, var1=new_value1, var2=new_value2, ..., time, loop, easing)
    animate(var1=new_value1, var2=new_value2, ..., time, easing)
    animate(Object)
    Args:
    Object: The atom or image to animate.
    var1=new_value1, var2=new_value2, ...: Vars to change in the animation step.
    time: Time of this step, in 1/10s.
    loop: Number of times to show the animation, or -1 to loop forever
    easing: The "curve" followed by this animation step

    This proc creates an animation sequence that will be displayed to players. Starting with an atom or image, you can change one or more vars that affect its apprearance. This change will take place immediately, but will be displayed to users as a gradual change over a period of time.

    If the Object argument is left out, a new animation step will be created for the last object that was animated. If all other arguments are left out, this is tantamount to saying you want to start a new animation that does nothing, effectively ending the animation entirely.

    Example:

    mob/proc/GrowAndFade() // expand (scale by 2x2) and fade out over 1/2s animate(src, transform = matrix()*2, alpha = 0, time = 5) obj/spell/proc/Spin() // cast a spell on a monster: make the icon spin // this animation takes 3s total (6 ticks * 5) animate(src, transform = turn(matrix(), 120), time = 2, loop = 5) animate(transform = turn(matrix(), 240), time = 2) animate(transform = null, time = 2)

    The following vars will animate smoothly:

    These vars can be changed, but will change immediately on each step rather than smoothly:

    Easing

    Animation doesn't have to be strictly linear. Some changes look much better if they follow a curve. A cubic curve, for instance, will start slow, accelerate very quickly in the middle, and slow down again at the end. A sine curve could be used with a flip transformation to make a coin appear to spin. A text bubble can jump into place and bounce a little before it settles. The choice of curve you use is called easing, and you have several good choices to pick from.

    These can be combined with EASE_IN or EASE_OUT using the | operator, to use just the first or last part of the curve.

    Example:

    obj/coin/proc/Spin() var/matrix/M = matrix() M.Scale(-1, 1) // flip horizontally animate(src, transform = M, time = 5, loop = 5, easing = SINE_EASING) animate(transform = null, time = 5, easing = SINE_EASING) obj/speech_bubble/New(newloc, msg) icon = 'bubble.dmi' var/obj/O = new O.maptext = msg O.maptext_width = width O.maptext_height = height overlays = O // start below final position and jump into place pixel_z = -100 alpha = 0 animate(src, pixel_z = 0, alpha = 255, time = 10, easing = ELASTIC_EASING)

    arccos proc

    See also:
    arcsin proc
    cos proc
    turn proc
    Format:
    arccos(X)
    Returns:
    The inverse cos of X in degrees.

    Example:

    mob/verb/test() usr << arccos(0) //90 usr << arccos(0.707107) //45 usr << arccos(1) //0

    arcsin proc

    See also:
    arccos proc
    sin proc
    turn proc
    Format:
    arcsin(X)
    Returns:
    The inverse sin of X in degrees.

    Example:

    mob/verb/test() usr << arcsin(0) //0 usr << arcsin(0.707107) //45 usr << arcsin(1) //90

    arglist proc

    See also:
    arguments (proc)
    call proc
    list proc
    Format:
    arglist(List)
    Args:
    List: a list to be used as the arguments to a procedure

    Normally, if you were to pass a list directly to a procedure, it would only come through as a singe argument to that procedure. In some cases, you might instead want the items in the list to become the arguments to the procedure. That is what arglist() achieves.

    If the items in the list are associations, these are treated as named arguments. Each such list item is matched against the names of the procedure arguments and its associated value is assigned to that parameter.

    Most built-in DM instructions do not support use of arglist(), but all user-defined procedures automatically support it. The built-in instructions which support named arguments will also support arglist().

    The following example shows how to use arglist() with both positional parameters and named arguments. Both of these examples could be replaced by a much simpler direct call without need for a list to hold the arguments; this is just to illustrate the syntax.

    Example:

    proc/MyProc(a,b) usr << "MyProc([a],[b])" mob/verb/test() var/lst = list(1,2) MyProc(arglist(lst)) //MyProc(1,2) lst = list(b=2,a=1) //just to illustrate that order does not matter MyProc(arglist(lst)) //MyProc(b=2,a=1) --> MyProc(1,2)

    arguments (proc)

    See also:
    named arguments (proc)
    path operators

    The parameters to a proc are referred to as arguments. To define argument variables, place them inside the ()'s in the proc definition. A default value may be specified. Otherwise, arguments default to null.

    Example:

    proc/Sum(a,b) return a + b

    Example:

    proc/set_mob_desc(mob/M,desc="big and bad") M.desc = desc world << "The new desc for [M] is [desc]."

    Note how the variable type may be specified. It is just like any other variable definition, except "var/" is implicit and does not need to be typed.


    named arguments (proc)

    See also:
    New proc (atom)
    arglist proc
    arguments (proc)

    The parameters passed to a procedure are called arguments. These may either be passed in positional order, or they can be passed as named arguments. Not all procedures are defined with the intention of supporting named arguments, so consult the documentation for the procedure in question first. (This is mainly an issue of whether the argument names might change in the future.)

    The following example shows several ways of producing the same call to a procedure.

    Example:

    mob/proc/MyProc(a,b,c) src << "MyProc([a],[b],[c])" mob/verb/test() MyProc(1,2,3) //positional parameters MyProc(a=1,b=2,c=3) //named arguments MyProc(1,b=2,c=3) //positional and named arguments MyProc(c=3,a=1,b=2) //named arguments can come in any order

    To prevent silent errors, named arguments that do not match any of the arguments of the procedure being called will generate a runtime error. This is somewhat different from the behavior of positional arguments in DM where it is perfectly acceptable to pass more arguments than were explicitly defined in the procedure.

    As always, arguments that are not assigned in the call will simply be given the value null (or whatever default value is specified in the definition).

    When an object procedure is overridden, the variable names in the new definition are the ones that get matched against named arguments in a call to that procedure. A procedure which is intended to support named arguments should therefore be defined with care so as to conform to the interface expected by users of the procedure. That doesn't stop you from changing that interface when overriding a procedure, but the normal case would be to preserve the argument names of the base procedure when overriding it.

    The following example is not useful, but it illustrates a situation where a procedure is overridden so as to preserve the same argument names and positions. As mentioned above, you are not required to preserve either the names or positions, but that is usually what you want.

    Example:

    mob proc/MyProc(a,b,c) usr << "mob.MyProc([a],[b],[c])" mob/verb/test() MyProc(a=1,b=2,c=3) special_mob MyProc(a,b,c,d) if(d) ..() //pass in same order else ..(c,b,a) //pass in reverse order test() MyProc(a=1,b=2,c=3,d=0) //normal order MyProc(a=1,b=2,c=3,d=1) //reverse the order

    This example merely used positional parameters in the call to ..(), but one can use named arguments there too if it is desirable.

    The best time to use named arguments is when calling a procedure that takes a lot of optional parameters. You can just name the ones that you want to assign and leave the rest unspecified. Trying to do the same thing with positional parameters can be much more awkward--especially when the arguments you do want to assign are preceded by a number of ones that you don't care to assign. It's easy to lose your place in the list or to forget what it does.

    Since named arguments involve a slight amount of extra overhead, one should avoid them in code that is highly cpu intensive due to being called many many times. Otherwise, code clarity may be a bigger priority.


    ascii2text proc

    See also:
    entities (text)
    text2ascii proc
    Format:
    ascii2text(N)
    Returns:
    A text string.
    Args:
    N: A number.

    ASCII codes are numerical values corresponding to keyboard and special characters. Among other things, they are used to represent many symbols in HTML. This proc converts an ASCII code to its corresponding text representation.

    Example:

    T = ascii2text(65) // = "A"

    block proc

    See also:
    list
    Format:
    block(Start,End)
    Returns:
    The list of turfs in the 3D block defined by Start and End (inclusive).
    Args:
    Start: A turf to be the lower-left corner of the block.
    End: A turf to be the upper-right corner of the block.

    The following example shows how to loop over a block of turfs.

    Example:

    world maxx = 20 maxy = 20 mob/verb/block_test() var/turf/T for(T in block(locate(1,1,1),locate(10,10,1))) T.text = " "

    bounds proc

    See also:
    bound_x var (movable atom)
    bound_y var (movable atom)
    bound_width var (movable atom)
    bound_height var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    locs list var (movable atom)
    obounds proc
    Pixel movement
    Format:
    bounds(Ref=src, Dist=0)
    bounds(Ref, x_offset, y_offset, extra_width=0, extra_height=0)
    bounds(x, y, width, height, z)
    Returns:
    A list of atoms within the given bounding box.
    Args:
    Ref: A turf, obj, or mob.
    Dist: A number (distance in pixels).
    x_offset, y_offset: Shift to bounding box position (from Ref's bounding box)
    extra_width, extra_height: Adjustment to bounding box size (from Ref's bounding box)
    x, y, z: Lower left corner of bounding box in absolute coords; x=1,y=1 is lower left of map
    width, height: Size of bounding box in absolute coords

    To leave Ref out of the results, use obounds() instead.

    Calling bounds() will default to bounds(src,0), if src is a turf, obj, or mob. This returns all turfs, objs, and mobs (including src) within src's bounding box.

    Changing the distance will return all objects within that distance from the bounding box. E.g., bounds(turf,12) will show you everything within 12 pixels of that turf.

    An object's bounding box can also be offset. bounds(src,-6,0) shows what src would touching if it moved 6 pixels west. bounds(turf,-12,-12,24,24) is equivalent to bounds(turf,12).

    In the final form, bounds() can use absolute coordinates and does not need an object to be Ref. Absolute coordinates start at 1,1 at the lower left corner of the map, by tradition.


    bounds_dist proc

    See also:
    bound_x var (movable atom)
    bound_y var (movable atom)
    bound_width var (movable atom)
    bound_height var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    bounds proc
    Pixel movement
    Format:
    bounds_dist(Ref, Target)
    Returns:
    The distance, in pixels, between Ref's and Target's bounding boxes.
    Args:
    Ref: A turf, obj, or mob.
    Target: A turf, obj, or mob.

    The value returned by bounds_dist() is the number of pixels that the two objects would have to move closer together (if this is even possible, of course) to be touching but not overlapping.

    A return value of 12 for instance means the two objects have a gap of 12 pixels between them.

    A return value of 0 means the two objects are not overlapping, but their bounding boxes touch.

    A return value of -2 means the two objects are overlapping by 2 pixels; they would have to move 2 pixels apart to separate.


    break proc

    See also:
    continue proc
    do proc
    for loop proc
    while proc
    Format:
    break Label

    Terminate the loop with the given label. If no label is specified, the innermost loop containing the break statement is assumed.

    Example:

    obj/zapper verb/use() var/mob/M for(M in view()) if(!M.key) break if(!M) M = usr M << "ZAP!" del(M)

    The zapper object kills the first mob it finds that doesn't belong to a player. If none can be found, it kills the user. Be careful! Note how this code takes advantage of the fact that the loop variable M will be null if the loop terminates normally.

    For an example of how to use labeled loops, see the reference section for the continue statement.


    browse proc

    See also:
    << output operator
    browse_rsc proc
    file proc
    link proc
    run proc
    output proc
    Format:
    usr << browse(Body,Options)
    Args:
    Body: html text, file, or null to close the browser.
    Options: optional parameters

    This sends the html text or file to the user and optionally displays it in the web browser. The default action is to use the embedded browser panel in the Dream Seeker window; specifying an alternate window name (see below) causes it to appear in a popup window. Passing in 'null' for the html text causes the browser panel or named window to be closed.

    The option parameters should either be omitted or they should be in a text string of the following format: "window=name;file=name;display=1;
    size=300x300;border=0;can_close=1;
    can_resize=1;can_minimize=1;titlebar=1"

    You may use commas (,), ampersands (&), or semicolons (;) as the delimiter. Any or all of the parameters may be specified and they may be included in any order.

    General options

    These control how to handle the text or file.

    window
    This is the name used to identify the popup window. It is not visible to the user. Multiple calls to browse() with the same window name overwrite previous contents of the same popup window. If window is not specified, the embedded browser panel will be used.
    file
    When this is unspecified, the client will store the generated html file in the user's byond "cache" directory with an appropriate name. If Body is a text string, the client will generate a unique name. If it is a file, it will use the name of the file. You can override this by setting this parameter. This is only useful when you need to reference the file later, typically in tandem with the display setting below.
    display
    This controls whether the browser actually displays Body in the web browser or not. If it is turned off (display=0), the text or file is simply sent to the user and expected to be referenced later. This might be useful, for instance, to first send an image to a user and then display a web page that uses that image: usr << browse('monster.png',"display=0") usr << browse("<img src=monster.png>A scary monster appears from the mist!") Note that this performs the same function as the browse_rsc proc (preserved for legacy reasons). It is a little more powerful because you can use it to send html text as well as files. In that case, you'll have to also supply the file=name argument so that you can reference the html text from within a later browse().

    When display=0, all of the other arguments besides file are ignored.

    Popup options

    These control how the popup window initially appears. Setting these parameters for an existing popup window or the embedded browser has no effect.

    border
    This is the width of the border between the edges of the dialogue and the window content. The default value is 0, meaning that the entire window is filled with html content.
    size
    This is the size of the popup window in pixels. The format is WIDTHxHEIGHT.
    can_close
    This specifies whether the window should be closable. The default value is 1, which enables the standard "X" button for closing.
    can_resize
    This controls whether the window is resizable. The default value is 1, enabling resizing and maximizing.
    can_minimize
    This controls whether the window is minimizable. The default value is 1, enabling the standard minimization button.
    titlebar
    The default titlebar=1 enables the standard bar at the top of the window. Turning it off disables can_close and can_minimize.

    Note also that many display options can be controlled through the html itself. For instance, to turn off the scrollbars, you can do: <body scroll=no>; to add a title, you can do: <head><title>My Title</title></head>; and so forth.

    The following example displays a help page in a popup window.

    Example:

    var/const/help = {" <html> <head><title>Help!</title></head> <body> You are beyond help! </body> </html> "} client/verb/help() usr << browse(help,"window=help") You can use commands like output() and winset() to interact with popups. The name of the window is the same name you gave the popup, and the browser is "[windowname].browser".

    Example:

    client/verb/more_help() usr << output("You are still beyond help!", "help.browser")

    browse_rsc proc

    See also:
    browse proc
    Format:
    usr << browse_rsc(File,FileName)
    Args:
    File: a resource file (such as an image)
    FileName: name of file (if different from source file)

    This sends the specified resource file to usr (or anybody else) and stores it in their cache directory with the specified name. In subsequent browse() output, you can then refer to that file.

    If your world is always running on the internet, you can save yourself the trouble and simply link to the image files through a web server. However, if it may be played offline, you can compile in the resource files and manually send them to players with browse_rsc().

    Note that no data is transmitted if it already exists in the user's cache, so there is little overhead in calling this every time you are about to use browse().

    Example:

    area var room_graphic = 'cozy_room.jpg' Enter(O) . = ..() //do default checks if(.) //if we got clearance to enter O << browse_rsc(room_graphic,"room.jpg") O << browse("<p><img src=room.jpg></p>[desc]")

    call proc

    See also:
    arglist proc
    hascall proc
    path operators
    Format:
    call(ProcRef)(Arguments)
    call(Object,ProcName)(Arguments)
    call(LibName,FuncName)(Arguments)
    Args:
    ProcRef: path of proc (/proc/MyProc)
    Object: source of proc or verb
    ProcName: name of proc or verb ("MyProc")
    LibName: name of external library ("test.DLL")
    FuncName: name of function in external library ("func")
    Returns:
    The return value of the proc being called.

    This instruction exists in order to call procs dynamically, since the proc reference or name may be an expression rather than a hard-coded value. This may serve the same purpose as a "function pointer" in C programs.

    The following examples do not demonstrate why you would want to do this, but the syntax is illustrated. The first one calls a specific procedure by using a path reference to that procedure.

    Example:

    /proc/MyProc(Arg) usr << "MyProc([Arg])" mob var MyProc = /proc/MyProc verb call_myproc() call(MyProc)("Hello, world!")

    The next example calls an object procedure (or verb) by name, rather than by path.

    Example:

    mob proc Proc1(Arg) usr << "Proc1([Arg])" Proc2(Arg) usr << "Proc2([Arg])" verb call_proc(Proc in list("Proc1","Proc2")) call(src,Proc)("Hello, world!") call() may also be used to access third-party libraries (.DLL files on windows, .SO files on unix), as long as the one or more of the following conditions is met: These functions must be prototyped in the DLL as: extern "C" char *func(int argc, char *argv[]) // argc = #arguments, argv[] = array of arguments

    Example:

    // test.dll, a win32 C++ library compiled in VC++: #include <string.h> // This is an example of an exported function. // windows requires __declspec(dllexport) to be used to // declare public symbols // the name of the function from within the dll may be compiler-dependent // (in this case it will usually be "merge" or "_merge) // Google "name decoration" for more information on this exciting topic. extern "C" __declspec(dllexport) char *merge(int n, char *v[]) { static char buf[500]; *buf=0; for(int i=0;i<n;i++) { strcat(buf,v[i]); // we should bounds-check but it's a stupid example! } return buf; } // DM code to use test.dll mob/verb/test() usr << call("test.dll","merge")("fee","fi","fo") // returns "feefifo" // As with the other call() versions, arglist() may be used to do runtime arguments: mob/verb/argtest() var/L = list("fee","fi","fo") usr << call("test.dll","func")(arglist(L)) // returns "feefifo" As the library prototype is char**, the call() arguments must be strings. Other types (like numbers) will be passed as the empty string ("") into the library function.

    Note for advanced users: on windows, call() uses the __cdecl convention by default. If you are designing or linking to a dll that uses the __stdcall convention instead, you can inform call() by prefacing the function name with the "@" symbol, eg, call("test.dll","@merge") would call a version of "merge" declared with the __stdcall convention. Typically these names are further decorated by the linker (in VC++, "merge" would be "_merge@8", so it'd be accessed with call("test.dll",@_merge@8")).


    ckey proc

    See also:
    ckeyEx proc
    ckey var (mob)
    savefile
    Format:
    ckey(Key)
    Args:
    Key: The player key to convert to canonical form.
    Returns:
    The key in canonical form. To do this, it strips all punctuation and space from the key and converts to lowercase. The result is still unique for each different key.

    The result could be used as a unique directory name in a server-side save file. Each player could be stored in a separate directory. By converting to canonical form, possible problems resulting from punctuation (like the path delimiter '/') in the key would be avoided. If players are saved in stand-alone files, it could be equally useful for generating a unique file name.

    Note that this may be used on any text string. It is not just limited to keys.

    Example:

    var/savefile/SaveFile = new("world.sav") proc/SavePlayer(mob/M) var/keydir = ckey(M.key) SaveFile.cd = "/players" SaveFile.cd = keydir M.Write(SaveFile) proc/LoadPlayer(mob/M) var/keydir = ckey(M.key) SaveFile.cd = "/players" if(!SaveFile.Find(keydir)) return 0 SaveFile.cd = keydir M.Read(SaveFile) return 1

    This example defines two procs for saving and loading players to a server-side file. These could be called in mob.Login() and mob.Logout(). Notice that instead of calling SaveFile.Write(M), this example instead calls M.Write(SaveFile) directly. The difference is that in this example we did not want a new mob to be created when loading the player but instead wanted to load information into an existing mob.

    In this example, the ckey() proc was used, but it would be more efficient to use mob.ckey, which is the same value precomputed.


    ckeyEx proc

    See also:
    ckey proc
    Format:
    ckeyEx(Text)
    Args:
    Text: The text string to convert to case-sensitive canonical key form.
    Returns:
    The same text stripped of all punctuation and space. Unlike, ckey(), case is preserved as are the '-' and '_' characters.

    The true canonical form of a key is in all lowercase, but occasionally, it is nice to preserve case when stripping a key (or other text) of any special characters.

    Note: This proc used to be named cKey, like ckey but with a capital k. To avoid confusion it has been renamed, but old code will still compile.


    cmptext proc

    See also:
    cmptextEx proc
    Format:
    cmptext(T1,T2,...)
    Returns:
    1 if all arguments are equal; 0 otherwise.
    Args:
    Any number of text strings to compare.

    This instruction is NOT sensitive to case. It also ignores the \proper and \improper text macros. The case-sensitive version is cmptextEx().

    Example:

    if(cmptext("Hi","HI")) world << "Equal!" else world << "Not equal!"

    This outputs "Equal!" since "Hi" and "HI" are the same, ignoring case.


    cmptextEx proc

    See also:
    cmptext proc
    Format:
    cmptextEx(T1,T2,...)
    Returns:
    1 if all arguments are equal; 0 otherwise.
    Args:
    Any number of text strings to compare.

    This instruction is sensitive to case. The case-insensitive version is cmptext().

    Because identical text is internally combined to conserve memory, cmptextEx(T1,T2) is equivalent to (T1 == T2).

    Example:

    if(cmptextEx("Hi","HI")) world << "Equal!" else world << "Not equal!"

    This outputs "Not equal!" since "Hi" and "HI" are different when taking case into account.

    Note: This proc used to be named cmpText, like cmptext but with a capital T. To avoid confusion it has been renamed, but old code will still compile.


    continue proc

    See also:
    break proc
    do proc
    for loop proc
    while proc
    Format:
    continue Label

    Begins the next iteration of the loop with the given label. If no label is specified, the innermost loop containing the continue statement is assumed.

    Example:

    client/verb/who() var/mob/M usr << "Players:" for(M in world) if(M == usr) continue if(M.key) usr << M.key

    This displays a list of players who have a mob in the world. The continue statement is used here to avoid including the user in the list. The same thing could have been achieved by using only the if statement. In more complicated situations, however, very long conditional expressions and deeply nested if statements can be avoided by using continue and its companion break.

    Here is an example using a label to continue an outer loop from inside an inner one:

    client/verb/loners() var/mob/M var/mob/G usr << "Loners:" finding_loners: for(M in world) for(G in world) if(M in G.group) continue finding_loners //found a loner usr << M.name

    This displays a list of mobs who do not belong in anyone else's group. Notice the syntax for labeling a list. The name of the block is simply placed in the code followed by a colon and its contents are indented inside it.


    copytext proc

    Format:
    copytext(T,Start=1,End=0)
    Returns:
    A text string.
    Args:
    T: A text string.
    Start: The text character position in which to begin the copy.
    End: The text character position immediately following the last character to be copied.

    Copy characters in T between Start and End. The default end position of 0 stands for the lentext(T)+1, so by default the entire text string is copied.

    Example:

    pre = copytext("Hi there",1,3))// = "Hi" post = copytext("Hi there",4)) // = "there"

    If the start or end position is negative, it counts backwards from the end of the string.

    Example:

    post = copytext("Hi there",-5)) // = "there"

    cos proc

    See also:
    arccos proc
    sin proc
    turn proc
    Format:
    cos(X)
    Returns:
    The cos of X, where X is in degrees.

    Example:

    mob/verb/test() usr << cos(0) //1 usr << cos(45) //0.707... usr << cos(90) //0

    del proc

    See also:
    Del proc (datum)
    garbage collection
    Format:
    del Object
    Args:
    Object: Any data object (datum, savefile, world, you name it)

    Destroy an object and null out all references to it. Procs that are executing with src equal to that object are silently killed, causing execution to return to the caller. If that is not what you want, you should detach the proc from the source object by setting src to null.

    When an object is deleted, its Del() procedure is called. Currently, if the Del() procedure does not execute the default action (by calling ..()), then the deletion of the object is aborted. You should not depend on this, as it may change. In other words, be sure to always call the default handler after doing your own stuff.

    Example:

    mob/Del() src << "Aaaaaaaah!" ..() mob/verb/self_destruct() del usr

    do proc

    See also:
    break proc
    continue proc
    for loop proc
    while proc
    Format:
    do Statement while( E )

    Execute Statement. If E is true (non-zero) do it over again. Continue until E is false (zero).

    Statement may be a block of code or a single statement.

    Example:

    var/i = 3 do world << i-- while(i)

    This outputs:

    3 2 1

    fcopy proc

    See also:
    fcopy_rsc proc
    shell proc
    Format:
    fcopy(Src,Dst)
    Args:
    Src: file to copy
    Dst: new copy to make
    Returns:
    1 on success; 0 otherwise.

    Src may be either a cache file, a savefile, or the name of an external file. Cache files are specified in single quotes and external files are in double quotes. If the path to the destination file does not already exist, it will be created.

    If the source and target are paths ending in "/", the contents of the source directory (including sub-directories) will be copied to the target path.

    This instruction could be useful when players upload files (like code) that you might want to dump to an external file.

    Example:

    mob/verb/change_world(F as file) fcopy(F,"world.dm") shell("DreamMaker world") world.Reboot()

    This (somewhat dangerous) example allows players to upload code, recompile, and reboot the world. It assumes that DreamMaker is in the path where the shell looks for executable files and also that the name of the running world is world.dmb.


    fcopy_rsc proc

    See also:
    cache
    fcopy proc
    file proc
    Format:
    fcopy_rsc(File)
    Args:
    File: file to copy into the resource cache
    Returns:
    reference to the file as a cache entry

    The file to copy may either be a file name (text string) or the return value of file() operating on the same. If a cache entry is passed as the argument, it will simply be returned with no action necessary.

    Once a file has been copied into the resource cache (i.e. the world's .rsc file), it may be used as an icon or a sound or whatever is appropriate. Most internal operations involving resource files automatically perform this operation when you try to use an external file in place of a cache entry. For example, when assigning a file() object to atom.icon, fcopy_rsc() is implicitly invoked.

    The main reason you would ever want to call this explicitly is if you are storing references to resource files in your own data structures and you want to ensure that all values are converted to cache entries so they may be directly compared to one another.


    fdel proc

    See also:
    shell proc
    Format:
    fdel(File)
    Args:
    File: name of file to delete
    Returns:
    1 on success; 0 otherwise.

    If the specified file ends in '/', it is treated as a directory. Any contents (including sub-directories) are deleted as well.

    Be careful!


    fexists proc

    See also:
    flist proc
    length proc
    Format:
    fexists(File)
    Args:
    File: name of file to test
    Returns:
    1 if file exists; 0 otherwise.

    file proc

    See also:
    << output operator
    fcopy_rsc proc
    ftp proc
    isfile proc
    link proc
    run proc
    savefile
    sound proc
    Format:
    file(Path)

    Returns a file object corresponding to the named file. This file object can then be used in a variety of ways. One would be to send it to a player to view using the browse() instruction. Output may also be appended to the file using the << operator.

    Note that the file exists in the external filesystem (ie the hard disk) and not the cache. That means the path is specified in double quotes and will be evaluated at run-time rather than compile-time. The file need not exist at compile time and may even be modified at a later date. This is the principle reason for using a file in the filesystem rather than a cached resource file (specified in single quotes).

    Example:

    mob/verb/help() usr << browse(file("help.html"))

    Many DM instructions that deal with files treat file("name") and "name" the same. There are cases such as browse() where a simple text string is not interpreted as a filename; it is in those situations where file() is really necessary.


    file2text proc

    See also:
    shell proc
    text2file proc
    Format:
    file2text(File)
    Args:
    File: file to read
    Returns:
    the contents of the file.

    This can be useful when interacting with external applications that generate output in a text file. For example, you might have an external program that mimics conversation:

    Example:

    mob/oracle/verb/tell(T as text) text2file(T,"talk.in") shell("talk < talk.in > talk.out") usr << file2text("talk.out")

    findtext proc

    See also:
    findtextEx proc
    Format:
    findtext(Haystack,Needle,Start=1,End=0)
    Returns:
    The position of Needle in Haystack; 0 if not found.
    Args:
    Haystack: The text string to search.
    Needle: The sub-text to search for.
    Start: The text character position in Haystack in which to begin the search.
    End: The text character position in Haystack immediately following the last character to search.

    This instruction is NOT sensitive to the case of Haystack or Needle. The case-sensitive version is findtextEx().

    Example:

    if(findtext("Hi There","there")==0) world << "Not found!" else world << "Found!"

    This outputs "Found!", since "there" is a part of the string "Hi There", ignoring case.

    If the start or end position is negative, the position is counted backwards from the end of the string. E.g., findtext("Banana", "na", -3) starts three characters from the end and only searches the final "ana".


    findtextEx proc

    See also:
    findtext proc
    Format:
    findtextEx(Haystack,Needle,Start=1,End=0)
    Returns:
    The position of Needle in Haystack; 0 if not found.
    Args:
    Haystack: The text string to search.
    Needle: The sub-text to search for.
    Start: The text character position in Haystack in which to begin the search.
    End: The text character position in Haystack immediately following the last character to search.

    This instruction is sensitive to the case of Haystack and Needle. The case-insensitive version is findtext().

    Example:

    if(findtextEx("Hi There","there")==0) world << "Not found!" else world << "Found!"

    This outputs "Not found!", since "there" is not a part of the string "Hi There", taking into account case.

    If the start or end position is negative, the position is counted backwards from the end of the string. E.g., findtextEx("Banana", "na", -3) starts three characters from the end and only searches the final "ana".

    Note: This proc used to be named findText, like findtext but with a capital T. To avoid confusion it has been renamed, but old code will still compile.


    flick proc

    See also:
    icon_state var (atom)
    Format:
    flick(Icon,Object)
    Args:
    Icon: An icon file or state name.
    Object: The target object.

    Cause the icon attached to Object to be temporarily replaced with the specified icon or icon state for the duration of the animation. This is a purely visual effect and does not effect the actual value of the object's icon variable.

    Example:

    flick('blink.dmi',usr) //show another icon flick("fight",usr) //show usr's fight state

    flist proc

    See also:
    fexists proc
    Format:
    flist(Path)
    Args:
    Path: The path in the filesystem to get a listing of.
    Returns:
    A list of files contained in the specified directory and whose names begin with the specified text. The names of sub-directories are listed too, and are marked by a trailing "/".

    The path is of the form "dir1/dir2/.../file". Only files beginning with the "file" part are listed, so be sure to end a directory name with "/" if you wish to see its contents. Otherwise you will just get that directory name back with a "/" appended.

    Only files and sub-directories directly contained in the specified path are listed (ie not the contents of the sub-directories too). The file names in the list do not include the path information but just the bare file name.


    for proc

    See also:
    for list proc
    for loop proc

    The for proc can be used to iterate values over a fixed range or list. Consult the appropriate entry for more information.


    for list proc

    See also:
    for loop proc
    list
    Format:
    for (Var [as Type] [in List]) Statement
    Args:
    Var: A variable to sequentially contain each member of the list.
    List: The list to loop through. This defaults to the whole world.
    Type: One or more of area, turf, mob, or obj, ORed together. If no type is specified, the declared type of Var will be used to skip over inappropriate elements in the list.

    Example:

    usr << "Mobs:" var/mob/M for(M in view()) usr << M.name

    This loops M through the mobs in view(), outputting the name at each iteration.

    You can declare the variable right inside the for statement. Its scope is entirely contained within the for statement, so it will not conflict with a similar variable declared elsewhere in the same procedure.

    Example:

    client/verb/who() for(var/client/Player) usr << Player

    for loop proc

    See also:
    break proc
    continue proc
    do proc
    for list proc
    while proc
    Format:
    for(Init, Test, Inc) Statement

    First execute Init. Then if Test is true (non-zero), execute Statement. After this execute Inc. Continue checking Test, doing Statement, and performing Inc until Test turns out to be false (zero).

    Statement may be a code block or a single statement. Semicolons may be substituted for commas inside the parentheses as a convenience to C/C++ programmers.

    Init and Inc may be omitted. If Test is omitted, the loop will continue forever (unless a break, goto, or return instruction is used to get out of the loop).

    Example:

    var/i for(i=0, i<3, i++) world << i

    This outputs:

    0 1 2

    ftp proc

    See also:
    << output operator
    browse proc
    file proc
    link proc
    run proc
    sound proc
    Format:
    O << ftp(File,Name)

    Sends a file to O with the (optional) suggested name for saving to disk. The file may be a cache file (loaded at compile time) or an external file (accessed at run-time). Cache files are specified in single quotes, and external files are in double quotes.

    This function could be used to distribute source code, supplementary documentation, or anything.

    Example:

    mob/verb/geticon(O in view()) usr << ftp(O:icon)

    This example allows the user to download the icons from other objects in the game.


    get_dir proc

    See also:
    dir var (atom)
    Format:
    get_dir(Loc1,Loc2)
    Returns:
    The direction from Loc1 to Loc2. Possible results are NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, and SOUTHWEST. An approximation will be made if the true direction is not exactly in line with one of these.
    Args:
    Loc1: An object on the map.
    Loc2: An object on the map.

    If the direction is not directly lying along one of the four primary cardinal directions, the result will become the nearest diagonal direction (eg. if Loc2 is mostly north but a little to the east of Loc1, the direction returned will be NORTHEAST).


    get_dist proc

    See also:
    bounds_dist proc
    Format:
    get_dist(Loc1,Loc2)
    Returns:
    The distance between Loc1 and Loc2, in tiles. This is the number of full-tile movements (disregarding any obstacles and allowing diagonal moves) required to go from one to the other.
    Args:
    Loc1: An object on the map.
    Loc2: An object on the map.

    At this time, get_dist() never returns a value greater than 127.

    For a distance in pixels, use bounds_dist().


    get_step proc

    See also:
    step proc
    walk proc
    Format:
    get_step(Ref,Dir)
    Returns:
    The location of the new position.
    Args:
    Ref: Starting point or object.
    Dir: One of NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, SOUTHWEST.

    Calculate the position of a step from Ref in the direction Dir.


    get_step_away proc

    See also:
    step_away proc
    walk_away proc
    Format:
    get_step_away(Ref,Trg,Max=5)
    Returns:
    The location of the new position, or 0 if no change.
    Args:
    Ref: Starting point or object.
    Trg: An object on the map.
    Max: The maximum distance between Ref and Targ before movement halts.

    Calculate position of a step from Ref on a path to Trg, taking obstacles into account. If Ref is farther than Max steps from Trg, 0 will be returned.


    get_step_rand proc

    See also:
    step_rand proc
    walk_rand proc
    Format:
    get_step_rand(Ref)
    Returns:
    The location of the new position, or 0 if no change.
    Args:
    Ref: Starting point or object.

    Calculate position of a step from Ref in random motion.


    get_step_to proc

    See also:
    step_to proc
    walk_to proc
    Format:
    get_step_to(Ref,Trg,Min=0)
    Returns:
    The location of the new position, or 0 if no change.
    Args:
    Ref: Starting point or object.
    Trg: An object on the map.
    Min: The minimum distance between Ref and Trg before movement halts.

    Calculate the position of a step from Ref on a path to Trg, taking obstacles into account. If Ref is within Min steps of Trg, no step is computed. This is also true if the target is too far away (more than twice world.view steps). In either case, null is returned.


    get_step_towards proc

    See also:
    step_towards proc
    walk_towards proc
    Format:
    get_step_towards(Ref,Trg)
    Returns:
    The location of the new position.
    Args:
    Ref: Starting point or object.
    Trg: An object on the map.

    Calculate the position of a step from Ref in the direction of Trg.


    goto proc

    Format:
    goto node

    Jump to the specified node in the current proc.

    Example:

    goto End world << "ERR" End world << "The end"

    This displays "The end".


    hascall proc

    See also:
    call proc
    Format:
    hascall(Object,ProcName)
    Args:
    Object: source of proc or verb
    ProcName: name of proc or verb ("MyProc")
    Returns:
    1 if object has such a proc or verb; 0 otherwise

    hearers

    See also:
    ohearers
    view proc
    viewers
    Format:
    hearers(Depth=world.view,Center=usr)

    This is just like viewers(), but it is a list of mobs that can hear the center object. Currently, this is computed on the assumption that opaque objects block sound, just like they block light.


    html_decode proc

    See also:
    html_encode proc
    Format:
    html_decode(HtmlText)
    Args:
    HtmlText: text to be "unescaped"
    Returns:
    unescaped text

    Special characters such as < and > are not displayed literally in html and may produce garbled output. To display these characters literally, they must be "escaped". For example, < is produced by the code &lt; and > is produced by the code &gt;.

    The html_decode() instruction takes a text string containing such escaped symbols and turns them into their literal counterparts. The more useful function is html_encode() which does the reverse.


    html_encode proc

    See also:
    html_decode proc
    Format:
    html_encode(PlainText)
    Args:
    PlainText: text to be html "escaped"
    Returns:
    escaped text

    Special characters such as < and > are not displayed literally in html and may produce garbled output. If you want to ensure that an entire text string is displayed literally, you can "escape" those characters. For example, < is produced by the code &lt; and > is produced by the code &gt;.

    The html_encode() instruction does this for you automatically. If you wanted to disallow html input from players, you could use this to force their text to be displayed literally:

    Example:

    mob/verb/say(T as text) view() << "[usr] says, '[html_encode(T)]'"

    If a URL is included in the text, special characters like & that are part of the URL will be skipped. This keeps automatically created links in the output from being broken.

    Note for BYOND oldies: the old-style formatting codes such as "\red" which are still parsed but not encouraged are completely stripped out by html_encode().


    icon proc

    See also:
    file proc
    icon_states proc
    icons
    Format:
    icon(file,state,dir,frame,moving)
    (supports named arguments)
    Args:
    file: an icon file or /icon object
    icon_state: an optional text string, specifying a single icon state to load
    dir: an optional direction to extract
    frame: an optional animation frame to extract
    moving: Non-zero to extract only movement states, 0 for non-movement states, or null (default) for both

    This is equivalent to new/icon(). It creates an /icon object, which is initialized to contain the same graphical data as the given file. If an icon state or direction are specified, only those parts of the original icon will be included in the new icon object.


    icon_states proc

    See also:
    icons
    icon_size var (world)
    map_format var (world)
    Big icons
    Tiled icons
    Format:
    icon_states(Icon, mode=0)
    Returns:
    A list of text strings.
    Args:
    Icon: the icon being accessed
    mode: applies to icons larger than one tile when using map_format=TILED_ICON_MAP; see below

    Icons may have one or more internal states, which are identified by name. The state "" is the default.

    If you are not using the TILED_ICON_MAP value for world.map_format, you can ignore the mode argument.

    When graphics bigger than world.icon_size are used as an icon, and the map_format in use is TILED_ICON_MAP, they are internally broken up into tiles, one per icon state. The mode argument was added for big icons that get split into several smaller tiles. Those icons have several smaller states per true icon_state. For example if your 64×64 icon has a state named "open", it will contain states "open", "open 0,0", "open 1,0", "open 0,1", and "open 1,1" which are all used internally. (If the state name is blank, the sub-states are just "0,0", etc.) When using the TILED_ICON_MAP format, you need these for displaying the icon over several different atoms.

    mode=0 will only show the sub-states ("open 0,0" and so on), all of which can be safely extracted in a single-tile icon via the icon() proc. mode=1 will show the main state names ("open"); any time you work with that state name you're working with the full-size icon. mode=2 will show all of the states.


    if proc

    See also:
    goto proc
    Format:
    if( E ) Statement1
    else if( E2 ) Statement2
    else Statement3

    If the expression E is true (non-zero) then execute Statement1. Otherwise, test E2, etc. Finally, if none of the expressions are true, execute Statement3. The else nodes are all optional.

    Statement1, Statement2, and Statement3 may be a single statement or a code block with optional braces: {}.

    Example:

    if(T==1) world << "TRUE" else world << "FALSE"

    This will display "TRUE" if T has value 1, and "FALSE" otherwise.


    image proc

    See also:
    << operator
    del proc
    icon
    image objects
    images var (client)
    overlays var (atom)
    Format:
    image(icon,loc,icon_state,layer,dir)
    (supports named arguments)
    Returns:
    An image reference on success; 0 on failure.
    Args:
    icon: An icon, object prototype, object instance, or other image.
    loc: The location at which to display the image.
    icon_state: The icon state to use.
    layer: The drawing layer to use.
    dir: The direction to orient the image.

    Images are "virtual" objects, which have a purely visual effect. Once created, they can be made to appear to selected players. The image() instruction is simply a short-hand for new/image().

    The image remains attached to the location specified by loc. For example, if loc is a mob, the image will appear above the mob until it is destroyed.

    The arguments icon_state, layer, and dir may be used to override the settings associated with the icon or object used to create the image. For example, the default drawing layer for an plain icon is FLY_LAYER (above all other objects), but you could change this to OBJ_LAYER to make it appear under mobs on the map.

    Example:

    var/Box Box = image ('highlight.dmi', usr) usr << Box ... del(Box) //when done, remove image

    Another common use of images is in making an overlay:

    overlays += image('pants.dmi',icon_state = "red")

    Since the loc argument could never be a text string, the above statement can be further shortened:

    overlays += image('pants.dmi',"red")

    This is much preferable to achieving the same effect with icon('pants.dmi',"red"), since that involves the overhead of creating a new icon file, which should only be done when it is really necessary.


    initial proc

    See also:
    issaved proc
    vars list var (datum)
    Format:
    initial(Var)
    Args:
    Var: A variable to find the initial value of.

    This returns the original compile-time value of a variable. It could be used to reset a variable to its default value or to check if a variable has changed.

    Example:

    obj/verb/set_icon(I as null|icon) if(!I) I = initial(icon) icon = I This example allows an object's icon to be modified. If the user does not specify a new icon, it will be reset to the original one.

    input proc

    See also:
    alert proc
    arguments (verb)
    Format:
    input(Usr=usr,Message,Title,Default) as Type in List
    Returns:
    User's response.

    This sleeps the current proc until the user responds to the input dialog. The only required argument is the message. The type may be any combination of input types allowed for verb arguments. The default is text.

    Example:

    mob/verb/create_character() usr.name = input("Choose a name for your character.", "Your Name", usr.name) usr.gender = input("Select a gender for your character.", "Your Gender", usr.gender) in list("male","female","neuter")

    If the target of the input prompt is not a player, the result will be the default value. If no default value is specified and null is allowed by the input type, that will be returned. Otherwise, an error will result, crashing the proc that called input().


    isarea proc

    See also:
    isloc proc
    Format:
    isarea(Loc1, Loc2 ...)
    Returns:
    1 if all args are valid areas; 0 otherwise
    Args:
    Any number of locations to test.

    isfile proc

    See also:
    cache
    file proc
    isicon proc
    Format:
    isfile(File)
    Args:
    File: the value to test

    This returns a true value when given a file. Both objects returned by file() and files stored in the resource cache qualify.


    isicon proc

    See also:
    cache
    icon
    isfile proc
    Format:
    isicon(Icon)
    Args:
    Icon: the value to test

    This returns a true value when given an icon. Both /icon memory objects and icon files stored in the resource cache qualify.


    isloc proc

    Format:
    isloc(Loc1, Loc2 ...)
    Returns:
    1 if all args are valid locs; 0 otherwise.
    Args:
    Any number of locations to test.

    Tests validity of a location. If the argument is a mob, obj, turf, or area, this returns 1.

    This is equivalent to: (ismob(Loc) || isobj(Loc) || \ isturf(Loc) || isarea(Loc))


    ismob proc

    See also:
    isloc proc
    Format:
    ismob(Loc1, Loc2 ...)
    Returns:
    1 if all args are valid mobs; 0 otherwise
    Args:
    Any number of locations to test.

    isnull proc

    See also:
    null
    Format:
    isnull(Val)
    Returns:
    1 if Val is null; 0 otherwise

    isnum proc

    Format:
    isnum(Val)
    Returns:
    1 if Val is a number; 0 otherwise

    isobj proc

    See also:
    isloc proc
    Format:
    isobj(Loc1, Loc2 ...)
    Returns:
    1 if all args are valid objs; 0 otherwise
    Args:
    Any number of locations to test.

    ispath proc

    See also:
    ispath proc
    typesof proc
    Format:
    ispath(Val)
    ispath(Val,Type)
    Returns:
    single-argument: 1 if Val is a type path
    double-argument: 1 if Val is a type path derived from Type; 0 otherwise.
    Args:
    Val: A type path.
    Type: A type path or instance.

    Example:

    var/M M = /mob/ugly/duckling if(ispath(M,/mob/ugly)) //true if(ispath(M)) //true if(ispath(new/mob)) //false

    issaved proc

    See also:
    initial proc
    savefile
    tmp vars
    vars list var (datum)
    Format:
    issaved(Var)
    Args:
    Var: The variable to test.

    This returns 1 if the given variable should be automatically saved when writing an object to a savefile and 0 otherwise. Variables which are not global, const, or tmp will return 1.


    istext proc

    Format:
    istext(Val)
    Returns:
    1 if Val is text; 0 otherwise

    isturf proc

    See also:
    isloc proc
    Format:
    isturf(Loc1, Loc2 ...)
    Returns:
    1 if all args are valid turfs; 0 otherwise
    Args:
    Any number of locations to test.

    istype proc

    See also:
    ispath proc
    locate proc
    typesof proc
    Format:
    istype(Val,Type)
    Returns:
    1 if Val is derived from Type; 0 otherwise.
    Args:
    Val: An object instance.
    Type: An object prototype or instance. If no type is specified and a variable was passed in as the first argument, it will default to the declared type of the variable.

    If you don't have an object instance to test, but just want to see if one prototype derives from another one, use ispath() instead.

    Example:

    var/M M = new/mob/ugly/duckling() if(istype(M,/mob/ugly)) //this will be true usr << "[M] is ugly!"

    Using implicit types, that same example can be rewritten as follows:

    var/mob/ugly/M M = new/mob/ugly/duckling() if(istype(M)) //this will be true usr << "[M] is ugly!"

    length proc

    Format:
    length(E)
    Returns:
    The length of the data associated with E.
    Args:
    E: a text, list, or file

    Example:

    world << length("Hi")

    This outputs, "2", the length of the string "Hi".

    Example:

    world << length(list(1,2,3))

    This outputs, "3", the length of the list.

    Example:

    world << length(file("test.txt"))

    This outputs the length of the file.


    lentext proc

    See also:
    length proc
    Format:
    lentext(T)
    Returns:
    The length of text T.
    Args:
    T: A text string.

    This instruction is obsoleted by length().

    Example:

    world << lentext("Hi")

    This outputs, "2", the length of the string "Hi".


    link proc

    See also:
    << output operator
    Topic proc (client)
    file proc
    run proc
    Format:
    O << link(url)

    This causes the recipient (O) to view the specified url. The url could be a web or BYOND address. In the latter case, the player will disconnect from the current world and connect to the specified one.

    The format of a BYOND url is as follows:

    byond://address:port?TopicData

    To access a registered world, address:port may be replaced by the registered name in the hub. The optional topic data is processed by the world once the player has connected. If only a topic is specified, the current world processes it.

    Example:

    usr << link("byond://byond.com:6000") //BYOND address usr << link("http://www.byond.com") //web address usr << link("?myTopic") //topic

    list proc

    See also:
    arglist proc
    list
    list associations
    Format:
    list(A,B,C,...)
    or
    list(A=a,B=b,C=c,...)
    Returns:
    A new list with contents A, B, C, and (optional) associated values a, b, c.
    Args:
    Arbitrary number of elements to be inserted into the list.

    Assign elements to a list.

    Example:

    var/L[] L = list(1,2,3)

    This creates a new list 'L' that initially contains elements 1, 2, and 3. The length of L is 3.

    The list() instruction may also be used to create associative lists.

    Example:

    var/list/lst = list("player" = "James Byond", "score" = 2000)

    That creates a list with contents ("player, "score") and associated values ("James Byond", 2000) respectively.

    The index values should be constants, and that usually means text constants. When these index values happen to be text strings that satisfy all the requirements for variable names, this may also be written in a convenient short-hand without the double quotes:

    var/list/lst = list(player = "James Byond", score = 2000)

    In other words, this is exactly the same syntax as for named arguments.


    list2params proc

    See also:
    Topic proc (client)
    list associations
    params var (world)
    params2list proc
    text2num proc
    Format:
    list2params(List)
    Args:
    List: List to encode as a text string.

    This instruction converts a list of parameter names and associated values into a single text string suitable for use in a URL or similar situation. The format of the resulting text string is:

    "name1=value1&name2=value2&..."

    Special characters such as '=' and '&' inside the parameter names or values are written in the form: %xx where xx are two hexadecimal digits representing the ASCII value of the character. In addition, spaces are converted to '+'.

    This parameter format is the same one used by most html forms and is known by the MIME type 'application/x-www-form-urlencoded'. It is often used in DM to pack information into topic links.

    The original list has items "name1", "name2", and so on. These in turn are associated with the corresponding values value1, value2, and so on.

    Example:

    var/plist[0] plist["offense"] = "jwalk" plist["time"] = "10:00" usr << list2params(plist)

    The above example creates a simple parameter list which associates the item "offense" with the value "jwalk" and the item "time" with the value "10:00". This will produce the text string "offense=jwalk&time=10:00".

    Object values in the list (like say a mob) get turned into references in the parameter text, just as though you had embedded them with "\ref[Object]". When read back in with params2list(), you could convert these values back into real references by using locate().


    locate proc

    See also:
    istype proc
    tag var (datum)
    Format:
    locate(Type) in Container
    locate(X,Y,Z)
    locate(Tag)
    locate(TextRef)
    Returns:
    An object of the specified type or the turf at the given coordinates. If a text string is given in place of an object type, the object with the same tag is found. If a container is given, only objects directly within that object are searched.
    Args:
    Type: An object prototype or tag. If locate() is being used in an assignment to a variable with a declared type, this argument is optional and will default to the type of the variable being assigned.
    Container: An optional container object. (The default is world.)
    X,Y,Z: A set of numerical coordinates.
    Tag: The value of an object's tag variable (must be unique).
    TextRef: An embedded object reference created by the \ref text macro.

    Types are matched in the same manner as istype(). In other words, locate(/obj) could return an instance of something derived from /obj, such as /obj/armor.

    If there is more than one instance of the specified type, the first one found will be chosen.

    Example:

    var/mob/shopkeeper/M = locate() if(M) usr << "Found the shopkeeper." else usr << "Could not find the shopkeeper."

    This looks for a mob of a type /mob/shopkeeper in the world (world.contents).

    Example:

    usr.Move(locate(/turf/Home))

    This "teleports" the usr to a turf of the type /turf/Home.

    Example:

    usr.Move(locate(1,2,3))

    This moves the usr to the turf at coordinates (x,y,z) = (1,2,3).


    log proc

    See also:
    ** operator
    Format:
    log(X,Y)
    log(Y)
    Returns:
    The logarithm (base X) of Y. If X is not specified, a natural logarithm is computed (base 2.718...).

    The logarithm is the power to which you have to raise X in order to get Y. In other words, the following is true (ignoring round-off error):

    X ** log(X,Y) == Y

    One nice property of this function is that it gradually increases, with a slope that continuously tapers off. In other words, it can be useful to represent diminishing returns from some input, such as money, experience points, and so forth.


    lowertext proc

    See also:
    uppertext proc
    Format:
    lowertext(T)
    Returns:
    A lowercase text string.
    Args:
    T: A text string.

    Make all of the characters of T lowercase.

    Example:

    L = lowertext("HI THERE") // = "hi there"

    matrix proc

    See also:
    matrix
    Format:
    matrix()
    matrix(Matrix)
    matrix(a, b, c, d, e, f)
    Returns:
    A new matrix.
    Args:
    Matrix: a matrix to copy
    a - f: The individual matrix components

    If no arguments are provided, a new default (identity) matrix is created.


    max proc

    See also:
    min proc
    Format:
    max(A,B,C,...)
    Returns:
    the maximum of the arguments.

    Example:

    usr << max(1,2,3)

    This example displays 3.

    If a single argument is specified, this is expected to be a list and the maximum item from the list is returned. Items to be compared may be numbers, text strings, or null, but numbers and text strings may not be mixed.


    md5 proc

    See also:
    file proc
    Format:
    md5(T)
    md5(F)
    Returns:
    text or null.
    Args:
    T: A text string.
    F: A file.

    This proc implements MD5 hashing. A hash function is a one-way process that compacts information to a short value: a hash. The same value will always have the same hash. Among other uses, most computers use hashing to store passwords. By storing just the hash, the password file contains very little sensitive information, but the password can still be verified by confirming that md5(password)==hash. MD5 is a widely-used hash function.

    Example:

    mob/var/hash mob/Read(savefile/S) ..() // hash was saved in the file along with other values if(md5("[level]/[exp]/[exp_needed]") != hash) src << "Cheater!" del(src)

    In the example, a few vars belonging to a mob were saved along with a hash of those values. When the mob is loaded again, the game compares the hash to the values to make sure it's still accurate. If the values or hash had been changed by a sneaky player, they wouldn't match. (But a sneaky player could still calculate hash themselves if they knew the exact text used to make it, so this should be kept secret.)

    If the argument is a file, md5() will read the file and return the MD5 hash of the file's entire contents. If the file doesn't exist, it returns null. The file may be a cache file or an external file.

    Examples:

    var/hash = "(insert hash value here)" // Compute this ahead of time // Check that the cached default icon is still the same if (md5('default.dmi') != hash) world << "The default icon has been modified!" // Or check that the entire game resource file is pristine if (md5(file("mygame.rsc")) != hash) world << "The game resources have been modified!"

    Note that you must pass the result of file() in order to compute the hash of an external file's contents at runtime. Otherwise md5() will treat the filename as text and return the hash of the name only.

    If T is anything but a text string or file, the proc returns null.


    min proc

    See also:
    max proc
    Format:
    min(A,B,C,...)
    Returns:
    the minimum of the arguments.

    Example:

    usr << min(1,2,3)

    This example displays 1.

    If a single argument is specified, this is expected to be a list and the minimum item from the list is returned. Items to be compared may be numbers, text strings, or null, but numbers and text strings may not be mixed.


    missile proc

    Format:
    missile(Type, Start, End)
    Args:
    Type: An object prototype or icon file.
    Start: The starting location.
    End: The ending location.

    Send a missile of the given Type between two locations. The effect is purely visual. When Type is an object, its icon is used for the missile.

    Example:

    missile(/obj/fireball, usr, loc)

    new proc

    See also:
    New proc (atom)
    New proc (datum)
    New proc (icon)
    newlist proc
    path operators
    Format:
    new Type(Args)
    Returns:
    A reference to a new instance of Type.
    Args:
    Type: The type of object to create.
    Args: Arguments for the Type.New() proc.

    A new instance of Type is created. The arguments (Args) are passed to its New() proc. A handy short-cut: if Type is not specified and new() is being used in an assignment, the variable type of the left-hand-side will be used as the default type.

    The atom types /area, /turf, /obj, and /mob all take a location argument specifying the initial position. If not specified, it defaults to null.

    Newly created areas or turfs replace any existing area or turf at the specified location.

    Example:

    obj/stick mob/verb/magic_stick() var/obj/stick/S = new(src) //create a stick in my inventory S.desc = "This is no ordinary stick!" view() << "[src] creates \an [S] from thin air!"

    newlist proc

    See also:
    list proc
    new proc
    Format:
    newlist(A,B,C,...)
    Returns:
    A list of new objects, just as though you had done list(new A,new B,new C,...).
    Args:
    Arbitrary number of types to be created in the list.

    Example:

    mob/contents = newlist(/obj/scroll/readme)

    This causes new mobs to be created with a readme scroll in their inventory.

    It is possible to make simple initializations when you want variables to have values other than the default for the particular type you are creating.

    Example:

    mob/contents = newlist( /obj/scroll/readme { name = "Introduction" desc = "The fate of Bracolia depends on you ..." } )

    This is the most common use of "modified types", but it is not specific to the newlist instruction. Anywhere a type value may be used in DM, it may be followed by a list of initializations. The general syntax for a modified types is:

    path {var1 = val1; var2 = val2}

    The semicolon is necessary if you put several variable assignments on the same line. The braces are necessary, even though they are generally optional in DM (since the compiler looks at your indentation). The reason is that the path + initializations must be parsed as a single expression, which is a different context from the usual use of braces in DM when you are defining a true type. Also, indentation inside of an argument list is always ignored anyway.


    num2text proc

    See also:
    isnum proc
    text2num proc
    Format:
    num2text(N,SigFig=6)
    Returns:
    A text string.
    Args:
    N: A number.
    SigFig: Number of significant digits.

    Get the text string for a number. The number of significant digits determines when scientific notation is used. The default is 6, so scientific notation will only be used when there are more than 6 digits.

    Example:

    T = num2text(12,1) // = "1.2e1"

    obounds proc

    See also:
    bounds proc
    Format:
    obounds(Ref=src, Dist=0)
    obounds(Ref, x_offset, y_offset, extra_width=0, extra_height=0)
    Returns:
    A list of atoms within the given bounding box, excluding Ref.
    Args:
    Ref: A turf, obj, or mob.
    Dist: A number (distance in pixels).
    x_offset, y_offset: Shift to bounding box position (from Ref's bounding box)
    extra_width, extra_height: Adjustment to bounding box size (from Ref's bounding box)

    The results from obounds() are identical to bounds(), but obounds() leaves Ref out of the results.


    ohearers

    See also:
    hearers
    oview proc
    oviewers
    Format:
    ohearers(Depth=world.view,Center=usr)

    This is just like hearers(), but it excludes the center object and its contents from the list. It is a list of all other mobs that can hear the center object.


    orange proc

    See also:
    << output operator
    block
    oview proc
    range proc
    Format:
    orange(Dist,Center=usr)
    Returns:
    A list of objects within Dist tiles of Center, excluding Center.
    Args:
    Dist: A number.
    Center: An object on the map.

    This instruction is identical to oview() except visibility is ignored. All objects are included in the list whether they are visible or not. The center object and its contents are excluded.


    output proc

    See also:
    << output operator
    winclone proc
    winset proc
    Format:
    output(msg, control)
    Args:
    msg: Text, an atom, a file, or null
    control: The ID of a control in the player's skin, or null for the default

    This is used in conjunction with the << output operator to send output to a particular control in the player's skin. If null is sent, the control will be cleared.

    Example:

    usr << output("Your score is [score].", "scorepane.output")

    The browser control in an interface can be used to execute javascript via the output() command. The format is: target << output("[params]","[control]:[scriptname]") where "[params]" is a url-encoded list of string arguments to the javascript function, as formatted by list2params().

    Example:

    mob/Login() . = ..() usr << output(\ {" <script type="text/javascript"> function replace(v) { document.getElementById('foo').innerHTML = v; } </script> <div id="foo">This text can change.</div> <p>And this can't.</p> "}, "browser1"); #define LP(str) list2params(list(str)) mob/verb/newtext(T as text) usr << output(LP(T),"browser1:replace")

    This allows for the creation of more dynamic interfaces, since javascript provides access to many client-side operations and flicker-free updates.


    oview proc

    See also:
    << output operator
    orange proc
    view proc
    Format:
    oview(Dist,Center=usr)
    Returns:
    A list of visible objects within Dist tiles of Center, excluding Center.
    Args:
    Dist: A number.
    Center: An object on the map.

    This instruction is just like view() except it doesn't include Center or its contents in the list.

    Example:

    oview() << "to others in sight of [usr]"

    oviewers

    See also:
    hearers
    oview proc
    oviewers
    Format:
    oviewers(Depth=world.view,Center=usr)

    This is just like viewers(), but it excludes the center object and its contents from the list. It is a list of all other mobs that can see the center object.


    params2list proc

    See also:
    Topic proc (client)
    list associations
    list2params proc
    params var (world)
    text2num proc
    Format:
    params2list(Params)
    Args:
    Params: Text string of parameter values.

    This instruction converts a parameter text string to a list of individual parameters and associated values. The format of the parameter text is:

    "name1=value1&name2=value2&..."

    The field separator ';' may be used in place of '&'.

    Special characters such as '=', ';', and '&' inside the parameter names or values should be written in the form: %xx where xx are two hexadecimal digits representing the ASCII value of the character. For example, '=' would be written %3d, ';' would be %3b, '&' would be %26, and '%' would be %25. These 'escaped' codes are automatically translated into the corresponding character when read by params2list().

    This parameter format is the same one used by most html forms and is known by the MIME type 'application/x-www-form-urlencoded'. It is often used in DM to pack information into topic links. Though DM does not require it, the standard format is for newlines to be written as CR LF pairs (%0d%0a) and spaces to be written as '+' characters. That means if you want to write a '+' symbol, you will have to use %2b.

    The list produced from the parameter text has items "name1", "name2", and so on. To access the values associated with these, you use the parameter name as the list index.

    Example:

    var/ptext = "offense=jwalk&time=10:00" var/plist[] = params2list(ptext) var/p for(p in plist) usr << "[p] = [plist[p]]"

    The above example defines a simple parameter text string containing two parameters: "offense" and "time". These are associated with the values "jwalk" and "10:00". The for loop illustrates how one might loop through the list and print out each setting.

    Note that all values are stored as text strings in the list. If you wish to perform a numerical operation (such as addition), you should convert the value to a number first using text2num(). If the value is an object text reference, you can convert that into the object itself by using locate().

    If you have multiple items with the same name, they will be combined into a list of text strings. For example, "key=value1;key=value2" would set list["key"] to a list containing "value1" and "value2", not necessarily in that order.


    pick proc

    See also:
    prob proc
    Format:
    pick(Val1,Val2,...)
    Returns:
    One of the given values randomly chosen.

    To make a particular value more or less likely to be chosen, a relative probability may be specified like this:

    prob(P); Val Or P; Val

    A value for P of 200 makes it twice as likely as the norm, 50 half as likely, and so on.

    Example:

    obj/food verb/eat() usr << pick ( "[usr] eats \a [src].", prob(50) "[usr] devours \a [src].", prob(25) "[usr] wolfs down \a [src]." ) del(src)

    Also, to pick a value randomly from a list, simply pass the list as the sole argument into pick(). In this case, there is no provision for weighting the probabilities. All items in the list are equally likely.


    prob proc

    See also:
    pick proc
    rand proc
    rand_seed proc
    roll proc
    Format:
    prob(P)
    Returns:
    1 with probability P percent; otherwise 0
    Args:
    P: A number.

    rand proc

    See also:
    pick proc
    prob proc
    rand_seed proc
    roll proc
    Format:
    rand(L=0,H) or rand()
    Returns:
    A random integer between L and H inclusive; or a random number from 0 up to 1 if L and H are omitted.
    Args:
    L: A number for the lower-bound.
    H: A number for the upper-bound.

    rand_seed proc

    See also:
    pick proc
    prob proc
    rand proc
    roll proc
    Format:
    rand_seed(Seed)
    Args:
    Seed: An integer used to initialize the random number generator.

    Many DM procedures make use of a pseudo-random number generator. You can use rand_seed() to initialize the generator. The sequence returned by the generator is identical each time it is initialized with the same seed, so you could use this to reproduce the same output from an algorithm that uses the random number generator. If you never call rand_seed(), the generator is initialized with a seed from the system clock, so it is effectively random.

    Note that with multiple realtime algorithms making calls to the generator at unpredictable times, you are likely not to get the same result even when using the same seed. The overall sequence will be the same, but individual sub-components of your world might call it in a different order.

    The pseudo-random number generator is system dependent, so do not expect the sequence generated from a particular seed to be identical on two different machines or operating systems.


    range proc

    See also:
    << output operator
    block
    view proc
    orange proc
    Format:
    range(Dist,Center=usr)
    Returns:
    A list of objects within Dist tiles of Center.
    Args:
    Dist: A number.
    Center: An object on the map.

    This instruction is identical to view() except visibility is ignored. All objects are included in the list whether they are visible or not.

    A Dist of 0 includes Center, the contents of Center (normally usr.contents), its location (normally the turf a mob is standing on), and any other contents of that location. A value of 1 extends the region to the neighboring squares on the map and so on. You can also use a rectangular box size using a text string such as "13x11". Both arguments are optional and may be passed in any order.


    return proc

    See also:
    . var (proc)
    Format:
    return E

    Stop execution of the current proc and return the value of E to the caller. If no value is specified, the value of '.' will be returned, which defaults to null.


    rgb proc

    Format:
    rgb(R,G,B)
    or
    rgb(R,G,B,A)
    Args:
    R,G,B: Numbers from 0-255 corresponding to the red, green, and blue components of a color.
    A: Optional alpha component; 0 is transparent, 255 is opaque.

    A way of representing a color to be used in conjunction with icon arithmetic. The colors rgb(0,0,0) and rgb(255,255,255) represent black and white, two corners of the "color cube".

    Example:

    mob/proc/hurtme() // make a mob look damaged by adding red to his icon src.icon += rgb(20,0,0)

    This proc returns a text string in the form used by HTML (#RRGGBB). rgb(255,0,128) for example becomes "#ff0080". If you use an alpha component, the format is #RRGGBBAA. You can use strings like this in most procs that use colors such as icon blending operations, and you can also use the short form #RGB or #RGBA. So if you know in advance that you want to use the color white, you can simply use"#fff" instead of rgb(255,255,255).


    roll proc

    See also:
    rand proc
    Format:
    roll(ndice=1,sides)
    roll(dice)
    Returns:
    The sum of the rolled dice.
    Args:
    ndice: number of dice to role.
    sides: number of sides to the dice.
    dice: a text string encoding both ndice and sides (see below).

    The sides of the dice are numbered 1 through the total number of sides and each is equally likely.

    An alternate form takes the dice parameters in a single text value such as "3d4". This may be useful when you want to store the dice information in a single variable. You can even specify an offset, such as "3d4+5". That adds 5 to the sum of 3 dice having 4 sides each.

    Example:

    obj/potion/healing var/dice = "3d6" verb/drink() var/h = roll(dice) if(h>15) usr << "Very refreshing!" else usr << "You feel better."

    round proc

    Format:
    round(A)
    round(A,B)
    Returns:
    rounded A
    Args:
    A: A number.
    B: The nearest multiple to round A.

    The first format returns the floor of A (the largest integer less than or equal to A). The second format rounds A to the nearest multiple of B.

    Example:

    usr << round(1.45) // outputs 1 usr << round(-1.45) // outputs -2 usr << round(1.45,1.5) // outputs 1.5

    run proc

    See also:
    << output operator
    file proc
    link proc
    Format:
    O << run(File)

    This is similar to link() but instead of a URL, you can pass a file to be viewed directly. The file may be a cache file or an external file.

    Example:

    mob/var/picture = 'mob.jpg' mob/verb/view_pic(mob/M as mob in view()) usr << run(M.picture) mob/verb/set_pic(F as file) usr.picture = F

    This example defines a picture to be associated with each mob and a verb for viewing another mob's picture. Players can also configure their own pictures.


    settings (proc)

    proc settings:

    verb/set
      name
      desc
      category
      hidden
      popup_menu
      instant
      invisibility
      src
      background
    

    Procs and verbs are the same "type" so these attributes may be set for both procs and verbs; most of them only apply to verbs, so they only take effect if the proc is invoked as a verb (by adding it to a verb list).


    background setting (proc)

    See also:
    sleep proc
    spawn proc

    To avoid lag from procedures that hog the CPU for too long, you can turn on background processing. This will cause it to periodically sleep for long enough to allow other events to be processed.

    The following example is a typical "ticker" procedure. It spawns off an infinite loop which does some work and then sleeps before iterating again. By running this in the background, you ensure that the work being done does not create large delays. You could achieve a similar thing by sprinkling calls to sleep(0) or sleep(-1) in the "working" part of the loop.

    Example

    proc/Ticker() set background = 1 spawn while(1) for(var/mob/M in world) M.Tick() sleep(10)

    Since the background procedure sleeps at unpredictable times, you must be aware that race conditions are possible if the background procedure interacts with variables modified by other procedures. It's still much safer than multi-threaded programs because the background procedure never interrupts other code; but other code may interrupt the background procedure.

    Note that procedures that are called by the background procedure do not automatically run in the background unless they too have the background setting turned on. For instance, the code in the above example does not imply that the mob Tick() procs would run in the background. This is convenient, because you should only ever apply background processing to code after checking that there are no potential race conditions involved.

    If you have an eye for race conditions, you might think that the above code has one in which a mob gets deleted after it is assigned to M but before the call to M.Tick() is executed. However, background processing is only interrupted at loop points in the code, so the above code is safe. It would only ever be interrupted at the end of the for or while loops.


    shell proc

    See also:
    fcopy proc
    fdel proc
    file2text proc
    system_type var (world)
    text2file proc
    Format:
    shell(Command)
    Args:
    Command: system command to run
    Returns:
    null on failure to execute command
    exit code of command otherwise

    This function is used to run an external program. The syntax of Command depends on the server machine's operating system. Be sure to redirect input and output to files if there is any. Also realize that the command will fail if the program you try to run is not in the path where the shell expects to find executable files (unless you specify a full path).

    Since shell() allows arbitrary access to the system, each call requires authorization from the person hosting the world, unless running in trusted mode. Authorization is only sought when running in Dream Seeker, since Dream Daemon is intended to be non-interactive. Calling shell() with no arguments is a way of checking if it is allowed by the current safety settings. It will return true if running in Dream Seeker (regardless of safety mode) or if running in Dream Daemon in trusted mode.

    The calling proc will sleep until the command is finished executing.

    Example:

    mob/verb/dir(Path as text) shell("dir [Path] > dir.out") usr << file2text("dir.out")

    This example displays the output of the "dir" command to the user.


    shutdown proc

    See also:
    Export proc (world)
    startup proc
    Format:
    shutdown(Addr,Natural=0)
    Args:
    Addr: This is the address of the child world returned by startup().
    Natural: Specifies whether to wait for the child world to die naturally, or whether it should be killed with the "Del" world topic. The default value of 0 kills the child, and a value of 1 waits for the child to exit of its own accord.

    If no address is specified, the current world is shut down.


    sin proc

    See also:
    arcsin proc
    cos proc
    turn proc
    Format:
    sin(X)
    Returns:
    The sin of X, where X is in degrees.

    Example:

    mob/verb/test() usr << sin(0) //0 usr << sin(45) //0.707... usr << sin(90) //1

    sleep proc

    See also:
    background setting (proc)
    spawn proc
    tick_lag var (world)
    Format:
    sleep(Delay)
    Args:
    Delay: The amount of time to sleep, in 1/10 seconds.

    Pause the current proc (and its callers) for a specified amount of time. If no delay is specified, it will be scheduled to resume as soon as other immediately pending events are processed.

    Note that sleeping in some procedures results in the return value being lost. For example, if you sleep inside Enter() or Exit(), it will be as if you returned immediately where you started sleeping.

    Also be aware, that a sleeping procedure whose src object gets deleted will automatically terminate when execution returns to it. This is to protect you against trying to access properties or procedures of a deleted (and therefore null) object. If you do not want the procedure to be terminated, you should set src to null.

    One common use of sleep is to create what is known as a ticker. That is an infinite loop that performs some periodic operation.

    Example:

    proc/Weather() spawn while(1) //infinite ticker loop world << "The sun rises in the east." sleep(500) world << "The noon day sun rises high in the sky." sleep(500) world << "The sun sinks low in the west." sleep(1000)

    Notice how such infinite loops are usually created using spawn to prevent the caller from getting locked up. You could call this procedure from world.New() to start it rolling.

    If the ticker does intensive processing during each iteration, you probably want to run it in the background like this:

    proc/Ticker() set background = 1

    Calling sleep() with a negative argument (such as sleep(-1)) causes it to do a backlog check. Only if other pending events have become backlogged will it sleep. This is similar to running in the background, but you manually control where the backlog checks are made. The difference between this and sleep(0) is that sleep(0) always sleeps the current procedure for as short a time as possible, whereas sleep(-1) only sleeps the current procedure if other scheduled events have become backlogged. Therefore, sleep(-1) will tend to run the current procedure at a higher priority with fewer interruptions. It is appropriate when there is a single task that needs to be done before anything else can happen, and you just want to make sure that network and user I/O are not terribly lagged in the process.


    sorttext proc

    See also:
    > operator
    < operator
    sorttextEx proc
    Format:
    sorttext(T1,T2,...)
    Args:
    Any number of text strings to sort.
    Returns:
    1 if text is ascending
    -1 if text is descending
    0 otherwise

    This instruction is NOT sensitive to case. The case sensitive version is sorttextEx().

    Example:

    switch(sorttext("A","B")) if(1) world << "ascending" if(-1)world << "descending" if(0) world << "neither"

    This outputs "ascending", since "A" comes before "B" in the alphabet.


    sorttextEx proc

    See also:
    > operator
    < operator
    sorttext proc
    Format:
    sorttextEx(T1,T2,...)
    Args:
    Any number of text strings to sort.
    Returns:
    1 if text is ascending
    -1 if text is descending
    0 otherwise.

    This instruction is sensitive to case. The case-insensitive version is sorttext().

    NOTE: Uppercase letters are lower in the alphabetical order than lowercase letters.

    Example:

    switch(sorttextEx("a","B")) if(1) world << "ascending" if(-1)world << "descending" if(0) world << "neither"

    This outputs, "descending", since "B" comes before "a" in the alphabet.

    Note: This proc used to be named sortText, like sorttext but with a capital T. To avoid confusion it has been renamed, but old code will still compile.


    sound proc

    See also:
    << output operator
    Format:
    sound(file,repeat=0,wait,channel,volume)
    (supports named arguments)
    Args:
    file: A sound file to play
    repeat: 1 to play sound repeatedly
    wait: 0 to interrupt current sound on channel; 1 to wait in queue
    channel: 0 for any available channel, 1-8 for specific channel (wavs only)
    volume: 100 for full volume (default), 0 for none, or any value in between

    This is used to play a sound file.

    The sound file must be a music or sample file. Music files include MIDI (.mid or .midi), and module formats .mod, .it, .s3m, .xm, and .oxm. A sample file used for sound effects can be .wav, .ogg, .raw, .wma, or .aiff.*

    The following example plays some sound files. Note that sound() is not even necessary when you don't need to set any additional parameters.

    Example:

    usr << 'giggle.wav' // play a giggle once usr << sound('gigue.midi',1) // repeat gigue usr << sound('boom.wav', volume=50) // play an explosion at half volume

    *See Notes under sound support for more information.


    spawn proc

    See also:
    background setting (proc)
    sleep proc
    Format:
    spawn(Delay=0) Statement
    Args:
    Delay: The amount of time (in 1/10 seconds) before Statement is executed.

    Run Statement after a delay. Statement may be a single statement or a code block enclosed in (optional) braces and indented. If delay is negative, the spawned code is executed before continuing in the main code. If it is zero, the spawned code is scheduled to happen right after other existing events that are immediately pending.

    Example:

    spawn(30) storm() usr << "Storm clouds are brewing!"

    This will display "Storm clouds are brewing!" and then call the storm() proc after 3 seconds.

    The important feature of spawn() is that the caller does not have to wait around for the spawned code to finish.

    Any vars you have defined in the proc itself, including arguments, will be copied between the spawned code and the code that runs right away. This means that if one part modifies one of those vars, the other part will not see that change. Changes made to objects, lists, datums, etc. however will be visible to both code blocks.


    sqrt proc

    Format:
    sqrt(A)
    Returns:
    The square root of A
    Args:
    A: A number.

    Example:

    usr << sqrt(2) // outputs 1.41421

    startup proc

    See also:
    params var (world)
    shutdown proc
    Format:
    startup(File,Port=0,Options,...)
    Args:
    File: The dmb file to run in a new server or null to load the current world.
    Port: The network port to start the new server on. A value of 0 indicates that any available port should be used.
    Options: Any number of the options listed below. Each option should be in an argument by itself. If the option takes a parameter, this can be in the same argument or in the following one.

    The valid options are:

    -once
    automatically shuts down the server when all players have logged off.
    -close
    Closes the child copy of DreamDaemon after the world it is running shuts down.
    -log <logfile>
    sends all server output to the specified file. The path to the file is relative to the world directory (the path containing the world .dmb file).
    -logself
    is identical to "-log [YourWorldFile].log".
    -safe
    runs the server in a special protective mode. The server may only access files in the same directory (or below) as the dmb file and access to the shell() command is disabled. This is the default mode if no security setting is specified and the world is run from a directory by the same name as the dmb file.
    -home <path>
    runs with the specified "safe home" directory. Normally, in safe mode the directory containing the world dmb file is the safe home.
    -ultrasafe
    like -safe, this prohibits all file access. This is the default if no security mode is specified and the world is not run from a directory with the same name.
    -trusted
    allows full access to files on the computer and to the shell() command. Note that this does not bypass the normal security of the operating system. For example, in the UNIX operating system, all of the usual access restrictions apply. This mode merely removes BYOND's built-in safety checks.
    -params <paramtext>
    this is for passing user-defined parameters to the world. Multiple parameters may be packed into a single argument or -params may be used several times. In either case, the parameters are all loaded into world.params when the world starts up. The parameter format is "name1=value1&name2=value2&...".
    -quiet
    disables the server's normal output indicating the BYOND version number and network port.
    -nologdates
    disables automatic date/time output in the log.
    -CGI
    runs the world as a CGI program (to be executed by a web server). A /client object is automatically created for the user and any output sent to the associated mob gets returned to the user's web browser. This option is normally specified in the compile-time setting: world.executor, which is automatically initialized for you if you include html/CGI.dm from the html library.
    -suid <path>
    runs the world as the owner of the specified directory or path. This only works if DreamDaemon is running as root on operating systems where there even is such a thing.
    -suidself
    runs the world as the owner of the world dmb file. This only works if DreamDaemon is running as root on operating systems where there even is such a thing.
    -cd <path>
    runs with the specified working directory. Normally, the directory containing the world dmb file is used.
    -port P
    sets the network port to P. The port may also be specified as a positional argument (following the .dmb name).
    -ports <list>
    restricts the range of ports that DreamDaemon and any child worlds may use. The syntax of list is a comma separated list of ports or ranges of ports. Example: -ports 1234,1236,1240-1250.
    Returns:
    The address of the new server in the form ip:port.

    stat proc

    See also:
    Stat proc (atom)
    Stat proc (client)
    statpanel proc
    Format:
    stat(Name,Value)
    Args:
    Name: the name of the stat line
    Value: the data to be displayed

    This is used in a Stat() proc to send a stat line to usr, the person looking at an object. A stat line has an optional name part which must be unique for each stat line (or successive calls will replace previous ones).

    The stat line gets appended to the current stat panel. The current panel may be changed by using statpanel().

    If no name is specified and the value is a list, this is the same as calling stat on each item in the list. This can be used (in conjunction with statpanel) to create an inventory panel or something similar.

    Example:

    mob/Stat() stat("description",src.desc) if(src == usr) stat(src.contents)

    This example displays the mob's description and inventory all in one panel. The code ensures that only the mob may see his own inventory, but you don't have to worry about that unless you change client.statobj to something other than one's own mob.


    statpanel proc

    See also:
    Stat proc (atom)
    Stat proc (client)
    stat proc
    Format:
    statpanel(Panel,Name,Value)
    Args:
    Panel: the name of the stat panel
    Name: the name of the stat line
    Value: the data to be displayed
    Returns:
    If called with just a Panel argument, 1 is returned if the player is looking at the panel and 0 is returned if not. This may be useful to avoid the needless overhead of generating output to a panel that is not visible.

    This is used in a Stat() proc to change the default panel (for subsequent stat lines) or to send one line to the specified panel. Name and Value are both optional. If neither is specified, this simply changes the default panel. Otherwise, the default panel is unchanged and a stat line is appended to Panel.

    Example:

    mob/Stat() stat("description",src.desc) if(src == usr) statpanel("inventory",src.contents)

    This example displays the mob's description in one panel and inventory in another. Only the mob may see his own inventory, but you don't have to worry about that unless you change client.statobj to something other than one's own mob.


    step proc

    See also:
    get_step proc
    walk proc
    step_size var (movable atom)
    Format:
    step(Ref,Dir,Speed=0)
    Returns:
    1 on success; 0 otherwise
    Args:
    Ref: A mob or obj.
    Dir: One of NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, SOUTHWEST.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref in the direction Dir.


    step_away proc

    See also:
    get_step_away proc
    walk_away proc
    step_size var (movable atom)
    Format:
    step_away(Ref,Trg,Max=5,Speed=0)
    Returns:
    1 on success; 0 otherwise.
    Args:
    Ref: A mob or obj.
    Trg: An object on the map.
    Max: The maximum distance between Ref and Targ before movement halts.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref on a path away from location Trg, taking obstacles into account. If Ref is farther than Max steps from Trg, no action will be taken.


    step_rand proc

    See also:
    get_step_rand proc
    walk_rand proc
    step_size var (movable atom)
    Format:
    step_rand(Ref,Speed=0)
    Returns:
    1 on success; 0 otherwise.
    Args:
    Ref: A mob or obj.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref randomly.


    step_to proc

    See also:
    get_step_to proc
    walk_to proc
    step_size var (movable atom)
    Format:
    step_to(Ref,Trg,Min=0,Speed=0)
    Returns:
    1 on success; 0 otherwise.
    Args:
    Ref: A mob or obj.
    Trg: An object on the map.
    Min: The minimum distance between Ref and Trg before movement halts.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref on a path to the location Trg, taking obstacles into account. If Ref is within Min steps of Trg, no action will be taken. This is also the case if the target is too far away (more than twice world.view steps).


    step_towards proc

    See also:
    get_step_towards proc
    walk_towards proc
    step_size var (movable atom)
    Format:
    step_towards(Ref,Trg,Speed)
    Returns:
    1 on success; 0 otherwise.
    Args:
    Ref: A mob or obj.
    Trg: An object on the map.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref in the direction of the location Trg.


    switch proc

    See also:
    if proc
    Format:
    switch(E)
    if(A1,A2,...) Statement1
    if(B1,B2,...) Statement1
    else Statement3

    The "switch" instruction is a compact notation for a lengthy "else-if" chain. The expression E is compared to the values A1, A2, B1, B2, etc. When a match is found, the following statement (or code block) is executed. An optional "else" statement is run if no match is found. Once a matching switch condition is found, no further conditions will be tested.

    The values A1, A2, etc. must be constants. As a convenience, a range of values may be specified in the form: A1 to An.

    The switch instruction is MUCH more efficient than a lengthy "else-if" chain, because the expression E is evaluated only once. The conditional values may be any constant expression, such as a number or text string.

    Example:

    switch (2) if(1) world << "ONE" if(4) world << "FOUR" if(2,3) world << "TWO or THREE" if(5 to 10) world << "FIVE to TEN" else world << "not ONE to TEN"

    This outputs:

    TWO or THREE

    text proc

    See also:
    << operator
    macros (text)
    Format:
    text(FormatText,Args)
    Returns:
    The text with macros arguments substituted.
    Args:
    FormatText: a text string possibly containing text macros.
    Args: a set of arguments that corresponds to the number of empty embedded expressions in FormatText.

    Complicated or lengthy embedded expressions in a text string can sometimes make the string difficult to read. In this case, one can use trailing arguments. The position in which the expression should be substituted should be marked with [] and the expression should then be passed as an argument after the text string.

    Example:

    usr << text("You are [] leagues from home.",sqrt(usr.x**2 + usr.y**2))

    text2ascii proc

    See also:
    ascii2text proc
    entities (text)
    Format:
    text2ascii(T,pos=1)
    Returns:
    A number.
    Args:
    T: A text string.
    pos: The character position in T to use.

    ASCII codes are numerical values corresponding to keyboard and special characters. Among other things, they are used to represent many symbols in HTML. This proc converts a text string to its corresponding ascii representation.

    Example:

    num = text2ascii("A") // = 65 num = text2ascii("HAPPY",2) // = 65

    text2file proc

    See also:
    file2text proc
    shell proc
    Format:
    text2file(Text,File)
    Args:
    Text: text to be added to file
    File: file to be appended to
    Returns:
    1 on success; 0 otherwise.

    Appends text to a file. If the file does not exist, one will be created.

    This can be useful when interacting with external applications that read output from a text file. For example, you might have an external program that mimics conversation:

    Example:

    mob/oracle/verb/tell(T as text) text2file(T,"oracle.in") shell("oracle < oracle.in > oracle.out") usr << file2text("oracle.out")

    text2num proc

    See also:
    istext proc
    num2text proc
    Format:
    text2num(T)
    Returns:
    A number.
    Args:
    T: A text string.

    If T is a text string for a number, return the number. Any non-numeric text following the initial portion will be ignored. If there is no initial numeric portion, the result is null.

    Example:

    num = text2num("123") // = 123

    text2path proc

    See also:
    ispath proc
    Format:
    text2path(T)
    Returns:
    a type path or null.
    Args:
    T: A text string.

    Example:

    var/myturf = text2path("/turf/[src.color]") if(myturf) src.loc = locate(myturf)

    T is changed from a text string to the equivalent type path, or null if there is no such type.


    time2text proc

    See also:
    realtime var (world)
    timeofday var (world)
    Format:
    time2text(timestamp,format)
    Args:
    timestamp: a time value as obtained from world.realtime or world.timeofday
    format: a text string describing the output format.
    Returns:
    a text string containing the date and time in the specified format.

    A time value (GMT) is converted to text representing the time in the game's time zone.

    The default format is "DDD MMM DD hh:mm:ss YYYY", which produces results such as "Wed, May 23 15:41:13 2001". As you can see, the fields in the format text are replaced by components of the date and time. The following list contains all of the recognized fields. Anything else in the format string is inserted directly into the output.

    YYYY
    year (2001, 2002, ...)
    YY
    year (01, 02, ...)
    Month
    January, February, ...
    MMM
    Jan, Feb, ...
    MM
    number of the month (01, 02, ...)
    Day
    Monday, Tuesday, ...
    DDD
    Mon, Tue, ...
    DD
    day of the month
    hh
    hour (00, 01, ... 23)
    mm
    minute
    ss
    second

    Because world.timeofday is in a range of 0 to 864000, values in this range are treated as a time for the current date. This way time2text() can return accurate results for world.timeofday. Any other values are interpreted as coming from world.realtime and will have the right time and date.


    turn proc

    See also:
    Turn proc (icon)
    dir var (atom)
    Format:
    turn(Dir, Angle)
    Returns:
    The rotated direction.
    Args:
    Dir: One of NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, SOUTHWEST.
    Angle: An angle in degrees.

    Example:

    var/dir dir = turn(NORTH, 90) // dir = west dir = turn(dir, -90) // dir = north dir = turn(dir, 45) // dir = northwest

    turn proc (applied to an icon)

    See also:
    turn proc
    icon
    Format:
    turn(Icon, Angle)
    Returns:
    The rotated icon.
    Args:
    Icon: an icon to rotate
    Angle: An angle in degrees (clockwise rotation).

    Example:

    mob/verb/drink() //this effect is very confusing! usr.icon = turn(usr.icon,90) usr << "Woah! That stuff is powerful!" sleep(200) usr.icon = turn(usr.icon,-90)

    An icon that is not square will not be turned.

    If the icon is an /icon datum, a new datum will be created as the result.


    turn proc (applied to a matrix)

    See also:
    turn proc
    matrix
    Format:
    turn(Matrix, Angle)
    Returns:
    A new matrix which has been rotated.
    Args:
    Matrix: a matrix to rotate
    Angle: An angle in degrees (clockwise rotation).

    Example:

    mob/verb/drink() //this effect is very confusing! usr.transform = turn(usr.transform, 90) usr << "Woah! That stuff is powerful!" sleep(200) usr.transform = null

    typesof proc

    See also:
    istype proc
    locate proc
    Format:
    typesof(Type1,Type2,...)
    Returns:
    A list of all types that are derived from the specified "base" types.
    Args:
    The "base" types.

    Example:

    obj/fruit apple peach mango var/list/fruit_types = typesof(/obj/fruit)

    In this example, fruit_types is initialized to contain /obj/fruit, /obj/fruit/apple, /obj/fruit/peach, and /obj/fruit/mango.

    This procedure can also be used to list procs and verbs.

    Example:

    mob/admin_commands/verb shutdown_world() world.Del() reboot_world() world.Reboot() //for testing mob/verb/add_admin() verbs += typesof(/mob/admin_commands/verb) mob/verb/remove_admin() verbs -= typesof(/mob/admin_commands/verb)

    uppertext proc

    See also:
    lowertext proc
    Format:
    uppertext(T)
    Returns:
    A capitalized text string.
    Args:
    T: A text string.

    Capitalize all of the characters of T.

    Example:

    U = uppertext("hi there") // = "HI THERE"

    url_decode proc

    See also:
    Topic proc (client)
    url_encode proc
    Format:
    url_decode(UrlText)
    Args:
    UrlText: text to be "unescaped"
    Returns:
    unescaped text

    Most non-alphanumeric characters are converted to another format in a URL. To send these characters literally, they must be "escaped".

    The url_decode() instruction takes a text string containing such escaped symbols and turns them into their literal counterparts. Usually this is done for you automatically in Topic(). The more useful function is url_encode() which does the reverse.


    url_encode proc

    See also:
    url_decode proc
    Format:
    url_encode(PlainText, format=0)
    Args:
    PlainText: text to be URL "escaped"
    format: 0 to treat PlainText as a query string, 1 to treat it as a full URL
    Returns:
    escaped text

    Special characters such as spaces are not used literally in URLs. If you want to ensure that an entire text string is sent literally, you can "escape" those characters. For example, a double quote (ASCII 34) is produced by the code %22, where 22 is hexadecimal for 34.

    The url_encode() instruction does this for you automatically. Using format=1 will treat the URL as already encoded and only re-encode characters that don't belong in the result. Otherwise PlainText is treated as part of a query string; in this case spaces are converted to + instead of %20, and most characters are escaped.

    Example:

    mob/verb/Private(M as mob in players, T as text) if(!client || !M || !M.client || !T) return usr << "\[To <a href='?msg=[url_encode(M.key)]'>[M.name]</a>\] [T]" M << "\[From <a href='?msg=[url_encode(key)]'>[name]</a>\] [T]"

    vars (procs)

    See also:
    procs

    Built-in proc vars:

    proc/var
    .
    args
    src
    usr

    . var (proc)

    See also:
    return proc
    vars (procs)

    This is the default return value. If a proc exits without calling return or if no arguments are specified the value of '.' will be returned. The default value of '.' is null.

    Example:

    mob/Login() . = ..() view() << "[src] logs in."

    args list var (proc)

    See also:
    list

    This is a list of the arguments passed to the proc or verb.

    Example:

    proc/add() var {cur; tot} for(cur in args) tot += cur return tot

    Here, add() may be called with any number of arguments, each accessed through the args list.


    global var (proc)

    See also:
    src var (proc)

    This is not really a variable but is used to force treatment of the following variable or proc as global. This may be necessary if a local or src-level variable has the same name.

    Example:

    var/myvar = "global" mob verb/test() var/myvar = "local" usr << myvar usr << global.myvar

    This example outputs "local" and then "global".


    src var (proc)

    This is a variable equal to the object containing the proc or verb. It is defined to have the same type as that object.

    Example:

    obj/bread verb/eat() world << "[usr] eats [src]"

    If a player named "Bob" calls "eat bread", the output will be "Bob eats the bread."

    Note that src has no meaning for global procs, derived from /proc, unless they are invoked as verbs (by being attached to a verb list).


    usr var (proc)

    This is a mob variable (var/mob/usr) containing the mob of the player who executed the current verb, or whose action ultimately called the current proc.

    Example:

    obj/bread verb/eat() world << "[usr] eats [src]"

    If a player named "Bob" calls "eat bread", the output will be "Bob eats the bread."

    Essentially, usr is an implicit parameter that is passed to every proc or verb. Each procedure inherits the value from its caller. While it can simplify your code in some situations, it can also lead to subtle problems if you are assuming that usr is automatically assigned to src when you call a verb programmatically. It is not.

    The only time usr is assigned for you is when a player (in Dream Seeker) executes a verb, clicks something with the mouse, or any other such action.

    A good rule of thumb is to never put usr in a proc. Typically this is an unsafe programming practice, even when you know that a certain proc is only ever called by a verb, because it is common during development to change the way or time at which a proc is called. If src would not be the correct choice, it is better to send another argument to your proc with the information it needs.

    Certain built-in procs such as mob/Click() are called automatically by a client counterpart like client/Click(); usually atom/Stat() is called by client/Stat(); and so on. It is mostly safe to apply usr as directed in those situations. It is mostly not safe to apply usr in a movement proc such as Move() or Enter(), because objs and non-player mobs may move as well, without setting usr.

    Although usr is often set in mob/Login() when a client first connects, you should not assume it is valid if Login() is called any other way. Common cases occur when creating a new character, loading a player's mob from a savefile; or explicitly when setting a mob's key or changing the value of client.mob. It is safest to use src in mob/Login(), which is always correct, rather than usr.

    usr is the default point of reference for several procs like view() and range(), because of their common use in verbs. It is also the default recipient for input() and alert() messages. When using these in procs, be aware of that so you can change the default value to something more appropriate.


    view proc

    See also:
    << output operator
    hearers
    oview proc
    range proc
    see_in_dark var (mob)
    see_infrared var (mob)
    see_invisible var (mob)
    sight var (mob)
    view var (client)
    view var (world)
    viewers
    Format:
    view(Dist=5,Center=usr)
    Returns:
    A list of visible objects within Dist tiles of Center.
    Args:
    Dist: A number.
    Center: An object on the map.

    A Dist of 0 includes Center, the contents of Center (normally usr.contents), its location (normally the turf a mob is standing on), and any other contents of that location. A value of 1 extends the region to the neighboring squares on the map and so on. Both arguments are optional and may be passed in any order.

    The default range is actually controlled by the size of the map viewport size, which is configured with world.view. Since the default value of that variable is 5, the default range is also 5. You may use any valid view size, so an explicit view size such as "11x17" is also valid.

    Example:

    view() << "to all in sight of [usr]" view(src) << "to all in sight of [src]" view(1,src.loc) << "to all within reach of [src]"

    Be aware of the following distinctions:

    view(usr) //objects that usr can see view(usr.loc) //objects visible from usr's position view(usr.client) //objects visible to player

    In many cases, the three different statements could produce the same result, but they are not identical in general. For example, the first statement takes into account the visual capabilities of usr, which might include such things as the ability to see in the dark or to see invisible objects.

    The second statement, since it is from a non-mob would just do a plain visibility calculation with no special visual capabilities. In many cases, you would want to use viewers() or hearers() instead.

    The third statement produces a list of visible objects as the player sees things, which might be different than how the mob sees things if client.eye and client.mob are different.


    viewers

    See also:
    hearers
    oviewers
    view proc
    Format:
    viewers(Depth=world.view,Center=usr)

    This is just like view(), but it is a list of mobs that can see the center object, rather than a list of objects visible to the center object.


    walk proc

    See also:
    get_step proc
    step proc
    step_size var (movable atom)
    Format:
    walk(Ref,Dir,Lag=0,Speed=0)
    Args:
    Ref: A mob or obj.
    Dir: One of NORTH, SOUTH, EAST, WEST, NORTHEAST, NORTHWEST, SOUTHEAST, SOUTHWEST, or 0 to halt.
    Lag: Delay in world ticks between movement.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref in the direction Dir continuously. Each step will be preceded by Lag time of inactivity.

    A call to a walking function aborts any previous walking function called on Ref. To halt walking, call walk(Ref,0).

    This function returns immediately, but continues to process in the background.


    walk_away proc

    See also:
    get_step_away proc
    step_away proc
    step_size var (movable atom)
    Format:
    walk_away(Ref,Trg,Max=5,Lag=0,Speed=0)
    Args:
    Ref: A mob or obj.
    Trg: An object on the map.
    Max: The maximum distance between Ref and Targ before movement halts.
    Lag: Delay in world ticks between movement.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Moves Ref on a path away from Trg continuously, taking obstacles into account. Each step will be preceded by Lag time of inactivity. If Ref is farther than Max steps from Trg, no action will be taken.

    A call to a walking function aborts any previous walking function called on Ref. To halt walking, call walk(Ref,0).

    This function returns immediately, but continues to process in the background.


    walk_rand proc

    See also:
    get_step_rand proc
    step_rand proc
    step_size var (movable atom)
    Format:
    walk_rand(Ref,Lag=0,Speed=0)
    Args:
    Ref: A mob or obj.
    Lag: Delay in world ticks between movement.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Moves Ref randomly. Each step will be preceded by Lag time of inactivity.

    A call to a walking function aborts any previous walking function called on Ref. To halt walking, call walk(Ref,0).

    This function returns immediately, but continues to process in the background.


    walk_to proc

    See also:
    get_step_to proc
    step_to proc
    step_size var (movable atom)
    Format:
    walk_to(Ref,Trg,Min=0,Lag=0,Speed=0)
    Args:
    Ref: A mob or obj.
    Trg: An object on the map.
    Min: The minimum distance between Ref and Trg before movement halts.
    Lag: Delay in world ticks between movement.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref on a path to Trg continuously, taking obstacles into account. Each step will be preceded by Lag time of inactivity. If Ref is within Min steps of Trg, no action will be taken. This is also true if the target is too far away (more than twice world.view steps).

    A call to a walking function aborts any previous walking function called on Ref. To halt walking, call walk(Ref,0).

    This function returns immediately, but continues to process in the background.


    walk_towards proc

    See also:
    get_step_towards proc
    step_towards proc
    step_size var (movable atom)
    Format:
    walk_towards(Ref,Trg,Lag=0,Speed=0)
    Args:
    Ref: A mob or obj.
    Trg: An object on the map.
    Lag: Delay in world ticks between movement.
    Speed: Speed to move, in pixels. 0 uses Ref.step_size.

    Move Ref in the direction of Trg continuously. Each step will be preceded by Lag time of inactivity.

    A call to a walking function aborts any previous walking function called on Ref. To halt walking, call walk(Ref,0).

    This function returns immediately, but continues to process in the background.


    while proc

    See also:
    break proc
    continue proc
    do proc
    for loop proc
    Format:
    while( E ) Statement

    If E is true (non-zero) execute Statement. Continue testing E and doing the while block until E becomes false (zero).

    Statement may be a block of code or a single statement.

    Example:

    var/i = 3 while(i) world << i--

    This outputs:

    3 2 1

    winclone proc

    See also:
    winexists proc
    winget proc
    winset proc
    winshow proc
    Format:
    winclone(player, window_name, clone_name)
    Args:
    player: A mob or client.
    window_name: The name of a window, pane, menu, or macro set in the world's skin file.
    clone_name: The name of the new window, pane, menu, or macro set to create.

    Creates a clone of a window, pane, menu, or macro set that exists in the world's skin file. The original object as it exists in the skin file (not its current state) is used as a template to build the clone. The clone will exist only for the player you choose.

    Example:

    winset(usr, "templatewindow", "clonedwindow")

    If a window is not visible by default, it will have to be shown with winset() or winshow(). A pane may be shown by using it in a Child or Tab control. Menus or macros must be assigned to a window with winset() before they will work.

    If window_name is "window", "pane", "menu", or "macro", and the skin file does not have a control of that name already, the proc will create a new control of that type from scratch. A new window is invisible by default. For windows and panes, you should give them a size with winset() before adding any controls so you can set their anchors properly.

    Once a clone is created, it can be deleted via a winset() call:

    Example:

    winset(usr, "clonedwindow", "parent=none")

    winexists proc

    See also:
    winclone proc
    winget proc
    winset proc
    winshow proc
    Format:
    winexists(player, control_id)
    Args:
    player: A mob or client.
    control_id: The unique ID of a control in the player's skin.

    Tells if a control exists and if so, what type it is. The return value is an empty string if the control does not exist, but otherwise it is the type of control. See the Skin reference for information about the types of controls this proc can return.

    This proc will not tell you if a control has been defined in the skin file but is not in use yet.


    winget proc

    See also:
    winexists proc
    winset proc
    Skin reference
    Format:
    winget(player, control_id, params)
    Args:
    player: A mob or client.
    control_id: The unique ID of a control in the player's skin.
    params: The name of a parameter to read, or a semicolon-separated list of parameters

    Retrieves info from a player about the current state of their skin. If control_id and params are each just a single value, then the return value will be a simple string with the value of that parameter. If control_id or params is a semicolon-separated list like the kind used in list2params(), then the result will be in a similar format, and can be converted to a list form using params2list().

    The control_id can be a window name, or in a "[window].[control]" format, or just the control ID as long as it is unique. You can retrieve info on more than one control at once by separating them with semicolons, like "button1;button2".

    Example:

    usr << "mainwindow.is-visible = [winget(usr, "mainwindow", "is-visible")]" usr << "\nOther params:" usr << winget(usr, "mainwindow", "pos;is-maximized") usr << "\nButtons:" usr << winget(usr, "button1;button2", "is-checked")

    This outputs:

    mainwindow.is-visible = true Other params: pos=0x0;is-maximized=true Buttons: button1.is-checked=true;button2.is-checked=false

    If the returned result is actual text for any parameters, the single quote or double quote characters may be escaped with a backslash. An actual backslash will also be escaped with a backslash.

    You can also use a special wildcard format to retrieve info about all the controls in a window, menu, or macro set. If control_id is "mainwindow.*" for instance, then any control that is part of mainwindow--and mainwindow itself--is included in the result if it has the parameter(s) you're looking for. Use params2list() to interpret the result. See the skin reference for more details.


    winset proc

    See also:
    winclone proc
    winexists proc
    winget proc
    winshow proc
    Skin reference
    Format:
    winset(player, control_id, params)
    Args:
    player: A mob or client.
    control_id: The unique ID of a control in the player's skin.
    params: A list of parameters to set, in the format returned by list2params().

    Sets parameters for a player's skin. The parameter list can be created by making a list and using list2params(), or it can be done manually by just using a string like "is-visible=true;text-color=#f00".

    The control_id can be a window name, or in a "[window].[control]" format, or just the control ID as long as it is unique.

    If you want to use a text string that may include spaces, surround the string with double quotes and escape them using a backslash, e.g. "text=\"This is some text.\"". Backslashes can also be used by preceding them with another backslash. For filenames, use single quotes around the file. Sometimes escapement may need to go several levels deep; for example to set up an input control with a default say command, you will need to escape it twice:

    Desired command: say "
    Escaped form with quotes: "say \""
    Final form: \"say \\\"\"

    winset(usr, "mainwindow.input", "command=\"say \\\"\"")

    You can set more than one control's parameters at once by leaving the control_id argument null, and including the control as part of the parameter list:

    winset(usr, null,\ "mainwindow.output.background-color=#ffffff;mainwindow.input.background-color=#ffffff")

    Another use for winset() is to send commands to the client that normally can only run from there, like .profile or .quit. To do this leave the control_id argument null, and just use a parameter called "command":

    obj/quitbutton name = "Quit" icon = 'buttons.dmi' icon_state = "quit" Click() winset(usr, null, "command=.quit")

    winshow proc

    See also:
    winclone proc
    winget proc
    winset proc
    Format:
    winshow(player, window, show=1)
    Args:
    player: A mob or client.
    window: The name of a window in the player's skin.
    show: Use a nonzero value to show the window, zero to hide it.

    Shows or hides a window in the player's skin.


    savefile

    See also:
    >> operator (savefile)
    << operator (savefile)
    Export proc (client)
    New proc (client)
    savefile procs
    vars (savefile)

    A database file in DM is called a "savefile". All of the contents of a savefile reside in a single file. The contents of the file are stored in database directories. These should not be confused with real directories in the external file system. The database directories are all contained inside the one file.

    Each database directory contains a list of sub-directories and a buffer in which data may be written. The absolute path to a directory has the following format: "/Dir1/Dir2/...". The current directory may be set by assigning its absolute path name to savefile.cd. A relative path (one that doesn't begin with "/") may also be used, in which case the new path starts at the current directory. The path "." stands for the current directory, ".." for its parent, "../.." for its parent's parent, etc.

    A savefile may be created with new/savefile(name). The optional name argument may be an external file name (existing or to be created) in double quotes or a file from the resource cache in single quotes. Of course, a variable containing either of these types of values may also be used. If no name is specified, a temporary file will be created, which will be destroyed when the savefile is no longer in use. If a resource cache is specified, a temporary file will be created and the contents of the cached file will be copied into it. Changes will therefore only be temporary.


    operators (savefile)

    Built-in savefile operators:

    savefile/operator
    <<
    >>

    >> operator (savefile)

    See also:
    >> input operator
    << operator (savefile)
    Read proc (datum)
    Format:
    F >> Var
    F["Path"] >> Var

    Reads a value from a buffer into a variable. If Path is not specified, the current buffer will be used. Otherwise, the buffer at the specified path will be accessed. Whenever the current directory is set, reading starts at the beginning of that buffer (replacing any previous contents). For this reason, when the Path parameter is given, the first value in the specified buffer is always read. If there is no data in the buffer or the end of the buffer has been reached, null is returned.

    If the value read is a previously written object, its own directory will be opened and the object's Read proc will be called to load any data that was written in the object's Write proc.

    If the value read is a savefile (ie a savefile inside of a savefile), it is treated a little differently. Instead of returning a savefile object, it returns data cached in the world's rsc file. This is to give you control over what file this data is copied into before it is opened as a savefile. If you want to just open it up in a temporary file, do something like this:

    obj var savefile/myfile Read() . = ..() //do the normal stuff if(myfile) //load data into a temporary file and create savefile object myfile = new/savefile(myfile)

    << operator (savefile)

    See also:
    >> operator (savefile)
    << output operator
    Write proc (datum)
    Format:
    F << Val
    F["Path"] << Val

    Writes Val to a buffer. If Path is not specified, the current buffer will be used. Otherwise, the buffer at the specified path will be written to. Whenever the current directory is set, writing starts at the beginning of that buffer (replacing any previous contents). For this reason, when the Path parameter is given, the specified buffer is always overwritten.

    If Val is an object, a separate directory will be created for the object and the object's Write proc will be called. In addition to data that may be written by the Write() proc, the type of the object is stored in a buffer called "type". In the case of turfs, the location of the turf is also recorded so that it can be recreated at the same position. All other objects must be repositioned after the object is recreated (like in the object's Read() proc).

    Single operations that write multiple values (such as saving an object) are handled somewhat specially to avoid two references to the same object creating duplicate entries in the savefile. After the object being referenced is written once, successive references to the same object will be saved simply as references rather than as full objects. If this was not done, two references to the same object would be read back in as two separate objects. This also avoids infinite loops that would result when objects contain references back to themselves.


    savefile procs

    savefile/proc
    ExportText
    ImportText
    Lock
    Unlock
    New

    ExportText proc (savefile)

    See also:
    ImportText proc (savefile)
    Format:
    savefile.ExportText(path=cd,file)
    Args:
    path: the path to export
    file: optional file to write to

    Converts all or part of a savefile to a human readable text format, similar in syntax to DM. If no file is specified, the savefile text is returned as a text string instead of being written to a file.

    The following example shows how to export and later import a savefile. The user's mob is written into a directory with the same name as their ckey and the result is written to a text file.

    Example:

    mob/verb/write() var/savefile/F = new() var/txtfile = file("players/[ckey].txt") F[ckey] << usr fdel(txtfile) F.ExportText("/",txtfile) usr << "Your savefile looks like this:" usr << "&lt;pre&gt;[html_encode(file2text(txtfile))]&lt;/pre&gt;" mob/verb/read() var/savefile/F = new() var/txtfile = file("players/[ckey].txt") F.ImportText("/",txtfile) F[ckey] >> usr

    ImportText proc (savefile)

    See also:
    ExportText proc (savefile)
    Format:
    savefile.ImportText(path=cd,source)
    Args:
    path: the path at which to write the imported data
    source: a file or text string to import

    Reads a text file or string and writes it into a savefile. See ExportText for an example.


    Lock proc (savefile)

    See also:
    New proc (savefile)
    Unlock proc (savefile)
    Format:
    Lock(timeout)
    Args:
    timeout: seconds to wait; -1 for no timeout
    Returns:
    1 on success; 0 on failure

    In order to modify a savefile, exclusive access to the file must be guaranteed, so that other processes reading or writing to the file do not experience data corruption. This is known as "locking" the file. While the file is locked, only the world that obtained the lock may access it.

    Normally, you do not need to worry about this, because a lock is automatically obtained upon the first attempt to write to the file. In a CGI application, where many instances of the program might be running simultaneously, the normal locking, which just tries once and crashes the proc on failure, would not be ideal.

    Explicitly calling Lock() allows you to specify a timeout and it also allows you to handle the case in which no lock could be obtained. If you want it to wait indefinitely, use -1. Just be careful if there are several files read by multiple processes that it is not possible for deadlock to occur.

    Obtaining a lock will fail if the file is locked by another world or if it is even open by any other world.

    If you are using Lock(), then you probably also want to specify a timeout when you open the savefile, since that too can fail due to the file being locked by another process.


    New proc (savefile)

    See also:
    Lock proc (savefile)
    Unlock proc (savefile)
    Format:
    New(filename,timeout)
    Args:
    filename: name of file or empty for temporary file
    timeout: seconds to wait; -1 for no timeout

    You call this via new/savefile(filename,timeout). The timeout is used to determine how long to wait if the file is locked. Normally (timeout=0), if the file is locked, the proc crashes with a runtime error. If you specify a timeout, then it will keep trying to open the file and if this fails, it will simply return with savefile.name being empty (ie a false value).

    If the first argument is an entry in the world's rsc cache, the data will be copied into a temporary file and accessed from there. Changes to this, and any other temporary file, are not saved. When you close the file, it simply gets deleted.


    Unlock proc (savefile)

    See also:
    Lock proc (savefile)
    New proc (savefile)
    Format:
    Unlock()

    Exclusive locks are automatically released when the savefile is closed, but if you want to keep reading the file and allow other processes to do the same, then you can explicitly unlock it.

    Note that this does not allow other processes to lock the file. It only allows them to read from it. As long as the file is open by more than one process, no lock may be obtained.


    vars (savefile)

    savefile vars:

    savefile/var
    cd
    dir
    eof
    name

    cd var (savefile)

    See also:
    savefile

    This is the path name of the current directory. Setting it causes the current directory to change. (We are talking about the current database directory inside the savefile. It is not a real directory on the filesystem.) It is perfectly legal to change to a non-existent directory. This new directory will not be saved to disk unless its buffer (or one of its children) is modified, however.

    Example:

    var/savefile/F = new() // temporary file F.cd = "/MyDir/Icon" F.cd = ".." // change to /MyDir F.cd = "Icon" // change to /MyDir/Icon

    dir list var (savefile)

    See also:
    list
    savefile

    The name of each child directory of the current data directory is stored in the list savefile.dir. New directories may be created with savefile.dir.Add() and removed with savefile.dir.Remove(). To test for the existence of a directory, use savefile.dir.Find(). (Note that these are database directories inside the savefile--not real directories on the filesystem.)

    The order of directories is not necessarily preserved, so do not assume, for example, that newer directories will be at the end of the list.


    eof var (savefile)

    If there is more data to read in the current buffer, eof is 0; otherwise it is 1. Setting eof to 1 moves to the end of the buffer and 0 moves to the beginning. Setting it to -1 deletes the current buffer.


    name var (savefile)

    See also:
    savefile

    The external "real" filename is stored in file.name. It is initialized when creating a new file. If none is specified, a temporary file with a random name will be created.

    Example:

    var/savefile/F1 var/savefile/F2 F1 = new() // create a temp file F2 = new("myfile") // open "myfile" world << "F1.name = [F1]" world << "F2.name = [F2]"

    sound

    See also:
    vars (sound)
    sound proc

    A /sound datum is created by the sound() proc or by new/sound(). It can be used to change the way a sound file will play. When you're ready to play the sound, just send it to a player like so:

    var/sound/S = sound('bubbles.wav') usr << S

    vars (sound)

    Built-in sound vars:

    sound/var
    file
    repeat
    wait
    channel
    volume
    frequency
    pan
    priority
    status
    x, y, z
    falloff
    environment
    echo

    file var (sound)

    See also:
    sound proc
    vars (sound)

    This is the file that will be played when the sound is sent to a player.


    repeat var (sound)

    See also:
    sound proc
    vars (sound)
    Default value:
    0 (do not repeat)

    Set to 1 to repeat the sound indefinitely once it begins playing, 2 to repeat it forwards and backwards.


    wait var (sound)

    See also:
    sound proc
    vars (sound)
    Default value:
    0 (do not wait)

    Set to 1 to wait for other sounds in this channel to finish before playing this one.


    channel var (sound)

    See also:
    sound proc
    vars (sound)
    Default value:
    0 (any channel)

    For sound effects, set to 1 through 1024 to choose a specific sound channel. For values of 0 or less, any available channel will be chosen. If you play a null sound (no file) on channel 0, the settings for the datum will affect all channels.


    volume var (sound)

    See also:
    sound proc
    vars (sound)
    Default value:
    100 (full volume)

    Set to a percentage from 0 to 100 of the sound's full volume. It will play at that volume when it is sent to a player.


    frequency var (sound)

    See also:
    vars (sound)
    Default value:
    0

    Any value from -100 to 100 will play this sound at a multiple of its normal frequency. Set to 2 to play at double speed, for example, or -1 to play backwards. A value of 0 or 1 will play the sound at its normal frequency.

    Set to a specific frequency (in Hz) outside of the -100 to 100 range to change the playback rate of the sound. A negative value is also allowed. The value 0 means that the sound should be played as-is. This value will take effect when the sound is sent to a player.

    CD-quality sound is sampled at 44.1 KHz, which is a value of 44100. Other common sample rates for .wav files are 8000, 11025, and 22050. (11025 is usually a good quality for most sound effects without making file size too large.) If you know the file's sample rate, doubling the value will play it at a higher pitch and twice as fast; halving it will play it at a lower pitch and twice as slow.


    pan var (sound)

    See also:
    vars (sound)
    Default value:
    0

    Alter the panning of a sound. -100 is full left, 100 is full right, and 0 is at the center. This value will take effect when the sound is sent to a player.

    For music, pan can range from -100 (no pan separation) to 0 (full separation).


    priority var (sound)

    See also:
    vars (sound)
    Default value:
    0

    Sounds with higher priority may steal channels from sounds of lower priority. The maximum value is 255. 0 is the lowest.


    status var (sound)

    See also:
    vars (sound)
    Default value:
    0

    Alter the way the sound is heard by affecting several different on/off values which combine as bit flags.

    SOUND_MUTE // do not play the sound SOUND_PAUSED // pause sound SOUND_STREAM // create as a stream SOUND_UPDATE // update a playing sound

    Use the | operator to combine these values. The setting you choose will take effect when the sound is sent to a player.

    SOUND_MUTE | SOUND_UPDATE will mute a sound, but it will continue to play. It can be unmuted while still playing by resending it with status=SOUND_UPDATE.

    SOUND_PAUSED | SOUND_UPDATE will pause a sound. It can be restarted from its current position by resending it with status=SOUND_UPDATE.

    SOUND_STREAM will create this sound as a stream. Streams take less memory, but can not play multiple times at once, nor can they play in reverse. This flag is only valid the first time that a sound is played in a particular mode (normal vs. 3D). Changing the flag later will not change the stream status of the sound in that mode.

    SOUND_UPDATE updates the settings for the sound currently playing on the specified channel. If this flag is not set or no channel is specified, the sound will start again from the beginning.


    x, y, and z vars (sound)

    See also:
    vars (sound)
    falloff var (sound)
    Default value:
    all 0

    Set to different values to give your sound a 3D effect which will be applied when it is played. Positive values for x will sound as if they come from the right, positive y sounds like it is above the player's head, and positive z sounds like it is directly ahead. The effect of 3D sound depends on the player's computer's sound card, and is greatly enhanced when wearing headphones.

    Depending on the value of falloff, the settings for the location of the sound can also affect its volume. Once the distance passes the value of falloff, the volume will diminish.

    If these values are all set to 0, you should set environment if you want to treat it as a 3D sound. Otherwise BYOND will assume this is meant to be a non-3D sound such as music or the interface.


    falloff var (sound)

    See also:
    vars (sound)
    x, y, z vars (sound)
    Default value:
    1

    Within the falloff distance a 3D sound stays at the constant loudest volume possible. Outside of this distance it attenuates at a rate determined by the falloff.

    Higher values will make sounds fade out more slowly as they get farther away. The distance of a sound is set by x, y, and z.


    environment var (sound)

    See also:
    vars (sound)
    x, y, z vars (sound)
    echo var (sound)
    Default value:
    -1

    Changes the environmental reverb for all 3D sounds until another environment is specified. Only 3D sounds react to the environment. Please see the EAX2 documentation at http://developer.creative.com/ for detailed information about these settings.

    This value may be a number which selects a preset, or a list to choose settings manually. The default value (-1) specifies no change in environment. A numeric value from 0 to 25 specifies a set of reverb presets for the environment. The environment presets are:

    1. generic
    2. padded cell
    3. room
    4. bathroom
    5. livingroom
    6. stoneroom
    7. auditorium
    8. concert hall
    9. cave
    10. arena
    11. hangar
    12. carpetted hallway
    13. hallway
    14. stone corridor
    15. alley
    16. forest
    17. city
    18. mountains
    19. quarry
    20. plain
    21. parking lot
    22. sewer pipe
    23. underwater
    24. drugged
    25. dizzy
    26. psychotic

    A 23-element list represents a custom environment with the following reverbration settings. A null or non-numeric value for any setting will select its default.

    1 EnvSize (1.0 to 100.0) default = 7.5
    environment size in meters
    2 EnvDiffusion (0.0 to 1.0) default = 1.0
    environment diffusion
    3 Room (-10000 to 0) default = -1000
    room effect level (at mid frequencies)
    4 RoomHF (-10000 to 0) default = -100
    relative room effect level at high frequencies
    5 RoomLF (-10000 to 0) default = 0
    relative room effect level at low frequencies
    6 DecayTime (0.1 to 20.0) default = 1.49
    reverberation decay time at mid frequencies
    7 DecayHFRatio (0.1 to 2.0) default = 0.83
    high-frequency to mid-frequency decay time ratio
    8 DecayLFRatio (0.1 to 2.0) default = 1.0
    low-frequency to mid-frequency decay time ratio
    9 Reflections (-10000 to 1000) default = -2602
    early reflections level relative to room effect
    10 ReflectionsDelay (0.0 to 0.3) default = 0.007
    initial reflection delay time
    11 Reverb (-10000 to 2000) default = 200
    late reverberation level relative to room effect
    12 ReverbDelay (0.0 to 0.1) default = 0.011
    late reverberation delay time relative to initial reflection
    13 EchoTime (0.075 to 0.250) default = 0.25
    echo time
    14 EchoDepth (0.0 to 1.0) default = 0.0
    echo depth
    15 ModulationTime (0.04 to 4.0) default = 0.25
    modulation time
    16 ModulationDepth (0.0 to 1.0) default = 0.0
    modulation depth
    17 AirAbsorptionHF (-100 to 0.0) default = -5.0
    change in level per meter at high frequencies
    18 HFReference (1000.0 to 20000) default = 5000.0
    reference high frequency (hz)
    19 LFReference (20.0 to 1000.0) default = 250.0
    reference low frequency (hz)
    20 RoomRolloffFactor (0.0 to 10.0) default = 0.0
    like rolloffscale in System::set3DSettings but for reverb room size effect
    21 Diffusion (0.0 to 100.0) default = 100.0
    Value that controls the echo density in the late reverberation decay.
    22 Density (0.0 to 100.0) default = 100.0
    Value that controls the modal density in the late reverberation decay
    23 Flags default = 63
    Bit flags that modify the behavior of above properties
    • 1 - 'EnvSize' affects reverberation decay time
    • 2 - 'EnvSize' affects reflection level
    • 4 - 'EnvSize' affects initial reflection delay time
    • 8 - 'EnvSize' affects reflections level
    • 16 - 'EnvSize' affects late reverberation delay time
    • 32 - AirAbsorptionHF affects DecayHFRatio
    • 64 - 'EnvSize' affects echo time
    • 128 - 'EnvSize' affects modulation time

    echo var (sound)

    See also:
    vars (sound)
    x, y, z vars (sound)
    environment var (sound)
    Default value:
    null

    If set to an 18-element list, this value customizes reverbration settings for this sound only. A null or non-numeric value for any setting will select its default. Please see the EAX2 documentation at http://developer.creative.com/ for indepth information about these settings.

    Here's a rundown of some of the terms: Direct refers to the amount of effect when the sound is on a direct path to the listener. Obstruction is when an object is blocking the direct path but there are other ways for the sound to reach the listener. Occlusion means the sound is on the other side of a wall, and mostly blocked. Exclusion means the sound is on the other side of a wall, but a doorway or window is be allowing it to pass through to the listener. You can use a little of each of these effects to increase realism.

    1 Direct (-10,000 to 1,000) default = 0
    direct path level (at low and mid frequencies)
    2 DirectHF (-10,000 to 0) default = 0
    relative direct path level at high frequencies
    3 Room (-10,000 to 1,000) default = 0
    room effect level (at low and mid frequencies)
    4 Room HF (-10,000 to 0) default = 0
    relative room effect level at high frequencies
    5 Obstruction (-10,000 to 0) default = 0
    main obstruction control (attenuation at high frequencies)
    6 ObstructionLFRatio (0.0 to 1.0) default = 0.0
    obstruction low-frequency level re. main control
    7 Occlusion (-10,000 to 0) default = 0
    main occlusion control (attenuation at high frequencies)
    8 OcclusionLFRatio (0.0 to 1.0) default = 0.25
    occlusion low-frequency level re. main control
    9 OcclusionRoomRatio (0.0 to 10.0) default = 1.5
    relative occlusion control for room effect
    10 OcclusionDirectRatio (0.0 to 10.0) default = 1.0
    relative occlusion control for direct path
    11 Exclusion (-10,000 to 0) default = 0
    main exlusion control (attenuation at high frequencies)
    12 ExclusionLFRatio (0.0 to 1.0) default = 1.0
    exclusion low-frequency level re. main control
    13 OutsideVolumeHF (-10,000 to 0) default = 0
    outside sound cone level at high frequencies
    14 DopplerFactor (0.0 to 10.0) default = 0.0
    like DS3D flDopplerFactor but per source
    15 RolloffFactor (0.0 to 10.0) default = 0.0
    like DS3D flRolloffFactor but per source
    16 RoomRolloffFactor (0.0 to 10.0) default = 0.0
    like DS3D flRolloffFactor but for room effect
    17 AirAbsorptionFactor (0.0 to 10.0) default = 1.0
    multiplies AirAbsorptionHF member of environment reverb properties.
    18 Flags default = 7
    Bit flags that modify the behavior of properties
    • 1 - Automatic setting of 'Direct' due to distance from listener
    • 2 - Automatic setting of 'Room' due to distance from listener
    • 4 - Automatic setting of 'RoomHF' due to distance from listener

    turf

    See also:
    atom
    procs (turf)
    vars (turf)
    Map

    Turfs cover the surface of the map. They are derived from /turf.

    Example:

    turf floor desc = "A wood plank floor." wall desc = "A stone wall." density = 1

    This example defines the turf prototype turf/floor and /turf/wall.

    Turfs cannot be moved. They can only be created or destroyed by changing world.maxx, world.maxy, or world.maxz. When you create a new turf with new(), it always replaces the old one.

    Example:

    // replace old_turf with a wall var/turf/wall/T = new(old_turf)

    procs (turf)

    Built-in turf procs:

    turf/proc
    Click
    DblClick
    Del
    Enter
    Entered
    Exit
    Exited
    MouseDown
    MouseDrag
    MouseDrop
    MouseEntered
    MouseExited
    MouseMove
    MouseUp
    New
    Read
    Stat
    Topic
    Write

    vars (turf)

    Built-in turf vars:

    turf/var
    alpha
    blend_mode
    color
    contents
    density
    desc
    dir
    gender
    icon
    icon_state
    invisibility
    underlays
    overlays
    loc
    layer
    luminosity
    mouse_over_pointer
    mouse_drag_pointer
    mouse_drop_pointer
    mouse_drop_zone var
    mouse_opacity var
    name
    opacity
    parent_type
    suffix
    tag
    text
    transform
    type
    vars
    verbs
    x
    y
    z

    parent_type var (turf)

    See also:
    parent_type var

    The default parent_type of /turf is /atom.


    vars

    See also:
    path operators
    vars (atom)
    vars (client)
    vars (datum)
    vars (mob)

    Variables are derived from var.

    Variable Declaration Format:
    var/Type/Name = Value
    var Type/Name = Value

    Value defaults to null.

    The hard-coded types are:
    datum (ancestor of all objects)
    atom (all mappable objects)
    atom/movable (objs and mobs)
    obj
    mob
    turf
    area
    savefile
    client
    list
    world
    Type modifiers:
    global
    const
    tmp

    User types may be derived from anything except for /world, /list, /client, and /savefile.


    const vars

    See also:
    vars

    The const type modifier defines a constant value. This may be useful for centralizing the location of a value that is used repeatedly so that it can be easily configured. It has the advantage over #define macros of obeying the normal scope rules for variables. This means, for example, that a const variable declared inside a proc will not conflict with other variables declared elsewhere.

    Example:

    mob var/const/max_items = 100 Enter(O) if(src.contents.len >= src.max_items) return 0 return ..()

    This example defines an upper limit on the number of items a mob may carry.


    global vars

    See also:
    vars

    The global type modifier makes a var permanent and shared. This means only one copy of the var is maintained. Otherwise, separate copies of the var are maintained for each instance containing the var (be it a proc, mob, obj, etc.)

    Example:

    mob/proc/Counter() var/global/count src << "Count = [++count]"

    This example increases the count each time the proc is called. If count were not declared global, the displayed count would be 1 every time.


    tmp vars

    See also:
    savefile
    vars

    The tmp type modifier indicates that an object variable should not be automatically written to the save file. This could mean that the variable is transient--that is, it is calculated at run-time and need not be saved. It could also indicated that the designer will handle saving of that variable specially and wishes to bypass the automated routine.

    It is especially important to use tmp when you have references to external objects that should not be saved along with the object. For example, suppose players have a leader variable which indicates who or what they are following. You would not necessarily want the leader to be saved in the player's savefile. Therefore, you would need to use tmp when defining the variable.

    Example:

    mob var/tmp leader verb follow(mob/M) leader = M
    The following built-in variables are defined as tmp vars:
    type
    parent_type
    vars
    verbs
    group
    loc
    x
    y
    z
    ckey

    verbs

    See also:
    arguments (verb)
    settings (verb)
    vars (verbs)

    Verbs may be attached to mobs, objs, turfs, and areas. Players can then use them as commands if they have access to the source.

    Verbs are fundamentally the same "type" as procs, so their vars are the same.

    Example:

    mob/verb/poof() world << "POOF!"

    Whenever a player in the world types the command "poof", this verb will be invoked.

    In addition to the normal access control (see the verb src setting) verbs can be dynamically added and removed from objects. One way to do this is to use new() with the following syntax:

    new verb_path(Destination,Name,Desc)

    The Destination specifies the object to receive the verb. Name and Desc optionally specify a new name and description for the verb.

    Example:

    mob/DM/verb/kill(mob/M) del(M) mob/DM/verb/give_kill_verb(mob/M) new/mob/DM/verb/kill(M)

    This example defines two verbs (accessible to mobs of type /mob/DM). One verb kills other mobs. The other adds the kill verb to another mob (giving the second mob the ability to kill).

    In some situations, the ability to dynamically change an object's verb list is quite useful, but most of the time it is far more convenient to do the same thing by manipulating objects rather than verbs directly. For example, the previous example can be handled by having an object with the kill verb attached it it. Then players have greater versatility in manipulating the verb by simply moving the object around.

    Example:

    obj/scroll/kill/verb/kill(mob/M) set src = usr.contents //implicit src del(M)

    The use of an implicit verb source in this example gives the user access to the kill verb without having to specify the source scroll as long as the scroll exists in the user's inventory. In other words, the player types "kill rat" rather than "kill kill rat".


    arguments (verb)

    See also:
    argument expanding
    command_text (client)

    The parameters to a verb are referred to as arguments. For verbs, the input type and possible value list may also be specified.

    The possible input types are:

    text          // a quoted text string
    password      // un-echoed text (for use with input() only)
    message       // multi-line text
    command_text  // raw command text from the rest of the input line
    num           // a number
    icon          // an icon file from the user's computer
    sound         // a sound file from the user's computer
    file          // any type of file from the user's computer
    key           // a key from the user's BYOND key file
    color         // a color (see rgb proc)
    null          // indicates that the argument is optional
    
    mob
    obj
    turf
    area
    anything
    

    These can be combined with the '|' operator. The first group are called constant input types because they turn on various types of literal values that the user can type in (like a number or a text string). The second group work in conjunction with a list of objects or values. They are called input type filters because they may be used to filter out certain types of values from the list. For example a mob or an obj within sight would be specified as follows:

    myverb(M as mob|obj in view()) {...}

    A default value may be specified which takes effect in the case of null arguments. For example:

    myverb(M=usr as null|mob|obj in view()) {...}

    In this example, the input type null did not have to be used explicitly, because assigning a default value (in this case usr) turns it on by default.

    The anything input type can be used to combine values in a list with other constant input types. Here, this is done with the null input type:

    set_aggression(a="on" as null|anything in list("on","off"))

    For input types containing mob, obj, turf, or area, the possible value list defaults to view().

    If no input type is specified, the variable type will be used to determine whether it is a mob, obj, turf, or area.

    Example:

    mob/verb/tell(mob/M,msg as text) M << "[usr] tells you, /"[msg]/""

    This example defines a verb with two arguments: a target mob, and some text.


    argument expanding

    See also:
    arguments (verb)

    The expression used to to provide a list of possible values for a verb argument may reference the value of arguments prior to the one being expanded. It may even reference the value of the argument being expanded, but this will always be a text string equal to what the user has typed so far.

    In addition, there is a special variable called "expanding" which is only accessible in this context. It is 1 if the user's input is being expanded and 0 if the user's final input is being validated. In certain rare cases, you may wish to tell the difference between these two cases. For example, you could use this to have possible values which do not show up in the expansion lists, but which are accepted when typed in full.

    Example:

    mob/verb/test(A in MyProc(A,expanding)) usr << "You typed: [A]" proc/MyProc(A,expanding) var/values[] = list("one","two","three") if(!expanding) values += "secret" return values

    settings (verb)

    verb settings:

    verb/set
      name
      desc
      category
      hidden
      popup_menu
      instant
      invisibility
      src
      background
    

    Procs and verbs are the same "type" so these attributes may be set for procs as well; most of them do not have any meaning, however, unless the proc is invoked as a verb (by adding it to a verb list).


    category setting (verb)

    See also:
    default_verb_category var (client)
    show_verb_panel var (client)
    Format:
    set category = "Category"
    Args:
    Category: A text string for the category.

    Verbs in the same category are visually grouped together in the verb panels. The default is "", which is displayed in the default panel titled "Commands". You can change that default by setting client/default_verb_category.

    To hide a verb from all panels, set the category to null. The verb may still show up in right-click popup menus, so you may want to use the hidden or popup_menu verb properties instead.


    desc setting (verb)

    Format:
    set desc = "Description"
    Args:
    Description: A text string containing the help text.

    The desc attribute sets the descriptive help string for the verb. The player may access this by hitting the 'F1' key after entering the command. This will normally produce a list of each argument by type followed by the desc text. If you wish to override the syntax description, put your modified version inside parentheses at the beginning of the desc text.

    Example:

    mob/verb/tell(mob/M,T as text) set desc = "(target,message) Talk privately to someone." M << "[usr] tells you, '[T]"

    This will produce the help text:

    usage: tell target message (Talk privately to someone.)

    If the syntax description had not been supplied, it would have produced:

    usage: tell mob "text" (Talk privately to someone.)

    hidden setting (verb)

    See also:
    category setting (verb)
    invisibility setting (verb)
    name setting (verb)
    popup_menu setting (verb)
    Format:
    set hidden = Setting
    Args:
    Setting: 1 for hidden verbs; 0 otherwise.

    A hidden verb is not visible to players (in menus or in expansion lists) but if typed in full can still be accessed.

    An alternate way to hide a verb from the command-line and verb panels is to make "." the first character in the name. The verb will not show up in command-expansion (ie when hitting spacebar) until the "." has been typed. This could be useful for hiding verbs that would otherwise clutter up the verb list, while still making them relatively easy to use. If you think this is a random quirky feature, you are right. To put "." in front of the name, use the name setting.


    instant setting (verb)

    See also:
    settings (verb)
    Format:
    set instant = Setting
    Args:
    Setting: 1 for "instant" verbs; 0 otherwise.
    Default value:
    0

    Normally a player can only call one verb per tick, but they can call any number of "instant" verbs in the same tick. This setting is useful for commands called by the game's interface, or for more responsive controls like for instance the use of "combos" in fighting games.

    Verbs with the instant setting can be used on the same tick as a regular verb, but only one regular verb can be used each tick. Commands are still processed in the order they are received, so verbs that use this setting may have to wait if several regular verbs are queued up ahead of them.

    Any verbs that are already built-in, such as movement commands and mouse commands, cannot be modified to use this setting. You can, however, create replacement verbs of your own for most of them.

    Example:

    mob/verb/FastNorth() set instant = 1 usr.Move(get_step(usr,NORTH), NORTH)

    To avoid abuse by players, you should use this setting for commands that are unlikely to cause "spam" or give players any kind of unfair advantage.


    invisibility setting (verb)

    See also:
    hidden setting (verb)
    invisibility var (atom)
    sight var (mob)
    Format:
    set invisibility = Setting
    Args:
    Setting: 0 to 100
    Default value:
    same as invisibility of the source object.

    An invisible verb is only accessible to players who can see invisible objects. This is different from a hidden verb which does not clutter up the verb list but which is still accessible when typed in full.


    name setting (verb)

    Format:
    set name = "Name"
    Args:
    Name: A text string for the name.

    The name attribute of a verb defaults to the node name. Setting the name attribute explicitly may be necessary if the name includes characters not allowed in node names.


    popup_menu setting (verb)

    See also:
    category setting (verb)
    hidden setting (verb)
    invisibility setting (verb)
    Format:
    set popup_menu = Setting
    Args:
    Setting: 1 (default) for showing this verb in the popup menus; 0 otherwise.

    Use this to prevent a verb from showing up in the popup "context" menu when users right-click on objects.


    src setting (verb)

    Format:
    set src in List
    set src = List
    Args:
    List: One of view(), oview(), world, world.contents, usr, usr.contents, or usr.loc

    With the first format, if src is in List for a particular player, then that player will have access to the proc. The player must explicitly specify the name of the source on the command line.

    The second format behaves the same, except the source is not read from the command line. If more than one possible source exists, one will be chosen at random.

    When usr or world is specified for the first format, it will be expanded to usr.contents and world.contents respectively.

    The default setting depends on the type of src:

    mob: src = usr obj: src in usr // short for usr.contents turf: src = view(0) area: src = view(0)

    Example:

    obj/verb/examine() set src in view() usr << "You examine [src]."

    Example:

    obj/MagicCloak/verb/disappear() set src = usr.contents usr.invisibility = 1 view() << "[usr] disappears!"

    visibility setting (verb)

    See:
    invisibility setting (verb)

    The function of this variable has been replaced by invisibility, which provides a full range of settings.


    vars (verbs)

    See:
    vars (procs)

    . var (verb)

    See:
    . var (proc)

    args list var (verb)

    See:
    args list var (proc)

    src var (verb)

    See:
    src var (proc)

    usr var (verb)

    See:
    usr var (proc)

    world

    See also:
    procs (world)
    vars (world)

    The world node is used to define some global properties for the world. Like the other types, the world has overridable vars and procs. New vars and procs cannot be defined under world though; to make global vars and procs, use /var and /proc instead.


    procs (world)

    Built-in world procs:

    world/proc
    AddCredits
    ClearMedal
    Del
    Export
    GetConfig
    GetCredits
    GetMedal
    GetScores
    Import
    IsBanned
    IsSubscribed
    New
    OpenPort
    PayCredits
    Reboot
    Repop
    SetConfig
    SetMedal
    SetScores
    Topic

    AddCredits proc (world)

    See also:
    GetCredits proc (world)
    PayCredits proc (world)
    Format:
    AddCredits(player, credits, note)
    Returns:
    1 if the credits were added successfully, 0 or null otherwise.
    Args:
    player: a mob, client, key, or ckey
    credits: A number of credits to add to the player's account
    note: An optional note (for author purposes) for the credit change

    Adds credits to a player's account. The proc will return 1 if it is successful, or 0 if the attempt failed and should not be tried again. This feature is intended for games that make use of the credit system, and for security all such games must use a hub password.

    This proc will return null if there was no way to reach the hub. Use isnull() to check for a null value. Contacting the hub may take a few moments, so it is a good idea to use spawn() to avoid holding up the rest of the game.

    Example:

    mob/proc/QuestCompleted(name, credits) src << "Congratulations! You completed the [name] quest and earned [credits] credit\s!" world.AddCredits(name, credits, "Quest: [name]")

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    ClearMedal proc (world)

    See also:
    GetMedal proc (world)
    SetMedal proc (world)
    GetScores proc (world)
    SetScores proc (world)
    Format:
    ClearMedal(medal, player)
    Returns:
    1 if the medal was rescinded successfully, 0 or null otherwise.
    Args:
    medal: name of the medal being rescinded
    player: a mob, client, key, or ckey

    Removes a medal from a player. The proc will return 1 if it is successful, or 0 if the medal was not already awarded. If the world already knows this medal was not earned, the hub will not be contacted.

    This proc will return null if there was no way to reach the hub. Use isnull() to check for a null value. Contacting the hub may take a few moments, so it is a good idea to use spawn() to avoid holding up the rest of the game.

    Example:

    mob/NPC Die(mob/killer) // assume Die() is a proc all mobs have spawn() if(ismob(killer) && killer.key) world.ClearMedal("Pacifist", killer)

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    Del proc (world)

    See also:
    Del proc (datum)
    shutdown proc
    Format:
    Del()
    When:
    Called when the world is shutdown.
    Default action:
    Shutdown the world.

    When the world is destroyed, only the Del() proc of the world object is called automatically. If you want to delete any other objects, you must do so from within world/Del(). Once this procedure returns, any other procedures which may still be executing are immediately aborted and all objects are silently destroyed.

    To prevent accidental hangs during world/Del() from preventing shutdown, a timeout is applied to any sleeping operations such as sleep, world.Export(), and so on. If the total time slept exceeds the timeout, world/Del() is aborted. Currently, this timeout is set at 30 seconds.


    Export proc (world)

    See also:
    Export proc (client)
    Import proc (world)
    Topic proc (world)
    link proc
    shutdown proc
    Format:
    Export(Addr,File,Persist,Clients)
    When:
    Call this to send a message to another server. The message may be composed of an optional topic text string (in the address) and an optional file. This will call world.Topic() on the remote server, which may in turn call world.Import() to access the file.
    Args:
    Addr: The address of the recipient server. It should be in the form byond://server?topic. The topic portion is optional.
    File: The (optional) file to send. This could be a cache file (in single quotes) an external file (in double quotes) or a savefile.
    Persist: Set to 1 to indicate that the server should keep this connection open, to expedite subsequent calls to the same address. An open connection can be closed at a later time by passing 0 in the Persist field.
    Clients: An optional client, or list of clients, to tell the receiver about.
    Default action:
    Send the topic text string and file to the remote server and return the result of calling world.Topic() there. Note that this will cause the caller to sleep while waiting for the necessary data to be transfered.

    Example:

    mob/verb/shout(Msg as text) world << Msg world.Export("[ShadowWorld]?shout:[Msg]")

    This example defines a verb that will broadcast a message to everyone in this world as well as sending it in the form of topic text to another world whose address is stored in the variable ShadowWorld. This address could be manually set or could be the result of calling startup().

    It is also possible to access an HTTP server via world.Export(). Simply use an http address such as: http://www.byond.com. This returns a list of HTTP header parameters as well as the extra values "STATUS" and "CONTENT". The value associated with the "STATUS" entry is the HTTP status code returned by the web server (as text). The value associated with the "CONTENT" entry is the requested resource.

    Example:

    mob/verb/test() var/http[] = world.Export("http://www.byond.com") if(!http) usr << "Failed to connect." return usr << "HTTP Header:" for(var/V in http) usr << "[V] = [http[V]]" usr << "\n" var/F = http["CONTENT"] if(F) usr << html_encode(file2text(F))

    Note that the HTTP request is submitted using the GET method as opposed to the POST method. Support for POST may be added in the future.

    If the Clients argument is used, it accepts a client that is currently loggedin, a mob belonging to such a client, or a list of any of these. The remote server will receive a list of their keys in world.Topic().


    GetConfig proc (world)

    See also:
    IsBanned proc (world)
    SetConfig proc (world)
    Format:
    GetConfig(config_set,param)
    Returns:
    Value of requested parameter.
    Args:
    config_set: name of the configuration set (see below)
    param: name of the configuration parameter

    This command is for retrieving configuration information that is shared by applications installed on the same system. The configuration data is accessed by specifying the configuration "set" and the parameter within that set. The "sets" defined so far are:

    env system environment variables (changes are not persistent) admin list of site administrators ban list of banned users or IP addresses keyban list of banned users (deprecated) ipban list of banned addresses (deprecated)

    If no parameter is specified, a list of the names of all available parameters is returned.

    The format of the configuration data itself is currently being defined. It will generally be a sequence of parameters (such as produced by list2params()). For example, each ban entry would have the user's ckey or ckeyEx as the parameter, and might have data such as "reason=jerkish;message=You+jerk!".

    Example:

    mob/verb ban(key as text) world.SetConfig("ban",ckey(key),"reason=fiendish;admin=[ckey]") lookban(key as null|text) if(key) usr << "[key]: [world.GetConfig("ban",key)]" else var/lst[] = world.GetConfig("ban") for(key in lst) usr << "[key]: [world.GetConfig("ban",key)]"

    Ban files store information on a game-specific basis. You will only be able to read and write values that are set for the game you are running (defined by the value of world.hub). It is possible for a host to specify universal bans as well, but these will not be accessible via GetConfig or SetConfig. If you are using "ban" as the config_set, IP addresses are recognized automatically. (See the ban format info below.)

    It is possible, but rarely useful, to specify a configuration "space" of SYSTEM, USER, HOME, or APP. Settings made in the SYSTEM space are shared by all BYOND software on the computer. The USER space is shared by all software owned by the same user. The HOME space is shared by all worlds running with the same safe home directory. The APP space is shared by all software running from the same filesystem directory. By default, the USER space is used, and if that cannot be modified (in safe mode), then HOME is used instead. These distinctions are sometimes important on a UNIX machine, where there are many BYOND sites belonging to different users, but even then, the default behavior is almost always what you want.

    The configuration space is specified inside the configuration set parameter like this:

    world.SetConfig("APP/keyban",...)

    When reading configuration settings, the spaces are always lumped together. In cases of settings with the same name but different values, APP overrides HOME, which overrides USER, which overrides SYSTEM.

    Ban Format

    If you want to create or read bans at runtime by using the "ban" config set, these are the main parameters currently used:

    type
    The ban's type, if any. It can be "sticky", "session", or "time", or a combination separated by commas. Session bans expire when the current session is over (world.Reboot() does not affect this).
    reason
    The reason the ban was implemented; this is for the host's or admin's purposes only and is not displayed to the user.
    message
    A message to display to the user.
    keys
    Other keys caught in a sticky ban.
    IP
    Other IP addresses caught in a sticky ban.
    computer_id
    Other computer_id values caught in a sticky ban.
    time
    The number of seconds remaining in the ban. The type parameter must include "time" for this to mean anything. If this parameter is not present when a timed ban is read, it means the ban has expired.

    The old "keyban" and "ipban" config files are now just aliases for "ban".


    GetCredits proc (world)

    See also:
    AddCredits proc (world)
    PayCredits proc (world)
    Format:
    GetCredits(player)
    Returns:
    Number of credits if hub contact was successful, null otherwise.
    Args:
    player: a mob, client, key, or ckey

    Retrieves the number of available credits in a player's account. This feature is intended for games that make use of the credit system, and for security all such games must use a hub password.

    This proc will return null if there was no way to reach the hub. Use isnull() to check for a null value. Contacting the hub may take a few moments, so it is a good idea to use spawn() to avoid holding up the rest of the game.

    The best time to call this proc is before a player does something that would allow them to spend credits, and/or just afterward, so they can see what is left in their account.

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    GetMedal proc (world)

    See also:
    SetMedal proc (world)
    ClearMedal proc (world)
    GetScores proc (world)
    SetScores proc (world)
    Format:
    GetMedal(medal, player)
    Returns:
    1 if the medal has been earned by the player
    0 if the medal has not been earned
    A list of medals in list2params() format if checking all medals
    null if the hub cannot be contacted
    Args:
    medal: name of the medal being checked
    player: a mob, client, key, or ckey

    Checks to see if a medal has been awarded to the player in question. If the medal has been awarded, the return value is 1. If not, 0.

    You can also use GetMedal() to read a list of all medals a player has earned for the hub entry, by leaving the medal argument blank. If you also leave the player argument blank, you will get a list of all medals available to the hub entry. In both cases the result can be parsed with params2list().

    This proc will return null if there was no way to reach the hub or otherwise verify the medal's status. Use isnull() to check for a null value.

    Whenever possible, GetMedal() will avoid contacting the hub by using the information it was given when the user logged in. If contacting the hub is required, the proc may take a few moments to return a result. It is a good idea to use spawn() to avoid holding up the rest of the game.

    Example:

    turf/medal_door density = 1 icon_state = "closed" var/medal = "Dragon slayer" verb/Knock() usr << "<b>Guard:</b> Just checking your credentials...." var/hasmedal = world.GetMedal(medal, usr) if(hasmedal) usr << "<b>Guard:</b> Go right in." icon_state = "open" density = 0 else if(!isnull(hasmedal)) usr << "<b>Guard:</b> Sorry, no admittance without a <b>[medal]</b> badge." else usr << "<b>Guard:</b> Sorry, I lost the paperwork. Try again later."

    You can add an optional hub path argument if you want to look at a medal for a different hub entry.


    GetScores proc (world)

    See also:
    SetScores proc (world)
    GetMedal proc (world)
    SetMedal proc (world)
    ClearMedal proc (world)
    Formats:
    GetScores(key, fields)
    GetScores(count, field)
    GetScores(count, skip, field)
    Returns:
    A parameter list of scores for a given entry. Use params2list() to interpret the results.
    Args:
    key: the name of the player, character, etc. for which scores have been set
    fields: The data fields to retrieve
    count: The number of top score records to look at
    skip: The number of top score records to skip over

    Retrieves information about scores that is kept on the BYOND hub.

    This proc will return null if there was no way to reach the hub. Use isnull() to check for a null value. Contacting the hub may take a few moments, so it is a good idea to use spawn() to avoid holding up the rest of the game.

    GetScores(key, fields)

    In this form, you can get information about individual scores. This is the most common way to use GetScores().

    The key is an arbitrary text value. Usually a player's key is a good choice, but you can also use the name of their character, or anything else you like, as long as it is unique. The key is case-insensitive.

    Scores and stats use data fields, which might be things like "Score", "Level", "Class", etc. To retrieve all the fields associated with a key, leave the fields argument blank. To retrieve only certain fields, you can send a separated list like "Score;Level" which is in the same format returned by list2params().

    If you leave the key argument blank, you will get a complete list of keys that have scores and stats associated with them.

    Example 1:

    mob/var/scores_found mob/var/score = 0 mob/Login() ..() spawn() var/scores = world.GetScores(key) scores_found = !isnull(scores) if(scores) var/list/params = params2list(scores) if(params["Score"]) score = text2num(params["Score"]) src << "You have [score] point\s!"

    GetScores(count, field)
    and GetScores(count, skip, field)

    In this form, the proc gets a list of the top scores for a certain field, and gives you the keys and scores in order. To get the top 10 players by level, for instance, you would use GetScores(10,"level"). This returns a parameter list with the top keys and scores, so it might be in a form like "Bob=100;Anita=80;David=20;Charlie=5".

    The count and skip arguments are always numbers, not text. The count is the number of scores to retrieve, and skip is the number to skip over to get to them. So count=10 and skip=0 is the top 10, while count=10 and skip=5 is #6 through #15. If you leave out skip, it's a 0.

    The way you set up your hub entry is how the top scores are determined. If you told the hub that the "score" field is always sorted from highest number to lowest, then that's what you'll get. If "birthplace" is set up to use an alphabetical order, that's the order that GetScores() will use. If a field cannot be sorted, this form of GetScores() will return an empty text string.

    If you don't specify a field, your hub entry may have a default field to use. For instance if your hub page displays "Score", then "Level", then the "Score" field is the default.

    Example 2:

    mob/var/scores_found mob/Login() ..() spawn() var/top_scores = world.GetScores(10, "Booty") scores_found = !isnull(scores) if(scores) var/list/params = params2list(scores) src << "<b>Top Buccaneers:</b>" for(var/i=1, i<params.len, ++i) var/player = params[i] var/loot = params[player] src << "[i]\th place: [player] with [loot] doubloon\s" if(params.len && params[1] == key) src << "Ye be master of the seas! Take thy well-earned hat." icon_state = "Commodore"

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    Import proc (world)

    See also:
    Export proc (world)
    Import proc (client)
    Topic proc (world)
    fcopy proc
    Format:
    Import()
    Returns:
    The file sent by the remote server. The file will be downloaded to the local server's resource cache. Note that this will cause the caller to sleep while waiting for the necessary data to be transfered.
    When:
    Call this inside world.Topic() if you are expecting a file from the remote server.

    Example:

    //sending the file mob/proc/Export(Addr) var/savefile/F = new() F.Write(src) world.Export(Addr,F) //receiving the file world/Topic() var/savefile/F = new(world.Import()) F.Read() //read the mob

    This example defines a mob proc called Export() which writes the mob to a savefile and sends it to another server (specified by Addr). The remote server opens it as a savefile and creates the mob (if the same mob type is defined on both servers and mob.Read() is compatible with the sending server's mob.Write()).

    Note that another method of transferring player mobs is to use the key savefile (accessed by client.Export() and client.Import()). Direct server to server communication on the other hand could transfer data (like non-players) without the need for player involvement at all.

    Savefiles are the most common type of file to transfer, but world.Import() simply returns a reference to an item in the world's .rsc file, which could be any type of file. This particular example demonstrates how to open such a file as a temporary savefile. (It gets dumped from the cache into a separate temporary file, which is then opened as a savefile.) Other types of files would be handled differently. For example, you could use fcopy() to dump the cached item to its own separate file.


    IsBanned proc (world)

    See also:
    GetConfig proc (world)
    params2list proc
    address var (client)
    computer_id var (client)
    hub var (world)
    Format:
    IsBanned(key,address,computer_id)
    Returns:
    True value if user is banned from this world. This may be a list, in which case special meaning is attributed to certain list elements as described below.
    Args:
    key: BYOND key of the user.
    address: current IP address of the user.
    computer_id: current computer_id of the user if known.

    By default, this procedure checks the "ban" configuration file. If an entry is found for the current world (based on the value of world.hub), the parameter text is converted into a list (using params2list()), and the result is returned. Otherwise, null is returned.

    A ban that applies to all worlds on the host's computer will not call IsBanned(). The connection will simply be denied.

    This procedure is called internally whenever a new user connects (before client/New() is called). If the result is true, access is denied. If you want to ban a user but still allow them to log in (perhaps with reduced functionality), you can put "Login=1" in the parameter text. If you want to display an explanation to the user about why they are banned, you can also put "message=X" in the parameter text, where X is the message to display to the user. A reason for the ban can be added with a "reason=X" field. Of course, you can also override IsBanned() and insert these values directly into the list that is returned.

    Example

    world/IsBanned(key,address) . = ..() //check the ban lists if(istype(., /list)) .["Login"] = 1 //allow banned user to login

    When you ban people from paging you, this also causes them to be added to the keyban list. Even if they are already connected, IsBanned() will be re-evaluated and acted upon at that time. When you remove pager ban, they are removed from keyban as well.

    Additional data elements may be added to the ban list in the future. The current definition includes just the following items:

    Login
    true if banned user should be allowed to log in
    reason
    text string describing the reason or origin of the ban. For example, when people are banned from the pager, they are added to the "keyban" list with reason = "pager ban". This text is internal information only and is not displayed to the banned user.
    message
    text string explaining to the user why they were banned and possibly what they should do to be forgiven.

    Since the data in the "ban" file is in application/x-www-form-urlencoded format, it is probably not desirable to edit the file by hand. No built-in facilities for editing the file have been provided (aside from automatic addition of pager bans), but an interface could be created, using GetConfig and SetConfig to read and write the data. Extra features could also be added such as automatic inference of key associations by IP address.


    IsSubscribed proc (world)

    Format:
    IsSubscribed(player)
    IsSubscribed(player, "BYOND") (to check BYOND Membership)
    Returns:
    Number of days left in subscription, -1 for a lifetime subscriber, or null if hub contact failed
    Args:
    player: a mob, client, key, or ckey

    Checks a player for their subscription status to this game. This is a simpler alternative to client.CheckPassport(), which is deprecated, and also allows you to check even when the player has gone offline.

    This proc will return null if contacting the hub was required, but there was no way to reach the hub. Contacting the hub may take a few moments, so it is a good idea to use spawn() to avoid holding up the rest of the game.

    Example:

    mob/verb/JoinClub() if(!world.IsSubscribed(src)) src << "Sorry, the club is only for subscribers." else // go to the turf with the tag "clubhouse" loc = locate("clubhouse") src << "Welcome to the clubhouse!"

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    New proc (world)

    Format:
    New()
    When:
    Called after the world is initially loaded. The only procs preceding this one would be in the initialization of global variables and objects on the map.
    Default action:
    None.

    OpenPort proc (world)

    See also:
    port var (world)
    visibility var (world)
    See also:
    OpenPort(port=0)
    Args:
    port: the network port to open
    Returns:
    1 on success; 0 on failure

    This causes the world to be hosted on the specified network port. A value of 0 or "any" requests that any available port be used. The value "none" causes the port to be closed so that no new connections are possible.

    This proc may be overridden. If it is, calling ..() is necessary to open the port. If ..() is not called, it will not open.

    Example:

    world/OpenPort(port) // only allow subscribers to host if(host_is_subscribed) return ..()

    The "ports" configuration option in cfg/byond.txt can be used to control what ports worlds may open. The -ports command-line option may also be used. See startup for the syntax.


    PayCredits proc (world)

    See also:
    AddCredits proc (world)
    GetCredits proc (world)
    Format:
    PayCredits(player, credits, note)
    Returns:
    1 if the credits were spent successfully, 0 or null otherwise.
    Args:
    player: a mob, client, key, or ckey
    credits: A number of credits to deduct from the player's account
    note: An optional note (for author purposes) for the credit change

    Removes credits from a player's account, if they have enough. The proc will return 1 if it is successful, or 0 if the attempt failed (usually because the player doesn't have enough credits). This feature is intended for games that make use of the credit system, and for security all such games must use a hub password.

    This proc will return null if there was no way to reach the hub. Use isnull() to check for a null value. Contacting the hub may take a few moments, so it is often a good idea to use spawn() to avoid holding up the rest of the game.

    Example:

    mob/proc/ItemShop() var/items = list("Get credits!", "Magic sword"=10, "Skeleton key"=50) var/choices[0] var/item,price for(item in items) price = items[item] choices["[item]: [price] credit\s"] = item var/credits = world.GetCredits(key) if(isnull(credits)) src << "Sorry, the item shop isn't available right now." return var/choice = input(src,\ "You have [credits] credit\s. What would you like to purchase?",\ "Item Shop")\ as null|anything in choices if(!choice) return // cancel if(choice == "Get credits") src << link("http://www.byond.com/games/Author/MyGame/credits") return item = choices[choice] price = items[item] if(!price) return src << "Contacting item shop..." var/result = world.PayCredits(name, price, "Item shop: [item]") if(isnull(result)) src << "Sorry, the item shop isn't available right now." else if(!result) src << "You need [price-credits] more credit\s to buy [item]." else src << "You bought \a [item]!" // Now give the user the item and save their character // These procs are for you to define src.AddEquipment(item) src.SaveCharacter()

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    Reboot proc (world)

    Format:
    Reboot(reason)
    Args:
    reason: the reason Reboot() was called:
    Default action:

    Reload the world from scratch. Any connected players will automatically relogin. This would be useful if you needed to recompile the world after changing some code.

    In a UNIX environment, you can cause a running server to reboot by sending it the signal SIGUSR1.

    If you override this proc, you must call ..() if you want the reboot to complete normally.


    Repop proc (world)

    Format:
    Repop()
    Default action:
    Reload the obj and mob instances defined in the world map. This "repopulates" a world to its initial state. Only objects that were destroyed will be recreated.

    SetConfig proc (world)

    See also:
    GetConfig proc (world)
    Format:
    SetConfig(config_set,param,value)
    Args:
    config_set: name of the configuration set (see below)
    param: name of the configuration parameter
    value: data to store (or null to delete this entry)

    This command is for storing configuration information that is shared by applications installed on the same system. The configuration data is accessed by specifying the configuration "set" and the parameter within that set.

    For more information, see GetConfig.


    SetMedal proc (world)

    See also:
    GetMedal proc (world)
    ClearMedal proc (world)
    GetScores proc (world)
    SetScores proc (world)
    Format:
    SetMedal(medal, player)
    Returns:
    1 if the medal was awarded successfully, 0 or null otherwise.
    Args:
    medal: name of the medal being awarded
    player: a mob, client, key, or ckey

    Awards a medal to a player. The proc will return 1 if it is successful, or 0 if the medal was already awarded. If the world already knows this medal was earned before, the hub will not be contacted.

    This proc will return null if there was no way to reach the hub. Use isnull() to check for a null value. Contacting the hub may take a few moments, so it is a good idea to use spawn() to avoid holding up the rest of the game.

    Example:

    mob/monster/dragon Die(mob/killer) // assume Die() is a proc all mobs have spawn() if(ismob(killer) && killer.key) world.SetMedal("Dragon slayer", killer)

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    SetScores proc (world)

    See also:
    GetScores proc (world)
    GetMedal proc (world)
    SetMedal proc (world)
    ClearMedal proc (world)
    Format:
    SetScores(key, fields)
    Returns:
    The key, if the scores were successfully updated; null otherwise.
    Args:
    key: the name of the player, character, etc. for which scores should be set
    fields: The data fields to set

    Updates scores that are kept on the BYOND hub.

    The key is an arbitrary text value. Usually a player's key is a good choice, but you can also use the name of their character, or anything else you like, as long as it is unique. The key is case-insensitive.

    Scores and stats use data fields, which might be things like "Score", "Level", "Class", etc. Use list2params() to set the fields that you want to change. Fields that you do not include in the list will not be changed. A field with a blank value will be deleted.

    Sending an empty text string for the fields will erase the scores for that key.

    This proc will return null if there was no way to reach the hub. Use isnull() to check for a null value. Contacting the hub may take a few moments, so it is a good idea to use spawn() to avoid holding up the rest of the game.

    Example:

    var/params // Change the Score and Pet fields params = list("Score"=123, "Pet"="Dog") world.SetScores("Tom", list2params(params)) // Delete the Pet field params = list("Pet"="") world.SetScores("Tom", list2params(params)) // Delete Tom's scores entirely world.SetScores("Tom", "")

    Security note: You can specify a different hub path and hub_password by adding these as extra arguments, but this is not recommended for security reasons. If you use this feature, it should only be on games that cannot be downloaded by the public.


    Topic proc (world)

    See also:
    Del proc (world)
    Export proc (world)
    Import proc (client)
    Import proc (world)
    Reboot proc (world)
    Format:
    Topic(T,Addr,Master,Keys)
    When:
    Called when a message is received from another server by using world.Export(). If a file is expected, world.Import() may be called to get it. The return value of Topic() will be passed back to the remote server.
    Args:
    T: The topic text string specified by the remote server (everything following ? in the URL).
    Addr: The address of the remote server.
    Master: 1 if remote server is the server which started this one.
    Keys: List of keys belonging to users who are logged in on the remote server
    Default action:
    The topic "ping" returns a true value (number of players plus one), which may be useful for telling if a server is alive. The topics "Reboot" and "Del" will call world.Reboot() and world.Del() respectively if the message was sent by the master server.

    Example:

    world/Topic(T) if(findtext(T,"shout:") == 1) world << copytext(T,7)

    This example allows other servers to send this server topic text of the form "shout:msg" and will broadcast the message to all the players in this world.

    The Keys argument is either null, or a list of user keys. Any keys in the list are logged in to the remote server.


    vars (world)

    Built-in world vars:

    world/var
    address
    area
    cache_lifespan
    contents
    cpu
    executor
    fps
    game_state
    host
    hub
    hub_password
    icon_size
    internet_address
    log
    loop_checks
    map_format
    maxx
    maxy
    maxz
    mob
    name
    params
    port
    realtime
    reachable
    sleep_offline
    status
    system_type
    tick_lag
    turf
    time
    timeofday
    url
    version
    view
    visibility

    address var (world)

    See also:
    port var (world)
    url var (world)
    internet_address var (world)

    This is the network address of the machine hosting the world. If it cannot be determined, it will be null.

    The full network address of the world may be formed by concatenating the world address and port: "byond://[address]:[port]".

    In CGI mode, this is the web address of the world.

    This is the local address only. If the world is hosted via a router, the external IP address may be different. Use internet_address to find the external address, if available.


    area var (world)

    Default value:
    /area.

    This is the default area type to be placed on the map wherever no area is specified. A value of 0 turns off the default area.


    byond_version var (world)

    See also:
    DM_VERSION macro
    byond_version var (client)
    system_type var (world)

    This is the version of BYOND at run-time. A game designed to work around known bugs in older versions could use this to adapt its behavior accordingly.


    cache_lifespan var (world)

    See also:
    cache
    Default value:
    30 (days)

    Number of days items that are not in use will be saved in the resource cache (.rsc file). Files uploaded by players are stored in the world's .rsc file for future use. If the file is not used for the specified amount of time, it will be removed to save space.

    Setting this value to 0 causes items to be saved for the current session only. This is used by the CGI library, because web browsers cannot make use of server-side caches when uploading files anyway.

    This value must be a whole number.


    contents list var (world)

    See also:
    list
    Default value:
    List of all areas, turfs, mobs, and objs initially in the world.

    This is a list of every object in the world. Objects in this list are in no particular order.

    Example:

    proc/ListAreas(mob/M) var/area/A M << "Areas:" for (A in world.contents) M << A

    This example displays a list of every area in existence. As a convenient short-hand, one may simply write for(A) or for(A in world) instead of the full for(A in world.contents).


    cpu var (world)

    See also:
    tick_lag var (world)

    This is the percentage of a server tick that the server spends processing running procs. A value of 0 would indicate very little cpu usage. A value of 100 would indicate full cpu usage, which could mean that the server cannot complete all the necessary computations during a tick to finish in time for the next tick. In this case, timed events (such as sleep) may take longer than requested.

    When deciding on a value for tick_lag, one could use this value to determine if the cpu is fast enough to tick at a higher rate.


    executor var (world)

    See also:
    startup proc
    Format:
    executor = "/usr/local/byond/bin/DreamDaemon [params]"

    This option is for direct execution of .dmb files in UNIX. The most common use is for writing CGI programs that are executed by the web server.

    The first parameter in the executor text string is the path to DreamDaemon. The one listed above is the standard UNIX location.

    Optional parameters may follow. The most common are -CGI and -logself.

    Example:

    world/executor = "/usr/local/byond/bin/DreamDaemon -CGI -logself"

    This example creates a CGI program to be executed by a web server. It puts its error output in the file projname.log.

    All of this is configured for you when you include html/CGI.dm from the html library.


    fps var (world)

    See also:
    tick_lag var (world)
    Pixel movement
    Default value:
    10

    The value of world.fps defines the speed of the world in frames (server ticks) per second. By default this is 10 fps, which is a good speed if all objects move in full tiles. Higher values yield smoother results, but at a cost to performance. Timing of many events may be limited by the system clock, so fps values beyond 40 or 50 may cause unwanted effects like jitter even for projects that are not very demanding in terms of performance.

    For projects making use of pixel movement, higher fps is usually desired. 40 seems to be a good value for general use, but in worlds that have a large number of players, you may wish to lower the value and give players a higher step_size per tick instead.

    This var exists for convenience; it is calculated by 10 / world.tick_lag. The value of world.tick_lag is actually more accurate, but it is easier to think of world speed in terms of frames per second. The actual tick rate has a resolution of 1ms.

    When reading world.fps, the result is always given as a whole number to gloss over rounding error.


    game_state var (world)

    See also:
    name var (world)
    status var (world)
    visibility var (world)
    Default value:
    0

    At runtime, this value may be changed to let the BYOND hub know about certain changes in the game's status. An example for using this value is if the number of players in the game gets too high and most new logins are rejected, you can set game_state to 1 to let the hub know this server is full.

    The following values are accepted:

    0
    Normal status
    1
    Server is full -- do not trigger waiting-list alerts for this server

    Note that this value does not affect how your world reacts to new players logging in.


    host var (world)

    See also:
    game_state var (world)
    name var (world)
    status var (world)
    visibility var (world)
    Default value:
    null

    If the information is made available by the pager, this will provide the key of the world's host. If the host is not known, this value will be either null or an empty string.


    hub var (world)

    See also:
    hub_password var (world)
    name var (world)
    status var (world)
    game_state var (world)
    version var (world)
    visibility var (world)
    Default value:
    null

    This is a registered BYOND hub path. The default value of null is for unregistered games. Registered games (don't worry, it's free!) have their own hub page showing a brief description of the game, the author, an optional installation package, and links to online games. The hub path is a string of the form "YourName.GameName" and can be found in your hub console.

    Even unregistered games show up in the hub when they are live (that is online with people connected). It just doesn't show any of the extra info like a description, and there is no way for people to find out about it when nobody is logged in.

    If you do not want your game to show up in the hub (like while you are in the initial stages of development), just compile with visibility=0. Either that, or turn off your pager or your BYOND locator when you are connected to it.

    You (or the players) might also wish to turn off the notice of a live game in the hub when there is no longer any room for new players or if it is too late in the game for new people to join. At such times, you can simply set the visibility to 0.

    Example:

    world hub = "Dan.PipeStock" //registered hub path mob/verb/start_game() world.visibility = 0 //...

    If you configure your hub page to require a hub password, you must also specify world.hub_password.


    hub_password var (world)

    See also:
    hub var (world)
    visibility var (world)
    Default value:
    null

    If world.hub is set, any live session of the game will be attached to the specified BYOND Hub page. Under the default settings, any game can set world.hub and attach itself to any BYOND Hub page.

    To beef up security, you can set a hub password in your hub's configuration page via the BYOND website. This will ensure that only authorized copies of your game can attach themselves to your hub page when live. Then simply copy that password into your code as world.hub_password so that your game's live broadcast will be accepted by the hub.

    Example:

    world hub = "Dan.PipeStock" //registered hub path hub_password = "UPAggnJaeXmSBoKK" //password for live game authentication

    Note that for security reasons, reading this variable at runtime will return a hashed version of the value that was set.


    icon_size var (world)

    See also:
    map_format var (world)
    step_size var (movable atoms)
    Gliding
    Pixel movement
    Default value:
    32

    This is the tile size that will be used as a default for icons in the world. It can be set to a single number that represents both the width and height, or you can use a format like "[width]x[height]" (such as "16x48") to specify width and height separately.

    This value affects several calculations, including icon operations and gliding between turfs.

    Please note: If you do not use a square icon size and you are using a topdown map format, you may experience display issues if setting client.dir to EAST or WEST. A non-square tile with a topdown map format will also interfere with pixel movement. For this reason, square sizes are recommended when using any topdown-view map_format.


    internet_address var (world)

    See also:
    port var (world)
    url var (world)
    address var (world)

    This is the network address of the machine hosting the world, as it is seen by the outside network (from the Internet) and the hub. If it cannot be determined, it will be null.

    The full network address of the world may be formed by concatenating the world address and port: "byond://[address]:[port]".

    This var exists because world.address may not be accurate if the world is hosted on a machine behind a router using NAT. The value returned by internet_address can be given to other players who wish to log in.


    log var (world)

    See also:
    file proc
    startup proc

    Sending output to world.log may be useful for debugging purposes. The output goes to the same place run-time proc errors are displayed.

    Example:

    if(1+1 != 2) world.log << "Uh oh."

    You can assign world.log to a file name or file() object to redirect output to that file. (There is also a command-line option to Dream Daemon that does this.)

    Example:

    world.log = file("mylog.txt")

    loop_checks var (world)

    Default value:
    1

    Setting this to 0 disables the very long loop protection. By default, loops in the code which undergo a very large number of iterations or recursions are aborted (by crashing the proc). This prevents the proc from locking up the server for too long.

    You may need to disable this feature if your code has some very long loops in it. Before doing that, make sure it's not infinitely long! Your program will utterly crash if it runs out of system stack space, which can happen in a very deep or infinite recursion.


    map_format var (world)

    See also:
    icon_size var (world)
    view var (world)
    view var (client)
    screen_loc var (movable atoms)
    Topdown maps
    Isometric maps
    Side-view maps
    Big icons
    Tiled icons
    Default value:
    TOPDOWN_MAP
    Possible values:
    • TOPDOWN_MAP
    • ISOMETRIC_MAP
    • SIDE_MAP
    • TILED_ICON_MAP

    This value says how the world will display maps. In a normal overhead tiled map the value is TOPDOWN_MAP for the top-down format. For older games that predate this feature, the value is TILED_ICON_MAP.

    If you use a map format other than top-down, the HUD will still use a tile format like it would in top-down display. HUD objects are not projected into whatever map_format you use and they are not affected by changing client.dir. The size of the HUD is rounded up to the nearest number of full screen tiles; the size of each tile is defined by world.icon_size.

    Top-down format

    (See more at Topdown maps.)

    This is the default map format. Icons are drawn in a tile form and viewed from overhead. In this layout, the layer assigned to each atom is very important. The number of tiles shown is set by client.view or world.view.

    Because this format is familiar and easy to understand, it is the default setting. Most of the vars related to maps and atoms are designed and documented with this format in mind.

    Tiled icon format

    (See more at Tiled icons.) In BYOND 4.0 a new feature was introduced for using "big" icons, bigger than the standard tile size, by splitting them up into states like "0,0", "1,0", and so on. This functionality is no longer needed since BYOND now has the ability to display icons in their natural size. Some games that were designed before this, however, may still need to make use of this splitting feature that breaks icons into smaller tile-sized pieces. When an icon is broken into chunks, each state in the icon is given a thumbail version of the full image, and then new states are added to show each chunk. For instance if world.icon_size is the default 32×32, and the icon is 64×64, then the "door" state would become a thumbnail of the full door image while "door 0,0" (the lower left corner), "door 1,0", "door 0,1", and "door 1,1" were created to show each smaller section of the image. If the default "" state is broken into chunks, those chunks are just named "0,0" and so on without a space. This format is deprecated. It exists to support older games and allow them to be compiled without causing them to break, until they can be redesigned for one of the newer formats.

    Isometric format

    (See more at Isometric maps.)

    If map_format is set to ISOMETRIC_MAP, the map is displayed in isometric form. Isometric tiles are displayed in a foreshortened diagonal perspective, where the "north" direction actually displays as northeast on the player's screen, and "east" shows up as southeast. The value of client.view or world.view is used to calculate the minimum number of tiles to display, and extra tiles to each side will be shown to fill in the corners.

    In an isometric map, the tile width set in world.icon_size is the most important factor. This should be a multiple of 4 for best results. The minimum tile height is half that value, and any extra height is used to show vertical structures that "stick up" off the map surface. When you draw an isometric tile icon, start with a flattened diamond shape at the bottom that is only half as high as it is wide.

    Isometric maps behave differently during drawing than top-down maps. In isometric, tiles that are nearer to the viewer's perspective are drawn in front of tiles farther back, regardless of layer. Layers only count within an individual tile. This means that if you want to have a vertical structure "stick up" to partially hide something behind it, the icon sticking up should always be on a tile forward from the one being partly covered. E.g. if you have a wall taking up part of your tile, it needs to be at the "back" end of the tile to properly hide anything on the tiles behind it.

    The pixel_x and pixel_y values, step_x and step_y values, and the gliding that happens when moving between tiles, are based on the width set by world.icon_size. If you set world.icon_size="64x128" to show tall buildings, only the 64 matters for pixel offsets. Use atom.pixel_z to adjust the position of atoms vertically. A positive pixel_z value makes an object look higher up. The client.pixel_z value can also be used to adjust perspective. Note: Offsets for x and y also affect the layering order used to draw the icons. Any object with a pixel offset onto another tile is considered part of whichever tile is closer.

    If you use an icon wider than one tile, the "footprint" of the isometric icon (the actual map tiles it takes up) will always be a square. That is, if your normal tile size is 64 and you want to show a 128x128 icon, the icon is two tiles wide and so it will take up a 2×2-tile area on the map. The height of a big icon is irrelevant--any excess height beyond width/2 is used to show vertical features. To draw this icon properly, other tiles on that same ground will be moved behind it in the drawing order.

    One important warning about using big icons in isometric mode is that you should only do this with dense atoms. If part of a big mob icon covers the same tile as a tall building for instance, the tall building is moved back and it could be partially covered by other turfs that are actually behind it. A mob walking onto a very large non-dense turf icon would experience similar irregularities.

    Side-view format

    (See more at Side-view maps.)

    The SIDE_MAP format is like a cross between TOPDOWN_MAP and ISOMETRIC_MAP. It looks very similar to a top-down view but it is intended for more of a 3/4 perspective, where tiles lower on the screen are considered closer to the viewer. Because this impacts the way layers work, most of the layering behavior is the same as with isometric.

    In a 3/4 perspective the tiles are often foreshortened, so pixel offsets are adjusted to account for this. For example, you may set world.icon_size to "32x24", but the tile is considered to be a perfect square if you look at it from the top down. Because the width is 32 pixels, the virtual height is also 32, so if you use pixel_y=32 the atom will appear one tile further back than it normally is. (This adjustment doesn't affect screen objects or pixel_z.)

    Changing client.dir preserves the same tile size regardless of orientation.


    maxx var (world)

    See also:
    area var (world)
    maxy var (world)
    maxz var (world)
    turf var (world)
    Map
    Default value:
    0

    The world map is a three-dimensional block of turfs with coordinates ranging from (1,1,1) to (maxx,maxy,maxz). If set at compile time, it provides a lower bound and will be increased as needed by the map files.

    The default value is 0, indicating no map. If any of the map dimensions are set to non-zero values at compile time, the others will default to 1.

    New territory created by increasing the map boundaries is filled in with the default turf and area (world.turf, and world.area).


    maxy var (world)

    See also:
    area var (world)
    maxx var (world)
    maxz var (world)
    turf var (world)
    Default value:
    0

    The world map is a three-dimensional block of turfs with coordinates ranging from (1,1,1) to (maxx,maxy,maxz). If set at compile time, it provides a lower bound and will be increased as needed by the map files.

    The default value is 0, indicating no map. If any of the map dimensions are set to non-zero values at compile time, the others will default to 1.

    New territory created by increasing the map boundaries is filled in with the default turf and area (world.turf, and world.area).


    maxz var (world)

    See also:
    area var (world)
    maxx var (world)
    maxy var (world)
    turf var (world)
    Default value:
    0

    The world map is a three-dimensional block of turfs with coordinates ranging from (1,1,1) to (maxx,maxy,maxz). If set at compile time, it provides a lower bound and will be increased as needed by the map files.

    The default value is 0, indicating no map. If any of the map dimensions are set to non-zero values at compile time, the others will default to 1.

    New territory created by increasing the map boundaries is filled in with the default turf and area (world.turf, and world.area).


    mob var (world)

    See also:
    New proc (client)
    Default value:
    /mob.

    When a player connects to the world, the world is searched for a mob with the player's key. If one is found, the player is connected to that mob. If none is found, a new mob of type world.mob is created and the player is connected to this new mob.

    The default value is /mob. Setting world.mob to 0 prevents the creation of default mobs.

    Example:

    world mob = /mob/newbie mob/newbie Login() src << "Welcome, [name]." ..()

    This example will connect new players to mobs of type /mob/newbie. They are welcomed when they connect.


    name var (world)

    Default value:
    The <world> part of the <world>.dmb file.

    This is the name of the world.

    Example:

    world name = "The Void"

    params var (world)

    See also:
    list associations
    params2list proc
    startup proc
    Default value:
    null

    This is a list of parameters passed to the world from the command-line -params option when the server was started. The parameter text is passed through params2list() to generate the world.params list.

    Example:

    world/New() var/p if(params.len) world.log << "Command-line parameters:" for(p in params) world.log << "[p] = [params[p]]"

    This example displays the value of each parameter.


    port var (world)

    See also:
    OpenPort proc (world)
    address var (world)
    reachable var (world)
    visibility var (world)

    This is the network port of the world. If the world does not have an open network port, this is 0.


    realtime var (world)

    See also:
    time var (world)
    timeofday var (world)
    time2text proc

    This is the time (in 1/10 seconds) since 00:00:00 GMT, January 1, 2000 (also known as the BYOND era).

    Because this is a large number, BYOND's number system isn't capable of enough precision to deliver the exact number of 1/10 second ticks. It usually rounds off to the nearest several seconds. For more accurate readings use world.timeofday.


    reachable var (world)

    See also:
    port var (world)
    OpenPort proc (world)

    Returns 1 if the world is currently hosted and the port can be reached by players (as determined by the BYOND hub), 0 if not.

    If the port is not reachable, there may be a brief period during which the hub is still attempting to make contact; during that time the port is assumed to be reachable. Currently, the reachability test times out and fails after 30 seconds.


    sleep_offline var (world)

    Default value:
    0

    Setting this to 1 causes the world to be suspended when there are no players, even if you have sleeping procs waiting to happen. The default value is 0, which means the server will only sleep if there are no players and no procs waiting to happen. The main purpose of the variable is to save the cpu from doing work when there is nobody around to appreciate it. On the other hand, that doesn't give the poor NPC's a break from the nasty humans.


    status var (world)

    See also:
    hub var (world)
    game_state var (world)
    visibility var (world)

    This is a short text string used in BYOND hub to describe the state of a game in progress. For example, you might want to indicate if new players will be able to actively play, or whether they would have to join as spectators.

    Example:

    world status = "accepting players" mob/verb/start_game() world.status = "accepting spectators" //...

    system_type var (world)

    See also:
    byond_version var (world)
    shell proc

    This variable indicates the operating system type at run-time. It will be one of the following constants:


    tick_lag var (world)

    See also:
    fps var (world)
    sleep proc
    Default value:
    1

    This is the smallest unit of time (one server tick) measured in 1/10 seconds. The duration of events that take some finite amount of time (like sleep) will be rounded to a whole number of ticks.

    Players are limited to one command (including movements) per server tick, so this value can be used to adjust the responsiveness of the game. If the network is too slow to keep up with players, their commands will get queued up, which can be annoying when trying to move. In this case, tick_lag should be increased so that the stored up movement commands are discarded. On the other hand, if you have a very fast network, you may wish to decrease tick_lag to speed up the response time to player commands.

    Often it is more convenient to set world.fps instead of world.tick_lag, since fps (frames per second) is an easier way to think of server ticks. world.tick_lag is 10 / world.fps and vice-versa, so a tick_lag of 0.25 is equal to 40 fps.


    time var (world)

    See also:
    realtime var (world)
    tick_lag var (world)

    This gives the amount of time (in 1/10 seconds) that the world has been running. In actual fact, it is the number of server ticks that have passed multiplied by world.tick_lag. Therefore if the server sleeps (when no players are connected) this time is not counted. Also, if the server runs overtime during a tick (because procs take longer than tick_lag to finish) this still only counts as one tick. This value is therefore a measure of "game time" rather than real time.


    timeofday var (world)

    See also:
    realtime var (world)
    time var (world)
    time2text proc

    This is the time (in 1/10 seconds) since 00:00:00 GMT today. It is basically identical to world.realtime but doesn't include any information about the date. This is a much smaller number; hence it is more accurate.


    turf var (world)

    Default value:
    /turf.

    This is the default turf type to be placed on the map wherever no turf is specified. A value of 0 turns off the default turf.


    url var (world)

    See also:
    address var (world)

    This is the full network address of the world. (For example, byond://dan.byond.com:6005.)


    version var (world)

    See also:
    hub var (world)
    Default value:
    0

    If you are distributing your game to players, you can use this variable to automatically notify them of new releases. To do so, you will first need to set world.hub to the hub path of your game. You can then advertise the current version by configuring that value in your hub console.

    When players boot up an outdated version of your game (as indicated by comparing world.version with the version advertised by BYOND hub), they will be notified of the new release.


    view var (world)

    See also:
    lazy_eye var (client)
    show_map var (client)
    view proc
    view var (client)
    Default value:
    5
    Possible values:
    -1 to 34 or "WIDTHxHEIGHT"

    This is the default map viewport range. The default value of 5 produces an 11x11 viewport. A value of -1 turns off the map display altogether. The client may automatically scale down icons in order to conveniently fit the map on the player's screen.

    For non-square views, you can assign this to a text string of the form "WIDTHxHEIGHT". For example, "11x11" is equivalent to a view depth of 5, but you could make it wider like this: "13x11".

    This setting also affects the default range of the view(), oview(), range(), and orange() procedures.

    If the entire map is small enough to fit on one screen (arbitrarily defined to be 21x21 or less), the default view is automatically adjusted to fit the map. In this case, client.lazy_eye is also automatically turned on by default, since you probably don't want the map to scroll around.


    visibility var (world)

    See also:
    OpenPort proc (world)
    hub var (world)
    Default value:
    1 (visible)

    This controls whether the world advertises itself in the BYOND Hub when it has an open network port for accepting players. The visibility of the world still depends on whether any of the connected players has their location reporter turned on, and that in turn relies on the pager being turned on.


    Special notes

    This section of the reference should help explain some concepts that may be harder to understand or that can use more clarification.

    Big icons
    HUD / screen objects
    Isometric maps
    Side-view maps
    Tiled icons
    Topdown maps
    BACKGROUND_LAYER
    EFFECTS_LAYER
    TOPDOWN_LAYER

    BACKGROUND_LAYER

    See also:
    layer var (atom)
    map_format var (world)
    EFFECTS_LAYER
    TOPDOWN_LAYER

    BACKGROUND_LAYER is a special high value that can be added to the regular layer of any atom. This is only available when using a non-topdown world.map_format, such as isometric or side-view mapping.

    The purpose of this value is to make an atom appear below any regular atoms. In an isometric map for instance, HUD objects will always appear above the map, but makeing a HUD object appear behind the map is basically impossible without this feature.

    When using this special layer, it should be added to the layer an atom normally uses. For instance an obj should have a layer of BACKGROUND_LAYER + OBJ_LAYER.

    This can be mixed with TOPDOWN_LAYER and EFFECTS_LAYER, but it will take precedence over both. Anything with BACKGROUND_LAYER will always appear below anything without it.

    Images or overlays with FLOAT_LAYER can be left alone. They will automatically have the same layer as whatever atom they are attached to.

    (Note: BACKGROUND_LAYER will not be usable by clients older than build 465. If you use this value, your code should not allow older clients to connect to the server.)


    Big icons

    See also:
    icon
    icon procs
    Blend proc (icon)
    map_format var (world)
    icon_size var (world)
    Tiled icons
    Isometric maps
    Side-view maps

    BYOND allows you to use icons that are not the same size as the tile size defined in world.icon_size. These icons can be manipulated with the /icon datum using their raw, native size, and shown on the map in full size. To use the old behavior where an atom can display only an icon of the normal tile size, use the TILED_ICON_MAP value for map_format instead.

    When you use an icon of non-standard size on an atom, the icon is "anchored" to the southwest corner of the atom. If you are using a top-down view (world.map_format=TOPDOWN_MAP), the icon will appear to spread out further to the east and north. In an isometric map (world.map_format=ISOMETRIC_MAP), the icon will cover additional tiles north and east as well. The "footprint" of an isometric icon--the actual map tiles it covers--is always square, so if your tile size is 64x64 and you use a 128x64 icon, the 128-pixel width means the icon will cover a 2x2 section of map tiles.

    It is important to remember that using a big icon is a visual effect only. It will not affect how the atom bumps into other atoms or vice-versa.

    Big icons will affect layering--the order in which icons are drawn. In general, because a big icon is covering more than one tile of the map, it will try to draw above any other tiles in that space that are on the same layer. This way, you can set a turf to use a big icon without having to change the turfs to the north and east. If an atom has a big icon, any overlays and underlays attached to it will be pulled forward as well, so they will draw in front of anything on their same layer. In isometric mode this is about the same, except that the layer isn't that important--anything in the way will just be moved back behind the big icon. (Note: Big overlays will not "pull forward" on their own. If the main atom uses a single-tile icon, a big overlay attached to it will not try to draw in front of other icons on the same layer. This is so that name labels, health bar overlays, etc. will not cause any odd behavior. To be safe, you should always specify a layer when adding an overlay.)

    In isometric mode, layering is affected by the "distance" between the atom and the viewer, so putting a regular-sized icon and part of a big icon on the same tile could cause layering oddities. Tiles that are covered by a big icon will tend to be drawn behind the big icon as mentioned above. For this reason, any atoms whose icons cover more than one tile (the extra height of an isometric icon doesn't count) should always be dense, and you should block movement onto any tile covered by them.

    When manipulating icons with the /icon datum, you can still use Blend() to combine icons of different sizes. By default, the icons will be lined up at their southwest corners. You can change the position at which the second icon is blended.


    EFFECTS_LAYER

    See also:
    layer var (atom)
    map_format var (world)
    BACKGROUND_LAYER
    TOPDOWN_LAYER

    EFFECTS_LAYER is a special high value that can be added to the regular layer of any atom. This is only available when using a non-topdown world.map_format, such as isometric mapping.

    The purpose of this value is to make an atom appear above any regular atoms. For instance, in an isometric map if you want to display a character's name below them, it does not make much sense to have nearer objects cover up that name, so you can tell the name overlay to use EFFECTS_LAYER + MOB_LAYER and it will show up on top of all the normal icons on the map.

    When using this special layer, it should be added to the layer an atom normally uses. For instance an obj should have a layer of EFFECTS_LAYER + OBJ_LAYER.

    This can be mixed with TOPDOWN_LAYER. Anything in TOPDOWN_LAYER will display on top of EFFECTS_LAYER, and TOPDOWN_LAYER + EFFECTS_LAYER will be above both.

    This can also be mixed with BACKGROUND_LAYER, which takes priority over everything else.

    Images or overlays with FLOAT_LAYER can be left alone. They will automatically have the same layer as whatever atom they are attached to.


    Gliding

    See also:
    Pixel movement
    animate_movement var (movable atom)
    glide_size var (movable atom)
    bound_x var (movable atom)
    bound_y var (movable atom)
    bound_width var (movable atom)
    bound_height var (movable atom)
    step_size var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)

    Gliding is a "glitz" effect applied by BYOND to cover up the visual sins of tile-based movement, by making objects and the map appear to move smoothly from one tile to another instead of immediately jumping. Because pixel movement is now an option, gliding is deprecated; it is supported for legacy projects.

    To control the gliding speed of an atom, set glide_size to the value of your choice. If this is not set, the client will attempt to adjust the speed manually.

    The animate_movement var can be used to control the way in which an object glides, or suppress gliding altogether.

    Because gliding interferes with pixel movement, gliding is turned off if you set any of the bound or step vars for an atom to a non-default value.


    HUD / screen objects

    See also:
    screen_loc var (movable atoms)
    screen var (client)
    view var (client)
    map_format var (world)
    icon_size var (world)
    layer var (atom)
    image objects

    HUD stands for Heads-Up Display, and refers to any atoms that appear on the screen but don't move when the player moves. Any movable atom can be added to the HUD by setting its screen_loc var, and adding it to client.screen for each user who is supposed to see it. These atoms are called screen objects. This can be used to display a character's vital stats, scores, etc.

    If you want to have something like a health meter or name attached to a moving atom, use overlays or /image objects instead. An /image object is similar to a screen object in that it can be shown to only certain players instead of being shown to everyone.

    The size of the screen depends on client.view (or world.view), world.map_format, and world.icon_size. In a normal TOPDOWN_MAP map format, client.view is the same as the screen size. In other map formats the screen might be a different size.

    The screen_loc var can be set to a value like "1,1" (the southwest tile of the screen), "4,NORTH" (fourth tile from the west, along the north side of the screen), "SOUTHEAST", and so on. Pixel offsets for screen objects can be set using a colon followed by the pixel position. That is, "1:8,2:-8" means the object will be on the left-hand side of the screen, one tile up from the bottom, and then shifted 8 pixels to the rigth and 8 down.

    screen_loc can also be used to stretch the bounds of the HUD. A screen_loc of 0,0 will cause the atom to appear to the southwest of the southwest-most tile on the visible map, outside of the regular map bounds. Using HUDs in this way you can provide a nice decorative "frame" for your map.

    You can use HUDs in other map controls as well, by preceding screen_loc with the name of the map you will use followed by a colon. For instance, screen_loc="map2:1,1" will show an icon in the southwest corner of the map2 control. The actual size of a secondary HUD is based on how far out the icons in it extend in any direction. If you have one icon at "map2:1,1" and another at "map2:4,3", then that HUD will be four tiles wide and three high.


    Isometric maps

    See also:
    map_format var (world)
    icon_size var (world)
    dir var (client)
    pixel_z var (atom)
    screen_loc var (movable atoms)
    Big icons
    Side-view maps
    Topdown maps
    HUD
    BACKGROUND_LAYER
    EFFECTS_LAYER
    TOPDOWN_LAYER

    Isometric projection is a form of pseudo-3D in which the 2D icons used by BYOND can be arranged in a way to give the appearance of three dimensions. If you look at a map top-down, each tile on the map is a square. The map is rotated 45° clockwise and then tilted at an angle (30°) so that each square now looks like a foreshortened diamond from the viewer's perspective. What was once north now points to the northeast end of the viewer's screen; what was once east now points southeast to the viewer. Tiles that are more to the south or east are "nearer" to the viewer, and tiles that are north or west are "farther". The actual direction the map faces can be changed by using client.dir.

    It is important to remember that this is an illusion of 3D, not real 3D.

    To use isometric mapping, set world.map_format to ISOMETRIC_MAP. You should set world.icon_size so the tile width is a multiple of 4 pixels. The width of the tile is highly important. The height of your tiles should be at least half that value. BYOND uses a 2:1 isometric format, meaning that the diamond base of each tile is half as high as its width. For example if you have a 64x64 tile size, every diamond in the map will be 64 pixels wide by 32 high, and you have an extra 32 pixels at the top of your icon for vertical projections like buildings. If you set the tile size to 64x80, the base is still a 64x32 diamond and you have 48 pixels left over for vertical structures.

    In this mode atom.pixel_x and atom.pixel_y will offset icons along the "ground". To adjust vertical position, use the pixel_z var. Higher values of pixel_z put an atom higher above the ground level.

    Layers

    The atom.layer var behaves differently in isometric mode. Because some tiles are nearer to the viewer than others, the tiles that are farther back need to be drawn first so they are behind any tiles that should go in front of them. So in isometric mode, the back row of tiles (a diagonal line of them) is drawn first, followed by the next row forward, and so on. The layer var only matters within the confines of a given tile, so within a single tile OBJ_LAYER still gets drawn above TURF_LAYER.

    Pixel offsets, which can be set by the atom.pixel_x or atom.pixel_y vars, or change while an atom glides from one tile to another, have an impact on layering as well. When an atom straddles two tiles, it is considered to be part of the "nearer" tile for layering purposes.

    Using icons wider than the regular tile size can have an impact on layering as well. See Big icons for more information.

    Because of the order in which icons are drawn, you may want to limit the ability of an atom to cut diagonally around corners. While moving northeast behind a dense wall, for instance, a mob might temporarily appear in front of the wall because its pixel offsets (from gliding) temporarily put it on the same tile as the wall. If you do not want to limit corner-cutting, a simple workaround for this case is to give the wall a higher layer than the mob.

    Screen objects (in client.screen) are always drawn on top of all isometric tiles.

    Since it may be desirable in some games to use a topdown map for some situations (like a special battle map), you can add TOPDOWN_LAYER to any atom's layer--e.g., TOPDOWN_LAYER+TURF_LAYER--to make it appear in topdown mode. Topdown and isometric tiles really aren't meant to be mixed, but if they do mix you'll see topdown tiles always display above isometric tiles, just like screen objects do. The best way to use this is to apply TOPDOWN_LAYER to every tile in a certain part of the map that the players can't walk to.

    If you want to use an overlay that should not be covered by other "nearer" icons on the map, such as a name or health meter, add EFFECTS_LAYER to the overlay's layer. Icons with EFFECTS_LAYER will draw above regular icons. Then objects with TOPDOWN_LAYER will draw on top of everything else.

    Screen size

    In this mode, world.view or client.view is used to define the minimum number of map tiles you will see, not the screen/HUD size which is calculated from client.view. Extra map tiles are shown to fill out the screen size. HUD objects use screen coordinates, so 1,1 is still the lower left.

    The actual HUD size is always a full number of tiles, whose size is defined by world.icon_size. If you have a tile size of 64x64, and world.view=6 (a 13x13 map), a full 13x13 diamond of map tiles will be shown. The width of this diamond is 13 tiles. The height is only half that, plus whatever vertical space is needed to show the icons in that area. Then everything is rounded up to a full tile size, so the result is a 13x7-tile screen. This is the formula you need if you want to calculate the screen size:

    pixel_width = round(icon_width * (view_width + view_height) / 2) pixel_height = round(icon_width * (view_width + view_height - 2) / 4) + icon_height screen_width = round((pixel_width + icon_width - 1) / icon_width) screen_height = round((pixel_height + icon_height - 1) / icon_height)

    If you use TOPDOWN_LAYER, any topdown sections of the map will be limited to this same view.


    Pixel movement

    See also:
    Bounding boxes
    bound_x var (movable atom)
    bound_y var (movable atom)
    bound_width var (movable atom)
    bound_height var (movable atom)
    Speed and position
    step_size var (movable atom)
    step_x var (movable atom)
    step_y var (movable atom)
    locs list var (movable atom)
    contents list var (atom)
    fps var (world)
    Movement
    Move proc (movable atom)
    Cross proc (movable atom)
    Crossed proc (movable atom)
    Uncross proc (movable atom)
    Uncrossed proc (movable atom)
    Other topics
    bounds proc
    bounds_dist proc
    Gliding

    Pixel movement is a concept that allows atoms to escape the constraints of BYOND's historically tile-based movement, and move in smaller steps. In the past this had to be done with soft code, but that was sometimes inconvenient and it did not perform as well in projects with many objects moving.

    The key to understanding pixel movement is to use the bound and step vars. You use the bound family of vars to define a bounding box for a movable atom, instead of just making it one full tile in size. The step vars can give it a movement speed and offset it from the corner of the tile it's standing on.

    Those are for movable atoms only; they do not apply to turfs.

    Bounding boxes

    Left: The bounding box (blue) is the only part of the mob that actually collides with anything. By default, it would cover the whole turf (brown). Any turfs covered by the bounding box are in the mob's locs var. Right: The atom's true position (shaded) is offset from the turf by step_x and step_y.

    As an example, if your players' mobs have icons that only cover the center 24×24 pixels of a regular 32×32 icon, then you would set the mobs' bound_x and bound_y to 4--because there are 4 pixels unused to the left and bottom--and bound_width and bound_height to 24.

    The mob's physical location on the map depends on four things: Its loc, its step_x/y values, its bound_x/y values, and its bound_width/height. The lower left corner of the bounding box, relative to the turf the mob is actually standing on, begins at step_x+bound_x on the left and step_y+bound_y on the bottom.

    The physical position of the bounding box is not affected by the pixel_x/y/z vars. Those are still strictly visual offsets.

    The turfs the mob is covering can be read from the read-only locs var. The mob will also appear in the contents of those turfs. (Please note: This means if an atom is in a turf's contents, its loc is not necessarily that turf.)

    Movement

    All of the step and walk procs have been upgraded to take an additional argument, which is the speed at which the atom should move. If that argument is left out, the atom's own step_size is used by default. The step_size determines how fast the step_x and step_y values will change when moving.

    Move() has two new arguments that handle the position change gracefully. These are the step_x and step_y values for the target location.

    Pixel movement changes the behavior of the Move() proc, because a lot of things are possible that were not possible when BYOND only supported moving one tile at a time. For starters, a Move() is either a "slide" or a "jump" depending on the distance. A slide is when the move can be stopped partway; a jump is strictly pass/fail. Anything greater than one tile and the mover's regular step_size is considered a jump. Changing z levels is also a jump, as is moving to/from a non-turf.

    If step_x and step_y aren't within a good range, the new loc and the step_x/y values may be changed. The goal of Move() is for the southwest corner of the mover's bounding box to be standing on loc.

    Enter() and Exit() can be called for several turfs and/or areas, not just one at a time. It is also possible for them not to be called at all. They are only called when first attempting to enter or (fully) exit. The behavior of Enter() has also been changed; whereas in the past, it looked at the density of itself and its contents, it will now only look at contents that fully envelop that turf. This is because it is possible for an atom to be standing only partly on a turf, without fully blocking it.

    To handle collisions between two movables, a new family of procs has been added: Cross() and Uncross() are the equivalent of Enter() and Exit(), and Crossed() and Uncrossed() are like Entered() and Exited().

    If an atom is sliding, its movement can be halted if it encounters an obstacle partway along its route. Bump() will still be called for any obstacles the atom runs into, but Move() will return the number of pixels moved (the most in any direction). When sliding at a speed so fast that the distance is bigger than the atom itself, the move will be split up into several smaller slides to avoid skipping over any obstacles.

    Gliding, which was used in the past to show smooth movement between atoms, has been deprecated. It is not used at all for atoms that use any of the pixel movement capabilities.

    Pixel procs

    The bounds() and obounds() procs have been added to grab a list of atoms within a given bounding box. That box can be relative to an atom, or in absolute coordinates.

    bounds_dist() tells the distance between two atoms, in pixels. If it is positive, that is the minimum distance the atoms would have to traverse to be touching. At 0, they are touching but not in collision. A negative value means the two atoms are in collision.


    Side-view maps

    See also:
    map_format var (world)
    icon_size var (world)
    dir var (client)
    pixel_z var (atom)
    screen_loc var (movable atoms)
    Big icons
    Isometric maps
    Topdown maps
    HUD
    BACKGROUND_LAYER
    EFFECTS_LAYER
    TOPDOWN_LAYER

    The side-view map format is used for 3/4 perspective, where the map is basically similar to a top-down view but is usually foreshortened. Just like with isometric projection, tiles that are closer to the bottom of the screen are considered to be closer to the viewer. This is a form of pseudo-3D in which the 2D icons used by BYOND can be arranged in a way to give the appearance of three dimensions.

    It is important to remember that this is an illusion of 3D, not real 3D.

    The atom.layer var behaves much the same way it does in ISOMETRIC_MAP mode. Because this layout uses a concept of "near" and "far" that doesn't exist in topdown maps, screen objects will always appear in front of the regular map unless you also make use of BACKGROUND_LAYER. See isometric maps for more information.

    Often when using this mode you will want to use a foreshortened world.icon_size, like a 32x24 format instead of 32x32 for example, and use taller icons for any vertical structures like walls or buildings. If you set world.icon_size to use foreshortening, then pixel_y (or pixel_x, depending on the orientation of client.dir) will be adjusted for you. For example, with world.icon_size set to "64x32", the tile is considered to be 64x64 if you were to look at it straight down, so you would need pixel_y=64 to offset by a whole tile. This does not apply to screen objects or pixel_z.


    Tiled icons

    See also:
    icon
    icon procs
    map_format var (world)
    icon_size var (world)
    Big icons

    In BYOND 3.0, any file like a large .bmp would be treated like a regular icon that had been broken up into several tile-sized icon states. All tiles then were 32x32 pixels. An image that was 100x100 would therefore take at least 4x4 tiles to display. The icon was padded to the right and the top with blank space to become an even multiple of 32x32, and then broken up into sections. The lower left section was given an icon_state of "0,0", the next to the right was "1,0", and so on, up to the upper right which was "3,3". Another icon state, a 32x32 thumbnail of the big image, was also included.

    BYOND 4.0 expanded on this concept by allowing icons to be defined that had individual graphics bigger than 32x32, and it would break each one up into tiles just like 3.0 did. If an icon had a state called "open" then it might break down into "open 0,0", "open 1,0", and so on, while the actual "open" state would be a thumbnail image. To show the whole image, you would have to have a separate atom or overlay for each individual tile.

    As of BYOND build 455, breaking big icons into tiles is no longer done by default. Instead, icons are shown and manipulated in their native size. To use the old method of breaking icons into tiles, set world.map_format to TILED_ICON_MAP. This is the default for all projects compiled before version 455.

    When using tiled icons, there are some important things to note:

    This example shows a big icon being applied to an atom in tiled mode, as overlays:

    Example:

    // icon is 3 tiles wide by 2 high icon_state = "0,0" // A temporary object used for the overlays var/obj/O = new O.icon = icon O.layer = FLOAT_LAYER for(var/tile_y=0, tile_y<2, ++tile_y) for(var/tile_x=0, tile_x<3, ++tile_x) if(tile_x && tile_y) O.pixel_x = tile_x * 32 O.pixel_y = tile_y * 32 O.icon_state = "[tile_x],[tile_y]" overlays += O

    Topdown maps

    See also:
    map_format var (world)
    icon_size var (world)
    dir var (client)
    layer var (atom)
    screen_loc var (movable atoms)
    Big icons
    HUD
    Isometric maps
    Side-view maps

    By default, BYOND displays all maps in top-down format, so world.map_format is set to TOPDOWN_MAP unless you say otherwise. This view means players are looking down on the map, and "north" corresponds to the top of their screen. (This can be changed by setting client.dir.)

    A related map_format, used by older games, is TILED_ICON_MAP. This is also topdown but it handles icons differently.

    In this form, the atom.layer var behaves exactly as you would expect: Icons with a lower layer are drawn beneath icons with a higher layer. The only exception is when you use big icons, which will be drawn above any other icons on the same layer. Also an atom's underlays will be drawn behind it unless their layer is changed, and its overlays will draw in front of it unless otherwise stated.

    Topdown mode also guarantees that world.view or client.view will set the exact screen size used by the HUD, except for HUD objects that appear outside of the normal bounds.

    Screen objects (HUD) can be intermixed with topdown icons. They can be made to appear above or below any other icons, but usually they are displayed on top. To make sure they always appear above other icons, you can give them a high layer like 10 or 100.


    TOPDOWN_LAYER

    See also:
    layer var (atom)
    map_format var (world)
    BACKGROUND_LAYER
    EFFECTS_LAYER

    TOPDOWN_LAYER is a special high value that can be added to the regular layer of any atom. This is only available when using a non-topdown world.map_format, such as isometric mapping.

    The purpose of this value is to make an atom appear as if it belongs in a top-down map, when using a map_format other than TOPDOWN_MAP or TILED_ICON_MAP. This can be handy for title screens, or for special battle maps or the inside of a building in an RPG.

    When using this special layer, it should be added to the layer an atom normally uses. For instance a turf should have a layer of TOPDOWN_LAYER + TURF_LAYER. Usually you will want one part of the map to have TOPDOWN_LAYER, and for players to be unable to walk to there from the regular map. Mixing topdown icons and icons in the normal map_format in view of each other could look very strange. For safety's sake, the easiest thing to do is to keep them on separate z layers.

    This can be mixed with EFFECTS_LAYER. Anything in TOPDOWN_LAYER will display on top of EFFECTS_LAYER, and TOPDOWN_LAYER + EFFECTS_LAYER will be above both.

    This can also be mixed with BACKGROUND_LAYER, which takes priority over everything else.

    Images or overlays with FLOAT_LAYER can be left alone. They will automatically have the same layer as whatever atom they are attached to.