docs/api/world

@usbx/world

Find, spawn and query parts

local world = require("@usbx/world")

startedevent instance_addedevent instance_removedevent findfunction getfunction queryfunction taggedfunction pickupfunction spawnfunction spawn_prefabfunction roomfunction raycastfunction raycast_allfunction shapecastfunction overlap_boxfunction overlap_spherefunction gravityvalue lightingvalue

world.started

event#

Fires once after every enabled script has finished loading. Callbacks connected later run immediately.

world.started: Event<()>

example

world.started:connect(function() print("ready") end)

Use it forstarting the first round once all scripts have loaded.

world.instance_added

event#

Fires when a script spawns or clones an instance or places a prefab, and when world.room makes a room.

world.instance_added: Event<(Instance)>

example

world.instance_added:connect(function(instance) print(instance.display_name) end)

Use it forkeeping track of the enemies, tokens or props that scripts spawn while the game runs.

world.instance_removed

event#

Fires when a script destroys an instance, and when a room goes with its player. The instance no longer exists when the event runs, so compare it with ==.

world.instance_removed: Event<(Instance)>

example

world.instance_removed:connect(function(instance) if instance == door then print("the door is gone") end end)

Use it fornoticing when a door, token or enemy has been destroyed.

world.find

function#

Finds an instance by its Script Name.

world.find(script_name: string) -> Instance?

example

local door = world.find("Door")

Use it forgrabbing the door, button or sign your script controls, using the Script Name you gave it.

script_nameScript Name of the instance.

world.get

function#

Finds an instance by its Instance ID, 32 hex digits, or gives nil.

world.get(id: string) -> Instance?

example

local part = world.get("0123456789abcdef0123456789abcdef")

Use it forfinding a part again from an Instance ID you saved.

idInstance ID of the instance, 32 hex digits.

world.query

function#

Finds every instance that matches all the options that are set. id finds the one instance with that Instance ID, if the other options match it too.

world.query(options: { … }) -> { … }

example

local coins = world.query({ tag = "Coin" })

Use it forcollecting every token, checkpoint or enemy at the start of a round, filtered by tag, name or kind.

optionsWhat to find. Every option is optional, and an instance must match all that are set.

Build a query calltag · kind · name · under · id

tag
Finds only instances that have this tag on them.
kind
Finds only instances of this kind, where part matches a part of any shape.
name
Finds only the instance that has this Script Name.
under
Finds only instances that are inside this one.
id
Finds only the instance with this Instance ID, which is 32 hex digits long.

world.tagged

function#

The events of every instance with the tag, also instances that get it later.

world.tagged(tag: string) -> TagSet

example

world.tagged("Lava").touched:connect(function(part, player) end)

Use it formaking every kill brick or lava block in the map behave the same way, even ones added later.

tagThe tag.

world.pickup

function#

Makes every instance with the tag a Pickup, such as a coin or a power-up, also instances that get the tag later. The first living player who touches one takes it: it hides and stops colliding at once, so nobody takes it twice, and on_pickup runs with it and the player.

world.pickup(tag: string, on_pickup: (Instance, Player) -> (), options: { … }?) -> Connection

example

world.pickup("Coin", function(_coin, player) coins:increment(player) end, { respawn = 10 })

Use it fortokens, health packs and power-ups that players collect and that can respawn after a few seconds.

tagThe tag of the pickups, such as "Coin". Instances that get the tag later are pickups too.

on_pickupRuns with the pickup and the player who took it. It can wait, as for saved data.

optionsoptionalWhether a pickup comes back, and when.

Build a pickup callrespawn

tagon_pickup

respawn
How many seconds until a taken pickup shows again, 0 or more, and without it a taken pickup is destroyed.

world.spawn

function#

Creates a part and returns it. Without physics the part is anchored.

world.spawn(options: SpawnOptions) -> Instance

example

local ball = world.spawn({ kind = "sphere", position = math3d.vector3.new(0, 10, 0) })

Use it fordropping falling blocks, projectiles or rewards into the game while it runs.

optionsThe shape, place and look of the part.

Build a spawn callkind · position · size · color · rotation · name · 4 more

