Complete reference for the SpawnWeaver Godot SDK (v1.0.0). The entire client API lives on the SpawnWeaver autoload; every request method is awaitable and returns an SWResult. Guides: Rooms, State sync, Events, Storage.

The SpawnWeaver autoload

Properties

Constants

Lifecycle

configure(project_key: String, server_url: String = "") -> void

Sets credentials in code instead of using res://spawnweaver.cfg. Call before start(). server_url is optional (defaults to production).

SpawnWeaver.configure("pk_your_key", "ws://127.0.0.1:5159/connect")

start() -> SWResult

Connects using the configured project key. Resolves once the session is welcomed (value: your SWPlayer) or the first connection attempt fails. After a successful start, the SDK auto-reconnects forever until stop(). Calling start() while already online resolves immediately; while connecting, it awaits the in-flight attempt.

var result := await SpawnWeaver.start()
if not result.ok:
    show_error(result.error.message)   # e.g. code "not-configured", "connect-failed"

stop() -> void

Disconnects and stops auto-reconnect. In-flight requests fail with code stopped; room_left("left") fires if you were in a room. Safe to call at any time.

is_online() -> bool

true when status == Status.ONLINE.

set_display_name(display_name: String) -> void

Sets the name other players see. Applied on your next create/join/match.

set_debug_enabled(enabled: bool) -> void

Toggles SDK console logging of every message and error.

Rooms

