GameRuntimeService
The game-facing side of configs and secrets: a running game (its game token) or its own servers (a server key).
On this page
- Summary
- Methods
- GetConfig
- GetSecret
- Grant
- SpendCurrency
- GetCurrencyBalance
- ListGrantRules
- ListPendingReceipts
- GetFriends
- IsFriendsWith
- GetGroupRank
- SendGameInvite
- GetParty
- Types
- CurrencyBalance
- CurrencyBalanceRequest
- GetRuntimeConfigRequest
- GetRuntimeSecretRequest
- ListRuntimeGrantRulesRequest
- PendingReceipt
- PendingReceiptsRequest
- PendingReceiptsResponse
- RuntimeConfig
- RuntimeFriend
- RuntimeFriends
- RuntimeFriendship
- RuntimeFriendshipRequest
- RuntimeGrantRequest
- RuntimeGrantResponse
- RuntimeGroupRank
- RuntimeGroupRankRequest
- RuntimeInviteRequest
- RuntimeInviteResponse
- RuntimeParty
- RuntimePlayerRequest
- RuntimeSecret
- SpendCurrencyRequest
- See also
The game-facing side: a running game (its session's game token) or the game's own servers (a server key, Authorization: Bearer neosk_...). Every method is a POST with a JSON body; see the overview for the protocol, authentication and errors.
Summary#
| Method | Auth | Description |
|---|---|---|
| GetConfig | Game token or server key | Every config value of the caller's game. Game tokens and server keys. |
| GetSecret | Server key | A secret's value. Server keys only: a player's game token never reads secrets (peer-to-peer hosts are players' devices). |
| Grant | Game token or server key | The only way a running game gives a player something of value. Game tokens of the session's authority (its host, else the member who joined first) for players in that session, and server keys for players in any open session of the game. The request names a rule the game's team declared; the platform checks the rule, its event, amount, caps and precondition, then grants, refuses or quarantines it. Retries with the same request_id get the first answer. |
| SpendCurrency | Game token or server key | Takes in-game currency from a player (never below zero). Currency only goes up through Grant: the data stores that hold it (currency.<name>) refuse a game's own writes. |
| GetCurrencyBalance | Game token or server key | A player's balance of an in-game currency. |
| ListGrantRules | Game token or server key | The rules the game may grant by (enabled ones). |
| ListPendingReceipts | Game token or server key | A player's purchase receipts for the game's products that no grant has spent yet (what a purchase_receipt rule takes), oldest first. |
| GetFriends | None | Social (SOC-5). A player's own game token for themselves; the session's authority (or a server key) for players in the session (any open session of the game). The player's friends: who they are, and whether each is in this session or this game now (friends who hide their online status are never shown as playing). |
| IsFriendsWith | None | |
| GetGroupRank | None | The player's rank in a group (0 and empty: not a member), for gating admin tools, team colours or VIP areas. |
| SendGameInvite | None | Invites a friend of the player to the player's session, as the player (the same rules and limits as inviting from the app: friends only, no blocks, the host's join setting, at most 10 invites in 10 minutes). The game should only call it when the player asked to invite. |
| GetParty | None | The player's party (empty when they're not in one), so a game can keep parties together. |
Methods#
GetConfig#
Every config value of the caller's game. Game tokens and server keys.
POST /neo.platform.v1.GameRuntimeService/GetConfig
Content-Type: application/jsonAuth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).
Request: GetRuntimeConfigRequest. Response: RuntimeConfig.
GetSecret#
A secret's value. Server keys only: a player's game token never reads secrets (peer-to-peer hosts are players' devices).
POST /neo.platform.v1.GameRuntimeService/GetSecret
Content-Type: application/jsonAuth: One of the game's server keys (Authorization: Bearer neosk_...). Never a player's game token.
Request: GetRuntimeSecretRequest. Response: RuntimeSecret.
Grant#
The only way a running game gives a player something of value. Game tokens of the session's authority (its host, else the member who joined first) for players in that session, and server keys for players in any open session of the game. The request names a rule the game's team declared; the platform checks the rule, its event, amount, caps and precondition, then grants, refuses or quarantines it. Retries with the same request_id get the first answer.
POST /neo.platform.v1.GameRuntimeService/Grant
Content-Type: application/jsonAuth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).
Request: RuntimeGrantRequest. Response: RuntimeGrantResponse.
SpendCurrency#
Takes in-game currency from a player (never below zero). Currency only goes up through Grant: the data stores that hold it (currency.<name>) refuse a game's own writes.
POST /neo.platform.v1.GameRuntimeService/SpendCurrency
Content-Type: application/jsonAuth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).
Request: SpendCurrencyRequest. Response: CurrencyBalance.
GetCurrencyBalance#
A player's balance of an in-game currency.
POST /neo.platform.v1.GameRuntimeService/GetCurrencyBalance
Content-Type: application/jsonAuth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).
Request: CurrencyBalanceRequest. Response: CurrencyBalance.
ListGrantRules#
The rules the game may grant by (enabled ones).
POST /neo.platform.v1.GameRuntimeService/ListGrantRules
Content-Type: application/jsonAuth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).
Request: ListRuntimeGrantRulesRequest. Response: ListGrantRulesResponse.
ListPendingReceipts#
A player's purchase receipts for the game's products that no grant has spent yet (what a purchase_receipt rule takes), oldest first.
POST /neo.platform.v1.GameRuntimeService/ListPendingReceipts
Content-Type: application/jsonAuth: A running game's game token, or one of the game's server keys (Authorization: Bearer neosk_...).
Request: PendingReceiptsRequest. Response: PendingReceiptsResponse.
GetFriends#
Social (SOC-5). A player's own game token for themselves; the session's authority (or a server key) for players in the session (any open session of the game). The player's friends: who they are, and whether each is in this session or this game now (friends who hide their online status are never shown as playing).
POST /neo.platform.v1.GameRuntimeService/GetFriends
Content-Type: application/jsonAuth: None.
Request: RuntimePlayerRequest. Response: RuntimeFriends.
IsFriendsWith#
POST /neo.platform.v1.GameRuntimeService/IsFriendsWith
Content-Type: application/jsonAuth: None.
Request: RuntimeFriendshipRequest. Response: RuntimeFriendship.
GetGroupRank#
The player's rank in a group (0 and empty: not a member), for gating admin tools, team colours or VIP areas.
POST /neo.platform.v1.GameRuntimeService/GetGroupRank
Content-Type: application/jsonAuth: None.
Request: RuntimeGroupRankRequest. Response: RuntimeGroupRank.
SendGameInvite#
Invites a friend of the player to the player's session, as the player (the same rules and limits as inviting from the app: friends only, no blocks, the host's join setting, at most 10 invites in 10 minutes). The game should only call it when the player asked to invite.
POST /neo.platform.v1.GameRuntimeService/SendGameInvite
Content-Type: application/jsonAuth: None.
Request: RuntimeInviteRequest. Response: RuntimeInviteResponse.
GetParty#
The player's party (empty when they're not in one), so a game can keep parties together.
POST /neo.platform.v1.GameRuntimeService/GetParty
Content-Type: application/jsonAuth: None.
Request: RuntimePlayerRequest. Response: RuntimeParty.
Types#
CurrencyBalance#
| Field | Type | Description |
|---|---|---|
currency | string | |
playerId | string | |
balance | string (int64) |
CurrencyBalanceRequest#
| Field | Type | Description |
|---|---|---|
currency | string | |
playerId | string |
GetRuntimeConfigRequest#
No fields: send {}.
GetRuntimeSecretRequest#
| Field | Type | Description |
|---|---|---|
name | string |
ListRuntimeGrantRulesRequest#
No fields: send {}.
PendingReceipt#
| Field | Type | Description |
|---|---|---|
receiptId | string | the purchase's transaction (txn_...): what a purchase_receipt grant names |
itemId | string | |
itemName | string | |
boughtAt | string |
PendingReceiptsRequest#
| Field | Type | Description |
|---|---|---|
playerId | string |
PendingReceiptsResponse#
| Field | Type | Description |
|---|---|---|
receipts | array of PendingReceipt |
RuntimeConfig#
| Field | Type | Description |
|---|---|---|
values | object (map of string to string) | key -> JSON text |
revision | string (int64) | the highest config version (changes when any value changes) |
RuntimeFriend#
| Field | Type | Description |
|---|---|---|
user | UserSummary | |
inThisSession | boolean | in the caller's session (a server key: in any session of the game) |
inThisGame | boolean | playing this game now (any session) |
RuntimeFriends#
| Field | Type | Description |
|---|---|---|
friends | array of RuntimeFriend |
RuntimeFriendship#
| Field | Type | Description |
|---|---|---|
friends | boolean |
RuntimeFriendshipRequest#
| Field | Type | Description |
|---|---|---|
playerId | string | |
userId | string |
RuntimeGrantRequest#
| Field | Type | Description |
|---|---|---|
rule | string | the rule's name |
playerId | string | who gets it (usr_...) |
amount | string (int64) | currency: how much (items and badges: 1, or 0 for 1) |
event | string | the event that earned it (the rule's event, if it names one) |
receiptId | string | a purchase_receipt rule: the purchase's transaction (txn_...) |
requestId | string | the game's idempotency key (1-100 characters) |
RuntimeGrantResponse#
| Field | Type | Description |
|---|---|---|
outcome | string | granted, refused or quarantined |
reason | string | |
grantId | string | the grant request (grq_...) |
balance | string (int64) | currency: the player's balance after it |
RuntimeGroupRank#
| Field | Type | Description |
|---|---|---|
member | boolean | |
rank | number | |
role | string |
RuntimeGroupRankRequest#
| Field | Type | Description |
|---|---|---|
playerId | string | |
groupId | string |
RuntimeInviteRequest#
| Field | Type | Description |
|---|---|---|
playerId | string | who invites (in a session of this game) |
userId | string | the friend invited |
RuntimeInviteResponse#
| Field | Type | Description |
|---|---|---|
sessionId | string | the session the friend was invited to (ses_...) |
RuntimeParty#
| Field | Type | Description |
|---|---|---|
partyId | string | pty_... (empty: not in a party) |
leader | UserSummary | |
members | array of UserSummary |
RuntimePlayerRequest#
| Field | Type | Description |
|---|---|---|
playerId | string |
RuntimeSecret#
| Field | Type | Description |
|---|---|---|
name | string | |
value | string |
SpendCurrencyRequest#
| Field | Type | Description |
|---|---|---|
currency | string | |
playerId | string | |
amount | string (int64) | |
requestId | string |