steamworks-ffi-node 0.2.3 → 0.3.1

package/README.md

@@ -1,10 +1,15 @@
-# Steamworks FFI - Real Steam Integration
+[![npm](https://img.shields.io/npm/v/steamworks-ffi-node.svg)](https://www.npmjs.com/package/steamworks-ffi-node)
+[![Chat](https://img.shields.io/discord/1426518243077656699?label=chat&logo=discord)](https://discord.gg/Ruzx4Z7cKr)
 
-A production-ready TypeScript/JavaScript wrapper for the Steamworks SDK using Koffi FFI, designed for Node.js and Electron applications with **real Steam client integration**.
+# Steamworks FFI - Steamworks SDK Integration
+
+A production-ready TypeScript/JavaScript wrapper for the Steamworks SDK using Koffi FFI, designed for Node.js and Electron applications with **Steamworks SDK integration**.
 
 > ✅ **No C++ Compilation Required**: Uses Koffi FFI for seamless installation without Visual Studio Build Tools!
 
-> 🎉 **NEW: 100% Achievement API Coverage** - All 20 Steam achievement functions now implemented! See [Complete Achievement Manager Documentation](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/docs/AchievementManager.md)
+> 🎉 **NEW: 100% Achievement API Coverage** - All 20 Steam achievement functions implemented! [See Documentation](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/docs/ACHIEVEMENT_MANAGER.md)
+
+> 🎉 **NEW: 100% Stats API Coverage** - All 13 Steam statistics functions implemented! [See Documentation](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/docs/STATS_MANAGER.md)
 
 ## 🎯 Features
 
@@ -15,7 +20,11 @@ A production-ready TypeScript/JavaScript wrapper for the Steamworks SDK using Ko
   - ✅ Friend comparisons (see friend achievements)
   - ✅ Global statistics (unlock percentages, popularity sorting)
   - ✅ Testing tools (reset stats/achievements)
-- **Real Steam Integration**: Direct FFI calls to Steamworks C++ SDK
+- **Complete Stats API**: 100% coverage of Steam User Stats functionality (13/13 functions)
+  - ✅ User stats (get/set int/float, average rate tracking)
+  - ✅ Friend comparisons (compare stats with friends)
+  - ✅ Global statistics (worldwide aggregated data with history)
+- **Steamworks Integration**: Direct FFI calls to Steamworks C++ SDK
 - **Cross-Platform**: Windows, macOS, and Linux support
 - **Batteries Included**: All Steamworks redistributables bundled - no SDK download needed!
 - **Electron Ready**: Perfect for Electron applications
@@ -45,14 +54,14 @@ npm install steamworks-ffi-node
 ```typescript
 import Steam from 'steamworks-ffi-node';
 
-// Initialize real Steam connection
+// Initialize Steam connection
 const steam = Steam.getInstance();
 const initialized = steam.init({ appId: 480 }); // Your Steam App ID
 
 if (initialized) {
   // Get achievements from Steam servers
   const achievements = await steam.getAllAchievements();
-  console.log('Real Steam achievements:', achievements);
+  console.log('Steam achievements:', achievements);
   
   // Unlock achievement (permanent in Steam!)
   await steam.unlockAchievement('ACH_WIN_ONE_GAME');
@@ -60,6 +69,17 @@ if (initialized) {
   // Check unlock status from Steam
   const isUnlocked = await steam.isAchievementUnlocked('ACH_WIN_ONE_GAME');
   console.log('Achievement unlocked:', isUnlocked);
+  
+  // Track user statistics
+  const kills = await steam.getStatInt('total_kills') || 0;
+  await steam.setStatInt('total_kills', kills + 1);
+  
+  // Get global statistics
+  await steam.requestGlobalStats(7);
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  steam.runCallbacks();
+  const globalKills = await steam.getGlobalStatInt('global.total_kills');
+  console.log('Total kills worldwide:', globalKills);
 }
 
 // Cleanup
@@ -100,23 +120,22 @@ For immediate testing, use Spacewar (App ID 480):
 
 ## 📚 API Documentation
 
-### Documentation
+Complete documentation for all APIs is available in the [docs folder](https://github.com/ArtyProf/steamworks-ffi-node/tree/main/docs):
 
-- **[SteamAPICore Documentation](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/docs/SteamAPICore.md)** - Initialization, lifecycle management, callbacks
-- **[Achievement Manager API](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/docs/AchievementManager.md)** - Complete achievement functionality (20 functions)
+➡️ **[View Complete Documentation](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/docs/README.md)**
 
-## 🎮 Real Steam Integration
+## 🎮 Steamworks Integration
 
 This library connects directly to the Steam client and Steamworks SDK:
 
 ```javascript
-// Real Steam API - no mocking!
+// Steam API - no mocking!
 const steam = Steam.getInstance();
 steam.init({ appId: 480 }); // Connects to actual Steam
 
 // Live achievements from Steam servers
 const achievements = await steam.getAllAchievements();
-console.log(achievements); // Real achievement data from your Steam app
+console.log(achievements); // Achievement data from your Steam app
 
 // Permanent achievement unlock in Steam
 await steam.unlockAchievement('YOUR_ACHIEVEMENT');
@@ -155,6 +174,45 @@ app.on('before-quit', () => {
 });
 ```
 
+### 📦 Packaging with ASAR
+
+When packaging your Electron app with ASAR archives, **native modules must be unpacked**. The library automatically detects ASAR and looks for files in `.asar.unpacked`.
+
+#### electron-builder Configuration
+
+Add to your `package.json` or `electron-builder.yml`:
+
+```json
+{
+  "build": {
+    "asarUnpack": [
+      "node_modules/steamworks-ffi-node/**/*"
+    ]
+  }
+}
+```
+
+#### electron-forge Configuration
+
+Add to your `forge.config.js`:
+
+```javascript
+module.exports = {
+  packagerConfig: {
+    asar: {
+      unpack: "**/{node_modules/steamworks-ffi-node}/**/*"
+    }
+  }
+};
+```
+
+The library will automatically:
+1. Detect if running inside an ASAR archive
+2. Replace `.asar` with `.asar.unpacked` in the library path
+3. Load the Steamworks SDK from the unpacked directory
+
+This ensures native libraries work correctly in packaged Electron apps!
+
 ## 🔧 Requirements
 
 - **Node.js**: 18+ 
@@ -186,7 +244,9 @@ All redistributable binaries are included in the package - no manual SDK downloa
 
 ### Electron-specific issues
 - ❌ Initialized in renderer → **Solution**: Only initialize in main process
-- ❌ Not cleaning up → **Solution**: Call `shutdown()` in `before-quit` event  
+- ❌ Not cleaning up → **Solution**: Call `shutdown()` in `before-quit` event
+- ❌ "cannot open shared object file: Not a directory" (Linux) → **Solution**: Add `asarUnpack` configuration (see Electron Integration section above)
+- ❌ Native module errors in packaged app → **Solution**: Ensure `steamworks-ffi-node` is in `asarUnpack` list
 
 ## 📄 License
 
@@ -197,4 +257,4 @@ MIT License - see LICENSE file for details.
 This package includes redistributable binaries from the Steamworks SDK (© Valve Corporation).
 These are distributed under the Steamworks SDK Access Agreement in accordance with Section 1.1(b).
 
-See [THIRD_PARTY_LICENSES.md](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/THIRD_PARTY_LICENSES.md) for full details.
+See [THIRD_PARTY_LICENSES.md](https://github.com/ArtyProf/steamworks-ffi-node/blob/main/THIRD_PARTY_LICENSES.md) for full details.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import SteamworksSDK from './steam';
-import { SteamAchievement, SteamInitOptions, SteamStatus, AchievementProgressLimits, UserAchievement, AchievementGlobalStats, AchievementWithIcon } from './types';
-export { SteamAchievement, SteamInitOptions, SteamStatus, AchievementProgressLimits, UserAchievement, AchievementGlobalStats, AchievementWithIcon };
+import { SteamAchievement, SteamInitOptions, SteamStatus, AchievementProgressLimits, UserAchievement, AchievementGlobalStats, AchievementWithIcon, SteamStat, GlobalStat, GlobalStatHistory, UserStat } from './types';
+export { SteamAchievement, SteamInitOptions, SteamStatus, AchievementProgressLimits, UserAchievement, AchievementGlobalStats, AchievementWithIcon, SteamStat, GlobalStat, GlobalStatHistory, UserStat };
 export default SteamworksSDK;
 export { SteamworksSDK as Steam };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,SAAS,CAAC;AACpC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,yBAAyB,EACzB,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,yBAAyB,EACzB,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACpB,CAAC;AAGF,eAAe,aAAa,CAAC;AAG7B,OAAO,EAAE,aAAa,IAAI,KAAK,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,SAAS,CAAC;AACpC,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,yBAAyB,EACzB,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACT,MAAM,SAAS,CAAC;AAGjB,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,WAAW,EACX,yBAAyB,EACzB,eAAe,EACf,sBAAsB,EACtB,mBAAmB,EACnB,SAAS,EACT,UAAU,EACV,iBAAiB,EACjB,QAAQ,EACT,CAAC;AAGF,eAAe,aAAa,CAAC;AAG7B,OAAO,EAAE,aAAa,IAAI,KAAK,EAAE,CAAC"}

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,oDAAoC;AA0BV,gBA1BnB,eAAa,CA0BW;AAJ/B,0BAA0B;AAC1B,kBAAe,eAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;AAAA,oDAAoC;AAkCV,gBAlCnB,eAAa,CAkCW;AAJ/B,0BAA0B;AAC1B,kBAAe,eAAa,CAAC"}

package/dist/internal/SteamAPICore.d.ts

@@ -1,45 +1,235 @@
 import { SteamInitOptions, SteamStatus } from '../types';
 import { SteamLibraryLoader } from './SteamLibraryLoader';
 /**
- * Core Steam API initialization and lifecycle management
+ * SteamAPICore
+ *
+ * Core Steam API initialization and lifecycle management.
+ * Handles Steam client connection, interface management, and callback processing.
+ *
+ * This class manages the fundamental Steam API operations:
+ * - Initialization and shutdown of the Steam API
+ * - Interface retrieval (UserStats, User)
+ * - Status monitoring (Steam running, initialization state)
+ * - Callback processing for Steam events
+ *
+ * @example
+ * ```typescript
+ * const loader = new SteamLibraryLoader();
+ * const apiCore = new SteamAPICore(loader);
+ *
+ * const success = apiCore.init({ appId: 480 });
+ * if (success) {
+ *   console.log('Steam API initialized!');
+ *   // Use Steam features...
+ *   apiCore.shutdown();
+ * }
+ * ```
  */
 export declare class SteamAPICore {
+    /** Steam library loader for FFI function calls */
     private libraryLoader;
+    /** Whether the Steam API has been successfully initialized */
     private initialized;
+    /** The Steam App ID for this application */
     private appId;
+    /** Pointer to the ISteamUserStats interface */
     private userStatsInterface;
+    /** Pointer to the ISteamUser interface */
     private userInterface;
+    /**
+     * Creates a new SteamAPICore instance
+     *
+     * @param libraryLoader - The Steam library loader for FFI calls
+     */
     constructor(libraryLoader: SteamLibraryLoader);
     /**
-     * Initialize Steam API
+     * Initialize the Steam API
+     *
+     * Establishes connection to the Steam client and retrieves necessary interfaces.
+     * Creates steam_appid.txt file required by Steam, loads the Steamworks library,
+     * and initializes all necessary Steam interfaces.
+     *
+     * @param options - Initialization options containing the Steam App ID
+     * @returns true if initialization was successful, false otherwise
+     *
+     * @example
+     * ```typescript
+     * const success = apiCore.init({ appId: 480 });
+     * if (success) {
+     *   console.log('Connected to Steam for App ID:', 480);
+     * } else {
+     *   console.error('Failed to initialize Steam API');
+     * }
+     * ```
+     *
+     * @remarks
+     * - Creates steam_appid.txt file in the current working directory
+     * - Sets SteamAppId environment variable
+     * - Automatically requests current stats from Steam servers
+     * - Runs callbacks to process initial Steam events
+     *
+     * @warning
+     * Requires Steam client to be running and user to be logged in
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_Init()` - Initialize the Steam API
+     * - `SteamAPI_IsSteamRunning()` - Check if Steam client is running
+     * - `SteamAPI_SteamUserStats_v013()` - Get ISteamUserStats interface
+     * - `SteamAPI_SteamUser_v023()` - Get ISteamUser interface
+     * - `SteamAPI_ISteamUserStats_RequestCurrentStats()` - Request current stats from Steam
+     * - `SteamAPI_RunCallbacks()` - Process Steam callbacks
      */
     init(options: SteamInitOptions): boolean;
     /**
-     * Shutdown Steam API
+     * Shutdown the Steam API
+     *
+     * Cleanly shuts down the Steam API connection and releases all interfaces.
+     * Should be called when the application is closing or Steam features are no longer needed.
+     *
+     * @example
+     * ```typescript
+     * process.on('SIGINT', () => {
+     *   apiCore.shutdown();
+     *   process.exit(0);
+     * });
+     * ```
+     *
+     * @remarks
+     * - Safe to call multiple times (only shuts down if initialized)
+     * - Clears all interface pointers
+     * - Sets initialized state to false
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_Shutdown()` - Shutdown the Steam API
      */
     shutdown(): void;
     /**
-     * Get current Steam status
+     * Get the current Steam status
+     *
+     * Returns detailed status information including initialization state,
+     * App ID, and the current user's Steam ID.
+     *
+     * @returns Object containing initialization status, App ID, and Steam ID
+     *
+     * @example
+     * ```typescript
+     * const status = apiCore.getStatus();
+     * console.log(`Initialized: ${status.initialized}`);
+     * console.log(`App ID: ${status.appId}`);
+     * console.log(`Steam ID: ${status.steamId}`);
+     * ```
+     *
+     * @remarks
+     * - Steam ID is '0' if not initialized or unable to retrieve
+     * - App ID is 0 if not initialized
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_ISteamUser_GetSteamID()` - Get current user's Steam ID
      */
     getStatus(): SteamStatus;
     /**
      * Run Steam callbacks to process pending events
+     *
+     * Processes all pending Steam callbacks and events. Should be called regularly
+     * (e.g., in a game loop or timer) to ensure Steam events are processed promptly.
+     *
+     * @example
+     * ```typescript
+     * // In a game loop or setInterval
+     * setInterval(() => {
+     *   apiCore.runCallbacks();
+     * }, 100); // Every 100ms
+     * ```
+     *
+     * @remarks
+     * - Safe to call even if not initialized (will be ignored)
+     * - Automatically called by init() and after stat/achievement operations
+     * - Required for receiving Steam events and callbacks
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_RunCallbacks()` - Process all pending Steam callbacks
      */
     runCallbacks(): void;
     /**
-     * Check if Steam client is running
+     * Check if the Steam client is running
+     *
+     * Verifies that the Steam client application is currently running on the user's system.
+     *
+     * @returns true if Steam is running, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (apiCore.isSteamRunning()) {
+     *   console.log('Steam client is active');
+     * } else {
+     *   console.warn('Steam client is not running');
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns false if Steam API is not initialized
+     * - Safe to call at any time
+     *
+     * Steamworks SDK Functions:
+     * - `SteamAPI_IsSteamRunning()` - Check if Steam client is running
      */
     isSteamRunning(): boolean;
     /**
-     * Check if initialized
+     * Check if the Steam API is initialized
+     *
+     * Returns the current initialization state of the Steam API.
+     *
+     * @returns true if initialized and ready to use, false otherwise
+     *
+     * @example
+     * ```typescript
+     * if (!apiCore.isInitialized()) {
+     *   console.error('Cannot perform Steam operations - not initialized');
+     *   return;
+     * }
+     * ```
      */
     isInitialized(): boolean;
     /**
-     * Get UserStats interface pointer
+     * Get the ISteamUserStats interface pointer
+     *
+     * Returns the native pointer to the ISteamUserStats interface, which is used
+     * for achievement and stats operations.
+     *
+     * @returns Pointer to ISteamUserStats interface, or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const userStats = apiCore.getUserStatsInterface();
+     * if (userStats) {
+     *   // Use interface for stats/achievement operations
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if Steam API is not initialized
+     * - This is a native pointer for use with FFI calls
      */
     getUserStatsInterface(): any;
     /**
-     * Get User interface pointer
+     * Get the ISteamUser interface pointer
+     *
+     * Returns the native pointer to the ISteamUser interface, which is used
+     * for user identity operations.
+     *
+     * @returns Pointer to ISteamUser interface, or null if not initialized
+     *
+     * @example
+     * ```typescript
+     * const user = apiCore.getUserInterface();
+     * if (user) {
+     *   // Use interface for user operations
+     * }
+     * ```
+     *
+     * @remarks
+     * - Returns null if Steam API is not initialized
+     * - This is a native pointer for use with FFI calls
      */
     getUserInterface(): any;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"SteamAPICore.d.ts","sourceRoot":"","sources":["../../src/internal/SteamAPICore.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;GAEG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,aAAa,CAAqB;IAC1C,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,kBAAkB,CAAa;IACvC,OAAO,CAAC,aAAa,CAAa;gBAEtB,aAAa,EAAE,kBAAkB;IAI7C;;OAEG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;IAmExC;;OAEG;IACH,QAAQ,IAAI,IAAI;IAWhB;;OAEG;IACH,SAAS,IAAI,WAAW;IAmBxB;;OAEG;IACH,YAAY,IAAI,IAAI;IAUpB;;OAEG;IACH,cAAc,IAAI,OAAO;IAYzB;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,qBAAqB,IAAI,GAAG;IAI5B;;OAEG;IACH,gBAAgB,IAAI,GAAG;CAGxB"}
+{"version":3,"file":"SteamAPICore.d.ts","sourceRoot":"","sources":["../../src/internal/SteamAPICore.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,YAAY;IACvB,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAqB;IAE1C,8DAA8D;IAC9D,OAAO,CAAC,WAAW,CAAkB;IAErC,4CAA4C;IAC5C,OAAO,CAAC,KAAK,CAAa;IAE1B,+CAA+C;IAC/C,OAAO,CAAC,kBAAkB,CAAa;IAEvC,0CAA0C;IAC1C,OAAO,CAAC,aAAa,CAAa;IAElC;;;;OAIG;gBACS,aAAa,EAAE,kBAAkB;IAI7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoCG;IACH,IAAI,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO;IAmExC;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,QAAQ,IAAI,IAAI;IAWhB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,IAAI,WAAW;IAmBxB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,YAAY,IAAI,IAAI;IAUpB;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,cAAc,IAAI,OAAO;IAYzB;;;;;;;;;;;;;;OAcG;IACH,aAAa,IAAI,OAAO;IAIxB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,qBAAqB,IAAI,GAAG;IAI5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,gBAAgB,IAAI,GAAG;CAGxB"}