steamworks-ffi-node 0.3.1 → 0.4.0

package/dist/internal/SteamLeaderboardManager.d.ts

@@ -0,0 +1,338 @@
+import { SteamLibraryLoader } from './SteamLibraryLoader';
+import { SteamAPICore } from './SteamAPICore';
+import { LeaderboardEntry, LeaderboardInfo, LeaderboardScoreUploadResult, LeaderboardSortMethod, LeaderboardDisplayType, LeaderboardDataRequest, LeaderboardUploadScoreMethod } from '../types';
+/**
+ * SteamLeaderboardManager
+ *
+ * Manages all Steam leaderboard operations including:
+ * - Finding and creating leaderboards
+ * - Uploading scores with optional details
+ * - Downloading leaderboard entries (global, friends, around user)
+ * - Retrieving leaderboard metadata
+ *
+ * Leaderboards are persistent scoreboards stored on Steam servers that allow
+ * players to compete globally or with friends. Each entry can include a score
+ * and up to 64 int32 detail values for additional game-specific data.
+ *
+ * ✅ IMPLEMENTATION NOTE:
+ * This implementation uses ISteamUtils polling to retrieve callback results
+ * synchronously after async operations complete. This provides full access to
+ * Steam callback data without requiring a C++ addon:
+ *
+ * 1. Initiates the async operation (returns SteamAPICall_t handle)
+ * 2. Polls ISteamUtils::IsAPICallCompleted() to check completion
+ * 3. Calls ISteamUtils::GetAPICallResult() to retrieve result struct
+ * 4. Returns complete callback data (handles, ranks, scores, etc.)
+ *
+ * All async operations now return actual results:
+ * - findOrCreateLeaderboard/findLeaderboard: Returns LeaderboardInfo with handle
+ * - uploadScore: Returns upload result with ranks and success status
+ * - downloadLeaderboardEntries: Returns array of LeaderboardEntry objects
+ * - attachLeaderboardUGC: Returns true/false based on actual result
+ *
+ * @example
+ * ```typescript
+ * const leaderboardManager = new SteamLeaderboardManager(libraryLoader, apiCore);
+ *
+ * // Find or create a leaderboard
+ * const leaderboard = await leaderboardManager.findOrCreateLeaderboard(
+ *   'HighScores',
+ *   LeaderboardSortMethod.Descending,
+ *   LeaderboardDisplayType.Numeric
+ * );
+ *
+ * // Upload a score and get rank information
+ * const result = await leaderboardManager.uploadScore(
+ *   leaderboard.handle,
+ *   1000,
+ *   LeaderboardUploadScoreMethod.KeepBest
+ * );
+ * console.log(`New rank: ${result.globalRankNew}`);
+ *
+ * // Download top 10 entries
+ * const entries = await leaderboardManager.downloadLeaderboardEntries(
+ *   leaderboard.handle,
+ *   LeaderboardDataRequest.Global,
+ *   1,
+ *   10
+ * );
+ * entries.forEach(entry => {
+ *   console.log(`${entry.globalRank}. Score: ${entry.score}`);
+ * });
+ * ```
+ */
+export declare class SteamLeaderboardManager {
+    /** Steam library loader for FFI function calls */
+    private libraryLoader;
+    /** Steam API core for initialization and callback management */
+    private apiCore;
+    /** Callback poller for retrieving async operation results */
+    private callbackPoller;
+    /**
+     * Creates a new SteamLeaderboardManager instance
+     *
+     * @param libraryLoader - The Steam library loader for FFI calls
+     * @param apiCore - The Steam API core for lifecycle management
+     */
+    constructor(libraryLoader: SteamLibraryLoader, apiCore: SteamAPICore);
+    /**
+     * Find or create a leaderboard
+     *
+     * Searches for a leaderboard by name, and creates it if it doesn't exist.
+     * This is an asynchronous operation that communicates with Steam servers.
+     *
+     * @param name - Name of the leaderboard (max 128 UTF-8 bytes)
+     * @param sortMethod - How entries should be sorted
+     * @param displayType - How scores should be displayed
+     * @returns Promise resolving to leaderboard info, or null on error
+     *
+     * @example
+     * ```typescript
+     * // Create a high score leaderboard
+     * const leaderboard = await leaderboardManager.findOrCreateLeaderboard(
+     *   'HighScores',
+     *   LeaderboardSortMethod.Descending,  // Highest is best
+     *   LeaderboardDisplayType.Numeric
+     * );
+     *
+     * // Create a speedrun leaderboard
+     * const speedrun = await leaderboardManager.findOrCreateLeaderboard(
+     *   'FastestTime',
+     *   LeaderboardSortMethod.Ascending,   // Lowest is best
+     *   LeaderboardDisplayType.TimeMilliseconds
+     * );
+     * ```
+     *
+     * @remarks
+     * - Leaderboard names must be unique per game
+     * - Maximum name length is 128 UTF-8 bytes
+     * - Waits up to 5 seconds for Steam server response
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_FindOrCreateLeaderboard()` - Find/create leaderboard
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardName()` - Get leaderboard name
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardEntryCount()` - Get entry count
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardSortMethod()` - Get sort method
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardDisplayType()` - Get display type
+     */
+    findOrCreateLeaderboard(name: string, sortMethod: LeaderboardSortMethod, displayType: LeaderboardDisplayType): Promise<LeaderboardInfo | null>;
+    /**
+     * Find an existing leaderboard
+     *
+     * Searches for a leaderboard by name. Unlike findOrCreateLeaderboard(),
+     * this will not create the leaderboard if it doesn't exist.
+     *
+     * @param name - Name of the leaderboard to find
+     * @returns Promise resolving to leaderboard info, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const leaderboard = await leaderboardManager.findLeaderboard('HighScores');
+     * if (leaderboard) {
+     *   console.log(`[Steamworks] Found leaderboard with ${leaderboard.entryCount} entries`);
+     * } else {
+     *   console.log('[Steamworks] Leaderboard does not exist');
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if leaderboard doesn't exist
+     * - Waits up to 5 seconds for Steam server response
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_FindLeaderboard()` - Find existing leaderboard
+     */
+    findLeaderboard(name: string): Promise<LeaderboardInfo | null>;
+    /**
+     * Get information about a leaderboard
+     *
+     * Retrieves metadata for a leaderboard using its handle.
+     *
+     * @param handle - Leaderboard handle
+     * @returns Leaderboard information, or null on error
+     *
+     * @remarks
+     * - Synchronous operation, no Steam server communication needed
+     * - Handle must be from a previous find/create operation
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardName()` - Get leaderboard name
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardEntryCount()` - Get entry count
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardSortMethod()` - Get sort method
+     * - `SteamAPI_ISteamUserStats_GetLeaderboardDisplayType()` - Get display type
+     */
+    getLeaderboardInfo(handle: bigint): LeaderboardInfo | null;
+    /**
+     * Upload a score to a leaderboard
+     *
+     * Submits a score for the current user to the specified leaderboard.
+     * Can optionally include up to 64 int32 detail values.
+     *
+     * @param leaderboardHandle - Handle to the leaderboard
+     * @param score - Score value to upload
+     * @param uploadMethod - How to handle the score (keep best or force update)
+     * @param details - Optional array of detail values (max 64)
+     * @returns Promise resolving to upload result, or null on error
+     *
+     * @example
+     * ```typescript
+     * // Upload simple score (keep best)
+     * await leaderboardManager.uploadScore(
+     *   leaderboard.handle,
+     *   1000,
+     *   LeaderboardUploadScoreMethod.KeepBest
+     * );
+     *
+     * // Upload score with details (e.g., level, time, difficulty)
+     * await leaderboardManager.uploadScore(
+     *   leaderboard.handle,
+     *   5000,
+     *   LeaderboardUploadScoreMethod.KeepBest,
+     *   [10, 300, 2] // level 10, 300 seconds, difficulty 2
+     * );
+     *
+     * // Force update score (even if worse)
+     * await leaderboardManager.uploadScore(
+     *   leaderboard.handle,
+     *   750,
+     *   LeaderboardUploadScoreMethod.ForceUpdate
+     * );
+     * ```
+     *
+     * @remarks
+     * - KeepBest: Only updates if new score is better
+     * - ForceUpdate: Always updates to new score
+     * - Details array is limited to 64 int32 values
+     * - Waits up to 3 seconds for Steam server response
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_UploadLeaderboardScore()` - Upload score to leaderboard
+     */
+    uploadScore(leaderboardHandle: bigint, score: number, uploadMethod: LeaderboardUploadScoreMethod, details?: number[]): Promise<LeaderboardScoreUploadResult | null>;
+    /**
+     * Download leaderboard entries
+     *
+     * Retrieves a range of entries from a leaderboard. Can fetch global top scores,
+     * entries around the current user, or friend entries.
+     *
+     * @param leaderboardHandle - Handle to the leaderboard
+     * @param dataRequest - Type of data to request
+     * @param rangeStart - Start of range (1-based for global, offset for around user)
+     * @param rangeEnd - End of range (1-based for global, offset for around user)
+     * @returns Promise resolving to array of entries, or empty array on error
+     *
+     * @example
+     * ```typescript
+     * // Get top 10 global entries
+     * const top10 = await leaderboardManager.downloadLeaderboardEntries(
+     *   leaderboard.handle,
+     *   LeaderboardDataRequest.Global,
+     *   1,  // Start at rank 1
+     *   10  // End at rank 10
+     * );
+     *
+     * // Get entries around current user (3 above, 3 below)
+     * const aroundMe = await leaderboardManager.downloadLeaderboardEntries(
+     *   leaderboard.handle,
+     *   LeaderboardDataRequest.GlobalAroundUser,
+     *   -3,  // 3 entries above
+     *   3    // 3 entries below
+     * );
+     *
+     * // Get friend entries
+     * const friends = await leaderboardManager.downloadLeaderboardEntries(
+     *   leaderboard.handle,
+     *   LeaderboardDataRequest.Friends,
+     *   0,  // Ignored for friends
+     *   0   // Ignored for friends
+     * );
+     * ```
+     *
+     * @remarks
+     * - Global: rangeStart and rangeEnd are 1-based ranks [1, N]
+     * - GlobalAroundUser: rangeStart is negative offset, rangeEnd is positive offset
+     * - Friends: range parameters are ignored
+     * - Returns up to requested number of entries, or fewer if not available
+     * - Waits up to 3 seconds for Steam server response
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_DownloadLeaderboardEntries()` - Download leaderboard entries
+     * - `SteamAPI_ISteamUserStats_GetDownloadedLeaderboardEntry()` - Get individual entry data
+     */
+    downloadLeaderboardEntries(leaderboardHandle: bigint, dataRequest: LeaderboardDataRequest, rangeStart: number, rangeEnd: number): Promise<LeaderboardEntry[]>;
+    /**
+     * Download leaderboard entries for specific users
+     *
+     * Retrieves leaderboard entries for an arbitrary set of Steam users.
+     * Useful for comparing scores with specific players.
+     *
+     * @param leaderboardHandle - Handle to the leaderboard
+     * @param steamIds - Array of Steam IDs to retrieve (max 100)
+     * @returns Promise resolving to array of entries, or empty array on error
+     *
+     * @example
+     * ```typescript
+     * // Compare scores with specific players
+     * const playerIds = ['76561198012345678', '76561198087654321'];
+     * const entries = await leaderboardManager.downloadLeaderboardEntriesForUsers(
+     *   leaderboard.handle,
+     *   playerIds
+     * );
+     *
+     * entries.forEach(entry => {
+     *   console.log(`[Steamworks] ${entry.steamId}: ${entry.score} (rank ${entry.globalRank})`);
+     * });
+     * ```
+     *
+     * @remarks
+     * - Maximum 100 users per request
+     * - Only returns entries for users who have scores
+     * - Only one outstanding request at a time
+     * - Waits up to 3 seconds for Steam server response
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_DownloadLeaderboardEntriesForUsers()` - Download entries for users
+     * - `SteamAPI_ISteamUserStats_GetDownloadedLeaderboardEntry()` - Get individual entry data
+     */
+    downloadLeaderboardEntriesForUsers(leaderboardHandle: bigint, steamIds: string[]): Promise<LeaderboardEntry[]>;
+    /**
+     * Attach user-generated content to a leaderboard entry
+     *
+     * Associates a piece of UGC (like a replay file, screenshot, or level)
+     * with the current user's leaderboard entry. The UGC must first be shared
+     * using ISteamRemoteStorage::FileShare().
+     *
+     * @param leaderboardHandle - Handle to the leaderboard
+     * @param ugcHandle - Handle to the shared UGC content
+     * @returns Promise resolving to true if successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // First, share a file to get UGC handle
+     * // const ugcHandle = await steamRemoteStorage.fileShare('replay.dat');
+     *
+     * // Then attach it to leaderboard entry
+     * const ugcHandle = BigInt('123456789'); // From FileShare
+     * const success = await leaderboardManager.attachLeaderboardUGC(
+     *   leaderboard.handle,
+     *   ugcHandle
+     * );
+     *
+     * if (success) {
+     *   console.log('[Steamworks] UGC attached to leaderboard entry');
+     * }
+     * ```
+     *
+     * @remarks
+     * - UGC must be created with ISteamRemoteStorage::FileShare() first
+     * - Only one UGC item can be attached per leaderboard entry
+     * - Attaching new UGC replaces any previously attached UGC
+     * - Common use cases: replays, screenshots, custom levels
+     * - Waits up to 3 seconds for Steam server response
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_AttachLeaderboardUGC()` - Attach UGC to leaderboard entry
+     */
+    attachLeaderboardUGC(leaderboardHandle: bigint, ugcHandle: bigint): Promise<boolean>;
+}
+//# sourceMappingURL=SteamLeaderboardManager.d.ts.map