kindrequired
Which shape the part is made in, and you always have to give it.
positionrequired
Where the part is placed in the world, and you have to give it every time.
xyz
sizedefault 4, 1, 2
How big the part is in studs, which must be above 0 on each axis.
xyz
color
The part's color, which is grey when you leave it out.
#ff0000
rotation
How the part is turned, as a rotation in degrees on each axis.
xyz
name
The part's Script Name, which must not already be in use or you get an error.
tags
A list of tags to put on the part, which can hold at most 64.
parent
The group to put the part in, and leaving it nil puts it at the world root.
physics
Settings that let the part fall and be pushed, and without them the part stays anchored in place.
Inside it: enabled, density, friction, bounciness
audience
The only players who can see the part, given as one Player or a list of them, while everyone else is not sent it and walks through it.

world.spawn_prefab

function#

Places a copy of a prefab of the place and returns its root, an Npc when the root is an NPC. The copy has new Instance IDs, and its Script Names get the lowest number that is free.

world.spawn_prefab(name: string, options: PrefabSpawnOptions) -> Instance

example

local car = world.spawn_prefab("Car", { position = math3d.vector3.new(0, 5, 0) })

Use it forplacing cars, enemies or furniture that you built ahead of time as prefabs.

nameName of a prefab of the place.

optionsWhere the copy goes.

Build a spawn_prefab callposition · rotation · parent · name · tags · audience

name

positionrequired
Where the prefab's origin goes in the world.
xyz
rotation
How the copy is turned, in degrees on each axis.
xyz
parent
The group to put the copy in, which must not be scaled, and nil puts it at the root of the world.
name
The Script Name to give the root of the copy.
tags
A list of tags to put on the root of the copy.
audience
The only players who see the copy, as one Player or a list of them, and other players are not sent it and walk through it.

world.room

function#

A group at the world origin that only the player sees, made on the first call and the same after. What a script puts in it is the player's alone.

world.room(player: Player) -> Instance

example

local room = world.room(player)

Use it forprivate bases, personal puzzles or rewards that only one player can see.

playerThe player whose room it is.

world.raycast

function#

Casts a ray and gives the first hit, or nil. The distance defaults to the length of the direction.

world.raycast(options: QueryFilter & { … }) -> RaycastHit?

example

local hit = world.raycast({ origin = math3d.vector3.new(0, 10, 0), direction = math3d.vector3.new(0, -20, 0) })

Use it forlaser guns, checking line of sight, or finding the ground below a point.

optionsWhere the ray starts, which way it goes and what it can hit.

Build a raycast callorigin · direction · distance · ignore · include · tag · 3 more

originrequired
The point in the world where the ray starts.
xyz
directionrequired
Which way the ray goes, which must not be zero, and its length sets how far unless distance is set.
xyz
distance
How far the ray goes in studs, which is used instead of the length of direction.
ignore
A list of instances and players to skip, along with everything under them.
include
Only finds these instances and players and everything under them, so players not listed here are never found.
tag
Only finds instances with this tag, and skips players unless players is true.
collision_group
Only finds parts that collide with this Collision Group, and skips players unless players is true.
hit_triggers
Whether to also find parts that cannot collide.
players
Whether it finds players, which it does by default, though tag and collision_group skip players unless this is true.

world.raycast_all

function#

Casts a ray and gives everything it passes through, nearest first: one hit for each instance or player, at most 256.

world.raycast_all(options: QueryFilter & { … }) -> { … }

example

local hits = world.raycast_all({ origin = player.position, direction = math3d.vector3.new(0, -50, 0) })

Use it forshots that pierce through things, or counting every wall between two points.

optionsWhere the ray starts, which way it goes and what it can hit.

Build a raycast_all callorigin · direction · distance · ignore · include · tag · 3 more

originrequired
The point in the world where the ray starts.
xyz
directionrequired
Which way the ray goes, which must not be zero, and its length sets how far unless distance is set.
xyz
distance
How far the ray goes in studs, which is used instead of the length of direction.
ignore
A list of instances and players to skip, along with everything under them.
include
Only finds these instances and players and everything under them, so players not listed here are never found.
tag
Only finds instances with this tag, and skips players unless players is true.
collision_group
Only finds parts that collide with this Collision Group, and skips players unless players is true.
hit_triggers
Whether to also find parts that cannot collide.
players
Whether it finds players, which it does by default, though tag and collision_group skip players unless this is true.

