5

Description

"In this tutorial, we will cover the basic initialization of Steamworks with GodotSteam in your game; as well as getting callbacks globally and getting data about the users. [Check out the common issues tutorial if](https:\/\/godotsteam.com\/issues\/common_issues) you have issues getting things to work too.\r\n\r\nPlease note, this tutorial is only valid for the module and GDExtension versions of GodotSteam; the GDNative version will already have these functions present in the **[steam.gd](https:\/\/github.com\/GodotSteam\/GodotSteam\/blob\/gdnative-plugin\/addons\/godotsteam\/steam.gd)** autoload script.\r\n\r\n??? guide Relevant GodotSteam classes and functions\r\n* [Main class](https:\/\/godotsteam.com\/classes\/main)\r\n\t* [steamInit()](https:\/\/godotsteam.com\/classes\/main#steaminit)\r\n\t* [steamInitEx()](https:\/\/godotsteam.com\/classes\/main#steaminitex)\r\n\t* [run_callbacks()](https:\/\/godotsteam.com\/classes\/main#run_callbacks)\r\n* [Apps class](https:\/\/godotsteam.com\/classes\/apps)\r\n * [getAppBuildId()](https:\/\/godotsteam.com\/classes\/apps#getappbuildid)\r\n * [getAppInstallDir()](https:\/\/godotsteam.com\/classes\/apps#getappinstalldir)\r\n * [getAppOwner()](https:\/\/godotsteam.com\/classes\/apps#getappowner)\r\n * [getAvailableGameLanguages()](https:\/\/godotsteam.com\/classes\/apps#getavailablegamelanguages)\r\n * [getCurrentGameLanguage()](https:\/\/godotsteam.com\/classes\/apps#getcurrentgamelanguages)\r\n * [getInstalledDepots()](https:\/\/godotsteam.com\/classes\/apps#getinstalleddepots)\r\n * [getLaunchCommandLine()](https:\/\/godotsteam.com\/classes\/apps#getlaunchcommandline)\r\n * [isSubscribed()](https:\/\/godotsteam.com\/classes\/apps#issubscribed)\r\n* [Friends class](https:\/\/godotsteam.com\/classes\/friends)\r\n\t* [getPersonaName()](https:\/\/godotsteam.com\/classes\/friends#getpersonaname)\r\n* [User class](https:\/\/godotsteam.com\/classes\/user)\r\n\t* [getSteamID()](https:\/\/godotsteam.com\/classes\/user#getsteamid)\r\n\t* [loggedOn()](https:\/\/godotsteam.com\/classes\/user#loggedon)\r\n* [Utils class](https:\/\/godotsteam.com\/classes\/utils)\r\n * [getSteamUILanguage()](https:\/\/godotsteam.com\/classes\/utils#getsteamuilanguage)\r\n * [isSteamRunningOnSteamDeck()](https:\/\/godotsteam.com\/classes\/utils#issteamrunningonsteamdeck)\r\n * [isSteamRunningInVR()](https:\/\/godotsteam.com\/classes\/utils#issteamrunninginvr)\r\n???\r\n\r\n## Preparation{.block}\r\n\r\nBefore we go any further, it is recommended that you enable logging in your project if you have not done so. This will help both you, and us, debug any issues you might run into down the road. Of course, if you have a custom logging system, don't worry about this.\r\n\r\n::: tabs\r\n@tab:active Godot 2.x, 3.x\r\nTo enable logging in the Godot editor, go to: **Projects > Project Settings > Logging > File Logging** and check **Enable File Logging**. This will start placing logs in your project's user data folder. Where are these, you might ask? [Check out the official Godot Engine documentation to find the locations.](https:\/\/docs.godotengine.org\/en\/stable\/tutorials\/io\/data_paths.html?highlight=user%20data)\r\n\r\n\r\n@tab Godot 4.x\r\nTo enable logging in the Godot editor, go to: **Projects > Project Settings > Debug > File Logging** and check **Enable File Logging**. This will start placing logs in your project's user data folder. Where are these, you might ask? [Check out the official Godot Engine documentation to find the locations.](https:\/\/docs.godotengine.org\/en\/stable\/tutorials\/io\/data_paths.html?highlight=user%20data)\r\n\r\n:::\r\n\r\n## Steam App ID{.block}\r\n\r\nWhen the game is run through the Steam client, it already knows which game you are playing. However, during development and testing, you must supply a valid app ID somehow. Typically, if you do not already have an app ID, you can use **app ID 480** which is Valve's SpaceWar example game. You can set the app ID in one of three ways, depending on what is easiest for you:\r\n\r\n### Method 1: steam_appid.txt\r\n\r\nCreate a steam_appid.txt file and with _only_ the app ID as the text. This file must be where ever your regular Godot or GodotSteam-enabled editor is located. Though, in the case of plug-ins, sometimes it must be in the root of your project to work correctly. Also, when shipping your game to Steam, _do not include this file_ as it is not needed. Granted it won't hurt anything if you do.\r\n\r\n### Method 2: Pass It To Initialization\r\n\r\nYou can pass the app ID to either **steamInit()** or **steamInitEx()** to set it during initialization. This will vary based on the version of GodotSteam you are using as **Steamworks SDK 1.61** automatically syncs user data before the game launches. In GodotSteam versions 3.27 \/ 4.11 or earlier, setting the app ID will be the second argument passed. And in GodotSteam versions 3.28 \/ 4.12 or later, it will be the first argument passed. For example:\r\n\r\n::: tabs\r\n@tab:active GodotSteam 3.27 \/ 4.11 Or Earlier\r\n```gdscript\r\nvar initialize_response: Dictionary = Steam.steamInitEx( true, 480 )\r\nprint(\"Did Steam initialize?: %s \" % initialize_response)\r\n```\r\nIf you use this method, you **must** pass a true or false as for the first argument.\r\n\r\n@tab GodotSteam 3.28 \/ 4.12 Or Later\r\n```gdscript\r\nvar initialize_response: Dictionary = Steam.steamInitEx ( 480 )\r\nprint(\"Did Steam initialize?: %s \" % initialize_response)\r\n```\r\n:::\r\n\r\n!!! warning Notes\r\nThis functionality **does not** exist in GDNative. It only exists in GodotSteam 3.22 and up for Godot 3.x and GodotSteam 4.5 and up for Godot 4.x and GDExtension.\r\n!!!\r\n\r\n### Method 3: Set Environment Variables\r\n\r\nYou can set two environment variables in an autoload GDscript or the first GDscript to run; preferably the script where you run the Steam initialization function and preferably in the **_init()** function. For example:\r\n\r\n```gdscript\r\nfunc _init() -> void:\r\n\t# Set your game's Steam app ID here\r\n\tOS.set_environment(\"SteamAppId\", str(app_id))\r\n\tOS.set_environment(\"SteamGameId\", str(app_id))\r\n```\r\n\r\nThanks to user **B0TLANNER** for providing this method.\r\n\r\n## Initialize Steam{.block}\r\n\r\nIn my personal projects, I usually create an auto-load GDscript called **[steamworks.gd](https:\/\/github.com\/GodotSteam\/Skillet\/blob\/master\/src\/autoload\/steamworks.gd)** which is added as a singleton. I then create a function called **initialize_steam()** and add the code below. This is then called from the **_ready()** function in my **[steamworks.gd](https:\/\/github.com\/GodotSteam\/Skillet\/blob\/master\/src\/autoload\/steamworks.gd)**:\r\n\r\n```gdscript\r\nfunc _ready() -> void:\r\n\tinitialize_steam()\r\n\r\n\r\nfunc initialize_steam() -> void:\r\n\tvar initialize_response: Dictionary = Steam.steamInitEx()\r\n\tprint(\"Did Steam initialize?: %s \" % initialize_response)\r\n```\r\n\r\nBy default, in GodotSteam versions 3.27 \/ 4.11 or earlier, **steamInitEx()** will query Steamworks for the local user's current statistics and send this data back as a callback (signal). You can pass a boolean (false) to the function to prevent this behavior: **steamInitEx( false )**. In GodotSteam versions 3.28 \/ 4.12 or later, thanks to Steamworks SDK 1.61, this happens automatically at the client level. **steamInitEx()** will always send back a dictionary with two keys \/ values:\r\n\r\n- \"verbal\" - The verbose, text version of status\r\n- \"status\" - A status code with various results:\r\n * 0: Successfully initialized\r\n * 1: Some other failure\r\n * 2: We cannot connect to Steam, the client probably isn't running\r\n * 3: Steam client appears to be out of date\r\n\r\n## Checking For Errors{.block}\r\n\r\nThe returned dictionary from **steamInitEx()** can be printed and ignored. However, there are certain conditions where you might not know why the game crashed at boot or does something unexpected; especially in development. For these cases we will check if Steamworks was actually initialized and to stop the game if anything is amiss, we do this:\r\n\r\n```gdscript\r\nfunc initialize_steam() -> void:\r\n var initialize_response: Dictionary = Steam.steamInitEx()\r\n\tprint(\"Did Steam initialize?: %s\" % initialize_response)\r\n\r\n\tif initialize_response['status'] > Steam.STEAM_API_INIT_RESULT_OK:\r\n\t\tprint(\"Failed to initialize Steam, shutting down: %s\" % initialize_response)\r\n\t\tget_tree().quit()\r\n```\r\n\r\nThis code will obviously shut down the game if Steam does not initialize and returns a status of anything except 0. You may just want to capture the failure data and continue on, though the Steamworks functionality won't quite work. Most times, in development, getting a failure will probably be caused by a missing API file (steam_api.dll, libsteam_api.so, libsteam_api.dylib) or not setting the game's app ID by one of the methods mentioned earlier. In any case, the intialization functions should give you a pretty good idea of why it failed. If you still cannot figure it out, please contact us for assistance!\r\n\r\n!!! warning Notes\r\nGDNative **does not** have access to any enums so Steam.STEAM_API_INIT_RESULT_OK does not exist. You will want to check for 0 instead.\r\n!!!\r\n\r\n## Getting More Data{.block}\r\n\r\nThere are a ton of functions you can call just after initialization to gather more data about your user; everything from location, to language used, to avatars, etc. While we won't go over each of them in this tutorial, here are some things you can grab:\r\n\r\n```gdscript\r\nvar app_installed_depots: Array = Steam.getInstalledDepots( app_id )\r\nvar app_languages: String = Steam.getAvailableGameLanguages()\r\nvar app_owner: int = Steam.getAppOwner()\r\nvar build_id: int = Steam.getAppBuildId()\r\nvar game_language: String = Steam.getCurrentGameLanguage()\r\nvar install_dir: Dictionary = Steam.getAppInstallDir( app_id )\r\nvar is_on_steam_deck: bool = Steam.isSteamRunningOnSteamDeck()\r\nvar is_on_vr: bool = Steam.isSteamRunningInVR()\r\nvar is_online: bool = Steam.loggedOn()\r\nvar is_owned: bool = Steam.isSubscribed()\r\nvar launch_command_line: String = Steam.getLaunchCommandLine()\r\nvar steam_id: int = Steam.getSteamID()\r\nvar steam_username: String = Steam.getPersonaName()\r\nvar ui_language: String = Steam.getSteamUILanguage()\r\n```\r\n\r\nThis will check if Steam is online, if the app is running on the Steam Deck, get the current user's Steam ID64, check if the current user owns the game, and more. Please check the glossary of functions at the beginning of this tutorial for more information on each function. You can also have the game turn itself off if the current user does not own the game by simply doing this:\r\n\r\n```gdscript\r\nif is_owned == false:\r\n\tprint(\"User does not own this game\")\r\n\tget_tree().quit()\r\n```\r\n\r\n!!! warning Notes\r\nShutting the game down with this **is_owned** behavior might cause problems from people using Family Share, Free Weekends, or other methods of trying the game out. There are other functions to check for those conditions which you might want to consider.\r\n!!!\r\n\r\n## Callbacks{.block}\r\n\r\nA very important piece of Steamworks is getting callbacks from Steam itself in response to different function. To receive callbacks you will need to have the **run_callbacks()** function running somewhere; preferably every frame or so. There are two methods available:\r\n\r\n### Method 1: Add It To \\_process()\r\n\r\nThe standard method has been adding the **Steam.run_callbacks()** function to the **_process()** function like so:\r\n\r\n```gdscript\r\nfunc _process(_delta: float) -> void:\r\n\tSteam.run_callbacks()\r\n```\r\n\r\nI highly suggest, much like the initialization process, you put this **_process()** function with the **Steam.run_callbacks()** in a global (singleton) script so it is always checking for callbacks. Though, if you want, you can put it in any **_process()** function in any given script that might be using callback information.\r\n\r\n### Method 2: Pass It To Initialization\r\n\r\nDepending on your version of GodotSteam, you can pass true as the second or third argument to either initialization function and have GodotSteam check for callbacks internally. Below are the examples, make sure to match the version you are using:\r\n\r\n::: tabs\r\n@tab:active GodotSteam 3.27 \/ 4.11 Or Earlier\r\n```gdscript\r\nvar initialize_response: Dictionary = steamInitEx( false, 480, true )\r\nprint(\"Did Steam initialize?: %s \" % initialize_response)\r\n```\r\n\r\n@tab GodotSteam 3.28 \/ 4.12 Or Later\r\n```gdscript\r\nvar initialize_response: Dictionary = steamInitEx( 480, true )\r\nprint(\"Did Steam initialize?: %s \" % initialize_response)\r\n```\r\n:::\r\n\r\n!!! warning Notes\r\nThe argument **does not** exist in the GDNative nor GDExtension version currently. This only works in GodotSteam 3.22 or newer for Godot 3.x and in GodotSteam 4.5 or newer for Godot 4.x.\r\n!!!\r\n\r\nSome users have noticed that if their **run_callbacks** sits in a script or node that can be paused, said callbacks will fail to trigger. Make sure this function resides in a script or node that is always processing!\r\n\r\n## Additional Resources{.block}\r\n\r\n### Video Tutorials\r\nPrefer video tutorials? Feast your eyes and ears!\r\n\r\n[youtube: Godot + Steam tutorial](https:\/\/www.youtube.com\/watch?v=J0GrG-AffCI&t=571s){ data-author=\"BluePhoenixGames\" }\r\n\r\n[youtube: Integrating Steamworks](https:\/\/www.youtube.com\/watch?v=VCwNxfYZ8Cw){ data-author=\"FinePointCGI\" }\r\n\r\n[youtube: GodotSteam - How It Works - Initialization](https:\/\/makertube.net\/w\/wH3ejcfFqFaFQuL4qdPC3X){ data-author=\"Gramps \/ GodotSteam\" }\r\n\r\n[youtube: Godot 4 Steam Integration](https:\/\/www.youtube.com\/watch?v=l0b5mh2HjyE){ data-author=\"Gwizz\" }\r\n\r\n### Example Project\r\n\r\n[To see this tutorial in action with more in-depth information, check out our upcoming free-to-play game Skillet on GitHub.](https:\/\/github.com\/GodotSteam\/Skillet\/blob\/master\/src\/autoload\/steamworks.gd) There you can get a full view of the code used which can serve as a starting point for you to branch out from."