`create_room(options: Dictionary =

Creates a room and puts you in it as host. Value: the SWRoom (result.room).

var result := await SpawnWeaver.create_room({"visibility": "public", "max_players": 4})
if result.ok:
    print(result.room.code)

Errors: already-in-room, not-connected.

join_room(code: String) -> SWResult

Joins by share code, or by a public room's id from list_rooms() (strings starting with room_/match_ are treated as ids). Value: the SWRoom.

var result := await SpawnWeaver.join_room("4V8772")

Errors: room-not-found, room-full, already-in-room, not-connected.

leave_room() -> SWResult

Leaves your current room. Value: null. Fires room_left("left") on success. Errors: not-in-room, not-connected.

list_rooms(limit: int = 20) -> SWResult

Lists joinable public rooms of your project, most recently active first. Value: Array of SWRoomSummary (result.rooms).

var result := await SpawnWeaver.list_rooms()
for summary in result.rooms:
    print(summary.code, " ", summary.player_count)

update_room(changes: Dictionary) -> SWResult

Host only. Updates room attributes; only provided fields change, but metadata replaces the whole map. Accepts the same keys as create_room options. Value: the updated SWRoom. All members receive room_updated.

Errors: not-host, not-in-room.

Matchmaking

`find_match(mode: String = "default", options: Dictionary =

Queues for a match and resolves when one is found (value: the SWRoom), the server times the ticket out, or you cancel. Options: region (String, default "global"), size (int, default 2, range 2–64). A second call replaces the first ticket.

var result := await SpawnWeaver.find_match("duel", {"region": "eu"})
if result.ok:
    start_game(result.room)
elif result.error.code == "match-timeout":
    offer_retry()

Errors: match-timeout (retryable), cancelled, already-in-room, invalid-payload (bad size, or | in mode/region), not-connected. Client-side await ceiling: 120 s.

cancel_matchmaking() -> SWResult

Cancels matchmaking: any awaited find_match() resolves with code cancelled, and the server-side ticket is removed. Value: {"hadTicket": bool}.

Events

`send_event(event_name: String, data: Dictionary =

Fire-and-forget relay to the other members of your room (you never receive your own event). Not awaitable; failures arrive on the error signal. Queued automatically while reconnecting (up to 128 messages) and flushed on resume; dropped with a warning when fully offline.

SpawnWeaver.send_event("fired", {"dir": [0, 1]})

State sync

All four calls resolve with value: the confirmed change payload (a raw Dictionary — e.g. {roomId, entityId, ownerId, patch, state}); the matching signal (room_state_changed / entity_changed / entity_removed) fires for everyone, including you. Patches are shallow merges; a null value removes the key.

set_room_state(patch: Dictionary) -> SWResult

Host only: patches the room-level shared state.

await SpawnWeaver.set_room_state({"phase": "combat", "old_key": null})

Errors: not-host, not-in-room, state-too-large, rate-limited.

set_entity(entity_id: String, data: Dictionary) -> SWResult

Creates or replaces an entity you own. Errors: not-in-room, state-forbidden (someone else owns it), state-limit-exceeded, state-too-large, rate-limited.

patch_entity(entity_id: String, patch: Dictionary) -> SWResult

Patches an entity you own. Errors: as set_entity, plus entity-not-found.

delete_entity(entity_id: String) -> SWResult

Deletes an entity you own. Everyone receives entity_removed(id, "deleted"). Errors: entity-not-found, state-forbidden, not-in-room.

Player storage

storage_get(key: String) -> SWResult

Value: the stored Variant, or null when the key was never set.

storage_set(key: String, value: Variant) -> SWResult

Persists any JSON-serializable Variant. Survives restarts. Value: null. Errors: storage-invalid-key, storage-value-too-large, storage-quota-exceeded.

storage_delete(key: String) -> SWResult

Value: bool — true when the key existed.

storage_list(prefix: String = "") -> SWResult

Value: Array[String] of this player's keys, optionally filtered by prefix.

await SpawnWeaver.storage_set("save", {"level": 3})
var save := await SpawnWeaver.storage_get("save")        # save.value == {"level": 3}
var keys := await SpawnWeaver.storage_list()             # keys.value == ["save"]
var gone := await SpawnWeaver.storage_delete("save")     # gone.value == true

Leaderboards

Project-scoped ranked score boards (guide). A board springs into existence on first submit; a player holds at most one entry per board. Board names match ^[a-z0-9_.\-]{1,64}$.

leaderboard_submit(board: String, score: int, mode: String = "max") -> SWResult

Submits a score. mode: "max" (default — keep the higher score), "min" (keep the lower; ranks read ascending), "latest" (always overwrite). Value: {best, rank, updated} — updated is false when the submit didn't beat your stored score.

var result := await SpawnWeaver.leaderboard_submit("highscore", 4200)
if result.ok:
    print("rank #", result.value["rank"])

Errors: leaderboard-invalid-board, leaderboard-invalid-score, not-connected.

leaderboard_top(board: String, limit: int = 10) -> SWResult

The board's best entries, best first. limit 1–100. Value: Array[SWLeaderboardEntry]. Errors: leaderboard-invalid-board, not-connected.

leaderboard_around(board: String, entry_range: int = 5) -> SWResult

Your entry ± entry_range neighbors (1–50). Value: {entries: Array[SWLeaderboardEntry], player_rank: int, total: int} — player_rank is -1 when you have no entry (the top of the board is returned instead). Errors: leaderboard-invalid-board, not-connected.

Diagnostics

get_ping_ms() -> float

The heartbeat round-trip latency (same as latency_ms).

create_debug_report() -> Dictionary

A diagnostic snapshot: SDK/engine versions, status, server URL, player/room ids, latency, reconnect attempts, and ring buffers of the last 50 messages and 10 errors.

create_debug_report_string() -> String

The report as pretty-printed JSON — paste into the dashboard's Debug Bundle viewer.

simulate_connection_loss() -> void

Testing helper: drops the socket so auto-reconnect and room resume run exactly as after a real network blip.

Signals

Broadcasts only — request outcomes come back via await, never signals.

Models

SWResult

The outcome of every awaited call.

SWError

SWPlayer

SWRoom

SWLeaderboardEntry

One row from leaderboard_top() / leaderboard_around().

SWRoomSummary

One entry from list_rooms().

Nodes

LobbyBrowser

A complete lobby UI with zero code (extends Control): player name field, Create room, Quick match, join by code, and a live public-room list. Built from standard Controls, so your project Theme restyles it. Connect entered_room and switch to your game scene — that's the whole integration.

SpawnSync

Drop-in network sync for a Node2D or Node3D — add as a child of the node to replicate. Local copies send (dirty-checked, at send_rate); remote copies interpolate. Re-registers after reconnects/room changes; deletes its entity on exit.

Method: set_local(local: bool) — switches the controlling client and (re)registers (called by PlayerSpawner when spawning).

State keys sent: 2D — x, y, rot, sx, sy; 3D — x, y, z, rx, ry, rz, sx, sy, sz; plus each synced_properties name verbatim.

PlayerSpawner

Spawns one instance of your player scene per player in the room; despawns on leave; survives reconnects (idempotent reconcile); auto-wires any SpawnSync inside the scene (entity id + local authority) before it enters the tree.

Optional hook on the player scene's root script, called right before add_child:

func setup(player: SWPlayer, is_local: bool) -> void:
    pass

Error codes

SDK-local codes (raised without a server round-trip)

Server codes

Limits and remedies: Limits. Wire-level details: Protocol reference.