Eve library

Platform SDK Integration Guide

Guide

Revision 1

On this page

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.