Main code

extends Node

var app_id: int = 480
var app_installed_depots: Array = []
var app_languages: String = ""
var app_owner: int = 0
var build_id: int = 0
var game_language: String
var install_dir: Dictionary = {}
var is_on_steam_deck: bool = false
var is_on_vr: bool = false
var is_online: bool = false
var is_owned: bool = false
var launch_command_line: String = ""
var steam_id: int = 0
var steam_username: String = ""
var ui_language: String


func _init() -> void:
	# Set your game's Steam app ID here unless you are passing the app ID to the initialization function
	OS.set_environment("SteamAppId", str(app_id))
	OS.set_environment("SteamGameId", str(app_id))


func _ready() -> void:
	initialize_steam()


# This is necessary to receive Steamworks callbacks / signals. Not needed if you pass true as the last argument to the initialization function.
func _process(_delta: float) -> void:
	Steam.run_callbacks()


func initialize_steam() -> void:
	# Depending on the GodotSteam version or your preference, here are some options
	var initialize_response: Dictionary = Steam.steamInitEx()
	#  var initialize_response: Dictionary = Steam.steamInitEx( false, app_id, true )
	#  var initialize_response: Dictionary = Steam.steamInitEx( app_id, true )
	print("Did Steam initialize?: %s" % initialize_response)

	if initialize_response['status'] > Steam.STEAM_API_INIT_RESULT_OK:
		print("Failed to initialize Steam. Shutting down. %s" % initialize_response)
		get_tree().quit()

	# Gather additional data
	app_installed_depots = Steam.getInstalledDepots( app_id )
	app_languages = Steam.getAvailableGameLanguages()
	app_owner = Steam.getAppOwner()
	build_id = Steam.getAppBuildId()
	game_language = Steam.getCurrentGameLanguage()
	install_dir = Steam.getAppInstallDir( app_id )
	is_on_steam_deck = Steam.isSteamRunningOnSteamDeck()
	is_on_vr  = Steam.isSteamRunningInVR()
	is_online = Steam.loggedOn()
	is_owned = Steam.isSubscribed()
	launch_command_line = Steam.getLaunchCommandLine()
	steam_id = Steam.getSteamID()
	steam_username = Steam.getPersonaName()
	ui_language = Steam.getSteamUILanguage()
		
	# Check if account owns the game
	if is_owned == false:
		print("User does not own this game")
		get_tree().quit()

Comments