steamworks-ffi-node 0.3.0 → 0.4.0

package/dist/internal/SteamStatsManager.js

@@ -36,10 +36,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SteamStatsManager = void 0;
 const koffi = __importStar(require("koffi"));
 /**
- * Manages Steam user statistics operations
- * Handles getting/setting stats, global stats, and friend stats
+ * SteamStatsManager
+ *
+ * Manages all Steam user statistics operations including:
+ * - User stats (get/set integer and float values)
+ * - Average rate stats (for tracking rates over time)
+ * - Friend/user stats (view stats of other players)
+ * - Global stats (aggregate statistics across all players)
+ * - Global stat history (historical data over time)
+ *
+ * Stats are different from achievements - they are numeric values that can increase/decrease
+ * and are used for leaderboards, progress tracking, and game analytics.
+ *
+ * @example
+ * ```typescript
+ * const statsManager = new SteamStatsManager(libraryLoader, apiCore);
+ *
+ * // Set and get player stats
+ * await statsManager.setStatInt('total_kills', 100);
+ * const kills = await statsManager.getStatInt('total_kills');
+ *
+ * // Get global stats
+ * await statsManager.requestGlobalStats(7);
+ * const globalKills = await statsManager.getGlobalStatInt('total_kills');
+ * ```
  */
 class SteamStatsManager {
+    /**
+     * Creates a new SteamStatsManager 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;
@@ -48,17 +76,35 @@ class SteamStatsManager {
     // User Stats Operations (Get/Set)
     // ========================================
     /**
-     * Get an integer stat value
+     * Get an integer stat value for the current user
      *
-     * @param statName - Name of the stat to retrieve
-     * @returns The stat value, or null if not found/error
+     * Retrieves a 32-bit integer stat value from Steam. Stats are numeric values
+     * that track player progress and can be used for leaderboards and analytics.
+     *
+     * @param statName - Name of the stat to retrieve (as defined in Steamworks Partner site)
+     * @returns SteamStat object with name, value, and type, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * const killsStat = await statsManager.getStatInt('total_kills');
+     * if (killsStat) {
+     *   console.log(`[Steamworks] ${killsStat.name}: ${killsStat.value}`);
+     *   // Access value directly: killsStat.value
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if Steam API is not initialized
+     * - Stat names are case-sensitive and must match Steamworks configuration
+     * - Use getStatFloat() for decimal values
+     * - Returns structured SteamStat object with full metadata
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetStatInt32()` - Get int32 stat value
      */
     async getStatInt(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -67,31 +113,51 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetStatInt32(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'int32');
-                console.log(`📊 Got stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value,
+                    type: 'int'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting stat "${statName}":`, error.message);
             return null;
         }
     }
     /**
-     * Get a float stat value
+     * Get a float stat value for the current user
      *
-     * @param statName - Name of the stat to retrieve
-     * @returns The stat value, or null if not found/error
+     * Retrieves a floating-point stat value from Steam. Use this for stats that
+     * require decimal precision (e.g., average accuracy, distance traveled).
+     *
+     * @param statName - Name of the stat to retrieve (as defined in Steamworks Partner site)
+     * @returns SteamStat object with name, value, and type, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * const accuracyStat = await statsManager.getStatFloat('shooting_accuracy');
+     * if (accuracyStat) {
+     *   console.log(`[Steamworks] ${accuracyStat.name}: ${(accuracyStat.value * 100).toFixed(2)}%`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if Steam API is not initialized
+     * - Use getStatInt() for whole number values
+     * - Returns structured SteamStat object with full metadata
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetStatFloat()` - Get float stat value
      */
     async getStatFloat(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -100,26 +166,49 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetStatFloat(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'float');
-                console.log(`📊 Got stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value,
+                    type: 'float'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting stat "${statName}":`, error.message);
             return null;
         }
     }
     /**
-     * Set an integer stat value
+     * Set an integer stat value for the current user
      *
-     * @param statName - Name of the stat to set
+     * Updates a 32-bit integer stat value and immediately stores it to Steam servers.
+     * The new value will be visible in your Steam profile and can trigger achievements.
+     *
+     * @param statName - Name of the stat to set (as defined in Steamworks Partner site)
      * @param value - Integer value to set
      * @returns true if successful, false otherwise
      *
+     * @example
+     * ```typescript
+     * // Increment kill count
+     * const currentKills = await statsManager.getStatInt('total_kills') || 0;
+     * const success = await statsManager.setStatInt('total_kills', currentKills + 1);
+     * if (success) {
+     *   console.log('[Steamworks] Kill count updated!');
+     * }
+     * ```
+     *
+     * @remarks
+     * - Automatically calls StoreStats() to save to Steam servers
+     * - Runs callbacks to process the store operation
+     * - Can trigger stat-based achievements
+     * - Use setStatFloat() for decimal values
+     *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_SetStatInt32()` - Set int32 stat value
      * - `SteamAPI_ISteamUserStats_StoreStats()` - Store stats to Steam servers
@@ -127,7 +216,7 @@ class SteamStatsManager {
      */
     async setStatInt(statName, value) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -137,33 +226,50 @@ class SteamStatsManager {
                 // Store the stats to Steam servers
                 const stored = this.libraryLoader.SteamAPI_ISteamUserStats_StoreStats(userStatsInterface);
                 if (stored) {
-                    console.log(`✅ Set stat "${statName}" to ${value}`);
+                    console.log(`[Steamworks] Set stat "${statName}" to ${value}`);
                     // Process callbacks
                     this.libraryLoader.SteamAPI_RunCallbacks();
                     return true;
                 }
                 else {
-                    console.warn(`⚠️ Failed to store stat: ${statName}`);
+                    console.warn(`[Steamworks] Failed to store stat: ${statName}`);
                     return false;
                 }
             }
             else {
-                console.warn(`⚠️ Failed to set stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to set stat: ${statName}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error setting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error setting stat "${statName}":`, error.message);
             return false;
         }
     }
     /**
-     * Set a float stat value
+     * Set a float stat value for the current user
      *
-     * @param statName - Name of the stat to set
+     * Updates a floating-point stat value and immediately stores it to Steam servers.
+     * Use this for stats requiring decimal precision.
+     *
+     * @param statName - Name of the stat to set (as defined in Steamworks Partner site)
      * @param value - Float value to set
      * @returns true if successful, false otherwise
      *
+     * @example
+     * ```typescript
+     * // Update accuracy based on hits/shots
+     * const hits = 85;
+     * const shots = 100;
+     * const accuracy = hits / shots; // 0.85
+     * await statsManager.setStatFloat('shooting_accuracy', accuracy);
+     * ```
+     *
+     * @remarks
+     * - Automatically calls StoreStats() to save to Steam servers
+     * - Runs callbacks to process the store operation
+     * - Use setStatInt() for whole number values
+     *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_SetStatFloat()` - Set float stat value
      * - `SteamAPI_ISteamUserStats_StoreStats()` - Store stats to Steam servers
@@ -171,7 +277,7 @@ class SteamStatsManager {
      */
     async setStatFloat(statName, value) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -181,35 +287,52 @@ class SteamStatsManager {
                 // Store the stats to Steam servers
                 const stored = this.libraryLoader.SteamAPI_ISteamUserStats_StoreStats(userStatsInterface);
                 if (stored) {
-                    console.log(`✅ Set stat "${statName}" to ${value}`);
+                    console.log(`[Steamworks] Set stat "${statName}" to ${value}`);
                     // Process callbacks
                     this.libraryLoader.SteamAPI_RunCallbacks();
                     return true;
                 }
                 else {
-                    console.warn(`⚠️ Failed to store stat: ${statName}`);
+                    console.warn(`[Steamworks] Failed to store stat: ${statName}`);
                     return false;
                 }
             }
             else {
-                console.warn(`⚠️ Failed to set stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to set stat: ${statName}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error setting stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error setting stat "${statName}":`, error.message);
             return false;
         }
     }
     /**
      * Update an average rate stat
-     * This is used for stats like "average speed" or "kills per hour"
      *
-     * @param statName - Name of the stat to update
-     * @param countThisSession - Count for this session
+     * Updates stats that represent rates or averages over time (e.g., "kills per hour",
+     * "average speed"). Steam automatically maintains the average calculation.
+     *
+     * @param statName - Name of the stat to update (as defined in Steamworks Partner site)
+     * @param countThisSession - Count/value for this session (e.g., kills this session)
      * @param sessionLength - Length of session in seconds
      * @returns true if successful, false otherwise
      *
+     * @example
+     * ```typescript
+     * // Update kills per hour stat
+     * const sessionKills = 25;
+     * const sessionSeconds = 1800; // 30 minutes
+     * await statsManager.updateAvgRateStat('kills_per_hour', sessionKills, sessionSeconds);
+     * // Steam calculates: (25 / 1800) * 3600 = 50 kills/hour
+     * ```
+     *
+     * @remarks
+     * - Automatically calls StoreStats() to save to Steam servers
+     * - Steam maintains the running average across all sessions
+     * - sessionLength should be in seconds
+     * - Used for "per hour" or "per game" statistics
+     *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_UpdateAvgRateStat()` - Update average rate stat
      * - `SteamAPI_ISteamUserStats_StoreStats()` - Store stats to Steam servers
@@ -217,7 +340,7 @@ class SteamStatsManager {
      */
     async updateAvgRateStat(statName, countThisSession, sessionLength) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -227,23 +350,23 @@ class SteamStatsManager {
                 // Store the stats to Steam servers
                 const stored = this.libraryLoader.SteamAPI_ISteamUserStats_StoreStats(userStatsInterface);
                 if (stored) {
-                    console.log(`✅ Updated avg rate stat "${statName}": ${countThisSession} over ${sessionLength}s`);
+                    console.log(`[Steamworks] Updated avg rate stat "${statName}": ${countThisSession} over ${sessionLength}s`);
                     // Process callbacks
                     this.libraryLoader.SteamAPI_RunCallbacks();
                     return true;
                 }
                 else {
-                    console.warn(`⚠️ Failed to store stat: ${statName}`);
+                    console.warn(`[Steamworks] Failed to store stat: ${statName}`);
                     return false;
                 }
             }
             else {
-                console.warn(`⚠️ Failed to update avg rate stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to update avg rate stat: ${statName}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error updating avg rate stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error updating avg rate stat "${statName}":`, error.message);
             return false;
         }
     }
