danchie/tekton
3
1
Fork 0
Code Issues 20 Pull Requests Actions Packages Projects 10 Releases 1 Wiki Activity
Files
16526301539acc3318dea442652a71939d767f9b
tekton/docs/STEAMWORKS_SETUP.md
T
adtpdn 8a2f865ad8 feat: update 2.1.9
2026-04-29 01:36:49 +08:00

14 KiB
Raw Blame History

Steamworks Setup Guide for Tekton Armageddon

This guide explains how to set up Steamworks for Windows, Mac, and Linux builds while using Nakama for mobile platforms (Android/iOS) for leaderboards, achievements, and shop functionality.

Overview

  • Desktop (Windows/Mac/Linux): Single build that detects Steam at runtime
    • If launched through Steam: Steam login available for Nakama registration; all features use Nakama
    • If launched standalone: Uses Nakama for all features
  • Mobile (Android/iOS): Uses Nakama for all backend services
  • Unified Backend: All platforms use Nakama for achievements, leaderboards, and shop
  • Steam Integration: Steam is only used for authentication (auth session ticket for Nakama login)

Prerequisites

Steamworks Setup

  1. Steam Partner Account

  2. Steam App ID

    • Create a new app in Steamworks
    • Note your App ID (e.g., 480)
    • Update steam_app_id in scripts/services/steamworks_manager.gd

  3. Steamworks SDK

    • Download the Steamworks SDK from Steamworks
    • The GodotSteam plugin includes the SDK, but you may need it for reference

Installation Steps

1. Install GodotSteam GDExtension

Option A: Via Godot Asset Library (Recommended)

  1. Open Godot Editor
  2. Go to Project > Asset Library
  3. Search for "GodotSteam GDExtension 4.4+"
  4. Download and install the plugin
  5. Restart Godot Editor

Option B: Manual Installation

  1. Download from: https://codeberg.org/godotsteam/godotsteam/releases
  2. Download version 4.18.1 (compatible with Godot 4.6.2)
  3. Extract to addons/godotsteam/ in your project
  4. Enable the plugin in Project > Project Settings > Plugins

2. Configure Steamworks in Project

  1. Enable the Plugin

    • Go to Project > Project Settings > Plugins
    • Enable "GodotSteam"

  2. Set Steam App ID

    • Edit scripts/services/steamworks_manager.gd
    • Change steam_app_id to your Steam App ID:
    var steam_app_id: int = YOUR_APP_ID_HERE

  3. Add BackendService as Autoload

    • Go to Project > Project Settings > Autoload
    • Add BackendService with path: res://scripts/services/backend_service.gd
    • Enable it as a singleton

3. Configure Steamworks Features

Achievements

  1. Define Achievements in Steamworks

    • Go to Steamworks > Your App > Achievements
    • Create achievements with API names (e.g., "first_win", "level_10")
    • Set display names, descriptions, and icons

  2. Use in Code

    # Unlock an achievement
BackendService.unlock_achievement("first_win")

# Set progress (for progress-based achievements)
BackendService.set_achievement_progress("kill_100_enemies", current_kills, 100)

# Check achievement status
var progress = BackendService.get_achievement_progress("first_win")

Leaderboards

  1. Define Leaderboards in Steamworks

    • Go to Steamworks > Your App > Leaderboards
    • Create leaderboards with API names (e.g., "high_score", "fastest_time")
    • Set sort order (ascending/descending) and display type

  2. Use in Code

    # Submit a score
BackendService.submit_leaderboard_score("high_score", 1000)

# Get leaderboard entries
BackendService.leaderboard_entries_loaded.connect(_on_leaderboard_loaded)
BackendService.get_leaderboard_entries("high_score", 1, 10)

func _on_leaderboard_loaded(leaderboard_id: String, entries: Array):
    for entry in entries:
        print("Player: %s, Score: %d" % [entry.player_name, entry.score])

Shop (Steam Inventory)

Note: Steam shop functionality requires additional setup with Steam Inventory Service or Steam Microtransactions. This is a complex feature that requires:

  1. Steam Inventory Service Setup

    • Define items in Steamworks > Your App > Inventory
    • Set item types, prices, and properties
    • Implement purchase callbacks in steamworks_manager.gd

  2. Alternative: Use external payment processor for desktop and sync with Nakama

4. Export Presets

The project includes export presets for all platforms:

Desktop Builds (single build for Steam and standalone)

  • Windows Desktop (preset.0) → build/tekton_armageddon_v2.1.7.exe
  • macOS (preset.2) → build/tekton_armageddon_v2.1.7.zip
  • Linux/X11 (preset.3) → build/tekton_armageddon_v2.1.7.x86_64

