NEO Platform calls
Grant currency, badges and purchases, read friends, groups and parties, invite friends, declare ad breaks and close a session to matchmaking from scripts, limited to what neo.toml exposes.
On this page
Scripts can call the NEO Platform directly: give players currency, items and badges, deliver developer products they bought, read their friends, group rank and party, invite a friend, declare a break an ad may fill, and close the session to matchmaking. Each call is asynchronous, like saving data: it returns a promise that resolves on a later simulation tick, so scripts stay deterministic.
A script can only make the calls your game exposes. You list them in neo.toml, and nothing else reaches the platform.
import { economy, badges, products, social, ads, session } from "neo";from neo import economy, badges, products, social, ads, sessionExposing calls in neo.toml#
[script.platform] calls lists every platform call your game's own scripts may make:
[script.platform]
calls = ["grant.coins_for_wins", "grant.first_win", "grant.gem_pack", "spend.coins", "balance.*", "receipts", "friends", "party"]| Call name | Allows |
|---|---|
grant.<rule> | economy.grant, badges.award and products.deliver with the grant rule <rule>. |
spend.<currency> | economy.spend of the currency <currency>. |
balance.<currency> | economy.balance of the currency <currency>. |
receipts | products.pending. |
rules | economy.rules. |
friends | social.friends. |
is_friend | social.isFriend. |
group_rank.<group> | social.groupRank for the group <group>. |
invite | social.invite. |
party | social.party. |
ad_break | ads.breakPoint. |
joinable | session.setJoinable. |
grant, spend, balance and group_rank take a name. <op>.* covers every name, as balance.* does above. The other calls take no name.
A call your game doesn't expose throws in the script, before any request leaves the game: spend.gems isn't exposed to this script (neo.toml [script.platform] calls, or a role's NeoPlatform.spend.gems:call). A typo in calls is a manifest error. See The [script] manifest.
Calls for players' live scripts#
Players' live scripts start with no platform calls. A role grants them some with NeoPlatform.<call>:call:
[script.roles.player]
grant = ["NeoPlatform.friends:call", "NeoPlatform.party:call"]
[script.roles.vip]
grant = ["NeoPlatform.balance.coins:call"]A role can never grant more than calls lists. NeoPlatform.spend.gems:call with no spend.gems (or spend.*) in calls is an error: `NeoPlatform.spend.gems:call` grants more than [script.platform] calls declares.
The generated neo.d.ts and neo.pyi document these calls, and the generated reference page (script.types with format: md) lists the ones each script may make.
Where calls may come from#
| Calls | @server code | @client code | Shared code |
|---|---|---|---|
economy, badges, products | Yes | No | No |
session.setJoinable | Yes | No | No |
social | Yes, about any player in the session | Yes, about the local player | No |
ads.breakPoint | No | Yes, the local player's own break | No |
@server code runs on the session's host, which is the platform's authority for the session. Shared code runs on every player's game, so it never calls the platform. A call from the wrong place throws, for example balance.coins: NEO Platform calls are made from @server code (it runs on the session's host). A client that wants a grant asks the host with a remote call, and the host decides. See Contexts and remotes.
How replies arrive#
- Replies arrive at the start of a later tick, in the order the requests were made.
- At most 32 requests are sent per tick, and at most 128 can wait for replies at once. Await them before making more.
- When the platform refuses a request, the promise rejects with its code and message, for example
permission_denied: ...orfailed_precondition: .... In Python theawaitraises. - Players are session player ids, as scripts see players, or platform user ids (
usr_…). An empty player is the local player.
Economy: grant rules and currencies#
Nothing of value is given on a game's word. Your team declares grant rules for the game: what a rule gives (one of your passes or products, a badge, or an amount of an in-game currency), the event the game must name, the most per request, and caps per player per day. Scripts ask for a grant by naming a rule, and the platform checks it against the rule. See ListGrantRules in the API reference.
import { World, server, economy, badges } from "neo";
export default class Rewards extends World {
@server
async win(player) {
const g = await economy.grant("coins_for_wins", player, { amount: 5, event: "win" });
if (g.outcome === "granted") console.log("balance", g.balance);
await badges.award("first_win", player);
}
@server
async buyHat(player) {
// rejects when the player has too little
const b = await economy.spend("coins", player, 3);
console.log("left", b.balance);
}
}from neo import World, server, economy, badges
class Rewards(World):
@server
async def win(self, player):
g = await economy.grant("coins_for_wins", player, {"amount": 5, "event": "win"})
if g.outcome == "granted":
print("balance", g.balance)
await badges.award("first_win", player)
@server
async def buy_hat(self, player):
# raises when the player has too little
b = await economy.spend("coins", player, 3)
print("left", b.balance)
default = Rewards| Call (JS / Python) | Needs | Resolves to |
|---|---|---|
economy.grant(rule, player, options) | grant.<rule> | { outcome, reason, grantId, balance } |
economy.spend(currency, player, amount, options) | spend.<currency> | { currency, player, balance } |
economy.balance(currency, player) | balance.<currency> | { currency, player, balance } |
economy.rules() | rules | the game's enabled grant rules: [{ name, kind, currency, event, maxAmount, description }] |
badges.award(rule, player, options) | grant.<rule> | a grant result |
The options are an object in JavaScript and a dict in Python:
| Option | Meaning |
|---|---|
amount | How much to grant. A currency rule needs it; items and badges default to 1. spend takes its amount as an argument, 1 or more. |
event | The event the rule names, such as "win". |
requestId (Python also request_id) | The platform's idempotency key, 1 to 100 characters. A retry with the same key gets the first answer and grants nothing more. By default each request gets its own key. |
Grant results#
Only granted gave the player something. quarantined means your team reviews it before anything is given. refused comes with a reason:
| Reason | Why |
|---|---|
not_authority | The calling game isn't the session's authority. |
player_not_in_session | The player isn't in this session. |
unknown_rule | The game has no rule by that name. |
rule_disabled | The rule is turned off. |
wrong_event | The event doesn't match the rule's. |
bad_amount | The amount is under 1 or over the rule's limit. |
already_awarded | The player already has the badge. |
already_owned | The player already owns the item. |
missing_receipt, bad_receipt, receipt_used | A purchase rule needs a receipt for this player's purchase that hasn't been delivered yet. |
missing_item | The rule requires an item the player doesn't own. |
A rule's daily caps can also refuse a grant, or quarantine it if the rule says so.
Developer products#
When a player buys one of your developer products, the purchase waits for your game to deliver it. Deliver each purchase through the product's grant rule; a receipt is delivered only once.
import { World, server, products } from "neo";
export default class Shop extends World {
@server
async deliver(player) {
for (const r of await products.pending(player)) {
const d = await products.deliver(r.receiptId, "gem_pack", player);
console.log("delivered", r.itemName, d.outcome);
}
}
}from neo import World, server, products
class Shop(World):
@server
async def deliver(self, player):
for r in await products.pending(player):
d = await products.deliver(r.receiptId, "gem_pack", player)
print("delivered", r.itemName, d.outcome)
default = Shop| Call (JS / Python) | Needs | Resolves to |
|---|---|---|
products.pending(player) | receipts | [{ receiptId, itemId, itemName, boughtAt }] |
products.deliver(receipt, rule, player, options) | grant.<rule> | a grant result |
Social: friends, groups, invites and parties#
In @client code a player's own game asks about its own player: leave player empty. The platform refuses questions about other players from there. @server code may ask about any player in the session.
import { World, on, client, social } from "neo";
export default class Lobby extends World {
@client
@on("menu_open")
async menu() {
const playing = (await social.friends()).filter((f) => f.inThisGame);
console.log("friends in this game:", playing.map((f) => f.displayName));
const party = await social.party();
if (party) console.log("party of", party.members.length);
}
}from neo import World, on, client, social
class Lobby(World):
@client
@on("menu_open")
async def menu(self):
friends = await social.friends()
playing = [f.displayName for f in friends if f.inThisGame]
print("friends in this game:", playing)
party = await social.party()
if party is not None:
print("party of", len(party.members))
default = Lobby| Call (JS) | Python | Needs | Resolves to |
|---|---|---|---|
social.friends(player) | social.friends(player) | friends | [{ id, username, displayName, inThisSession, inThisGame }] |
social.isFriend(player, user) | social.is_friend(player, user) | is_friend | true or false |
social.groupRank(player, group) | social.group_rank(player, group) | group_rank.<group> | { member, rank, role }: rank 0 and an empty role when the player isn't a member |
social.invite(player, user) | social.invite(player, user) | invite | { sessionId } |
social.party(player) | social.party(player) | party | { partyId, leader, members }, or null (None) when the player isn't in a party |
social.invite invites the friend user to the player's session as the player, so call it only when the player asked for it. Only friends can be invited, at most 10 in 10 minutes; inviting someone who isn't a friend is refused with failed_precondition. group is the group's id; group_rank.* in calls covers every group.
Ad breaks#
Guests playing on the web can be shown an ad, but never on a timer and never mid-action. Your game declares natural breaks, such as between rounds, on respawn or back in the lobby, and NEO decides whether to fill one: guests only, and at most one ad per 10 minutes of play.
import { World, on, client, ads } from "neo";
export default class Rounds extends World {
@client
@on("round_over")
async breather() {
const r = await ads.breakPoint("between_rounds");
console.log("break over:", r.shown, r.reason);
}
}from neo import World, on, client, ads
class Rounds(World):
@client
@on("round_over")
async def breather(self):
r = await ads.break_point("between_rounds")
print("break over:", r.shown, r.reason)
default = Roundsads.breakPoint(name) (ads.break_point in Python, exposed as ad_break) resolves once the break is over or was declined, with { shown, reason, nextAllowedAt }. Keep the game paused and muted until it resolves. When no ad was shown, reason says why:
| Reason | When |
|---|---|
signed_in | The player has an account. Players on the desktop and BLACKBOX are always signed in. |
capped | An ad was shown too recently; nextAllowedAt says when the next may be. |
not_in_session | The game isn't running in a NEO session, for example a web build opened on its own. |
busy | Another ad is up, the game hasn't started yet, or the tab is in the background. |
Closing a session to matchmaking#
session.setJoinable(false) (session.set_joinable in Python, exposed as joinable) stops matchmaking from placing new players in the session, for example while a round is in progress. session.setJoinable(true) opens it again so it fills back up. It resolves to { joinable }.
import { World, server, session } from "neo";
export default class Match extends World {
@server
async startRound() {
await session.setJoinable(false);
}
@server
async endRound() {
await session.setJoinable(true);
}
}from neo import World, server, session
class Match(World):
@server
async def start_round(self):
await session.set_joinable(False)
@server
async def end_round(self):
await session.set_joinable(True)
default = MatchOnly @server code may call it, because it runs on the session's host. The platform refuses it from any other player with permission_denied.
From Rust#
A game's Rust code can make the same calls through neo_platform_api: PlatformApi has grant, spend_currency, currency_balance, grant_rules, pending_receipts, friends, is_friends_with, group_rank, send_game_invite, party and set_joinable, and AdBreaks::break_point(name) declares a break. The platform's side of each call is in the GameRuntimeService reference.