Games Publishing

GPC manages Play Games Services achievement and leaderboard configurations from the terminal or CI/CD pipeline. Define each config as JSON, version it alongside your app, diff your local files against what is live, and push updates in a pipeline instead of clicking through the Play Console.

Every command takes --json for scripting. GPC covers full create, list, update, and delete for both achievements and leaderboards, plus achievement icon upload and directory-level push and pull for bulk sync.

Prerequisites

1. Play Games Services enabled in the Google Play Console for your app
2. A service account with the androidpublisher scope (the same one GPC uses for publishing)
3. Your Games application ID (numeric) -- found in Play Console under Play Games Services > Setup & management > Configuration

Configuration

Set your application ID once in .gpcrc.json:

{
  "app": "com.example.mygame",
  "games": {
    "applicationId": "12345678901234"
  }
}

Or pass it per command with --game-id, or set the GPC_GAME_ID environment variable. The resolution order is: flag, env, config.

Creating Achievements

Define an achievement in a JSON file:

{
  "achievementType": "STANDARD",
  "initialState": "HIDDEN",
  "draft": {
    "name": {
      "translations": [
        { "locale": "en-US", "value": "First Victory" },
        { "locale": "fr-FR", "value": "Premiere victoire" }
      ]
    },
    "description": {
      "translations": [
        { "locale": "en-US", "value": "Win your first match" },
        { "locale": "fr-FR", "value": "Gagnez votre premier match" }
      ]
    },
    "pointValue": 10
  }
}

gpc games achievements create --file achievements/first-victory.json

For incremental achievements (progress-based):

{
  "achievementType": "INCREMENTAL",
  "initialState": "REVEALED",
  "stepsToUnlock": 100,
  "draft": {
    "name": {
      "translations": [{ "locale": "en-US", "value": "Centurion" }]
    },
    "description": {
      "translations": [{ "locale": "en-US", "value": "Play 100 matches" }]
    },
    "pointValue": 50
  }
}

Creating Leaderboards

{
  "scoreOrder": "LARGER_IS_BETTER",
  "draft": {
    "name": {
      "translations": [{ "locale": "en-US", "value": "All-Time High Scores" }]
    },
    "scoreFormat": {
      "numberFormatType": "NUMERIC"
    }
  }
}

gpc games leaderboards create --file leaderboards/high-scores.json

Score format types:

• NUMERIC -- plain number (points, count)
• TIME_DURATION -- milliseconds displayed as time
• CURRENCY -- monetary value (requires currencyCode)

Localization

Every achievement and leaderboard name and description is a localized string bundle, not a plain string. You add a language by including another entry in its translations array. There is no separate translations command: the locales you ship are the ones present in the config JSON you create, update, or push.

{
  "draft": {
    "name": {
      "translations": [
        { "locale": "en-US", "value": "First Victory" },
        { "locale": "fr-FR", "value": "Premiere victoire" },
        { "locale": "de-DE", "value": "Erster Sieg" },
        { "locale": "ja-JP", "value": "初勝利" }
      ]
    },
    "description": {
      "translations": [
        { "locale": "en-US", "value": "Win your first match" },
        { "locale": "fr-FR", "value": "Gagnez votre premier match" },
        { "locale": "de-DE", "value": "Gewinne dein erstes Spiel" },
        { "locale": "ja-JP", "value": "初めての試合に勝利する" }
      ]
    }
  }
}

Notes:

• locale uses BCP 47 codes (en-US, fr-FR, pt-BR). Use the same set Play Games Services supports in the Console.
• One locale should match your game's default language; players in an unlisted locale fall back to it.
• update and push replace the whole bundle, so include every locale you want to keep on each write. Run pull first to fetch the current translations, then edit and push back to avoid dropping a language.
• diff compares the full localized bundle, so a changed or added translation shows up before you push.

Syncing with Diff

Before updating, compare your local definition against the remote:

gpc games achievements diff CgkI1234567890 --file achievements/first-victory.json

If there are differences, apply them:

gpc games achievements update CgkI1234567890 --file achievements/first-victory.json

CI/CD Workflow

Store game configuration JSON files in your repo and sync them on merge:

# .github/workflows/games-sync.yml
name: Sync Games Config
on:
  push:
    branches: [main]
    paths: ["games/**"]

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: yasserstudio/gpc-action@v1
        with:
          service-account-json: ${{ secrets.GPC_SERVICE_ACCOUNT }}
      - run: gpc games achievements push games/achievements
        env:
          GPC_GAME_ID: ${{ vars.GAME_ID }}

Draft vs Published

The Configuration API uses a draft/published model:

• draft: editable, visible only to testers
• published: live, read-only via this API

When you create or update a configuration, changes go to the draft state. Publishing happens through the Play Console UI when you publish your Play Games Services configuration.

Icon Upload Depends on a Retired Endpoint

gpc games achievements set-icon and gpc games leaderboards set-icon call the Games Configuration API's imageConfigurations resource. As of discovery revision 20260820 that resource is no longer in Google's published API: only achievementConfigurations and leaderboardConfigurations remain. Google may still serve the upload route, so GPC still makes the call, but if it has been switched off you get a clear error instead of a raw 404:

Error [API_ENDPOINT_RETIRED]: Google removed the Play Games icon upload endpoint (imageConfigurations) from the Games Configuration API
Suggestion: Upload achievement and leaderboard icons in the Play Console (Grow > Play Games Services > Setup and management > Achievements / Leaderboards)

Nothing else is affected. create, update, delete, diff, push, and pull never touch that endpoint, so directory sync keeps working in full: icons are the only piece that has to move to the Play Console.

Deprecation Note

Google deprecated the Play Games v1 SDK (September 2025) with full shutdown in June 2027. The Configuration API uses a separate path (v1configuration) and the androidpublisher scope, and has no announced deprecation. GPC will track any changes.

See Also

• Command Reference -- full CLI syntax
• API Coverage