Game -- a XEP which defines the rules of a match

Initiator -- the entity that started a game.

Match -- represents a specific instance of a game played in a room.

Member -- a user with an affiliation of type "member" in the context of member-only games.

Owner -- a priviledged entity that owns a game.

Player -- a user in a match who has a defined game role

Role -- role in the game (e.g. 'black' and 'white' in chess)

Room -- a game room in which matches are played

Room JID -- the &ROOMJID; by which an occupant is identified within the context of a match; contrast with Bare JID and Full JID.

Spectator -- an entity who does not actually plays the game but watches it.

Occupant -- a player or spectator who is currently in the match.

Unmoderated Room -- The owner has limited rights. The match cannot be saved; antonym: Moderated Room.

Moderated Room -- The owner is allowed to kick users, revoke roles and save the match; antonym: Unmoderated Room.

Hidden Room -- a room that cannot be found by any user through normal means such as searching and service discovery; antonym: Public Room.

Public Room -- a room that can be found by any user through normal means such as searching and service discovery; antonym: Hidden Room.

Members-Only Room -- a room that a user cannot enter without being on the member list; antonym: Open Room.

Open Room -- a room that anyone may enter without being on the member list; antonym: Members-Only Room.

Password-Protected Room -- a room that a user cannot enter without first providing the correct password; antonym: Unsecured Room.

Unsecured Room -- a room that anyone is allowed to enter without first providing the correct password; antonym: Password-Protected Room.

Fully-Anonymous Room -- a room in which the full JIDs or bare JIDs of occupants cannot be discovered by anyone, including the room owner; contrast with Non-Anonymous Room and Semi-Anonymous Room.

Semi-Anonymous Room -- a room in which an occupant's full JID can be discovered by the room owner only; contrast with Fully-Anonymous Room and Non-Anonymous Room.

Non-Anonymous Room -- a room in which an occupant's full JID is exposed to all other occupants; contrast with Semi-Anonymous Room and Fully-Anonymous Room.

active -- room that is currently in use

adjourned -- 'saved' room

There are three different match status:

created -- before the initial room configuration is done

inactive -- before and after a match, turns are not possible, options can be changed

active -- within a match, turns are possible, options cannot be changed

paused -- halted within a match, turns are not possible, options cannot be changed

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 "island-chess@games.shakespeare.lit" room. The characters are as follows:

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.

A Jabber entity may wish to discover if a service implements the Multi-User Game protocol; in order to do so, it sends a service discovery information ("disco#info") query to the service's JID:

The service MUST return its identity and the features it supports:

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.

If the full list of rooms is large (see &xep0030; for details), the service MAY return only a partial list of rooms. If it does so, it SHOULD include a <set/> element (as defined in &xep0059;) to indicate that the list is not the full result set.

It is RECOMMENDED that a user uses &xep0055; 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 &xep0059;) 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 &xep0128;, 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 game. 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 &xep0045;.

See Room Types for details.

A user MAY also query a specific match for its associated items (occupants):

An implementation MAY return a list of existing occupants if that information is publicly available, or return no list at all if this information is kept private.

Note: These <item/> elements are qualified by the disco#items namespace, not the mug namespace; this means that they cannot possess 'role' attributes, for example.

If a non-occupant attempts to send a disco request to an address of the form &ROOMJID;, a MUG service SHOULD return the request to the entity and specify a &badrequest; 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 'http://jabber.org/protocol/mug#matches':

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:

The client MAY implement &xep0196; to announce running games. To publish a running game the user sends:

When the user stops playing the game (i.e. leaves the game room), the user's client SHOULD send an empty &GAME; element with the same ItemID:

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; 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; 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 ¬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; 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.

When a user wants to take a free role, he sends the following presence to &ROOM;.

After the role has been successfully assigned to the requesting occupant, the service MUST send the new presence to all occupants.

If the role is already taken, the service must return the following error.

If the requested role doesn't exist in the match, the service MUST return a not-acceptable error.

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 &ROOMJID; 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.

If a client wants to resign, he sends the following.

Afterwards, the service decides whether to cancel or pause the match based on the game specification.

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.

To change his nickname, an occupant sends the following presence.

The service must send the updated presence to all occupants.

If the room already contains another user with the nickname the same rules apply as on entering a room.

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 ¬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 ¬acceptable; error to the sender.

If allowed in accordance with room configuration, an occupant MAY be allowed to retrieve the list of room members. For details, see the Modifying the Member List section of this document.

In order to exit a multi-user game room, an occupant sends a presence stanza of type "unavailable" to the &ROOMJID; it is currently using in the room.

If the leaving occupant had a role that was indispensable, the service MUST pause or cancel the game.

To resume the game, all players have to send <start/> messages again.

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.

The owner may change the configuration whenever the match status is 'inactive'.

If there are no configuration options available, the service MUST return an empty query element to the owner as shown in the previous use case.

The owner SHOULD then submit the form with updated configuration information.

The owner may save the room whenever the match status is 'inactive' and save the room including the match state in a moderated room.

If saving is allowed, the service MUST inform all occupants and remove them from the room.

After saving the room, nobody can join it until it is loaded by the owner.

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 required Privileges.

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 'role' attribute.

The room owner may decide to transfer the ownership to another occupant.

1. In order to allow supporting multiple games on the service the component may offer a game plugin interface.

2. To manage team games, the service should offer game plugins an API and leave game turn message routing to the game plugins.

3. In case of loading a room the service SHOULD remember each player's role, so it can assign the roles properly when the room is loaded.

4. The game service MAY offer a managed multi-user chatroom. This can be done by creating a new chat room and keep membership synchronized with the game room.

1. In order to respect the users privacy the jabber client SHOULD hide active matches for discovering as default behavior. However jabber clients MAY offer a setting to enable the active match discovery.

2. MUG clients MAY highlight users that participate in a room chat somehow. The highlighting could be done with a small speech balloon icon behind the players name.

The XMPP Registrar includes the following MUG-related namespaces in its registry of protocol namespaces:

• http://jabber.org/protocol/mug
• http://jabber.org/protocol/mug#user
• http://jabber.org/protocol/mug#owner

A Multi-User Game service or match is identified by the "game" category and the "multi-user" type within Service Discovery.

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.