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.
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:
@serverruns it only on the session's host, the machine that decides what counts.@clientruns 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#
| Annotation | Runs | Reads this.state | Writes this.state |
|---|---|---|---|
| none (the default) | On every player's game, from the same inputs. | Yes | Yes. Every game computes the same value. |
@server | Only 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. |
@client | On each player's machine. A player's live script runs its @client methods on its author's machine only. | Yes | No. 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:
- Each player's machine sees its own character touch the pad (
@client). - It asks the host to count the step (
claimPad, a remote call). - The host adds the point to
this.state, which reaches every game at one tick, and tells every player's machine (cheer). - The promise resolves with the new total.
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 });
}
}from neo import World, on, server, client
class PadRace(World):
state = {"pads": {}}
# each player's machine: their character stepped on a block
@client
@on("touch", tag="Block")
async def touched(self, player, block):
if block.name != "pad":
return
total = await self.claim_pad()
print("pad race:", total)
# the host only: at most two claims a second per player
@server(rate=2)
def claim_pad(self):
who = self.sender
pads = dict(self.state.pads)
pads[who] = pads.get(who, 0) + 1
self.state.pads = pads
self.cheer(who, pads[who])
return pads[who]
# every player's machine, when the host counted someone's step
@client
def cheer(self, who, total):
self.emit("pad_race", {"who": who, "total": total})
default = PadRaceThe 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#
| From | Call | What happens |
|---|---|---|
@client code | a @server method of the same script (this.claimPad()) | A remote call. Returns a promise of the host's result. |
@client code | this.remote("claim_pad", ...args) | A remote call to any of the game's remotes, by its snake_case name. |
@server code | a @client method (this.cheer(who, n)) | Runs it on every player's machine. Returns nothing. |
@server code | this.to(player).cheer(who, n) | Runs it on one player's machine only. |
| shared code | a @server or @client method | A 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.statechange applies, so code after theawaitreads the new state. In Python, a refused call raises in the awaiting handler. this.senderis the calling player's id inside a@servermethod 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 firstawait. Elsewhere it'snull(None).this.to(player)only works in@servercode. Anywhere else it's aTypeError.this.contextsays 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#
| Limit | Value |
|---|---|
| Arguments and results of one call | At most 2 KB, encoded. |
| Entities in arguments or results | Not allowed. An entity's id is only valid on one machine: send its name or a field instead. |
| Remote calls a client sandbox can make | 16 per tick. |
| Remote calls waiting for a reply | 256 per client sandbox. Await some first. |
| Client calls a server sandbox can make | 64 per tick. |
One this.state change sent by the host | At 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
@servermethod; - 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:
[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.statecarries over, but a@serversandbox's instance fields and pending timers don't. Keep anything the host must remember inthis.state.
Checking it#
| Command | Shows |
|---|---|
script.list | Each script's contexts and methods. |
script.remote.status | The 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.