This document defines how to initiate a game session over the XMPP protocol
WARNING: This document has not yet been accepted for consideration or approved in any official manner by the Jabber Software Foundation, and this document must not be referred to as a Jabber Enhancement Proposal (JEP). If this document is accepted as a JEP by the Jabber Council, it will be published at <http://www.jabber.org/jeps/> and announced on the <email@example.com> mailing list.
Type: Standards Track
Last Updated: 2006-08-31
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, JEP-0030, JEP-0163, JEP-0049
Superseded By: None
Short Name: Not yet assigned
This Jabber Enhancement Proposal is copyright 1999 - 2006 by the Jabber Software Foundation (JSF) and is in full conformance with the JSF's Intellectual Property Rights Policy (http://jabber.org/jsf/ipr-policy.php). This material may be distributed only subject to the terms and conditions set forth in the Open Publication License, v1.0 or later (the latest version is presently available at http://www.opencontent.org/openpub/).
The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.
The Extensible Messaging and Presence Protocol (XMPP) is defined in the XMPP Core (RFC 3920) and XMPP IM (RFC 3921) specifications contributed by the Jabber Software 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 JEP 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 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".
Many modern IM networks support playing games. Still, XMPP mostly lacks the support. This document specifies, how to initiate a game session, however does not specify any of these games.
It also describes how to save a game session for future use, move the negotiation or to other resource and how to publish the will to play games (or game presence). These features are optional.
This depends on JEP-0030 (Service Discovery), which is used to discover game support, as well as the optional parts of this protocol and the actual games.
The presenting of game presence depends on PEP (JEP-0163).
The private XML storage (JEP-0049) is used when for saving the game session for future.
To discover support for the game, a Service Discovery query MUST be sent to all entities in question. Entity that supports this protocol MUST respond and include the <feature var='http://jabber.org/protocols/games'/> in the response. It MAY present <feature var='http://jabber.org/protocols/games#save'/> and <feature var='http://jabber.org/protocols/games#forward'/> when it supports saving the game and forwarding the game to other resource respectively. Ability to present game availability does not need to be discovered.
<iq type='get' firstname.lastname@example.org' email@example.com' id='req1'> <query xmlns='http://jabber.org/protocol/disco#info'/> </iq> <iq type='result' firstname.lastname@example.org' email@example.com' id='req1'> <query xmlns='http://jabber.org/protocol/disco#info'> ... <feature var='http://jabber.org/protocol/games'/> <feature var='http://jabber.org/protocol/games#save'/> <feature var='http://jabber.org/protocol/games#forward'/> ... </query> </iq>
There are many types of games. From the point of view of the sessions, they can be divided into these:
For this purpose, there are these kinds of information to be sent:
In order to discover list of supported and actually ongoing/connectable games, one can request a game list using an <iq/> stanza of 'type' "get". It contains an empty element <list/> qualified by 'http://jabber.org/protocol/games' namespace.
<iq firstname.lastname@example.org/room' to='games.montague.net' type='get' id='list'> <list xmlns='http://jabber.org/protocol/games'/> </iq>
In the answer, the <list/> element contains any number of <game-type/> elements, each specifying a supported game type. It MUST possess a 'type' attribute. The value of this attribute is the namespace of the game, specified in a separate protocol. Each of these MAY contain list of active games. Each game is represented as an <game> element, possessing 'gid' attribute, which is the game id. It MAY contain a 'name' attribute, which is a human readable name of that game.
The <game/> element MAY contain <opened/> element, which means the game can be connected. The <game/> element MAY contain <spectable/> element, which means the game can be connected as spectator. The <game/> element MAY contain <description/> element, which contains a human readable description of the game. It MAY as well contain any other XML data, but it MUST be in the game namespace.
<iq from='games.montague.net' email@example.com/room' type='result' id='list'> <list xmlns='http://jabber.org/protocol/games'> <game-type type='game:swordplay'> <game gid='gid1' name='practise'> <opened/> <spectable/> <rules xmlns='game:swordplay'> <no-kills/> </rules> </game> </game-type> <game-type type='game:machination'/> </list> </iq>
The returned list MAY not include all active games, but it SHOULD include all supported game types, because the game list is used to discover, which game types can be initiated with this JID or invited to.
If the game allows it, a game type that is not directly supported by this resource, but is supported by a different resource or application, that may be launched if need, may be included in the list. In that case, invitations SHOULD be forwarded by actually queried JID to the resource which supports it. In other words, one resource (the IM client) MAY pretend it can play some game and if an invitation comes, it launches an application capable of playing the game and forwards the invitation to it. If a game supports this, it MUST start the negotiation by an invitation.
Invitation is a <message/> stanza without a 'type' attribute. It may be addressed directly to a full JID, or to a bare JID. It MAY contain <text/> element, which contains human readable text to be showed with the invitation. The <message/> stanza MUST contain an <invite/> element qualified by 'http://jabber.org/protocol/games' namespace. It possesses these attributes:
|'type'||REQUIRED||The value of this attribute is the namespace of the game ("game:swordplay" in the above example)|
|'gid'||REQUIRED||The game id. If the game does not yet exists, it must be generated for the purpose of the invitation. The game id MUST be generated in a manner that minimizes the possibility of the gid collisions (two same gids).|
|'name'||OPTIONAL||Human readable name of game.|
|'description'||OPTIONAL||Human readable description of game. SHOULD be longer than name.|
|'password'||OPTIONAL||Some games may be password protected. In order to be able to join such game, one must know the password. If inviting to a password protected game, the inviter SHOULD include this attribute.|
|'originator'||OPTIONAL||As said above, the invitation MAY be forwarded to different resource. In that case, this attribute contains the original sender of the invitation. Invitation with this attribute included MUST NOT be forwarded to different bare JID, only to different resource of the same JID.|
The <invite/> element MAY contain other XML data in the scope of game namespace. The purpose of these is to more specify the game, for example the proposed or used game rules.
The <invite/> element MAY contain <spectator/> element, which specifies the invitation is not invitation for a game, but only to spectate.
<message firstname.lastname@example.org/garden' email@example.com/room'> <text>Come practice a bit</text> <invite xmlns='http://jabber.org/protocol/games' type='game:swordplay' gid='gid1' name='practise'> <rules xmlns='game:swordplay'> <no-kills/> </rules> </invite> </message>
To forward an invitation to a different resource, 'originator' attribute is added and set to the sender of the invitation and is sent to the other resource othervise unchanged.
If an invitation with 'originator' attribute set is received from different JID, it MUST be ignored.
<message firstname.lastname@example.org/room' email@example.com/garden'> <text>Come practice a bit</text> <invite xmlns='http://jabber.org/protocol/games' type='game:swordplay' gid='gid1' name='practise' firstname.lastname@example.org/garden'> <rules xmlns='game:swordplay'> <no-kills/> </rules> </invite> </message>
When one side wants to create a game session with other side, it sends <iq/> stanza of 'type' "set" to the other side. It contains <init/> element qualified by 'http://jabber.org/protocol/games' namespace. It possess these attributes:
|'type'||REQUIRED||Namespace of the game this session will serve for.|
|'gid'||REQUIRED||Game id. If the game does not yet exist (this session creates it), it must be generated. MUST be generated in a way that minimizes the possibility of the gid collisions.|
|'password'||OPTIONAL||If the game is password protected, specifies the password to log in the game.|
The <init/> element MAY contain <spectator/> element, which specifies that user does not want to really join the game, but just watch. It MAY as well contain <get-player-list/> element, which is used with web type games. It is described bellow.
<iq type='set' email@example.com/garden' firstname.lastname@example.org/garden' id='in'> <init xmlns='http://jabber.org/protocol/games' type='game:swordplay' gid='gid1'> <equipment xmlns='game:swordplay'>saber</equipment> </init> </iq>
On positive response, the <init/> element returned possess only one attribute, 'sid'. The value is the ID of this session. The session MUST be generated in a way that minimizes possibility od ID collisions. The <init/> element MAY contain XML data qualified by the game namespace to provide additional information.
<iq type='result' email@example.com/garden' firstname.lastname@example.org/garden' id='in' <init xmlns='http://jabber.org/protocol/games' sid='sid1'/> </iq>
To start the game, one player just becomes the only player of the game and others start joining his game.
User creates a session to one of the already connected players. While requesting the session, he MUST include the <get-player-list/< element. After the session is created, list of other players is sent to him and he creates sessions to them as well. In these session, he MUST NOT include the <get-player-list/>.
When a user creates a session and requests the player list, the accepting user MUST send the list of other players to him and send the list.
The list is <message/> stanza containing <player-list/> qualified by the 'http://jabber.org/protocol/games' namespace. It contains any number of <player/> elements, which contains full JIDs of other players.
Joins and disconnects of players can be tracked by created/terminated connections.
TODO: Some example
The session terminates whenover something of these happens:
Sending a <message/> stanza, which contains <term/> element qualified by 'http://jabber.org/protocol/games' namespace terminates the session. It MUST possess 'sid' attribute, which specifies, what session should be terminated. The <message/> stanza MAY contain <text/> attribute, which is the player's leaving message. The <term/> element MAY contain additional XML data qualified by the game namespace.
The <message/> stanza MUST be addressed to the full JID, with which the session was initiated.
<message email@example.com' firstname.lastname@example.org'> <text>I have something to do</text> <term xmlns='http://jabber.org/protocol/games' sid='sid1'/> </message>
For privacy reasons, the implementation MAY reject the session, not show the invitation or not provide full list of games to other entity.
This JEP requires no interaction with the the Internet Assigned Numbers Authority (IANA) .
The Jabber Registrar  shall include 'http://jabber.org/protocol/games' in its registry of protocols.
1. The Internet Assigned Numbers Authority (IANA) is the central coordinator for the assignment of unique parameter values for Internet protocols, such as port numbers and URI schemes. For further information, see <http://www.iana.org/>.
2. The Jabber Registrar maintains a list of reserved Jabber protocol namespaces as well as registries of parameters used in the context of protocols approved by the Jabber Software Foundation. For further information, see <http://www.jabber.org/registrar/>.