Parts, lights, labels and sounds
The world classes a game can expose to scripts (Part, Light, TextLabel, Sound, Camera, Player moves) and the raycast and overlap queries, with every field, range and rate.
NEO's neo_classes crate gives games a set of ready-made kinds that scripts can create and control: shapes, lights, text, sounds and camera effects, plus world queries. A game adds the plugin, then grants what it wants in neo.toml, separately for its own scripts and for each player role. As with any kind, nothing is reachable until it's granted (see Exposure and permissions).
Colours are strings like "#ff8800". Rotations are in degrees: x pitch, y yaw, z roll. Positions and sizes are in metres.
Part#
A primitive shape in the world. Collidable parts block the character, where the game supports it, and are hit by scripts' raycasts and overlaps.
| Field | Type | Range | Meaning |
|---|---|---|---|
position | {x, y, z} | Where it is. | |
shape | string | "box", "sphere", "cylinder", "wedge" | A wedge is a ramp rising toward −X. |
size | {x, y, z} | 0.05–200 each | Along its own axes; a sphere's diameter is the largest. |
rotation | {x, y, z} | −3600–3600 each | Degrees: pitch, yaw, roll. |
color | string | "#rrggbb". | |
roughness | number | 0–1 | 0 is a mirror, 1 is matte. |
metallic | number | 0–1 | Metalness. |
anchored | boolean | Stays put. Unanchored parts are simulated by the game's physics, when it has one. | |
visible | boolean | Drawn. | |
collidable | boolean | Blocks the character and queries. | |
name | string | A name for scripts and the editor. | |
tags | string list | Tags scripts can look for (part.tags.includes("lava")). |
destroy() removes it (at most 20 calls per second). A player can only destroy what their own scripts spawned.
const step = this.spawn("Part", {
shape: "box", size: { x: 2, y: 0.4, z: 2 }, color: "#ff8800",
position: { x: 0, y: 1, z: 4 }, tags: ["step"],
});Light#
| Field | Type | Range | Meaning |
|---|---|---|---|
position | {x, y, z} | Where it is. | |
kind | string | "point", "spot", "directional" | |
color | string | "#rrggbb". | |
intensity | number | 0–100 | 1 is a bright bulb; for a directional light, 1 is overcast daylight. |
range | number | 0.1–200 | How far a point or spot light reaches, in metres. |
angle | number | 1–89 | A spot light's cone half-angle, in degrees. |
enabled | boolean | On. | |
rotation | {x, y, z} | −3600–3600 each | The light shines along its forward; the default −90 pitch points straight down. |
destroy() as for parts. Daylight scenes are bright, so a small point light shows mostly as a pool of colour on nearby surfaces.
TextLabel#
Text over a position in the world, or fixed on the screen.
| Field | Type | Range | Meaning |
|---|---|---|---|
position | {x, y, z} | Where it floats, when not on the screen. | |
text | string | At most 200 characters are shown. | |
color | string | "#rrggbb". | |
size | number | 6–96 | Text size in pixels. |
visible | boolean | Shown. | |
screen | boolean | Fixed on the screen at (screenX, screenY) instead of over its position. | |
screenX | number | 0–1 | 0 is the left edge, 1 the right. |
screenY | number | 0–1 | 0 is the top, 1 the bottom. |
destroy() as for parts.
Sound#
| Field | Type | Range | Meaning |
|---|---|---|---|
position | {x, y, z} | Where it plays from. | |
clip | string | A clip in the game's sound bank, or a built-in cue: "ui_move", "ui_confirm", "ui_back". | |
volume | number | 0–1 | Level. |
pitch | number | 0.25–4 | Playback rate: 1 as recorded, 2 an octave up. |
looped | boolean | Loops until stopped. | |
playing | boolean | read-only | A looped sound is playing. |
play() and stop() (at most 8 calls per second each), and destroy().
Camera#
There is one Camera, for the local player's view. Scripts can't spawn it.
| Member | Meaning |
|---|---|
fov | The current field of view, in degrees (read-only). |
shake(amount) | Shakes the view, amount 0–1. At most 4 calls per second. |
fovPunch(degrees) | Briefly widens (positive) or narrows (negative) the view, −30 to 30. At most 4 calls per second. |
A player's script only affects that player's own camera.
Player moves#
Games built on the gameplay kit add these to Player:
| Member | Meaning |
|---|---|
walkSpeed | The character's walk speed factor (read-only). |
teleport(position) | Moves the character. The game refuses positions outside its allowed area, and in multiplayer the host approves the move. |
setWalkSpeed(factor) | Changes the walk speed; the game clamps it to the range its animations look right in. |
emote(name) | Plays an emote or animation by name. |
A player's script only moves that player's own character.
World queries#
Two methods on World (this in JavaScript, self in Python), each granted separately:
| Method | Returns | Grant |
|---|---|---|
raycast(origin, direction, maxDistance) | { point, normal, distance, entity } or null | World.raycast:call (at most 120 per second) |
overlap(center, radius) | every entity whose shape touches the sphere | World.overlap:call (at most 30 per second) |
They test against the game's level geometry and its collidable parts, as they were at the start of the tick: a part spawned this tick is found from the next one. The answer is the same on every machine.
const hit = this.raycast(me.position, { x: 0, y: -1, z: 0 }, 10);
// reading hit.entity.tags needs the Part.tags:get grant
if (hit && hit.entity?.tags?.includes("lava")) this.log("standing over lava");Granting to players#
A player grant can narrow a range and say which objects it reaches:
[script.players]
allowed = "everyone"
max_spawned = 16 # objects one player's scripts may have at once (default 32)
[script.roles.player]
grant = [
"Part:spawn", "Part.position:get set", "Part.size:get set range=0.1..=3", "Part.destroy:call",
"Light:spawn", "Light.intensity:get set range=0..=10",
"World.raycast:call",
]
[script.roles.builder]
grant = ["Block.position:set any", "World.overlap:call"]range=a..=bnarrows writes to that range, inside the range the game declares. A write outside it is refused with an error the script can catch.ownedandanysay which objects a player's grant reaches. By default a player's field writes reach only what that player's scripts spawned (owned), and method calls reach any object (any), because methods check who is calling themselves. Addanyto a field grant to let a role change the game's own objects, asbuilderdoes above. The game's own scripts always reach everything.max_spawnedcaps how many objects one player's scripts may have at once.