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:
Functions:
sm.camera.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.
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 |
sm.camera.cameraSphereCast(radius, start, direction)
Client only
Performs a distance convex sweep with the shape of a sphere, from a position with a given direction.
Parameters:
| Type | Name | Description |
|---|---|---|
| number | radius | The radius of the cast sphere |
| Vec3 | start | The start position. |
| Vec3 | direction | The cast direction and range. |
Returns:
| Type | Description |
|---|---|
| number | The fraction of the distance reached until collision. |
sm.camera.getCameraPullback()
Client only
Returns the camera's zoom step.
Returns:
| Type | Description |
|---|---|
| number | step How far away the camera is from the player while standing |
| number | seatedStep How far away the camera is from the player while seated |
sm.camera.getCameraState()
Client only
Gets the camera's control state.
Returns:
| Type | Description |
|---|---|
| integer | state How the camera is moved. (See sm.camera.state) |
sm.camera.getDefaultFov()
Client only
Returns the camera's default field of view angle.
Returns:
| Type | Description |
|---|---|
| number | The field of view. |
sm.camera.getDefaultPosition()
Client only
Returns the world position where the camera should be by default.
Returns:
| Type | Description |
|---|---|
| Vec3 | The camera's world position. |
sm.camera.getDefaultRotation()
Client only
Returns the world rotation where the camera should be by default.
Returns:
| Type | Description |
|---|---|
| Quat | The camera's default world rotation. |
sm.camera.getDirection()
Client only
Returns the direction the camera is aiming.
Returns:
| Type | Description |
|---|---|
| Vec3 | The direction of the camera's aim. |
sm.camera.getFov()
Client only
Returns the camera's field of view angle.
Returns:
| Type | Description |
|---|---|
| number | The field of view. |
sm.camera.getPosition()
Client only
Returns the world position of the camera.
Returns:
| Type | Description |
|---|---|
| Vec3 | The camera's world position. |
sm.camera.getRight()
Client only
Returns the right-vector perpendicular to the camera's aim.
Returns:
| Type | Description |
|---|---|
| Vec3 | The right-vector of the camera's aim. |
sm.camera.getRotation()
Client only
Returns the world rotation of the camera.
Returns:
| Type | Description |
|---|---|
| Quat | The camera's world rotation. |
sm.camera.getUp()
Client only
Returns the up-vector perpendicular to the camera's aim.
Returns:
| Type | Description |
|---|---|
| Vec3 | The up-vector of the camera's aim. |
sm.camera.setCameraPullback(step, seatedStep)
Client only
Sets the camera's zoom step.
Parameters:
| Type | Name | Description |
|---|---|---|
| integer | step | How far away the camera is from the player while standing |
| integer | seatedStep | How far away the camera is from the player while seated |
sm.camera.setCameraState(state)
Client only
Sets the camera's control state.
Parameters:
| Type | Name | Description |
|---|---|---|
| integer | state | How the camera is moved. (See sm.camera.state) |
sm.camera.setDirection(direction)
Client only
Sets the direction the camera is aiming.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | direction | The direction of the camera's aim. |
sm.camera.setFov(FOV)
Client only
Sets the camera's field of view angle.
Parameters:
| Type | Name | Description |
|---|---|---|
| number | FOV | The field of view. |
sm.camera.setPosition(position)
Client only
Sets the world position of the camera.
Parameters:
| Type | Name | Description |
|---|---|---|
| Vec3 | position | The camera's world position. |
sm.camera.setRotation(rotation)
Client only
Sets the rotation of the camera.
Parameters:
| Type | Name | Description |
|---|---|---|
| Quat | rotation | The rotation of the camera. |
sm.camera.setSeatLockedCameraPullback(pullback)
Client only
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:
| Type | Name | Description |
|---|---|---|
| number | pullback | The pullback distance. |
sm.camera.setSeatLockedCameraUpOffset(upOffset)
Client only
Sets the camera up offset for the seatLockedCamera camera state.
Parameters:
| Type | Name | Description |
|---|---|---|
| number | upOffset | The up offset in local space. |
sm.camera.setSeatLockedLocalDirection(localDirection)
Client only
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:
| Type | Name | Description |
|---|---|---|
| Vec3 | localDirection | The local direction to face. |
sm.camera.setSeatLockedLocalUp(localUp)
Client only
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:
| Type | Name | Description |
|---|---|---|
| Vec3 | localUp | The local up direction. |
sm.camera.setShake(strength)
Client only
Sets the camera's level of camera shake.
Parameters:
| Type | Name | Description |
|---|---|---|
| number | strength | The camera shake strength. |
sm.camera.setUnseatDirection(worldDirection?)
Client only
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:
| Type | Name | Description |
|---|---|---|
| Vec3 | worldDirection? | The world-space direction to face on unseat. (optional) |