Changes in proto for Player Tracking design update

This includes changes to make PlayerID consistent in casing.

Code generation will come in the next PR to make things easier to
review.

Work on #1033

proto/sdk/alpha/alpha.proto

@@ -21,44 +21,96 @@ import "google/api/annotations.proto";
 
 // SDK service to be used in the GameServer SDK to the Pod Sidecar.
 service SDK {
-    // Call when a player has connected.
-    rpc PlayerConnect (PlayerId) returns (Empty) {
+    // PlayerConnect increases the SDK’s stored player count by one, and appends this playerID to GameServer.Status.Players.IDs.
+    //
+    // GameServer.Status.Players.Count and GameServer.Status.Players.IDs are then set to update the player count and id list a second from now,
+    // unless there is already an update pending, in which case the update joins that batch operation.
+    //
+    // PlayerConnect returns true and adds the playerID to the list of playerIDs if this playerID was not already in the
+    // list of connected playerIDs.
+    //
+    // If the playerID exists within the list of connected playerIDs, PlayerConnect will return false, and the list of
+    // connected playerIDs will be left unchanged.
+    //
+    // An error will be returned if the playerID was not already in the list of connected playerIDs but the player capacity for
+    // the server has been reached. The playerID will not be added to the list of playerIDs.
+    //
+    // Warning: Do not use this method if you are manually managing GameServer.Status.Players.IDs and GameServer.Status.Players.Count
+    // through the Kubernetes API, as indeterminate results will occur.
+    rpc PlayerConnect (PlayerID) returns (Bool) {
         option (google.api.http) = {
             post: "/alpha/player/connect"
             body: "*"
         };
     }
 
-    // Call when a player has disconnected.
-    rpc PlayerDisconnect (PlayerId) returns (Empty) {
+    // Decreases the SDK’s stored player count by one, and removes the playerID from GameServer.Status.Players.IDs.
+    //
+    // GameServer.Status.Players.Count and GameServer.Status.Players.IDs are then set to update the player count and id list a second from now,
+    // unless there is already an update pending, in which case the update joins that batch operation.
+    //
+    // PlayerDisconnect will return true and remove the supplied playerID from the list of connected playerIDs if the
+    // playerID value exists within the list.
+    //
+    // If the playerID was not in the list of connected playerIDs, the call will return false, and the connected playerID list
+    // will be left unchanged.
+    //
+    // Warning: Do not use this method if you are manually managing GameServer.status.players.IDs and GameServer.status.players.Count
+    // through the Kubernetes API, as indeterminate results will occur.
+    rpc PlayerDisconnect (PlayerID) returns (Bool) {
         option (google.api.http) = {
             post: "/alpha/player/disconnect"
             body: "*"
         };
     }
 
-    // Change the player capacity to a new value.
+    // Update the GameServer.Status.Players.Capacity value with a new capacity.
     rpc SetPlayerCapacity (Count) returns (Empty) {
         option (google.api.http) = {
-            post: "/alpha/player/capacity"
+            put: "/alpha/player/capacity"
             body: "*"
         };
     }
 
-    // Get the last player capacity that was set through the SDK.
-    // If the player capacity is set from outside the SDK, use SDK.GameServer() instead.
-    rpc GetPlayerCapacity(Empty) returns (Count) {
+    // Retrieves the current player capacity. This is always accurate from what has been set through this SDK,
+    // even if the value has yet to be updated on the GameServer status resource.
+    //
+    // If GameServer.Status.Players.Capacity is set manually through the Kubernetes API, use SDK.GameServer() or SDK.WatchGameServer() instead to view this value.
+    rpc GetPlayerCapacity (Empty) returns (Count) {
         option (google.api.http) = {
             get: "/alpha/player/capacity"
         };
     }
 
-    // get the current player count
-    rpc GetPlayerCount(Empty) returns (Count) {
+    // Retrieves the current player count. This is always accurate from what has been set through this SDK,
+    // even if the value has yet to be updated on the GameServer status resource.
+    //
+    // If GameServer.Status.Players.Count is set manually through the Kubernetes API, use SDK.GameServer() or SDK.WatchGameServer() instead to view this value.
+    rpc GetPlayerCount (Empty) returns (Count) {
         option (google.api.http) = {
             get: "/alpha/player/count"
         };
     }
+
+    // Returns if the playerID is currently connected to the GameServer. This is always accurate from what has been set through this SDK,
+    // even if the value has yet to be updated on the GameServer status resource.
+    //
+    // If GameServer.Status.Players.IDs is set manually through the Kubernetes API, use SDK.GameServer() or SDK.WatchGameServer() instead to determine connected status.
+    rpc IsPlayerConnected (PlayerID) returns (Bool) {
+        option (google.api.http) = {
+            get: "/alpha/player/connected/{playerID}"
+        };
+    }
+
+    // Returns the list of the currently connected player ids. This is always accurate from what has been set through this SDK,
+    // even if the value has yet to be updated on the GameServer status resource.
+    //
+    // If GameServer.Status.Players.IDs is set manually through the Kubernetes API, use SDK.GameServer() or SDK.WatchGameServer() instead to view this value.
+    rpc GetConnectedPlayers(Empty) returns (PlayerIDList) {
+        option (google.api.http) = {
+            get: "/alpha/player/connected"
+        };
+    }
 }
 
 // I am Empty
@@ -70,7 +122,17 @@ message Count {
     int64 count = 1;
 }
 
+// Store a boolean result
+message Bool {
+    bool bool = 1;
+}
+
 // The unique identifier for a given player.
-message PlayerId {
-    string playerId = 1;
+message PlayerID {
+    string playerID = 1;
+}
+
+// List of Player IDs
+message PlayerIDList {
+    repeated string list = 1;
 }

proto/sdk/sdk.proto

@@ -148,6 +148,7 @@ message GameServer {
         message PlayerStatus {
             int64 count = 1;
             int64 capacity = 2;
+            repeated string IDs = 3;
         }
 
         string state = 1;