JEP-xxxx: Chess game

This document defines how to play a chess game over XMPP


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 <standards-jig@jabber.org> mailing list.


JEP Information

Status: ProtoJEP
Type: Standards Track
Number: xxxx
Version: 0.0.2
Last Updated: 2006-09-14
JIG: Standards JIG
Approving Body: Jabber Council
Dependencies: XMPP Core, Game sessions
Supersedes: None
Superseded By: None
Short Name: Not yet assigned

Author Information

Michal Vaner

Email: michal.vaner@kdemail.net
JID: michal.vaner@njs.netlab.cz

Legal Notice

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

Discussion Venue

The preferred venue for discussion of this document is the Standards-JIG discussion list: <http://mail.jabber.org/mailman/listinfo/standards-jig>.

Relation to XMPP

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.

Conformance Terms

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


Table of Contents

1. Introduction
2. Requirements
3. Discovering Support
4. Game Presence
5. Game Start
5.1. The Invitation
5.2. Session Creation
6. Game Flow
7. Game Termination
7.1. Explicit Termination
7.2. Match Termination
7.3. Player Leaves
8. Spectators
8.1. Spectator Initialization
8.2. Game Flow
8.3. Spectator Termination
9. Saving The Game
10. Game Forwarding
11. Implementation Notes
11.1. Simplified Clients
11.2. Game Bots
12. Security Considerations
13. IANA Considerations
14. Jabber Registrar Considerations
15. XML Schema
Notes
Revision History


1. Introduction

It is usual to play games over IM networks. Since Chess is a well known game, XMPP needs a protocol to support the game.

This document describes the protocol to play a chess match.

2. Requirements

This uses Game Sessions as the base of the protocol.

3. Discovering Support

An entity supporting this chess protocol MUST support Game Sessions. The discovery of the chess game support specifically is done trough Game Sessions game list. The namespace of the chess game is 'http://jabber.org/protocol/chess-game'. The discovery could look like this (expecting service discovery returned positively for game sessions):

Example 1. Chess game example

<iq from='romeo@montague.net/garden'
    to='juliet@capulet.com/balcony'
    type='get'
    id='game-list'>
  <list xmlns='http://jabber.org/protocol/games'/>
</iq>

<iq from='juliet@capulet.com/balcony'
    to='romeo@montague.net/garden'
    type='get'
    id='game-list'>
  <list xmlns='http://jabber.org/protocol/games'>
    <game-type type='http://jabber.org/protocol/chess-game'/>
  </list>
</iq>
    

If there already is a game ongoing, it MAY be listed as well, for spectators for example. As additional data, it MAY contain the game rules and optionally actual state as described bellow. It does not contain the peer player, since it would mean providing his JID to someone else without him knowing it.

4. Game Presence

The will to play chess game can be obtained as described in Game Sessions. TODO: Example, once this part of game sessions is finished.

5. Game Start

Game is initiated with an invitation. Then a game session is created, which starts the game. The game session MAY be created from a different resource than the one to which the invitation was sent. If the attempt to create the game session happens too late (for example, the sender of invitation starts playing with someone else), the sender client SHOULD deny the game session automatically.

5.1 The Invitation

The <invite/> element contain at last one element <rules/> qualified by 'http://jabber.org/protocol/chess-game' namespace. Each of them represents one set of rules and initial setup to which the initiator agrees to play with. The other side chooses one of them for the game session.

Each <rules/> element possesses these attributes:

Table 1: <rules/> attributes

Name Type Description
'initiator' REQUIRED Specifies if the initiator is "black" or "white".
'rules' REQUIRED Sets the game rules. The values are in the table below.
'limit-move' OPTIONAL If specified, contains number of seconds for each move. If a user does not move in the specified time, he lost. If the attribute is missing, no limit is set and the move can last indefinitelly.
'limit-game' OPTIONAL Similar to 'limit-move', but the time is for all the moves of one player.
'turn' OPTIONAL Overrides whose turn it is. If not specified, it is white's turn. Values "white" or "black".

Table 2: Values of 'rulest' attribute

Value Description
"default" Full chess rules, including en-passant, castling and promoting.
"simplified" Does not include en-passant and castling.
"beginner" Does not include en-passant, castling and promoting.
"none" Does not check any moves. Promoting, castling and en-passant is not possible.
"none-ext" Does not check any moves and makes promoting, castling and en-passant possible.

Initial layout MAY be specified in the <rules/> element. It is specified by a list of <piece/> elements, possessing these attributes:

Table 3: <piece/> attributes

