Foundation for Steamworks

A lightweight, modular integration layer for Steamworks.NET that exposes Steam features through flexable components and a type-safe generated code wrapper.

---

🛠 Also Available For

---

Become a GitHub Sponsor

Support Heathen by becoming a GitHub Sponsor. Sponsorship directly funds the development and maintenance of free tools like this, as well as our game development Knowledge Base and community on Discord.

Sponsors also get access to our private SourceRepo, which includes developer tools for O3DE, Unreal, Unity, and Godot.
Learn more or explore other ways to support @ heathen.group/kb

---

What it does

Foundation maps Steamworks interfaces to Unity-friendly patterns, primarily focused on User Data, Stats, Achievements, and Leaderboards. It operates via two main systems:

System	Purpose
Generated Wrapper	A static SteamTools.Game class that provides type-safe access to your specific App IDs and API names.
Modular Components	MonoBehaviours that allow you to build Steam-driven UI in the Inspector without writing glue code.

The following core features are covered:

• Core — Application IDs, multi-app support (Main, Demo, Playtest), and automated initialization.
• User — Persona names, Steam levels, online status, and avatars.
• Stats — Integer and Float stat management with local caching and server sync.
• Achievements — Localized names, descriptions, icons, and unlock/lock state.
• Leaderboards — Score uploading, rank retrieval, and entry display.

---

Requirements

• Unity engine 6.0 or compatible
• A registered Steamworks developer account
• Steamworks.NET

---

Installation

Via Unity Package Manager (UPM)

1. In Unity, go to Window > Package Manager.
2. Click + > Add package from git URL.
3. Enter: https://github.com/heathen-engineering/Unity-Foundation-for-Steamworks.git?path=/com.heathen.steamworksfoundation

Steamworks.NET is installed automatically. On the first domain reload after Foundation is imported, the editor will detect if Steamworks.NET is missing and prompt you to install the recommended version. If you need a specific version, menu items are available under Help > Heathen > Steamworks Foundation > Install Steamworks.NET ….

---

Setup & Workflow

1. Configuration

Open Project Settings > Steamworks. Define your App IDs and list your API names (Achievements, Stats, Leaderboards) exactly as they appear in the Steamworks Partner Portal.

2. Code Generation

Click Generate Code in the settings panel. This creates Assets/Scripts/Generated/SteamTools.Game.cs. This wrapper provides static access to your data:

// Type-safe access to your Steam data
uint id = SteamTools.Game.AppId;
SteamTools.Game.Achievements.ACH_WIN_ONE_GAME.Unlock();
int wins = SteamTools.Game.Stats.NumWins.GetInt();

3. Initialisation

No code required: Add the InitializeSteamworks component to a GameObject in your startup scene. It calls SteamTools.Game.Initialise() automatically and respects the OnReady event without any scripting.

From code: Call the init method once at startup and subscribe to OnReady to know when leaderboard handles and user data are fully populated.

void Awake() {
    SteamTools.Game.Initialise();
    SteamTools.Interface.OnReady += () => Debug.Log("Steam is Ready");
}

---

Component Reference

Foundation uses a Parent-Child modular design. The parent component holds the data reference, and child components on the same GameObject automatically react to it.

User & Achievements

Parent	Child Component	Purpose
SteamUserData	SteamUserName	Displays persona name in a TMP label.
	SteamUserStatus	Displays online/offline status.
SteamAchievementData	SteamAchievementIcon	Displays achievement icon in a UI Image.
	SteamAchievementChanged	Fires a UnityEvent on unlock.

Stats & Leaderboards

Parent	Child Component	Purpose
SteamLeaderboardData	SteamLeaderboardRank	Displays the local user's rank.
	SteamLeaderboardDisplay	Populates a list/grid of leaderboard entries.

---

Usage Overview

C# Example — Committing Stat Changes:

using Heathen.SteamworksIntegration;

// Update local cache
SteamTools.Game.Stats.NumWins.SetInt(newWins);

// Sync with Steam Servers
API.StatsAndAchievements.Client.StoreStats();

C# Example — Uploading Leaderboard Scores:

var board = SteamTools.Game.Leaderboards.TopScores;
board.UploadScore(score, ELeaderboardUploadScoreMethod.k_ELeaderboardUploadScoreMethodKeepBest, 
    (result, error) => { /* handle result */ });

---

Public Namespaces & Headers

Namespace	Contents
Heathen.SteamworksIntegration	Core data types (UserData, AchievementData) and components.
Heathen.SteamworksIntegration.API	Low-level static wrappers for Steam interfaces.
SteamTools	The generated wrapper (Game, Interface, Events).