# Steamworks Setup Guide for Tekton Armageddon

> **Current status: Steam builds are not active.** All platforms (Windows, Linux, macOS, Android) use Nakama as their sole backend. GodotSteam GDExtension exists in `addons/godotsteam/` but is **not enabled** in the project. This doc explains the current Nakama-only architecture and how to re-enable Steam if needed in the future.

---

## Current Architecture (Nakama-Only)

```
┌──────────────────────────────────────────────────┐
│                  Game Client                      │
│  ┌──────────────────────────────────────────┐    │
│  │          BackendService (autoload)        │    │
│  │  ┌─────────────┐  ┌──────────────────┐   │    │
│  │  │ NakamaManager│  │steamworks_manager│   │    │
│  │  │ (active)     │  │ (dormant)        │   │    │
│  │  └─────────────┘  └──────────────────┘   │    │
│  └──────────────────────────────────────────┘    │
└──────────────────────┬───────────────────────────┘
                       │
              ┌────────▼────────┐
              │  Nakama Server   │
              │ (RPC backend)    │
              │ achievements     │
              │ leaderboards     │
              │ shop/economy     │
              │ auth             │
              │ multiplayer      │
              └─────────────────┘
```

- **All backends use Nakama** — achievements, leaderboards, shop, authentication, multiplayer.
- **Platform detection** (`BackendService._detect_platform()`) distinguishes:
  - `MOBILE_NAKAMA` — Android/iOS (`OS.has_feature("android")` or `OS.has_feature("ios")`)
  - `DESKTOP_NAKAMA` — Windows/Linux/macOS (default when GodotSteam not loaded)
  - `DESKTOP_STEAM` — only activated if `ClassDB.class_exists("Steam")` at runtime
- **GodotSteam GDExtension** is present in `addons/godotsteam/` but **not enabled** in Project Settings > Plugins. It is shipped in the CI export (Windows only, `|| true` on copy failure) but does not execute.
- **No Steam App ID configured.** The `steam_app_id` in `steamworks_manager.gd` defaults to `480` (generic test ID) via `ProjectSettings.get_setting("steam/initialization/app_id", 480)`.
- **No Steam Partner account, no Steamworks app, no Steam build pipelines** are active.

---

## Export Presets

The project has 4 export presets in `export_presets.cfg`:

| Preset | Name | Platform | Export Path |
|--------|------|----------|-------------|
| preset.0 | Windows Desktop | Windows | `build/windows/tekton_armageddon_v2.4.3.exe` |
| preset.1 | Android | Android | `build/tekton-dash-armageddon-v.2.4.3.apk` |
| preset.2 | macOS | macOS | `build/tekton_armageddon_v2.4.3.zip` |
| preset.3 | Linux/X11 | Linux | `build/linux/tekton_armageddon_v2.4.3.x86_64` |

No separate Steam vs. Non-Steam presets. All presets produce the same Nakama-only build.

### CI Export Flow (`.gitea/workflows/ci.yml`)

On tag push (`v*`), the CI pipeline:

1. **Checkout** code at tag
2. **Setup Godot 4.7** (cached)
3. **Export Windows** → `build/windows/tekton_armageddon_windows.exe` (copies `libgodotsteam*` DLLs if present, failure ignored with `|| true`)
4. **Export Linux** → `build/linux/tekton_armageddon_linux.x86_64`
5. **Export macOS** → `build/macos/tekton_armageddon_macos.zip`
6. **Extract changelog** from `CHANGELOG_DRAFT.md`
7. **Create Gitea release** and upload all 3 platform zips
8. **Publish** release (draft → published)

