diff --git a/proto/sdk/alpha/alpha.proto b/proto/sdk/alpha/alpha.proto index 0f7f69c116..b9f2bb6524 100644 --- a/proto/sdk/alpha/alpha.proto +++ b/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; } \ No newline at end of file diff --git a/proto/sdk/sdk.proto b/proto/sdk/sdk.proto index ba7d5b3030..2cbef579fb 100644 --- a/proto/sdk/sdk.proto +++ b/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;