Profile Lifecycle Flow

This flowchart illustrates the complete lifecycle of a game profile, from creation through launch, execution, and cleanup.

Overview

Game profiles are user-configured instances of a game with specific content (mods, maps, addons), settings, and workspace strategies. Each profile is isolated and can be launched independently.

Flow Diagram

Key Components

Profile Creation

Profile Model

• File: GenHub.Core/Models/GameProfile.cs
• Fields:
  • id: Unique identifier
  • name: User-defined name
  • gameId: Target game identifier
  • contentIds: List of manifest IDs
  • workspaceStrategy: Symlink, Hardlink, or Copy
  • settings: Game-specific settings
  • created: Creation timestamp
  • lastPlayed: Last launch timestamp

Content Selection

• Source: ManifestPool (installed content)
• Filtering: By target game compatibility
• Validation: Dependency resolution, conflict checking

Settings Configuration

• ViewModel: GameProfileSettingsViewModel.cs
• Categories:
  • Display (resolution, windowed mode)
  • Graphics (quality, effects)
  • Audio (volume, music)
  • Gameplay (difficulty, speed)

Profile Launch

Workspace Preparation

• Service: ProfileLauncherFacade.cs
• Process:
  1. Create workspace directory (e.g., workspaces/profile-{id})
  2. Resolve content files from CAS
  3. Apply workspace strategy
  4. Write Options.ini

Workspace Strategies

Symlink Strategy

• Command: mklink /D (Windows) or ln -s (Unix)
• Pros: No disk space duplication, instant setup
• Cons: Requires Developer Mode or admin rights
• Cleanup: Remove symlinks only (CAS files remain)

Hardlink Strategy

• Command: mklink /H (Windows) or ln (Unix)
• Pros: No disk space duplication, no special permissions
• Cons: Same filesystem required
• Cleanup: Remove hardlinks (CAS files remain)

Copy Strategy

• Command: File copy
• Pros: Works everywhere, no special requirements
• Cons: Duplicates disk space, slower setup
• Cleanup: Delete all copied files

Options.ini Generation

• Service: GameSettingsMapper.cs
• Process:
  1. Load profile settings
  2. Map to game-specific INI format
  3. Write to workspace/Options.ini
  4. Validate INI syntax

Game Launch

• Process:
  1. Find game executable path
  2. Set working directory to workspace
  3. Start process with arguments
  4. Monitor process lifecycle

Process Monitoring

Monitoring Loop

• Interval: 1 second
• Checks:
  • Process still running
  • Process exit code
  • Crash detection

Crash Detection

• Indicators:
  • Non-zero exit code
  • Unexpected termination
  • Exception logs
• Action: Log crash details, show dialog

Cleanup

Workspace Cleanup

• Trigger: Game process exits
• Process:
  1. Remove workspace files (based on strategy)
  2. Delete workspace directory
  3. Preserve logs and save files (if configured)

Reference Counting

• Purpose: Track CAS file usage
• Action: Decrement reference count for profile content
• Cleanup: Remove unused CAS files (if count = 0)

Profile Management

Profile Storage

• File: profiles.json (user data directory)
• Schema:

{
  "profiles": [
    {
      "id": "uuid",
      "name": "My Mod Profile",
      "gameId": "generals-zh",
      "contentIds": ["1.0.publisher.mod.content1", "..."],
      "workspaceStrategy": "Symlink",
      "settings": { ... },
      "created": "2026-03-15T10:00:00Z",
      "lastPlayed": "2026-03-15T12:30:00Z"
    }
  ]
}

Profile Operations

• Create: Add new profile to profiles.json
• Edit: Modify content or settings
• Duplicate: Clone existing profile
• Delete: Remove profile and cleanup workspace
• Export: Share profile configuration
• Import: Load profile from file

Error Handling

Content Validation Errors

• Missing content from ManifestPool
• Incompatible content versions
• Unresolved dependencies

Workspace Errors

• Symlink creation failure (permissions)
• Hardlink creation failure (filesystem)
• Copy failure (disk space, permissions)

Launch Errors

• Game executable not found
• Process start failure
• Crash on startup

Cleanup Errors

• File deletion failure (in use)
• Permission errors
• Orphaned workspace directories

Performance Optimizations

Lazy Loading

• Load profile settings only when needed
• Defer content validation until launch
• Cache workspace paths

Parallel Operations

• Copy files in parallel (copy strategy)
• Create symlinks in parallel
• Background dependency resolution

Caching

• Cache resolved dependencies
• Cache game settings mappings
• Cache workspace paths

Related Files

• GenHub.Core/Models/GameProfile.cs
• GenHub/Features/GameProfiles/ViewModels/GameProfileSettingsViewModel.cs
• GenHub/Features/GameProfiles/Services/ProfileLauncherFacade.cs
• GenHub/Features/GameProfiles/Services/GameSettingsMapper.cs
• GenHub.Core/Services/Storage/WorkspaceStrategy.cs
• GenHub.Core/Services/Manifest/ManifestPool.cs