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.
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.
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>
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.
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.
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 | |
|---|---|
| template | This is filled in by the client when the class is created, from the HTML template included in the control's .dms definition. |
| config | An object that contains default configuration options. For instance, {maxLines: 1000} in an output control. |
| fn | An 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. |
| winsetfn | An 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 | |
|---|---|
| config | An object that contains configuration options. It is a copy of the class's config, not linked to it. |
| winsetfn | An object containing winset/winget functions that can be used to set or get control properties. |
| top | The outer div element of this control. |
| elem | The "main" element of this control; it is the same as top unless you change it, which is usually done in create(). |
| ui | An 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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:
|
| 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) | |
|---|---|
| fontFamily | The font-family parameter, referring to the font the control should use. |
| fontSize | The control's font size, in points. |
| fontStyle | Defines 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. |
| backgroundColor | The background color; a winget returns either "none" or #RRGGBB. |
| backgroundImage | The background image. |
| isVisible | Whether 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.
byond objectThe main JavaScript object the client uses is called byond. It contains modules such as byond.skin,
byond.server, and so on.
byond object modules | |
|---|---|
| skin | The client skin. The client sends all its output to the skin's functions. |
| prompt | The module in charge of handling prompts; also a function. |
| lightbox | The module in charge of displaying lightboxes; also a function. |
| event | Functions 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 <. |
| 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. |
| cssPx | Like css(), but with pixel sizes. |
| cssPt | Like css(), but with point sizes. |
| cssColor | Like 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. |
byond.skin moduleThe 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. |
byond.prompt moduleThe 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:
fill() and show() methods.
|
byond.prompt members | |
|---|---|
| fn | An object that contains default methods. These are used in addition to byond.fn. |
| winsetfn | An 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. | |
| params | The 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.
| 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 | ||||||||||
These controls are all based on their BYOND counterparts.
Several controls have been introduced exclusively for the webclient.
These prompt types are based on their BYOND counterparts.
| Parameter | Format | Supported by | Default | Misc. info |
|---|---|---|---|---|
| align | center or left or right or top or bottom or top-left or top-right or bottom-left or bottom-right | Label | center | Default alignment of text, both horizontal and vertical. (Only horizontal alignment is supported at this time.) |
| allow-html | true or false | Label, Info | Label: 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 none | All | none | Anchors 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 none | All | none | |
| angle1 | [angle] | Bar | 0 | The angle where the bar's arc starts, if dir is clockwise or counterclockwise. 0 is due north, 90 is east, etc. |
| angle2 | [angle] | Bar | 180 | The 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 none | All | #fff | Affects background color. May not work the same in all controls. |
| bar-color | #RRGGBB or #RGB or none | Bar | #fff | Affects the fill color. |
| button-type | pushbutton or pushbox or checkbox or radio | Button | pushbutton | Changes 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-scroll | none or horizontal or vertical or both | Pane | none | The 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] | Grid | 1x1 | The 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] | Grid | 0x0 | The 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] | Grid | 0x0 | The active cell. Any output sent to the grid will go into this cell. If is-list is true, this can be set to |
| 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. |
| dir | north or south or east or west or clockwise or counterclockwise | Bar | east | The 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. |
| fit | none or left or right | Child | none | Allows 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. |
| focus | true or false | All | false | True 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] | All | 0 | Leave 0 to use the default font size. |
| font-style | "bold" or "italic" or "underline" or "strike" or any combination | All | "" | 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 #RGB | Grid, Info | #0f0 | The 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-size | 0 or [size] | Map | 0 | Size, 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]" | All | no default | The 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-mode | center or stretch or tile | Main, Label | stretch | If using a background image, this decides how the image will fit the window/pane or label. |
| is-checked | true or false | Button | false | True if the button is currently checked. (Set button-type to use this with buttons.) |
| is-default | true or false | All | false | Specifies a default control. This should be set to true for your main window, map, info, and main output, input, and browser controls. |
| is-disabled | true or false | Button | false | Disables the control. |
| is-password | true or false | Input | false | Turns password-hiding mode on or off for an input control. |
| is-slider | true or false | Bar | false | The bar is an adjustable slider instead of a progress bar. |
| is-vert | true or false | Child | false | The splitter, if it appears, is vertical. You can use "is-vertical" as an alias for this parameter. |
| is-visible | true or false | All | true | The main window should usually be made visible. |
| keep-aspect | true or false | Label | false | If stretching an image, preserve its aspect ratio. |
| left | "[pane name]" or none | Child | none | The 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. |
| letterbox | true or false | Label, Map | true | If 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. |
| lock | none or left or right | Child | none | Allows 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 0 | Output | 1000 | Maximum 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-line | true or false | Input | false | Turns multi-line input mode on or off. |
| no-command | true or false | Input | false | True 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 none | All | 0,0 | Position of upper left corner. |
| prefix-color | #RRGGBB or #RGB or none | Info | none | The 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 none | Child | none | The 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-click | true or false | Map, Info, Grid | false | True if this control should allow right-clicks to behave like any other click instead of opening up popup menus or similar special behavior. |
| show-names | true or false | Grid | true | If 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] | All | 0x0 | Setting 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]% | Bar | 50% | 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 none | Info | none | The 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]% | Bar | 50% | Size of the track when is-slider is true; this is multiplied by the width value. |
| splitter | 0 to 100 | Child | 50 | Percent 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 none | Info | none | Affects background color for tabs. |
| tab-font-family | "[font name]" | Info | "" | Same as font-family, but for tabs. |
| tab-font-size | [point size] | Info | 0 | Same as font-size, but for tabs. |
| tab-font-style | "bold" or "italic" or "underline" or "strike" or any combination | Info | "" | Same as font-style, but for tabs. |
| tab-text-color / tab-color | #RRGGBB or #RGB or none | Info | none | Affects 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 none | All | #000 | Affects 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 none | Bar | #fff | Affects the track color. |
| type | [TYPE] | All | no default | The type of control. Read-only. |
| value | 0 to 100 | Bar | 0 | The "fullness" of the bar or slider, as a percentage. |
| view-size | [size] | Map | 0 | Size, 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] | Bar | 10 | Width, in pixels, of the bar or slider. 0 uses all available width. |
| zoom | 0 or [size] | Map | 0 | Zoom 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. |
flick(), missile()browse_rsc(), popups (in lightbox), calling JavaScript code via output()| Feature | Dream Seeker | Webclient |
|---|---|---|
| Supported skin controls | "Main" doubles as pane and windowUser-defined custom controls; "main" split into "pane" and "pop" | |
| Skin parameters | Many parameters used for styling | Most styling is with CSS; only a subset of parameters supported |
| Transparency | Limited | Highly configurable via CSS |
| Nesting | Child/tab and panes required for nested interfaces | Any control can be used as a pane, and new container controls can be designed |
| Docking | Requires child control and panes | Controls can be built that dock themselves |
| Prompts | Only limited customization | Custom prompts can be defined |
| output() | Can send text, files, etc. to any skin control; can call JavaScript in browser control | Same, but can also send lists with mixed items, e.g. list('orange.dmi',"citrus") allowing for even more advanced interfaces |
| Map control | Auto-zoom, or specific zoom level; text mode | Auto or 1:1 only |
| Menus | Skins can have custom menus | Not present, but could be user-defined with a custom control |
| Client-side commands | Mostly specific to Dream Seeker | .skin [javascript code] |
| General UI | Click behavior easier to customize | |
| Display | All blend_mode options supported in hardware mode | Subtactive 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 program | Not feasible |