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:
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.
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.
In the above example, only the background color is important, not the font
specification.
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.
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:
<![CDATA[
<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:
<![CDATA[
"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:
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:
<![CDATA[
area
Entered(O)
if(desc) O << desc
return ..()
outside
desc = "Ah! A breath of fresh air!"
]]>
animate_movement var (movable atoms)
- See also:
- Move proc (movable atom)
- pixel_step_size var (movable atoms)
- Default value:
- FORWARD_STEPS (1)
- Possible values:
- NO_STEPS (0)
- FORWARD_STEPS (1)
- SLIDE_STEPS (2)
- SYNC_STEPS (3)
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.
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:
<![CDATA[
"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.)
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.
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.
Normal layering rules apply to screen objects, 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").
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 layer below that.
Offsets may be applied to screen_loc coordinates. For example,
"NORTH+1,WEST" is in a border above 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 line this: "1:16,1:16".
In this case the object is shifted to the northeast by 16 pixels.
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.)
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:
<![CDATA[
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")]."
]]>
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:
<![CDATA[
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!
layer var (atom)
- See also:
- overlays var (atom)
- z var (atom)
- map_format var (world)
- 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:
<![CDATA[
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, 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.
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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
]]>
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:
<![CDATA[
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:)
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:
<![CDATA[
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.
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.
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.
Export proc (client)
- See also:
- Import proc (client)
- New proc (client)
- hub var (world)
- savefile
- Format:
- client.Export(url,file)
- client.Export(file)
- Args:
- url: a Dream Seeker action url
- file: optional file to attach
The default action, when no url is specified, is to store the given 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 savefile is exported to the player's computer, it replaces any
previous savefile 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 savefile. It
is also possible for the user to tinker with the file, since it resides on
their computer.
To delete the client-side savefile completely, call
client.Export() with no argument at all.
The url parameter may be used to make Dream Seeker do one of various other
operations on the file. You normally do not call it directly but various
procedures and libraries use it internally. The URL has the following format:
<![CDATA[
"Address##action=ActionName"
]]>
In most cases, Address is blank, because the destination of the file is
simply the user's own computer. ActionName may be any one of the following:
- ftp
- offer to store the attached file on the user's computer (generated by ftp()
- run
- offer to run the attached file on the user's computer (generated by run)
- browse_rsc
- store the attached file for subsequent use by a browser page (generated by browse_rsc)
- browse_file
- display the attached file as a browser page (generated by browse)
- hubfile
- store the attached file at BYOND Hub (see hublib)
If no action is specified, the attached file is stored as a client-side
savefile.
Example:
<![CDATA[
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, that applies only to the user's hubfiles
stored at BYOND Hub. The specific query syntax is not documented here,
because those details are all taken care of by the hublib DM library.
You can use it to create a savefile shared between one or more users, useful,
for example, in turn-based games where the users can make moves whenever they
happen to log in rather than all having to play at the same time.
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)
- 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.
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:
<![CDATA[
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!
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:
<![CDATA[
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:
<![CDATA[
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).
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.
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:
<![CDATA[
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:
<![CDATA[
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.
eye var (client)
- See also:
- lazy_eye var (client)
- mob var (client)
- perspective var (client)
- pixel_step_size var (client)
- view var (client)
- virtual_eye var (client)
- view var (world)
- 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.
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:
<![CDATA[
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.
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:
<![CDATA[
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".
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.
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:
<![CDATA[
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.
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:
<![CDATA[
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.
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:
<![CDATA[
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.
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.
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:
<![CDATA[
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.
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:
<![CDATA[
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.
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:
- ICON_ADD
- ICON_SUBTRACT
- ICON_MULTIPLY
- ICON_OVERLAY
- ICON_AND
- ICON_OR
- ICON_UNDERLAY
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.
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:
<![CDATA[
// 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:
<![CDATA[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:
- For any red in the original icon, add 30% gray to the output.
- For any green in the original icon, add 59% gray to the output.
- For any blue in the original icon, add 11% gray to the output.
- Add an additional 0% (nothing).
Or this will make a nice moonlight effect:
<![CDATA[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))
]]>
- For any red in the original icon, add rgb(51,12.75,12.75) (dark pink) to the output.
- For any green in the original icon, add rgb(25.5,76.5,51) (dark bluish green) to the output.
- For any blue in the original icon, add rgb(25.5,25.5,102) (dark grayish blue) to the output.
- Add an additional 0% (nothing).
Or a negative icon (invert all colors):
<![CDATA[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:
<![CDATA[
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.
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.)
image objects
- See also:
- icon var (atom)
- image proc
- image vars
- images var (client)
- overlays 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:
<![CDATA[
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:
<![CDATA[
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.
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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. The 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:
<![CDATA[
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:
<![CDATA[
var/list/lst = list(player = "James Byond", score = 2000)
]]>
In other words, this is exactly the same syntax as for named arguments.
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:
<![CDATA[
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:
<![CDATA[
obj
clothing
gloves
]]>
One generally uses indentation when you have several things to define with
a common parent path:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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.
<![CDATA[
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:
<![CDATA[
mob/var/clothing/feet
mob/var
clothing
hands
torso
]]>
Provisos
Just do not make a mistake like the following:
<![CDATA[
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:
<![CDATA[
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 "/".
<![CDATA[
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.
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:
<![CDATA[
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:
<![CDATA[
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 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:
<![CDATA[
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:
<![CDATA[
mob/Move() // override proc
world << "moving..."
return ..() // call default
]]>
This proc will print "moving..." whenever
the mob moves.
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:
<![CDATA[
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)
]]>
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:
<![CDATA[
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:
<![CDATA[
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, let code clarity may priority.
browse proc
- See also:
- << output operator
- browse_rsc proc
- file proc
- link proc
- run 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:
<![CDATA[
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:
<![CDATA[
var/const/help = {"
<html>
<head><title>Help!</title></head>
<body>
You are beyond help!
</body>
</html>
"}
client/verb/help()
usr << browse(help,"window=help")
]]>
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:
<![CDATA[
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:
<![CDATA[
/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:
<![CDATA[
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:
- The library is located in the BYOND user bin/ folder (~/.byond/bin on unix,
typically "My Documents/BYOND/bin/" on windows). This is intended to allow the user
to install permanently "trusted" libraries. -OR-
- The server is run in -trusted mode. -OR-
- The server grants permission to access the DLL at runtime, through a prompt query.
These functions must be prototyped in the DLL as:
<![CDATA[
extern "C" char *func(int argc, char *argv[])
// argc = #arguments, argv[] = array of arguments
]]>
Example:
<![CDATA[
// 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;
}
]]>
<![CDATA[
// 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:
- cKey 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:
<![CDATA[
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.
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:
<![CDATA[
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:
<![CDATA[ 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.
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:
<![CDATA[
mob/Del()
src << "Aaaaaaaah!"
..()
mob/verb/self_destruct()
del usr
]]>
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:
<![CDATA[
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.
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:
<![CDATA[
var/i
for(i=0, i<3, i++)
world << i
]]>
This outputs:
<![CDATA[
0
1
2
]]>
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 < and > is
produced by the code >.
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:
<![CDATA[
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_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:
<![CDATA[
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:
- image: 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:
<![CDATA[
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:
<![CDATA[
overlays += image('pants.dmi',icon_state = "red")
]]>
Since the loc argument could never be a text string, the above
statement can be further shortened:
<![CDATA[
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.
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
"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:
<![CDATA[
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.
- 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:
<![CDATA[
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:
<![CDATA[
usr.Move(locate(/turf/Home))
]]>
This "teleports" the usr to a turf of the type /turf/Home.
Example:
<![CDATA[
usr.Move(locate(1,2,3))
]]>
This moves the usr to the turf at coordinates (x,y,z) = (1,2,3).
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:
<![CDATA[
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:
<![CDATA[
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.
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:
<![CDATA[
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:
<![CDATA[
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.
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:
<![CDATA[
"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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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.
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.
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:
<![CDATA[
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).
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
<![CDATA[
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:
<![CDATA[
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.
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:
<![CDATA[
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:
<![CDATA[
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.
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:
<![CDATA[
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.
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:
<![CDATA[
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.
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
"break" instruction may be used to exit from the switch statement.
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:
<![CDATA[
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:
<![CDATA[
TWO or THREE
]]>
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[
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.
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.
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.
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:
<![CDATA[
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:
<![CDATA[
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:
<![CDATA[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":
<![CDATA[obj/quitbutton
name = "Quit"
icon = 'buttons.dmi'
icon_state = "quit"
Click()
winset(usr, null, "command=.quit")]]>
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.
>> 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:
<![CDATA[
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.
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.
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.
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.
<![CDATA[
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.