Changes in proto for Player Tracking design update (#1481)

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;