# Python Game Server Client SDK

> This is the Python version of the Agones Game Server Client SDK.

---

LLMS index: [llms.txt](/site/llms.txt)

---

Check the [Client SDK Documentation](/site/docs/guides/client-sdks/) for more details on each of the SDK functions and how to run the SDK locally.

## SDK Functionality

| Area            | Action              | Implemented |
|-----------------|---------------------|-------------|
| Lifecycle       | Ready               | ✔️          |
| Lifecycle       | Health              | ✔️          |
| Lifecycle       | Reserve             | ✔️          |
| Lifecycle       | Allocate            | ✔️          |
| Lifecycle       | Shutdown            | ✔️          |
| Configuration   | GameServer          | ✔️          |
| Configuration   | Watch               | ✔️          |
| Metadata        | SetAnnotation       | ✔️          |
| Metadata        | SetLabel            | ✔️          |
| Counters        | GetCounterCount     | ✔️          |
| Counters        | SetCounterCount     | ✔️          |
| Counters        | IncrementCounter    | ✔️          |
| Counters        | DecrementCounter    | ✔️          |
| Counters        | SetCounterCapacity  | ✔️          |
| Counters        | GetCounterCapacity  | ✔️          |
| Lists           | AppendListValue     | ✔️          |
| Lists           | DeleteListValue     | ✔️          |
| Lists           | SetListCapacity     | ✔️          |
| Lists           | GetListCapacity     | ✔️          |
| Lists           | ListContains        | ✔️          |
| Lists           | GetListLength       | ✔️          |
| Lists           | GetListValues       | ✔️          |
| Player Tracking | GetConnectedPlayers | ✔️          |
| Player Tracking | GetPlayerCapacity   | ✔️          |
| Player Tracking | GetPlayerCount      | ✔️          |
| Player Tracking | IsPlayerConnected   | ✔️          |
| Player Tracking | PlayerConnect       | ✔️          |
| Player Tracking | PlayerDisconnect    | ✔️          |
| Player Tracking | SetPlayerCapacity   | ✔️          |

## Prerequisites

- [Python >= 3.10](https://www.python.org/downloads/)

## Installation

Install from source, 
<a href="https://github.com/agones-dev/agones/blob/release-1.58.0/sdks/python" target="_blank" data-proofer-ignore>directly from GitHub</a>


## Usage

To begin working with the SDK, create an instance and connect to the sidecar.

```python
from agones import AgonesSDK

sdk = AgonesSDK()
sdk.connect()
```

A context manager is also supported:

```python
with AgonesSDK() as sdk:
    sdk.ready()
    # game logic
```

To send a [health check](/site/docs/guides/client-sdks/#health) ping, call `sdk.health()`. This should be called periodically in a background thread.

```python
import threading
import time

def health_loop():
    while True:
        sdk.health()
        time.sleep(2)

threading.Thread(target=health_loop, daemon=True).start()
```

To mark the [game session as ready](/site/docs/guides/client-sdks/#ready) call `sdk.ready()`.

```python
sdk.ready()
```

To mark that the [game session is completed](/site/docs/guides/client-sdks/#shutdown) and the game server should be shut down call `sdk.shutdown()`.

```python
sdk.shutdown()
```

To mark the game server as [reserved](/site/docs/guides/client-sdks/#reserveseconds) for a period of time, call `sdk.reserve(seconds)`.

```python
sdk.reserve(30)
```

To [set a Label](/site/docs/guides/client-sdks/#setlabelkey-value) on the backing `GameServer` call `sdk.set_label(key, value)`.

```python
sdk.set_label("test-label", "test-value")
```

To [set an Annotation](/site/docs/guides/client-sdks/#setannotationkey-value) on the backing `GameServer` call `sdk.set_annotation(key, value)`.

```python
sdk.set_annotation("test-annotation", "test value")
```

To get [details of the backing `GameServer`](/site/docs/guides/client-sdks/#gameserver) call `sdk.get_game_server()`.

```python
gameserver = sdk.get_game_server()
print(f"Name: {gameserver.object_meta.name}")
print(f"State: {gameserver.status.state}")
```

To get [updates on the backing `GameServer`](/site/docs/guides/client-sdks/#watchgameserverfunctiongameserver) as they happen, call `sdk.watch_game_server(callback)`.

This will watch for updates in a background daemon thread and call the provided callback on each update.

```python
def on_update(gameserver):
    print(f"GameServer update, state: {gameserver.status.state}")

sdk.watch_game_server(on_update)
```

For more information, please read the [SDK Overview](/site/docs/guides/client-sdks/), check out 
<a href="https://github.com/agones-dev/agones/blob/release-1.58.0/sdks/python/agones/sdk.py" target="_blank" data-proofer-ignore>the Python SDK implementation</a>
.