Name Type Description
'color' REQUIRED The color of the piece, either "white" or "black".
'place' REQUIRED The field of the chessboard, for example "a8". Case insensitive.
'type' REQUIRED The type of the piece, one of "pawn", "bishop", "king", "knight", "queen" or "rook".
'state' OPTIONAL This can be specified to identify the state of the piece. With pawn, it can be "gone-2", which means en-passant can be done against this piece. If it is king or rook, they can be "unmoved", which means castling can be done with them.
With this specification, each side MUST have exactly one king and two pieces MUST NOT be on the same place.

Example 2. Romeo invites juliet

<message to='juliet@capulet.com/balcony'
    from='romeo@montague.net/garden'>
  <invite xmlns='http://jabber.org/protocol/games'
      type='http://jabber.org/protocol/chess-game'
      gid='chess-romeo@montague.net-juliet@capulet.com-76231494389'
      xmlns:chess='http://jabber.org/protocol/chess-game'>
    <chess:rules initiator='black'
        rules='default'/>
    <chess:rules initiator='black'
        turn='black'
        limit-game='600'
        rules='default'>
      <chess:piece type='king'
          place='a1'
          color='black'/>
      <chess:piece type='king'
          place='h3'
          color='white'/>
      <chess:piece type='rook'
          place='h4'
          color='white'/>
    </chess:rules>
  </invite>
</message>

    

5.2 Session Creation

If the other side wishes to engage in the game, it creates a game session. The game session contains exactly one <rules/> element specified in the invitation. By the successfull creation of the session, the game starts and (if not specified otherwise), the white moves.

The invitation validity is only for one attempt to create session.

Example 3. Juliet accepts the game and Romeo confirms

<iq type='set'
    from='juliet@capulet.com/room'
    to='romeo@montague.net/room'
    id='init'>
  <init xmlns='http://jabber.org/protocol/games'
      type='http://jabber.org/protocol/chess-game'
      xmlns:chess='http://jabber.org/protocol/chess-game'
      gid='chess-romeo@montague.net-juliet@capulet.com-76231494389'>
    <chess:rules initiator='black'
        turn='black'
        limit-game='600'
        rules='default'>
      <chess:piece type='king'
          place='a1'
          color='black'/>
      <chess:piece type='king'
          place='h3'
          color='white'/>
      <chess:piece type='rook'
          place='h4'
          color='white'/>
    </chess:rules>
  </init>
</iq>

<iq type='result'
    from='romeo@montague.net/room'
    to='juliet@capulet.com/room'
    id='init'>
  <init xmlns='http://jabber.org/protocol/games'
      sid='chess-romeo@montague.net-juliet@capulet.com-76231494389'/>
</iq>
    

6. Game Flow

During the game, players change in turn, each of them sending one move a time. Each move is represented as a <message/> stanza addressed to the full JID of the other player. The stanza contains exactly one <move/> element qualified by 'http://jabber.org/protocol/chess-game'. It possesses these attributes:

Table 4: <move/> attributes

Name Type Description
'from' REQUIRED The initial position of the piece, specified in the form of "b4".
'to' REQUIRED Destination position of the piece.
'sid' RECOMMENDED The session id to which this move belongs. It can be used to recognize more simultaneous games.
'promote' OPTIONAL Promotes the piece to the specified type. The value is one of "rook", "bishop", "knight" or "queen". Can not be used with rules "beginner" and "none".
'special' OPTIONAL Marks special move, either "castling", in which case the move is of the king and the rook jumps over, or "en-passant, in which case the move is to the destination place and the pawn behind this piece is removed.

Example 4. Part of the match between Romeo and Juliet

<message from='romeo@montague.net/room'
    to='juliet@capulet.com/room'>
  <move xmlns='http://jabber.org/protocol/chess-game'
      from='a1'
      to='a2'
      sid='chess-romeo@montague.net-juliet@capulet.com-76231494389'/>
</message>

<message from='juliet@capulet.com/room'
    to='romeo@montague.net/room'>
  <move xmlns='http://jabber.org/protocol/chess-game'
      from='h3'
      to='b4'
      sid='chess-romeo@montague.net-juliet@capulet.com-76231494389'/>
</message>
  

7. Game Termination

7.1 Explicit Termination

Game can be terminated explicitely by terminating the game session. The termination SHOULD contain <reason/> element, qualified by 'http://jabber.org/protocol/chess-game' namespace, describing the reason of disconnection.

Table 5: Possible Disconnection Reasons

Reason Description
give up The player surrenders.
cheating The player (or client by an automatic check) consideres the opponents move to be against rules.

Example 5. Romeo gives up

<message to='juliet@capulet.com/room'
    from='romeo@montague.net/room'>
  <term xlmlns='jabber.org/protocol/games'
      sid='chess-romeo@montague.net-juliet@capulet.com-76231494389'/>
    <reason>give up</reason>
  </term>
</message>
      

7.2 Match Termination

Game automatically terminates, when one of the players can not move, either he lost or it is a draw, lost his king (in the case when 'rules' are "none" or "none-ext") or when one of the player reaches a time limit. In such case, the game and the session is considered terminated implicitely.

