XEP-xxxx: Instant Gaming

Many modern instant messenger networks support playing games. Still, XMPP mostly lacks this kind of support. Therefore, this document 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.

2. Requirements¶

This document addresses the functionality which is needed to play games over the XMPP. In particular this functionality consists of:

3. One-to-One Gaming Use Cases¶

The following section describes the use cases associated with one-to-one instant gaming. It is not supposed to provide professional gaming capabilites with independent move validation, spectators, etc. Instead, it only supports two player games without spectators and no move validation.

Despite the existence of Multi-User Gaming, Instant Gaming is considered important for making gaming over XMPP popular. Rapid deployment of new two-player games is possible without waiting for server support or finding a suitable server.

3.1 Discovering Client Game Support¶

An implementation of Instant Gaming MUST support Service Discovery (XEP-0030) [1].

A Jabber entity may wish to discover if another entity implements the Instant Gaming protocol; in order to do so, it sends a service discovery information ("disco#info") query to the other entity's full JID:

Example 1. User Queries Another User for Instant Gaming via Disco¶

<iq from='romeo@montague.net/garden'
    to='juliet@capulet.com/balcony'
    id='req1'
    type='get'>
  <query xmlns='http://jabber.org/protocol/disco#info'/>
</iq>

The entity MUST return the features it supports. Game protocols SHOULD include a <feature/> element with their namespace in the response, too.

Example 2. Entity Returns Disco Info Results¶

<iq from='juliet@capulet.com/garden'
    to='romeo@montague.net/balcony'
    id='req1'
    type='result'>
  <query xmlns='http://jabber.org/protocol/disco#info'>
    ...
    <feature var='http://jabber.org/protocol/games'/>
    <feature var='http://jabber.org/protocol/games/tictactoe'/>
    <feature var='http://jabber.org/protocol/games/chess'/>
    ...
  </query>
</iq>

3.2 Invitation¶

In order to invite someone to a game, the initiator sends a message to her/his opponent containing an <invite/> element, which MUST specify the invitation type (see Table 1).

Furthermore, a <game/> element with a "var" attribute containing the namespace of the game protocol is REQUIRED. It MAY also contain additional information which SHOULD then be specified using Data Forms (XEP-0004) [2]. Such information might be used to state the rules or other slight variations for the particular game. If an invitation with unsupported rules or options is received, a <not-acceptable/> error of type "modify" SHOULD be send to the inviting entity.

The <thread/> element MUST be present and it MUST contain a unique ID which identifies the current match. The ID MAY for example consist of the initiator's and the opponent's (bare) JID, the game name, the current datetime (which then SHOULD conform to the DateTime profile specified in XMPP Date and Time Profiles (XEP-0082) [3]) and a random number, all separated by hyphens. It is not supposed to get parsed and is only used to uniquely identify the game.

Example 3. Romeo Invites Juliet to a Game of Checkers¶

<message
    from='romeo@montague.net/garden'
    to='juliet@capulet.com/balcony'>
  <thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
  <invite xmlns='http://jabber.org/protocol/games'
      type='new'>
    <reason>
      Hello Juliet,
      would you like to play a little game?
    </reason>
    <game var='http://jabber.org/protocol/games/checkers'/>
  </invite>
</message>

Table 1: Invitation types¶

Invitation Type	Meaning
new	The game is totally new and contains no data of previous games.
renew	The game is over and shall be recreated from the beginning with the same match ID.
adjourned	This invitation is to resume an adjourned game. It MUST only be send to the same opponent as from the beginning of the game and MUST contain the same game id. Further information provides Game Loading
constructed	This type states that the game will start with a state which is different from the state new games have.

An invitation of type "renew" SHOULD contain the same match ID and <game/> element as the initial "new" invitation. It MUST only be send when the previous match with the same match ID has been terminated. If it is received earlier, an <unexpected-request/> error SOULD be send to the sender of the premature invitation. Game protocols SHOULD switch the beginning player and leave all other options the same.

In the unlikely but possible event that an invitation of type "renew" is received immediately after one has been send with the same match ID, this invitation SHOULD be treated as if it were a <message/> with a <join/> element. Invitations with match IDs that are already assigned to a running game SHOULD be ignored.

The opponent SHOULD NOT ignore the invitation. If she/he does not want to play, the invitation SHOULD be declined. In order to decline the invitation, the opponent MUST send a message of the following form to the initiator.

Example 4. Juliet Declines Romeo’s Invitation¶

<message
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'>
  <thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
  <decline xmlns='http://jabber.org/protocol/games'>
    <reason>I won't fight you.</reason>
  </decline>
