steamworks-ffi-node 0.3.0 → 0.4.0

package/dist/internal/SteamAchievementManager.js

@@ -36,15 +36,62 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SteamAchievementManager = void 0;
 const koffi = __importStar(require("koffi"));
 /**
- * Manages all Steam achievement operations
+ * SteamAchievementManager
+ *
+ * Manages all Steam achievement operations including:
+ * - Core operations (get, unlock, clear, check status)
+ * - Visual features (icons, progress notifications)
+ * - Progress tracking (get limits for progress bars)
+ * - Friend comparisons (see friend achievements)
+ * - Global statistics (unlock percentages, popularity sorting)
+ * - Testing tools (reset stats/achievements)
+ *
+ * @example
+ * ```typescript
+ * const achievementManager = new SteamAchievementManager(libraryLoader, apiCore);
+ * const achievements = await achievementManager.getAllAchievements();
+ * await achievementManager.unlockAchievement('ACH_WIN_ONE_GAME');
+ * ```
  */
 class SteamAchievementManager {
+    /**
+     * Creates a new SteamAchievementManager instance
+     *
+     * @param libraryLoader - The Steam library loader for FFI calls
+     * @param apiCore - The Steam API core for lifecycle management
+     */
     constructor(libraryLoader, apiCore) {
         this.libraryLoader = libraryLoader;
         this.apiCore = apiCore;
     }
     /**
      * Get all achievements from Steam
+     *
+     * Retrieves complete achievement data including unlock status and timestamps.
+     * Automatically runs Steam callbacks to ensure latest data is available.
+     *
+     * @returns Promise resolving to array of all achievements, or empty array on error
+     *
+     * @example
+     * ```typescript
+     * const achievements = await achievementManager.getAllAchievements();
+     * console.log(`[Steamworks] Found ${achievements.length} achievements`);
+     * achievements.forEach(ach => {
+     *   console.log(`[Steamworks] ${ach.displayName}: ${ach.unlocked ? 'Unlocked' : 'Locked'}`);
+     * });
+     * ```
+     *
+     * @remarks
+     * - Returns empty array if Steam API is not initialized
+     * - Includes display name, description, unlock status, and unlock time
+     * - Unlock time is a Unix timestamp (seconds since epoch)
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_RunCallbacks()` - Process Steam callbacks
+     * - `SteamAPI_ISteamUserStats_GetNumAchievements()` - Get total achievement count
+     * - `SteamAPI_ISteamUserStats_GetAchievementName()` - Get achievement API name
+     * - `SteamAPI_ISteamUserStats_GetAchievementDisplayAttribute()` - Get display attributes
+     * - `SteamAPI_ISteamUserStats_GetAchievementAndUnlockTime()` - Get unlock status and time
      */
     async getAllAchievements() {
         if (!this.apiCore.isInitialized()) {
@@ -87,7 +134,7 @@ class SteamAchievementManager {
                     });
                 }
                 catch (error) {
-                    console.warn(`Failed to get achievement ${i}:`, error.message);
+                    console.warn(`[Steamworks] Failed to get achievement ${i}:`, error.message);
                 }
             }
             return achievements;
