Skip to main content

ADR-016: Steam Integration Architecture

Status​

Accepted

Context​

To provide a seamless user experience and enable community content sharing, we need to integrate with Steam's platform services. This includes:

  • Cloud storage for user settings and preferences
  • Workshop for sharing overlay configurations
  • Cross-device synchronization
  • Community features (ratings, comments, collections)

Decision​

We will implement a local-first architecture with Steam Cloud as an optional enhancement, using steamworks-rs for Rust bindings.

Architecture Principles​

  1. Local-First Design

    • All settings stored locally in standard format
    • Steam Cloud acts as sync layer, not primary storage
    • Application fully functional without Steam connection
    • Graceful degradation when Steam unavailable

  2. Progressive Enhancement

    • Core features work without Steam
    • Steam adds sync and sharing capabilities
    • No hard dependency on Steam API availability
    • Clear user communication about Steam features

  3. Migration Path

    • Start with local JSON/TOML settings
    • Add Steam Cloud sync when API keys available
    • Automatic migration of existing local settings
    • Conflict resolution favors most recent changes

Implementation Details​

Settings Storage​

// Local settings structure
pub struct OverlaySettings {
    version: u32,
    overlays: Vec<OverlayConfig>,
    keybinds: HashMap<String, Action>,
    preferences: UserPreferences,
    last_modified: SystemTime,
}

// Steam Cloud sync
- File: overlay_settings.json (&lt;1MB)
- Sync on startup and shutdown
- Periodic sync during runtime (5 min intervals)
- Conflict resolution by timestamp

Workshop Integration​

pub struct WorkshopItem {
    title: String,
    description: String,
    tags: Vec&lt;String&gt;,
    content_type: ContentType, // OverlayLayout, Keybinds, Theme
    data: Vec<u8>, // Serialized content
    preview_image: Option<Vec<u8>>,
}

Feature Categories​

  1. Steam Cloud Features

    • User preferences and settings
    • Overlay positions and configurations
    • Keybind mappings
    • Theme selections
    • Recent file lists

  2. Steam Workshop Features

    • Share overlay layouts
    • Share keybind configurations
    • Share custom themes
    • Browse community content
    • Rate and comment on items
    • Create collections

  3. Steam Integration Points

    • Authentication via Steam ID
    • Rich Presence updates
    • Achievement tracking (future)
    • Steam Input API (future)

Technical Implementation​

Dependencies​

[dependencies]
steamworks = "0.10"  # Or latest version
serde = { version = "1.0", features = ["derive"] }

API Key Management​

  • Store API keys in environment variables
  • Never commit keys to repository
  • Graceful fallback without keys
  • Clear error messages for missing keys

Error Handling​

  • All Steam operations wrapped in Result<T>
  • Timeout handling for API calls
  • Retry logic with exponential backoff
  • User notification for sync failures

Consequences​

Positive​

  • Seamless experience across devices
  • Community content sharing
  • No lock-in to Steam platform
  • Progressive enhancement model
  • Robust offline support

Negative​

  • Additional API complexity
  • Need to handle Steam downtime
  • Version compatibility concerns
  • Privacy considerations for cloud data
  • Potential sync conflicts

Alternatives Considered​

  1. Steam-Only Storage

    • Simpler but creates platform lock-in
    • Poor offline experience
    • Not suitable for non-Steam users

  2. Custom Cloud Solution

    • More control but higher maintenance
    • Need to handle authentication, storage
    • Missing community features

  3. No Cloud Integration

    • Simpler but poor multi-device experience
    • No community content sharing
    • Manual backup required

Migration Strategy​

Phase 1: Local Settings (Current)​

  • JSON/TOML file storage
  • Manual import/export
  • No synchronization

Phase 2: Steam Cloud (Sprint 8)​

  • Add Steam Cloud sync
  • Automatic migration tool
  • Dual storage (local + cloud)

Phase 3: Workshop (Sprint 8)​

  • Enable content sharing
  • In-VR browser for discovery
  • Rating and comment system

Security Considerations​

  • No sensitive data in Steam Cloud
  • User consent for data upload
  • Clear privacy policy
  • Option to disable cloud features
  • Local encryption for sensitive settings

References​

  • Steamworks SDK Documentation
  • steamworks-rs Rust bindings
  • Sprint 8 Plan: Steam Integration
  • Local Settings System (already implemented)

Date​

2025-07-10

Authors​

  • Claude (AI Assistant)
  • VR Creator Platform Team