Docs: Player Capacity Integration Pattern

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

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.
+
+<a href="../../../diagrams/allocation-player-capacity.puml.png" target="_blank">
+<img src="../../../diagrams/allocation-player-capacity.puml.png" alt="Player Capacity Allocation Diagram" />
+</a>
+
+## 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.

site/layouts/shortcodes/alpha.html

@@ -1,9 +1,17 @@
-{{- $gate := .Get "gate" }}
+{{- $gate := split (.Get "gate") "," }}
+{{- $len_gate := len $gate }}
 {{- $title := .Get "title" }}
 <div class="alert alert-warning" role="alert">
     <h4 class="alert-heading">Warning</h4>
-    <p>The {{ $title }} feature is currently <strong><a href="{{ ref . "/docs/Guides/feature-stages.md#alpha" }}">Alpha</a></strong>,
+    <p>The {{ $title }} {{ if gt $len_gate 1 }}features are{{ else }}feature is{{ end }} currently <strong><a href="{{ ref . "/docs/Guides/feature-stages.md#alpha" }}">Alpha</a></strong>,
         not enabled by default, and may change in the future.</p>
-    <p>Use the Feature Gate <code>{{- $gate }}</code> to enable and test this feature.</p>
+    <p>Use the Feature
+        {{ if gt $len_gate 1 }}Gates{{else}}Gate{{ end }}
+        {{- range $index, $value := first (sub $len_gate 1) $gate }} <code>{{ $value }}</code>, {{- end}}
+        {{ if gt $len_gate 1 }}and{{ end }}
+        {{ range (last 1 $gate) }}
+        <code>{{ . }}</code>
+        {{ end }}
+        to enable and test {{ if gt $len_gate 1 }}these features{{else}}this feature{{ end }}.</p>
     <p>See the <a href="{{ ref . "/docs/Guides/feature-stages.md#feature-gates" }}">Feature Gate documentation</a> for details on how to enable features.</p>
 </div>

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 <i>GameServers</i> ==
+
+Player1 -> Matchmaker: Requests a game session
+Matchmaker -> Agones: Create: <i>GameServerAllocation</i>
+note left
+  <i>GameServerAllocation</i> implemented to
+  optionally select an already allocated <i>GameServer</i>
+  if one exists. At this stage, one does not, so
+  Agones will allocate a <i>Ready</i> <i>GameServer</i>.
+end note
+Agones -> GameServer: Finds a <i>Ready</i> <i>GameServer</i>,\nsets it to <i>Allocated</i> State
+Matchmaker <-- Agones : <i>GameServerAllocation</i> is returned\nwith <i>GameServer</i> details\nincluding IP and port to connect to.
+Player1 <-- Matchmaker : Returns <i>GameServer</i> connection information
+Player1 -> Binary : Connects to game server process
+Binary -> SDK : SDK.Alpha.PlayerConnect(id)
+note right
+  Process calls <i>PlayerConnect(...)</i>
+  on player client connection.
+end note
+GameServer <-- SDK : Increments <i>Status.Players.Count</i>\nand add <i>id</i> to <i>Status.Players.Ids</i>
+
+== Allocated <i>GameServers</i> with player(s) on them ==
+
+Player2 -> Matchmaker: Requests a game session
+Matchmaker -> Agones: Create: <i>GameServerAllocation</i>
+note left
+  The <i>GameServerAllocation</i> will this time
+  find the Allocated <i>GameServer</i> that "Player One"
+  is currently active on.
+end note
+Agones -> GameServer: Finds the Allocated <i>GameServer</i>\nwith player capacity.
+note right
+  This is the same <i>GameServer</i> that "Player One"
+  is currently playing on.
+end note
+Matchmaker <-- Agones: returns <i>Allocated GameServer</i> record
+Player2 <-- Matchmaker : Returns <i>GameServer</i> connection information
+Player2 -> Binary : Connects to game server process
+Binary -> SDK : SDK.Alpha.PlayerConnect(id)
+GameServer <-- SDK : Increments <i>Status.Players.Count</i>\nand add <i>id</i> to <i>Status.Players.Ids</i>
+
+@enduml