GodotSteam

Steam API for the Godot game engine


Project maintained by Gramps Hosted on GitHub Pages — Theme by mattgraham

Introduction

Pre-compiles are available here if you don't want to compile it yourself: https://github.com/Gramps/GodotSteam/releases.

This is the documentation page for GodotSteam, a Steamworks module for Godot Engine, and GodotSteam for GDNative (more on GDNative for Godot 3.0 here). It was initially forked from Kermer's excellent fork which was forked from Mavhod's original. It has since grown from there with more functionality, newer GDNative and Godot 3 version, direct Steamworks API codebase, and more.

You can also view a more up-to-date and expanded version of the documentation at the repository's wiki page!

There are a few things you'll need to start working with the module:

Those are the basics to working with the wrapper. How, to get the most out of it, you'll need these too:

  • Logged into your Steam client if testing your game or any scenes.

From here either navigate to the Module How-To or GDNative How-To.

How To Get Started: GodotSteam module

  1. Download the module repository and unpack it.
  2. Download and unpack the Steamworks SDK.
  3. Download and unpack the Godot Engine source.
  4. Move the following to godotsteam/sdk/:
    sdk/public/
    sdk/redistributable_bin/
  5. The repo's directory contents should now look like this:
    godotsteam/sdk/public/*
    godotsteam/sdk/redistributable_bin/*
    godotsteam/SCsub
    godotsteam/config.py
    godotsteam/godotsteam.cpp
    godotsteam/godotsteam.h
    godotsteam/register_types.cpp
    godotsteam/register_types.h
  6. Now move the "godotsteam" directory into the "modules" directory of the unpacked Godot Engine source.
  7. Recompile for your platform:
  8. When recompiling the engine is finished, copy the shared library (steam_api) from sdk/redistributable_bin/ folders to the Godot binary location (by default in the godot source /bin/ file but you can move them to a new folder). It should look like this:
    • Linux 32/64-bit
      libsteam_api.so
      ./godot.linux.tools.32 or ./godot.linux.tools.64
    • OSX
      libsteam_api.dylib
      ./godot.osx.tools.32 or ./godot.osx.tools.64
    • Windows 32-bit
      steam_api.dll
      ./godot.windows.tools.32.exe
    • Windows 64-bit
      steam_api64.dll
      ./godot.windows.tools.64.exe
  9. Your game must ship with the executable, Steam API DLL/SO/DyLIB, and steam_appid.txt to function. Lack of the Steam API DLL/SO/DyLib (for your respective OS) or the steam_appid.txt will cause it fail and crash.
    • NOTE: For OSX, the libsteam_api.dylib and steam_appid.txt must be in the Content/MacOS/ folder in your application zip or the game will crash.

From here you should be able to call various functions of Steamworks. You should be able to look up the functions in Godot itself under the search section. In addition, you should be able to read the Steamworks API documentation to see what all is available and cross-reference with GodotSteam.

You may notice that achievements and stats do not work properly if the game is tested outside of Steam (as in running it from the Steam client itself). This behavior seems to be new within the last few weeks and is most likely a changed on Valve's end.

How To Get Started: GodotSteam For GDNative

  1. Download the GodotNative GDNative repository and unpack it.
  2. Download and unpack the Steamworks SDK.
  3. Download and unpack the Godot Engine 3.0 binary.
  4. Download the GDNative starter pack.
  5. Recommended you compile the bindings as the GDNative Starter kit may not be up to date.
    1. Download the CPP bindings and Godot headers.
    2. Follow their instructions for proper layout, you may need to change the Scon file to the right directories
    3. Compile the core first:
      scons platform=[your platform] target=core
    4. The compile the bindings:
      scons platform=[your platform] target=bindings generate_bindings=yes
  6. Alternately, download the GDNative Starter kit.
  7. Unpack the starter kit into your project's root folder or place the bindings into your lib/ folder, depending on which previous step you took.
  8. Unpack the Steamworks SDK then copy the public and redistributable_bin** to /include/sdk folder.
  9. Unpack this repo and place it into your project's root folder.
    • Allow the folders to merge.
    • Nothing should overwrite unless you are updating to a new version of this repo.
  10. You should end up with a project folder that looks something like this:
    include/godot/*
    include/godot_cpp/*
    include/godot_cpp/core/*
    include/sdk/public/steam/*include/sdk/redistributable_bin/*
    include/godot.h
    lib/godot.windows.opt.tools.64.lib
    lib/godot_cpp_bindings.lib
    lib/godot_cpp_core.lib
    lib/godotsteam.tres
    lib/libgodot_cpp_bindings.so (for Linux)
    lib/libgodot_cpp_core.so (for Linux)
    lib/godot_cpp_bindings.dll (for Windows)
    lib/godot_cpp_core.dll (for Windows)
    lib/steam.tscn
    src/godotsteam.cpp
    src/init.cpp
    src/SConstruct
  11. Navigate to the src directory in your project and run:
    scons platform=[your platform]
  12. You can enter the bit architecture with **bits** or **b** arguments or not. There is a fallback to automatically find this. However, I recommend you use one.

OPTIONAL: if you choose not to use the included steam.tscn file, follow these steps. Otherwise, continue on to the next section.

  1. Create a new scene with one node as a, well, Node.
    1. Name it Steam.
    2. Save the scene as steam.tscn in your project.
    3. On Inspector tab for this node, select a new script.
    4. Name it Steam.
    5. Set language as Native.
    6. Set path: built-in script to On.
    7. Press create.
  2. Under newly created script settings in Inspector tab.
    1. Click next to Library and select New GDNativeLibrary.
    2. Click the right arrow and it should show a list of platforms.
    3. Select the platforms you built for.
      • You could dump multiple platform files (SO, DLL, Dylib) into your folder to select more than one.
    4. For each selected platform, link the right file by clicking the folder icon next to them.
      • Example: x11 would link libgodotsteam.so, Windows would link godotsteam.dll, Mac would link libgodotsteam.dylib
    5. Then press the save icon and save this as godotsteam.tres in your lib folder.

The last step after doing the above optional steps or just using the supplied steam.tscn file in /lib.

  1. Add the steam.tscn to your project as a singelton in the AutoLoad section under Project Settings.
  2. Done!

Now you should be able to call functions from GodotSteam like you would normally with the GodotSteam module:

steam.steamInit()
steam.getIPCountry()
steam.isSteamRunning()

Functions and Features

Here is a list of all the functions and features available in the GodotSteam module. Many will reference appID or steamID. AppID always references to a game, applications, or DLC's ID number in Steam. The steamID, however, can reference a user, lobby session, server, or such.

Basics

  • steamInit()
    - Starts up the Steam API.
  • isSteamRunning()
    - Returns true/false if Steam is running
  • restartAppIfNecessary( int appID )
    - Checks if your executable was launched through Steam and relaunches it through Steam if it wasn't.
    - Returns bool; if true then it starts the Steam client (if required) and launches your application again. If false, then the game was launched through Steam and no action is needed.
  • run_callbacks()
    - From my understanding, this should be run often if you are expecting them. Should be called in the _process(true) function.

Apps

  • hasOtherApp( int appID )
    - Does the user own the given application/game for this appID?
  • getDLCCount()
    - Get the total number of DLC installed for this application/game.
  • isDLCInstalled( int appID )
    - Is the given DLC appID installed for this application/game?
  • requestAppProofOfPurchaseKey( int appID )
    - Returns purchase key for given application/game in a callback (currently not working).
  • isAppInstalled( int appID )
    - Check if given application/game is installed, not necessarily owned.
  • getCurrentGameLanguage()
    - Get the user's current game language (ie. english, russian, french).
  • isVACBanned()
    - Does the user have a VAC ban for this game.
  • getEarliestPurchaseUnixTime( int value )
    - Returns the Unix time of the purchase of the app.
  • isSubscribedFromFreeWeekend()
    - Checks if the user is subscribed to the current app through a free weekend.
  • installDLC( int value )
    - Install control for optional DLC.
  • uninstallDLC( int value )
    - Uninstall control for optional DLC.
  • isSubscribed()
    - Is user subscribed too...? Lacks notes from Valve.
  • isLowViolence()
    - Set to low violence in Steam? Lacks notes from Valve.
  • isCybercafe()
    - Is user a cyber cafe? Lacks notes from Valve.
  • isSubscribedApp( int value )
    - Checks ownership of another game related to yours: a demo, etc.
  • getAppBuildId()
    - Returns the build ID for this application; will change based on backend updates.

Friends

  • getFriendCount()
    - Get the number of friends the user has.
  • getPersonaName()
    - Get the user's Steam username.
  • getFriendPersonaName( int steamID )
    - Get the given user's Steam username.
  • setGameInfo( stringserver key, stringserver value )
    - Set the game information in Steam; used in 'View Game Info'. Must be set as a key/value pair; multiple may be set.
  • clearGameInfo()
    - Clear the game information in Steam; used in 'View Game Info'.
  • inviteFriend( int steamID, stringconnection )
    - Invite friend ot current game/lobby.
  • setPlayedWith( int steamID )
    - Set player as 'Played With' for current game.
  • getRecentPlayers()
    - Get list of players user has recently played game with.
  • getFriendAvatar( int size )
    - Get player's avatar.
  • activateGameOverlay( string dialog )
    - Activates the overlay with optional dialog to open the following: "Friends", "Community", "Players", "Settings", "OfficialGameGroup", "Stats", "Achievements", "LobbyInvite".
  • activateGameOverlayToUser( string url, int steamID )
    - Activates the overlay to the following: "steamid", "chat", "jointrade", "stats", "achievements", "friendadd", "friendremove", "friendrequestaccept", "friendrequestignore".
  • activateGameOverlayToWebPage( string url )
    - Activates the overlay with specified web address.
  • activateGameOverlayToStore( int appID )
    - Activates the overlay with the application/game Steam store page.
  • activateGameOverlayInviteDialog( int steamID )
    - Activates game overlay to open the invite dialog. Invitations will be sent for the provided lobby.
  • getUserSteamGroups()
    - Get list of user's Steam groups; a mix of different Steamworks API group functions.
  • getUserSteamFriends()
    - Get a list of user's Steam friends; a mix of different Steamworks API friend functions.
  • activateGameOverlayInviteDialog( int steamID )
    - Activates game overlay to open the invite dialog. Invitations will be sent for the provided lobby.

Matchmaking

  • createLobby( int lobby type, int max members )
    - Create a lobby on the Steam servers, if private the lobby will not be returned by any RequestLobbyList() call.
  • joinLobby( int lobby ID )
    - Join an existing lobby.
  • leaveLobby( int lobby ID )
    - Leave a lobby, this will take effect immediately on the client side, other users will be notified by LobbyChatUpdate_t callback.
  • inviteUserToLobby( int lobby ID, int steamID )
    - Invite another user to the lobby, the target user will receive a LobbyInvite_t callback, will return true if the invite is successfully sent, whether or not the target responds.

Music

  • musicIsEnabled()
    - Is Steam music enabled?
  • musicIsPlaying()
    - Is Steam music playing something?
  • musicGetVolume()
    - Get the volume level of the music. Returned as a float.
  • musicPause()
    - Pause whatever Steam music is playing.
  • musicPlay()
    - Play current track/album.
  • musicPlayNext()
    - Play next track/album.
  • musicPlayPrev()
    - Play previous track/album.
  • musicSetVolume( float value )
    - Set the volume of Steam music. Must pass a float between 0.0 and 1.0.

Remote Storage

  • fileWrite( string file, void data, int data)
    - Write user file to remote online storage.
  • fileRead( string file, void data, int data to read)
    - Read user file from remote online storage.
    - Returns a Dictionary with d["ret"] and d["buf"].
  • fileForget( string file )
    - Deletes the file from remote storage, but leaves it on the local disk and remains accessible from the API.
    - Returns 1 if forgotten, 0 if not.
  • fileDelete( string file )
    - Delete user file from remote online storage.
    - Returns 1 if deleted successfully, 0 if not.
  • fileExists( string file )
    - Check if a remote file exists.
    - Returns 1 if it does, 0 if it does not.
  • filePersisted( string file )
    - Checks if a specific file is persisted in the Steam Cloud. Depreciated: PS3 Only
    - Returns 1 if it has, 0 if it has not.
  • getFileSize( string file )
    - Get the size of the current file.
    - Returns the file size in bytes.
  • getFileTimestamp( string file )
    - Get the timestamp of when the file was uploaded.
    - Returns datetime in Unix format.
  • getFileCount()
    - Get the number of files saved on Steam Cloud.
    - Returns an integer; the number of files present for the current user, including files in subfolders.
  • isCloudEnabledForAccount()
    - Check if Cloud Saves/Storage is enabled for the user's account.
    - Returns 1 if enabled, 0 if not.
  • isCloudEnabledForApp()
    - Check if Cloud Saves/Storage is enabled for the application.
    - Returns 1 if enabled, 0 if not.
  • 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.

Screenshots

  • hookScreenshots( bool hook)
    - Toggles whether the overlay handles screenshots
  • isScreenshotsHooked()
    - Checks if the app is hooking screenshots
  • triggerScreenshot()
    - Causes the Steam overlay to take a screenshot.
  • writeScreenshot( array data, int width, int height )
    - Writes a screenshot to the user's Steam screenshot library

Signals

  • _lobby_created
    - Signal the lobby has been created.
  • _lobby_joined
    - Signal that lobby has been joined.
  • _lobby_invite
    - Signal that a lobby invite was sent.
  • _join_requested
    - Signal a game/lobby join has been requested.
  • _avatar_loaded
    - Signal that the avatar has been loaded.
  • _number_of_current_players
    - Signal number of current players (online + offline)
  • _leaderboard_loaded
    - Signal a leaderboard has been loaded or has failed.
  • _leaderboard_uploaded
    - Signal a leaderboard entry has been uploaded
  • _leaderboard_entries_loaded
    - Signal leaderboard entries are downloaded.
  • _overlay_toggled
    - Signal when overlay is triggered.
  • _low_power
    - Signal when battery power is running low, less than 10 minutes left.
  • _server_connected
    - When connected to a server.
  • _server_disconnected
    - When disconnected from a server.
  • _dlc_installed
    - Posted after the user gains ownership of DLC & that DLC is installed.
  • _get_auth_session_ticket_response
    - Response from getAuthSessionTicket
  • _validate_auth_ticket_response
    - Called when an authentication ticket has been validated
  • _screenshot_ready
    - A screenshot has been requested by the user

UGC (User Generated Content) / Workshop

  • getNumSubscribedItems()
    - Number of subscribed items.
  • getItemState( int file ID )br />- Get EItemState flags about item on this client.
  • downloadItem( int file ID, bool high priority )
    - Download new or update already installed item. If returns true, wait for DownloadItemResult_t. If item is already installed, then files on disk should not be used until callback received.
  • suspendDownloads( bool suspend )
    - SuspendDownloads( true ) will suspend all workshop downloads until SuspendDownloads( false ) is called or the game ends.

Users

  • getSteamID()
    - Get the user's Steam ID (ID3).
  • loggedOn()
    - Check, true/false, if user is logged into Steam currently.
  • getPlayerSteamLevel()
    - Get the user's Steam level.
  • getUserDataFolder()
    - Get the user's Steam installation path.
  • advertiseGame( string server IP, int port )
    - (LEGACY FUNCTION) Set data to be replicated to friends so that they can join your game.
  • getGameBadgeLevel( int series, bool foil )
    - Trading Card badges data access, if you only have one set of cards, the series will be 1.
  • getAuthSessionTicket()
    - Get an authentication ticket
  • cancelAuthTicket( int ticket )
    - Cancels an authentication ticket
  • beginAuthSession( int ticket, int steamID )
    - Authenticate the ticket from the entity's Steam ID to be sure it is valid and isn't reused
  • endAuthSession(( int steamID )
    - Ends an authentication session

User Statistics

  • getAchievement( string name )
    -Return true/false if use has given achievement.
  • getStatInt( string name )
    - Get the value of an integer statistic.
  • getStatFloat( string name )
    - Get the value of a float statistic.
  • resetAllStats( bool achievements too )
    - Reset all Steam statistics; optional to reset achievements.
  • requestCurrentStats()
    - Request all statistics and achievements from Steam servers.
  • setAchievement( string name )
    - Set a given achievement.
  • setStatFloat( string name, float value )
    - Set a statistic.
  • setStatInt( string name, int value )
    - Set a statistic.
  • storeStats()
    - Store all statistics, and achievements, on Steam servers; must be called to "pop" achievements.
  • clearAchievement( string name )
    - Clears a given achievement.
  • findLeaderboard( string name )
    - Find a given leaderboard, by name.
  • getLeaderboardName()
    - Get the name of a leaderboard.
  • getLeaderboardEntryCount()
    - Get the total number of entries in a leaderboard, as of the last request.
  • downloadLeaderboardEntries( int start, int end, int type )
    - Request all rows for friends of user.
  • downloadLeaderboardEntriesForUsers( array users ID )
    - Request a maximum of 100 users with only one outstanding call at a time.
  • uploadLeaderboardScore( int score, bool keep best )
    - Upload a leaderboard score for the user.
  • getDownloadedLeaderboardEntry( string handle, int entry count )
    - Once all entries are accessed, the data will be freed up and the handle will become invalid, use this to store it.
  • updateLeaderboardHandle( string handle )
    - Update the currently used leaderboard handle.
  • getLeaderboardHandle()
    - Get the currently used leaderboard handle.
  • getLeaderboardEntries()
    - Get the currently used leaderboard entries.
  • getAchievementAndUnlockTime( string name, bool achieved, int unlock time )
    - Get the achievement status, and the time it was unlocked if unlocked (in seconds since January 1, 19).
  • indicateAchievementProgress( string name, int current progress, int max progress )
    - Achievement progress, triggers an AchievementProgress callback, that is all.

Utilities

  • getCurrentBatteryPower()
    - Get the amount of battery power, clearly for laptops.
  • getIPCountry()
    - Get the user's country by IP.
  • getSecondsSinceAppActive()
    - Returns seconds since application/game was started.
  • getServerRealTime()
    - Get the actual time.
  • isOverlayEnabled()
    - Returns true/false if Steam overlay is enabled.
  • isSteamRunningInVR()
    - Is Steam running in VR?.
  • getSteamUILanguage()
    - Get the Steam user interface language.
  • getAppID()
    - Get the Steam ID of the running application/game.
  • setOverlayNotificationPosition( int pos )
    - Set the position where overlay shows notifications. Accepts integers 0-3 (top left, top right, bottom left, bottom right).
  • isSteamInBigPictureMode()
    - Returns true if Steam & the Steam Overlay are running in Big Picture mode.
  • startVRDashboard()
    - Ask SteamUI to create and render its OpenVR dashboard.