7.3 Player Leaves

When <presence/> of 'type' "unavailable" is received from the opponent, the session is terminated implicitely and the game terminates with it.

8. Spectators

8.1 Spectator Initialization

Spectator MUST first discover the game using the Game List query. If the other side wants to publish the game to him, it includes the game in the returned list. It MAY provide rules and actual state of the game.

Once a spectable game is discovered by the Game List query, one can start spectator session to the specified game. In sucessfull response to the game creation, a <rules/> element is sent, containing actual board state, whose turn it is and rules in the same form as in the game start. The only difference in this <rules/> element is it does not possess 'initiator' attribute, but 'host' attribute, which specifies the color of player to which the spectator connects.

Spectator session MAY be created without invitation.

Example 6. Spectator Session Creation

<iq type='get'
    from='mercutio@montague.net/room'
    to='romeo@montague.net/room'
    id='game-list'>
  <list xmlns='http://jabber.org/protocol/games'/>
</iq>

<iq type='result'
    from='romeo@montague.net/room'
    to='mercutio@montague.net/room'
    id='game-list'>
  <list xmlns='http://jabber.org/protocol/games'>
    <game-type type='http://jabber.org/protocol/chess-game'>
      <game gid='chess-romeo@montague.net-juliet@capulet.com-76231494389'>
        <spectable/>
      </game>
    </game-type>
  </list>
</iq>

<iq type='set'
    from='mercutio@montague.net/room'
    to='romeo@montague.net/room'
    id='ss-init'>
  <init xmlns='http://jabber.org/protocol/games'
      type='http://jabber.org/protocol/chess-game'
      gid='chess-romeo@montague.net-juliet@capulet.com-76231494389'>
    <spectator/>
  </init>
</iq>

<iq type='result'
    from='romeo@montague.net/room'
    to='mercutio@montague.net/room'
    id='ss-init'>
  <init xmlns='http://jabber.org/protocol/games'
      sid='spect1'>
    <rules xmlns='http://jabber.org/protocol/games'
        host='black'
        turn='black'
        limit-game='600'
        rules='default'>
      <piece type='king'
          place='a1'
          color='black'/>
      <piece type='king'
          place='h3'
          color='white'/>
      <piece type='rook'
          place='h4'
          color='white'/>
    </rules>
  </init>
</iq>
    

8.2 Game Flow

The host (the player to which the spectator connected) echoes all the moves in the game to the spectator, using the same <move/> element as in usual game flow. The player whose move it is is not specified, as it can be deduced from the color of piece moved or from the number of moves since the beggining.

Example 7.

<message from='romeo@montague.net/room'
    to='mercutio@montague.net/room'>
  <move xmlns='http://jabber.org/protocol/chess-game'
      from='a1'
      to='a2'
      sid='chess-romeo@montague.net-juliet@capulet.com-76231494389'/>
</message>

<message from='romeo@montague.net/room'
    to='mercutio@montague.net/room'>
  <move xmlns='http://jabber.org/protocol/chess-game'
      from='h3'
      to='b4'
      sid='chess-romeo@montague.net-juliet@capulet.com-76231494389'/>
</message>
    

8.3 Spectator Termination

The spectator session can be terminated before the game itself terminates, by either of the sides. The session is terminated without any chess game specified data included (just game session termination withou additional XML data included).

If the game terminates before the spectator session is terminated, the host MUST terminate the session with <reason/> included. These are valid reasons:

If <presence/> of 'type' "unavailable" is received from the host, the session is terminated. This makes imaginatory reason host disconnected unnecessary.

9. Saving The Game

TODO once saving is defined in game sessions.

10. Game Forwarding

TODO once this is defined in game sessions.

11. Implementation Notes

11.1 Simplified Clients

It is possible to write a client that is spectator only, in which case it does not need to check rules and MUST NOT include chess game in the game list.

It is possible to write a client that does not support hosting spectators. In such case, it MUST NOT mark any of its games in the list as spectable.

11.2 Game Bots

This protocol allows of implementing an AI game bot. However, the AI of chess game is usually CPU consuming, so care should be taken to limit number of simultaneous games.

12. Security Considerations

Author is not aware of any security issues introduced by this protocol extension.

13. IANA Considerations

This JEP requires no interaction with the the Internet Assigned Numbers Authority (IANA) [1].

14. Jabber Registrar Considerations

The Jabber Registrar [2] shall include 'http://jabber.org/protocol/chess-game' in its registry of protocols.

15. XML Schema

TODO


Notes

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


Revision History

Version 0.0.2 (2006-09-14)

Modified to use Game Sessions for negotiation; moved to namespace on jabber.org.

(mv)

Version 0.0.1 (2006-08-23)

First draft.

(mv)


END