NEOLearn

Rust code and scripts

A NEO game is built in Rust. Scripts are JavaScript or Python that run inside the running game, written by you and, where you allow it, by players.

Updated October 21, 2026

On this page

A NEO game has two kinds of code. You build the game in Rust. You and, where you allow it, your players script it in JavaScript or Python while it runs. They do different jobs, and scripts only reach what the Rust code exposes to them.

The two layers#

Rust (the game)Scripts (on top of the game)
What it's forThe game itself: its systems, components, physics, characters, rendering, networking and UI.Gameplay on top: platforms, puzzles, timers, spawning, rules and events.
LanguageRust, using the engine's crates.JavaScript or Python (NeoPy). Each game uses one of the two.
Who writes itThe game's creators.The game's creators, and players if the game allows it.
When it changesWhen you compile it. A change reaches players when you publish a new version.While the game runs. Saving a script hot-reloads it and keeps its state.
What it can reachEverything in the engine.Only the entity kinds, fields and methods the Rust code exposes and neo.toml grants.
Where it runsCompiled into the game, natively or as WebAssembly.In the script VM inside the game: sandboxed, deterministic and limited by fuel and memory.
Where you edit itThe desktop Studio. A browser can't compile Rust.Any Studio, including the browser one.

A project keeps both together. The Rust is in crates/ and the scripts are in assets/scripts/ (see Projects).

How they connect#

The Rust code decides what scripts can see. You mark components with #[derive(ScriptExpose)] and methods with #[script_methods]. Then neo.toml grants scripts part of that. If something isn't declared in Rust, it doesn't exist for scripts, and a grant in neo.toml can never widen what Rust declares. See Exposure and permissions.

crates/my_game_game/src/lib.rs
#[derive(Component, ScriptExpose)]
#[script(kind = "Platform", transform(get, set))]
pub struct Platform {
    #[script(get, set, range = 0.0..=1.0)]
    pub speed: f32,
}
assets/scripts/platform.js
import { World, on } from "neo";

export default class Mover extends World {
  @on("tick")
  move(dt) {
    for (const p of this.query("Platform")) {
      const { x, z } = p.position;
      p.position = { x, y: 1 + Math.sin(this.time), z };
    }
  }
}

The Rust code defines what a platform is and how fast it may move. The script decides how it moves, and you can change that while the game is running.

Which one to use#

  • Use Rust when you're adding something new to the game: a new kind of object, a system that runs every frame for thousands of entities, physics, networking, rendering, or anything players mustn't be able to change.
  • Use scripts when you're arranging and tuning what the game already has: levels, rules, timers, rewards and events. Scripts are also how designers who don't write Rust work on the game.

Script performance is fine for gameplay logic. Heavy per-frame work belongs in Rust: each script has a fixed budget per tick (see Limits and determinism).

Scripts are deterministic, and the Rust code they see must be too. The fields scripts read are part of every script's state hash, so Rust code that moves script-visible entities mustn't use the platform's sin and cos (f32::sin, f32::cos): their last bit differs between machines. Use libm or straight-line arithmetic; see Rust game code that scripts can see.

Scripts written by players#

Because scripts can only reach what you expose, you can let players write scripts for your game while it runs. Their scripts get less access than yours:

  • Off by default. [script.players] allowed in neo.toml decides who may load live scripts: nobody, the owner, the owner's friends, a role, or everyone.
  • Their own grants. A player's script starts with no access. It gets only what [script.roles.player] grants, plus the grants of any other roles the player holds.
  • Their own budgets and moderation. Player scripts have separate fuel and memory budgets, and each one must pass your game's moderation check before it runs.
  • No save data. Only your game's own scripts can save data.

Everything else works the same way for player scripts: they're sandboxed and deterministic, and they hot-reload.

See also#