Functions | Remote Storage

Here is a list of all the functions available in the GodotSteam module. The descriptions are pulled from the official Steamworks SDK documentation with modifications made to fit GodotSteam's implementation of the functions. Naturally, any GodotSteam-specific functions will be noted as such.


beginFileWriteBatch()

  • Use this along with endFileWriteBatch to wrap a set of local file writes/deletes that should be considered part of one single state change. For example, if saving game progress requires updating both savegame1.dat and maxprogress.dat, wrap those operations with calls to beginFileWriteBatch and endFileWriteBatch.
  • These functions provide a hint to Steam which will help it manage the app's Cloud files. Using these functions is optional, however it will provide better reliability.
  • Note that the functions may be used whether the writes are done using the Remote Storage API, or done directly to local disk (where AutoCloud is used).
  • Returns a bool.

endFileWriteBatch()

  • Use this along with beginFileWriteBatch - see that documentation for more details.
  • Returns a bool.

fileDelete( string file )

  • Deletes a file from the local disk, and propagates that delete to the cloud.
  • This is meant to be used when a user actively deletes a file. Use fileForget if you want to remove a file from the Steam Cloud but retain it on the users local disk.
  • When a file has been deleted it can be re-written with fileWrite to reupload it to the Steam Cloud.
  • Returns a bool.

fileExists( string file )

  • Check if a remote file exists.
  • Returns a bool.

fileForget( string file )

  • Deletes the file from remote storage, but leaves it on the local disk and remains accessible from the API.
  • When you are out of Cloud space, this can be used to allow calls to fileWrite to keep working without needing to make the user delete files.
  • How you decide which files to forget are up to you. It could be a simple Least Recently Used (LRU) queue or something more complicated.
  • Requiring the user to manage their Cloud-ized files for a game, while is possible to do, it is never recommended. For instance, "Which file would you like to delete so that you may store this new one?" removes a significant advantage of using the Cloud in the first place: its transparency.
  • Once a file has been deleted or forgotten, calling fileWrite will resynchronize it in the Cloud. Rewriting a forgotten file is the only way to make it persisted again.
  • Returns a bool.

filePersisted( string file )

  • Checks if a specific file is persisted in the Steam Cloud.
  • Returns a bool.

fileRead( string file, int data_to_read ) fileRead( string file, uint32_t data_to_read )

  • Opens a binary file, reads the contents of the file into a byte array, and then closes the file.
  • Note: This is a synchronous call and as such is a will block your calling thread on the disk IO, and will also block the SteamAPI, which can cause other threads in your application to block. To avoid "hitching" due to a busy disk on the client machine using fileReadAsync, the asynchronous version of this API is recommended.
  • Returns a dictionary:
    • ret (bool)
    • buf (PoolByteArray)

fileReadAsync( string file, int offset, int data_to_read ) fileReadAsync( string file, uint32 offset, uint32_t data_to_read )

  • Starts an asynchronous read from a file. The offset and amount to read should be valid for the size of the file, as indicated by getFileSize or getFileTimestamp.
  • Triggers a _file_read_async_complete call result.
  • Returns nothing; void.

fileShare( string file )

  • Share a file.
  • Triggers a file_share_result call result.
  • Returns nothing; void.

fileWrite( string file, PoolByteArray data )

  • Creates a new file, writes the bytes to the file, and then closes the file. If the target file already exists, it is overwritten.
  • Note: This is a synchronous call and as such is a will block your calling thread on the disk IO, and will also block the SteamAPI, which can cause other threads in your application to block. To avoid "hitching" due to a busy disk on the client machine using fileWriteAsync, the asynchronous version of this API is recommended.
  • Returns a bool.

fileWriteAsync( string file, PoolByteArray data )

  • Creates a new file and asynchronously writes the raw byte data to the Steam Cloud, and then closes the file. If the target file already exists, it is overwritten.
  • Triggers a _file_write_async_complete call result.
  • Returns nothing; void.

fileWriteStreamCancel( int write_handle ) fileWriteStreamCancel( uint64_t write_handle )

  • Cancels a file write stream that was started by fileWriteStreamOpen.
  • This trashes all of the data written and closes the write stream, but if there was an existing file with this name, it remains untouched.
  • Returns a bool.

fileWriteStreamClose( int write_handle ) fileWriteStreamClose( uint64_t write_handle )

  • Closes a file write stream that was started by fileWriteStreamOpen.
  • This flushes the stream to the disk, overwriting the existing file if there was one.
  • Returns a bool.

fileWriteStreamOpen( string file )

  • Creates a new file output stream allowing you to stream out data to the Steam Cloud file in chunks. If the target file already exists, it is not overwritten until fileWriteStreamClose has been called.
  • To write data out to this stream you can use fileWriteStreamWriteChunk, and then to close or cancel you use fileWriteStreamClose and fileWriteStreamCancel respectively.
  • Returns an int. Returns a uint64_t.

fileWriteStreamWriteChunk( int write_handle, PoolByteArray data ) fileWriteStreamWriteChunk( uint64_t write_handle, PoolByteArray data )

  • Writes a blob of data to the file write stream.
  • Returns a bool.

getCachedUGCCount()

  • Gets the number of cached UGC.
  • Returns an int. Returns an int32.

getCachedUGCHandle( int content ) getCachedUGCHandle( int32 content )

  • Gets the cached UGC's handle.
  • Returns an int. Returns a uint64_t.

