NEOLearn

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.

Updated October 21, 2026

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.

JavaScript
import { economy, badges, products, social, ads, session } from "neo";
Python
from neo import economy, badges, products, social, ads, session

Exposing calls in neo.toml#

[script.platform] calls lists every platform call your game's own scripts may make:

neo.toml
[script.platform]
calls = ["grant.coins_for_wins", "grant.first_win", "grant.gem_pack", "spend.coins", "balance.*", "receipts", "friends", "party"]
Call nameAllows
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>.
receiptsproducts.pending.
ruleseconomy.rules.
friendssocial.friends.
is_friendsocial.isFriend.
group_rank.<group>social.groupRank for the group <group>.
invitesocial.invite.
partysocial.party.
ad_breakads.breakPoint.
joinablesession.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:

neo.toml
[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 codeShared code
economy, badges, productsYesNoNo
session.setJoinableYesNoNo
socialYes, about any player in the sessionYes, about the local playerNo
ads.breakPointNoYes, the local player's own breakNo

@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: ... or failed_precondition: .... In Python the await raises.
  • 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.

rewards.js
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);
  }
}
Call (JS / Python)NeedsResolves 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()rulesthe 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:

OptionMeaning
amountHow much to grant. A currency rule needs it; items and badges default to 1. spend takes its amount as an argument, 1 or more.
eventThe 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:

ReasonWhy
not_authorityThe calling game isn't the session's authority.
player_not_in_sessionThe player isn't in this session.
unknown_ruleThe game has no rule by that name.
rule_disabledThe rule is turned off.
wrong_eventThe event doesn't match the rule's.
bad_amountThe amount is under 1 or over the rule's limit.
already_awardedThe player already has the badge.
already_ownedThe player already owns the item.
missing_receipt, bad_receipt, receipt_usedA purchase rule needs a receipt for this player's purchase that hasn't been delivered yet.
missing_itemThe 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.

shop.js
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);
    }
  }
}
Call (JS / Python)NeedsResolves 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.

lobby.js
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);
  }
}
Call (JS)PythonNeedsResolves to
social.friends(player)social.friends(player)friends[{ id, username, displayName, inThisSession, inThisGame }]
social.isFriend(player, user)social.is_friend(player, user)is_friendtrue 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.

rounds.js
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);
  }
}

ads.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:

ReasonWhen
signed_inThe player has an account. Players on the desktop and BLACKBOX are always signed in.
cappedAn ad was shown too recently; nextAllowedAt says when the next may be.
not_in_sessionThe game isn't running in a NEO session, for example a web build opened on its own.
busyAnother 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 }.

match.js
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);
  }
}

Only @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.

See also#