Types Reference

interface WavedashResponse<T> {
  success: boolean;     // Whether the operation succeeded
  data: T | null;       // Result data (null on failure)
  message?: string;     // Error message if success is false
}

const user = WavedashJS.getUser(); // sync getter

const response = await WavedashJS.getLeaderboard("high-scores");

if (response.success) {
  const leaderboard: Leaderboard = response.data;
  // Use leaderboard...
} else {
  console.error(response.message);
}

interface WavedashConfig {
  debug?: boolean;                       // Useful for logging and testing — enables verbose output in the browser console
  deferEvents?: boolean;                 // Lets your game finish setup before handling lobby/multiplayer events
  remoteStorageOrigin?: string;          // Custom origin for remote file storage
  p2p?: Partial<P2PConfig>;             // P2P networking configuration (see P2PConfig below)
}

interface P2PConfig {
  maxPeers: number;                // Max concurrent connections (default: 8)
  enableReliableChannel: boolean;  // TCP-like channel
  enableUnreliableChannel: boolean; // UDP-like channel
  messageSize?: number;            // Max bytes per message slot (default: 2048, max: 65536)
  maxIncomingMessages?: number;    // Incoming message queue depth (default: 1024)
}

interface Leaderboard {
  id: string;           // Leaderboard ID
  name: string;         // Display name
  sortOrder: LeaderboardSortOrder;   // "ascending" | "descending"
  displayType: LeaderboardDisplayType; // See LeaderboardDisplayType below
  totalEntries: number; // Total number of entries
}

// 0 = ascending  — Lower scores rank higher (time trials, golf)
// 1 = descending — Higher scores rank higher (points, high scores)
type LeaderboardSortOrder = 0 | 1;

// 0 = numeric           — Display as a number (e.g., "1,000")
// 1 = time_seconds      — Display as time in seconds (e.g., "1:23")
// 2 = time_milliseconds — Display as time with milliseconds (e.g., "1:23.456")
// 3 = time_game_ticks   — Display as game ticks (assumes 60fps)
type LeaderboardDisplayType = 0 | 1 | 2 | 3;

interface LeaderboardEntry {
  userId: string;      // Player's user ID
  username?: string;   // Player's display name
  score: number;       // Score value
  globalRank: number;  // Current rank
  ugcId?: string;      // Attached UGC (optional)
  timestamp: number;   // Submission timestamp
  metadata?: Uint8Array; // Optional binary metadata
}

interface Lobby {
  lobbyId: string;               // Lobby ID
  visibility: LobbyVisibility;   // Access level
  maxPlayers: number;            // Player limit
  playerCount: number;           // Current count
  metadata: Record<string, unknown>; // Custom data
}

// 0 = public       — Anyone can find and join
// 1 = friends_only — Only friends can see and join
// 2 = private      — Only joinable with the lobby ID
type LobbyVisibility = 0 | 1 | 2;

interface LobbyUser {
  lobbyId: string;              // Lobby ID
  userId: string;               // User ID
  username: string;             // Display name
  userAvatarUrl?: string;       // Avatar URL
  isHost: boolean;              // Whether this user is the host
}

interface LobbyMessage {
  messageId: string;   // Message ID
  lobbyId: string;     // Lobby ID
  userId: string;      // Sender's ID
  username: string;    // Sender's name
  message: string;     // Message text
  timestamp: number;   // Timestamp
}

interface LobbyInvite {
  notificationId: string;  // Notification ID
  lobbyId: string;         // ID of the lobby you're invited to
  sender: {
    _id: string;           // User ID of who sent the invite
    username: string;      // Username of who sent the invite
    avatarUrl?: string;    // Avatar URL of the sender
  };
  _creationTime: number;   // When the invite was sent
}

interface Friend {
  userId: string;      // Friend's user ID
  username: string;    // Friend's display name
  avatarUrl?: string;  // Avatar URL (if set)
  isOnline: boolean;   // Whether the friend is currently online
}

interface P2PConnection {
  lobbyId: string;
  peers: Record<string, P2PPeer>;
  state: P2PConnectionState;
}

type P2PConnectionState =
  | "connecting"
  | "connected"
  | "disconnected"
  | "failed";

interface P2PPeer {
  userId: string;    // Peer's user ID
  username: string;  // Peer's display name
}

interface P2PMessage {
  fromUserId: string;   // Sender's user ID
  channel: number;      // Channel number (0-7)
  payload: Uint8Array;  // Binary data
}

// UGC types are integer values:
// 0 = screenshot    - Player-captured screenshot
// 1 = video         - Player-captured video
// 2 = community     - Community-created content (levels, mods, etc.)
// 3 = game_managed  - Game-managed content (replays, saves)
// 4 = other         - Other UGC types
type UGCType = 0 | 1 | 2 | 3 | 4;

// UGC visibility is an integer value:
// 0 = public       - Anyone can view
// 1 = friends_only - Only friends can view
// 2 = private      - Only the creator can view
type UGCVisibility = 0 | 1 | 2;

interface RemoteFileMetadata {
  exists: boolean;     // Whether file exists
  key: string;         // Full storage key
  name: string;        // Filename
  lastModified: number; // Unix timestamp
  size: number;        // Size in bytes
  etag: string;        // Version identifier
}

interface EngineInstance {
  type: "GODOT" | "UNITY" | "UNREAL";

  // Send message to engine
  SendMessage(
    objectName: string,
    methodName: string,
    value?: string | number | boolean
  ): void;

  // Emscripten filesystem API
  FS: {
    readFile(path: string, opts?: Record<string, unknown>): string | Uint8Array;
    writeFile(path: string, data: string | ArrayBufferView, opts?: Record<string, unknown>): void;
    mkdirTree(path: string, mode?: number): void;
    syncfs(populate: boolean, callback?: (err: unknown) => void): void;
    analyzePath(path: string): { exists: boolean };
  };
}

type UserId = string;
type GameId = string;
type LobbyId = string;
type LeaderboardId = string;
type UGCId = string;