Player Store

Player Store gives each player typed key-value storage for currencies, inventory tags, and progression fields. You define keys once with read/write permissions, then use the same JSON shape from Unity client and REST API.

Store Definitions

Manage definitions with dev endpoints scoped by gameKeyId.

GET /v1/dev/player-store-defs?gameKeyId={uuid}
POST /v1/dev/player-store-defs?gameKeyId={uuid}
DELETE /v1/dev/player-store-defs/{storeKey}?gameKeyId={uuid}

POST Request DTO

{
  "storeKey": "gold",
  "valueType": "STRING | NUMBER | STRING_LIST",
  "numberMin": 0,
  "numberMax": 1000000,
  "clientWritable": true,
  "clientReadable": true
}

GET Item / POST Response DTO

{
  "storeKey": "gold",
  "valueType": "NUMBER",
  "numberMin": 0,
  "numberMax": 1000000,
  "clientWritable": true,
  "clientReadable": true
}

numberMin and numberMax are optional. They apply to NUMBER keys and enforce bounds for writes and mutations.

Read & Write Values

Client and website use one payload shape for both request and response:

{
  "value": "text | number | [\"a\", \"b\"]"
}

Client Endpoints

GET /v1/client/player-store/{storeKey}
PUT /v1/client/player-store/{storeKey}

Dev Endpoints

GET /v1/dev/player-store/{playerId}/{storeKey}?gameKeyId={uuid}
PUT /v1/dev/player-store/{playerId}/{storeKey}?gameKeyId={uuid}

Client Transactions

Apply catalog transactions with strict server-side catalog mode. Auth unchanged: existing client auth plus X-Player-Id.

POST /v1/client/player-store/tx

Request Body

{
  "transactionId": "buy_pack_1"
}

Response Body

{
  "transactionId": "buy_pack_1",
  "applied": true,
  "alreadyApplied": false
}

Behavior

Field rename: use transactionId. txId is obsolete.
Client sends only transaction ID; no client-defined conditions or mutations.
Duplicate retry of the same transaction returns 200 with already-applied state.

Status Handling

200 applied=true, alreadyApplied=false: first successful apply.
200 applied=false, alreadyApplied=true: idempotent duplicate retry; treat as success.
409 TX_CONDITION_FAILED: requirements/funds not satisfied.
409 TX_MISMATCH: request has unsupported extra fields (for example conditions/mutations).
400 TX_NOT_ALLOWED: unknown or disabled catalog transaction.
400 INVALID_TRANSACTION_ID: invalid transaction ID format.

var result = await PlayerStore.Transaction("buy_pack_1", session).Execute();

Unity Usage

await PlayerStore.Value(PlayerStoreDefs.Gold).Set(10m);
var gold = await PlayerStore.Value(PlayerStoreDefs.Gold).Get();

Next reference: Unity Client API and REST API.

Rules & Errors

Definition Rules

Definitions are create-only.
Duplicate key returns 409 STORE_KEY_ALREADY_DEFINED.
Delete missing key returns 404 STORE_KEY_NOT_DEFINED.
Store key must match lowercase regex; invalid key returns 400 INVALID_STORE_KEY.
NUMBER bounds enforced on writes and mutations; out-of-range returns 400 PLAYER_STORE_NUMBER_OUT_OF_RANGE.

Delete Behavior

Deleting a definition cascades player values through FK constraints, so old values for that storeKey are removed automatically.