Skip to main content

​
Node.js SDK

The Node.js SDK provides integration for JavaScript and TypeScript game servers.

​
Installation

npm
npm install @google-cloud/agones-sdk
yarn
yarn add @google-cloud/agones-sdk

​
Quick Start

​
JavaScript

server.js
const AgonesSDK = require('@google-cloud/agones-sdk');

const agonesSDK = new AgonesSDK();

async function main() {
    try {
        // Connect to SDK server
        await agonesSDK.connect();
        console.log('Connected to Agones SDK');
        
        // Mark as ready
        await agonesSDK.ready();
        console.log('Server marked as Ready');
        
        // Start health checking
        setInterval(async () => {
            try {
                await agonesSDK.health();
            } catch (error) {
                console.error('Health check failed:', error);
            }
        }, 2000);
        
        // Get GameServer
        const gameServer = await agonesSDK.getGameServer();
        console.log(`GameServer name: ${gameServer.objectMeta.name}`);
        
        // Run your game server
        // ...
        
        // Shutdown
        await agonesSDK.shutdown();
    } catch (error) {
        console.error('Error:', error);
    }
}

main();

​
TypeScript

server.ts
import AgonesSDK from '@google-cloud/agones-sdk';

const agonesSDK = new AgonesSDK();

async function main(): Promise<void> {
    try {
        await agonesSDK.connect();
        await agonesSDK.ready();
        
        setInterval(async () => {
            await agonesSDK.health();
        }, 2000);
        
        const gameServer = await agonesSDK.getGameServer();
        console.log(`Server: ${gameServer.objectMeta?.name}`);
        
        // Game server logic
        // ...
        
        await agonesSDK.shutdown();
    } catch (error) {
        console.error('Error:', error);
    }
}

main();

​
SDK Reference

​
Connection

await agonesSDK.connect();
Connects to the SDK server sidecar.

​
Lifecycle Methods

await agonesSDK.ready();
await agonesSDK.shutdown();
await agonesSDK.allocate();
await agonesSDK.reserve(seconds);

​
Health Checking

await agonesSDK.health();

​
Metadata

await agonesSDK.setLabel(key, value);
await agonesSDK.setAnnotation(key, value);

​
State Monitoring

const gameServer = await agonesSDK.getGameServer();

agonesSDK.watchGameServer((gameServer) => {
    console.log('GameServer updated:', gameServer);
});

​
Alpha Features

​
Player Tracking

await agonesSDK.alpha.playerConnect(playerID);
await agonesSDK.alpha.playerDisconnect(playerID);
const connected = await agonesSDK.alpha.isPlayerConnected(playerID);
const players = await agonesSDK.alpha.getConnectedPlayers();
const count = await agonesSDK.alpha.getPlayerCount();
const capacity = await agonesSDK.alpha.getPlayerCapacity();
await agonesSDK.alpha.setPlayerCapacity(100);

​
Beta Features

​
Counters

const counter = await agonesSDK.beta.getCounter('sessions');
await agonesSDK.beta.updateCounter('sessions', { count: 5, capacity: 10 });

​
Lists

const list = await agonesSDK.beta.getList('players');
await agonesSDK.beta.addListValue('players', 'player-1');
await agonesSDK.beta.removeListValue('players', 'player-1');
await agonesSDK.beta.updateList('players', { values: ['p1', 'p2'], capacity: 100 });

​
Error Handling

All SDK methods return Promises. Use try-catch or .catch(): 
try {
    await agonesSDK.ready();
} catch (error) {
    console.error('Failed to mark ready:', error);
}

// Or
agonesSDK.ready()
    .then(() => console.log('Ready!'))
    .catch(error => console.error('Error:', error));

​
Best Practices

  • Always use await or .then() with SDK methods
  • Use setInterval for health checks, not recursive setTimeout
  • Clear intervals on shutdown
  • Handle connection errors gracefully

​
Example

See the nodejs-simple example for a complete implementation.

​
Next Steps

SDK Overview

Compare all available SDKs

API Reference

Complete SDK API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us