Functions reference — Wavedash Docs

A reference for the public Wavedash SDK functions documented across these guides. Each entry shows the JavaScript signature and a brief description. For full usage examples, see the linked feature page.

Initialization

Functions for setting up the SDK and managing the connection lifecycle. See SDK setup for details.

Function	Description
`init(config)`	Initializes the SDK and applies configuration options. Must be awaited before calling any other SDK method. See SDK setup for supported fields.
`readyForEvents()`	Flushes the deferred event queue. Call after your game finishes loading if you passed `deferEvents: true` to `init()`.

function init(config: WavedashConfig): Promise<void>;

function readyForEvents(): void;

Players

Identity, friends, avatars, and presence. See Player identity for details.

Function	Description
`getUser()`	Returns the signed-in player's profile object.
`getUserId()`	Returns the player's stable string ID.
`getUsername()`	Returns the player's display name.
`listFriends()`	Fetches the current player's friends list.
`getUserAvatarUrl(userId, size)`	Returns an avatar URL for a user at the given size.
`updateUserPresence(data)`	Sets the player's presence status visible to friends.

function getUser(): User;

function getUserId(): string;

function getUsername(): string;

function listFriends(): Promise<WavedashResponse<Friend[]>>;

function getUserAvatarUrl(
  userId: string,
  size: 0 | 1 | 2
): string | null;

function updateUserPresence(
  data: Record<string, unknown>
): Promise<void>;

Avatar sizes

Constant	Value	Size	Use case
`AVATAR_SIZE_SMALL`	`0`	64 px	Lists, compact UI
`AVATAR_SIZE_MEDIUM`	`1`	128 px	Profile cards, chat
`AVATAR_SIZE_LARGE`	`2`	256 px	Full profile view

Achievements & stats

Track player statistics and unlock achievements. See Achievements & stats for details.

Function	Description
`requestStats()`	Fetches player stats from the server.
`getStat(statId)`	Returns the local value of a stat after `requestStats()` has resolved.
`setStat(statId, value, storeNow?)`	Sets a stat value locally. Pass `storeNow: true` to schedule a persist.
`getAchievement(achievementId)`	Returns whether an achievement is unlocked.
`setAchievement(achievementId, storeNow?)`	Unlocks an achievement. Pass `storeNow: true` to schedule a persist.
`storeStats()`	Immediately flushes all pending stat and achievement changes to the server.

function requestStats(): Promise<WavedashResponse<void>>;

function getStat(statId: string): number;

function setStat(
  statId: string,
  value: number,
  storeNow?: boolean
): void;

function getAchievement(achievementId: string): boolean;

function setAchievement(
  achievementId: string,
  storeNow?: boolean
): void;

function storeStats(): void;

Leaderboards

Competitive scoreboards with rankings. See Leaderboards for details.

Function	Description
`getOrCreateLeaderboard(id, sortOrder, displayType)`	Gets an existing leaderboard or creates one with the given settings.
`uploadLeaderboardScore(leaderboardId, score, keepBest, ugcId?)`	Submits a score. When `keepBest` is true, only updates if the score improves.
`listLeaderboardEntries(leaderboardId, start, count, friendsOnly?)`	Fetches a page of top entries.
`listLeaderboardEntriesAroundUser(leaderboardId, countAhead, countBehind, friendsOnly?)`	Fetches entries surrounding the current player's rank.
`getMyLeaderboardEntries(leaderboardId)`	Fetches the current player's own entries.
`getLeaderboardEntryCount(leaderboardId)`	Returns the cached total entry count (returns `-1` if not yet queried).

function getOrCreateLeaderboard(
  id: string,
  sortOrder: 0 | 1,
  displayType: 0 | 1 | 2 | 3
): Promise<WavedashResponse<Leaderboard>>;

function uploadLeaderboardScore(
  leaderboardId: string,
  score: number,
  keepBest: boolean,
  ugcId?: string
): Promise<WavedashResponse<{ globalRank: number }>>;

function listLeaderboardEntries(
  leaderboardId: string,
  start: number,
  count: number,
  friendsOnly?: boolean
): Promise<WavedashResponse<LeaderboardEntry[]>>;

function listLeaderboardEntriesAroundUser(
  leaderboardId: string,
  countAhead: number,
  countBehind: number,
  friendsOnly?: boolean
): Promise<WavedashResponse<LeaderboardEntry[]>>;

function getMyLeaderboardEntries(
  leaderboardId: string
): Promise<WavedashResponse<LeaderboardEntry[]>>;

function getLeaderboardEntryCount(
  leaderboardId: string
): number;

Lobbies

Multiplayer room management. See Multiplayer lobbies for details.

