sm.camera

The camera library contains methods related to the localPlayer's camera view.

In first-person view the camera is located inside the player's head, whereas in third-person view it floats behind them.

This library can only be used on the client.

Constants

Name	Type	Description
`state`	table	Camera states are used to specify how the camera will view the world. The default state is meant for normal gameplay and the scripted states are meant to be used in cutscenes or interactables.

state

Value type: table

Camera states are used to specify how the camera will view the world. The default state is meant for normal gameplay and the scripted states are meant to be used in cutscenes or interactables.

The states are:

default – The camera is controlled by the player.
cutsceneFP – Scripted first-person camera; position, rotation, and FOV are set by script.
cutsceneTP – Scripted third-person camera; position, rotation, and FOV are set by script.
forcedTP – Forces a third-person view regardless of the player's zoom step. Used during tumbling.
gyroSeatFP – First-person camera whose direction is driven by the gyro seat's rotation.
gyroSeatTP – Third-person camera for the gyro seat.
scriptedTP – Third-person camera with position, rotation, and FOV fully overridden by script. Used for interactable cutscenes.
seatLockedCamera – The camera direction and position are locked to the seat's local space. The view is first-person unless a pullback is set, which produces a third-person view.

{
    default          = 1,
    cutsceneFP       = 2,
    cutsceneTP       = 3,
    forcedTP         = 4,
    gyroSeatFP       = 5,
    gyroSeatTP       = 6,
    scriptedTP       = 7,
    seatLockedCamera = 8,
}

Client-only

cameraSphereCast

sm.camera.cameraSphereCast( radius, start, direction )

Performs a distance convex sweep with the shape of a sphere, from a position with a given direction.

Parameters:

Name	Type	Description
`radius`	number	The radius of the cast sphere
`start`	Vec3	The start position.
`direction`	Vec3	The cast direction and range.

Returns:

Type	Description
number	The fraction of the distance reached until collision.

getCameraPullback

sm.camera.getCameraPullback(  )

Returns the camera's zoom step.

Returns:

Name	Type	Description
`step`	number	How far away the camera is from the player while standing
`seatedStep`	number	How far away the camera is from the player while seated

getCameraState

sm.camera.getCameraState(  )

Gets the camera's control state.

Returns:

Name	Type	Description
`state`	integer	How the camera is moved. (See sm.camera.state)

getDefaultFov

sm.camera.getDefaultFov(  )

Returns the camera's default field of view angle.

Returns:

Type	Description
number	The field of view.

getDefaultPosition

sm.camera.getDefaultPosition(  )

Returns the world position where the camera should be by default.

Returns:

Type	Description
Vec3	The camera's world position.

getDefaultRotation

sm.camera.getDefaultRotation(  )

Returns the world rotation where the camera should be by default.

Returns:

Type	Description
Quat	The camera's default world rotation.

getDirection

sm.camera.getDirection(  )

Returns the direction the camera is aiming.

Returns:

Type	Description
Vec3	The direction of the camera's aim.

getFov

sm.camera.getFov(  )

Returns the camera's field of view angle.

Returns:

Type	Description
number	The field of view.

getPosition

sm.camera.getPosition(  )

Returns the world position of the camera.

Returns:

Type	Description
Vec3	The camera's world position.

getRight

sm.camera.getRight(  )

Returns the right-vector perpendicular to the camera's aim.

Returns:

Type	Description
Vec3	The right-vector of the camera's aim.

getRotation

sm.camera.getRotation(  )

Returns the world rotation of the camera.

Returns:

Type	Description
Quat	The camera's world rotation.

getUp

sm.camera.getUp(  )

Returns the up-vector perpendicular to the camera's aim.

Returns:

Type	Description
Vec3	The up-vector of the camera's aim.

setCameraPullback

sm.camera.setCameraPullback( step, seatedStep )

Sets the camera's zoom step.

Parameters:

Name	Type	Description
`step`	integer	How far away the camera is from the player while standing
`seatedStep`	integer	How far away the camera is from the player while seated

setCameraState

sm.camera.setCameraState( state )

Sets the camera's control state.

Parameters:

Name	Type	Description
`state`	integer	How the camera is moved. (See sm.camera.state)

setDirection

sm.camera.setDirection( direction )

Sets the direction the camera is aiming.

Parameters:

Name	Type	Description
`direction`	Vec3	The direction of the camera's aim.

setFov

sm.camera.setFov( FOV )

Sets the camera's field of view angle.

Parameters:

Name	Type	Description
`FOV`	number	The field of view.

setPosition

sm.camera.setPosition( position )

Sets the world position of the camera.

Parameters:

Name	Type	Description
`position`	Vec3	The camera's world position.

setRotation

sm.camera.setRotation( rotation )

Sets the rotation of the camera.

Parameters:

Name	Type	Description
`rotation`	Quat	The rotation of the camera.

setSeatLockedCameraPullback

sm.camera.setSeatLockedCameraPullback( pullback )

Sets the camera pullback distance for the seatLockedCamera camera state.

When greater than zero the camera is pulled back from the seat origin along the camera direction.

Parameters:

Name	Type	Description
`pullback`	number	The pullback distance.

setSeatLockedCameraUpOffset

sm.camera.setSeatLockedCameraUpOffset( upOffset )

Sets the camera up offset for the seatLockedCamera camera state.

Parameters:

Name	Type	Description
`upOffset`	number	The up offset in local space.

setSeatLockedLocalDirection

sm.camera.setSeatLockedLocalDirection( localDirection )

Sets the local direction for the camera when using the seatLockedCamera camera state.

The direction is in the seat's local space and will be transformed by the interpolated seat rotation.

Parameters:

Name	Type	Description
`localDirection`	Vec3	The local direction to face.

setSeatLockedLocalUp

sm.camera.setSeatLockedLocalUp( localUp )

Sets the local up vector for the camera when using the seatLockedCamera camera state.

The up vector is in the seat's local space.

Parameters:

Name	Type	Description
`localUp`	Vec3	The local up direction.

setShake

sm.camera.setShake( strength )

Sets the camera's level of camera shake.

Parameters:

Name	Type	Description
`strength`	number	The camera shake strength.

setUnseatDirection

sm.camera.setUnseatDirection( worldDirection )

Sets the world-space direction for the local player character to face when the player unseats. Cleared automatically when used or when entering a seat.

Passing nil clears any previously set unseat direction.

Parameters:

Name	Type	Description
`worldDirection` (optional)	Vec3	The world-space direction to face on unseat. (optional)