git ssb


happy0 / ssb-chess


Gordon Martin authored Merge pull request #85 from Happy0/rematch_fromLatest: 585763c on 3/3/2019, 4:33:44 PM


A library for building chess clients for the scuttlebutt platform. This library is intended to make it easier to build your own ssb-chess client, bot or tool.

For an example of a scuttlebutt chess client built using this library see ssb-chess-mithril.

Required scuttlebot plugins


Note: since this is built on a peer 2 peer protocol, messages may be corrupted or deliberately misleading to cheat. ssb-chess doesn't validate that the client agrees a post is valid yet as it assumes your friends can be trusted.

The documentation below documents the 'content' section of the scuttlebutt messages. The 'author' field of the outer object containing the content field is the ID of person who posted the message (made the chess move, posted the chat message, invited another player to a game, etc.)

For example, the entire scuttlebutt message for a move could look like this:

  "key": "%mbTncS4L6NkmWbUu28SYFR+gkS+EBXtv69qw1Nys+GA=.sha256",
  "value": {
    "previous": "%tAgOzYHfdUDjTCtL/WPdBFikGpi7FF1y5yluIa0L70c=.sha256",
    "author": "@RJ09Kfs3neEZPrbpbWVDxkN92x9moe3aPusOMOc4S2I=.ed25519",
    "sequence": 2467,
    "timestamp": 1512721788946,
    "hash": "sha256",
    "content": {
      "type": "chess_move",
      "ply": 35,
      "root": "%GplJjfQtF931QBN/QLb5Dbkkn7p6vPDa6GlArwx7lXs=.sha256",
      "orig": "d6",
      "dest": "e7",
      "pgnMove": "dxe7",
      "fen": "r1b2rk1/pp1pPppp/6q1/8/2Pp1B2/1Q1P2P1/PP4BP/R3R1K1 b - - 0 18",
      "branch": "%FvjrSmC/02bneFhr1/xZz9K5HQezQBTI4nEyG3rQ7FM=.sha256"
    "signature": "0SpisCR/celfcZsc9Bc0Ikq/12bAp2B3sNh5q0lPqTB1JsMT56rtVzxq75ly1eE3+bp+vj+XfZ262wDCNLjhDw==.sig.ed25519"
  "timestamp": 1513461650805.013

Send an Invitation to Play

Type chess_invite


  "type": "chess_invite",
  "inviting": "@RJ09Kfs3neEZPrbpbWVDxkN92x9moe3aPusOMOc4S2I=.ed25519",
  "myColor": "black",
  "branch": [

The key of the message inviting a player to play then becomes the game ID which subsequent messages link back to.

Accept an Invitation to Accept

Type chess_invite_accept


      "type": "chess_invite_accept",
      "root": "%JJis5OErved3kJu2q9tpPyd+hjFq4EnqHUusy6LJ+OE=.sha256",
      "branch": "%JJis5OErved3kJu2q9tpPyd+hjFq4EnqHUusy6LJ+OE=.sha256"

A player may accept an invite they have received by sending a message of type chess_invite_accept linking back to the key of the original game invitation message.

The game is then 'in progress.'

A chess move

Type chess_move


  "type": "chess_move",
  "ply": 26,
  "root": "%WbzP0UxevK8j4g6CdLmgFnsjblnW0EVp/u6phVD5Y/4=.sha256",
  "branch": "%FvjrSmC/02bneFhr1/xZz9K5HQezQBTI4nEyG3rQ7FM=.sha256",
  "orig": "b2",
  "dest": "c1",
  "pgnMove": "bxc1=B",
  "fen": "r2qkbnr/p3pppp/3p4/6B1/4P3/5Q2/b2N1PPP/2b1KB1R w kq - 0 14",
  "promotion": "b"

Game end

Type chess_game_end


Note: The client should work out the winner for display based on who posted the message. For resign messages, the opposite player is the winner. For 'mate' messages, the player authoring the message is the winner and for a draw there are no winners.

 "type": "ssb_chess_game_end",
  "status": "mate",
  "ply": 20,
  "fen": "rnb2rk1/ppp2ppp/3p4/4p1qK/2P1n3/8/P2P1PPP/RNB2BNR w - - 2 11",
  "root": "%HGPn7yS2bjpWZndXtuusOjGXrirIIGu0XS18aY8YoFM=.sha256",
  "branch": "%FvjrSmC/02bneFhr1/xZz9K5HQezQBTI4nEyG3rQ7FM=.sha256",
  "orig": "f6",
  "dest": "g5",
  "pgnMove": "Qg5#"

Chess Chat

Type ssb_chess_chat

Note: If this is a private message between the two players in the game, the content of the message is encrypted using sbot.private.publish with an array of the IDs of the players of the game as the recipients parameter.

If it is not a private message, it is a public message in the observer chat between spectators of the game. This shouldn't be displayed to the two players playing (or only displayed after the game has finished) so that the game isn't interfered with. Obviously a player could look at the raw feed to see what other people are saying about the game, but it's better to not make the chat easily visible.


  msg: "Chat testarooni"
  root: "%YQktCnxwY0rQyljO6BLrD7AQwRpf13HzbsVAZV19vlo=.sha256"
  type: "chess_chat"

Chess logic library

Built with git-ssb-web