The CI does **not** upload to Steam. All builds are distributed via Gitea releases (https://git.klud.top/danchie/tekton/releases).

---

## Platform Detection

The `BackendService` autoload (`scripts/services/backend_service.gd`) detects platform at startup:

```gdscript
func _detect_platform() -> void:
    if OS.has_feature("android") or OS.has_feature("ios"):
        current_platform = Platform.MOBILE_NAKAMA
    else:
        if ClassDB.class_exists("Steam"):
            current_platform = Platform.DESKTOP_STEAM
        else:
            current_platform = Platform.DESKTOP_NAKAMA
```

Since GodotSteam is not enabled, desktop builds always hit `DESKTOP_NAKAMA`. The `steamworks_manager.gd` is only loaded when `DESKTOP_STEAM` is selected.

Check current platform at runtime:
```gdscript
print("Platform: %s" % BackendService.get_platform_name())
print("Initialized: %s" % BackendService.is_initialized())
```

### Platform Types

| Value | Trigger | Backend |
|-------|---------|---------|
| `DESKTOP_NAKAMA` | Desktop build, GodotSteam not loaded | Nakama only |
| `DESKTOP_STEAM` | Desktop build, GodotSteam loaded + Steam running | Nakama + Steam auth |
| `MOBILE_NAKAMA` | Android/iOS feature detected | Nakama only |

---

## Local Testing

### Nakama Backend (All Platforms)

1. Ensure Nakama server is running locally (see `server/docker-compose.yaml`)
2. Launch the game from Godot Editor (press F5)
3. Log in with email/password or device ID
4. Test achievements, leaderboards, shop via game UI
5. Check console for `"BackendService: Initialized Nakama backend"`

### Force-Specific Platform for Testing

Temporarily override platform in `BackendService._detect_platform()`:
```gdscript
func _detect_platform() -> void:
    current_platform = Platform.DESKTOP_NAKAMA  # Force desktop Nakama mode
    # ... or ...
    current_platform = Platform.MOBILE_NAKAMA   # Force mobile mode
```

### Export and Run Standalone

```bash
# Windows
godot --headless --export-release "Windows Desktop" build/windows/standalone.exe
./build/windows/standalone.exe

# Linux
godot --headless --export-release "Linux/X11" build/linux/standalone.x86_64
./build/linux/standalone.x86_64

# macOS
godot --headless --export-release "macOS" build/macos/standalone.zip
```

---

## Activating Steam Support (Future)

If Steam distribution is needed later, these are the steps:

1. **Get a Steam Partner account** at https://partner.steamgames.com/
2. **Create Steam app** and get an App ID
3. **Enable GodotSteam plugin** in Project > Project Settings > Plugins
4. **Set App ID** in Project Settings > steam > initialization > app_id (or in `steamworks_manager.gd`)
5. **Configure Nakama** to accept Steam auth tickets (set Steam API key in Nakama config)
6. **Add a Steam-specific export preset** or modify existing presets to include Steam SDK redistributables
7. **Update CI pipeline** to upload builds to Steamworks SDK pipelines
8. **Test Steam auth flow**: launch through Steam, verify `"SteamworksManager: Steam initialized"`, verify Steam login → Nakama registration

### What the Dormant Steam Code Does

The existing `steamworks_manager.gd` provides:

- `get_auth_session_ticket()` — retrieves Steam auth session ticket for Nakama login
- `get_steam_user_name()` — returns Steam persona name
- `get_steam_user_id()` — returns Steam ID

All game features (achievements, leaderboards, shop) are already implemented purely via Nakama RPCs in `BackendService.api_rpc_async()`. Steam would only be used for **authentication** — the rest stays on Nakama.

---

## File Structure

```
scripts/
├── backend_service.gd          # Unified interface (autoload) — Nakama-only default
├── steamworks_manager.gd       # Steamworks implementation (dormant, loads only if GodotSteam present)
└── nakama_manager.gd           # NakamaManager autoload (active)

addons/godotsteam/              # GodotSteam GDExtension (installed but not enabled)
addons/com.heroiclabs.nakama/   # Nakama GDSDK (active)

export_presets.cfg              # Export presets — all Nakama-only, no Steam presets
.gitea/workflows/ci.yml         # CI pipeline — exports Win/Linux/macOS to Gitea releases
docs/STEAMWORKS_SETUP.md        # This documentation
```

---

## Key Differences from Previous State

| Aspect | Before | Now |
|--------|--------|-----|
| Steam builds | Active, separate Steam/Non-Steam presets | Dormant, not shipped |
| Backend | Nakama + Steam | Nakama only |
| Export presets | 6+ (Steam + Non-Steam variants) | 4 (all Nakama-only) |
| Desktop platform detection | Steam if `OS.has_feature("steam")` | Nakama unless GodotSteam loaded |
| CI | Uploaded to Steamworks | Gitea releases only |
| Steam App ID | Configured | Default 480 (test), not set |

---

## Additional Resources

- **Nakama Documentation**: https://heroiclabs.com/docs/nakama/
- **GodotSteam Documentation**: https://godotsteam.com/ (for future reference)
- **GodotSteam GitHub**: https://codeberg.org/godotsteam/godotsteam
- **Steamworks Documentation**: https://partner.steamgames.com/doc/home
- **CI Workflow**: `.gitea/workflows/ci.yml`