Mobile Builds

  • Android (preset.1) → build/tekton-dash-armageddon-v.2.1.5.apk

Note: Desktop builds are universal - the same executable works on both Steam and standalone. The game detects whether it's running through Steam at runtime and switches backends accordingly.

Configure macOS Export

  1. Code Signing (for distribution)

    • Get an Apple Developer certificate
    • Update codesign/identity in export preset
    • Set codesign/enable to true

  2. Architecture

    • Currently set to "universal" (Intel + Apple Silicon)
    • Can be changed to "x86_64" or "arm64" if needed

Configure Linux Export

  1. Architecture
    • Currently set to "x86_64"
    • Add ARM64 preset if needed for Linux ARM devices

5. Platform Detection

The BackendService automatically detects the platform and backend:

# Detection logic in BackendService
if OS.has_feature("android") or OS.has_feature("ios"):
    # Mobile → Nakama
elif OS.has_feature("steam"):
    # Desktop → Steamworks
else:
    # Desktop → Local storage (non-Steam builds)

You can check the current platform:

print("Platform: %s" % BackendService.get_platform_name())
print("Initialized: %s" % BackendService.is_initialized())

Platform Types

  • DESKTOP_STEAM: Running through Steam client (Steam login available, all features use Nakama)
  • DESKTOP_NAKAMA: Desktop build not running through Steam (uses Nakama)
  • MOBILE_NAKAMA: Android/iOS (uses Nakama)

Runtime Detection

The game automatically detects the launch method:

  • If OS.has_feature("steam") is true → Steam login available, all features use Nakama
  • Otherwise → All features use Nakama

This means the same desktop build can be:

  • Uploaded to Steam (Steam login enabled, all data stored in Nakama)
  • Distributed standalone (all data stored in Nakama)

Steam Login for Nakama

When running through Steam, players can use their Steam account to register or log in to Nakama. This is the only Steam integration - all game features (achievements, leaderboards, shop) use Nakama.

How it works:

  1. Player clicks "Sign in with Steam" button on login screen
  2. Game retrieves Steam auth session ticket via Steamworks
  3. Auth ticket is sent to Nakama for authentication
  4. Nakama validates the ticket with Steam backend
  5. If valid, player is logged in/registered to Nakama
  6. Player's Steam account is linked to their Nakama account

Benefits:

  • No password needed for Steam users
  • Automatic account creation on first login
  • Seamless cross-platform progression (all data in Nakama)
  • Steam username is used as display name
  • Unified backend across all platforms

Requirements:

  • Nakama server must be configured with Steam API key
  • Steamworks must be initialized (game launched through Steam)
  • GodotSteam plugin must support getAuthSessionTicket()

Configuration: Set your Steam API key in Nakama server configuration:

nakama:
  social:
    steam:
      api_key: "your_steam_api_key"

Nakama Integration for Mobile

Current Setup

Your project already has Nakama integrated via addons/com.heroiclabs.nakama/ and NakamaManager autoload.

Connecting to BackendService

The BackendService will automatically use Nakama on mobile. You need to implement Nakama-specific methods in NakamaManager:

# In NakamaManager.gd, add these signals:
signal achievement_unlocked(achievement_id: String)
signal leaderboard_score_submitted(leaderboard_id: String, score: int, success: bool)

# Implement achievement methods
func unlock_achievement(achievement_id: String):
    # Use Nakama's achievement system
    var achievement = await client.write_storage_object_async(
        session,
        NakamaWriteStorageObject.new(
            "achievements",
            achievement_id,
            {"unlocked": true, "timestamp": Time.get_unix_time_from_system()}
        )
    )
    achievement_unlocked.emit(achievement_id)

# Implement leaderboard methods
func submit_leaderboard_score(leaderboard_id: String, score: int):
    # Use Nakama's leaderboard system
    var result = await client.write_leaderboard_record_async(
        session,
        leaderboard_id,
        score
    )
    leaderboard_score_submitted.emit(leaderboard_id, score, result != null)

Testing

Testing Steam Builds

  1. Export Steam Build

    • Use the "Windows Desktop (Steam)" preset (preset.0)
    • Export to build/steam/tekton_armageddon_v2.1.7.exe

  2. Upload to Steam

    • Upload the exported build to Steamworks
    • Set as the default build for your app

  3. Run through Steam

    • Launch the game via Steam (not directly)
    • Steam must be running
    • Check console for "SteamworksManager: Steam initialized successfully"

  4. Test Achievements

    • Call BackendService.unlock_achievement("test_achievement")
    • Check Steam overlay (Shift+Tab) to see achievement unlock

  5. Test Leaderboards

    • Submit scores via BackendService.submit_leaderboard_score()
    • View in Steamworks backend or Steam overlay

