Live player scripts
Let players write and run JavaScript or Python in your running game, limited to what you expose to them, and moderate what they run.
On this page
A game can let its players script it while they play. A player opens the in-game script console, writes a script in the game's language, and runs it. The script can only use what your Rust code exposes and what your neo.toml grants to that player's roles. It runs on every player's game in the session, and you can pause, stop or ban it at any time.
Player scripts are off until you turn them on. For how they differ from your own scripts, see Rust code and scripts.
Turning it on#
Allow players in [script.players], set their budgets, and grant each role what it may touch:
[script.players]
allowed = "everyone" # nobody (default), owner, friends, role:<name>, everyone
fuel_per_tick = 200_000
fuel_per_call = 100_000
calls_per_tick = 200
memory = "4MB"
[script.roles.player]
grant = [
"Player.position:get", "Player.speed:get",
"Block.position:get set", "Block.name:get", "Block.size:get", "Block:spawn",
"Remote.claim_pad:fire",
]
[script.roles.builder]
grant = ["Block.size:set", "Block.scale:call"]Every player holds the player role; other roles add to it. Anything not granted doesn't exist for a player's script. The grant syntax is in Exposure and permissions.
Remote.claim_pad:fire lets players' scripts call one of your game's remotes, here Starter's pad race, with this.remote("claim_pad"). See Contexts and remotes.
The script console#
When the game allows a player to script, ` (backquote) or F8 opens the console over the game. While it's open, the game's controls ignore the keyboard.
| Key | What it does |
|---|---|
| Ctrl+Enter | Run the script (or replace the one running). |
| Ctrl+. | Stop the script. |
| F2 | Show the API this player's roles may use (the generated neo.d.ts or neo.pyi). |
| F3 | Restore the example script. |
| F4 | Clear the editor. |
| Ctrl+V (Cmd+V on a Mac) | Paste text. Line breaks are normalised, tabs become two spaces, other control characters are dropped, and the script is kept within 64 KB. |
| F9 | Pick one of the other players' live scripts. |
| F10 | Report the picked script to NEO, with its source as your game received it. |
| Esc | Close the console. The script keeps running. |
The header shows the language, the script's state, its fuel and faults, and what the player's roles may touch. The output pane shows what the script prints (console.log, this.log, or Python's print), its faults, and whether the game accepted or refused it, and why.
import { World, on } from "neo";
export default class Follow extends World {
state = { id: null };
@on("tick")
follow() {
const me = this.query("Player")[0];
if (this.state.id === null) {
this.state.id = this.spawn("Block", { position: me.position }).id;
return;
}
const b = this.query("Block").find((x) => x.id === this.state.id);
if (b) b.position = { x: me.position.x + 2, y: 1.5, z: me.position.z };
}
}If this script tried b.size = … as a plain player, it would get TypeError: Block.size isn't writable by scripts, because only the builder role may set it.
How it runs in a session#
- The host decides. In single player your own game decides. In a multiplayer session the host checks, in order: bans, the
[script.players]policy, the language, your moderation check, the player's grants, the per-player and per-session limits, and a trial compile. A refusal goes back to the player's console with the reason. - Everyone runs it. An accepted script is sent to every player in the session, and each one starts it at the tick the host picked. A player who joins later gets the scripts already running.
- Nobody can widen it. Each player's game works out the script's permissions from its own copy of
neo.toml, so not even the host can grant a player more than you did. Only the host can start or stop scripts, and the author is taken from the network, not from the message. - It can't replace your scripts. A player's script is named
<player>/<name>, so it never overwrites one of the game's own scripts. - It can't save data. Only the game's own scripts can.
- It makes only the platform calls a role grants. A player's script starts with no NEO Platform calls. A role grants some with
NeoPlatform.<call>:call, never more than[script.platform] callslists. For example,NeoPlatform.friends:calllets a player's@clientcode read their own friends. - It can use contexts. A player's script can have
@serverand@clientmethods. Its@clientmethods run on its author's machine only, and its@servermethods on the host, which checks every call. It can call the game's other remotes only with aRemote.<name>:firegrant. See Contexts and remotes.
Printing never changes a script's state hash, and output is capped at 32 lines of 400 characters per tick.
Moderating player scripts#
In the Studio, the Scripts panel has a Live player scripts section that lists each one with its author, roles, state, start tick, size, source hash, faults and fuel. Its buttons are Source, Pause/Resume, Stop and Ban author (Unban for a banned player). A ban stops all of that player's scripts on every player's game and refuses new ones.
The same controls are commands, for tools and agents:
| Command | What it does |
|---|---|
script.live.list | Every live script and its record. |
script.live.source, script.live.output | A live script's source, and its last 200 lines of output. |
script.live.submit, script.live.stop | Run or stop a script as a player (for testing). |
script.live.ban, script.live.unban | Ban or unban an author. |
script.pause, script.resume, script.unload | Act on a live script on every player's game. |
script.console.state, open, set, run, stop | Drive the in-game console. |
script.debug.* | Debug a live script. Only its author, the game's owner, a moderator or the session host may. See Debugging scripts. |
See Script commands for the other commands.
Limits today#
- Shared worlds. A script runs on every player's game, but each game simulates its own character. A script that reads a player's position can read slightly different values on different machines, so keep player scripts to things your game already replicates.
- Moderation in the Creator Hub is by player. Moderation ▸ Live scripts bans a player from live scripting in your game, and Configurations ▸ Player roles grants roles. Pausing, stopping and inspecting individual scripts is in the Studio and the commands.
Reports and NEO's moderators#
Players can report another player's live script, from the console (F9, then F10) or on the web from the game menu's Report a player dialog, choosing A live script they ran. Reports are for signed-in players. The report carries the script's source as the reporter's game received it. When NEO's moderators disable a reported script, it stops on every player's game in the session at the same tick and is refused from then on: every version of it, or only the reported version. The author's console says NEO's moderators disabled it.