@@ -98,7 +145,32 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Unlock achievement in Steam
+     * Unlock an achievement in Steam
+     *
+     * Permanently unlocks the specified achievement and syncs to Steam servers.
+     * Shows Steam overlay notification if enabled.
+     *
+     * @param achievementName - The API name of the achievement to unlock
+     * @returns Promise resolving to true if successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const success = await achievementManager.unlockAchievement('ACH_WIN_ONE_GAME');
+     * if (success) {
+     *   console.log('[Steamworks] Achievement unlocked!');
+     * }
+     * ```
+     *
+     * @remarks
+     * - Achievement must be configured in Steamworks Partner site
+     * - Changes are immediately stored to Steam servers
+     * - Steam overlay will show unlock notification
+     * - Cannot unlock already unlocked achievements (returns true)
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_SetAchievement()` - Mark achievement as unlocked
+     * - `SteamAPI_ISteamUserStats_StoreStats()` - Store achievement to Steam servers
+     * - `SteamAPI_RunCallbacks()` - Process unlock notification
      */
     async unlockAchievement(achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -139,7 +211,32 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Clear achievement in Steam (for testing)
+     * Clear an achievement in Steam (for testing purposes)
+     *
+     * Removes the unlock status of an achievement. Should only be used for testing.
+     * Changes are immediately stored to Steam servers.
+     *
+     * @param achievementName - The API name of the achievement to clear
+     * @returns Promise resolving to true if successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Clear achievement for testing
+     * await achievementManager.clearAchievement('ACH_WIN_ONE_GAME');
+     * ```
+     *
+     * @remarks
+     * - Only use for testing/debugging purposes
+     * - Achievement must be configured in Steamworks Partner site
+     * - Changes are immediately stored to Steam servers
+     * - Cannot clear already locked achievements (returns true)
+     *
+     * @warning This permanently removes the achievement unlock from user's profile
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_ClearAchievement()` - Mark achievement as locked
+     * - `SteamAPI_ISteamUserStats_StoreStats()` - Store change to Steam servers
+     * - `SteamAPI_RunCallbacks()` - Process the change
      */
     async clearAchievement(achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -180,7 +277,28 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Check if achievement is unlocked
+     * Check if an achievement is unlocked
+     *
+     * Queries Steam for the current unlock status of a specific achievement.
+     *
+     * @param achievementName - The API name of the achievement to check
+     * @returns Promise resolving to true if unlocked, false if locked or error
+     *
+     * @example
+     * ```typescript
+     * const isUnlocked = await achievementManager.isAchievementUnlocked('ACH_WIN_ONE_GAME');
+     * if (isUnlocked) {
+     *   console.log('[Steamworks] Player has already won one game');
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns false if Steam API is not initialized
+     * - Returns false if achievement doesn't exist
+     * - Returns false on any error (check console for details)
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetAchievement()` - Get achievement unlock status
      */
     async isAchievementUnlocked(achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -202,14 +320,52 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get achievement by API name
+     * Get a specific achievement by its API name
+     *
+     * Retrieves complete data for a single achievement.
+     *
+     * @param achievementName - The API name of the achievement to retrieve
+     * @returns Promise resolving to achievement data, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const achievement = await achievementManager.getAchievementByName('ACH_WIN_ONE_GAME');
+     * if (achievement) {
+     *   console.log(`[Steamworks] ${achievement.displayName}: ${achievement.description}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Calls getAllAchievements() internally, so may be slower than batch operations
+     * - Returns null if achievement doesn't exist
+     * - Returns null if Steam API is not initialized
+     *
+     * Steamworks SDK Functions:
+     * - Uses getAllAchievements() which calls multiple SDK functions
      */
     async getAchievementByName(achievementName) {
         const achievements = await this.getAllAchievements();
         return achievements.find(a => a.apiName === achievementName) || null;
     }
     /**
-     * Get total number of achievements
+     * Get the total number of achievements configured for this game
+     *
+     * Returns the count of all achievements defined in Steamworks Partner site.
+     *
+     * @returns Promise resolving to total achievement count, or 0 on error
+     *
+     * @example
+     * ```typescript
+     * const total = await achievementManager.getTotalAchievementCount();
+     * console.log(`[Steamworks] This game has ${total} achievements`);
+     * ```
+     *
+     * @remarks
+     * - Returns 0 if Steam API is not initialized
+     * - Count includes both locked and unlocked achievements
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetNumAchievements()` - Get total achievement count
      */
     async getTotalAchievementCount() {
         if (!this.apiCore.isInitialized()) {
@@ -228,16 +384,56 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get number of unlocked achievements
+     * Get the number of achievements the user has unlocked
+     *
+     * Counts how many achievements the current user has unlocked.
+     *
+     * @returns Promise resolving to count of unlocked achievements
+     *
+     * @example
+     * ```typescript
+     * const total = await achievementManager.getTotalAchievementCount();
+     * const unlocked = await achievementManager.getUnlockedAchievementCount();
+     * console.log(`[Steamworks] Progress: ${unlocked}/${total} (${(unlocked/total*100).toFixed(1)}%)`);
+     * ```
+     *
+     * @remarks
+     * - Calls getAllAchievements() internally to count unlocked achievements
+     * - Returns 0 if Steam API is not initialized
+     *
+     * Steamworks SDK Functions:
+     * - Uses getAllAchievements() which calls multiple SDK functions
      */
     async getUnlockedAchievementCount() {
         const achievements = await this.getAllAchievements();
         return achievements.filter(a => a.unlocked).length;
     }
     /**
-     * Get achievement icon handle
-     * Returns icon handle for use with ISteamUtils::GetImageRGBA()
-     * Returns 0 if no icon set or still loading
+     * Get the icon handle for an achievement
+     *
+     * Returns an icon handle that can be used with ISteamUtils::GetImageRGBA()
+     * to retrieve the actual icon image data.
+     *
+     * @param achievementName - The API name of the achievement
+     * @returns Promise resolving to icon handle (0 if no icon or still loading)
+     *
+     * @example
+     * ```typescript
+     * const iconHandle = await achievementManager.getAchievementIcon('ACH_WIN_ONE_GAME');
+     * if (iconHandle > 0) {
+     *   // Use ISteamUtils::GetImageRGBA() to get actual image data
+     *   console.log(`[Steamworks] Icon handle: ${iconHandle}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns 0 if no icon is set for the achievement
+     * - Returns 0 if icon is still being fetched from Steam
+     * - Wait for UserAchievementIconFetched_t callback if 0 is returned
+     * - Icon handle is valid until Steam API shutdown
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetAchievementIcon()` - Get achievement icon handle
      */
     async getAchievementIcon(achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -260,8 +456,33 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Indicate achievement progress to user
-     * Shows a progress notification in Steam overlay
+     * Show achievement progress notification to user
+     *
+     * Displays a progress notification in the Steam overlay showing current/max progress.
+     * Useful for achievements that require multiple steps or cumulative actions.
+     *
+     * @param achievementName - The API name of the achievement
+     * @param currentProgress - Current progress value
+     * @param maxProgress - Maximum progress value needed to unlock
+     * @returns Promise resolving to true if successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Show "Win 50 games" progress: 25/50
+     * await achievementManager.indicateAchievementProgress('ACH_WIN_50_GAMES', 25, 50);
+     *
+     * // Update progress when player wins another game
+     * await achievementManager.indicateAchievementProgress('ACH_WIN_50_GAMES', 26, 50);
+     * ```
+     *
+     * @remarks
+     * - Shows notification in Steam overlay (if enabled)
+     * - Does NOT unlock the achievement automatically
+     * - Call unlockAchievement() when currentProgress >= maxProgress
+     * - Notification only shows if progress has changed
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_IndicateAchievementProgress()` - Show progress notification
      */
     async indicateAchievementProgress(achievementName, currentProgress, maxProgress) {
         if (!this.apiCore.isInitialized()) {
@@ -292,7 +513,30 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get achievement progress limits (for integer-based progress)
+     * Get achievement progress limits (integer-based)
+     *
+     * Retrieves the minimum and maximum progress values for an achievement that
+     * uses integer-based progress tracking.
+     *
+     * @param achievementName - The API name of the achievement
+     * @returns Promise resolving to progress limits object, or null if not configured
+     *
+     * @example
+     * ```typescript
+     * const limits = await achievementManager.getAchievementProgressLimitsInt('ACH_WIN_50_GAMES');
+     * if (limits) {
+     *   console.log(`[Steamworks] Progress range: ${limits.minProgress} to ${limits.maxProgress}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if achievement has no progress tracking configured
+     * - Use for achievements with integer progress (e.g., "Win 50 games")
+     * - For float-based progress, use getAchievementProgressLimitsFloat()
+     * - Must be configured in Steamworks Partner site
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetAchievementProgressLimitsInt32()` - Get integer progress limits
      */
     async getAchievementProgressLimitsInt(achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -322,7 +566,30 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get achievement progress limits (for float-based progress)
+     * Get achievement progress limits (float-based)
+     *
+     * Retrieves the minimum and maximum progress values for an achievement that
+     * uses floating-point progress tracking.
+     *
+     * @param achievementName - The API name of the achievement
+     * @returns Promise resolving to progress limits object, or null if not configured
+     *
+     * @example
+     * ```typescript
+     * const limits = await achievementManager.getAchievementProgressLimitsFloat('ACH_TRAVEL_100KM');
+     * if (limits) {
+     *   console.log(`[Steamworks] Need to travel ${limits.maxProgress}km`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if achievement has no progress tracking configured
+     * - Use for achievements with decimal progress (e.g., "Travel 100.5km")
+     * - For integer-based progress, use getAchievementProgressLimitsInt()
+     * - Must be configured in Steamworks Partner site
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetAchievementProgressLimitsFloat()` - Get float progress limits
      */
     async getAchievementProgressLimitsFloat(achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -352,8 +619,37 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Request stats for another user (friend)
-     * This is async - you need to wait for the callback before calling getUserAchievement
+     * Request achievement stats for another user (friend)
+     *
+     * Initiates an asynchronous request to fetch achievement data for another Steam user.
+     * Must be called before getUserAchievement() can return data for that user.
+     *
+     * @param steamId - The Steam ID of the user (as string, e.g., "76561197960287930")
+     * @returns Promise resolving to true if request sent, false on error
+     *
+     * @example
+     * ```typescript
+     * const friendId = '76561197960287930';
+     *
+     * // Request friend's stats
+     * await achievementManager.requestUserStats(friendId);
+     *
+     * // Wait for callback and process
+     * await new Promise(resolve => setTimeout(resolve, 2000));
+     * steam.runCallbacks();
+     *
+     * // Now can get friend's achievement
+     * const achievement = await achievementManager.getUserAchievement(friendId, 'ACH_WIN_ONE_GAME');
+     * ```
+     *
+     * @remarks
+     * - This is an asynchronous operation - wait for callback
+     * - Friend must have played the game to have stats
+     * - Wait 1-2 seconds and call runCallbacks() before querying
+     * - Request times out after some period (varies)
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_RequestUserStats()` - Request user's achievement data
      */
     async requestUserStats(steamId) {
         if (!this.apiCore.isInitialized()) {
@@ -385,7 +681,41 @@ class SteamAchievementManager {
     }
     /**
      * Get achievement status for another user (friend)
-     * Must call requestUserStats() first and wait for callback
+     *
+     * Retrieves complete achievement data for another Steam user, including their
+     * unlock status and unlock time.
+     *
+     * @param steamId - The Steam ID of the user (as string)
+     * @param achievementName - The API name of the achievement
+     * @returns Promise resolving to user achievement data, or null if not available
+     *
+     * @example
+     * ```typescript
+     * // First request the user's stats
+     * await achievementManager.requestUserStats('76561197960287930');
+     * await new Promise(resolve => setTimeout(resolve, 2000));
+     * steam.runCallbacks();
+     *
+     * // Now get specific achievement
+     * const achievement = await achievementManager.getUserAchievement(
+     *   '76561197960287930',
+     *   'ACH_WIN_ONE_GAME'
+     * );
+     *
+     * if (achievement && achievement.unlocked) {
+     *   const date = new Date(achievement.unlockTime * 1000);
+     *   console.log(`[Steamworks] Friend unlocked on: ${date.toLocaleDateString()}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Must call requestUserStats() first and wait for callback
+     * - Returns null if stats not yet loaded or achievement doesn't exist
+     * - Friend must have played the game
+     * - Includes unlock time as Unix timestamp
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetUserAchievementAndUnlockTime()` - Get user's achievement status
      */
     async getUserAchievement(steamId, achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -425,8 +755,36 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Request global achievement percentages
-     * This is async - wait for callback before calling getAchievementAchievedPercent
+     * Request global achievement unlock percentages
+     *
+     * Initiates an asynchronous request to fetch global achievement statistics
+     * (what percentage of all players have unlocked each achievement).
+     *
+     * @returns Promise resolving to true if request sent, false on error
+     *
+     * @example
+     * ```typescript
+     * // Request global percentages
+     * await achievementManager.requestGlobalAchievementPercentages();
+     *
+     * // Wait for callback
+     * await new Promise(resolve => setTimeout(resolve, 2000));
+     * steam.runCallbacks();
+     *
+     * // Now can get percentages
+     * const percent = await achievementManager.getAchievementAchievedPercent('ACH_WIN_ONE_GAME');
+     * console.log(`[Steamworks] ${percent}% of players have unlocked this achievement`);
+     * ```
+     *
+     * @remarks
+     * - This is an asynchronous operation - wait for callback
+     * - Required before calling getAchievementAchievedPercent()
+     * - Required before calling getAllAchievementsSortedByPopularity()
+     * - Wait 2-3 seconds and call runCallbacks() before querying
+     * - Data is cached after first successful request
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_RequestGlobalAchievementPercentages()` - Request global percentages
      */
     async requestGlobalAchievementPercentages() {
         if (!this.apiCore.isInitialized()) {
@@ -456,8 +814,33 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get percentage of users who unlocked a specific achievement
-     * Must call requestGlobalAchievementPercentages() first
+     * Get global unlock percentage for a specific achievement
+     *
+     * Returns what percentage of all players have unlocked this achievement.
+     *
+     * @param achievementName - The API name of the achievement
+     * @returns Promise resolving to percentage (0-100), or null if not available
+     *
+     * @example
+     * ```typescript
+     * const percent = await achievementManager.getAchievementAchievedPercent('ACH_WIN_ONE_GAME');
+     * if (percent !== null) {
+     *   if (percent < 10) {
+     *     console.log(`[Steamworks] Rare achievement! Only ${percent.toFixed(2)}% have this`);
+     *   } else {
+     *     console.log(`[Steamworks] Common achievement: ${percent.toFixed(2)}% unlocked`);
+     *   }
+     * }
+     * ```
+     *
+     * @remarks
+     * - Must call requestGlobalAchievementPercentages() first
+     * - Returns null if global stats not yet loaded
+     * - Percentage is between 0.0 and 100.0
+     * - Data represents all players across all platforms
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetAchievementAchievedPercent()` - Get global unlock percentage
      */
     async getAchievementAchievedPercent(achievementName) {
         if (!this.apiCore.isInitialized()) {
@@ -485,8 +868,37 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get all achievements with global unlock percentages
-     * Must call requestGlobalAchievementPercentages() first and wait for callback
+     * Get all achievements with their global unlock percentages
+     *
+     * Combines achievement data with global statistics to show what percentage
+     * of players have unlocked each achievement.
+     *
+     * @returns Promise resolving to array of achievements with global stats
+     *
+     * @example
+     * ```typescript
+     * // Request global data first
+     * await achievementManager.requestGlobalAchievementPercentages();
+     * await new Promise(resolve => setTimeout(resolve, 2000));
+     * steam.runCallbacks();
+     *
+     * // Get all achievements with percentages
+     * const achievements = await achievementManager.getAllAchievementsWithGlobalStats();
+     *
+     * // Find rarest achievement
+     * const rarest = achievements.reduce((prev, curr) =>
+     *   curr.globalUnlockPercentage < prev.globalUnlockPercentage ? curr : prev
+     * );
+     * console.log(`[Steamworks] Rarest: ${rarest.displayName} (${rarest.globalUnlockPercentage.toFixed(2)}%)`);
+     * ```
+     *
+     * @remarks
+     * - Must call requestGlobalAchievementPercentages() first
+     * - Iterates through all achievements to fetch percentages
+     * - May return 0% for achievements where data is unavailable
+     *
+     * Steamworks SDK Functions:
+     * - Uses getAllAchievements() and getAchievementAchievedPercent()
      */
     async getAllAchievementsWithGlobalStats() {
         const achievements = await this.getAllAchievements();
@@ -504,8 +916,31 @@ class SteamAchievementManager {
         return result;
     }
     /**
-     * Get most achieved achievement info
-     * Returns iterator for use with getNextMostAchievedAchievementInfo
+     * Get the most achieved achievement
+     *
+     * Returns the achievement with the highest global unlock percentage.
+     * Provides an iterator for use with getNextMostAchievedAchievementInfo().
+     *
+     * @returns Promise resolving to most achieved achievement data with iterator, or null
+     *
+     * @example
+     * ```typescript
+     * const mostAchieved = await achievementManager.getMostAchievedAchievementInfo();
+     * if (mostAchieved) {
+     *   console.log(`[Steamworks] Most achieved: ${mostAchieved.apiName}`);
+     *   console.log(`[Steamworks] Unlocked by: ${mostAchieved.percent.toFixed(2)}% of players`);
+     *   console.log(`[Steamworks] You ${mostAchieved.unlocked ? 'have' : 'don\'t have'} it`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Must call requestGlobalAchievementPercentages() first
+     * - Returns -1 iterator if no data available
+     * - Use iterator with getNextMostAchievedAchievementInfo() to iterate
+     * - Ordered by highest percentage first
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetMostAchievedAchievementInfo()` - Get most achieved achievement
      */
     async getMostAchievedAchievementInfo() {
         if (!this.apiCore.isInitialized()) {
@@ -536,7 +971,43 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get next most achieved achievement info (iterate by popularity)
+     * Get the next most achieved achievement (iterate by popularity)
+     *
+     * Continues iteration through achievements ordered by global unlock percentage.
+     * Use the iterator from getMostAchievedAchievementInfo() or previous call.
+     *
+     * @param previousIterator - Iterator from previous call
+     * @returns Promise resolving to next achievement data with iterator, or null if end
+     *
+     * @example
+     * ```typescript
+     * // Get top 5 most achieved achievements
+     * const top5 = [];
+     * let current = await achievementManager.getMostAchievedAchievementInfo();
+     *
+     * if (current) {
+     *   top5.push(current);
+     *
+     *   for (let i = 0; i < 4; i++) {
+     *     const next = await achievementManager.getNextMostAchievedAchievementInfo(current.iterator);
+     *     if (!next) break;
+     *     top5.push(next);
+     *     current = next;
+     *   }
+     * }
+     *
+     * top5.forEach((ach, i) => {
+     *   console.log(`[Steamworks] ${i + 1}. ${ach.apiName}: ${ach.percent.toFixed(2)}%`);
+     * });
+     * ```
+     *
+     * @remarks
+     * - Must call requestGlobalAchievementPercentages() first
+     * - Returns null when iteration is complete (iterator === -1)
+     * - Achievements ordered from highest to lowest percentage
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetNextMostAchievedAchievementInfo()` - Get next achievement by popularity
      */
     async getNextMostAchievedAchievementInfo(previousIterator) {
         if (!this.apiCore.isInitialized()) {
@@ -567,8 +1038,42 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get all achievements sorted by global unlock percentage (most achieved first)
-     * Must call requestGlobalAchievementPercentages() first
+     * Get all achievements sorted by global unlock percentage
+     *
+     * Returns complete achievement list ordered from most to least achieved.
+     * Includes full achievement details with global unlock percentages.
+     *
+     * @returns Promise resolving to sorted array of achievements with global stats
+     *
+     * @example
+     * ```typescript
+     * // Request global data
+     * await achievementManager.requestGlobalAchievementPercentages();
+     * await new Promise(resolve => setTimeout(resolve, 2000));
+     * steam.runCallbacks();
+     *
+     * // Get sorted achievements
+     * const sorted = await achievementManager.getAllAchievementsSortedByPopularity();
+     *
+     * console.log('[Steamworks] Most to Least Achieved:');
+     * sorted.forEach((ach, i) => {
+     *   console.log(`[Steamworks] ${i + 1}. ${ach.displayName}: ${ach.globalUnlockPercentage.toFixed(2)}%`);
+     * });
+     *
+     * // Find rarest achievements
+     * const rare = sorted.filter(a => a.globalUnlockPercentage < 5);
+     * console.log(`[Steamworks] ${rare.length} rare achievements (< 5% unlock rate)`);
+     * ```
+     *
+     * @remarks
+     * - Must call requestGlobalAchievementPercentages() first
+     * - Returns empty array if no global data available
+     * - Sorted from highest to lowest percentage
+     * - Includes display names and descriptions
+     *
+     * Steamworks SDK Functions:
+     * - Uses getMostAchievedAchievementInfo() and getNextMostAchievedAchievementInfo()
+     * - `SteamAPI_ISteamUserStats_GetAchievementDisplayAttribute()` - Get display attributes
      */
     async getAllAchievementsSortedByPopularity() {
         const results = [];
@@ -613,8 +1118,41 @@ class SteamAchievementManager {
         return results;
     }
     /**
-     * Reset all stats and optionally achievements
-     * WARNING: This clears ALL user stats and achievements!
+     * Reset all user stats and optionally achievements
+     *
+     * Permanently clears all statistics and optionally all achievements for the current user.
+     * Changes are immediately stored to Steam servers.
+     *
+     * @param includeAchievements - If true, also clears all achievements (default: false)
+     * @returns Promise resolving to true if successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Reset only stats, keep achievements
+     * await achievementManager.resetAllStats(false);
+     *
+     * // Reset everything including achievements
+     * await achievementManager.resetAllStats(true);
+     * ```
+     *
+     * @warning
+     * **THIS PERMANENTLY DELETES USER DATA!**
+     * - All stats are set to 0
+     * - If includeAchievements=true, all achievements are locked
+     * - Changes are immediately synced to Steam servers
+     * - Cannot be undone
+     * - Only use for testing/debugging
+     *
+     * @remarks
+     * - Use with extreme caution - this affects user's permanent record
+     * - Recommended only for development/testing accounts
+     * - Does not affect other users or global statistics
+     * - Changes visible immediately in Steam overlay
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_ResetAllStats()` - Reset all stats and optionally achievements
+     * - `SteamAPI_ISteamUserStats_StoreStats()` - Store reset to Steam servers
+     * - `SteamAPI_RunCallbacks()` - Process the reset operation
      */
     async resetAllStats(includeAchievements = false) {
         if (!this.apiCore.isInitialized()) {
@@ -654,7 +1192,38 @@ class SteamAchievementManager {
         }
     }
     /**
-     * Get all achievements with icon handles
+     * Get all achievements with their icon handles
+     *
+     * Returns complete achievement list with icon handles that can be used
+     * to retrieve actual icon image data via ISteamUtils::GetImageRGBA().
+     *
+     * @returns Promise resolving to array of achievements with icon handles
+     *
+     * @example
+     * ```typescript
+     * const achievements = await achievementManager.getAllAchievementsWithIcons();
+     *
+     * achievements.forEach(ach => {
+     *   console.log(`[Steamworks] ${ach.displayName}:`);
+     *   console.log(`[Steamworks]   Status: ${ach.unlocked ? 'Unlocked' : 'Locked'}`);
+     *   console.log(`[Steamworks]   Icon Handle: ${ach.iconHandle}`);
+     *
+     *   if (ach.iconHandle > 0) {
+     *     // Use ISteamUtils::GetImageRGBA() to get actual image
+     *     // const imageData = steamUtils.getImageRGBA(ach.iconHandle);
+     *   }
+     * });
+     * ```
+     *
+     * @remarks
+     * - Icon handle of 0 means no icon or still loading
+     * - Icon handles are valid until Steam API shutdown
+     * - Use ISteamUtils interface to convert handles to image data
+     * - May trigger icon fetching if not yet cached
+     *
+     * Steamworks SDK Functions:
+     * - Uses getAllAchievements() and getAchievementIcon()
+     * - `SteamAPI_ISteamUserStats_GetAchievementIcon()` - Get icon handle for each achievement
      */
     async getAllAchievementsWithIcons() {
         const achievements = await this.getAllAchievements();