remote-snake/doc/api.org

#+TITLE: Remote Snake API

#+OPTIONS: toc:nil
#+LATEX_HEADER: \usepackage{fullpage}

* General Description
  - All transmissions will be based on TCP since:
    - Packet length are not fixed (large variance depending on the snake size and food)
    - Packet ordering is important (inverted request can compromise gameplay)
  - All TCP streams from *client to server* will:
    - Contain _plain json data_
    - Be terminated by an "#EOF" line (in order for the server to detect the end of the client request)
  - All TCP stream from *server to client* will contains _plain json data_ (connection will be closed by the server
    so, there is no need of "#EOF").
* Communications 
** Initialisation
   1. Client sent:
      #+BEGIN_SRC json
        {
            "type": "new-game"
        }
        #EOF
      #+END_SRC
   2. Server can reply:
      #+BEGIN_SRC json
        {
            "type": "state",
            "game-id": 1,
            "game-over": false,
            "snake": [[1,2],[1,3]],
            "food": [[6,7]]
        }  
      #+END_SRC
** Gameplay
*** Change Direction
    1. When client is playing a game, it can ask the server to change snake direction:
       #+BEGIN_SRC json
         {
             "type": "update",
             "game-id": 1,
             "direction": "left",
         }
         #EOF
       #+END_SRC
    2. Then, server can reply:
       #+BEGIN_SRC json
         {
             "type": "state",
             "game-id": 1,
             "game-over": false,
             "snake": [[0,2],[1,2]],
             "food": [[6,7]]
         }  
       #+END_SRC
*** Refresh Screen
    1. When no key are pressed (the snake is simply going forward). So, client can send:
       #+BEGIN_SRC json
         {
             "type": "update",
             "game-id": 1,
             "direction": null
         }
         #EOF
       #+END_SRC
    2. Server can reply:
       #+BEGIN_SRC json
         {
             "type": "state",
             "game-id": 1,
             "game-over": false,
             "snake": [[1,2],[0,2]],
             "food": [[6,7]]
         }  
       #+END_SRC
*** End Game
    - When game is over, server will send the following state message (switch "game-over" to true):
       #+BEGIN_SRC json
         {
             "type": "state",
             "game-id": 1,
             "game-over": true,
             "snake": [[0,2],[1,2]],
             "food": [[6,7]]
         }  
       #+END_SRC
    - No reply is expected from the client and server will be in charge to free local memory.