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

[empires-api] / empires.txt

diff --git a/empires.txt b/empires.txt
index 42d4f0ee459dbecc99f313da8557fbf522f8a826..fef6a08fbfaaa25da34ec4355b2b0a31a294ee0d 100644 (file)
--- a/empires.txt
+++ b/empires.txt
@@ -1,6 +1,6 @@
 Empires Game Protocol
 =====================
-Version: 0.6
+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,27 +108,51 @@ For a specific game the following API endpoints are defined.
 
     Example data: { "name": "Carl", "character: "Elvis" }
 
+    Example return data: 2
+
 /deregister/<ID>
 
     Method: POST
 
     Behavior: Removes an existing player with the given ID
 
+/spectator
+
+    Method: POST
+
+    Behavior: Add a new spectator with the given name, assigning and
+    returning an ID for the spectator.
+
+    Note: If the client supports cookies and has previously set a
+    nickname in the current session via the upper-level /profile API,
+    then the name can be omitted from the data here and the profile
+    nickname will be used instead.
+
+    Example data: { "name": "Carl" }
+
+    Example return data: 23
+
+/spectator/<ID>
+
+    Method: DELETE
+
+    Behavior: Remove an existing spectator with the given ID
+
 /reveal
 
     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
 
@@ -177,12 +201,30 @@ For a specific game the following API endpoints are defined.
                    { "id": 5, "captures": [] },
                    { "id": 6, "captures": [] } ]
 
+/spectators
+
+    Method: GET
+
+    Behavior: Gets a list of all spectators. A spectator is someone
+    who has started viewing the game (and stated their own
+    name) but isn't directly involved in the game.
+
+    Example data: [ { id: 1, name: "Richard"}, { id: 2, name: "Nancy"} ]
+
+    Note: The IDs of spectators and players are unrelated. If a person
+    initially joins as a spectator and then later joins the game as a
+    player, an unrelated player ID will be generated. From the
+    server's point of view, the events of a spectator leaving and a
+    player joining that happens to have the same name---those two
+    events have nothing to do with each other.
+
 /players
 
     Method: GET
 
     Behavior: Gets a list of all the player objects (without their
-    character names)
+    character names). A player is someone who is registered a
+    character choice to participate in the game.
 
     Example data: [ { id: 1, name: "Carl" }, { id: 2, name: "Kevin" } ]