package/dist/internal/SteamLeaderboardManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SteamLeaderboardManager.d.ts","sourceRoot":"","sources":["../../src/internal/SteamLeaderboardManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,OAAO,EACL,gBAAgB,EAChB,eAAe,EACf,4BAA4B,EAC5B,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,4BAA4B,EAM7B,MAAM,UAAU,CAAC;AA+DlB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,qBAAa,uBAAuB;IAClC,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAqB;IAE1C,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAe;IAE9B,6DAA6D;IAC7D,OAAO,CAAC,cAAc,CAAsB;IAE5C;;;;;OAKG;gBACS,aAAa,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY;IAUpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACG,uBAAuB,CAC3B,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,qBAAqB,EACjC,WAAW,EAAE,sBAAsB,GAClC,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAqDlC;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAmDpE;;;;;;;;;;;;;;;;;OAiBG;IACH,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAgD1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6CG;IACG,WAAW,CACf,iBAAiB,EAAE,MAAM,EACzB,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,4BAA4B,EAC1C,OAAO,CAAC,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,4BAA4B,GAAG,IAAI,CAAC;IA8E/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiDG;IACG,0BAA0B,CAC9B,iBAAiB,EAAE,MAAM,EACzB,WAAW,EAAE,sBAAsB,EACnC,UAAU,EAAE,MAAM,EAClB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAwF9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACG,kCAAkC,CACtC,iBAAiB,EAAE,MAAM,EACzB,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAkG9B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,oBAAoB,CACxB,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC;CAmDpB"}