NEOLearn

Contexts and remotes

Run script methods only on the session's host or only on players' machines with @server and @client, and call between them with remotes.

Updated October 21, 2026

On this page

By default a script method runs on every player's game in the session, from the same inputs, so every game computes the same result. Two decorators change where a method runs:

  • @server runs it only on the session's host, the machine that decides what counts.
  • @client runs it only on players' machines.

Both go on public instance methods only. On a static or #private method, a getter, a setter or an accessor field they throw a TypeError naming the decorator.

A @client method can call a @server method. That's a remote call: it goes to the host, the host runs the method, and the result comes back as a promise. Use it for anything a player shouldn't be able to decide alone, like scores.

The three contexts#

AnnotationRunsReads this.stateWrites this.state
none (the default)On every player's game, from the same inputs.YesYes. Every game computes the same value.
@serverOnly on the session's host.Yes, including its own writes not yet sent.Yes. The host sends the change, and every game applies it at the same tick.
@clientOn each player's machine. A player's live script runs its @client methods on its author's machine only.YesNo. Writing it is a TypeError.

In single player, your game is both the host and the player, so @server and @client methods both run on it, the same way they would in a session.

Example: the pad race#

Starter's assets/scripts/pad_race.js scores every player's steps on the orange pad. The host keeps the scores, so nobody can give themselves points:

  1. Each player's machine sees its own character touch the pad (@client).
  2. It asks the host to count the step (claimPad, a remote call).
  3. The host adds the point to this.state, which reaches every game at one tick, and tells every player's machine (cheer).
  4. The promise resolves with the new total.
pad_race.js
import { World, on, server, client } from "neo";

export default class PadRace extends World {
  state = { pads: {} };

  // each player's machine: their character stepped on a block
  @client
  @on("touch", { tag: "Block" })
  touched(player, block) {
    if (block.name !== "pad") return;
    this.claimPad()
      .then((n) => console.log(`pad race: ${n}`))
      .catch((e) => console.warn("the host didn't count it:", String(e)));
  }

  // the host only: at most two claims a second per player
  @server({ rate: 2 })
  claimPad() {
    const who = this.sender;
    const pads = { ...this.state.pads };
    pads[who] = (pads[who] || 0) + 1;
    this.state.pads = pads;
    this.cheer(who, pads[who]);
    return pads[who];
  }

  // every player's machine, when the host counted someone's step
  @client
  cheer(who, total) {
    this.emit("pad_race", { who, total });
  }
}

The real Starter script also shows the total in an on-screen label. It keeps the label's id in an instance field (this.label), because client code can't write this.state.

Calling between contexts#

FromCallWhat happens
@client codea @server method of the same script (this.claimPad())A remote call. Returns a promise of the host's result.
@client codethis.remote("claim_pad", ...args)A remote call to any of the game's remotes, by its snake_case name.
@server codea @client method (this.cheer(who, n))Runs it on every player's machine. Returns nothing.
@server codethis.to(player).cheer(who, n)Runs it on one player's machine only.
shared codea @server or @client methodA TypeError. Give the method an @on event instead, or call it from the other side.

Every @server method of a game's scripts is a remote, named by its snake_case name: a JavaScript claimPad and a Python claim_pad are both the remote claim_pad.

  • The promise settles at a tick. It resolves with the host's result, or rejects with the host's refusal, at the tick the host's reply is applied. That's the same tick its this.state change applies, so code after the await reads the new state. In Python, a refused call raises in the awaiting handler.
  • this.sender is the calling player's id inside a @server method a client called (Python: self.sender). It comes from the network connection, not from the message, so a player can't pretend to be someone else. Read it before the first await. Elsewhere it's null (None).
  • this.to(player) only works in @server code. Anywhere else it's a TypeError.
  • this.context says where the code is running: "shared", "server" or "client".

Each context is separate#

Each context runs in its own sandbox, with its own memory, timers, fuel and random stream. Nothing a @server or @client method does reaches the other games except a this.state change sent by the host, so every game's state hash stays the same.

Instance fields (this.label = ...) belong to the sandbox that set them. Keep client-only values, like a label's id or a local effect, in fields. Keep anything every game should agree on in this.state.

Limits#

LimitValue
Arguments and results of one callAt most 2 KB, encoded.
Entities in arguments or resultsNot allowed. An entity's id is only valid on one machine: send its name or a field instead.
Remote calls a client sandbox can make16 per tick.
Remote calls waiting for a reply256 per client sandbox. Await some first.
Client calls a server sandbox can make64 per tick.
One this.state change sent by the hostAt most 64 KB.
Calls to one @server method@server({ rate }) calls per second per player (Python: @server(rate=…)). 10 a second by default.

Arguments and results are plain values: numbers, strings, booleans, null, lists and objects of those.

The host checks every call#

Whatever a player's game sends, the host checks each call before running it:

  • the calling script also runs on the host, and belongs to the caller (a player can't call as another player's script);
  • the method is a @server method;
  • a player's live script holds the grant for it (below);
  • the payload fits the limits;
  • the caller is within the method's rate.

A refused call rejects the caller's promise with the reason, and is counted in script.remote.status.

Remotes and player scripts#

The game's own scripts can call every remote. A player's live script can call its own script's @server methods, and the game's other remotes only with a grant in one of the player's roles:

neo.toml
[script.roles.player]
grant = ["Remote.claim_pad:fire"]

With that grant, a player's script can call this.remote("claim_pad") and gets counted by the host like Starter's own pad race. See Exposure and permissions for the other grants.

Known limits#

  • Host hand-off. When the host leaves and another player takes over, this.state carries over, but a @server sandbox's instance fields and pending timers don't. Keep anything the host must remember in this.state.

Checking it#

CommandShows
script.listEach script's contexts and methods.
script.remote.statusThe game's remotes (name, script, method, rate), this machine's player id, whether it's the host, and the traffic: calls sent and accepted, replies, client calls, state changes, and refusals with reasons.

See Script commands.

See also#