Events reference

The SDK emits events when things happen — a player joins a lobby, a peer connects, the backend goes offline. Your game listens for these to react in real time.

Listening for events

WavedashSDK.lobby_joined.connect(_on_lobby_joined)
WavedashSDK.lobby_message.connect(_on_lobby_message)
WavedashSDK.p2p_connection_established.connect(_on_peer_connected)
WavedashSDK.backend_connected.connect(_on_backend_connected)

Wavedash.SDK.OnLobbyJoined += OnLobbyJoined;
Wavedash.SDK.OnLobbyMessage += OnLobbyMessage;
Wavedash.SDK.OnP2PConnectionEstablished += OnPeerConnected;
Wavedash.SDK.OnBackendConnected += OnBackendConnected;

// Strongly typed payload
// .on() returns an unsubscribe function.
const unsubscribeLobbyJoined = Wavedash.on(Wavedash.Events.LOBBY_JOINED, (payload) => {
  console.log(`Joined lobby ${payload.lobbyId}`);
});
Wavedash.on(Wavedash.Events.LOBBY_MESSAGE, (payload) => {
  console.log(`${payload.username}: ${payload.message}`);
});
Wavedash.on(Wavedash.Events.P2P_CONNECTION_ESTABLISHED, (payload) => {
  console.log(`Peer connected: ${payload.username}`);
});
Wavedash.on(Wavedash.Events.BACKEND_CONNECTED, (payload) => {
  console.log(`Backend connected (attempt ${payload.connectionCount})`);
});

// Later, to detach:
unsubscribeLobbyJoined();                            // via the unsubscribe fn
Wavedash.off(Wavedash.Events.LOBBY_JOINED, handler); // or using .off

Lobby events

Payload examples

LOBBY_JOINED — fires once when you create or join. users includes you. metadata is whatever the host has set with setLobbyData(); it's an empty object on a fresh lobby.

{
  "lobbyId": "j570h2k8p3m7n5q1r4s9t6v2w8x0y3z4",
  "hostId": "k7m1n3p5q7r9s2t4v6w8x0y2z4a6b8c0",
  "users": [
    {
      "userId": "k7m1n3p5q7r9s2t4v6w8x0y2z4a6b8c0",
      "username": "alice",
      "userAvatarUrl": "https://cdn.wavedash.gg/avatars/alice.png",
      "lobbyId": "j570h2k8p3m7n5q1r4s9t6v2w8x0y3z4",
      "isHost": true
    },
    {
      "userId": "n2p4q6r8s0t2v4w6x8y0z2a4b6c8d0e2",
      "username": "bob",
      "lobbyId": "j570h2k8p3m7n5q1r4s9t6v2w8x0y3z4",
      "isHost": false
    }
  ],
  "metadata": {
    "gameMode": "deathmatch",
    "mapName": "arena",
    "round": "2"
  }
}

LOBBY_USERS_UPDATED — one event per join/leave. Use changeType to branch.

{
  "userId": "n2p4q6r8s0t2v4w6x8y0z2a4b6c8d0e2",
  "username": "bob",
  "userAvatarUrl": "https://cdn.wavedash.gg/avatars/bob.png",
  "lobbyId": "j570h2k8p3m7n5q1r4s9t6v2w8x0y3z4",
  "isHost": false,
  "changeType": "JOINED"
}

LOBBY_MESSAGE — timestamp is Date.now()-style ms since epoch.

{
  "messageId": "m1n3p5q7r9s1t3v5w7x9y1z3a5b7c9d1",
  "lobbyId": "j570h2k8p3m7n5q1r4s9t6v2w8x0y3z4",
  "userId": "k7m1n3p5q7r9s2t4v6w8x0y2z4a6b8c0",
  "username": "alice",
  "message": "ready when you are",
  "timestamp": 1714296245000
}

LOBBY_DATA_UPDATED — the entire metadata object, not a diff. Values are strings or numbers.

{
  "gameMode": "deathmatch",
  "mapName": "arena",
  "round": "3",
  "scoreLimit": 10
}

LOBBY_KICKED:

{
  "lobbyId": "j570h2k8p3m7n5q1r4s9t6v2w8x0y3z4",
  "reason": "KICKED"
}

LOBBY_INVITE — note the sender object uses _id and avatarUrl (not userId/userAvatarUrl like the lobby user shape above).

