BYOND Webclient Developers' Guide

Version 509.1316

The BYOND webclient is a new way of playing games, via any modern browser, so they can be shared and enjoyed even by users who don't have BYOND installed. Servers running version 507 or higher can support players from the webclient and Dream Seeker alike. Players who wish to use the Webclient can visit the appropriate page on byond.com. Dream Daemon will provide an address for them to visit, as will the hub page.

The webclient is not a perfect copy of Dream Seeker. It supports many of the same things, but in some places it does not have the same functionality, and in other places it can do even more. The client is much more customizable even than Dream Seeker's skins, and developers can create new controls for it that Dream Seeker cannot support.

The client shows an ad before gameplay, but BYOND Members have the option of disabling this.

Defining Skins

The server will attempt to convert a .dmf-style skin, if present, to a Web-usable format as best it can. However, ideally you should provide a separate .dms file that contains your skin definition. A typical skin definition might look like this:

<body>
  <div id=main byondclass=child skinparams="left=map;right=output;splitter=50">
    <div id=map byondclass=map></div>
    <div id=output byondclass=output></div>
  </div>
  <div id=input byondclass=input></div>
</body>

This skin defines which controls you want, and what class--that is, what type--each control is. The term control refers to any object that has been created by the skin and can interact with it. A class is the definition for that type of control. Several classes are defined by default. For example:

More classes exist in the standard release that can be used. The controls above are present in the default skin.

Unlike BYOND 4.0 skins in Dream Seeker, the availability of CSS means you have much more freedom to setup how the skin will look. For example, the child control used above was not a necessity. With the right styles, you can simply say where each control will go.

Like in previous BYOND versions, macros can be defined in the .dms file. However, their format has changed so that they no longer require the Alt key, and they look like this:

macro
  West+REP return ".west"
  CTRL+S return "say"
  CTRL+Z return "sleep"
  CTRL+Z+UP return "stopsleep"

The macro name format is the same as it is in skins. Modifiers are SHIFT+, CTRL+, ALT+, +REP, and +UP.

Defining Classes

Classes can be user-defined, so you have great control over your interface. This is a very short list of some of the things classes can do:

To create a class you will need a .dms file that contains styles, code, and an HTML template.

<byondclass name="widget">

<!-- These styles apply to the whole document. -->
<!-- The class "byond_widget" is applied to the div for this control. -->

<style>
.byond_widget {
  color: blue;
}
</style>

<!-- The script defines how this control will behave -->

<script>
{
  config: {bananas: 3},
  fn: {
    output: function(obj,sub) {
      this.elem.innerHTML = obj.null ? '' : obj.text;
    }
  }
}
</script>

<!-- This is the template section, all of the elements that will go inside the div -->

<div id=top>Top div</div><div id=bottom>Bottom div</div>

</byondclass>

Class styles

Styles are not, unfortunately, scoped so that they apply only to this control. However, when a div is turned into a skin control, it is given a CSS class such as byond_[byondclass], so for instance in this example it would have byond_widget.

Class templates

The template is any HTML that will be put inside the control's div element when it's created in the skin. For instance, the map class's template contains a <canvas> tag.

If you set an id attribute for any element in your template, that ID will be assigned to the control's ui member; but the ID will not be used in the live document, so using JavaScript code such as document.getElementById(id) won't be able to retrieve it. (The reason for this: You can use any class more than once in a skin, but IDs in an HTML document are supposed to be unique. Conflicts are very undesirable.) Since the ui member will already point to the item, this won't be a problem.

Class code

The script section of a class defines how it behaves. The contents of the script should be an object literal in a form like {a:1, b:2}, or any code that returns an object literal.

// Method #1: Object literal
{
  config: {bananas: 3},
  fn: {
    output: function(obj,sub) {
      this.elem.innerHTML = obj.null ? '' : obj.text;
    }
  }
}

// Method #2: Function wrapper
(function(){
  return {
    config: {bananas: 3},
    fn: {
      output: function(obj,sub) {
        this.elem.innerHTML = obj.null ? '' : obj.text;
      }
    }
  };
})()

Typically, you would be most concerned with providing an fn member, a winsetfn member, and a config member. The functions in fn override the defaults found in byond.fn that are used for all controls; you can define your own functions here as well, for your own use. In winsetfn you have a list of functions that can handle winset or winget; these override any that are found in byond.winsetfn. And config is just a handy place to store information about the current state of the control, and possibly its default settings.

