423 lines
14 KiB
Markdown
423 lines
14 KiB
Markdown
# 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**
|
|
- You need a Steam Partner account to access Steamworks
|
|
- Apply at: https://partner.steamgames.com/
|
|
|
|
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:
|
|
```gdscript
|
|
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**
|
|
```gdscript
|
|
# 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**
|
|
```gdscript
|
|
# 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:
|
|
|
|
```gdscript
|
|
# 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:
|
|
```gdscript
|
|
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:
|
|
```yaml
|
|
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`:
|
|
|
|
```gdscript
|
|
# 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()`:
|
|
```gdscript
|
|
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
|
|
|
|
- **GodotSteam Documentation**: https://godotsteam.com/
|
|
- **GodotSteam GitHub**: https://codeberg.org/godotsteam/godotsteam
|
|
- **Steamworks Documentation**: https://partner.steamgames.com/doc/home
|
|
- **Nakama Documentation**: https://heroiclabs.com/docs/nakama/
|
|
|
|
## 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
|