steamworks-ffi-node 0.7.0 → 0.7.1

package/dist/internal/SteamScreenshotManager.d.ts

@@ -0,0 +1,327 @@
+import { SteamLibraryLoader } from './SteamLibraryLoader';
+import { SteamAPICore } from './SteamAPICore';
+import { ScreenshotHandle, EVRScreenshotType } from '../types';
+/**
+ * Manager for Steam Screenshots API operations
+ *
+ * The SteamScreenshotManager provides functionality to capture screenshots,
+ * add them to the user's Steam screenshot library, and tag them with metadata
+ * like location, users, and Workshop items.
+ *
+ * Screenshots can be captured in two ways:
+ * 1. **Overlay capture**: Using `triggerScreenshot()` to have Steam capture the screen
+ * 2. **Manual capture**: Your game captures the image and uses `writeScreenshot()` or
+ *    `addScreenshotToLibrary()` to add it
+ *
+ * @remarks
+ * The manual capture methods work without the overlay, making them suitable for
+ * headless or non-graphical environments. The overlay-based `triggerScreenshot()`
+ * requires the Steam overlay to be available.
+ *
+ * @example Basic screenshot capture
+ * ```typescript
+ * const steam = SteamworksSDK.getInstance();
+ * steam.init({ appId: 480 });
+ *
+ * // Add a screenshot from a file
+ * const handle = steam.screenshots.addScreenshotToLibrary(
+ *   '/path/to/screenshot.jpg',
+ *   null,  // No thumbnail - Steam will generate one
+ *   1920,
+ *   1080
+ * );
+ *
+ * if (handle !== INVALID_SCREENSHOT_HANDLE) {
+ *   // Tag the screenshot with location
+ *   steam.screenshots.setLocation(handle, 'Level 1 - Boss Fight');
+ * }
+ * ```
+ *
+ * @example Hook screenshots for custom handling
+ * ```typescript
+ * // Tell Steam your app handles screenshots
+ * steam.screenshots.hookScreenshots(true);
+ *
+ * // Now when user presses screenshot key, you get a callback
+ * // and should call writeScreenshot() or addScreenshotToLibrary()
+ * ```
+ *
+ * @see {@link https://partner.steamgames.com/doc/api/ISteamScreenshots ISteamScreenshots Documentation}
+ */
+export declare class SteamScreenshotManager {
+    /** Steam library loader for FFI function calls */
+    private libraryLoader;
+    /** Steam API core for initialization and callback management */
+    private apiCore;
+    /** Cached screenshots interface pointer */
+    private screenshotsInterface;
+    /**
+     * Creates a new SteamScreenshotManager instance
+     *
+     * @param libraryLoader - The Steam library loader for FFI calls
+     * @param apiCore - The Steam API core for lifecycle management
+     */
+    constructor(libraryLoader: SteamLibraryLoader, apiCore: SteamAPICore);
+    /**
+     * Gets the ISteamScreenshots interface pointer
+     *
+     * @returns The interface pointer or null if not available
+     */
+    private getScreenshotsInterface;
+    /**
+     * Writes a screenshot to the user's Steam screenshot library from raw RGB data
+     *
+     * @param rgbData - Buffer containing raw RGB pixel data (no alpha channel)
+     * @param width - Width of the image in pixels
+     * @param height - Height of the image in pixels
+     * @returns Screenshot handle, or INVALID_SCREENSHOT_HANDLE on failure
+     *
+     * @remarks
+     * - The image data must be in RGB format (3 bytes per pixel)
+     * - The buffer size should be width * height * 3 bytes
+     * - This method works without the overlay
+     * - The returned handle can be used to tag the screenshot
+     *
+     * @example Write raw RGB data as screenshot
+     * ```typescript
+     * // Assume you have raw RGB pixel data from your renderer
+     * const width = 1920;
+     * const height = 1080;
+     * const rgbData = Buffer.alloc(width * height * 3);
+     *
+     * // Fill rgbData with your screenshot pixels...
+     *
+     * const handle = steam.screenshots.writeScreenshot(rgbData, width, height);
+     *
+     * if (handle !== INVALID_SCREENSHOT_HANDLE) {
+     *   console.log('Screenshot saved with handle:', handle);
+     *   steam.screenshots.setLocation(handle, 'My Game Location');
+     * }
+     * ```
+     */
+    writeScreenshot(rgbData: Buffer, width: number, height: number): ScreenshotHandle;
+    /**
+     * Adds a screenshot to the user's Steam library from a file on disk
+     *
+     * @param filename - Path to the screenshot file (JPEG, TGA, or PNG)
+     * @param thumbnailFilename - Path to thumbnail file (200px wide), or null for auto-generation
+     * @param width - Width of the image in pixels
+     * @param height - Height of the image in pixels
+     * @returns Screenshot handle, or INVALID_SCREENSHOT_HANDLE on failure
+     *
+     * @remarks
+     * - Supported formats: JPEG, TGA, PNG
+     * - If thumbnail is provided, it must be 200 pixels wide with same aspect ratio
+     * - If thumbnail is null, Steam will generate one when the screenshot is uploaded
+     * - This method works without the overlay
+     *
+     * @example Add screenshot from file
+     * ```typescript
+     * // Add a screenshot without custom thumbnail
+     * const handle = steam.screenshots.addScreenshotToLibrary(
+     *   '/path/to/screenshot.png',
+     *   null,
+     *   1920,
+     *   1080
+     * );
+     *
+     * // Add with custom thumbnail
+     * const handle2 = steam.screenshots.addScreenshotToLibrary(
+     *   '/path/to/screenshot.jpg',
+     *   '/path/to/thumb.jpg',
+     *   2560,
+     *   1440
+     * );
+     *
+     * if (handle !== INVALID_SCREENSHOT_HANDLE) {
+     *   steam.screenshots.setLocation(handle, 'Epic Boss Battle');
+     * }
+     * ```
+     */
+    addScreenshotToLibrary(filename: string, thumbnailFilename: string | null, width: number, height: number): ScreenshotHandle;
+    /**
+     * Triggers the Steam overlay to take a screenshot
+     *
+     * @remarks
+     * - If screenshots are hooked via `hookScreenshots(true)`, this sends a
+     *   ScreenshotRequested_t callback instead and your game should capture
+     *   the screenshot manually
+     * - Requires the Steam overlay to be available
+     * - This is equivalent to the user pressing the screenshot hotkey
+     *
+     * @example Trigger overlay screenshot
+     * ```typescript
+     * // Simple screenshot button in your game
+     * function onScreenshotButtonClick() {
+     *   steam.screenshots.triggerScreenshot();
+     * }
+     * ```
+     */
+    triggerScreenshot(): void;
+    /**
+     * Toggles whether your game handles screenshots or Steam does
+     *
+     * @param hook - True to handle screenshots yourself, false to let Steam handle them
+     *
+     * @remarks
+     * When hooked:
+     * - Steam will NOT automatically capture screenshots when user presses hotkey
+     * - Instead, your game receives a ScreenshotRequested_t callback
+     * - Your game should then call `writeScreenshot()` or `addScreenshotToLibrary()`
+     *
+     * This is useful when:
+     * - You want to add custom overlays/HUD to screenshots
+     * - You want to capture from a specific render target
+     * - You need to post-process screenshots before saving
+     *
+     * @example Hook screenshots for custom capture
+     * ```typescript
+     * // Tell Steam we'll handle screenshots
+     * steam.screenshots.hookScreenshots(true);
+     *
+     * // Later, in your screenshot callback handler:
+     * function onScreenshotRequested() {
+     *   // Capture from your render target
+     *   const rgbData = myRenderer.captureScreen();
+     *
+     *   // Add to Steam library
+     *   const handle = steam.screenshots.writeScreenshot(rgbData, 1920, 1080);
+     *   steam.screenshots.setLocation(handle, getCurrentMapName());
+     * }
+     * ```
+     */
+    hookScreenshots(hook: boolean): void;
+    /**
+     * Checks if screenshots are currently hooked by your game
+     *
+     * @returns True if your game is handling screenshots, false if Steam handles them
+     *
+     * @example Check hook status
+     * ```typescript
+     * if (steam.screenshots.isScreenshotsHooked()) {
+     *   console.log('Game is handling screenshots');
+     * } else {
+     *   console.log('Steam overlay handles screenshots');
+     * }
+     * ```
+     */
+    isScreenshotsHooked(): boolean;
+    /**
+     * Sets the location metadata for a screenshot
+     *
+     * @param handle - Screenshot handle from writeScreenshot or addScreenshotToLibrary
+     * @param location - Location string (e.g., map name, level name)
+     * @returns True if location was set successfully
+     *
+     * @remarks
+     * The location is displayed in the Steam screenshot viewer and helps users
+     * remember where screenshots were taken.
+     *
+     * @example Tag screenshot with location
+     * ```typescript
+     * const handle = steam.screenshots.addScreenshotToLibrary(
+     *   '/path/to/screenshot.jpg',
+     *   null,
+     *   1920,
+     *   1080
+     * );
+     *
+     * if (handle !== INVALID_SCREENSHOT_HANDLE) {
+     *   steam.screenshots.setLocation(handle, 'World 3 - Lava Caves');
+     *   steam.screenshots.setLocation(handle, 'Boss: Fire Dragon');
+     * }
+     * ```
+     */
+    setLocation(handle: ScreenshotHandle, location: string): boolean;
+    /**
+     * Tags a Steam user as being visible in the screenshot
+     *
+     * @param handle - Screenshot handle from writeScreenshot or addScreenshotToLibrary
+     * @param steamId - Steam ID of the user to tag (as BigInt)
+     * @returns True if user was tagged successfully
+     *
+     * @remarks
+     * - You can tag up to 32 users per screenshot
+     * - Tagged users will see the screenshot in their profile
+     * - Users can untag themselves from screenshots
+     *
+     * @example Tag friends in screenshot
+     * ```typescript
+     * const handle = steam.screenshots.addScreenshotToLibrary(
+     *   '/path/to/group_photo.jpg',
+     *   null,
+     *   1920,
+     *   1080
+     * );
+     *
+     * if (handle !== INVALID_SCREENSHOT_HANDLE) {
+     *   // Tag all friends visible in the screenshot
+     *   const friends = steam.friends.getAllFriends();
+     *   for (const friend of friends.slice(0, 5)) {
+     *     steam.screenshots.tagUser(handle, friend.steamId);
+     *   }
+     * }
+     * ```
+     */
+    tagUser(handle: ScreenshotHandle, steamId: bigint): boolean;
+    /**
+     * Tags a Workshop item as being visible in the screenshot
+     *
+     * @param handle - Screenshot handle from writeScreenshot or addScreenshotToLibrary
+     * @param publishedFileId - Workshop item ID to tag (as BigInt)
+     * @returns True if item was tagged successfully
+     *
+     * @remarks
+     * - You can tag up to 32 Workshop items per screenshot
+     * - Useful for showing mods/custom content in screenshots
+     * - Tagged items will show the screenshot on their Workshop page
+     *
+     * @example Tag Workshop items in screenshot
+     * ```typescript
+     * const handle = steam.screenshots.addScreenshotToLibrary(
+     *   '/path/to/modded_screenshot.jpg',
+     *   null,
+     *   1920,
+     *   1080
+     * );
+     *
+     * if (handle !== INVALID_SCREENSHOT_HANDLE) {
+     *   // Tag the Workshop mods visible in this screenshot
+     *   const modId = BigInt('123456789');
+     *   steam.screenshots.tagPublishedFile(handle, modId);
+     *
+     *   // Set location too
+     *   steam.screenshots.setLocation(handle, 'Custom Map: Epic Arena');
+     * }
+     * ```
+     */
+    tagPublishedFile(handle: ScreenshotHandle, publishedFileId: bigint): boolean;
+    /**
+     * Adds a VR screenshot to the user's Steam library from files on disk
+     *
+     * @param type - The type of VR screenshot
+     * @param filename - Path to the normal 2D image for library view (JPEG, TGA, or PNG)
+     * @param vrFilename - Path to the VR-specific image matching the type
+     * @returns Screenshot handle, or INVALID_SCREENSHOT_HANDLE on failure
+     *
+     * @remarks
+     * - Supported formats: JPEG, TGA, PNG
+     * - The filename is used for the library thumbnail view
+     * - The vrFilename should contain the appropriate VR format for the type
+     *
+     * @example Add VR screenshot
+     * ```typescript
+     * const handle = steam.screenshots.addVRScreenshotToLibrary(
+     *   EVRScreenshotType.Stereo,
+     *   '/path/to/preview.jpg',
+     *   '/path/to/stereo_screenshot.jpg'
+     * );
+     *
+     * if (handle !== INVALID_SCREENSHOT_HANDLE) {
+     *   steam.screenshots.setLocation(handle, 'VR Level - Space Station');
+     * }
+     * ```
+     */
+    addVRScreenshotToLibrary(type: EVRScreenshotType, filename: string, vrFilename: string): ScreenshotHandle;
+}
+//# sourceMappingURL=SteamScreenshotManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"SteamScreenshotManager.d.ts","sourceRoot":"","sources":["../../src/internal/SteamScreenshotManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAC9C,OAAO,EACL,gBAAgB,EAChB,iBAAiB,EAElB,MAAM,UAAU,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,qBAAa,sBAAsB;IACjC,kDAAkD;IAClD,OAAO,CAAC,aAAa,CAAqB;IAE1C,gEAAgE;IAChE,OAAO,CAAC,OAAO,CAAe;IAE9B,2CAA2C;IAC3C,OAAO,CAAC,oBAAoB,CAAa;IAEzC;;;;;OAKG;gBACS,aAAa,EAAE,kBAAkB,EAAE,OAAO,EAAE,YAAY;IAKpE;;;;OAIG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,gBAAgB;IAsBjF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACH,sBAAsB,CACpB,QAAQ,EAAE,MAAM,EAChB,iBAAiB,EAAE,MAAM,GAAG,IAAI,EAChC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,GACb,gBAAgB;IAsBnB;;;;;;;;;;;;;;;;;OAiBG;IACH,iBAAiB,IAAI,IAAI;IAczB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAcpC;;;;;;;;;;;;;OAaG;IACH,mBAAmB,IAAI,OAAO;IAc9B;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,WAAW,CAAC,MAAM,EAAE,gBAAgB,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAmBhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,OAAO,CAAC,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAmB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,gBAAgB,CAAC,MAAM,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO;IAmB5E;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,wBAAwB,CACtB,IAAI,EAAE,iBAAiB,EACvB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,gBAAgB;CAoBpB"}