# Platform SDK Integration Guide

The `platform` module in `@aphrodite/game-runtime` wraps store and platform SDK
behavior behind a unified runtime contract. It is intentionally dependency-free:
shipping builds can bind the interfaces to Steamworks, EOS, GOG Galaxy,
PlayStation SDK, or Xbox GDK implementations without requiring those SDKs in
unit tests.

## Adapter Model

`PlatformSdkAdapter` covers:

- achievements and trophies
- rich presence
- friends, invites, and joinable sessions
- overlay focus handling
- cloud save sync and conflict resolution
- entitlement and DLC checks
- input prompt icon resolution

`PlatformSdkManager` registers adapters, initializes them, selects the active
platform, and exposes capability metadata to runtime systems.

## Public Store Adapters

The in-memory adapters model the feature contracts for public PC stores:

- Steam: achievements, friends, rich presence, overlay, cloud saves,
  matchmaking, workshop, store, entitlements, and input prompts.
- Epic Online Services: achievements, friends, presence, overlay, matchmaking,
  voice, anti-cheat, store, entitlements, and input prompts.
- GOG Galaxy: achievements, friends, presence, cloud saves, leaderboards,
  matchmaking, entitlements, and input prompts.

Bind real SDK calls by implementing `PlatformSdkAdapter` and preserving the same
operation result semantics.

## Console Stubs

PlayStation and Xbox adapters are NDA-safe stubs. They define the integration
surface without including proprietary SDK calls:

- PlayStation: trophies, activities, DualSense haptics, PSN friends, cloud
  saves, store, entitlements, and prompts.
- Xbox: achievements, Xbox Live friends, cloud saves, entitlements, prompts,
  Quick Resume, Smart Delivery, and Game Pass.

Replace the stubs inside platform-specific builds with SDK-backed adapters.

## Achievements And Trophies

`AchievementSystem` accepts platform-agnostic definitions and maps them to
platform ids:

```ts
await achievements.unlock({
  id: 'beat-boss',
  name: 'Boss Clear',
  description: 'Defeat the first boss',
  platformIds: {
    steam: 'STEAM_BEAT_BOSS',
    playstation: 'TROPHY_BEAT_BOSS',
  },
  trophyGrade: 'silver',
});
```

If a platform-specific id is missing, the canonical achievement id is used.

## Presence, Friends, And Overlay

`RichPresenceSystem` formats current activity, level, zone, party size, and join
secret into a store-visible presence payload. `PlatformFriendsService` lists
friends playing the same game, sends invites, and joins a friend's session.

`PlatformOverlayService` reports whether the active platform overlay should
pause gameplay and whether focus restoration tests should run.

## Cloud Saves

`PlatformCloudSaveService` supports these conflict strategies:

- latest timestamp
- local wins
- remote wins
- manual review

The adapter returns whether a sync uploaded, downloaded, matched, or requires
manual review.

## Entitlements

`PlatformEntitlementService` verifies base-game ownership, required DLC ids, and
subscription status before content loads. Use it before mounting DLC content or
starting platform-restricted modes.

## Input Prompt Icons

`InputPromptIconResolver` maps action ids to platform/device labels:

- PlayStation: Cross, Circle, Square, R2
- Xbox: A, B, X, RT
- Steam Deck: SteamDeck A/B/X/R2 labels
- PC: Enter, Esc, Space, E, Mouse1

UI code should render icon assets by `iconId` and keep text fallback labels for
accessibility.

## Compliance Checklist Automation

`PlatformComplianceChecklist` evaluates evidence against platform requirements.
`defaultComplianceRequirements` includes representative Steam, EOS, GOG, TRC,
and XR checks:

- Steam overlay focus handling
- EOS voice consent and mute handling
- GOG cloud save conflict resolution
- PlayStation TRC save data, activities, trophies, and suspend/resume
- Xbox XR Quick Resume, user switching, entitlements, and Smart Delivery

Keep platform certification evidence in CI artifacts so release managers can
trace each checklist status to an automated test or manual signoff.
