Skip to content

Events

The client emits one snake_case signal per server event. Connect handlers, then let the poll loop deliver events. Nothing arrives outside poll().

GDScript
var client := SignalFishClient.new()
add_child(client)

client.authenticated.connect(
    func(app_name, _org, _limits):
        print("authenticated: %s" % app_name)
        # Room commands require an authenticated session.
        var params := SignalFishClient.JoinRoomParams.new()
        params.game_name = "reef-rally"
        params.player_name = "Alice"
        client.join_room(params)
)
client.room_joined.connect(func(info): print("joined room %s" % info.room_code))
client.game_data_received.connect(func(from_player, data): print("%s: %s" % [from_player, data]))

Lifecycle and transport

GDScript
connected, disconnected(code, reason), connection_failed(error), protocol_error(error)

protocol_error is local and non-fatal; it never carries a server code.

Authentication

GDScript
authenticated(app_name, organization, rate_limits)
protocol_info(info)
authentication_error(error, error_code)

The protocol_info payload (SFTypes.ProtocolInfo) carries the server's capability statement: game_data_formats, player_name_rules, capabilities, the v3 protocol_version / min_protocol_version / max_protocol_version / transports fields, and max_outbound_message_size - the maximum complete encoded outbound payload in bytes when the server states one (v3+; 0 = absent).

Room lifecycle and presence

GDScript
room_joined(info), room_join_failed(reason, error_code), room_left
player_joined(player), player_left(player_id), player_reconnected(player_id)

Game data

GDScript
game_data_received(from_player, data)
game_data_binary_received(from_player, encoding, payload: PackedByteArray)

Authority and lobby

GDScript
authority_changed(authority_player, you_are_authority)
authority_response(granted, reason, error_code)
lobby_state_changed(lobby_state, ready_players, all_ready)
game_starting(peer_connections)

Heartbeat

GDScript
pong

Reconnection

GDScript
reconnected(info, missed_events: Array)
reconnection_failed(reason, error_code)

Spectators

GDScript
spectator_joined(info), spectator_join_failed(reason, error_code)
spectator_left(room_id, room_code, reason, current_spectators)
new_spectator_joined(spectator, current_spectators, reason)
spectator_disconnected(spectator_id, reason, current_spectators)

A recovered server detach uses the same spectator events. spectator_left clears the viewing state before its signal; room members observe the removal through spectator_disconnected. A correlated RoomOperationResult remains informational. It preserves the operation ID and payload without changing roles.

A reconnected player receives missed spectator removals in missed_events. The application replays those entries; they do not emit live signals again. During shutdown, queued terminal frames surface before disconnected when the engine retains them. Native Godot can discard data received with the close handshake in one poll. Server drain can also suppress detach notifications.

Generic server errors

GDScript
server_error(message, error_code)

v3 session plan

GDScript
signal_received(from_player, generation, signal_payload)
new_peer(peer_id, you_initiate)
session_plan(plan)
peer_transport_status(peer_id, transport, connected)
going_away(deadline_ms, retry_after_secs)
delivery_report(report)
room_operation_result(result)

These signals only fire when SignalFishConfig.protocol_version is set to a positive version (opt-in; 0 omits the capabilities and keeps the v2 wire bytes) and the server negotiates a v3 session plan.

going_away is a best-effort drain advisory; the close that follows stays authoritative. delivery_report and room_operation_result are surfaced verbatim; the client never acts on them. retry_after_secs is -1 when the server sends no hint.

Typed payloads and sentinels

  • Structured payloads are typed RefCounted objects in SFTypes and SFSessionTypes, such as PlayerInfo, RoomJoinedInfo, ConnectionInfo, and SessionPlanInfo. Each is built from the wire dictionary on decode and exposes to_dict() plus a raw dictionary with the exact wire details.
  • Closed sets are enums: SFTypes.LobbyState, GameDataEncoding, RelayTransport, SpectatorReason, ReplayStatus, SFErrorCodes.Code, and SFSessionTypes.Topology / SFSessionTypes.TransportKind / SFSessionTypes.DeliveryGapReason.
  • User game data stays Variant. Binary payloads are PackedByteArray.
  • raw may share structure across missed_events, so treat it as read-only. to_dict() returns the independent mutable copy.

Optional wire values decode to stable sentinels:

Wire value Decoded as
Missing string ""
Missing array Empty array
Unknown enum string The owning enum's UNKNOWN member
Absent error code SFErrorCodes.Code.NONE