diff --git a/build/includes/website.mk b/build/includes/website.mk index 6673ab4c16..3e3df44ae5 100644 --- a/build/includes/website.mk +++ b/build/includes/website.mk @@ -80,7 +80,8 @@ site-images: ${site_path}/static/diagrams/system-diagram.dot.png site-images: $(site_path)/static/diagrams/gameserver-lifecycle.puml.png site-images: $(site_path)/static/diagrams/gameserver-reserved.puml.png site-images: $(site_path)/static/diagrams/canary-testing.puml.png -site-images: $(site_path)/static/diagrams/allocation-player-capacity.puml.png +site-images: $(site_path)/static/diagrams/allocation-player-capacity-tracking.puml.png +site-images: $(site_path)/static/diagrams/allocation-player-capacity-list.puml.png site-images: $(site_path)/static/diagrams/reusing-gameservers.puml.png site-images: $(site_path)/static/diagrams/high-density.puml.png diff --git a/site/content/en/docs/Integration Patterns/player-capacity.md b/site/content/en/docs/Integration Patterns/player-capacity.md index 59588e76ff..fd4c181c9a 100644 --- a/site/content/en/docs/Integration Patterns/player-capacity.md +++ b/site/content/en/docs/Integration Patterns/player-capacity.md @@ -7,31 +7,63 @@ description: > Find a `GameServer` that has room for a specific number of players. --- +Using this approach, we are able to be able to make an Allocation request that is akin to: "Find me a `GameServer` +that is already allocated, with room for _n_ number of players, and if one is not available, allocate me a `Ready` +`GameServer`". + +Common applications of this type of allocation are Lobby servers where players await matchmaking, or a +persistent world server where players connect and disconnect from a large map. + {{% pageinfo color="info" %}} -[Counters and Lists]({{< ref "/docs/Guides/counters-and-lists.md" >}}) will eventually replace the Beta functionality +[Counters and Lists]({{< ref "/docs/Guides/counters-and-lists.md" >}}) will eventually replace the Alpha functionality of Player Tracking, which will subsequently be removed from Agones. -If you are currently using this Beta feature, we would love for you to test (and ideally migrate to!) this new +If you are currently using this Alpha feature, we would love for you to test (and ideally migrate to!) this new functionality to Counters and Lists to ensure it meet all your needs. - -This document will be updated to utilise Counters and Lists in the near future. {{% /pageinfo %}} +## Tracking Players Through Lists + +{{< beta title="Counters And Lists" gate="CountsAndLists" >}} + + +Player Capacity Allocation Diagram + + +### Example `GameServerAllocation` + +The below allocation will attempt to find an already Allocated `GameServer` from the `Fleet` "simple-game-server" with +room for at least 10, and if it cannot find one, will allocate a Ready one from the same `Fleet`. + +```yaml +apiVersion: allocation.agones.dev/v1 +kind: GameServerAllocation +spec: + selectors: + - matchLabels: + agones.dev/fleet: simple-game-server + gameServerState: Allocated # check for Allocated first + lists: + players: + minAvailable: 10 # at least 10 players in available capacity + - matchLabels: + agones.dev/fleet: simple-game-server + lists: + players: + minAvailable: 10 # not required, since our GameServers start with empty lists, but a good practice +``` + +## Player Tracking + {{< alpha title="Player Tracking and Allocation Player Filter" gate="PlayerTracking,PlayerAllocationFilter" >}} -Using this approach, we are able to be able to make a request that is akin to: "Find me a `GameServer` that is already -allocated, with room for _n_ number of players, and if one is not available, allocate me a `Ready` `GameServer`". - -Common applications of this type of allocation are Lobby servers where players await matchmaking, or a -persistent world server where players connect and disconnect from a large map. - - -Player Capacity Allocation Diagram + +Player Capacity Allocation Diagram -## Example `GameServerAllocation` +### Example `GameServerAllocation` The below allocation will attempt to find an already Allocated `GameServer` from the `Fleet` "lobby" with room for 10 to 15 players, and if it cannot find one, will allocate a Ready one from the same `Fleet`. @@ -51,11 +83,13 @@ spec: agones.dev/fleet: lobby ``` -{{< alert title="Note" color="info">}} -We recommend doing an extra check when players connect to a `GameServer` that there is the expected player capacity -on the `GameServer` as there can be a small delay between a player connecting and it being reported -to Agones. -{{< /alert >}} +## Consistency + +Agones, and Kubernetes itself are built as eventually consistent, self-healing systems. To that end, it is worth +noting that there may be minor delays between each of the operations in either of the above flows. For example, +depending on the cluster load, it may take approximately a second for an SDK driven +[list change]({{% ref "/docs/Guides/Client SDKs/_index.md#counters-and-lists" %}}) on a `GameServer` record to be visible to the Agones +allocation system. We recommend building your integrations with Agones with this in mind. ## Next Steps diff --git a/site/static/diagrams/allocation-player-capacity-list.puml b/site/static/diagrams/allocation-player-capacity-list.puml new file mode 100644 index 0000000000..d47a09cfef --- /dev/null +++ b/site/static/diagrams/allocation-player-capacity-list.puml @@ -0,0 +1,117 @@ +@startuml +/' +Copyright 2024 Google LLC All Rights Reserved. + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. +'/ + +'https://plantuml.com/sequence-diagram + +actor "Player One" as Player1 +actor "Player Two" as Player2 +participant Matchmaker +participant Agones +participant "GameServer\nResource" as GameServer +box "Game Server Pod" + participant "Game Server\nProcess" as Binary + participant SDK +end box + +activate GameServer + +== GameServer Start == + +Agones -> GameServer: GameServer created through\na Fleet configuration +note left +Fleet configuration includes a players List with an initial empty value +and a capacity set to the total number of players that be can be hosted on a GameServer. +end note +activate GameServer +GameServer -> Binary: Agones creates a Pod with the\nconfigured Game Server Container +activate Binary +activate SDK +Binary -> SDK: SDK.WatchGameServer() +note right +Use the SDK Watch function +to watch and react to allocation +and List mutation events +end note + +Binary -> SDK: SDK.Ready() +note right + Call Ready() when the + Game Server can take player + connections and is able to + be allocated. +end note +GameServer <-- SDK: Update to Ready State + +== No allocated GameServers == + +Player1 -> Matchmaker: Requests a game session +Matchmaker -> Agones: Create: GameServerAllocation +note left + The GameServerAllocation is implemented to + optionally select an already allocated GameServer + with an available capacity under List players + of 1. If one cannot be found, allocate a Ready + GameServer instead. + + Since at this stage there are no Allocated GameServer + Agones will allocate a Ready GameServer. +end note +Agones -> GameServer: Finds a Ready GameServer,\nsets it to Allocated State +Matchmaker <-- Agones : GameServerAllocation is returned\nwith GameServer details\nincluding IP and port to connect to. +Player1 <-- Matchmaker : Returns GameServer connection information +Player1 -> Binary : Connects to game server process +Binary -> SDK : SDK.Beta().AppendListValue("players", id) +note left + Process calls AppendListValue(...) + on player client connection. +end note +GameServer <-- SDK : Appends id to status.lists["players"].values + +== Allocated GameServers with player(s) on them == + +Player2 -> Matchmaker: Requests a game session +Matchmaker -> Agones: Create: GameServerAllocation +note left + The GameServerAllocation will this time find the + Allocated GameServer with the players List + with available capacity, indicating it has room for + more players. +end note +Agones -> GameServer: Finds the Allocated GameServer where\nlength(status["players"].values) < status["rooms"].capacity. +note right + This is the same GameServer that "Player One" + is currently playing on. +end note +Matchmaker <-- Agones: returns Allocated GameServer record +Player2 <-- Matchmaker : Returns GameServer connection information +Player2 -> Binary : Connects to game server process +Binary -> SDK : SDK.Beta().AppendListValue("players", id) +GameServer <-- SDK : Appends id to status.lists["players"].values + +alt Player disconnects + Binary -> SDK: SDK.Beta().DeleteListValue("players", id) + SDK --> GameServer: Removes id from status.lists["players"].values +end alt +note right + When a player disconnects, + remove their id from the "players" List, + to increase the available capacity + on this GameServer. +end note + + +@enduml diff --git a/site/static/diagrams/allocation-player-capacity-list.puml.png b/site/static/diagrams/allocation-player-capacity-list.puml.png new file mode 100644 index 0000000000..9dc0739256 Binary files /dev/null and b/site/static/diagrams/allocation-player-capacity-list.puml.png differ diff --git a/site/static/diagrams/allocation-player-capacity.puml b/site/static/diagrams/allocation-player-capacity-tracking.puml similarity index 100% rename from site/static/diagrams/allocation-player-capacity.puml rename to site/static/diagrams/allocation-player-capacity-tracking.puml diff --git a/site/static/diagrams/allocation-player-capacity.puml.png b/site/static/diagrams/allocation-player-capacity-tracking.puml.png similarity index 100% rename from site/static/diagrams/allocation-player-capacity.puml.png rename to site/static/diagrams/allocation-player-capacity-tracking.puml.png