Events reference — Wavedash Docs

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)

In JavaScript, event data is on e.detail. In Godot and Unity, it's passed directly as a Dictionary.

Lobby events

Event	Fires when	Payload
`LOBBY_JOINED`	You join or create a lobby	`lobbyId`, `hostId`, `users`, `metadata`
`LOBBY_USERS_UPDATED`	A user joins or leaves	`lobbyId`, `userId`, `username`, `userAvatarUrl`, `isHost`, `changeType` ("JOINED" or "LEFT")
`LOBBY_MESSAGE`	A chat message arrives	`messageId`, `lobbyId`, `userId`, `username`, `message`, `timestamp`
`LOBBY_DATA_UPDATED`	Lobby metadata changes	The full metadata object
`LOBBY_KICKED`	You're removed from the lobby	`lobbyId`, `reason` ("KICKED" or "ERROR")
`LOBBY_INVITE`	You receive a lobby invite	`notificationId`, `lobbyId`, `sender` (object with `_id`, `username`, `avatarUrl`), `_creationTime`

P2P events

Event	Fires when	Payload
`P2P_CONNECTION_ESTABLISHED`	A peer connection is ready	`userId`, `username`
`P2P_CONNECTION_FAILED`	A peer connection fails	`userId`, `username`, `error`
`P2P_PEER_DISCONNECTED`	A peer disconnects	`userId`, `username`

Stats events

Event	Fires when	Payload
`STATS_STORED`	Stats are persisted to the server	`success`, `message` (optional)

Backend events

Event	Fires when	Payload
`BACKEND_CONNECTED`	Connected to Wavedash	`isConnected`, `hasEverConnected`, `connectionCount`, `connectionRetries`
`BACKEND_DISCONNECTED`	Lost connection	Same as above
`BACKEND_RECONNECTING`	Attempting to reconnect	Same as above

Event constants

All event names are available as WavedashJS.Events:

WavedashJS.Events.LOBBY_JOINED           // "LobbyJoined"
WavedashJS.Events.LOBBY_USERS_UPDATED    // "LobbyUsersUpdated"
WavedashJS.Events.LOBBY_MESSAGE          // "LobbyMessage"
WavedashJS.Events.LOBBY_DATA_UPDATED     // "LobbyDataUpdated"
WavedashJS.Events.LOBBY_KICKED           // "LobbyKicked"
WavedashJS.Events.LOBBY_INVITE           // "LobbyInvite"
WavedashJS.Events.P2P_CONNECTION_ESTABLISHED  // "P2PConnectionEstablished"
WavedashJS.Events.P2P_CONNECTION_FAILED       // "P2PConnectionFailed"
WavedashJS.Events.P2P_PEER_DISCONNECTED      // "P2PPeerDisconnected"
WavedashJS.Events.STATS_STORED           // "StatsStored"
WavedashJS.Events.BACKEND_CONNECTED      // "BackendConnected"
WavedashJS.Events.BACKEND_DISCONNECTED   // "BackendDisconnected"
WavedashJS.Events.BACKEND_RECONNECTING   // "BackendReconnecting"

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().

WavedashJS.init({ deferEvents: true });

// set up listeners, load assets, etc.

WavedashJS.readyForEvents(); // flush the queue