Functions reference

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
`Wavedash` (default export of `@wvdsh/sdk-js`)	The SDK singleton. Install `@wvdsh/sdk-js` and `import Wavedash from "@wvdsh/sdk-js"` for fully-typed access. Same instance is also reachable as `window.Wavedash`.
`init(config?)`	Initializes the SDK, applies configuration options, and signals load-complete. Returns `true` on first call, `false` if already initialized. Call it once. `readyForEvents()` and the `getP2P*` getters (max payload size, max incoming messages, outgoing buffer) throw before `init()`; other calls still work, but no events reach your handlers until `init()` runs. 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()`. Otherwise `init()` calls this automatically.
`updateLoadProgressZeroToOne(progress)`	Reports load progress (0.0 – 1.0) to the Wavedash shell so it can render a loading bar. Call repeatedly while assets download or the runtime boots.
`loadComplete()`	Signals that the game is ready for the player to interact with. Idempotent. `init()` calls this internally, so you only need to call it directly if you want to signal load-complete before running `init()` (e.g., from a splash screen).
`loadScript(src)`	Convenience wrapper that appends a `<script>` tag to the page and resolves once it loads. Useful when you need to lazy-load a third-party library.
`initialized` (getter)	`true` once `init()` has been called.
`eventsReady` (getter)	`true` once the deferred event queue has been flushed.
`gameLoaded` (getter)	`true` once `loadComplete()` has fired.

import Wavedash from "@wvdsh/sdk-js";

interface WavedashSDK {
  init(config?: WavedashConfig): boolean;
  readyForEvents(): void;
  updateLoadProgressZeroToOne(progress: number): void;
  loadComplete(): void;
  loadScript(src: string): Promise<unknown>;
  readonly initialized: boolean;
  readonly eventsReady: boolean;
  readonly gameLoaded: boolean;
}

External links

Function	Description
`copyLink(url)`	Copies an external URL to the player's clipboard and shows a Wavedash toast, instead of navigating them out of the game. Call it inside a user-gesture handler (click, keydown, pointerdown). Resolves `true` on success.

function copyLink(url: string): Promise<boolean>;

Deprecated

Function	Description
`toggleOverlay()`	No-op. The in-game overlay no longer exists; the call logs a warning and does nothing.
`isMuted()`, `requestMute()`, `toggleMute()`	No-ops kept so older builds don't break; each logs a deprecation warning.

function toggleOverlay(): void;

Launch params

Read URL parameters that were passed when the game was launched. See SDK setup for details.

Function	Description
`getLaunchParams()`	Returns the key-value mapping of `wvdsh_`-prefixed URL query params that were present when the game launched.

function getLaunchParams(): GameLaunchParams;

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.
`getUserJwt()`	Returns a short-lived signed JWT you can forward to your own backend to authenticate the player.
`listFriends()`	Fetches the current player's friends list.
`getUserAvatarUrl(userId, size)`	Returns an avatar URL for a user at the given size.
`updateUserPresence(data)`	Stores `status` / `details` with the player's presence (not currently shown on friends-list rows).

function getUser(): User; // see Types — not exported by name

function getUserId(): UserId;

function getUsername(): string;
function getUsername(userId: UserId): string | null; // cached friends / lobby peers

function getUserJwt(): Promise<WavedashResponse<string>>;

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

function getUserAvatarUrl(
  userId: UserId,
  size?: number // a Wavedash.AvatarSize preset or custom pixels; default MEDIUM
): string | null;

function updateUserPresence(
  data: Record<string, string | number | boolean | null>
): Promise<WavedashResponse<boolean>>;

Avatar sizes

Wavedash.AvatarSize exposes preset pixel values. Pass any preset (or a custom pixel size) to getUserAvatarUrl.

Constant	Pixels	Use case
`Wavedash.AvatarSize.SMALL`	64	Lists, compact UI
`Wavedash.AvatarSize.MEDIUM`	128	Profile cards, chat
`Wavedash.AvatarSize.LARGE`	256	Full profile view

Fullscreen

Request, exit, and check fullscreen state. See Fullscreen for details.

Function	Description
`requestFullscreen(fullscreen)`	Asks the host to enter (`true`) or exit (`false`) fullscreen. Resolves to `true` if the host accepted, `false` if the browser rejected. Must be called from a user gesture to enter.
`toggleFullscreen()`	Flips the current fullscreen state. Resolves to `true` if the host accepted, `false` otherwise. Must be called from a user gesture when entering.
`isFullscreen()`	Returns whether the game is currently presented in fullscreen.

function requestFullscreen(fullscreen: boolean): Promise<boolean>;

function toggleFullscreen(): Promise<boolean>;

function isFullscreen(): boolean;

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 — `0` until stats and achievements have both loaded, or if the identifier isn't defined.
`setStat(statId, value, storeNow?)`	Sets a stat value. Saved to the server within about a second; pass `storeNow: true` to save immediately.
`getAchievement(achievementId)`	Returns whether an achievement is unlocked.
`setAchievement(achievementId, storeNow?)`	Unlocks an achievement. Saved to the server within about a second; pass `storeNow: true` to save immediately.
`storeStats()`	Immediately flushes all pending stat and achievement changes to the server.

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

function getStat(statId: string): number;

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

function getAchievement(achievementId: string): boolean;

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

function storeStats(): boolean;

Leaderboards

Competitive scoreboards with rankings. See Leaderboards for details.

Function	Description
`getLeaderboard(name)`	Fetches a leaderboard by name. Fails if it doesn't exist — use `getOrCreateLeaderboard` to create on miss.
`getOrCreateLeaderboard(name, sortOrder, displayType)`	Gets an existing leaderboard or creates one with the given settings.
`uploadLeaderboardScore(leaderboardId, score, keepBest, ugcId?, metadata?)`	Submits a score. When `keepBest` is true, only updates if the score improves. `metadata` stores small key/value data (strings, numbers, booleans) on the entry.
`listLeaderboardEntries(leaderboardId, offset, limit, 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 getLeaderboard(
  name: string
): Promise<WavedashResponse<Leaderboard>>;

function getOrCreateLeaderboard(
  name: string,
  sortOrder: LeaderboardSortOrder,
  displayType: LeaderboardDisplayType
): Promise<WavedashResponse<Leaderboard>>;

function uploadLeaderboardScore(
  leaderboardId: LeaderboardId,
  score: number,
  keepBest: boolean,
  ugcId?: UGCId,
  metadata?: LeaderboardEntryMetadata
): Promise<WavedashResponse<UpsertedLeaderboardEntry>>;

function listLeaderboardEntries(
  leaderboardId: LeaderboardId,
  offset: number,
  limit: number,
  friendsOnly?: boolean
): Promise<WavedashResponse<LeaderboardEntries>>;

function listLeaderboardEntriesAroundUser(
  leaderboardId: LeaderboardId,
  countAhead: number,
  countBehind: number,
  friendsOnly?: boolean
): Promise<WavedashResponse<LeaderboardEntries>>;

function getMyLeaderboardEntries(
  leaderboardId: LeaderboardId
): Promise<WavedashResponse<LeaderboardEntries>>;

function getLeaderboardEntryCount(
  leaderboardId: LeaderboardId
): number;

Lobbies

Multiplayer room management. See Multiplayer lobbies for details.

Function	Description
`createLobby(visibility, maxPlayers?)`	Creates and joins 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.
`getLobby(lobbyId)`	Fetches a lobby's details (and caches it, so `getLobbyData` can read its metadata before you 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 to a string, number, or boolean (host only). Passing `null` deletes the key.
`getLobbyData(lobbyId, key)`	Reads a metadata key. Returns `null` if unset.
`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: LobbyVisibility,
  maxPlayers?: number
): Promise<WavedashResponse<LobbyId>>;

function joinLobby(
  lobbyId: LobbyId
): Promise<WavedashResponse<boolean>>;

function leaveLobby(
  lobbyId: LobbyId
): Promise<WavedashResponse<LobbyId>>;

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

function getLobby(
  lobbyId: LobbyId
): Promise<WavedashResponse<Lobby>>;

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

function getLobbyHostId(
  lobbyId: LobbyId
): UserId | null;

function getNumLobbyUsers(
  lobbyId: LobbyId
): number;

function sendLobbyMessage(
  lobbyId: LobbyId,
  message: string
): boolean;

function inviteUserToLobby(
  lobbyId: LobbyId,
  userId: UserId
): Promise<WavedashResponse<boolean>>;

function setLobbyData(
  lobbyId: LobbyId,
  key: string,
  value: LobbyDataUpdate // string | number | boolean | null — null deletes the key
): boolean;

function getLobbyData(
  lobbyId: LobbyId,
  key: string
): LobbyDataValue | null; // string | number | boolean, or null if unset

function deleteLobbyData(
  lobbyId: LobbyId,
  key: string
): boolean;

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.
`getP2PMaxPayloadSize()`	Returns the maximum payload bytes for a single P2P message, derived from `P2PConfig.messageSize`.
`getP2PMaxIncomingMessages()`	Returns the configured max incoming messages per channel queue.
`getP2POutgoingMessageBuffer()`	Returns a pre-allocated scratch `Uint8Array` your game can write outgoing payload bytes into before calling `sendP2PMessage`. Used by engine SDKs for zero-copy handoff.

function broadcastP2PMessage(
  channel: number | undefined,   // default 0 — pass undefined to reach payload
  reliable: boolean | undefined, // default true
  payload: Uint8Array,
  payloadSize?: number
): boolean;

function sendP2PMessage(
  userId: UserId | undefined,
  channel: number | undefined,   // default 0
  reliable: boolean | undefined, // default true
  payload: Uint8Array,
  payloadSize?: number
): boolean;

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

function drainP2PChannelToBuffer(
  channel: number,
  buffer?: Uint8Array // optional reusable output buffer
): Uint8Array;

function getP2PMaxPayloadSize(): number;

function getP2PMaxIncomingMessages(): number;

function getP2POutgoingMessageBuffer(): Uint8Array;

In Unity, the equivalent is the static property Wavedash.SDK.MAX_PAYLOAD_SIZE (read once at Init() time and cached).

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.
`remoteFileExists(path)`	Checks whether a remote file exists. Sends a lightweight HEAD request — cheaper than attempting a download.
`deleteRemoteFile(path)`	Deletes a file from cloud storage.
`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<boolean>;

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

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

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

function remoteFileExists(
  path: string
): Promise<WavedashResponse<boolean>>;

function deleteRemoteFile(
  path: string
): Promise<WavedashResponse<string>>;

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

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?, filePath?)`	Creates a new UGC item and returns its ID. All args except `type` are optional — omit `filePath` to create metadata first and upload later via `updateUGCItem`.
`updateUGCItem(ugcId, updates?)`	Updates metadata and/or replaces the file on an existing UGC item. Pass only the fields you want to change in `updates`; any omitted field is untouched.
`deleteUGCItem(ugcId)`	Deletes a UGC item: removes it from the game's UGC library and frees the user's storage quota by the size of the deleted upload.
`downloadUGCItem(ugcId, filePath)`	Downloads a UGC item to the local filesystem.
`listUGCItems(args?)`	Lists UGC items with optional filters (`createdBy`, `ugcType`, `titleSearch`) and pagination (`numItems`, `continueCursor`). Returns `{ page, isDone, continueCursor }`.

function createUGCItem(
  type: UGCType,
  title?: string,
  description?: string,
  visibility?: UGCVisibility,
  filePath?: string
): Promise<WavedashResponse<UGCId>>;

function updateUGCItem(
  ugcId: UGCId,
  updates?: {
    title?: string;
    description?: string;
    visibility?: UGCVisibility;
    filePath?: string;
  }
): Promise<WavedashResponse<UGCId>>;

function deleteUGCItem(
  ugcId: UGCId
): Promise<WavedashResponse<UGCId>>;

function downloadUGCItem(
  ugcId: UGCId,
  filePath: string
): Promise<WavedashResponse<UGCId>>;

function listUGCItems(
  args?: {
    createdBy?: UserId;
    ugcType?: UGCType;
    titleSearch?: string;
    numItems?: number;
    continueCursor?: string;
  }
): Promise<WavedashResponse<PaginatedUGCItems>>;

Paid content

Check ownership, open the paywall, and fulfill consumable purchases. See Durables and Consumables for details.

Function	Description
`isEntitled(contentIdentifier)`	Durables only. Returns whether the player owns the given durable. A UI hint; Wavedash enforces access when serving the files. Always `false` for a consumable.
`getEntitlements()`	Durables only. Returns every durable content identifier the player owns for this game. Consumables never appear.
`triggerPaywall(contentIdentifier)`	Opens the Wavedash paywall for the content and resolves with whether the purchase completed. For a durable the player already owns, it resolves `true` immediately without opening. A consumable always opens the paywall. Handle purchases in `PURCHASE_COMPLETED`, not from this result.
`fulfillPurchase(purchaseId)`	Marks a consumable purchase fulfilled once you've granted it, so it stops being redelivered. Idempotent. Resolves with `{ status }`: `FULFILLED`, `ALREADY_FULFILLED` (also success), or `NOT_FOUND` (unknown or refunded, so don't grant it).
`getUnfulfilledPurchases()`	Returns the consumable purchases the game hasn't fulfilled, oldest first. They already arrive as `PURCHASE_COMPLETED` at launch; use this to retry a failed `fulfillPurchase` within the same session.

function isEntitled(
  contentIdentifier: string
): Promise<WavedashResponse<boolean>>;

function getEntitlements(): Promise<WavedashResponse<string[]>>;

function triggerPaywall(
  contentIdentifier: string
): Promise<WavedashResponse<boolean>>;

function fulfillPurchase(
  purchaseId: PurchaseId
): Promise<WavedashResponse<FulfillPurchaseResult>>;

function getUnfulfilledPurchases(): Promise<WavedashResponse<Purchase[]>>;

In Godot, WavedashSDK.download_content(item_path, local_path) fetches a file that shipped with your build but wasn't loaded yet — extra levels, high-resolution assets, paid files — and saves it under user://. local_path is optional and defaults to user:// + item_path. Because Wavedash re-checks ownership before serving paid bytes, a locked file resolves with code: 403 and the content_identifiers the player must buy.

There's no equivalent function in the JavaScript or Unity SDKs, and mostly there doesn't need to be: any request for a build file is gated, so an Addressables or AssetBundle load already goes through the check. Reach for fetch or UnityWebRequest when you want the 403 in hand. See Fetching the paid files for the flow in each engine.

Events

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

Function	Description
`on(eventName, listener)`	Registers a strongly-typed listener for an SDK event. listener receives the event payload. Returns an unsubscribe function.
`off(eventName, listener)`	Removes a listener previously registered with `on()`. Pass the same listener function you registered.

function on<K extends keyof WavedashEventMap>(
  eventName: K,
  listener: (payload: WavedashEventMap[K]) => void
): () => void;

function off<K extends keyof WavedashEventMap>(
  eventName: K,
  listener: (payload: WavedashEventMap[K]) => void
): void;

Search documentation