steamworks-ffi-node 0.2.3 → 0.3.1

package/dist/internal/SteamStatsManager.d.ts

@@ -0,0 +1,460 @@
+import { SteamLibraryLoader } from './SteamLibraryLoader';
+import { SteamAPICore } from './SteamAPICore';
+/**
+ * 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');
+ * ```
+ */
+export declare class SteamStatsManager {
+    /** Steam library loader for FFI function calls */
+    private libraryLoader;
+    /** Steam API core for initialization and callback management */
+    private apiCore;
+    /**
+     * 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: SteamLibraryLoader, apiCore: SteamAPICore);
+    /**
+     * Get an integer stat value for the current user
+     *
+     * 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 The stat value, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * const totalKills = await statsManager.getStatInt('total_kills');
+     * if (totalKills !== null) {
+     *   console.log(`Total kills: ${totalKills}`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if Steam API is not initialized
+     * - Stat names are case-sensitive and must match Steamworks configuration
+     * - Use getStatFloat() for decimal values
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetStatInt32()` - Get int32 stat value
+     */
+    getStatInt(statName: string): Promise<number | null>;
+    /**
+     * Get a float stat value for the current user
+     *
+     * 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 The stat value, or null if not found or on error
+     *
+     * @example
+     * ```typescript
+     * const accuracy = await statsManager.getStatFloat('shooting_accuracy');
+     * if (accuracy !== null) {
+     *   console.log(`Accuracy: ${(accuracy * 100).toFixed(2)}%`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if Steam API is not initialized
+     * - Use getStatInt() for whole number values
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetStatFloat()` - Get float stat value
+     */
+    getStatFloat(statName: string): Promise<number | null>;
+    /**
+     * Set an integer stat value for the current user
+     *
+     * 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('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
+     * - `SteamAPI_RunCallbacks()` - Process Steam callbacks
+     */
+    setStatInt(statName: string, value: number): Promise<boolean>;
+    /**
+     * Set a float stat value for the current user
+     *
+     * 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
+     * - `SteamAPI_RunCallbacks()` - Process Steam callbacks
+     */
+    setStatFloat(statName: string, value: number): Promise<boolean>;
+    /**
+     * Update an average rate stat
+     *
+     * 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
+     * - `SteamAPI_RunCallbacks()` - Process Steam callbacks
+     */
+    updateAvgRateStat(statName: string, countThisSession: number, sessionLength: number): Promise<boolean>;
+    /**
+     * Request stats for another user (friend)
+     *
+     * 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 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(`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 servers
+     */
+    requestUserStats(steamId: string | bigint): Promise<boolean>;
+    /**
+     * Get an integer stat value for another user (friend)
+     *
+     * 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 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 myKills = await statsManager.getStatInt('total_kills') || 0;
+     * const friendKills = await statsManager.getUserStatInt(friendId, 'total_kills') || 0;
+     *
+     * console.log(`You: ${myKills}, Friend: ${friendKills}`);
+     * ```
+     *
+     * @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
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetUserStatInt32()` - Get user's int32 stat value
+     */
+    getUserStatInt(steamId: string | bigint, statName: string): Promise<number | null>;
+    /**
+     * Get a float stat value for another user (friend)
+     *
+     * 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 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 friendAccuracy = await statsManager.getUserStatFloat(friendId, 'shooting_accuracy');
+     * if (friendAccuracy !== null) {
+     *   console.log(`Friend accuracy: ${(friendAccuracy * 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
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetUserStatFloat()` - Get user's float stat value
+     */
+    getUserStatFloat(steamId: string | bigint, statName: string): Promise<number | null>;
+    /**
+     * Request global stats data from Steam
+     *
+     * 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(`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 servers
+     */
+    requestGlobalStats(historyDays?: number): Promise<boolean>;
+    /**
+     * 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 as BigInt, 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 globalKills = await statsManager.getGlobalStatInt('total_kills');
+     * if (globalKills !== null) {
+     *   console.log(`All players have ${globalKills} total kills`);
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns BigInt for large numbers (can exceed JavaScript's safe integer range)
+     * - Must call requestGlobalStats() first
+     * - Wait 50-100ms after requesting before calling this
+     * - Useful for tracking game-wide statistics
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetGlobalStatInt64()` - Get global int64 stat value
+     */
+    getGlobalStatInt(statName: string): Promise<bigint | null>;
+    /**
+     * 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 or on error
+     *
+     * @example
+     * ```typescript
+     * // Get average accuracy across all players
+     * await statsManager.requestGlobalStats();
+     * await new Promise(resolve => setTimeout(resolve, 100));
+     *
+     * const avgAccuracy = await statsManager.getGlobalStatDouble('average_accuracy');
+     * if (avgAccuracy !== null) {
+     *   console.log(`Global average accuracy: ${(avgAccuracy * 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
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetGlobalStatDouble()` - Get global double stat value
+     */
+    getGlobalStatDouble(statName: string): Promise<number | null>;
+    /**
+     * 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 (1-60, default: 7)
+     * @returns Array of daily BigInt values, 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('Kill history (newest to oldest):');
+     *   history.forEach((kills, index) => {
+     *     const daysAgo = index === 0 ? 'today' : `${index} days ago`;
+     *     console.log(`  ${daysAgo}: ${kills} kills`);
+     *   });
+     * }
+     * ```
+     *
+     * @remarks
+     * - Array index [0] = today, [1] = yesterday, etc.
+     * - Must call requestGlobalStats(days) first with same or greater number of days
+     * - Returns BigInt values for large numbers
+     * - Maximum 60 days of history (automatically clamped)
+     * - Perfect for trend analysis and visualizations
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUserStats_GetGlobalStatHistoryInt64()` - Get historical int64 values
+     */
+    getGlobalStatHistoryInt(statName: string, days?: number): Promise<bigint[] | null>;
+    /**
+     * 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 (1-60, default: 7)
+     * @returns Array of daily float values, 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('Accuracy trend:');
+     *   history.forEach((accuracy, index) => {
+     *     if (index % 7 === 0) { // Weekly intervals
+     *       console.log(`  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 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 historical double values
+     */
+    getGlobalStatHistoryDouble(statName: string, days?: number): Promise<number[] | null>;
+}
+//# sourceMappingURL=SteamStatsManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SteamStatsManager.d.ts","sourceRoot":"","sources":["../../src/internal/SteamStatsManager.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAG9C;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,qBAAa,iBAAiB;IAC5B,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAqB;IAE1C,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAe;IAE9B;;;;;OAKG;gBACS,aAAa,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY;IASpE;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8B1D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8B5D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqCnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA4BG;IACG,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAqCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA0C5G;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IA4BlE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAgCxF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAoC1F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACG,kBAAkB,CAAC,WAAW,GAAE,MAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IA8BnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACG,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8BhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACG,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IA8BnE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACG,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;IAqC3F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACG,0BAA0B,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,GAAE,MAAU,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,IAAI,CAAC;CAoC/F"}