| Temporary version!
This document isn't finished yet. it's available to make it already possible to experiment with VMoo support Usage of this is (as is all usage of VMoo) at your own risk! |
|---|
The following document assumes you are using VMoo 1.2 (only
available as Dutch version) or above.
The former #_# protocol is no longer supported by VMoo 2.0 and above and isn't
publicly documented.
Please send your notes to vmoo@dds.nl
The MCP/2.1 protocol is based upon Out of Band commands. These Out of Band commands are in MCP lines starting with #$#. LambdaMoo uses a special way to handle lines starting with this specific string. All lines starting with #$# are handled bij #0:do_out_of_band_command (Even when executing a read()). To threat #$# as an ordinary string #$" can be put before the line. This has several advantages. (Pleas read the MCP/2.1 specification for more info).
The following sections assume you are familiar with all aspects of the MCP/2.1 protocol.
While writing this document I assume you are usoing VMoo, but almost every
aspect applies to every other client which uses MCP/2.1 or these packages.
(e.g. gMOO also uses most packages)
The term 'Moo' is used to specify a mud server which is able to communicate with a client using the MCP/2.1 protocol.
Many of the dns-nl-vgmoo and dns-com-vmoo packages use/abuse the power of the MCP Multine messages to send data with a minimal overhead at the moo. Most default Moo implementations of the MCP/2.1 specification assume that multiline messages should be threated as 1 long message, while VMoo has the abbility to threat every line of a multiline message as a separate light weight message. (Multiline data lines use far less data and processing than ordinary MCP lines.)
Most MCP implementation can use this feature with only minor changes.
E.g. the dns-nl-vgmoo-userlist package uses a single MCP multiline message to continuously update the activity status of all connected players.
4. packages supported by VMoo
VMoo supports the following packages:
mcp-negotiate 1.0 - 2.0 VMoo 1.2+ dns-org-mud-moo-simpleedit 1.0 VMoo 1.5+ (1.2 has a dot bug in the implementation) dns-com-awns-status 1.0 VMoo 1.2+ dns-com-ben-tfstatus 1.0 VMoo 1.2+ dns-nl-dds-external 1.0 VMoo 1.5+ dns-nl-vgmoo-client 1.0 VMoo 1.2-1.3 (Alias for dns-com-vmoo-client from 1.4) dns-nl-vgmoo-pages 1.0 VMoo 1.2-1.3 (Alias for dns-com-vmoo-pages from 1.4) dns-nl-vgmoo-userlist 1.0 VMoo 1.2-1.3 (Alias for dns-com-vmoo-userlist from 1.4) dns-com-vmoo-client 1.0 VMoo 1.4+ dns-com-vmoo-dialogs 1.0 VMoo 1.4+ dns-com-vmoo-mmedia 1.0 VMoo 1.4+ dns-com-vmoo-multiplex 1.0 VMoo 1.4+ dns-com-vmoo-pages 1.0 VMoo 1.4+ dns-com-vmoo-presuffix 1.0 VMoo 1.4+ dns-com-vmoo-userlist 1.0 VMoo 1.4+
The following messages are defined:
More information available at: http://www.moo.mud.org/mcp/
(VMoo only replies a negotiate-end message when mcp-negotiate 2.0 is supported an announced by the Moo!)
mcp-cord [1.0-1.0]
The following messages are defined:
More information available at: http://www.moo.mud.org/mcp/
This package is meant as a simple replacement for the MCP/0 '#$# edit name: ... upload: ...' command.
It doesn't trust on specific moo verbs as the old version does.
The following messages are defined:
The following messages are defined:
More information available at: http://www.awns.com/mcp/
The following messages are defined
More information available at: -?-
5.3.1 dns-nl-dds-external [1.0]
The following messages are defined:
dns-nl-dds-external-query() (Moo to Client)
dns-nl-dds-external-accepts(externals) (Client to Moo)
dns-nl-dds-external-exec(external [,info]) (Moo To Client)dns-nl-dds-external-query()
Requests the client to send an accepts list.
dns-nl-dds-external-accepts(externals) (Client to Moo)
A message to tell the moo which externals are accepted by the client. Externals is a moo-list.
dns-nl-dds-external-exec(external [,info]) (Moo To Client)
A moo request for the client to initiate an external.
VMoo accepts the following externals:
External Description Meaning of info value Browser Starts the default browser Url (Only http://, ftp:// and gopher:// are accepted for security reasons Starts mail reader To whom to write a message News Starts news reader newsgroup including news:
From VMoo version 1.5 onward the dns-nl-vgmoo packages are replaced by dns-nl-vmoo- packages with the same suffix. (For more information about implementing both packages in the same moo/client see dns-com-vmoo-userlist.)
6.1 dns-nl-vgmoo-userlist [1.0-1.1]
The following messages are defined:
dns-nl-vgmoo-userlist(fields*, icons*, d*)
dns-nl-vgmoo-userlist-friends(friends [,added] [,removed])
dns-nl-vgmoo-userlist-gaglist(gaglist [,added] [,removed])
dns-nl-vgmoo-userlist-icon-url(url) [1.1+]
dns-nl-vgmoo-userlist-menu(menu)
dns-nl-vgmoo-userlist-you(nr)
dns-nl-vgmoo-userlist-you(nr) (Moo to Client)
Moo to client message to specify which object number is assigned to the current connection.
This message should be sent before any other userlist message. To support future additions, clients should support the possibility that after the initialization this value could be updated. (Moo's shouldn't use this feature))
dns-nl-vgmoo-userlist-friends(friends [,added] [,removed]) (Moo to Client and vise versa)
dns-nl-vgmoo-userlist-gaglist(gaglist [,added] [,removed]) (Moo to Client and vise versa)These messages tell which users should be threated as friends and which should be ignored. The list of all users which fall in the categorie must be sent as the friends/gaglist parameter. To help speeding up the process of handling this message a client/moo can use also the added + removed parameters (Whenever one or more of these two parameters are used, the receiver is allowed to ignore the full list parameter!)
If a moo doesn't support friends and/or gaglists, it should reply to this message with a message which undo's the first message.
All parameters are moo-lists.
(The client always stores the full list even when players aren't connected)dns-nl-vgmoo-userlist-icon-url(url) [Package version 1.1 and above] (Moo to client)
dns-nl-vgmoo-userlist( fields*, icons*, d*)With this message a moo is able to provide it's own icons to clients which support http connections. When a client supports this option (And it is enabled), it will use this image instead of the default name assigned icons.
Normally, only one message of this type is used. (Actually only 2/3 of a message is sent).
After the initial line
#$#dns-nl-vgmoo-userlist 1234 fields*: "" icons*: "" d*: "" _data_tag: 5678 (1234 and 5678 are generated values as specified by the MCP/2.1 specification)the message is kept open to send updates as easy as possible.
First a fields line must be sent. (Only one line of this type is allowed per message!)
| fields: |
The fields parameter is a moo-list, which contains information about which data is available about each user. The first three fields are fixed: {"Object", "Name",
"Icon"} (Object, String, Integer), using more is optional.
Gender is an integer with 0 (male), 1 (female), 2 (undefined (It)) (Higher values are moo specific, negative values are reserved.) (player.ps[1] == "h") First Connect Time is the integer value of the unix time, when the user first connected to this moo. (player.first_connect_time) Connect Time is the integer value of the unix time, when the uses connected. (player.last_connect_time). It is up to the client what the player information is used for |
| Example: |
{"Object", "Name", "Icon", "Age"}
|
Before the data, an icons line should be sent.
| icons: |
The icons paramer is a moo-list, which defines the mapping from icon numbers to icon names. This information is used as long as no icon-url is received. (Every client is allowed to ignore the icon-url message!) The following icons are defined by default: "Idle", "Away", "Idle+Away", "Friend", "Newbie", "Inhabitant", "Inhabitant+", "Schooled", "Wizard", "Key", "Star" A moo can define new icons by defining icons by using other names. (Moo's are allowed to sent further icons line to update the mapping) |
| Example: | {"Newbie", "Programmer", "Inhabitant", "Inhabitant+","Wizard","Nerd"} |
When at least a fields a icons line is received the d lines can be used.
A d line consists of a special char followed by a moo-list.
The most important chars are:
<char> <List> List type = Initializes the userlist List of <Userinfo> + Adds a user <Userinfo> * Update user info <Userinfo> - Deletes a user List of objectnumber = Deletes the old userlist data and adds new players to the list. (Normally this is the first line after the icons line).(= also deletes all state data of the previous players)
+ Adds a new user to the userlist. (Is sent to all the users of this package after a new user is connected)
- Removes a user from the userlist. (When this user disconnected). (Also removes all state data of this user)
* Updates the <userinfo> of a user (State information isn't altered). The user is matched by his object-number.
<userinfo> is a list which contains the items defined in fields. The first item is the object number of the player and is the unique key by which a user is specified. (The Object fiels must be Unique; Name, icon, and any other fields are allowed to contain duplicate values)
<char> <List> List type < Set player idle List of objectnumber > Set player not idle (default) List of objectnumber [ Set player away List of objectnumber ] Set player not away (default) List of objectnumber ( Set player invisible (cloak) List of objectnumber ) Set player not invisible (default) List of objectnumber A moo should (re)initialize the state information after a =.
To provide some assitance I'll provide a small example
#$#dns-nl-vgmoo-userlist <~H=H, icons*: "" fields*: "" d*: "" _data-tag: h0+PE3
#$#* h0+PE3 fields: {"Object", "Name", "Icon", "Connect Time", "First Connect Time"}
#$#* h0+PE3 icons: {"Newbie", "Inhabitant", "Inhabitant+", "Schooled", "Key", "Star", "Wizard"}
#$#* h0+PE3 d: ={{#200, "Capi", 7, 941903426, 923400345}}
#$#* h0+PE3 d: <{#200}
#$#* h0+PE3 d: +{#444, "Mr.Ebou", 6, 921703426, 923400360}}
As usually, MCP lines with errors are ignored.
dns-nl-vgmoo-userlist-menu(menu)
This message provides a context menu (A client is free to ignore some or all items).
The menu is provided as a moo list which can contain the following items:
0 (integer value). This value defines a menu separator
{description, command} A menu option called description (The character & is used to define the shortcut. && is a literal &) which executes command.
In command and description $(x) is converted to UserInfo[x] (When x is a positiveinteger) or a newline when x is 'n'.
E.g.:
{{"&Look $(2)", "look $(1)"}, 0, {"&Info $(2)", "info $(1)"}, 0, {"&Wave $(2)", "wave $(1)"}, {"I&nvite $(2)", "invite $(1)"}}
6.2 dns-nl-vgmoo-client [1.0-1.0]
The following messages are defined:
dns-nl-vgmoo-client-info(name, text-version, internal-version, reg-id,
flags [,x-vmoo-flags]) (Client to Moo)
dns-nl-vgmoo-client-screensize(cols, rows) (Client to Moo)
dns-nl-vgmoo-client-disconnect([reason]) (Moo to Client)
dns-nl-vgmoo-client-info(name, text-version, internal-version, reg-id, flags, ...)
is a message which uniquely specifies which version of a client is used. Whit this information it is possible to check for specific versions of clients to prevent bugs from occuring and to provide online assistance to users of specific clients.
The following 'flags' are defined: p (a proxy is used to connect to *THIS* world), l (vmoo links).
The following 'x-vmoo-flags' are defined: m (multimedia), w
(popup windows)
(Other clients are encouraged to support similar information)
Name followed by Text version should form the complete client name
internal version is an integer which defines the version of the client in an easy parsable way. (To enable client-bug wurkarounds in moo). (toint() is used to parse this string) (0 if not supported)
reg-id is a numeric token which provides a unique user number to the moo. (In VMoo this number is some part of the registration number).
dns-nl-vgmoo-client-screensize(cols, rows)
Sent by the client whenever the screensize of the main text window changes.
(Please, only send this message after connecting en when the screensize changes and not when for example the screensize is increased by less than 1 character.).
dns-nl-vgmoo-client-disconnect([reason])
This message prepares the client for the disconnect event from the moo. It requests the client not to auto-reconnect when the connection is closed.
(VMoo ignores this message when it's send more than 5 seconds before disconnecting)
6.2 dns-nl-vgmoo-pages [1.0-1.0]
The following messages are defined:
dns-nl-vgmoo-pages-receive(from, msg) (Moo to Client)
dns-nl-vgmoo-pages-send(to, msg) (Client to Moo)
dns-nl-vgmoo-pages-receive(from, msg)
This message is sent when a page (moo user to user personal message) is received. The page origintates from from (moo-object defining a player as an object from dns-nl-vgmoo-userlist). msg is a moo-list containing the lines of the message.
dns-nl-vgmoo-pages-send(to, msg)
This command send a page to to (A moo object or a name/alias). (to must accept user objects from dns-nl-vgmoo-userlist). Msg is just an ordinary string. (Not a moo string)
7.1
dns-com-vmoo-userlist [1.0-1.1]
7.2 dns-com-vmoo-client [1.0]
7.3 dns-com-vmoo-pages [1.0]
From VMoo 1.5, the dns-nl-vgmoo prefix is abandoned and replaced by the dns-com-vmoo prefix.
To provide some level of compatibility VMoo wil support the old prefix in the following versions (Until VMoo 3.0 or so)
When a moo / client implementation needs to provide both interfaces the following rule should be applied:
- When both dns-nl-vgmoo-<package> and dns-com-vmoo-<package> are available the support of dns-nl-vgmoo-<package> should be disabled (Send no messages, ignore received messages)
For more information about the packages:
6.1. Dns-nl-vgmoo-userlist
6.2. Dns-nl-vgmoo-client
6.3. Dns-nl-vgmoo-pages
7.4 dns-com-vmoo-dialogs [1.0]
This package will be documented here when the first VMoo is available which supports this package.
(This package supports audio+visual moo->Client data)
This package will be documented here when the first VMoo is available which supports this package.
7.6 dns-com-vmoo-multiplex [1.0]
(This package supports multiplexing several data screens connected to 1 moo)
This package will be documented here when the first VMoo is available which supports this package.
7.7 dns-com-vmoo-presuffix [1.0]
(Advanced out of band version of standard PREFIX and SUFFIX moo commands. Probably needs server hacks!)
This package will be documented here when the first VMoo is available which supports this package.
The easiest way to read this sort of values in a moo is: $no_one:eval(string) which returs {1, value} when string is a valid moo string or {0, error_info} when string isn't. (This works als for non-wizards).