remote-snake/doc/api.org

#+TITLE: Remote Snake API

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

* General Description
  - All transmissions will be based on UDP
  - All UDP packet will contain plain json data
* Communications 
** Initialisation
   1. Server wait for a client
   2. Client can send:
      #+BEGIN_SRC json
        {
            "type": "new-game"
        }
      #+END_SRC
   3. Server can reply:
      #+BEGIN_SRC json
        {
            "type": "state",
            "syn": 1,
            "game-id": 1,
            "game-over": false,
            "snake": [(1,2),(1,3)],
            "food": [(6,7)]
        }  
      #+END_SRC
      Note that, syn entry is used to keep packet ordering consistent and detecting packet inversion on the network. Thus,
      syn entry indicate the expected syn that the client should send on the next UDP packet.
** 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",
             "syn": 1,
             "game-id": 1,
             "direction": "left",
         }
       #+END_SRC
    2. Server can reply
       #+BEGIN_SRC json
         {
             "type": "state",
             "syn": 2,
             "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",
             "syn": 2,
             "game-id": 1,
             "direction": null
         }
       #+END_SRC
    2. Server can reply:
       #+BEGIN_SRC json
         {
             "type": "state",
             "syn": 3,
             "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",
             "syn": null,
             "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. Note that syn=null.