WARNING: This document has not yet been accepted for consideration or approved in any official manner by the XMPP Standards Foundation, and this document is not yet an XMPP Extension Protocol (XEP). If this document is accepted as a XEP by the XMPP Council, it will be published at <http://xmpp.org/extensions/> and announced on the <email@example.com> mailing list.
Many modern instant messenger networks support playing games.
Still, XMPP mostly lacks this kind of support.
Therefore, this document (Multi-User Gaming or MUG) describes a base protocol for game playing over XMPP.
This protocol is not by itself sufficient to play games.
It just describes a basic protocol framework which game-specific protocols can use.
Most of the examples in this document use the scenario of Miranda and Ferdinand playing chess in Act V, Scene I of Shakespeare's The Tempest,
represented here as the "firstname.lastname@example.org" room. The characters are as follows:
Support for the all affiliations is REQUIRED.
(The "None" affiliation is the absence of an affiliation.)
If a user without a defined affiliation enters a match, the user's affiliation is defined as "None".
The member affiliation provides a way for room owners to specify a "whitelist" of users
who are allowed to enter a members-only match.
When a member enters a members-only match, his or her affiliation does not change.
Information about affiliations MUST be sent in all presence stanzas generated or reflected by the match and sent to occupants.
Owners are allowed to do what they like (saving/loading, change match options, etc.)
except in unmoderated matches. This match type restricts the use of owner privileges to specific room statuses.
Users with no affiliation SHALL NOT enter members-only matches.
Besides that, these users have the same privileges as members.
The ways in which a user's affiliation changes are well-defined.
Sometimes the change results from the user's own action (e.g., registering as a member of the match),
whereas sometimes the change results from an action taken by an owner.
If a user's affiliation changes, a MUG service implementation MUST change the user's affiliation to reflect the change
and communicate that to all occupants.
The service discovery items ("disco#items") protocol enables a user to query a
service for a list of associated items, which in the case of a game service would
consist of the active game rooms hosted by the service.
The service SHOULD return a full list of the active and public rooms it hosts.
It is RECOMMENDED that a user uses Jabber Search (XEP-0055)  to search for active or adjourned rooms.
At first the user needs to discover what search fields are supported by the service:
The service MUST then return the possible search fields to the user, and MAY include instructions:
The Saved Room option allows to search for active or adjourned rooms (see Room Status).
The Game Category field is to classify the game and to be able to only search for certain types of games.
Every game protocol MUST define its category in the corresponding game XEP.
After having received the possible search fields,
the user MAY then submit a search request, specifying values for any desired fields:
The submitting entity MAY submit the 'category' or 'game' field but MUST NOT submit both.
Sending an empty form adds up to searching for all games.
The service SHOULD then return a list of search results that match the values provided:
If the full list of rooms is large,
the service MAY return only a partial list of rooms.
If it does so, it SHOULD include a <set/> element (as defined in Result Set Management (XEP-0059) )
to indicate that the list is not the full result set.
Using the disco#info protocol, a user may also query a specific room for
more detailed information about the room. A user MAY do so before entering a
room in order to discover the room configuration.
The room then MUST return its identity and the features it supports.
A room MUST also return more detailed information in its disco#info response
using Service Discovery Extensions (XEP-0128) , identified by inclusion of a hidden FORM_TYPE field whose
value is "http://jabber.org/protocol/mug#matchinfo".
It MUST include a 'mug#game' field specifiying the namespace of the
Optional information MAY include a more verbose description of the room
and the current number of occupants and players in the match or
'mug#match_chat' field specifiying a URI for the chat.
This is usually a Multi-User Chat (XEP-0045) .
If a non-occupant attempts to send a disco request to an address of the form
<room@service/nick>, a MUG service SHOULD return the request to the entity and specify a
<bad-request/> error condition. If an occupant sends such a request, the service
MAY pass it through the intended recipient.
A Jabber user may want to discover if one of the user's contacts supports the
Multi-User Game protocol. This is done using Service Discovery.
The client SHOULD return its identity and the features it supports:
A user may also query a contact regarding which room the contact is in.
This is done by querying the contact's full JID (<user@host/resource>)
while specifying the Service Discovery node
The requested client MAY list the active rooms as response;
see the Implementation Guidelines section of this document for details.
Optionally, the contact MAY include its room nick as the value of the 'name' attribute:
It can be useful to invite other users to a room in which one is an occupant.
To do this, a MUG client sends XML of the following form to the <room@service> itself
adding an <invite/> element for every invitee.
(the reason is OPTIONAL and the message MUST be explicitly or implicitly of type "normal"):
The <room@service> itself MUST then add a 'from' address to the <invite/> element whose value is the room JID of the invitor
and send the invitation to the invitee specified in the 'to' address.
The room SHOULD add the password if the room is password-protected:
If the room is members-only, the service MAY also add the invitee to the member list.
If the invitor supplies a non-existent JID, the room SHOULD return an <item-not-found/> error to the invitor.
The invitee MAY choose to formally decline (as opposed to ignore) the invitation;
and this is something that the sender may want to be informed about.
In order to decline the invitation,
the invitee MUST send a message of the following form to the <room@service> itself:
Invitations MAY be based on room JIDs rather than bare JIDs
(so that, for example, an occupant could invite someone from one match to
another without knowing that person's bare JID).
Thus the service MUST handle both the invites and declines.
If the service is able to add the user to the room,
it MUST send presence from all the existing occupants' room JIDs to the new occupant's full JID,
including extended presence information about roles in a <game/> element
qualified by the 'http://jabber.org/protocol/mug' namespace
and containing an <item/> child with the 'affiliation' attribute
set to a value of "owner", "member", or "none" as appropriate:
The service MUST also send the new occupant's presence to all occupants including the new occupant.
If a role was assigned to the new occupant, it MUST be included in the presence
in order to notify the new and all other occupants about the new occupant's role.
Note: The order of the presence stanzas sent to the new occupant is important.
The service MUST first send the complete list of the existing occupants to the
new occupant and only then send the new occupant's own presence to the new
occupant. This helps the client know when it has received the complete
If the room is non-anonymous, the service MUST send the new occupant's full JID
to all occupants using extended presence information in an <game/> element qualified
by the 'http://jabber.org/protocol/mug' namespace and containing an <item/> child
with a 'jid' attribute specifying the occupant's full JID:
If the room is semi-anonymous, the service MUST send presence from the new occupant
to all occupants as specified above, but MUST include the new occupant's full JID
only in the presence notifications it sends to the room owner and not to any other
If the room requires a password and the user did not supply one (or the password
provided is incorrect), the service MUST deny access to the room and inform the
user that they are unauthorized; this is done by returning a presence stanza of
type "error" specifying a <not-authorized/> error:
Passwords SHOULD be supplied with the presence stanza sent when entering the room,
contained within an <game/> element qualified by the
'http://jabber.org/protocol/mug' namespace and containing a <password/> child.
Passwords are to be sent as cleartext; no other authentication methods are supported
at this time, and any such authentication or authorization methods shall be defined
in a separate specification (see the Security Considerations
section of this document).
If the room is members-only but the user is not on the member list, the service MUST
deny access to the room and inform the user that they are not allowed to enter the
room; this is done by returning a presence stanza of type "error" specifying a
<registration-required/> error condition:
If the room already contains another user with the nickname desired by the user
seeking to enter the room (or if the nickname is reserved by another user on the
member list), the service MUST deny access to the room and inform the user of the
conflict; this is done by returning a presence stanza of type "error" specifying a
<conflict/> error condition:
However, if the bare JID <user@domain> of the present occupant matches the bare JID
of the user seeking to enter the room, then the service SHOULD allow entry to the user,
so that the user has two (or more) in-room "sessions" with the same roomnick, one for each resource.
If a service allows more than one occupant with the same bare JID and the same room nickname,
it SHOULD route in-room messages and presence to all of the user's resources
and allow all of the user's resources to send messages to the room;
it is up to the implementation to determine how to route
private messages to all or only one resource
(based on presence priority or some other algorithm).
If the room has reached its maximum number of occupants, the service SHOULD
deny access to the room and inform the user of the restriction; this is done
by returning a presence stanza of type "error" specifying a <service-unavailable/>
Alternatively, the room could kick an "idle user" in order to free up space.
If a user attempts to enter a room while it is "locked" (i.e., before the room creator
provides an initial configuration and therefore before the room officially exists), the
service MUST refuse entry and return an <item-not-found/> error to the user:
If the room does not already exist when the user seeks to enter it, the service SHOULD
create it; however, this is not required, since an implementation or deployment MAY
choose to restrict the privilege of creating rooms. For details, see the
Creating a Room section of this document.
After the match is ready to be started (as to be defined by the game protocol),
all players MUST send start messages in order to start the game.
In order to see what players are ready to start, the service MUST reflect
the start message from each player to all players.
If the match is not ready, the service MUST send the following error.
After the service received messages from all players,
it MUST update the match status from inactive to active by a
presence broadcast to all occupants.
If the owner changes the configuration or roles change after a player sent his message
and before the service sends presence broadcast indicating the game status active,
the player MUST send the message again.
Note that the spectator alonso recieves the start presence, too.
In order to make a move in a match, a <message/> stanza MUST be send to <room@service/nick>
containing a <turn/> element qualified by 'http://jabber.org/protocol/mug#user' namespace.
Game protocols SHOULD place own elements defining the turn inside the <turn/> element.
A service MUST validate the player's move before passing it to the occupants.
If the turn is invalid, as defined by the game protocol,
the service MUST return an error and kick the player
unless the player is the owner of the room, in which case he SHOULD lose his game role.
If a spectator sends a turn the service MUST return the following error.
If a player sends a turn while the match status is 'inactive' or 'paused'
the service MUST send this error:
If the move is valid, the service MUST distribute the turn.
The occupants, who receive the turn are defined by the game protocol.
However, the turn MUST be reflected to the sender.
The game protocol respectively the game protocol implementation decides when a match is over.
In the case of game termination,
the service MUST notify every player through updated presence including the resulting final state.
Since each occupant has a unique room JID, an occupant MAY send a "private message" to a
selected occupant via the service by sending a message to the occupant's match JID. The message
type SHOULD be "chat", or MAY be left unspecified (i.e., a normal message). This privilege
SHOULD be allowed to any occupant (even a spectator in a moderated room).
The service is responsible for changing the 'from' address to the sender's match JID and
delivering the message to the intended recipient's full JID.
If the sender attempts to send a private message to a room JID that does not exist,
the service MUST return an <item-not-found/> error to the sender.
If the sender is not an occupant of the room in which the intended recipient is visiting,
the service MUST return a <not-acceptable/> error to the sender.
To create a room a user sends the following presence to the room.
If the priviledge to create a room is restricted to certain users
and the room cannot be created,
the service MUST reply with the following error.
If a game element or the var attribute with the game namespace is
missing then the service MUST deny creating a room and send a
presence with a bad request error back to the user.
If this user is allowed to create a room and the room does not yet exist,
the service MUST create the room according to some default configuration,
assign the requesting user as the initial room owner,
and add the owner to the room but not allow anyone else to enter the room
(effectively "locking" the room).
The initial presence stanza received by the owner from the room MUST include
extended presence information indicating the user's status as an owner
and acknowledging that the room is awaiting configuration and that the initial
match status is 'created'.
The role attribute is only necessary if the service assignes roles automatically.
If the user wants to configure the room, he MAY first request the configuration form.
If no configuration is possible, the service MUST return the following error.
The service then sends the initial configuration form to the user.
To finish the configuration, the user MUST submits the completed form to the service.
In addition to the room configuration, the user MAY also supply a custom initial state for the match.
Valid states are defined by the game protocol
and may consist of the explicit current state in form of a data form
or the series of turns that led to the state.
If the room creation fails because the specified room configuration options violate
one or more service policies (e.g., because the password for a password-protected room is blank),
the service MUST return a <not-acceptable/> error.
Alternatively, the room owner MAY cancel the configuration process:
If the room owner cancels the initial configuration, the service SHOULD destroy the room, making sure to send unavailable presence to the room owner (see the "Destroying a Room" use case for protocol details).
For Discovering of Saved Rooms see search for rooms.
Send an iq stanza to request loading a the room as follows:
After loading, the match status is 'paused' if the match was 'active' before saving.
Alternatively, the match status is set to 'inactive' if the match was inactive.
The service SHOULD send an invitation to all occupants that were present in the game when saved.
Players entering the room SHOULD be assigned the role they had when the room was saved.
In the context of a members-only match, the member list is essentially a
"whitelist" of people who are allowed to enter the match. Anyone who is not
a member is effectively banned from entering the match.
In the context of an open match, the member list is simply a list of users
(bare JID and reserved nick) who are registered with the match. Such users
may appear in a match roster, have their match nickname reserved, be
returned in search results, and the like.
It is RECOMMENDED that only the room owner
has the privilege to modify the member list in members-only rooms.
To do so, the owner first requests the member list by querying the room
for all users with an affiliation of "member":
Note: A service SHOULD also return the member list to any occupant in a
members-only room; i.e., it SHOULD NOT generate a <forbidden/> error when
a member in the room requests the member list.
This functionality may assist clients in showing all the existing members
even if some of them are not in the room, e.g. to help a member determine
if another user should be invited.
A service SHOULD also allow any member to retrieve the member list even
if not yet an occupant.
The service MUST then return the full member list to the owner qualified
by the 'http://jabber.org/protocol/mug#owner' namespace; each item MUST
include the 'affiliation' and 'jid' attributes and MAY include the 'nick' and
'role' attributes for each members that is currently an occupant.
The owner MAY then modify the member list. In order to do so, the owner MUST
send the changed items (i.e., only the "delta") to the service; each item MUST
include the 'affiliation' attribute (normally set to a value of "member" or "none")
and 'jid' attribute but SHOULD NOT include the 'nick' attribute and MUST NOT include
the 'role' attribute (which is used to manage game roles in a room):
The service MUST modify the member list and then inform the owner of success:
The service MUST change the affiliation of any affected user.
If the user has been removed from the member list, the service MUST change the user's
affiliation from "member" to "none".
If the user has been added to the member list, the service MUST change the user's affiliation to "member".
If a removed member is currently in a members-only room, the service SHOULD kick
the occupant by changing the removed member's affiliation to "none" and send appropriate
presence to the removed member as previously described.
No matter whether the removed member was in or out of a members-only room, the service MUST
subsequently refuse entry to the user.
For all room types, the service MUST send updated presence from this individual to all occupants,
indicating the change in affiliation by including an <game/> element qualified by the
'http://jabber.org/protocol/mug' namespace and containing an <item/> child with the
'affiliation' attribute set to a value of "none".
In addition, the service SHOULD send an invitation to any user who has been added to the
member list of a members-only room if the user is not currently affiliated with the
room, for example as an owner (such a user would by definition not be
in the match; note also that this example includes a password but not a reason --
both child elements are OPTIONAL):
While only the owner SHOULD be allowed to modify the member list,
an implementation MAY provide a configuration option that opens invitation privileges
to any member of a members-only match. In such a situation, any invitation sent SHOULD
automatically trigger the addition of the invitee to the member list.
However, if invitation privileges are restricted to the owner and a mere member attempts
to a send an invitation, the service MUST deny the invitation request and return a
<forbidden/> error to the sender:
Invitations sent through an open room MUST NOT trigger the addition of the invitee
to the member list.
If a user is added to the member list of an open room and the user is in the room,
the service MUST send updated presence from this individual to all occupants,
indicating the change in affiliation by including an <game/> element qualified by
the 'http://jabber.org/protocol/mug' namespace and containing an <item/>
child with the 'affiliation' attribute set to a value of "member".
The room owner may decide to modify the assigned game roles in a room.
To do so, the owner first requests a list of the occupants
and assigned roles by querying the room:
Note: The role 'all' is a reserved name for querying the list of
active players and MUST NOT be redefined by games for other purposes.
The service SHOULD then return the full list of all occupants qualified by
the 'http://jabber.org/protocol/mug#owner' namespace; each item MUST include the
'role' and 'nick' attributes and MAY include the 'jid' and 'affiliation' attributes for each
occupant in the room.
The service MUST send a <forbidden/> error if the owner has not the
The owner MAY then modify the roles assigned by occupants.
In order to do so, the owner MUST send the changed items (i.e., only the "delta") to the service;
each item MUST include the 'roles' attribute
and 'nick' attribute but SHOULD NOT include the 'jid' attribute and MUST NOT include
the 'affiliation' attribute:
The service MUST modify the roles of the occupants and then inform the owner of success:
The service MUST change the roles of any affected user and
MUST send updated presence to all occupants,
indicating the changed role by including an <game/> element qualified by the
'http://jabber.org/protocol/mug' namespace and containing an <item/> child with the
There are many features related to a MUG service or match that can be
discovered by means of Service Discovery. The most fundamental of these
is the 'http://jabber.org/protocol/mug' namespace. In addition, a MUG match
SHOULD provide information about the specific match features it implements,
such as password protection and match moderation.
Permission is hereby granted, free of charge, to any person obtaining a copy of this specification (the "Specification"), to make use of the Specification without restriction, including without limitation the rights to implement the Specification in a software program, deploy the Specification in a network service, and copy, modify, merge, publish, translate, distribute, sublicense, or sell copies of the Specification, and to permit persons to whom the Specification is furnished to do so, subject to the condition that the foregoing copyright notice and this permission notice shall be included in all copies or substantial portions of the Specification. Unless separate permission is granted, modified works that are redistributed shall not contain misleading information regarding the authors, title, number, or publisher of the Specification, and shall not claim endorsement of the modified works by the authors, any organization or project to which the authors belong, or the XMPP Standards Foundation.
Disclaimer of Warranty
## NOTE WELL: This Specification is provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. ##
Limitation of Liability
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall the XMPP Standards Foundation or any author of this Specification be liable for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising from, out of, or in connection with the Specification or the implementation, deployment, or other use of the Specification (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if the XMPP Standards Foundation or such author has been advised of the possibility of such damages.
This XMPP Extension Protocol has been contributed in full conformance with the XSF's Intellectual Property Rights Policy (a copy of which can be found at <https://xmpp.org/about/xsf/ipr-policy> or obtained by writing to XMPP Standards Foundation, P.O. Box 787, Parker, CO 80134 USA).
The HTML representation (you are looking at) is maintained by the XSF. It is based on the YAML CSS Framework, which is licensed under the terms of the CC-BY-SA 2.0 license.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 6120) and XMPP IM (RFC 6121) specifications contributed by the XMPP Standards Foundation to the Internet Standards Process, which is managed by the Internet Engineering Task Force in accordance with RFC 2026. Any protocol defined in this document has been developed outside the Internet Standards Process and is to be understood as an extension to XMPP rather than as an evolution, development, or modification of XMPP itself.
The following requirements keywords as used in this document are to be interpreted as described in RFC 2119: "MUST", "SHALL", "REQUIRED"; "MUST NOT", "SHALL NOT"; "SHOULD", "RECOMMENDED"; "SHOULD NOT", "NOT RECOMMENDED"; "MAY", "OPTIONAL".
7. The XMPP Registrar maintains a list of reserved protocol namespaces as well as registries of parameters used in the context of XMPP extension protocols approved by the XMPP Standards Foundation. For further information, see <https://xmpp.org/registrar/>.