Initialize and shut down the Steamworks API

Initialize the Steamworks API in a client application or a game server so your application can use Steamworks features, and shut it down when your application closes.

You must initialize the Steamworks API before you call any other Steamworks method. The initialization process differs depending on whether you're building a client application or a game server.

Prerequisites

For the client application, ensure the Steam client is installed and running, and that you're signed in to it. To check this through code, call SteamAPI.IsSteamRunning before you initialize the Steamworks API.

Important

Call SteamAPI.Init and GameServer.InitEx on the main thread. Don't call them from Task.Run, a new Thread, or code that runs after ConfigureAwait(false). In these cases, the initialization method runs on a thread other than the main thread. That thread has no Unity synchronization context, so the package runs your callback handlers on the background thread, where Unity APIs might not work.

Initialize and shut down a client application

To initialize and shut down the Steamworks API in a client application:

  1. Create a script that runs when your application starts.
  2. In the Start method, call SteamAPI.Init. Call this method on the main thread, so that the package delivers callbacks on the main thread, where your handlers can call Unity APIs.
  3. In the OnDestroy method, call SteamAPI.Shutdown to close the connection and free up the resources.

After SteamAPI.Init returns true, you can call the Steamworks methods from your application. If initialization fails, SteamAPI.Init returns false but doesn't provide details of failure. To identify the cause of failure, call SteamAPI.InitEx instead of SteamAPI.Init. It returns an ESteamAPIInitResult and an error message.

When you call SteamAPI.Shutdown, any call results that your application is still awaiting are canceled. Shutdown doesn't remove your callback subscriptions, so your handlers resume when you call SteamAPI.Init again.

The following code example demonstrates these steps:

void Start()
{
    if (!SteamAPI.Init())
    {
        Debug.LogError("Steam is not running, or the App Id is wrong.");
        return;
    }

    Debug.Log($"Signed in as {SteamFriends.GetPersonaName()} ({SteamUser.GetSteamID()})");
}

void OnDestroy()
{
    SteamAPI.Shutdown();
}

Initialize and shut down a game server

To initialize and shut down the Steamworks API in a game server:

  1. Create a script that runs when your server application starts.
  2. Call GameServer.InitEx with your server's address, ports, authentication mode, and version string.
  3. Call GameServer.Shutdown to close the server connection and free up the resources.

A game server always uses GameServer.InitEx, which returns an ESteamAPIInitResult and an error message. After the game server initialization succeeds, use the SteamGameServer classes, such as SteamGameServerNetworking and SteamGameServerUtils.

When you call the initialization methods SteamAPI.Init or GameServer.InitEx, the package automatically performs the following:

  • Ensures that the package's struct layout matches the target operating system before it communicates with the Steamworks SDK libraries.
  • Connects the package to the Steamworks API interfaces, such as SteamUserStats and SteamFriends, so your C# code can call them.
  • In the default Package dispatch mode, starts a background thread that reads callbacks from the Steamworks API and delivers them on the main thread.
Note

If you call an interface method such as those on SteamUser or SteamFriends before initialization completes, the package throws an InvalidOperationException. This prevents your application from crashing due to uninitialized memory. The only exceptions are SteamAPI.IsSteamRunning, which checks whether the Steam client is running and SteamAPI.RestartAppIfNecessary, which you call before initialization to relaunch your application through the Steam client if you didn't start through it.

Relaunch your application through the Steam client

If your application starts outside the Steam client, you can relaunch it through the Steam client. Before you call SteamAPI.Init, call SteamAPI.RestartAppIfNecessary with your application ID. If it returns true, quit the application.

The following example passes the application ID you set in the Steamworks settings to SteamAPI.RestartAppIfNecessary by using the SteamworksRuntimeSettings.AppId constant:

if (SteamAPI.RestartAppIfNecessary(new AppId_t(SteamworksRuntimeSettings.AppId)))
{
    //Quit your application here
}

Alternatively, define ENABLE_RESTART_STEAM_APP_HOOK in your scripting define symbols. The package then calls SteamAPI.RestartAppIfNecessary when your application starts, using the application ID in the Steamworks settings.

Note

SteamAPI.RestartAppIfNecessary returns false when a steam_appid.txt is already present next to the application executable, so your application doesn't relaunch. By default, the package generates this file for the development build, so the ENABLE_RESTART_STEAM_APP_HOOK define has no effect in a development build.

Additional resources