Agones SDK for Godot

Welcome to the community-driven Agones SDK for Godot Engine.

Latest version is for Godot 4.2.

If you're using Godot < 4.2, please use Release 0.4.0

If you're using Godot <= 3.x, please use Release 0.3.0

Example

extends Node
var peer = null

func _ready():
  if "--server" in OS.get_cmdline_args() or OS.has_feature("Server"):
    host_server(DEFAULT_PORT, MAX_PEERS)

func host_server(port, max_peers):
  peer = NetworkedMultiplayerENet.new()
  peer.create_server(port, max_peers)
  get_tree().set_network_peer(peer)
  # Initialize AGONES SDK
  AgonesSDK.start()
  # Agones .Ready()
  AgonesSDK.ready()

func _process(delta):
  if peer:
    # Agones .Health()
    AgonesSDK.health()

What is Agones?

Agones is an open source, batteries-included, multiplayer dedicated game server scaling and orchestration platform that can run anywhere Kubernetes can run.

This plugin allows your Godot Scripts communicate with Agones by giving you simple GDScript functions. Internally it works by calling the REST API that comes with Agones Server.

Only GDScript is supported for now

Install

To install this plugin, go to Releases and download the latest version agones-sdk.zip.

If you are using Godot 3.x, please install Release 0.3.0

Inside your Godot Project folder, create a folder named addons and extract the zip file inside it.

After installed, your folder structure will look like this:

Getting Started

Activate the plugin

• Open your project in Godot Editor
• Go to Project > Project Settings... > Plugins
• You should see AgonesSDK Plugin. On the right side, check the "Enable" box

Use the SDK functions

You now have access to a singleton called AgonesSDK, which you can use to call SDK functions.

The SDK functions does the communication with Agones's sidecar server, which is a small server that goes with your Godot dedicated server inside the Agones Container.

If you want to test in local environment, check this page Local Development - Agones

Ready()

# Simple usage. Automatically retries 10 times and waits 2 seconds before trying again.
AgonesSDK.ready()

# Tries 30 times, waiting 5 seconds between each attempt.
AgonesSDK.ready(30, 5)

Health()

AgonesSDK.health()

Reserve()

# Reserves the server for 10 seconds
AgonesSDK.reserve(10)

# Reserves the server for 60 seconds
AgonesSDK.reserve(60)

Allocate()

AgonesSDK.allocate()

Shutdown()

AgonesSDK.shutdown()

GameServer()

# Get gameserver information
result = yield(AgonesSDK.gameserver(), "agones_response")

success = result[0]  # true if the request was successfull, false otherwise
requested_endpoint = result[1]  # the url requested
info_dict = result[2]  # the JSON body returned by agones sidecar

SetLabel(key, value)

# Set metadata label on agones sidecar servr
AgonesSDK.set_label('version', '1.0.0')

SetAnnotation(key, value)

# Set metadata annotation on agones sidecar servr
AgonesSDK.set_annotation('version', '1.0.0')

Player Tracking

As players connect and disconnect from your game, the Player Tracking functions enable you to track which players are currently connected.

Player connect

# Sets player 1337 as connected
AgonesSDK.player_connect(1337)

Player disconnect

# Unsets player 1337 online status
AgonesSDK.player_disconnect(1337)

Counters & Lists (Beta)

Counters and Lists let you track arbitrary numeric counters and string lists on your GameServer (player tracking, team slots, etc). These are Beta Agones features and require Agones 1.37+ (enabled by default since 1.45).

Like the rest of the SDK, every call is asynchronous and reports back through the agones_response(success, endpoint, content) signal. For reads, content is the returned Counter ({name, count, capacity}) or List ({name, capacity, values}).

Lists

# Add a value to a list (e.g. mark a player as connected)
AgonesSDK.append_list_value("players", "player-123")

# Remove a value from a list
AgonesSDK.delete_list_value("players", "player-123")

# Read a list
var result = await AgonesSDK.get_list("players")
# result[2] -> { "name": "players", "capacity": 64, "values": ["player-123"] }

# Set the maximum capacity of a list
AgonesSDK.set_list_capacity("players", 64)

add_list_value / remove_list_value are available as aliases matching the Agones REST endpoint names (:addValue / :removeValue).

Counters

# Increment / decrement a counter (defaults to 1)
AgonesSDK.increment_counter("rooms")
AgonesSDK.decrement_counter("rooms", 2)

# Set an absolute count or capacity
AgonesSDK.set_counter_count("rooms", 5)
AgonesSDK.set_counter_capacity("rooms", 10)

# Read a counter
var result = await AgonesSDK.get_counter("rooms")
# result[2] -> { "name": "rooms", "count": 5, "capacity": 10 }

Reference

See Agones - Client SDK

Contributing

Contributions are very welcome.

License

Distributed under the terms of the MIT license, "godot-agones-sdk" is free and open source software