---
name: pollyglot/gplay-games
source: https://app.decimal.ai/s/pollyglot-gplay-games@1/SKILL.md
source_sha256: 5b65fca13c50
---

# gplay games (Play Games Services configuration)

`gplay games` configures a game's **Play Games Services** resources —
**achievement** and **leaderboard** configurations, each with the full CRUD set
(`list` / `view` / `create` / `update` / `delete`). It is an Admin API surface:
the developer *configures* the game. It is **not** the Play Games Services
runtime the game itself calls (sign-in, score submission) — that is out of
scope. Shared conventions (auth, output, exit codes, `--dry-run`/`--confirm`)
are in `gplay-cli-usage`. The whole namespace is `[experimental]`.

## Addressing: `--application-id`, not `--package`

This is the trap. Play Games resources are keyed by the **numeric Play Games
application ID** (a distinct ID space), *not* the Android package name.
**`--application-id <numeric-id>` is required on `list` and `create`**; the
per-resource commands `view` / `update` / `delete` are addressed by the
achievement/leaderboard id alone (no `--application-id`). The
`.gplay/config.json` package pin does **not** apply anywhere here.

```bash
gplay games achievements list --application-id 1234567890
gplay games leaderboards list --application-id 1234567890
```

## Draft-only — there is no publish

The single most important gotcha: every write here edits the **draft**
configuration. The `published` copy players see is **read-only**, and the API
exposes **no publish method** — pushing a draft live to players is **Play
Console-only**. So `gplay games … create/update` stages the change; a human
finishes it in the Console. Don't expect a CLI command to make it live.

## Achievements

```bash
gplay games achievements view <achievementId> --output json     # read one
gplay games achievements create --application-id 123 \
  --name "First Blood" --description "Win your first match" \
  --type STANDARD --initial-state REVEALED --point-value 10
```

- Field flags: `--name` / `--description` (localized, under `--locale`, default
  `en-US`), `--type STANDARD|INCREMENTAL`, `--initial-state HIDDEN|REVEALED`,
  `--point-value`, and `--steps-to-unlock` (**INCREMENTAL only**).
- Or `--from-json <file|->` for a full `AchievementConfiguration` body — the
  round-trip of `view --output json`, and the way to set **multiple locales at
  once**. `--from-json` and the field flags are **mutually exclusive**.

## Leaderboards

```bash
gplay games leaderboards create --application-id 123 \
  --name "High Scores" --score-order LARGER_IS_BETTER \
  --score-min 0 --score-max 1000000
```

- Field flags: `--name` (localized, `--locale`), `--score-order
  LARGER_IS_BETTER|SMALLER_IS_BETTER`, `--score-min` / `--score-max`.
- Or `--from-json <file|->` for a full `LeaderboardConfiguration` — the way to
  set `scoreFormat` or multiple locales. Mutually exclusive with the field flags.

## `update` replaces — fetch, edit, resend

`update <id>` is a **full PUT replace**: the body *replaces* the draft. For a
partial edit, read the current config, edit it, and resend it whole:

```bash
gplay games achievements view <id> --output json > ach.json
# edit ach.json …
gplay games achievements update <id> --from-json ach.json
```

The field flags on `update` send only what they name, so `--name` alone is fine
for a one-field change; reach for the fetch-edit-resend round-trip when you need
to preserve a rich body (multiple locales, nested fields).

## Safety

- `create` / `update` are **routine draft writes** — no `--confirm`. Rehearse
  with `--dry-run` (no HTTP; `--output json` prints the request body).
- `delete <id>` is **irreversible** → requires **`--confirm`** (missing → exit
  `3`); `CI=true` never auto-confirms.
- `GPLAY_READONLY` refuses every live write (exit `4`); `--dry-run` is exempt.
- `--output json` mirrors the API response verbatim (ADR-0003); `list` paging is
  `--max-results` + `--page-token` (read `nextPageToken` from the response).

Confirm the current verbs and flags with `gplay games --help` and
`gplay games <group> <command> --help` — the surface is `[experimental]`
(ADR-0033) and may still evolve.