Function	Description
`createLobby(visibility, maxPlayers)`	Creates a new lobby and returns its ID.
`joinLobby(lobbyId)`	Joins an existing lobby.
`leaveLobby(lobbyId)`	Leaves a lobby.
`listAvailableLobbies(friendsOnly?)`	Lists lobbies that the player can join.
`getLobbyUsers(lobbyId)`	Returns the list of users currently in a lobby.
`getLobbyHostId(lobbyId)`	Returns the user ID of the lobby host.
`getNumLobbyUsers(lobbyId)`	Returns how many users are in a lobby.
`sendLobbyMessage(lobbyId, message)`	Sends a chat message to the lobby.
`inviteUserToLobby(lobbyId, userId)`	Sends a lobby invite to another user.
`setLobbyData(lobbyId, key, value)`	Sets a metadata key on the lobby (host only).
`getLobbyData(lobbyId, key)`	Reads a metadata key from the lobby.
`deleteLobbyData(lobbyId, key)`	Removes a metadata key from the lobby (host only).
`getLobbyInviteLink(copyToClipboard?)`	Generates a shareable invite link for the current lobby.

function createLobby(
  visibility: 0 | 1 | 2,
  maxPlayers: number
): Promise<WavedashResponse<string>>;

function joinLobby(
  lobbyId: string
): Promise<void>;

function leaveLobby(
  lobbyId: string
): Promise<void>;

function listAvailableLobbies(
  friendsOnly?: boolean
): Promise<WavedashResponse<Lobby[]>>;

function getLobbyUsers(
  lobbyId: string
): LobbyUser[];

function getLobbyHostId(
  lobbyId: string
): string;

function getNumLobbyUsers(
  lobbyId: string
): number;

function sendLobbyMessage(
  lobbyId: string,
  message: string
): void;

function inviteUserToLobby(
  lobbyId: string,
  userId: string
): Promise<void>;

function setLobbyData(
  lobbyId: string,
  key: string,
  value: string
): void;

function getLobbyData(
  lobbyId: string,
  key: string
): string;

function deleteLobbyData(
  lobbyId: string,
  key: string
): void;

function getLobbyInviteLink(
  copyToClipboard?: boolean
): Promise<WavedashResponse<string>>;

P2P networking

Peer-to-peer messaging over WebRTC. See Multiplayer networking for details.

Function	Description
`broadcastP2PMessage(channel, reliable, payload)`	Sends a message to every connected peer.
`sendP2PMessage(userId, channel, reliable, payload)`	Sends a message to a single peer.
`readP2PMessageFromChannel(channel)`	Reads the next queued message from a channel, or `null` if empty.
`drainP2PChannelToBuffer(channel)`	Reads all queued messages into a tightly packed binary buffer for high-performance engines.

function broadcastP2PMessage(
  channel: number,
  reliable: boolean,
  payload: Uint8Array
): void;

function sendP2PMessage(
  userId: string,
  channel: number,
  reliable: boolean,
  payload: Uint8Array
): void;

function readP2PMessageFromChannel(
  channel: number
): P2PMessage | null;

function drainP2PChannelToBuffer(
  channel: number
): Uint8Array;

Cloud saves

Remote file storage synced across devices. See Cloud saves for details.

Function	Description
`writeLocalFile(path, data)`	Writes a file to the local virtual filesystem.
`readLocalFile(path)`	Reads a file from the local virtual filesystem.
`uploadRemoteFile(path)`	Uploads a local file to the player's cloud storage.
`downloadRemoteFile(path)`	Downloads a file from cloud storage to the local filesystem.
`downloadRemoteDirectory(path)`	Downloads an entire directory from cloud storage.
`listRemoteDirectory(path)`	Lists files in a cloud storage directory.

function writeLocalFile(
  path: string,
  data: Uint8Array
): Promise<void>;

function readLocalFile(
  path: string
): Promise<Uint8Array>;

function uploadRemoteFile(
  path: string
): Promise<WavedashResponse<void>>;

function downloadRemoteFile(
  path: string
): Promise<WavedashResponse<void>>;

function downloadRemoteDirectory(
  path: string
): Promise<void>;

function listRemoteDirectory(
  path: string
): Promise<WavedashResponse<RemoteFileMetadata[]>>;

User-generated content

Replays, screenshots, levels, and other player-created files. See User-generated content for details.

Function	Description
`createUGCItem(type, title, description, visibility, localPath)`	Uploads a new UGC item and returns its ID.
`updateUGCItem(ugcId, title, description, visibility, filePath)`	Updates metadata or replaces the file on an existing UGC item.
`downloadUGCItem(ugcId, localPath)`	Downloads a UGC item to the local filesystem.

function createUGCItem(
  type: 0 | 1 | 2 | 3 | 4,
  title: string,
  description: string,
  visibility: 0 | 1 | 2,
  localPath: string
): Promise<WavedashResponse<string>>;

function updateUGCItem(
  ugcId: string,
  title: string,
  description: string,
  visibility: 0 | 1 | 2,
  filePath: string | null
): Promise<void>;

function downloadUGCItem(
  ugcId: string,
  localPath: string
): Promise<WavedashResponse<void>>;

Events

Subscribe to SDK events. See Events reference for the full event list.

Function	Description
`addEventListener(eventName, handler)`	Registers a listener for an SDK event. Event data is available on `e.detail`.

function addEventListener(
  eventName: string,
  handler: (event: CustomEvent) => void
): void;