{
  "notificationId": "p3q5r7s9t1v3w5x7y9z1a3b5c7d9e1f3",
  "lobbyId": "j570h2k8p3m7n5q1r4s9t6v2w8x0y3z4",
  "sender": {
    "_id": "k7m1n3p5q7r9s2t4v6w8x0y2z4a6b8c0",
    "username": "alice",
    "avatarUrl": "https://cdn.wavedash.gg/avatars/alice.png"
  },
  "_creationTime": 1714296245000
}

P2P events

Peer connection lifecycle

A healthy peer lifecycle is P2P_CONNECTION_ESTABLISHED → (traffic) → P2P_PEER_DISCONNECTED. When the network hiccups — a Wi-Fi switch, a brief NAT rebinding — the SDK does an ICE restart and you'll see P2P_PEER_RECONNECTING → P2P_PEER_RECONNECTED in between. Treat that pair as "this peer is unreachable right now" → "go ahead and resume sending". It's still the same peer, no re-handshake is needed, and you don't need to tear down any per-peer state.

If ICE restarts exceed the SDK's retry budget (3 attempts), the SDK emits P2P_CONNECTION_FAILED and then P2P_PEER_DISCONNECTED as the channel closes. For broadcast sends, this is the signal to drop the peer from your "reachable" set — see Multiplayer networking for the full pattern.

Packet drop reasons

The reason field on P2P_PACKET_DROPPED tells you what remedy, if any, is needed:

Events are rate-limited per (direction, channel, reason) tuple. The first drop on an idle tuple fires immediately; further drops within 500 ms are coalesced into a single event at the end of the window. droppedCount is the number of drops in the current event, droppedTotal is the cumulative count for that tuple since P2P init.

Payload examples

The lifecycle events all share the same shape:

{
  "userId": "n2p4q6r8s0t2v4w6x8y0z2a4b6c8d0e2",
  "username": "bob"
}

P2P_CONNECTION_FAILED adds an error string:

{
  "userId": "n2p4q6r8s0t2v4w6x8y0z2a4b6c8d0e2",
  "username": "bob",
  "error": "ICE restart attempts exhausted"
}

P2P_PACKET_DROPPED:

{
  "channel": 0,
  "direction": "SEND",
  "reason": "QUEUE_FULL",
  "droppedCount": 5,
  "droppedTotal": 47
}

Stats events

Payload examples

{ "success": true }

On failure, message describes what went wrong:

{ "success": false, "message": "Network error while persisting stats" }

Backend events

Payload examples

All three events share this shape. connectionCount increments on each successful connect; connectionRetries counts failed attempts in the current outage.

{
  "isConnected": true,
  "hasEverConnected": true,
  "connectionCount": 2,
  "connectionRetries": 0
}

Fullscreen events

See Fullscreen for the request/toggle API and overlay-aware integration.

Per-language names

Each event is exposed as a JS constant, a Unity C# event, and a Godot signal. Connect to whichever matches your engine — the payload fields are the same across all three.

Godot additionally emits per-call signals (got_leaderboard, got_leaderboard_entries, posted_leaderboard_score, ugc_item_created, ugc_item_updated, ugc_item_downloaded, remote_file_uploaded, remote_file_downloaded, remote_directory_downloaded, got_remote_directory_listing, got_lobbies, sent_lobby_invite, got_lobby_invite_link, lobby_created, lobby_left, got_friends, got_user_jwt, user_avatar_loaded). These fire with the response of the matching async call — use them if you prefer signal-based flow over await.

Deferring events

If your game needs time to load before handling events, pass deferEvents: true to init(). The SDK queues all events until you call readyForEvents().

func _ready():
    WavedashSDK.init({"deferEvents": true})

    # set up listeners, load assets, etc.

    WavedashSDK.ready_for_events()  # flush the queue

using System.Collections.Generic;

void Awake()
{
    Wavedash.SDK.Init(new Dictionary<string, object>
    {
        { "deferEvents", true }
    });

    // set up listeners, load assets, etc.

    Wavedash.SDK.ReadyForEvents(); // flush the queue
}

Wavedash.init({ deferEvents: true });

// set up listeners, load assets, etc.

Wavedash.readyForEvents(); // flush the queue