Godot Encore

Appearance

Installation ​

This page covers how to install the Godot SDK from source and what to import in your game code.

Install from source ​

Option 1: Copy the SDK folder ​

Copy the repository sdk/ directory into your Godot project as:

  • res://addons/encore/

Expected structure:

  • res://addons/encore/client/encore_client.gd
  • res://addons/encore/client/encore_config.gd
  • res://addons/encore/client/error.gd
  • res://addons/encore/client/http_transport.gd
bash
cd your-godot-project
git submodule add https://github.com/godot-encore/encore.git addons/encore

This keeps the SDK source tracked and makes updates explicit.

Export your Linux headless server build ​

Before using the SDK in production, export your Godot server build for Linux headless/dedicated usage.

This gives you the server binary artifact that Encore Server will launch from your template binary_path.

What to import in your scripts ​

At minimum, preload these two classes:

gdscript
const EncoreClient = preload("res://addons/encore/client/encore_client.gd")
const EncoreConfig = preload("res://addons/encore/client/encore_config.gd")

If you handle typed errors in signal callbacks, also preload:

gdscript
const EncoreError = preload("res://addons/encore/client/error.gd")

Class roles:

  • EncoreClient: main async API (create/get/join helpers)
  • EncoreConfig: server URL + timeout + debug config
  • EncoreError: typed error object received from failure signals

Minimal setup ​

gdscript
extends Node

const EncoreClient = preload("res://addons/encore/client/encore_client.gd")
const EncoreConfig = preload("res://addons/encore/client/encore_config.gd")

var encore_client: EncoreClient

func _ready():
    var config = EncoreConfig.new("http://localhost:8080")
    config.debug = true

    encore_client = EncoreClient.new(config)
    add_child(encore_client)

Important:

  • Add the client as a node (add_child(encore_client)), since it uses Godot HTTP node behavior internally.
  • Use your real Encore Server URL in production (not localhost).

Configuration options ​

EncoreConfig supports:

  • base_url (default: http://localhost:8080)
  • timeout_seconds (default: 30.0)
  • debug (default: false)

Alternative constructor:

gdscript
var config = EncoreConfig.create(
    "https://encore.example.com",
    60.0
)

Receiving the server bind port in Godot ​

When Encore Server starts a game instance, it injects the allocated port through command arguments from your template.

Template example:

toml
[template]
name = "Quick Match - Deathmatch"
id = "game_QkMtDm7A2x"
binary_path = "/opt/gameservers/arena/server.x86_64"

args = ["--headless", "--", "--port={{port}}"]

In your Godot dedicated server code, read --port and bind your server to that value.

Simple example:

gdscript
const DEFAULT_PORT := 7777

func get_port_from_args(default_port: int = DEFAULT_PORT) -> int:
    var args := OS.get_cmdline_user_args()

    for i in range(args.size()):
        if args[i].begins_with("--port="):
            return _safe_port(args[i].substr("--port=".length()), default_port)
        if args[i] == "--port" and i + 1 < args.size():
            return _safe_port(args[i + 1], default_port)

    return default_port

func _safe_port(raw: String, default_port: int) -> int:
    var p := int(raw)
    if p < 1 or p > 65535:
        push_warning("Invalid port '%s', using %d" % [raw, default_port])
        return default_port
    return p

Use the returned port when starting ENet/UDP/TCP server listeners.

SDK result contract ​

SDK methods use empty values to indicate failure:

  • dictionary-returning methods -> {}
  • array-returning methods -> []
  • string-returning helpers -> ""

Always check for empty results before reading fields.

Next step ​

Continue with How to Use for concrete host/join and error-handling flows.