diff --git a/build/includes/website.mk b/build/includes/website.mk index 1aacc67c31..cdec6c4397 100644 --- a/build/includes/website.mk +++ b/build/includes/website.mk @@ -78,6 +78,7 @@ site-images: $(site_path)/static/diagrams/gameserver-states.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 # generate pngs from dot files %.dot.png: %.dot diff --git a/site/content/en/docs/Integration Patterns/player-capacity.md b/site/content/en/docs/Integration Patterns/player-capacity.md new file mode 100644 index 0000000000..9a4a07588c --- /dev/null +++ b/site/content/en/docs/Integration Patterns/player-capacity.md @@ -0,0 +1,56 @@ +--- +title: "Allocating based on GameServer Player Capacity" +linkTitle: "Player Capacity" +date: 2021-08-31 +weight: 90 +description: > + Find a `GameServer` that has room for a specific number of players. +--- + +{{< alpha + title="Player Tracking, Allocation Player Filter, and Allocation State Filter" + gate="PlayerTracking,PlayerAllocationFilter,StateAllocationFilter" >}} + +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 + + +## 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`. + +```yaml +apiVersion: "allocation.agones.dev/v1" +kind: GameServerAllocation +spec: + preferred: + - gameServerState: Allocated + matchLabels: + agones.dev/fleet: lobby + players: + minAvailable: 10 + maxAvailable: 15 + required: + matchLabels: + 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 >}} + +## Next Steps + +- Have a look at all commands the [Client SDK]({{< ref "/docs/Guides/Client SDKs/_index.md" >}}) provides. +- Check all the options available on [`GameServerAllocation`]({{% ref "/docs/Reference/gameserverallocation.md" %}}). +- If you aren't familiar with the term [Pod](https://kubernetes.io/docs/concepts/workloads/pods/pod/), this should + provide a reference. diff --git a/site/layouts/shortcodes/alpha.html b/site/layouts/shortcodes/alpha.html index dd1e435bdb..aecdb0dd11 100644 --- a/site/layouts/shortcodes/alpha.html +++ b/site/layouts/shortcodes/alpha.html @@ -1,9 +1,17 @@ -{{- $gate := .Get "gate" }} +{{- $gate := split (.Get "gate") "," }} +{{- $len_gate := len $gate }} {{- $title := .Get "title" }} diff --git a/site/static/diagrams/allocation-player-capacity.puml b/site/static/diagrams/allocation-player-capacity.puml new file mode 100644 index 0000000000..e22b8539f5 --- /dev/null +++ b/site/static/diagrams/allocation-player-capacity.puml @@ -0,0 +1,57 @@ +@startuml +'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 + +== No allocated GameServers == + +Player1 -> Matchmaker: Requests a game session +Matchmaker -> Agones: Create: GameServerAllocation +note left + GameServerAllocation implemented to + optionally select an already allocated GameServer + if one exists. At this stage, one does not, so + 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.Alpha.PlayerConnect(id) +note right + Process calls PlayerConnect(...) + on player client connection. +end note +GameServer <-- SDK : Increments Status.Players.Count\nand add id to Status.Players.Ids + +== 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 that "Player One" + is currently active on. +end note +Agones -> GameServer: Finds the Allocated GameServer\nwith player 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.Alpha.PlayerConnect(id) +GameServer <-- SDK : Increments Status.Players.Count\nand add id to Status.Players.Ids + +@enduml diff --git a/site/static/diagrams/allocation-player-capacity.puml.png b/site/static/diagrams/allocation-player-capacity.puml.png new file mode 100644 index 0000000000..5242c560f8 Binary files /dev/null and b/site/static/diagrams/allocation-player-capacity.puml.png differ