The Basic Mod Set: Server View
The following documents the standard mod set from the server's perspective. Note that what follows does not detail the message protocols that these mods obey. Consult the Basic Mod Set: Client View document for that information.
Note, however, that there are several mods that exist only on the server side, have no client presence, and are not directly visible to the client in any way.
Cartesian
The Cartesian mod provides the item to which it is attached with simple two-dimensional cartesian geometry. It also supports user manipulation of to the containership relation between objects. This mod may not be attached to users or contexts.
Representation
{
type:"cart",
left:INT,
top:INT,
width:INT,
height:INT
}
where:
left
andtop
are the X and Y coordinates of the screen position (in pixels) of the assocated item, relative to the position of its container.width
andheight
are the X and Y screen dimensions (in pixels) of the associated item.
Census
The Census mod allows a client to survey the number of users in a context, even if the client cannot see those users directly. It may be attached to any kind of object.
Representation
{ type:"census" }
Chat
The Chat mod enables multi-user text chat in a context. It is
attached to a context, never to a user or item. It may be configured to
individually allow or disallow the "say"
or "push"
messages, both to the context as a whole (public chat or push) and to
individual users (private chat or push).
Representation
{
type:"chat",
allowchat:?BOOL,
allowprivate:?BOOL,
allowpush:?BOOL,
allowprivatepush:?BOOL
}
where:
allowchat
is a flag that controls whether users are allowed to send"say"
messages to the region. If omitted, it defaults to true.allowprivate
is a flag that controls whether users are allowed to send"say"
messages to other users. If omitted, it defaults to true.allowpush
is a flag that controls whether users are allowed to send"push"
messages to the region. If omitted, it defaults to true.allowprivatepush
is a flag that controls whether users are allowed to send"push"
messages to other users. If omitted, it defaults to the logical AND of theallowprivate
andallowpush
flags.
ContextKey
The ContextKey mod enables entry to restricted entry contexts. It may be attached to a user or item, but doesn't make sense to be attached to a context. When a user attempts to enter a restricted context, the server checks to see if the user has a ContextKey mod attached or contains (at some level of nesting) an item with a ContextKey attached and that the ContextKey enables entry to the context.
Representation
{
type:"ctxkey",
contexts:[CTXREF_STR],
transferrable:?BOOL,
deletable:?BOOL,
expiration:?LONG
}
where:
contexts
is an array of context reference strings identifying the contexts to which this mod grants access.transferrable
is flag that, if present and false, marks the key as transferrable to another user. If it is not transferrable (it is by default), the server will prevent it from being moved to a containership hierarchy other than the one it is presently in. This flag only makes sense when the mod is attached to an item.deletable
is a flag that, if present and false, prevents the item to which the key is attached from being deleteable (items are deletable by default).expiration
is a number encoding a Unix timestamp that, if present, establishes an expiration time for the key. After this time it will no longer grant entry to any context. A value of 0 (the default) indicates that the key does not expire.
Dictionary
The Dictionary mod associates a server-moderated name/value lookup table with the object to which it is attached. It may be attached to a context, user or item.
Representation
{ type:"dictionary", names:[STR], values:[STR], persist:?BOOL }
where:
names
is an array of strings, containing the dictionary's lookup keys.values
is an array of strings parallel tonames
, containing the values. For a given element ofnames
, the element ofvalues
with the same array index contains that name's value.persist
is a flag that, if present and true, makes the state of the dictionary persistent. That is, when the object to which this mod is attached is checkpointed, the current state of the name/value settings is saved with it. If it is not persistent, then when the enclosing context is shut down, any changes will be lost, and the next time the object is loaded it will revert to its original settings.
Image
The Image mod associates an image with the object to which it is attached. It may be attached to any kind of object, but normally it will be attached to items. This mod is purely a data object; it has no behavior and no message protocol. It is up to the client application to make use of this data appropriately.
Representation
{ type:"image", img:STR, width:?INT, height:?INT }
where:
img
is the URL of an image.width
andheight
, if given, represent the horizontal and vertical extent of this image, in pixels.
Invisible
The Invisible mod causes the item to which it is attached to be hidden from clients. That is, any such items will not be included in the contents of their containers when these contents are transmitted to clients. The contents of an invisible item are thus also effectively invisible, even if they do not themselves have this mod attached. This mod may only be attached to an item and never to a context or user.
Representation
{ type:"invisible" }
Note
The Note mod associates a block of editable text with the item to which it is attached. It must be attached to an item, not a context or user.
Representation
{ type:"note", text:STR, style:?STYLEDESC }
where:
text
is the text of the note.style
is an optional style description for rendering the text. See below for details on the style descriptor object.
NoteMaker
The NoteMaker mod provides a facility for creating new items with Notes attached. It is normally attached to the context, but this is not required.
Representation
{ type:"notemaker", styles:STYLEOPTIONSDESC }
where:
styles
is a collection of style options that can constrain the styles associated with notes this mod creates. See below for details on the style options descriptor object.
TalkOptions
The TalkOptions mod describes controls the style information
associated with user utterances displayed as a result of "say"
messages. This mod must be attached to a context, not to a user or item. It
operates in conjunction with the Chat and TalkPrefs mods.
This mod is purely a data object; it has no message protocol.
Representation
{ type:"talkoptions", styles:STYLEOPTIONSDESC }
where:
styles
is a collection of style options that can constrain the styles associated with chat. See below for details on the style options descriptor object.
TalkPrefs
The TalkPrefs mod holds a user's current chat text display style settings. It operates in conjunction with the Chat and TalkOptions mods. It is always attached to a user. It always ephemeral, and so has no persistent representation.
Descriptor Objects
There are a couple of JSON objects that are used to carry standard bundles of information in the representations of certain mods and in some messages. These are not mods or messages themselves, but simply bundles of data.
Style Descriptor
The style descriptor contains information for the rendering of text.
Representation
{
type:"style",
color:?STR,
backgroundColor:?STR,
borderColor:?STR,
textStyle:?STR,
icon:?STR
}
where:
color
, if given, is the name of the text color.backgroundColor
, if given, is the name of the text background color.borderColor
, if given, is the name of the text border color.textStyle
, if given, is an HTML CSS style string for a text element.icon
, if given, is the URL of a marker icon.
All elements are optional. Color names are standard HTML color names.
Style Options Descriptor
The style options descriptor contains a collection of text style information. It represents a range of permitted style values for use in preference setting and display.
Representation
{
type:"styleoptions",
colors:[STR],
backgroundColors:[STR],
borderColors:[STR],
textStyles:[STR],
icons:[STR],
iconWidth:?INT,
iconHeight:?INT
}
where:
colors
, if given, is a series of permissible text color names.backgroundColors
, if given, is a series of permisslbe text background color names.borderColors
, if given, is a series of permissible text border color names.textStyles
, if given, is a series of permissible text style strings.icons
, if given, is a series of permissible marker icon URL strings.iconWidth
andiconHeight
, if given, are the common width and height, pixels, of the icons specified by theicons
attribute.
All elements are optional.