</message>

3.3 Joining a Game¶

In order to join a game, a <message/> stanza has to be send to the initiator's full JID. The <message/> stanza MUST contain the ID of the match to which the opponent wants to join in the <thread/> element. Besides that, a <join/> element qualified by the namespace 'http://jabber.org/protocol/games' is REQUIRED and the <body/> element is OPTIONAL.

Example 5. Juliet Joins the Game¶

<message
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'>
  <thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
  <join xmlns='http://jabber.org/protocol/games'/>
</message>

A successful join MUST be confirmed by sending the same message (with different sender and recipient) back to the opponent.

The initiator might refuse the join by sending a <message/> stanza of 'type' "error". It then MUST mirror the <thread/> ID and the original <join/> child element. The <error/> element MAY contain a <text/> element with a human-readable description of the error.

Example 6. Romeo Refuses Juliet¶

<message from='romeo@montague.net/garden'
    to='juliet@capulet.com/balcony'
    type='error'/>
  <thread>romeo@montague.net-juliet@capulet.com-checkers-1591-02-21T12:56:15Z-1234</thread>
  <join xmlns='http://jabber.org/protocol/games'/>
  <error type='cancel'>
    <not-allowed xmlns='urn:ietf:params:xml:xmpp-stanzas'/>
    <text>You are not welcome here!</text>
  </error>
</message>

3.4 Game Play¶

A turn in a game is sent in a message (of type "chat") to the other player's full JID. The <message/> stanza contains a <turn/> element which contains the element, representing the desired action (e.g. <move/>) qualified by the namespace of the particular game. The action itself can be further described by attributes or child elements (see corresponding game protocol).

A human-readable comment MAY be sent with the move in the <body/> element of the <message/>. In order to track the game to which the move belongs, the match ID is REQUIRED to be in the <thread/> element.

Example 7. Juliet Sends a Game Move to Romeo¶

<message
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'
    type='chat'>
  <thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
  <body>What do you say to this?</body>
  <turn xmlns='http://jabber.org/protocol/games'>
    <move xmlns='http://jabber.org/protocol/games/tictactoe'
        id='1'
        row='2'
        col='2'/>
  </turn>
</message>

A receipt for each message MAY be requested in accordance with Message Delivery Receipts (XEP-0184) [4].

3.5 Game Saving¶

While playing a game, it might be desirable to interrupt playing and resume it at a later time. Games with complete knowledge can be saved at any time by each of the players without sending messages. But the client of the saving player SHOULD inform the other player that the game was saved by sending the following message.

Example 8. Romeo Informs Juliet that he Saved the Game¶

<message
    from='romeo@montague.net/garden'>
    to='juliet@capulet.com/balcony'
  <thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
  <saved xmlns='http://jabber.org/protocol/games'/>
</message>

After receiving such an notification, an implementation MAY decide to save the game, too.

When playing games with incomplete knowledge, it is desirable that both players save the game at the same time in order to save a clean game state. The game protocol MUST define whether its game has to be saved independently or mutually.

If a game needs to be saved mutually by both players, one of the players requests the game to be saved by sending a message with a <save/> child element as follows.

Example 9. Juliet Issues a Game Saving Process¶

<message
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'>
  <thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
  <save xmlns='http://jabber.org/protocol/games'/>
</message>

The recipient of the above message MUST confirm a successful saving process using a <saved/> element as above.

To ensure that both players save the same game state, the sender MUST NOT send any game moves until he receives confirmation from the other player and the receiver MUST NOT send any game moves after receiving the request for saving until he has responded to it.

If the sender of the saving request receives a game move before getting confirmation of a successful saving process, she/he MUST NOT save the game and MUST send the following error message.

Example 10. A Mutual Game Save between Romeo and Juliet Fails¶

<message
    from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'
    type='error'>
  <thread>juliet@capulet.com-romeo@montague.net-tictactoe-1591-02-23T11:36:25Z-4321</thread>
  <save xmlns='http://jabber.org/protocol/games'/>
  <error type='cancel'>
    <conflict/>
  </error>
</message>

If one of the player's client encounters an error during the saving process, it MUST send an error message, too. This time it SHOULD NOT use a <conflict/>, but an <undefined-condition/> error condition.

3.6 Game Loading¶

An XMPP entity that wishes to resume a saved game has to send an invitation of "type" 'adjourned' to the same opponent it began playing with. It MAY also resume the game with another opponent, but then it MUST use the "type" 'constructed' and a new match ID.

