Client API Reference¶
The runtime addon ships two public classes under addons/signal_fish/:
SignalFishClient(Node): typed connect, authenticate, join, send, leave, and reconnect API. One snake_case signal per server event.SignalFishConfig(Resource): a configuration resource you can author in the editor or build in code.
Configuration fields¶
| Group | Field | Notes |
|---|---|---|
| Identity | app_id |
Required public identifier. |
| Identity | sdk_version |
Optional SDK version string. |
| Identity | platform |
Optional platform string. |
| Transport | endpoint_url |
Optional override; connect_to_server(url) also takes one. |
| Transport | auto_poll |
Default true; runs poll() from _process. |
| Game data | game_data_format |
"" (JSON), json, message_pack, or the opaque rkyv/protobuf pass-through encodings (v3-only; fall back to JSON when unadvertised or when the server negotiates v2). |
| Game data | decode_msgpack_payloads |
Default false. Opt-in MessagePack decode. |
| Limits | max_inbound_frame_bytes |
Frames over this are dropped (~256 KiB default). |
| Limits | max_buffered_bytes |
Send backpressure threshold (~256 KiB default). |
| Limits | max_outbound_frame_bytes |
One outbound text/binary frame over this is refused locally (64 KiB default, the upstream server default). |
| Limits | max_inbound_packets_per_poll |
Default 64; overflow moves to the next tick. |
| Reconnect | reconnect_max_attempts |
Default 5. Budget for auto-reconnect. |
| Heartbeat | heartbeat_interval_sec |
Default 0 (off). Seconds between automatic Pings while connected + authenticated. |
| Heartbeat | pong_timeout_sec |
Default 10. A silent link past this is torn down as a failure - while a dial or close handshake pends, during authentication where pings are not allowed, after a heartbeat ping, or after a mid-session authentication error - so auto-reconnect can engage. The dial, authentication, post-error, close, and reconnect room-response deadlines run even with the heartbeat off. The room-response deadline starts after authentication; incoming Pong replies leave it unchanged. A beat refused by backpressure arms the same deadline; the beat retries each interval and the deadline clears once a Pong lands. |
| v3 session plan | protocol_version |
Set to 3 to opt in to the v3 surface. |
| v3 session plan | supported_transports |
Capability list. |
| v3 session plan | supported_topologies |
Capability list. |
| v3 session plan | requested_capabilities |
Capability list. |
| Credential | credential |
Code only. Rides Authenticate as connect_token. |
Heartbeat needs the tree
Like the auto-reconnect backoff, the heartbeat runs from _process:
keep the client node in the scene tree (or drive the ticks yourself)
when you enable it.
v3 fields are additive
The v3 session-plan fields are omitted when unset, so v2 wire bytes stay identical to a plain v2 client.
credential is set in code only. It is never exported, persisted, or
serialized by the Resource pipeline, and the logger redacts it.
join_room() takes a SignalFishClient.JoinRoomParams object with the
fields game_name, player_name, room_code, max_players,
supports_authority, relay_transport, password, and join_only.
Set join_only = true with a room code from a room list or invite. A missing
room returns ROOM_NOT_FOUND. This requires server v0.10.0 or later.
Server v0.9.1 ignores join_only and may create a room for an unknown code.
Leave join_only unset or set it to false to allow room creation.
Lifecycle and state¶
func configure(config: SignalFishConfig) -> Error
func connect_to_server(url := "") -> Error # auto-sends Authenticate on open
func reconnect(player_id: String, room_id: String, auth_token: String) -> Error
func set_auto_reconnect(enabled: bool) -> void # default OFF
func poll() -> void
func close(code := 1000, reason := "") -> Error
func is_connected_to_server() -> bool
func is_authenticated() -> bool
func get_connection_state() -> ConnectionState # DISCONNECTED/CONNECTING/CONNECTED/CLOSING/CLOSED/FAILED
func get_session_state() -> SessionState # UNAUTHENTICATED/.../IN_ROOM_*/SPECTATING
func get_player_id() -> String
func get_room_id() -> String
func get_room_code() -> String
func get_lobby_state() -> int # SFTypes.LobbyState
func get_players() -> Array # Array[SFTypes.PlayerInfo]
func get_authority_player() -> String # "" while nobody holds authority
func get_spectators() -> Array # Array[SFTypes.SpectatorInfo]
func get_buffered_amount() -> int
Cached player readiness and authority flags update before their lobby and authority signals. Earlier roster snapshots keep their previous values.
Cached rosters (players, spectators) and mesh peers stay capped at 256
entries (SFTypeUtils.MAX_TRACKED_PEERS). Excess entries from a hostile
or misbehaving relay are dropped: rosters surface one protocol_error
per event, and the mesh logs an error. The session stays live.
Send methods¶
Each method returns Error. The 12 v2 client messages map to these
methods; Authenticate is sent automatically when the socket opens.
send_signal and send_transport_status are the v3 additions.
send_game_data_binary rides the negotiated binary-frame route.
func join_room(params: JoinRoomParams) -> Error
func leave_room() -> Error
func send_game_data(data) -> Error
func send_game_data_binary(bytes: PackedByteArray) -> Error
func set_ready() -> Error
func start_game() -> Error
func request_authority(become_authority: bool) -> Error
func provide_connection_info(info: SFTypes.ConnectionInfo) -> Error
func ping() -> Error
func join_as_spectator(game_name: String, room_code: String, spectator_name: String, password := "") -> Error
func leave_spectator() -> Error
func send_signal(to_peer: String, generation: String, signal_payload) -> Error
func send_transport_status(transport_kind: int, is_up: bool) -> Error
Room commands require an authenticated session. Sending one before
authentication emits protocol_error, returns ERR_UNAUTHORIZED, and
sends nothing.
While SPECTATING, player commands (leave_room, game-data sends, ready,
start, authority, connection info, signaling, and transport reports) return
ERR_UNAUTHORIZED with protocol_error and send nothing. Use
leave_spectator to end viewing. Ping and join requests stay available.
send_signal and send_transport_status also require a negotiated v3
connection. send_signal further requires the latest session_plan:
the generation must equal the current plan's. No signal can be sent
before a plan arrives, after the room or dial ends, or after a fresh
baseline until the next plan. Each refusal emits protocol_error,
returns an Error, and sends nothing - a dropped frame would only
surface as a generic server error while the peer waits.
Live spectators¶
On protocol v3, check info.capabilities.has("spectator_relay") in your
protocol_info handler before enabling live viewing. Older servers still
support spectator snapshots. A successful join or v3 negotiation alone
does not prove live delivery. Protocol v2 needs a verified server build or
deployment contract; otherwise live support is unknown.
The server change is server PR #1139.
After spectator_joined, public room events update the cached roster,
lobby, and authority before their signals run. game_starting preserves
the spectator role. Spectators receive relayed JSON and negotiated binary
game data through the usual signals, with no session_plan required.
MessagePack decode selects game_data_received; raw MessagePack and opaque
v3 rkyv/protobuf use game_data_binary_received. JSON negotiation uses
text GameData frames. Joining as a spectator clears any previous player ID
and mesh.
Games must relay their viewing state to spectators. Direct and WebRTC traffic is not mirrored. A late join supplies room metadata; the game must send its own application snapshot. Spectators have no seated reconnect token: join again after a lost connection. Live fixed-server acceptance covers delivery classes, leave/rejoin races and reconnect roster recovery. See the testing guide for qualified builds and commands.
State machines¶
enum ConnectionState { DISCONNECTED, CONNECTING, CONNECTED, CLOSING, CLOSED, FAILED }
enum SessionState { UNAUTHENTICATED, AUTHENTICATING, AUTHENTICATED, IN_ROOM_WAITING, IN_ROOM_LOBBY, IN_ROOM_FINALIZED, SPECTATING }
Lobby transitions are server-driven. The client never self-promotes its session state.
Behavior notes¶
- Sends are backpressured. Over
max_buffered_bytes, a send returnsERR_BUSY, emitsprotocol_error, and queues nothing. - A full native WebSocket send queue returns
ERR_BUSYwithout a protocol error. Keep polling and retry the same message after capacity becomes available. The connection stays open and the refused message is never queued. A frame that exceeds the engine'soutbound_buffer_sizereturnsERR_INVALID_DATAwithprotocol_error. Reduce the frame before retrying. - Frames over
max_inbound_frame_bytesare dropped withprotocol_error. - One outbound text/binary frame over
max_outbound_frame_bytesis refused withprotocol_errorandERR_INVALID_DATA, and nothing is queued. The default matches the upstream server's default inbound cap (64 KiB): the server drops an oversized text frame asMessageTooLargeand the action is lost; a binary frame it cannot verify ends the session. - Malformed input never crashes the client. Decode failures emit
protocol_errorand keep the connection. - Repeated JSON keys in an inbound text frame are rejected with
protocol_error(the engine's parser silently keeps the last one; upstream rejects duplicates). - Duplicate keys in a decoded MessagePack payload are rejected with
protocol_error(raw bytes still surface), matching the JSON rule. - Logs redact tokens and ids by default (
sf_log.gd).
The is_connected_to_server() rename¶
is_connected() became is_connected_to_server(). Godot owns
Object.is_connected(signal, callable), so it cannot be shadowed.
is_connected_to_server() reports the transport state CONNECTED.