Skip to content

Steam P2P

SFSteamIdentityBootstrap is an opt-in helper that puts Steam P2P traffic on a Signal Fish room. Steam has no matchmaking to lean on, so the room itself is the fence: the Signal Fish room owns membership, heartbeats, and reconnection-ready sessions, while Steam's relay network carries the game traffic. The bootstrap establishes and fences the Steam connections, and the game owns what flows over them.

The wire contract mirrors the dotnet client's Steamworks.NET adapter, so a room can mix bindings in principle: the two SteamId64s ride the game-data lane under the exact keys signal_fish_steam_host and signal_fish_steam_peer, as decimal strings that survive every JSON decoder losslessly.

Requirements

  • The GodotSteam GDExtension. Desktop platforms only: the Steamworks SDK ships no browser library, so web exports keep the relay-only client.
  • Steamworks initialized before start(), with callbacks pumped each frame (Steam.run_callbacks() in _process, or GodotSteam's embedded mode). The bootstrap never pumps them itself, so it stays honest about who owns the frame.

Using the bootstrap

Host:

GDScript
var bootstrap := SFSteamIdentityBootstrap.new()
add_child(bootstrap)
bootstrap.role = SFSteamIdentityBootstrap.Role.HOST
bootstrap.attach(client)
bootstrap.start()

The host publishes its SteamId64 when the room session goes live and re-publishes on its authority grant, on every later join, and whenever a peer's advertisement arrives (a peer can start coordinating after the host's publish), so late joiners never depend on timing. It also requests the authority: the fence needs a stable holder, and authority leaving the host fails the coordination.

Peer:

GDScript
bootstrap.role = SFSteamIdentityBootstrap.Role.PEER
bootstrap.attach(client)
bootstrap.start()
bootstrap.steam_host_connected.connect(func(host_id: String) -> void:
    # The session to the host is up; send game traffic to host_id over
    # your own P2P channels from here.
)

The peer publishes its own id, consumes the host id, and dials it by itself. start() returns ERR_UNAVAILABLE when GodotSteam is missing or Steamworks is uninitialized, so a silent no-op can never look like a fenced session.

The fence

The room must have authority enabled (supports_authority): the host lane binds to the room's authority, and a room without one is refused by start() or fails with its first baseline. Steam's rendezvous authenticates the connecting identity (the claim is Steam's, not the peer's), so the host only checks that the connecting id was advertised on the room's lane. An unknown requester waits accept_grace_sec (default 5 s) for its advertisement and is refused when it never comes; zero refuses every requester that was not already advertised. Advertisements belong to the member that published them and leave with them, and the host id is only consumed from the room's authority, so one hostile member can neither redirect the session nor poison the fence set. An id that keeps re-requesting without ever being advertised is refused for the rest of the session after a few grace windows.

Channels

The classic Steam P2P API is session-less: there is no listen call and no connect-success callback. The dial is a one-byte poke on the bootstrap channel (steam_channel, default 1), and the host's reply is the "connected" event. Run game traffic on your own channels; keep payloads off the bootstrap channel. A refused host reply closes that unfinished session and emits no connect signal. A later request can retry the handshake.

Signals

Signal Meaning
steam_host_id_received(steam_id) The published host id arrived (peer side). Informational; the bootstrap dials by itself.
steam_host_connected(steam_id) The peer's session to the host is up.
steam_peer_connected(steam_id) The host accepted a fenced peer.
steam_peer_disconnected(steam_id) A fenced peer's session went down (best effort).
coordination_failed(reason) A live-session failure stopped the coordination.

Configuration

Member Meaning
role HOST fences the accepts; PEER dials the published host id.
accept_grace_sec How long the host waits for an unknown requester's lane advertisement. Zero refuses immediately.
host_id_timeout_sec How long a peer waits for the host id before failing. Zero waits forever.
steam_connect_timeout_sec How long the dial may take before failing. Zero waits forever.
steam_channel The P2P channel the handshake uses. The game owns the rest.
max_packets_per_poll Handshake packets drained per poll. The rest waits for the next poll.
max_bytes_per_poll Handshake bytes drained per poll (256 KiB). A larger packet still drains alone.
steam Injectable Steam seam; tests substitute a fake, games leave it null.

Failure modes

coordination_failed fires and the coordination stops when the room connection closes or fails, the room session ends (including authentication_error), the room has no authority holder, the authority leaves the host, the published host id changes mid-session, the host Steam session closes, or a dial times out or fails. A dial that never completed and a fence request still pending close their Steam sessions; an established session always belongs to the game. stop() closes every session the bootstrap opened. Membership enforcement beyond the accept fence (room leave and rejoin races, the host leaving while peers hold connections) stays the game's job.