In case the game requires mutual saving by both players and the game was saved this way, one of the players simply sends an invitation of "type" 'adjourned' with the match ID of the saved game to the other player. After the invitee has successfully joined the game, it begins at the point where it was saved.

If the game was only saved by one of the players, the inviting player MUST send the saved game state in the invitation. This SHOULD be done by including an <x/> element in the <message/> stanza of the 'jabber:x:data' namespace. The exact representation of the game state is up to the game protocol, but SHOULD use Data Forms (XEP-0004) [2]. E.g. the state MAY also be encoded in a history of game moves.

Example 11. Romeo Invites Juliet to a Saved Game¶

<message
    from='romeo@montague.net/garden'
    to='juliet@capulet.com/balcony'>
  <thread>romeo@montague.net-juliet@capulet.com-tictactoe-1591-02-21T12:56:15Z-1234</thread>
  <invite xmlns='http://jabber.org/protocol/games'
      type='adjourned'>
    <reason>
      Hello Juliet,
      would you like to resume our little game?
    </reason>
    <game var='http://jabber.org/protocol/games/tictactoe'/>
    <x xmlns='jabber:x:data'
        type='submit'>
      <title>Game of Tic Tac Toe saved on 21st of February 1591 at 1 o'clock</title>
      <field var='x-player' type='jid-single'>
        <value>juliet@capulet.com/balcony</value>
      </field>
      <field var='o-player' type='jid-single'>
        <value>romeo@montague.net/garden</value>
      </field>
      <field var='move-id'>
        <value>5</value>
      </field>
      <field var='1-1'/>
      <field var='1-2'/>
      <field var='1-3'/>
        <value>o</value>
      </field>
      <field var='2-1'>
        <value>o</value>
      </field>
      <field var='2-2'>
        <value>x</value>
      </field>
      <field var='2-3'>
        <value>x</value>
      </field>
      <field var='3-1'/>
      <field var='3-2'/>
      <field var='3-3'/>
    </x>
  </invite>
</message>

The Tic Tac Toe game state information in this example is entirely fictional and only for demonstration purposes.

An implementation MAY present the game in the saved state to the user along with the invitation. It MAY also compare the state it received with the state it saved by its own and inform the user about any mismatches.

3.7 Termination¶

An implementation SHOULD send the following <message/> to end the game. The "reason" attribute is always REQUIRED.

Example 12. Romeo Terminates the Game and Accuses Juliet of Cheating¶

<message
    from='romeo@montague.net/garden'
    to='juliet@capulet.com/balcony'>
  <thread>juliet@capulet.com-romeo@montague.net-checkers-1591-02-23T11:36:25Z-4321</thread>
  <body>What devil art thou, that dost torment me thus?</body>
  <terminate xmlns='http://jabber.org/protocol/games'
    reason='resign'/>
</message>

This <message/> SHOULD also be send by one of the players before she/he changes her/his presence to unavailable, though a different "reason" MAY be used. For a list of possible reasons and their meaning see Table 2.

In case one player changes her/his presence to unavailable without sending a termination message, the other player might just wait or MAY save the game (if possible) and send a termination message with reason 'adjourn'.

A terminating <message/> with reason 'cheating' SHOULD be send, if an illegal move is received. If one entity receives a terminating <message/> although it already send one by it's own, it MUST ignore it.

Table 2: Termination reasons¶

Reason	Meaning
won	The player sending the message has won the game.
lost	The player sending the message has lost the game.
draw	The game is over and nobody has won.
resign	The player sending the message capitulates and quits.
adjourn	The game is not over and might be resumed at a later time.
cheating	The player receiving the message has submitted an illegel game move.

4. Glossary¶

Opponent -- in an One-to-One gaming context, the entity who was invited to play and did not start the game.

5. Business Rules¶

6. Implementation Notes¶

7. Internationalization Considerations¶

8. Security Considerations¶

9. IANA Considerations¶

10. XMPP Registrar Considerations¶

11. XML Schema¶

Appendices

Appendix A: Document Information¶

Appendix B: Author Information¶

Torsten Grote

Arne König

Appendix C: Legal Notices¶

Copyright

Permissions

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.

IPR Conformance

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).

Visual Presentation

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.

Appendix D: Relation to XMPP¶

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.

Appendix E: Discussion Venue¶

The primary venue for discussion of XMPP Extension Protocols is the <standards@xmpp.org> discussion list.

Discussion on other xmpp.org discussion lists might also be appropriate; see <https://xmpp.org/community/> for a complete list.

Appendix F: Requirements Conformance¶

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".