Testing Non-Steam Builds

  1. Export Non-Steam Build

    • Use the "Windows Desktop (Non-Steam)" preset (preset.1)
    • Export to build/standalone/tekton_armageddon_v2.1.7.exe

  2. Run Directly

    • Run the executable directly (not through Steam)
    • Check console for "BackendService: Initialized Nakama backend"

  3. Test Leaderboards

    • Ensure Nakama server is accessible
    • Open the leaderboard panel to fetch rankings
    • Submit scores via UserProfileManager.submit_to_leaderboard()
    • Leaderboards are global (same as mobile)

  4. Test Shop

    • Ensure Nakama server is accessible
    • Open the shop panel to fetch catalog
    • Purchase items via UserProfileManager.purchase_item()
    • Shop functionality works the same as mobile

Testing Nakama (Mobile)

  1. Run on Mobile Device

    • Export to Android/iOS using the Android preset (preset.2)
    • The game will automatically use Nakama backend
    • Check logs for "BackendService: Initialized Nakama backend"

  2. Test in Editor

    • To test Nakama in editor, temporarily modify _detect_platform():
    func _detect_platform() -> void:
    current_platform = Platform.MOBILE_NAKAMA  # Force Nakama

Troubleshooting

Steamworks Not Initializing

Problem: "SteamworksManager: Failed to initialize Steam"

Solutions:

  1. Ensure game is launched through Steam (not directly)
  2. Check Steam is running
  3. Verify steam_app_id is correct
  4. Check GodotSteam plugin is enabled in Project Settings
  5. Restart Godot Editor after installing plugin

Achievements Not Unlocking

Problem: Achievements don't appear in Steam overlay

Solutions:

  1. Ensure achievement API names match Steamworks configuration
  2. Check steam.storeStats() is called after setting achievements
  3. Verify achievement is published in Steamworks (not in draft)
  4. Test with Steam overlay open (Shift+Tab)

Leaderboards Not Working

Problem: Leaderboard scores not submitting

Solutions:

  1. Ensure leaderboard exists in Steamworks
  2. Check leaderboard API name matches
  3. Verify leaderboard is published
  4. Check console for error messages

Platform Detection Issues

Problem: Wrong backend being used

Solutions:

  1. Check OS features: print(OS.get_supported_features())
  2. Manually override platform in _detect_platform() for testing
  3. Ensure BackendService is added as autoload

File Structure

scripts/services/
├── backend_service.gd          # Unified interface (autoload)
└── steamworks_manager.gd       # Steamworks implementation

export_presets.cfg              # Export presets for all platforms
docs/STEAMWORKS_SETUP.md        # This documentation

Additional Resources

Next Steps

  1. Complete Steam Partner account setup
  2. Create Steam app and get App ID
  3. Install GodotSteam plugin
  4. Configure achievements and leaderboards in Steamworks
  5. Implement Nakama methods in NakamaManager for mobile
  6. Test on all target platforms
  7. Set up code signing for macOS distribution
  8. Configure Steam Inventory Service if using in-game shop

Notes

  • Steam builds only work when launched through Steam client
  • Non-Steam builds use Nakama for leaderboards and shop (same as mobile)
  • Shop functionality is available on both Steam (via Steam Inventory) and non-Steam (via Nakama)
  • Non-Steam builds sync to Nakama server, not Steam
  • Nakama is already integrated for multiplayer, leaderboards, and shop
  • Export presets are organized in separate folders: build/steam/ and build/standalone/

Build Workflow

For Steam Distribution

  1. Export using Steam presets (preset.0, preset.3, preset.5)
  2. Upload builds to Steamworks
  3. Configure achievements and leaderboards in Steamworks backend
  4. Set build as default in Steamworks
  5. Shop uses Steam Inventory Service (requires additional setup)

For Standalone Distribution (itch.io, GOG, etc.)

  1. Export using Non-Steam presets (preset.1, preset.4, preset.6)
  2. Distribute the standalone executables
  3. Ensure Nakama server is accessible to players
  4. Players get global leaderboards and shop via Nakama
  5. No Steam integration required

For Mobile Stores

  1. Export using Android preset (preset.2)
  2. Upload to Google Play / App Store
  3. Ensure Nakama server is configured and accessible
  4. Leaderboards and shop work the same as non-Steam desktop
Reference in New Issue View Git Blame Copy Permalink