# Node.js Game Server Client SDK

> This is the Node.js 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   | GetGameServer       | ✔️          |
| Configuration   | WatchGameServer     | ✔️          |
| 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

- Node.js >= 10.13.0

## Usage

Add the agones dependency to your project:

```sh
npm install @google-cloud/agones-sdk
```

If you need to download the source, rather than install from NPM, you can find it on 

<a href="https://github.com/agones-dev/agones/blob/release-1.58.0/sdks/nodejs" target="_blank" data-proofer-ignore>GitHub</a>
.

To begin working with the SDK, create an instance of it.

```javascript
const AgonesSDK = require('@google-cloud/agones-sdk');

let agonesSDK = new AgonesSDK();
```

To connect to the SDK server, either local or when running on Agones, run the `async` method `sdk.connect()`, which will
`resolve` once connected or `reject` on error or if no connection can be made after 30 seconds.

```javascript
await agonesSDK.connect();
```

To send a [health check](/site/docs/guides/client-sdks/#health) ping call `health(errorCallback)`. The error callback is optional and if provided will receive an error whenever emitted from the health check stream.

```javascript
agonesSDK.health((error) => {
	console.error('error', error);
});
```

To mark the game server as [ready to receive player connections](/site/docs/guides/client-sdks/#ready), call the async method `ready()`. The result will be an empty object in this case.

```javascript
let result = await agonesSDK.ready();
```

Similarly `shutdown()`, `allocate()`, `setAnnotation(key, value)` and `setLabel(key, value)` are async methods that perform an action and return an empty result.

To get [details of the backing GameServer](/site/docs/guides/client-sdks/#gameserver) call the async method
`getGameServer()`. The result will be an object representing `GameServer` defined
in 
<a href="https://github.com/agones-dev/agones/blob/release-1.58.0/proto/sdk/sdk.proto" target="_blank" data-proofer-ignore>`sdk.proto`</a>
.

```javascript
let result = await agonesSDK.getGameServer();
```

To get [updates on the backing GameServer](/site/docs/guides/client-sdks/#watchgameserverfunctiongameserver) as they happen, call `watchGameServer(callback, errorCallback)`. The callback will be called with a parameter matching the result of `getGameServer()`. The error callback is optional and if provided will receive an error whenever emitted from the watch stream.

```javascript
agonesSDK.watchGameServer((result) => {
	console.log('watch', result);
}, (error) => {
	console.error('error', error);
});
```

To mark the game server as [reserved](/site/docs/guides/client-sdks/#reserveseconds) for a period of time, call the async method `reserve(seconds)`. The result will be an empty object.

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/nodejs/src/agonesSDK.js" target="_blank" data-proofer-ignore>agonesSDK.js</a>
 and also look at the 
<a href="https://github.com/agones-dev/agones/blob/release-1.58.0/examples/nodejs-simple" target="_blank" data-proofer-ignore>Node.js example</a>
.