Because the classic P2P API has no session-closed callback, disconnects are detected by watching getP2PSessionState during poll() - best effort, and worth a fallback in the game's own protocol. A session only reports a drop after it was seen active: Steam reports connection setup as connecting, so setup never reads as a drop, and a session that never came up fails through p2p_session_connect_fail instead.

Live drill runbook

CI proves the bootstrap against a fake Steam seam. A live drill proves the real thing: two Steam seats, two accounts, one relay room, and the checklist as data (run_steam_live_drill.gd, issue #318). Run it before trusting the bootstrap in a shipped game.

Seats

  • Host seat: a machine with the native Steam client.
  • Peer seat: a second machine, or a container image with a desktop Steam client (Steam-Headless is a common one) on the same machine.
  • Accounts: two Steam accounts. The first login on a seat is interactive (Steam Guard), so use burner accounts and keep the seats logged in.
  • Steam app: the drills run against app id 480 (Spacewar). Put a steam_appid.txt file with 480 next to the Godot binary; Steamworks reads it when launched outside Steam.
  • Engine: Godot 4.4.1 plus the GodotSteam GDExtension 4.23.2 - the pair the opt-in steam-ext lane downloads, pins, and checksums; use its copy for the seat's drill tree. Version landmines (measured facts: .llm/research/steam-identity.md):
  • Every GDExtension from 4.16 on needs Godot 4.4 or newer.
  • Godot 4.3 caps at GDExtension 4.15, which ships no linux arm64 libraries; arm64 seats need the 4.23.2 extension with Godot 4.4.1.
  • Embedded callbacks broke in 4.14/3.29; auto-init plus embed only works from 4.23. The drill harness pumps run_callbacks() itself, so it needs neither.

Run

Self-check first - deterministic, no Steam needed:

Bash
python3 -E scripts/run-runtime-checks.py steam-drill

Then one process per seat against a real relay. --app is your Signal Fish app id on the relay; the Steam app id above is separate. Start the host, and read the room code from its room_joined row:

Bash
godot --headless --path . --script tests/smoke/run_steam_live_drill.gd ++ --mode=live --seat=host --endpoint=wss://your-relay/socket --app=your-app --player=Host --out=host.json

The host prints progress JSON as events arrive. Its room_joined event's value contains the room code. The final --out report is written when the seat stops. Both seats request an authority-enabled room.

Join the peer to the same room. The peer requires --room:

Bash
godot --headless --path . --script tests/smoke/run_steam_live_drill.gd ++ --mode=live --seat=peer --endpoint=wss://your-relay/socket --app=your-app --player=Peer --room=CODE --out=peer.json

The host seat reaches its connection milestone on steam_peer_connected; the peer seat reaches it on steam_host_connected. Add --observe-sec=30 to both commands to keep each seat polling for 30 seconds after its milestone. Set --deadline-sec=120 to allow time for setup and observation. The overall deadline still bounds the run. The default exits at the connection milestone. Captured Steam signals print as JSON events during observation, so you can wait for both seats to connect before driving a drop.

During observation, use your room controller to transfer authority away from the host. The expected authority-loss failure records that checklist item and ends observation. Other coordination failures still fail the run. To check peer leave detection, drive a Steam session drop while the host keeps observing. A room leave alone does not prove a Steam session drop. Keep unexercised items pending in the report.

Failed checks exit 1, usage errors exit 2, and everything else exits 0: passed, and also pending. A seat with no Steam, one that runs out of --deadline-sec, or a run with unexercised checklist items reports pending. Reaching the connection milestone still leaves leave-detection and authority-loss checks to drive during observation. Read the JSON report's status and each assertion's outcome, never the exit code alone. The report carries one row per recorded check, with elapsed times.

Evidence and verdict

  • Attach both seat JSON reports.
  • Capture Steam's relay log: launch each Steam client with -lognetapi; it writes all P2P networking info to log/netapi_log.txt under the Steam install directory.
  • Record the verdict on the drill issue (#322). A clean two-machine run closes #315; re-scope with the failures when it does not.
  • Update .llm/research/steam-identity.md open items with the fake-vs-real deltas.

Validation status

CI runs the full bootstrap against a deterministic fake Steam seam (fake time, fake transport, no GodotSteam). The GodotSteam call surface was authored against the GodotSteam 4.x sources and docs; live validation follows the runbook above.