Document player-info, player-enter, and player-update events

[lmno-api] / empires.txt

diff --git a/empires.txt b/empires.txt
index da590a3039521c24196acbc02840b3bd1d3d28c7..fef6a08fbfaaa25da34ec4355b2b0a31a294ee0d 100644 (file)
--- a/empires.txt
+++ b/empires.txt
@@ -1,6 +1,6 @@
 Empires Game Protocol
 =====================
-Version: 0.7
+Version: 0.9
 
 For a specific game the following API endpoints are defined.
 (Note: Only the trailing portion of the API URI is provided here.
@@ -49,35 +49,35 @@ For a specific game the following API endpoints are defined.
                event: player-leave
                data: {"id":3}
 
-       TYPE: game-state
+       TYPE: game-phase
 
-       WHEN: When client first connects and whenever game state changes
+       WHEN: When client first connects and whenever game phase changes
 
-       VALUES: Event gives both the old and new state.
+       VALUES: Event gives both the old and new phase.
                Each will be one of the following:
 
-               none: Pseudo-state used as old_state when game is started
+               none: Pseudo-phase used as old_phase when game is started
                join: Players are choosing characters and joining the game
                 reveal: Character names are being revealed to players
                 capture: Players are guessing characters in capture attempts
 
        NOTE: When a client first connects, it may see multiple
-             game-state transitions, to transition step-by-step from
-             the initial state to the state of the current game. See
+             game-phase transitions, to transition step-by-step from
+             the initial phase to the phase of the current game. See
              the example below which would be presented to a client
-             joining a game that is already in the "reveal state.
+             joining a game that is already in the "reveal phase.
 
        EXAMPLES:
 
-               event: game-state
-                data: {"old_state":"none","new_state":"join"}
+               event: game-phase
+                data: {"old_phase":"none","new_phase":"join"}
 
-               event: game-state
-                data: {"old_state":"join","new_state":"reveal"}
+               event: game-phase
+                data: {"old_phase":"join","new_phase":"reveal"}
 
        TYPE: character-reveal
 
-       WHEN: Periodically during the "reveal" state of the game
+       WHEN: Periodically during the "reveal" phase of the game
 
        EXAMPLE:
 
@@ -99,7 +99,7 @@ For a specific game the following API endpoints are defined.
 
     Behavior: Adds a new player with "name" and "character" and
     assigns an id. Also will add a new empire with empty "captured"
-    array.
+    array. Returns the numeric ID of the new player.
 
     Note: If the client supports cookies and has previously set a
     nickname in the current session via the upper-level /profile API,
@@ -108,6 +108,8 @@ For a specific game the following API endpoints are defined.
 
     Example data: { "name": "Carl", "character: "Elvis" }
 
+    Example return data: 2
+
 /deregister/<ID>
 
     Method: POST
@@ -140,17 +142,17 @@ For a specific game the following API endpoints are defined.
 
     Method: POST
 
-    When: Only valid when in game state of JOIN
+    When: Only valid when in game phase of JOIN
 
-    Behavior: Change state to REVEAL; reveal character names to all clienta
+    Behavior: Change phase to REVEAL; reveal character names to all clienta
 
 /start
 
     Method: POST
 
-    When: Only valid when in game state of REVEAL
+    When: Only valid when in game phase of REVEAL
 
-    Behavior: Change game state to CAPTURE
+    Behavior: Change game phase to CAPTURE
 
 /reset