Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Player Tracking: REST SDK Reference #1570

Merged
merged 2 commits into from
May 19, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
199 changes: 161 additions & 38 deletions site/content/en/docs/Guides/Client SDKs/rest.md
Original file line number Diff line number Diff line change
Expand Up @@ -38,70 +38,84 @@ You can read more about OpenAPI/Swagger code generation in their [Command Line T

## Reference

### Ready
### Lifecycle Management

#### Ready

Call when the GameServer is ready to accept connections

- Path: `/ready`
- Method: `POST`
- Body: `{}`

#### Example
##### Example

```bash
$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/ready
```

### Health
#### Health
Send a Empty every d Duration to declare that this GameServer is healthy

- Path: `/health`
- Method: `POST`
- Body: `{}`

#### Example
##### Example

```bash
$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/health
```

### Shutdown
#### Reserve

Call when the GameServer session is over and it's time to shut down
Move Gameserver into a Reserved state for a certain amount of seconds for the future allocation.

- Path: `/shutdown`
- Path: `/reserve`
- Method: `POST`
- Body: `{}`
- Body: `{"seconds": "5"}`

#### Example
##### Example

```bash
$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/shutdown
$ curl -d '{"seconds": "5"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/reserve
```

### Set Label
#### Allocate

Apply a Label with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata.
With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as `Allocated`.
For those scenarios, this SDK functionality exists.

See the SDK [SetLabel]({{< ref "/docs/Guides/Client SDKs/_index.md#setlabel-key-value" >}}) documentation for restrictions.
{{< alert title="Note" color="info">}}
Using a [GameServerAllocation]({{< ref "/docs/Reference/gameserverallocation.md" >}}) is preferred in all other scenarios,
as it gives Agones control over how packed `GameServers` are scheduled within a cluster, whereas with `Allocate()` you
relinquish control to an external service which likely doesn't have as much information as Agones.
{{< /alert >}}

#### Example
##### Example

```bash
$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/label
$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/allocate
```

### Set Annotation
#### Shutdown

Call when the GameServer session is over and it's time to shut down

Apply a Annotation with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata
- Path: `/shutdown`
- Method: `POST`
- Body: `{}`

#### Example
##### Example

```bash
$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/annotation
$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/shutdown
```

### GameServer
### Configuration Retrieval


#### GameServer

Call when you want to retrieve the backing `GameServer` configuration details

Expand Down Expand Up @@ -142,7 +156,7 @@ Response:
}
```

### Watch GameServer
#### Watch GameServer

Call this when you want to get updates of when the backing `GameServer` configuration is updated.

Expand All @@ -160,34 +174,143 @@ Response:
{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}
{"result":{"object_meta":{"name":"local","namespace":"default","uid":"1234","resource_version":"v1","generation":"1","creation_timestamp":"1533766607","annotations":{"annotation":"true"},"labels":{"islocal":"true"}},"status":{"state":"Ready","address":"127.0.0.1","ports":[{"name":"default","port":7777}]}}}
```
### Metadata Management

### Reserve
#### Set Label

Move Gameserver into a Reserved state for a certain amount of seconds for the future allocation.
Apply a Label with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata.

- Path: `/reserve`
- Method: `POST`
- Body: `{"seconds": "5"}`
See the SDK [SetLabel]({{< ref "/docs/Guides/Client SDKs/_index.md#setlabel-key-value" >}}) documentation for restrictions.

#### Example
##### Example

```bash
$ curl -d '{"seconds": "5"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/reserve
$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/label
```

### Allocate
#### Set Annotation

With some matchmakers and game matching strategies, it can be important for game servers to mark themselves as `Allocated`.
For those scenarios, this SDK functionality exists.
Apply an Annotation with the prefix "agones.dev/sdk-" to the backing `GameServer` metadata

{{< alert title="Note" color="info">}}
Using a [GameServerAllocation]({{< ref "/docs/Reference/gameserverallocation.md" >}}) is preferred in all other scenarios,
as it gives Agones control over how packed `GameServers` are scheduled within a cluster, whereas with `Allocate()` you
relinquish control to an external service which likely doesn't have as much information as Agones.
{{< /alert >}}
##### Example

```bash
$ curl -d '{"key": "foo", "value": "bar"}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/metadata/annotation
```

{{% feature publishVersion="1.6.0" %}}
### Player Tracking

{{< alpha title="Player Tracking" gate="PlayerTracking" >}}

#### Example
#### Alpha: PlayerConnect

This function increases the SDK’s stored player count by one, and appends this playerID to
`GameServer.Status.Players.IDs`.

##### Example

```bash
$ curl -d "{}" -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/allocate
$ curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connect
```

Response:
```json
{"bool":true}
```

#### Alpha: PlayerDisconnect

This function decreases the SDK’s stored player count by one, and removes the playerID from
[`GameServer.Status.Players.IDs`][playerstatus].

##### Example

```bash
$ curl -d '{"playerID": "uzh7i"}' -H "Content-Type: application/json" -X POST http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/disconnect
```

Response:
```json
{"bool":true}
```

#### Alpha: SetPlayerCapacity

Update the [`GameServer.Status.Players.Capacity`][playerstatus] value with a new capacity.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It might be worth clarifying that this capacity is not enforced as that is not a responsibility of Agones

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a good idea, I'm going to tackle this in #1569 , since it doesn't seem REST API specific.


##### Example

```bash
$ curl -d '{"count": 5}' -H "Content-Type: application/json" -X PUT http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity
```

#### Alpha: GetPlayerCapacity

This function 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.

##### Example

```bash
$ curl -d '{}' -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/capacity
```

Response:
```json
{"count":"5"}
```

#### Alpha: GetPlayerCount

This function 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.

```bash
$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/count
```

Response:
```json
{"count":"2"}
```

##### Example

#### Alpha: IsPlayerConnected

This function 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.

##### Example

```bash
$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected/uzh7i
```

Response:
```json
{"bool":true}
```

#### Alpha: GetConnectedPlayers

This function 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.

##### Example

```bash
$ curl -H "Content-Type: application/json" -X GET http://localhost:${AGONES_SDK_HTTP_PORT}/alpha/player/connected
```

Response:
```json
{"list":["uzh7i","3zh7i"]}
```

[playerstatus]: {{< ref "/docs/Reference/agones_crd_api_reference.html#PlayerStatus" >}}

{{% /feature %}}