getFileCount()

  • Gets the total number of local files synchronized by Steam Cloud.
  • Used for enumeration with getFileNameAndSize.
  • Returns an int. Returns a uint32_t.

getFileNameAndSize( int file )

  • Gets the file name and size of a file from the index.
  • Note: You must call getFileCount first to get the number of files.
  • Returns a dictionary:
    • name (string)
    • size (int)
    • name (string)
    • size (int32_t)

getFileSize( string file )

  • Get the size of the current file.
  • Returns an int. Returns an int32_t.

getFileTimestamp( string file )

  • Get the timestamp of when the file was uploaded.
  • Returns an int. Returns an int64_t.

getLocalFileChange( int file )

  • Note: only applies to applications flagged as supporting dynamic Steam Cloud sync.
  • After calling getLocalFileChangeCount, use this method to iterate over the changes. The changes described have already been made to local files. Your application should take appropriate action to reload state from disk, and possibly notify the user.
  • For example: The local system had been suspended, during which time the user played elsewhere and uploaded changes to the Steam Cloud. On resume, Steam downloads those changes to the local system before resuming the application. The application receives an local_file_changed, and uses getLocalFileChangeCount and getLocalFileChange to iterate those changes. Depending on the application structure and the nature of the changes, the application could:
    • Re-load game progress to resume at exactly the point where the user was when they exited the game on the other device
    • Notify the user of any synchronized changes that don't require reloading
    • Etc.
  • Returns a dictionary:
    • file (string)
    • change_type (int)
    • path_type (int)

getLocalFileChangeCount()

  • Note: only applies to applications flagged as supporting dynamic Steam Cloud sync.
  • When your application receives a local_file_changed, use this method to get the number of changes (file updates and file deletes) that have been made. You can then iterate the changes using getLocalFileChange.
  • Returns an int. Returns a uint32_t.

getQuota()

  • Gets the number of bytes available, and used on the users Steam Cloud storage.
  • Returns a dictionary:
    • total_bytes (int)
    • available_bytes (int)
    • total_bytes (uint64_t)
    • available_bytes (uint64_t)

getSyncPlatforms( string file )

  • Obtains the platforms that the specified file will synchronize to.
  • Returns a dictionary:
    • bitwise (int)
      • 0 - None
      • 1<<0 - Windows
      • 1<<1 - OSX
      • 1<<2 - PS3
      • 1<<3 - Linux
      • 1<<4 - Reserved
      • 0xffffffff - All
    • verbose (string)

getUGCDetails( int content ) getUGCDetails( uint64_t content )

  • Gets metadata for a file after it has been downloaded. This is the same metadata given in the download_ugc_result call result.
  • Returns a dictionary:
    • handle (int)
    • app_id (int)
    • size (int)
    • filename (string)
    • owner_id (int)
    • handle (uint64_t)
    • app_id (uint32_t)
    • size (int32)
    • filename (string)
    • owner_id (uint64_t)

getUGCDownloadProgress( int content ) getUGCDownloadProgress( uint64_t content )

  • Gets the amount of data downloaded so far for a piece of content. bytes_expected can be 0 if function returns false or if the transfer hasn't started yet, so be careful to check for that before dividing to get a percentage.
  • Returns a dictionary:
    • bytes_downloaded (int)
    • bytes_expected (int)
    • bytes_downloaded (int32)
    • bytes_expected (int32)

isCloudEnabledForAccount()

  • Checks if the account wide Steam Cloud setting is enabled for this user; or if they disabled it in the Settings->Cloud dialog.
  • Ensure that you are also checking isCloudEnabledForApp, as these two options are mutually exclusive.
  • Returns a bool.

isCloudEnabledForApp()

  • Checks if the per game Steam Cloud setting is enabled for this user; or if they disabled it in the Game Properties->Update dialog.
  • Ensure that you are also checking isCloudEnabledForAccount, as these two options are mutually exclusive.
  • It's generally recommended that you allow the user to toggle this setting within your in-game options, you can toggle it with setCloudEnabledForApp.
  • Returns a bool.

setCloudEnabledForApp( bool enabled )

  • Enable or disable Steam Cloud for this application. This must only ever be called as the direct result of the user explicitly requesting that it's enabled or not. This is typically accomplished with a checkbox within your in-game options.
  • Returns a bool.

setSyncPlatforms( string file, int platform )

  • Allows you to specify which operating systems a file will be synchronized to.
  • Use this if you have a multiplatform game but have data which is incompatible between platforms.
  • Files default to k_ERemoteStoragePlatformAll (0xffffffff) when they are first created. You can use the bitwise OR operator, "|" to specify multiple platforms.
  • Returns a bool.

ugcDownload( int content, int priority ) ugcDownload( uint64_t content, uint32 priority )

  • Downloads a UGC file.
  • A priority value of 0 will download the file immediately, otherwise it will wait to download the file until all downloads with a lower priority value are completed. Downloads with equal priority will occur simultaneously.
  • Returns nothing; void.

ugcDownloadToLocation( int content, string location, int priority ) ugcDownloadToLocation( uint64_t content, string location, uint32 priority )

  • Downloads a UGC file to a specific location.
  • Returns nothing; void.

ugcRead( int content, int data_size, int offset, int action ) ugcRead( uint64_t content, int32 data_size, uint32 offset, int action )

  • After download, gets the content of the file.
  • Returns a PoolByteArray.