# GamesVS integration instructions for an AI coding assistant

Use these instructions with the GamesVS OpenAPI 3.1 schema:
https://gamesvs.com/api-guide/openapi

Human guide: https://gamesvs.com/api-guide/
Game registration and token management: https://gamesvs.com/developers/
API base URL: https://api.gamesvs.com/v1

## Project inputs

- Game slug: ASK THE USER IF NOT PROVIDED.
- Desired features: leaderboard, player stats, achievement display, completed-run submissions.
- Server secret: GAMESVS_SERVER_TOKEN. Tell the user where to configure it in their
  hosting provider's server-only secrets; do not request the actual secret in chat.

Inspect the existing project before editing. Identify its language, hosting,
backend or server functions, game-completion events, and player authentication.
Use the project's existing patterns. Explain prerequisites in plain language.

## Implementation requirements

1. Read the supplied schema and follow its actual paths, request validation,
   response envelopes, security schemes, and errors. Do not invent endpoints.
2. Games on another website must call GamesVS through their backend. Browser
   cross-origin access is not currently configured. If no backend exists, explain
   that requirement and implement public reads only when a backend is available.
3. Keep server tokens off the browser, mobile/desktop game binaries, public
   environment variables, source control, URLs, and logs. Expose your own authenticated
   backend operations, never an unrestricted proxy that forwards arbitrary scores.
4. A server token authorizes one game; it does not authenticate a player. Official
   submissions require an existing GamesVS public player ID securely linked to your
   authenticated player. External account linking/OAuth is not implemented by GamesVS.
   If that mapping is absent, explain the blocker and leave official submissions
   disabled. Do not use emails, internal user IDs, invented IDs, or arbitrary client
   input as proof of a GamesVS identity. Public reads can be implemented first.
5. For server submissions, validate gameplay results on the backend and send
   Authorization: Bearer <server secret>, Content-Type: application/json, player_id,
   submission_id, score, and optional stats. All counters describe this run's increments,
   not lifetime totals. "verified" means server-authenticated, not independent anti-cheat.
6. Generate and persist a valid submission_id when the run finishes, before sending.
   Persist the player's identity and exact payload with it. Retry network failures,
   429, and transient 5xx using that same ID and payload, with bounded backoff and
   Retry-After support. Do not retry permanent validation/authentication errors.
   A 409 is a conflicting result, not permission to invent a new ID. Do not display
   achievement unlocks twice on a replayed response.
7. Direct browser submissions are supported only for games on the GamesVS origin.
   Use the same-origin base URL https://gamesvs.com/api/v1,
   the player's GamesVS login session, and GET /players/me to get player.id and
   csrf_token. Send X-SecurityID on POSTs; omit player_id and Authorization. These
   results stay unverified and do not affect official leaderboards or achievements.
8. Public leaderboard, game, verified-stat and achievement reads need no server
   token. Honor pagination. Stat totals are decimal strings; preserve accuracy when
   displaying them. Treat unlocked_at: null as a locked achievement. Achievement
   creation and configuration are not available through the API.
9. Add clear loading, empty, and error states. Do not poll on every game frame.
   Handle non-JSON failures as well as JSON API errors. Do not log secrets or
   grant CMS access to game users.
10. Test the relevant integration: successful reads, authenticated submissions,
    ownership checks in your backend, duplicate retries, token failure, rate limits,
    and recovery from a lost response. Never test with fabricated production player IDs.

## Finish with a short handoff

Explain what was added, which features are ready, where the user configures their
slug and server secret, and how to test with a real player. Name any remaining
hosting or account-linking requirement. Do not claim official submissions work
until a secure player mapping exists.