@@ -252,17 +375,42 @@ class SteamStatsManager {
     // ========================================
     /**
      * Request stats for another user (friend)
-     * Must be called before getting user stats
+     *
+     * Requests stat data from Steam servers for a specific user. Must be called
+     * before getting user stats with getUserStatInt() or getUserStatFloat().
+     * This is an asynchronous operation - wait a moment before reading the stats.
      *
      * @param steamId - Steam ID of the user (as string or BigInt)
-     * @returns true if request was sent, false otherwise
+     * @returns true if request was sent successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const friendSteamId = '76561198012345678';
+     *
+     * // Request the friend's stats
+     * const success = await statsManager.requestUserStats(friendSteamId);
+     * if (success) {
+     *   // Wait a moment for Steam to fetch the data
+     *   await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     *   // Now get the friend's stats
+     *   const friendKills = await statsManager.getUserStatInt(friendSteamId, 'total_kills');
+     *   console.log(`[Steamworks] Friend has ${friendKills} kills`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Must be called before getting user stats
+     * - Returns true immediately if request was sent (not when data arrives)
+     * - Wait 50-100ms after requesting before reading stats
+     * - User's stats must be public for this to work
      *
      * Steamworks SDK Functions:
-     * - `SteamAPI_ISteamUserStats_RequestUserStats()` - Request user stats from Steam
+     * - `SteamAPI_ISteamUserStats_RequestUserStats()` - Request user stats from Steam servers
      */
     async requestUserStats(steamId) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -270,33 +418,56 @@ class SteamStatsManager {
             const steamIdBigInt = typeof steamId === 'string' ? BigInt(steamId) : steamId;
             const callHandle = this.libraryLoader.SteamAPI_ISteamUserStats_RequestUserStats(userStatsInterface, steamIdBigInt);
             if (callHandle !== BigInt(0)) {
-                console.log(`📡 Requested stats for user: ${steamId}`);
+                console.log(`[Steamworks] Requested stats for user: ${steamId}`);
                 return true;
             }
             else {
-                console.warn(`⚠️ Failed to request user stats: ${steamId}`);
+                console.warn(`[Steamworks] Failed to request user stats: ${steamId}`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error requesting user stats:`, error.message);
+            console.error(`[Steamworks] Error requesting user stats:`, error.message);
             return false;
         }
     }
     /**
      * Get an integer stat value for another user (friend)
-     * Must call requestUserStats() first and wait for callback
+     *
+     * Retrieves a 32-bit integer stat value for a specific user. Must call
+     * requestUserStats() first and wait for the data to arrive.
      *
      * @param steamId - Steam ID of the user
      * @param statName - Name of the stat to retrieve
-     * @returns The stat value, or null if not found/error
+     * @returns UserStat object with steamId, name, value, and type, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * // Compare your kills to a friend's
+     * const friendId = '76561198012345678';
+     * await statsManager.requestUserStats(friendId);
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const myStat = await statsManager.getStatInt('total_kills');
+     * const friendStat = await statsManager.getUserStatInt(friendId, 'total_kills');
+     *
+     * if (myStat && friendStat) {
+     *   console.log(`[Steamworks] You: ${myStat.value}, Friend: ${friendStat.value}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Must call requestUserStats() first
+     * - Wait 50-100ms after requesting before calling this
+     * - Returns null if stats haven't arrived yet or user's stats are private
+     * - Returns structured UserStat object with full metadata including steamId
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetUserStatInt32()` - Get user's int32 stat value
      */
     async getUserStatInt(steamId, statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -306,33 +477,59 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetUserStatInt32(userStatsInterface, steamIdBigInt, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'int32');
-                console.log(`📊 Got user stat "${statName}" for ${steamId}: ${value}`);
-                return value;
+                console.log(`[Steamworks] Got user stat "${statName}" for ${steamId}: ${value}`);
+                return {
+                    steamId: typeof steamId === 'string' ? steamId : steamId.toString(),
+                    name: statName,
+                    value,
+                    type: 'int'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get user stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get user stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting user stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting user stat "${statName}":`, error.message);
             return null;
         }
     }
     /**
      * Get a float stat value for another user (friend)
-     * Must call requestUserStats() first and wait for callback
+     *
+     * Retrieves a floating-point stat value for a specific user. Must call
+     * requestUserStats() first and wait for the data to arrive.
      *
      * @param steamId - Steam ID of the user
      * @param statName - Name of the stat to retrieve
-     * @returns The stat value, or null if not found/error
+     * @returns UserStat object with steamId, name, value, and type, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * // Compare accuracy with a friend
+     * const friendId = '76561198012345678';
+     * await statsManager.requestUserStats(friendId);
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const friendStat = await statsManager.getUserStatFloat(friendId, 'shooting_accuracy');
+     * if (friendStat) {
+     *   console.log(`[Steamworks] Friend accuracy: ${(friendStat.value * 100).toFixed(2)}%`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Must call requestUserStats() first
+     * - Wait 50-100ms after requesting before calling this
+     * - Returns null if stats haven't arrived yet or user's stats are private
+     * - Returns structured UserStat object with full metadata including steamId
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetUserStatFloat()` - Get user's float stat value
      */
     async getUserStatFloat(steamId, statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -342,16 +539,21 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetUserStatFloat(userStatsInterface, steamIdBigInt, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'float');
-                console.log(`📊 Got user stat "${statName}" for ${steamId}: ${value}`);
-                return value;
+                console.log(`[Steamworks] Got user stat "${statName}" for ${steamId}: ${value}`);
+                return {
+                    steamId: typeof steamId === 'string' ? steamId : steamId.toString(),
+                    name: statName,
+                    value,
+                    type: 'float'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get user stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get user stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting user stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting user stat "${statName}":`, error.message);
             return null;
         }
     }
@@ -360,17 +562,40 @@ class SteamStatsManager {
     // ========================================
     /**
      * Request global stats data from Steam
-     * Must be called before getting global stats
      *
-     * @param historyDays - Number of days of history to retrieve (0-60)
-     * @returns true if request was sent, false otherwise
+     * Requests aggregated statistics across all players from Steam servers.
+     * Optionally includes historical data for trend analysis.
+     * Must be called before getting global stats.
+     *
+     * @param historyDays - Number of days of history to retrieve (0-60, default: 0)
+     * @returns true if request was sent successfully, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Request current global stats (no history)
+     * await statsManager.requestGlobalStats(0);
+     *
+     * // Request with 7 days of history for trends
+     * await statsManager.requestGlobalStats(7);
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const totalKills = await statsManager.getGlobalStatInt('total_kills');
+     * console.log(`[Steamworks] All players combined: ${totalKills} kills`);
+     * ```
+     *
+     * @remarks
+     * - Must be called before getting global stats
+     * - Returns true immediately if request was sent (not when data arrives)
+     * - Wait 50-100ms after requesting before reading stats
+     * - historyDays is automatically clamped to 0-60 range
+     * - Historical data allows tracking trends over time
      *
      * Steamworks SDK Functions:
-     * - `SteamAPI_ISteamUserStats_RequestGlobalStats()` - Request global stats from Steam
+     * - `SteamAPI_ISteamUserStats_RequestGlobalStats()` - Request global stats from Steam servers
      */
     async requestGlobalStats(historyDays = 0) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return false;
         }
         try {
@@ -379,32 +604,53 @@ class SteamStatsManager {
             const userStatsInterface = this.libraryLoader.SteamAPI_SteamUserStats_v013();
             const callHandle = this.libraryLoader.SteamAPI_ISteamUserStats_RequestGlobalStats(userStatsInterface, days);
             if (callHandle !== BigInt(0)) {
-                console.log(`📡 Requested global stats with ${days} days of history`);
+                console.log(`[Steamworks] Requested global stats with ${days} days of history`);
                 return true;
             }
             else {
-                console.warn(`⚠️ Failed to request global stats`);
+                console.warn(`[Steamworks] Failed to request global stats`);
                 return false;
             }
         }
         catch (error) {
-            console.error(`❌ Error requesting global stats:`, error.message);
+            console.error(`[Steamworks] Error requesting global stats:`, error.message);
             return false;
         }
     }
     /**
-     * Get a global stat value (int64)
-     * Must call requestGlobalStats() first and wait for callback
+     * Get a global stat value (64-bit integer)
+     *
+     * Retrieves an aggregated integer stat value across all players.
+     * Must call requestGlobalStats() first and wait for the data to arrive.
      *
      * @param statName - Name of the global stat to retrieve
-     * @returns The stat value, or null if not found/error
+     * @returns GlobalStat object with name, value, and type, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * // Get total kills across all players
+     * await statsManager.requestGlobalStats();
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const globalStat = await statsManager.getGlobalStatInt('total_kills');
+     * if (globalStat) {
+     *   console.log(`[Steamworks] ${globalStat.name}: ${globalStat.value}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Must call requestGlobalStats() first
+     * - Wait 50-100ms after requesting before calling this
+     * - Useful for tracking game-wide statistics
+     * - Returns structured GlobalStat object with full metadata
+     * - Value is number (BigInt converted to number for consistency)
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetGlobalStatInt64()` - Get global int64 stat value
      */
     async getGlobalStatInt(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -413,32 +659,58 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetGlobalStatInt64(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'int64');
-                console.log(`🌍 Got global stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got global stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value: Number(value),
+                    type: 'int64'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat "${statName}":`, error.message);
             return null;
         }
     }
     /**
-     * Get a global stat value (double)
-     * Must call requestGlobalStats() first and wait for callback
+     * Get a global stat value (double-precision float)
+     *
+     * Retrieves an aggregated floating-point stat value across all players.
+     * Must call requestGlobalStats() first and wait for the data to arrive.
+     * Use this for averages or stats requiring decimal precision.
      *
      * @param statName - Name of the global stat to retrieve
-     * @returns The stat value, or null if not found/error
+     * @returns GlobalStat object with name, value, and type, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * // Get average accuracy across all players
+     * await statsManager.requestGlobalStats();
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const avgStat = await statsManager.getGlobalStatDouble('average_accuracy');
+     * if (avgStat) {
+     *   console.log(`[Steamworks] ${avgStat.name}: ${(avgStat.value * 100).toFixed(2)}%`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Use for stats requiring decimal precision
+     * - Must call requestGlobalStats() first
+     * - Wait 50-100ms after requesting before calling this
+     * - Perfect for calculating game-wide averages
+     * - Returns structured GlobalStat object with full metadata
      *
      * Steamworks SDK Functions:
      * - `SteamAPI_ISteamUserStats_GetGlobalStatDouble()` - Get global double stat value
      */
     async getGlobalStatDouble(statName) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -447,33 +719,63 @@ class SteamStatsManager {
             const success = this.libraryLoader.SteamAPI_ISteamUserStats_GetGlobalStatDouble(userStatsInterface, statName, valueOut);
             if (success) {
                 const value = koffi.decode(valueOut, 'double');
-                console.log(`🌍 Got global stat "${statName}": ${value}`);
-                return value;
+                console.log(`[Steamworks] Got global stat "${statName}": ${value}`);
+                return {
+                    name: statName,
+                    value,
+                    type: 'double'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat "${statName}":`, error.message);
             return null;
         }
     }
     /**
-     * Get global stat history (int64)
-     * Returns daily values for the stat, with [0] being today, [1] yesterday, etc.
+     * Get global stat history for an integer stat
+     *
+     * Retrieves historical daily values for a global stat. Array index [0] is today,
+     * [1] is yesterday, etc. Useful for tracking trends and creating graphs.
      *
      * @param statName - Name of the global stat
-     * @param days - Number of days of history to retrieve (max 60)
-     * @returns Array of daily values, or null if error
+     * @param days - Number of days of history to retrieve (1-60, default: 7)
+     * @returns GlobalStatHistory object with name, history array, and type, or null if error
+     *
+     * @example
+     * ```typescript
+     * // Get 7 days of global kill history
+     * await statsManager.requestGlobalStats(7);
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const history = await statsManager.getGlobalStatHistoryInt('total_kills', 7);
+     * if (history) {
+     *   console.log(`[Steamworks] ${history.name} history (${history.type}):`);
+     *   history.history.forEach((kills, index) => {
+     *     const daysAgo = index === 0 ? 'today' : `${index} days ago`;
+     *     console.log(`[Steamworks]   ${daysAgo}: ${kills} kills`);
+     *   });
+     * }
+     * ```
+     *
+     * @remarks
+     * - Array index [0] = today, [1] = yesterday, etc.
+     * - Must call requestGlobalStats(days) first with same or greater number of days
+     * - Returns structured GlobalStatHistory object with full metadata
+     * - Values are numbers (BigInt converted to number for consistency)
+     * - Maximum 60 days of history (automatically clamped)
+     * - Perfect for trend analysis and visualizations
      *
      * Steamworks SDK Functions:
-     * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryInt64()` - Get global stat history
+     * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryInt64()` - Get historical int64 values
      */
     async getGlobalStatHistoryInt(statName, days = 7) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -485,35 +787,67 @@ class SteamStatsManager {
             if (elementsReturned > 0) {
                 const history = [];
                 for (let i = 0; i < elementsReturned; i++) {
-                    history.push(koffi.decode(historyOut, 'int64', i));
+                    history.push(Number(koffi.decode(historyOut, 'int64', i))); // Convert BigInt to number
                 }
-                console.log(`🌍 Got ${elementsReturned} days of history for "${statName}"`);
-                return history;
+                console.log(`[Steamworks] Got ${elementsReturned} days of history for "${statName}"`);
+                return {
+                    name: statName,
+                    history,
+                    type: 'int64'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat history: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat history: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat history "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat history "${statName}":`, error.message);
             return null;
         }
     }
     /**
-     * Get global stat history (double)
-     * Returns daily values for the stat, with [0] being today, [1] yesterday, etc.
+     * Get global stat history for a floating-point stat
+     *
+     * Retrieves historical daily values for a global stat with decimal precision.
+     * Array index [0] is today, [1] is yesterday, etc. Ideal for tracking averages
+     * and rates over time.
      *
      * @param statName - Name of the global stat
-     * @param days - Number of days of history to retrieve (max 60)
-     * @returns Array of daily values, or null if error
+     * @param days - Number of days of history to retrieve (1-60, default: 7)
+     * @returns GlobalStatHistory object with name, history array, and type, or null if error
+     *
+     * @example
+     * ```typescript
+     * // Track average accuracy trend over 30 days
+     * await statsManager.requestGlobalStats(30);
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const history = await statsManager.getGlobalStatHistoryDouble('average_accuracy', 30);
+     * if (history) {
+     *   console.log(`[Steamworks] ${history.name} trend (${history.type}):`);
+     *   history.history.forEach((accuracy, index) => {
+     *     if (index % 7 === 0) { // Weekly intervals
+     *       console.log(`[Steamworks]   Week ${index/7}: ${(accuracy * 100).toFixed(2)}%`);
+     *     }
+     *   });
+     * }
+     * ```
+     *
+     * @remarks
+     * - Array index [0] = today, [1] = yesterday, etc.
+     * - Must call requestGlobalStats(days) first with same or greater number of days
+     * - Returns structured GlobalStatHistory object with full metadata
+     * - Returns floating-point values for decimal precision
+     * - Maximum 60 days of history (automatically clamped)
+     * - Perfect for tracking averages, rates, and percentages over time
      *
      * Steamworks SDK Functions:
-     * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryDouble()` - Get global stat history
+     * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryDouble()` - Get historical double values
      */
     async getGlobalStatHistoryDouble(statName, days = 7) {
         if (!this.apiCore.isInitialized()) {
-            console.warn('⚠️ Steam API not initialized');
+            console.warn('[Steamworks] Steam API not initialized');
             return null;
         }
         try {
@@ -527,16 +861,20 @@ class SteamStatsManager {
                 for (let i = 0; i < elementsReturned; i++) {
                     history.push(koffi.decode(historyOut, 'double', i));
                 }
-                console.log(`🌍 Got ${elementsReturned} days of history for "${statName}"`);
-                return history;
+                console.log(`[Steamworks] Got ${elementsReturned} days of history for "${statName}"`);
+                return {
+                    name: statName,
+                    history,
+                    type: 'double'
+                };
             }
             else {
-                console.warn(`⚠️ Failed to get global stat history: ${statName}`);
+                console.warn(`[Steamworks] Failed to get global stat history: ${statName}`);
                 return null;
             }
         }
         catch (error) {
-            console.error(`❌ Error getting global stat history "${statName}":`, error.message);
+            console.error(`[Steamworks] Error getting global stat history "${statName}":`, error.message);
             return null;
         }
     }