docs/api/camera

@usbx/camera

Move and control the camera

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

setfunction move_tofunction look_atfunction set_fovfunction set_inputfunction shakefunction letterboxfunction resetfunction

camera.set

function#

Sets the camera shot: follow (the player's own camera), fixed at a position, orbit around a subject or track a subject from an offset. It blends from the current view over duration and replaces a running move.

camera.set(target: Target?, options: { … }) -> ()

example

camera.set(player, { mode = "orbit", subject = player, distance = 10, speed = 20, duration = 1 })

Use it fortop down views, boss arenas, or orbiting shots that show off a build.

targetoptionalOne player, a list of players, or nil for every player, also those who join later.

optionsThe mode, what the camera looks at, the field of view and the blend.

Build a set callmode · position · subject · look_at · offset · distance · 6 more

target

mode
How the camera behaves, where follow is the player's own camera.
positionfixed only
Where the camera stands, which a fixed camera needs.
xyz
subjectorbit and track only
The point, instance or player the camera circles or follows, which both of those modes need.
look_at
The point, instance or player the camera faces, by default the subject or straight ahead when fixed, and in follow the camera turns to keep it in view.
offsettrack onlydefault 0, 6, 12
Where the camera sits compared to the subject, at most 1000 studs away.
xyz
distanceorbit onlydefault 12
How far the camera stays from the subject, from 0.5 to 1000 studs.
heightorbit onlydefault 4
How high above the subject the camera sits, from -1000 to 1000 studs.
speedorbit onlydefault 0
How many degrees per second the camera circles the subject, from -720 to 720.
fov
The field of view in degrees, from 1 to 170, and nil uses the player's own.
input
Whether the player can turn and zoom the camera, which is on by default for follow and orbit and off for fixed and track.
durationdefault 0
How many seconds the camera takes to blend from the current view, up to 60, where 0 cuts straight to it.
easing
How the motion speeds up and slows down: linear, or quad, sine, cubic, quart, expo, back, bounce or elastic followed by _in, _out or _in_out.
for example

camera.move_to

function#

Moves the camera from the current view to a fixed pose over duration and holds it there. The player's camera input is off until set_input or reset.

camera.move_to(target: Target?, options: { … }) -> CameraMove

example

local move = camera.move_to(player, { position = math3d.vector3.new(0, 20, 30), look_at = player, duration = 2 })

Use it forcutscenes, intro flyovers, or showing players the door that just opened.

targetoptionalOne player, a list of players, or nil for every player, also those who join later.

optionsWhere the camera ends, what it faces and how long the move takes.

Build a move_to callposition · look_at · fov · duration · easing

target

positionrequired
Where the camera ends up when the move finishes.
xyz
look_at
The point, instance or player the camera faces, and nil keeps it facing the way it already does.
fov
The field of view at the end of the move in degrees, from 1 to 170, which stays as it is when nil.
durationrequired
How many seconds the move takes, from 0 to 60.
easing
How the motion speeds up and slows down: linear, or quad, sine, cubic, quart, expo, back, bounce or elastic followed by _in, _out or _in_out.
for example

camera.look_at

function#

Turns the camera to face a point, an instance or a player, in any mode, and replaces a running move. In follow it keeps the target in view, a lock-on.

camera.look_at(target: Target?, at: (vector | Instance | Player)?, options: { … }?) -> ()

example

camera.look_at(player, math3d.vector3.new(0, 0, 0), { duration = 0.5 })

Use it forpointing players' cameras at a boss or a goal, or locking on to a target.

targetoptionalOne player, a list of players, or nil for every player, also those who join later.

atoptionalA point, an instance or a player to face. Nil faces the shot's default again.

optionsoptionalThe blend.

Build a look_at callduration · easing

targetat

durationdefault 0
How many seconds the camera takes to blend from the current view, up to 60, where 0 cuts straight to it.
easing
How the motion speeds up and slows down: linear, or quad, sine, cubic, quart, expo, back, bounce or elastic followed by _in, _out or _in_out.
for example

camera.set_fov

function#

Sets the field of view in degrees, and replaces a running move. Nil gives the player's own back.

camera.set_fov(target: Target?, fov: number?, options: { … }?) -> ()

example

camera.set_fov(player, 40, { duration = 0.3 })

Use it forzooming in for a sniper scope, or widening the view while a player sprints.

targetoptionalOne player, a list of players, or nil for every player, also those who join later.

fovoptionalDegrees, 1 to 170. Nil is the player's own.

optionsoptionalThe blend.

Build a set_fov callduration · easing

targetfov

durationdefault 0
How many seconds the camera takes to blend from the current view, up to 60, where 0 cuts straight to it.
easing
How the motion speeds up and slows down: linear, or quad, sine, cubic, quart, expo, back, bounce or elastic followed by _in, _out or _in_out.
for example

camera.set_input

function#

Allows or forbids the player to turn and zoom the camera.

camera.set_input(target: Target?, allowed: boolean) -> ()

example

camera.set_input(player, false)

Use it forlocking player camera control during cutscenes or puzzles.

targetoptionalOne player, a list of players, or nil for every player, also those who join later.

allowedWhether the player may turn and zoom the camera.

camera.shake

function#

Shakes the view, fading out over duration, in any mode.

camera.shake(target: Target?, options: { … }?) -> ()

example

camera.shake(player, { amplitude = 0.8, duration = 0.4 })

Use it forexplosions, earthquakes or heavy hits.

targetoptionalOne player, a list of players, or nil for every player now.

optionsoptionalHow strong, how fast and how long.

Build a shake callamplitude · frequency · duration

target

amplitudedefault 0.5
How far the view shakes, from 0 to 10 studs.
frequencydefault 12
How many times a second the view shakes, from 0.1 to 60.
durationdefault 0.5
How many seconds the shake lasts as it fades out, from 0 to 10.

camera.letterbox

function#

Slides cinematic bars in at the top and the bottom of the screen, or out.

camera.letterbox(target: Target?, options: { … }?) -> ()

example

camera.letterbox(player, { visible = true })

Use it formaking cutscenes feel like a movie, with bars sliding in at the top and bottom of the screen.

targetoptionalOne player, a list of players, or nil for every player, also those who join later.

optionsoptionalWhether the bars show, their size and how fast they slide.

Build a letterbox callvisible · size · duration

target

visible
Whether the bars show, which they do by default, so false hides them.
sizedefault 0.12
How tall each bar is as a share of the screen, from 0 to 0.4.
durationdefault 0.3
How many seconds the bars take to slide in or out, from 0 to 10.

camera.reset

function#

Gives the player's own camera back: follow mode, their field of view, input on, no bars and no shake. It replaces a running move.

camera.reset(target: Target?, options: { … }?) -> ()

example

camera.reset(player, { duration = 1 })

Use it forgiving players their own camera back once a cutscene ends.

targetoptionalOne player, a list of players, or nil for every player.

optionsoptionalThe blend back to the player's own camera.

Build a reset callduration · easing

target

durationdefault 0
How many seconds the camera takes to blend from the current view, up to 60, where 0 cuts straight to it.
easing
How the motion speeds up and slows down: linear, or quad, sine, cubic, quart, expo, back, bounce or elastic followed by _in, _out or _in_out.
for example