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 = Wavedash.getUser(); // sync getter

const response = await Wavedash.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
  p2p?: Partial<P2PConfig>;             // P2P networking configuration (see P2PConfig below)
}

interface P2PConfig {
  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 GameLaunchParams {
  lobby?: string;              // Lobby ID if the player followed an invite link
  [key: string]: string | undefined; // Any other wvdsh_-prefixed params
}

interface Leaderboard {
  id: Id<"leaderboards">;              // Leaderboard ID
  name: string;                        // Display name
  sortOrder: LeaderboardSortOrder;     // 0 = ASC, 1 = DESC
  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: Id<"users">;                  // Player's user ID
  username?: string;                    // Player's display name
  score: number;                        // Score value
  globalRank: number;                   // Current rank
  ugcId?: Id<"userGeneratedContent">;   // Attached UGC (optional)
  timestamp: number;                    // Submission timestamp
  metadata?: Uint8Array;                // Optional binary metadata
}

interface Lobby {
  lobbyId: Id<"lobbies">;            // 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: Id<"lobbies">;       // Lobby ID
  userId: Id<"users">;          // 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: Id<"lobbies">;       // Lobby ID
  userId: Id<"users">;          // Sender's ID
  username: string;             // Sender's name
  message: string;              // Message text
  timestamp: number;            // Timestamp
}

interface LobbyInvite {
  notificationId: string;       // Notification ID
  lobbyId: Id<"lobbies">;       // ID of the lobby you're invited to
  sender: {
    _id: Id<"users">;           // 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: Id<"users">;   // 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: Id<"lobbies">;
  peers: Record<Id<"users">, P2PPeer>;
  state: P2PConnectionState;
}

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

interface P2PPeer {
  userId: Id<"users">;   // Peer's user ID
  username: string;      // Peer's display name
}

interface P2PMessage {
  fromUserId: Id<"users">;   // 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 };
  };
}

import type { Id } from "@wvdsh/sdk-js";

type UserId = Id<"users">;
type LobbyId = Id<"lobbies">;
type LeaderboardId = Id<"leaderboards">;
type UGCId = Id<"userGeneratedContent">;