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 because:
    - Packet length are not fixed
    - Packet ordering is important
  - All TCP stream from *client to server* will:
    - Contain plain json data
    - Be terminated by a "#EOF" line (in order for the server to detect the end of the request
  - All TCP stream from *server to client* will contains plai json data (connection will be closed by the server
    so there is no need of "#EOF".
* Communications 
** Initialisation
   1. Server wait for a client
   2. Client can send:
      #+BEGIN_SRC json
        {
            "type": "new-game"
        }
        #EOF
      #+END_SRC
   3. 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 to the server to change snake direction:
       #+BEGIN_SRC json
         {
             "type": "update",
             "game-id": 1,
             "direction": "left",
         }
         #EOF
       #+END_SRC
    2. 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 press (the snake is simply going straigth 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.