The function wrapper format is useful if you need to define other functions or vars that should be kept totally private to the class. Intermediate/advanced JavaScript programmers might prefer this approach for some cases.

To retrieve the defaults for any class that has been created, call byond.skin.getClass(type).

These are the vars that are standard in a class definition, which you can override:

Class members
templateThis is filled in by the client when the class is created, from the HTML template included in the control's .dms definition.
configAn object that contains default configuration options. For instance, {maxLines: 1000} in an output control.
fnAn object containing methods that will be assigned directly to the control when it is created. Any functions here will override the ones in byond.fn, which are also given to the control.
winsetfnAn object containing winset/winget functions that will be assigned to the control's winsetfn member when it is created. Any functions here will override the ones in byond.winsetfn, which are also given to the control.

These are members and methods of the control, once it has been created by the skin using this class as a guide. Methods are defined in the class's fn member, or in byond.fn. Many methods take an argument called sub that can refer to a sub-control, like for instance a grid cell.

Control members
configAn object that contains configuration options. It is a copy of the class's config, not linked to it.
winsetfnAn object containing winset/winget functions that can be used to set or get control properties.
topThe outer div element of this control.
elemThe "main" element of this control; it is the same as top unless you change it, which is usually done in create().
uiAn object containing named items in the control. For instance, if your template had a tag with id="slider", then ui.slider will point to that element for this control.
Control methods (defined in the class's fn member or byond.fn)
content(sub)Return the element to use as the primary content area. By default this returns this.elem.
create()After the template is created, do any additional work needed to setup this class. Setting this.elem to the appropriate element is usually done here.
output(obj,sub)Output something to this control. obj is an argument that may contain one of several members:
  • null: If true, this is a request to clear the control.
  • text: Text to output; there may be other things to output as well.
  • num: A floating point number, if a number was output. There will be a text member as well in this case.
  • file: A file URL to browse or view, usually pointing to something on the game server. If the URL begins with /html/ it's a browse() file.
  • atom: An atom ID used by the client, which can be used to interact with it.
  • list: An array of output objects. This happens when a list is sent as output. E.g., if the server sends list('myicon.dmi',"blue"), this array will be: [{file:(url to myicon.dmi)}, {text:"blue"}].
  • choices: An array of possible choices returned by command expansion. (See expand().)
winset(props,sub)Set the given properties for this control. props is an object with name:value pairs. You can use the hyphenated parameter names that BYOND skins use, or camelCase.
winget(props,sub)Get the given properties for this control. If props contains a parameter called "*", it will be filled in with a full list of available parameters (in BYOND hyphenated format) and their values.
clear(sub)Clear this control.
stats(panels, verbs)Display stats. panels is an array of objects, each of which has a name, rows (number of rows), and items (an array of items, three for each row). Each item is in the format used by output(). The verbs argument is an array of objects which have name and desc members.
popup(options)Make this control popup. Options may include width and height.
popdown()If this control is currently a popup, close it.
remove()Remove this control from the skin.
keyEvent(event, any)Return true to swallow this keyboard event. The any argument is true if exact modifier keys aren't important, which is used by the map control.
onsize()Do something when resized. By default, this calls the command set in this.config.onSize, if any.
onshow()Calls the command set in this.config.onShow, if any.
onhide()Calls the command set in this.config.onHide, if any.
paneAdopted(id, newparent)Says that a pane previously belonging to this control has been adopted away. The pane's ID is id and newparent is the new owner (or null)
adopt(newparent)Adopt this pane as a child of the control whose ID is newparent (may be null). It's up to the parent control to decide how to display/hide this pane, but the old parent will be notified of the adoption by calling paneAdopted(this.id,newparent) automatically.
dock(container)Captures the existing skin contents in the given container (it may be a control, in which case they are added to container.elem, or it may be the element itself). Any controls with a higher dockOrder() are left alone, because they will end up containing this control.
dockOrder()Returns the docking priority of this control; 0 by default. Higher priority puts this control closer to the "top" of the skin; it can contain lower-priority docking controls. E.g., the hotbar has a higher priority than the D-pad, so the hotbar contains the D-pad which contains everything else.
css(selector, attribute, value)Sets or returns a CSS stylesheet rule for the given selector, for this control only. E.g., this.css('tr:hover', 'color', 'blue') will make the text in any <tr> element in this control turn blue on hover. The value argument should be null to clear the rule, and omitted completely to return the value of the current rule.
Commands
input(command)Send a command to the server.
expand(command)Request an expansion of this command. It will be sent back via output() to this same control, and the output object returned may include a choices member (a list of options) as well as text.
topic(topic)Send a link topic to the server, which will be received in client.Topic().
Mouse
mouse(params,event)Tells the client to handle a mouse event. The event argument can be sent as a member of params instead. Members of the params object may include:
  • type: The event type: "down", "up", "click", "dblclick", "move", "drag", "drop. This can be taken from the event if it isn't included.
  • id: The ID of the control sending the event.
  • panel: The name of a panel/sub-control sending the event. Can be left blank.
  • element: The element holding the atom's icon, if any.
  • atom: The numeric ID of the atom this event is for.
  • event: The event to check. The event argument, if present, overrides this.
captureMouse()Asks to capture mouse events. Capture will auto-release if the mouse leaves the window or the user lets go of the buttons.
releaseMouse()Asks to release mouse capture.
mouseEvent(event)Mouse events received during capture. By default, this just calls this.mouse({},event).
dragTarget(event)Return an object with optional parameters (the same ones used in the mouse method) to describe the panel and control ID to use when mouse events happen over this object.
Information
iconInfo(icon)Gets the information for the icon with this ID number, or null if none is found. The object return may include these numbers:
  • width, height: The size of the icon.
  • text: The maptext that goes with this icon, if any.
atomIcon(atom)Returns a data URL that can be used to display the icon for the atom with this ID number, including its overlays and underlays.
atomInfo(atom)Gets the information for the atom with this ID number, or null if none is found. The object return may include these numbers:
  • id: The atom ID.
  • name: The name of the atom.
  • appearance: The appearance ID of the atom. (Images are not taken into account.)
  • icon: The atom's icon (a number). This is a number representing the whole icon file, not the individual frame. To display this icon, set an <img> tag's src to byond.iconUrl(...) (see byond.iconUrl() for argument info).
  • state: The atom's icon_state.
  • dir: The atom's direction (a number). Corresponds to the direction constants used in the DM language.
atomVerbs(atom)Asks the server for a list of verbs for the atom with this ID number. If any are found, output() is called for this control. The output object has these properties:
  • atom: The atom ID.
  • verbs: An array of verbs. Each verb is an object with name, args, and desc properties.
Macros
hasMacro(event) or hasMacro(name)Returns true if there is a macro for this keyboard event or macro name.
getMacro(name)Returns object representing the macro by this name, if it exists; null if it does not. The object may have the following values:
  • name: The macro's full name
  • keyCode: The keyCode used by the macro.
  • command: The command to execute.
  • ctrl: True if the CTRL key is required.
  • shift: True if the SHIFT key is required.
  • alt: True if the ALT key is required.
  • up: True if this is a key-up macro.
  • rep: True if this is a repeating macro.
  • local: True if this is a local macro.
getMacros()Returns an object whose key-value pairs represent the current macros in use. Each key is the macro's keyboard combination (e.g., "CTRL+A+REP"), and each associated value is an object like the kind returned by getMacro (above).
fireMacro(name)Fires the macro by this name.
userMacros(macros)Sets a list of local macros to use. The macros argument is an object with keys such as "Ctrl+R+Rep", and the values that go with each key are the commands to use.
isCharKey(keycode)Returns true if this keycode is a regular character key.
unstickKeys()Releases the key-down info for all keys and runs any key-up macros needed.

To interact with winset and winget, you can add functions to winsetfn. Every function there takes two arguments: the value to set--or undefined or null, if it's a winget--and a sub argument for a sub-control ID if applicable. The default winset functions will all act on the element returned by this.content(sub). These are the default winset options available for all controls:

Winset/winget functions: property(value,sub)
fontFamilyThe font-family parameter, referring to the font the control should use.
fontSizeThe control's font size, in points.
fontStyleDefines the style for the control. The value is a comma-separated list containing bold, italic, underline, strike, or any combination thereof (including none of them).
color
textColor
The foreground color. In winget mode, the returned value is either "none" or a color in #RRGGBB format.
backgroundColorThe background color; a winget returns either "none" or #RRGGBB.
backgroundImageThe background image.
isVisibleWhether the control is visible (assuming a parent element doesn't hide it).

When you write a winset function, remember that the value you are given will be a string unless it is undefined or null. You can use byond.winset2bool(value) to return a true or false value instead (or null if the string couldn't be interpreted), and byond.winset2num(value) to convert to a number. If you're interacting with a style property, look at the byond object's CSS manipulation methods for more information.

The byond object

The main JavaScript object the client uses is called byond. It contains modules such as byond.skin, byond.server, and so on.

byond object modules
skinThe client skin. The client sends all its output to the skin's functions.
promptThe module in charge of handling prompts; also a function.
lightboxThe module in charge of displaying lightboxes; also a function.
eventFunctions for working with events.
byond function
byond(id, type)Returns the control with this ID, or the default control of the given type.
Starting the ID with a colon, e.g. ":output", looks for the default of that type.
Following the ID with a colon and a sub-control ID, e.g. "grid:1,1", means only the first part ("grid") will be used for lookup.
byond object methods
Utility
extend(object, e1, ...)Copy any of e1's properties, plus those of any additional arguments, to object. This is a shallow copy. Returns object.
extendUnused(object, e1, ...)Copy any of e1's properties, plus those of any additional arguments, to object if it does not have them already. This is a shallow copy. Returns object.
tryExtend(object, e1, ...)Same as extend(), but wraps everything in a try/catch block and ignores errors.
htmlEncode(string)Converts a text string to escaped HTML.
htmlDecode(string)Converts a text string from escaped HTML to unescaped, removing entities such as &lt;.
toCamelCase(string)Converts a text string from hyphenated form to camelCase.
fromCamelCase(string)Converts a text string from camelCase to hyphenated form.
sanitizeId(string)Converts a text string into a standardized control ID: lowercase, containing only letters, numbers, and underscores.
winset2bool(value)Converts a value to true, false, or null (indeterminate).
winset2num(value)Converts a value to a numerical form for winset commands that need it. Returns null if indeterminate.
URLs
isByondUrl(url, anyByond)Returns true if the URL is in the form ?... or byond://?.... If the anyByond parameter is true, this will also match any byond:// URL.
domain()Returns the host and port merged together as "[ip]:[port]".
url(uri)Converts a local URI such as myfile.png to a full URL pointing to the game server.
iconUrl(icon, state, dir, frame, moving, params)
iconUrl(..., params)
Returns the URL for an icon with the given icon ID and parameters. Takes 0-5 arguments in order, followed by the optional params argument. params is an object literal, and can hold any of the arguments by name. E.g., byond.iconUrl({icon:3, state:'closed'}) is the same as byond.iconUrl(3, 'closed').
CSS manipulation
toPx(unit)How many pixels, roughly, are in the given unit. E.g., byond.toPx('em') is the number of pixels in one em unit.
attr(element, name, value)Set an attribute on a DOM element. Use only two arguments to get the attribute value instead.
css(element, name, value)Set a style for a DOM element; use only two arguments to read the style. Or, the name argument can be replaced with an object such as {width:'100%'} which can set multiple values at once.
cssPxLike css(), but with pixel sizes.
cssPtLike css(), but with point sizes.
cssColorLike css(), but with colors; returns a friendly hex #RRGGBB value when used to read a color.
HTML helper functions
contains(haystack,needle)Both arguments are HTML elements. Returns true if haystack contains needle.
controlFor(element)Returns the skin control this element belongs to, if any.
children(element, all)Returns the skin controls that are children of this element (or control), if any. Unless all is true, grandchildren will not be included.
pos(element)Returns the position of this element relative to the body, as an object with x and y properties.
innerSize(element)Returns the interior size of this element (not including any borders or padding), as an object with width and height properties.

The byond.skin module

The skin module organizes and handles most workings of the interface, parceling out instructions to controls.

byond.skin methods
General
find(id, type)Identical to the byond() function.
findAll(id, type)Returns a list of controls found. The id parameter can be left null or can include asterisks as wild cards.
top()Returns the skin's container div: either a div with the ID "skin" or the document body.
availableName(type)Returns an unused ID that can be used for a new control with this type.
getClass(type)Returns the template object used to build new controls of this class.
getPrompts(type)Returns the template object used to build new prompts of this type.
Interaction
output(id, obj)Looks up the control that goes with this ID, and sends obj and a sub-control ID to the control's output method. If obj.null is true, it calls the control's clear method instead. And if the control does not exist and obj.file is specified, a new browser control will be created as a popup.
winset(id, props)Looks up the control that goes with this ID, and sends the properties to set and a sub-control ID to the control's winset method.
winget(id, props)Looks up the control that goes with this ID, and sends the properties to get and a sub-control ID to the control's winget method. Returns the result of the control's winget.
prompt(params)Calls byond.prompt(params)
stats(panels, verbs)Statpanel information. By default, looks up the default info control and calls its stats member.
status(obj)Mouseover status. By default, calls byond.skin.output(":status",obj), which will either call output or clear. The obj parameters in use are atom and text, or null to clear.
popup(id, type, options)Creates a popup with the given ID, using the specified class type (often "browser"), and with the given options which are passed to the new control's popup method.
attach(id, type)Finds the div with the given ID, and turns it into a control using type as the class. In place of the id argument, you can use a div, and an ID will be assigned if one doesn't exist already. Returns the control.
dispatchKeyEvent(event, asker, any)This is the event handler for keyup and keydown events for the whole document. It can also be called by other controls to find out if a more important control wants this event, in case the control itself has a handler that is called first. Returns true if the event should proceed. If a control calls this, it should be sent as the asker argument. The any argument is true if a non-exact key match is allowed, e.g. if Shift+Left can be considered equivalent to Left.

The byond.prompt module

The prompt module is used for creating prompt popups. byond.prompt is also a function.

byond.prompt(params)Creates a new prompt based on the parameters given in the params object. The parameters can include:
  • type: The prompt type to use, e.g. "text", "num", "any" (multiple choice), "alert", "color", "message", etc.
  • title: The title of this prompt.
  • help: The help text for this prompt.
  • choices: An array of possible choices. Does not apply to some prompt types.
  • defaultChoice: The default choice to use, if any.
  • canCancel: True if the prompt should display a cancel option.
  • reply(choice): A callback function that sends back the response for this prompt.
  • cancel(): A callback function that cancels this prompt.
In addition to creating the prompt, this will call the prompt's fill() and show() methods.
byond.prompt members
fnAn object that contains default methods. These are used in addition to byond.fn.
winsetfnAn object that contains default winset methods. These are used in addition to those in byond.winsetfn.
byond.prompt methods
which(params)Returns which prompt type to use. By default, this will use params.type if it's available, or otherwise will fallback on an appropriate default such as text or any.
Prompt members
These methods are in addition to the members used in classes.
paramsThe list of options used to create the prompt.
Prompt methods (defined in byond.prompt.fn)
These methods are in addition to, and supercede, anything in byond.fn.
fill()Does initial filling work.
show()Displays the prompt in a lightbox and calls onshow().
reply(choice)Calls this.params.reply with the choice given if the prompt has not already been replied to or canceled, and removes the prompt.
cancel()Calls this.params.cancel if the prompt has not already been replied to or canceled, and removes the prompt.
onclickoff()Return true if clicking outside the lightbox should prevent closing it.
onshow()Called by the default show() method.
cleanup()Closes the lightbox and removes this prompt from the skin by calling this.remove().

You can define custom prompt types as well as custom classes. Instead of using a <byondclass> tag in the .dms file, you use a <byondprompt> tag instead and use the methods listed above. The format is very similar. To use a custom prompt, override byond.prompt.which to parse the prompt parameters and return the name of your prompt type when appropriate.

Skin parameters

  All Pane Label Button Input Output Browser Map Info Child Tab Grid Bar
Size & position pos
size
anchor1
anchor2
  view-size   fit*
lock
  cells
cell-span
is-list
width
slider-width*
track-width*
General appearance is-visible   multi-line max-lines   is-vert   dir
angle1
angle2
Color text-color
background-color
  highlight-color
tab-text-color
tab-background-color
prefix-color
suffix-color
  bar-color
track-color*
User interaction is-default   button-type
group
is-checked
is-disabled
is-disabled
is-password
no-command
  right-click right-click splitter current-tab current-cell
right-click
is-slider
value
Text & title font-family
font-size
font-style
  allow-html*
text
align
text text   allow-html
tab-font-family
tab-font-size
tab-font-style
  show-names  
Images image   image-mode
keep-aspect
letterbox
  icon-size*
letterbox
render-mode*
zoom*
 
Commands on-size   command command   on-show
on-hide
on-show on-show
on-hide
  on-tab   on-change
Panes   can-scroll   left
right
tabs  

BYOND standard controls

These controls are all based on their BYOND counterparts.

Webclient-only controls

Several controls have been introduced exclusively for the webclient.

BYOND standard prompts

These prompt types are based on their BYOND counterparts.

Detailed parameter list (see BYOND Skin Reference for more info)

ParameterFormatSupported byDefaultMisc. info
aligncenter or left or right or top or bottom or top-left or top-right or bottom-left or bottom-rightLabelcenterDefault alignment of text, both horizontal and vertical. (Only horizontal alignment is supported at this time.)
allow-htmltrue or falseLabel, InfoLabel: false
Info: true
Allow HTML tags to be used in stat or label text. Dream Seeker does not support allow-html for labels, except to remove the HTML tags entirely.
anchor1[x%],[y%] or noneAllnoneAnchors the control within the window/pane. 0,0 is the upper left, 100,100 the lower right. Use one anchor to manage the control's position only, or two to stretch it.
anchor2[x%],[y%] or noneAllnone
angle1[angle]Bar0The angle where the bar's arc starts, if dir is clockwise or counterclockwise. 0 is due north, 90 is east, etc.
angle2[angle]Bar180The angle where the bar's arc ends, if dir is clockwise or counterclockwise. 0 is due north, 90 is east, etc.
background-color#RRGGBB or #RGB or noneAll#fffAffects background color. May not work the same in all controls.
bar-color#RRGGBB or #RGB or noneBar#fffAffects the fill color.
button-typepushbutton or pushbox or checkbox or radioButtonpushbuttonChanges the type of button. A pushbox is a regular button that can be pushed in (used as a checkbox or radio control). A value of checkbox or radio will make it look like a simple checkbox or radio button.
can-scrollnone or horizontal or vertical or bothPanenoneThe pane will retain its horizontal and/or vertical size and show scrollbars if necessary, instead of shrinking to fit the container.
cell-span[columns]x[rows]Grid1x1The span of the current grid cell; it can be merged with cells to the right and down. If is-list is true, this setting is ignored. This setting is only available at runtime.
cells[columns]x[rows]Grid0x0The number of columns and rows in the grid. If is-list is true, this sets the maximum number of items in the list; it can be set to just a single value [items]. Setting the number of rows or columns to -1 means that value will not change.
command"[verb]"Button, Input""Command executed when the button is activated; or the default command for an Input control. If used for Input, this command is followed by whatever the user types in. For input controls, if your command starts with an exclamation point (!), everything after the ! is shown as a default prompt that may be cleared by the user.
current-cell[column],[row]Grid0x0The active cell. Any output sent to the grid will go into this cell. If is-list is true, this can be set to 1,[item] or just the item number.
current-tab"[name]"Info, Tab""The name the active/default tab. For the tab control, if this is set to a tab that is not currently available, the pane/control by that name will be added as another tab.
dirnorth or south or east or west or clockwise or counterclockwiseBareastThe direction of the bar; as the value increases the bar will move further in this direction. The clockwise and counterclockwise directions will let you make an arc from angle1 to angle2. You can use cw and ccw as shorthand for clockwise or counterclockwise.
fitnone or left or rightChildnoneAllows one pane to dictate the splitter position by requesting that its automatic width or height be used. The splitter is hidden if this is used.
focustrue or falseAllfalseTrue if this control has focus; set to true to give it focus. (Support is presently limited.)
font-family"[font name]"All""Leave blank to use the default font. This can be used for CSS-style fallback fonts, e.g. "Arial,Helvetica".
font-size[point size]All0Leave 0 to use the default font size.
font-style"bold" or "italic" or "underline" or "strike" or any combinationAll""Sets the font style. Values can be combined if separated by spaces or commas.
group"[name]" or ""Button""If the button should be treated as part of a radio button group, this is the name of the group; otherwise group should be blank. Buttons in different panes are always treated as a different group.
highlight-color#RRGGBB or #RGBGrid, Info#0f0The color used to highlight moused-over statpanel items or verbs. In grids, this color is used when hovering over objects or links.
icon'[file]'All""Custom icon used alongside the title, if displayed somewhere that uses the title (e.g. the Tab control).
icon-size0 or [size]Map0Size, in pixels, of icons on map. 0 stretches to fit available space; 32 is the BYOND standard icon size. Use zoom if you'd rather go by a ratio instead of pixels. (This is an alias for zoom. As a rule you should use the newer parameter "zoom" instead.)
id"[name]"Allno defaultThe name of this control. The name should ideally be unique. Controls can be referenced by [windowname].[controlname] at runtime, but this is legacy behavior and should not be standard practice going forward. Read-only.
image'[file or url]'Main, Label, Button, Output""Background image for control.
image-modecenter or stretch or tileMain, LabelstretchIf using a background image, this decides how the image will fit the window/pane or label.
is-checkedtrue or falseButtonfalseTrue if the button is currently checked. (Set button-type to use this with buttons.)
is-defaulttrue or falseAllfalseSpecifies a default control. This should be set to true for your main window, map, info, and main output, input, and browser controls.
is-disabledtrue or falseButtonfalseDisables the control.
is-passwordtrue or falseInputfalseTurns password-hiding mode on or off for an input control.
is-slidertrue or falseBarfalseThe bar is an adjustable slider instead of a progress bar.
is-verttrue or falseChildfalseThe splitter, if it appears, is vertical. You can use "is-vertical" as an alias for this parameter.
is-visibletrue or falseAlltrueThe main window should usually be made visible.
keep-aspecttrue or falseLabelfalseIf stretching an image, preserve its aspect ratio.
left"[pane name]" or noneChildnoneThe name of the pane that will appear on the left/top side of this Child. If none, the right/bottom side fills the whole space.
letterboxtrue or falseLabel, MaptrueIf map auto-scales its icons, make sure the entire map fits, and fill excess space with blackness. If letterbox is not enabled, zoom to fill the entire available space; any excess will be cut off. For labels, this controls image sizing when keep-aspect is true.
locknone or left or rightChildnoneAllows one pane to "lock" the splitter so if the Child control is resized, the splitter will stay put on that side.
max-lines[lines] or 0Output1000Maximum number of lines before the control drops old text to make room for more. (Extra lines may be allowed to prevent flickering between trims.) 0 is no limit.
multi-linetrue or falseInputfalseTurns multi-line input mode on or off.
no-commandtrue or falseInputfalseTrue if this input box isn't used to enter commands.
on-change"[verb]"Bar""Command executed when the value of the bar/slider is changed. If you drag the slider around, the command will not run until you let go.
on-hide"[verb]"Browser, Info""Command executed when the default browser or info control is hidden by the game.
on-show"[verb]"Map, Browser, Info""Command executed when the default map, browser, or info control is shown by the game.
on-size"[verb]"All""Command executed when the control is resized. If you are dragging a window edge or splitter, the command won't run until you finish. No command will be sent in response to size or splitter changes made by winset().
on-tab"[verb]"Info, Tab""Command executed when the current tab is changed.
pos[x],[y] or noneAll0,0Position of upper left corner.
prefix-color#RRGGBB or #RGB or noneInfononeThe color used in the prefix/header column, to the left of atoms in the statpanel. If no color is specified, the normal text-color is used.
render-mode"WebGL:high" or "WebGL:low" or "Canvas2D"Label, Map"WebGL:high"Determines how the map control renders its content. The default is to use WebGL in high-quality mode, which mimics Dream Seeker's rendering for better quality. Low-quality WebGL mode and Canvas2D may both show scaling artifacts in certain games, but WebGL:low will perform slightly better than WebGL:high in demanding games. Canvas2D should generally be avoided if at all possible, although it will be used as a fallback if WebGL is unavailable.
right"[pane name]" or noneChildnoneThe name of the pane that will appear on the right/bottom side of this Child. If none, the left/top side fills the whole space.
right-clicktrue or falseMap, Info, GridfalseTrue if this control should allow right-clicks to behave like any other click instead of opening up popup menus or similar special behavior.
show-namestrue or falseGridtrueIf atoms are output to the grid, show the atom's name next to the icon. If the atom has no icon and show-names is false, the grid cell will be blank.
size[width]x[height]All0x0Setting 0 for width or height uses up any available space right/downward. If the control is a popup, this refers to its interior size, not counting borders, titlebar, menu, or statusbar.
slider-width[width] or [percentage]%Bar50%Size of the slider in the direction of the bar: either in pixels or, if a percentage is given, relative to its width.
suffix-color#RRGGBB or #RGB or noneInfononeThe color used in the suffix column, to the right of atoms in the statpanel that have a suffix. If no color is specified, the normal text-color is used.
track-width[multiplier] or [percentage]%Bar50%Size of the track when is-slider is true; this is multiplied by the width value.
splitter0 to 100Child50Percent distance of the splitter, if it appears, from the left/top of the Child control. 50% is an equal split.
tab-background-color#RRGGBB or #RGB or noneInfononeAffects background color for tabs.
tab-font-family"[font name]"Info""Same as font-family, but for tabs.
tab-font-size[point size]Info0Same as font-size, but for tabs.
tab-font-style"bold" or "italic" or "underline" or "strike" or any combinationInfo""Same as font-style, but for tabs.
tab-text-color / tab-color#RRGGBB or #RGB or noneInfononeAffects foreground text for tabs.
tabs"[tab names, comma-separated]" or "+[new tab name]" or "-[tab to
tabs"[tab names, comma-separated]" or "+[new tab name]" or "-[tab to remove]"Tab""The names of the panes/controls that will appear as tabs, in order, separated by commas. Precede with "+" to add tabs to the current list without removing any, or "-" to remove only the tabs you specify.
text"[label]"Label, Button, Input""Text shown in label/button/input. For input controls this setting is only available at runtime.
text-color / color#RRGGBB or #RGB or noneAll#000Affects foreground text. The parameter name "color" can be used as an alias.
title"[title]"All""The title of this control. This is used by the Tab control to display a name. See also the icon parameter.
track-color#RRGGBB or #RGB or noneBar#fffAffects the track color.
type[TYPE]Allno defaultThe type of control. Read-only.
value0 to 100Bar0The "fullness" of the bar or slider, as a percentage.
view-size[size]Map0Size, in pixels, the area the map is using (or trying to use) for display, not including any of the "letterboxing". If icon-size is not 0, this value may be bigger than the control's actual size. Read-only.
width[width]Bar10Width, in pixels, of the bar or slider. 0 uses all available width.
zoom0 or [size]Map0Zoom factor for icons on map. 0 stretches to fit available space; 1 will show the icons at their normal size. Other values are not supported at this time.

Feature Comparison

This is a quick list of supported features the client carries over from Dream Seeker: Here is a short list of differences between the two platforms: "Main" doubles as pane and window
FeatureDream SeekerWebclient
Supported skin controlsUser-defined custom controls; "main" split into "pane" and "pop"
Skin parametersMany parameters used for stylingMost styling is with CSS; only a subset of parameters supported
TransparencyLimitedHighly configurable via CSS
NestingChild/tab and panes required for nested interfacesAny control can be used as a pane, and new container controls can be designed
DockingRequires child control and panesControls can be built that dock themselves
PromptsOnly limited customizationCustom prompts can be defined
output()Can send text, files, etc. to any skin control; can call JavaScript in browser controlSame, but can also send lists with mixed items, e.g. list('orange.dmi',"citrus") allowing for even more advanced interfaces
Map controlAuto-zoom, or specific zoom level; text modeAuto or 1:1 only
MenusSkins can have custom menusNot present, but could be user-defined with a custom control
Client-side commandsMostly specific to Dream Seeker.skin [javascript code]
General UIClick behavior easier to customize
DisplayAll blend_mode options supported in hardware modeSubtactive blend_mode not supported
Sound.wav, .ogg, MIDI, module music.wav, .ogg, or .mp3 (browsers vary)*
MIDI and module support in compatible browsers
Music can be toggled off separately from sound effects
* For greatest audio support, set sound.file to list('sound.ogg','sound.mp3').
† MIDI is supported via the Jazz plugin or natively in Chrome by enabling MIDI in flags.
run()Users can choose to run a command or programNot feasible