platform-achievements

Cross-platform game achievements. Describe your achievements once, then mirror them to Google Play Games, Game Center and Steam with a sync that is safe to call from anywhere, any number of times. Generate the files the three store consoles want from the same list. No runtime dependencies: the Capacitor game-services plugin and the steamworks.js client are passed in.

npm install platform-achievements

The model

Four ideas carry the whole package.

• Earned versus acknowledged. What the player has earned is the game's own truth. What a platform has acknowledged is what that platform confirmed receiving. A platform still needs exactly earned − acknowledged. Nothing is queued by hand, so a report that failed, was never sent or was sent while offline is simply still outstanding the next time you sync.
• Absolute progress. An incremental achievement ("win 10 matches") is described by the steps reached, 7, not by "add 3". Steam takes the absolute value. Play Games and Game Center only add, so the adapter sends the difference from the last acknowledged value.
• Idempotent sync. An acknowledgement is recorded only after the platform confirms it, and never goes backwards. Syncing twice sends nothing the second time; one failing report never blocks the others.
• Structural adapters. Each adapter asks for the few methods it needs, typed as an interface. This package imports no Capacitor, no Play Games plugin and no Steam module.

Quick start

import {
  MemoryAcknowledgementStore,
  resolveAchievements,
  syncAchievements,
} from 'platform-achievements'
import { gameServicesAchievements } from 'platform-achievements/game-services'

// 1. Describe the achievements once.
const achievements = resolveAchievements(
  [
    { key: 'first-win', name: 'First Win', description: 'Win your first match.', points: 5 },
    {
      key: 'ten-wins',
      name: 'Ten Wins',
      description: 'Win 10 matches, in any mode.',
      points: 10,
      steps: 10, // incremental: a progress bar of 10 steps
    },
  ],
  { gameCenterNamespace: 'com.example.game' },
)

// 2. Pick the adapter for this build. `plugin` is your Capacitor game-services plugin.
const adapter = gameServicesAchievements(plugin, 'game-center') // or 'play' on Android

// 3. Sync whenever it might help: on sign-in, on resume, after a match.
const result = await syncAchievements({
  achievements,
  earned: { 'first-win': 1, 'ten-wins': 7 }, // from your save data
  adapter,
  store: new MemoryAcknowledgementStore(), // use a durable store of your own in a real game
})
// { sent: 2, failed: 0, errors: [], unaddressed: 0, signedIn: true }

earned maps a key to what the player has: 1 for a standard achievement, the steps reached for an incremental one. Everything else, including which reports to send and what to remember, follows from it.

Entry points

| Import | What it gives you | | --- | --- | | platform-achievements | resolveAchievements, outstanding, syncAchievements, AcknowledgementStore and MemoryAcknowledgementStore, validateAchievements and CONSOLE_LIMITS | | platform-achievements/game-services | gameServicesAchievements(plugin, 'play' \| 'game-center') for the Capacitor game-services plugin | | platform-achievements/steam | steamAchievements(client) for a steamworks.js client | | platform-achievements/web | webAchievements, a no-op for builds with no platform profile | | platform-achievements/export | Play Console, App Store Connect and Steamworks submission files, and a flat ZIP for the Play import |

Both ESM and CommonJS are shipped, with types for each.

What each platform supports

| | Google Play Games | Game Center | Steam | | --- | --- | --- | --- | | Unlock | idempotent | idempotent | idempotent | | Progress | adds whole steps | adds percentage points | sets a stat, absolute | | Needs a durable acknowledgement store for progress | yes | yes | no, but it still stores | | Hidden achievements | yes | yes | yes | | Ids | generated by the console after import (playIds) | yours, permanent (gameCenterNamespace) | yours (ACH_<KEY>, STAT_<KEY>) | | Bulk import | CSV and icons in a flat ZIP | JSON records and icons | none; enter by hand from the JSON | | Icons | 512 px PNG | 1024 px PNG | 256 px JPEG, earned and locked |

Details, limits and the order to do things in are in docs/platforms.md.

Store console files

import { playConsoleZip, submission } from 'platform-achievements/export'

const { files, icons } = submission(achievements)
// files: 'play/AchievementsMetadata.csv', 'app-store-connect/app-store-connect.json', ...
// icons: [{ path: 'play/first-win.png', key: 'first-win', size: 512, format: 'png', locked: false }, ...]
// Draw each icon at its size, then:
const zip = playConsoleZip({ ...files, ...drawnIcons }) // drawnIcons: path -> bytes

The package decides what files exist, what they are called and how big each icon is. You draw the icons however your game draws things.

Compatibility

• Node.js 22, 24 and 26 (the maintained lines; engines.node is >=22). The package is plain TypeScript with no platform APIs, so it also runs in browsers and in a Capacitor webview.
• @idleflowgames/capacitor-play-games 0.3 on Capacitor 8 matches the game-services interface, and steamworks.js 0.4 matches the Steam one. Both are typed structurally, so any compatible object works.

Documentation

• Documentation site
• API reference, platforms and architecture
• Contributing, security policy and changelog

License

MIT. Copyright (c) 2026 Jon Bogaty.