Camera Properties
All of these properties can be set during runtime, although some properties should only be set when the camera is disabled to ensure the best user experience.
While there are some guardrails in place to prevent you from messing up setting up the camera properties, the module asumes you are passing correct value types.
Warning
Any property that starts with the character _ is not meant to be changed.
CameraOffset
Camera.CameraOffset: Vector3
The offset of the camera from our player's character, more specifically the offset from our player's character's humanoid root part, defaults to the legacy value of Roblox's native shift lock.
FOV
Camera.FOV: number
The camera's field of view can be set to any number between 0 and 120.
PitchLimit
Camera.PitchLimit: number
The maximum degrees to which the camera can be angled up and down. This value can be set to any number between 1 and 89.9.
LockedIcon
Camera.LockedIcon: string
The icon will be displayed when the MouseLocked property is set to true. Setting this to nil disables the icon functionality on mobile and consoles.
UnlockedIcon
Camera.UnlockedIcon: string
The icon will be displayed when the MouseLocked property is set to false. This functionality is only available on PC.
AdjustedControllerIconDisplay
Camera.AdjustedControllerIconDisplay: boolean
Roblox adjusts the mouse/cursor position when using a gamepad. If you want consistent icon behavior across all devices, set this property to true. If set to true, the mouse icon will be readjusted to reflect the PC position when playing on a gamepad. Due to technical limitations, this adjustment is only visual; the actual mouse will still be offset by Roblox. To account for this, please write your code accordingly. For example, if a gun relies on the mouse position, the bullets will not fire at the cursor position that the player can see but at the invisible cursor that is positioned above the visible cursor. This property would be more applicable to a "melee fighting" style of game rather than a shooter game.
MouseLocked
Camera.MouseLocked: boolean
Regardless of the property's name, it affects the camera across all platforms. Setting this value to false will unlock the mouse and set the camera to a static state, where no inputs will be accepted. This value is intended for scenarios where the player needs to interact with some form of UI, such as an inventory menu.
ZoomLocked
Camera.ZoomLocked: boolean
Determines whether the player can control the camera's zoom functionality.
MaxZoom
Camera.MaxZoom: number
The maximum distance the camera can zoom away from its subject.
MinZoom
Camera.MinZoom: number
The maximum distance the camera can zoom in towards its subject.
StartZoom
Camera.StartZoom: number
The camera will always start from this value when it is enabled. This value must be between the minimum and maximum zoom values.
ZoomStiffness
Camera.ZoomStiffness: number
Controls the speed of the camera zoom functionality as it adjusts to the desired zoom level.
ZoomSpeedMouse
Camera.ZoomSpeedMouse: number
Controls the speed at which the desired zoom level is adjusted in response to mouse wheel inputs. The default value aligns with Roblox's default behavior.
ZoomSpeedKeyboard
Camera.ZoomSpeedKeyboard: number
Controls the speed at which the desired zoom level is adjusted in response to keyboard inputs. The default value aligns with Roblox's default behavior.
ZoomSpeedTouch
Camera.ZoomSpeedTouch: number
Controls the speed at which the desired zoom level is adjusted in response to touch inputs. The default value aligns with Roblox's default behavior.
ZoomSensitivityCurvature
Camera.ZoomSensitivityCurvature: number
Determines how the zoom level changes in response to user input, making the zoom speed non-linear and dependent on the current zoom level.
ZoomControllerKey
Camera.ZoomControllerKey: Enum.KeyCode | nil
The key responsible for zooming in and out on a gamepad. Setting this to nil will disable the zoom functionality on the gamepad.
ZoomInKeyboardKey
Camera.ZoomInKeyboardKey: Enum.KeyCode | nil
The key responsible for zooming in on keyboard. Setting this to nil will disable the zoom in functionality on keyboard.
ZoomOutKeyboardKey
Camera.ZoomOutKeyboardKey: Enum.KeyCode | nil
The key responsible for zooming out on keyboard. Setting this to nil will disable the zoom out functionality on keyboard.
SyncZoom
Camera.SyncZoom: boolean
When this property is set to true, the camera will attempt to sync its zoom with Roblox's default camera zoom when the camera gets enabled or disabled. Enabling this behavior will introduce yielding when disabling the camera via the SetEnabled method until the sync is achieved.
MouseRadsPerPixel
Camera.MouseRadsPerPixel: Vector2
Affects the sensitivity of mouse camera movement inputs.
GamepadSensitivityModifier
Camera.GamepadSensitivityModifier: Vector2
Affects the sensitivity of gamepad camera movement inputs.
TouchSensitivityModifier
Camera.TouchSensitivityModifier: Vector2
Affects the sensitivity of touch camera movement inputs.
GamepadLowerKValue
Camera.GamepadLowerKValue: number
Controls the thumbstick input sensitivity for negative inputs: lower values result in more responsive extremes, while higher values provide smoother, more linear control.
GamepadKValue
Camera.GamepadKValue: number
Controls the thumbstick input sensitivity for positive inputs: lower values result in more responsive extremes, while higher values provide smoother, more linear control.
GamepadDeadzone
Camera.GamepadDeadzone: number
This specifies the range of gamepad input values near 0 that will be mapped to an output of 0 to prevent unintentional inputs.
RaycastChannel
Camera.RaycastChannel: Channel | nil
The Channel that will be used for that camera's raycast operations. For more information, please visit SmartRaycast's documentation page.
ObstructionRange
Camera.ObstructionRange: number
If the camera moves closer to the player's character than this range, the character will start to become transparent for better camera visibility.
RotateCharacter
Camera.RotateCharacter: boolean
Sets whether or not the Humanoid will automatically rotate to face in the direction the camera is looking. When set to false, the character rotation will no longer be updated at all. This is done to allow you to add custom character rotation behavior while still retaining the camera functionality. If you want the character to rotate in the direction they are moving, simply set the local character's humanoid AutoRotate property to true after you disable the camera's RotateCharacter property.
CorrectionReversion
Camera.CorrectionReversion: boolean
Whether or not camera collision corrections will be reverted gradually or instantly.
CorrectionReversionSpeed
Camera.CorrectionReversionSpeed: number
The speed at which the camera's collision correction is reverted. This value is scaled based on the current camera offset.
TimeUntilCorrectionReversion
Camera.TimeUntilCorrectionReversion: number
The time required for the camera correction reversal process to commence after collision corrections are no longer applied to the camera. Corrections to the camera's zoom will revert slightly more quickly than other types of corrections. This process is executed on a per-axis basis.
VelocityOffset
Camera.VelocityOffset: boolean
Determines whether the camera will "lag behind" at certain velocity speeds to make the camera movement feel more dynamic.
AllowVelocityOffsetOnTeleport
Camera.AllowVelocityOffsetOnTeleport: boolean
Whether or not the camera should treat the player's character teleportation as regular motion. The module tries its best to detect when teleportation occurs, but the ideal way to handle spikes in velocity due to teleportation is to manually set VelocityOffset to true or false accordingly during runtime, based on whether a teleport is about to be performed on the player's character. If you are planning to introduce your own logic to detect teleportation, then you should set this property to true.
VelocityOffsetVelocityThreshold
Camera.VelocityOffsetVelocityThreshold: number
The minimum camera movement velocity required to start applying the velocity offset.
VelocityOffsetFrequency
Camera.VelocityOffsetFrequency: number
Governs the rate at which the camera's offset adjusts to match the current velocity.
VelocityOffsetDamping
Camera.VelocityOffsetDamping: number
The amplitude of oscillations as the velocity offset reaches its target.
FreeCamMode
Camera.FreeCamMode: boolean
This property controls the current mode of the camera. Setting this property to true will disable the normal camera update process. The camera will rely on the FreeCamCFrame property for its position and orientation. The camera can still be influenced via the camera shake functionality in this mode.
FreeCamCFrame
Camera.FreeCamCFrame: CFrame
This property will be used to determine the camera's position and orientation when FreeCamMode is set to true. You can use this property to animate or statically position the camera during cutscenes.