world.shapecast

function#

Moves a ball (radius) or a box (size) along the direction and gives the first hit, or nil.

world.shapecast(options: QueryFilter & { … }) -> RaycastHit?

example

local hit = world.shapecast({ origin = player.position, direction = math3d.vector3.new(0, 0, -20), radius = 2 })

Use it forwide sword swings or thick projectiles, where a thin ray could miss what they should hit.

optionsThe ball or box, where it starts, which way it goes and what it can hit.

Build a shapecast callorigin · direction · distance · radius · size · rotation · 6 more

originrequired
The point in the world where the shape starts.
xyz
directionrequired
Which way the shape moves, which must not be zero, and its length sets how far unless distance is set.
xyz
distance
How far the shape moves in studs, which is used instead of the length of direction.
radius
The radius of a ball to cast along the path.
size
The size of a box to cast, which is used instead of a ball when you give it.
xyz
rotation
How the cast box is turned, as a rotation in degrees.
xyz
ignore
A list of instances and players to skip, along with everything under them.
include
Only finds these instances and players and everything under them, so players not listed here are never found.
tag
Only finds instances with this tag, and skips players unless players is true.
collision_group
Only finds parts that collide with this Collision Group, and skips players unless players is true.
hit_triggers
Whether to also find parts that cannot collide.
players
Whether it finds players, which it does by default, though tag and collision_group skip players unless this is true.

world.overlap_box

function#

Finds what a box overlaps: at most 256 instances, and the players.

world.overlap_box(options: QueryFilter & { … }) -> Overlap

example

local inside = world.overlap_box({ center = door.position, size = math3d.vector3.new(8, 8, 8) })

Use it fordoors that open when someone stands in front of them, or checking whether an area is clear.

optionsThe box and what it can find.

Build a overlap_box callcenter · size · rotation · ignore · include · tag · 3 more

centerrequired
The point at the middle of the box, given as a position in the world.
xyz
sizerequired
How big the box is in studs on each axis.
xyz
rotation
How the box is turned, as a rotation in degrees.
xyz
ignore
A list of instances and players to skip, along with everything under them.
include
Only finds these instances and players and everything under them, so players not listed here are never found.
tag
Only finds instances with this tag, and skips players unless players is true.
collision_group
Only finds parts that collide with this Collision Group, and skips players unless players is true.
hit_triggers
Whether to also find parts that cannot collide.
players
Whether it finds players, which it does by default, though tag and collision_group skip players unless this is true.

world.overlap_sphere

function#

Finds what a ball overlaps: at most 256 instances, and the players.

world.overlap_sphere(options: QueryFilter & { … }) -> Overlap

example

local near = world.overlap_sphere({ center = player.position, radius = 10 })

Use it forexplosions or auras that affect everything and everyone nearby.

optionsThe ball and what it can find.

Build a overlap_sphere callcenter · radius · ignore · include · tag · collision_group · 2 more

centerrequired
The point at the middle of the ball, given as a position in the world.
xyz
radiusrequired
How far the ball reaches out from its middle, in studs.
ignore
A list of instances and players to skip, along with everything under them.
include
Only finds these instances and players and everything under them, so players not listed here are never found.
tag
Only finds instances with this tag, and skips players unless players is true.
collision_group
Only finds parts that collide with this Collision Group, and skips players unless players is true.
hit_triggers
Whether to also find parts that cannot collide.
players
Whether it finds players, which it does by default, though tag and collision_group skip players unless this is true.

world.gravity

value#

The gravity of the place in studs per second squared, as set in Studio. Read-only.

world.gravity: number

example

print("gravity:", world.gravity)

Use it forreading the game's gravity so jump arcs and launch strengths match it.

world.lighting

value#

The Clock, the skies, the ambient light and the fog of the place. Every value is writable.

world.lighting: Lighting

example

world.lighting.clock = 18

Use it forday and night cycles, spooky fog, or a warm sunset scene.