MouseBehavior

Description:

This property sets how the user’s mouse behaves based on the Enum/MouseBehavior Enum. The default value is Enum.MouseBehavior.Default.

It can be set to three values:

Default: The mouse moves freely around the user’s screen.
LockCenter: The mouse is locked, and cannot move from, the center of the user’s screen.
LockCurrentPosition: The mouse is locked, and cannot move from, it’s current position on the user’s screen at the time of locking.

The value of this property does not affect the sensitivity of events tracking mouse movement. For example, UserInputService/GetMouseDelta|GetMouseDelta returns the same DataType/Vector2|Vector2 screen position in pixels regardless of whether the mouse is locked or able to move freely around the user’s screen. As a result, default scripts like those controlling the camera are not impacted by this property.

This property is overridden if a GuiButton with GuiButton/Modal|Modal enabled is GuiButton/Visible unless the player’s right mouse button is down.

Note that, if the mouse is locked, UserInputService/InputChanged will still fire when the player moves the mouse and will pass in the Delta that the mouse attempted to move by. Additionally, if the player is kicked from the game, the mouse will be forcefully unlocked.

As UserInputService is client-side only, this property can only be used in a LocalScript.

Code Samples

Create a Custom CameraScript

By default, Roblox relies on a LocalScript, described [here][1], to control the user’s camera. However, this script can be overridden with a custom CameraScript. The example below demonstrates how to create a custom script to control the user’s camera using many of the UserInputService events.

The script is broken into two parts:

Mobile camera events, which rely on touch events
Non-mobile camera events, which rely on keyboard input and tracking the user’s movement

First, the camera script needs utility functions to setup the camera and set its Camera/CameraType|CameraType to Scriptable so that the script can control the camera. It also needs a function to update the camera when it moves, rotates, and zooms.

Using touch events allows us to track user input as they interact with the touchscreen on their mobile device. These events allow us to handle camera movement, rotation, and zoom.

The second half of the code sample adds camera support for players on desktop devices. When input begans, the function Input() checks that the state of the input is Enum/UserInputState|Enum.UserInputState.Begin to ignore all keypress inputs other than when the user first presses a key down. When the user presses I and O the camera zooms in and out. When the presses down and moves their left mouse button, the script Enum/MouseBehavior|locks the player’s mouse by changing the UserInputService/MouseBehavior property. The camera rotates according to the mouse’s UserInputService/GetMouseDelta|change in screen position. When the player moves their character, the camera moves with them.

All of the parts discussed above are combined and shown in the code sample below.

			
			
				Create a Custom CameraScript

			
			
			
				Expected Output
			
			
				Expand
				
			
		

			
			-- ========================================
-- GLOBAL VARIABLES
-- ========================================
local UserInputService = game:GetService("UserInputService")
local RunService = game:GetService("RunService")

-- The camera used by the LocalPlayer
local camera = game.Workspace.CurrentCamera

local players = game:GetService("Players")
local player = players.LocalPlayer
local character = player.CharacterAdded:Wait()
local torso = character:WaitForChild("Torso")
local playerPosition = torso.Position

local default_CameraPosition = torso.Position
local default_CameraRotation = Vector2.new(0,math.rad(-60))
local default_CameraZoom = 15

local cameraPosition = default_CameraPosition
local cameraRotation = default_CameraRotation
local cameraZoom = default_CameraZoom

local cameraRotationBounds = {math.rad(-81),math.rad(20)}
local cameraZoomBounds = nil --{10,200}
local touchDragSpeed = 0.15
local cameraSpeed = 0.1
local cameraRotateSpeed = 10
local cameraMouseRotateSpeed = 0.25
local cameraTouchRotateSpeed = 10
-- ========================================
-- ========================================





-- ========================================
-- UTILITY FUNCTIONS
-- ========================================
local function SetCameraMode()
camera.CameraType = "Scriptable"
camera.FieldOfView = 80
camera.CameraSubject = nil
end

local function UpdateCamera()
SetCameraMode()
local cameraRotationCFrame = CFrame.Angles(0, cameraRotation.X, 0)*CFrame.Angles(cameraRotation.Y, 0, 0)
camera.CFrame = cameraRotationCFrame + cameraPosition + cameraRotationCFrame*Vector3.new(0, 0, cameraZoom)
camera.Focus = camera.CFrame - Vector3.new(0, camera.CFrame.p.Y, 0)
end
-- ========================================
-- ========================================




-- ========================================
-- MOBILE CAMERA EVENTS
-- ========================================
-- Events used to control the camera for players using a mobile device

-- ====================
-- CAMERA MOVE
-- ====================
-- Fired by UserInputService.TouchPan
local lastTouchTranslation = nil
local function TouchMove(touchPositions, totalTranslation, velocity, state)
	if state == Enum.UserInputState.Change or state == Enum.UserInputState.End then
		local difference = totalTranslation - lastTouchTranslation
	cameraPosition = cameraPosition + Vector3.new(difference.X, 0, difference.Y)
		UpdateCamera()
	end
	lastTouchTranslation = totalTranslation
end

-- ====================
-- CAMERA ROTATE
-- ====================
-- Fired by UserInputService.TouchRotate
local lastTouchRotation = nil
local function TouchRotate(touchPositions, rotation, velocity, state)
if state == Enum.UserInputState.Change or state == Enum.UserInputState.End then
local difference = rotation - lastTouchRotation
cameraRotation = cameraRotation + Vector2.new(-difference,0)*math.rad(cameraTouchRotateSpeed*cameraRotateSpeed)
		UpdateCamera()
	end
lastTouchRotation = rotation
end

-- ====================
-- CAMERA ZOOM
-- ====================
-- Fired by UserInputService.TouchPinch
local lastTouchScale = nil
local function TouchZoom(touchPositions, scale, velocity, state)
	if state == Enum.UserInputState.Change or state == Enum.UserInputState.End then
		local difference = scale - lastTouchScale
		cameraZoom = cameraZoom * (1 + difference)
		if cameraZoomBounds ~= nil then
			cameraZoom = math.min(math.max(cameraZoom, cameraZoomBounds[1]), cameraZoomBounds[2])
		else
			cameraZoom = math.max(cameraZoom, 0)
end
		UpdateCamera()
	end
	lastTouchScale = scale
end

local function Input()
	UpdateCamera()
end
-- ========================================





-- ========================================
-- NON-MOBILE CAMERA EVENTS
-- ========================================

local function Input(inputObject)
	if inputObject.UserInputType == Enum.UserInputType.Keyboard then
		if inputObject.UserInputState == Enum.UserInputState.Begin then						
			-- ====================
			-- CAMERA ZOOM
			-- ====================
			-- (I) Zoom In
			if inputObject.KeyCode == Enum.KeyCode.I then
			 	cameraZoom = cameraZoom - 15
			elseif inputObject.KeyCode == Enum.KeyCode.O then
				cameraZoom = cameraZoom + 15
			end
		
			-- (O) Zoom Out
			if cameraZoomBounds ~= nil then
				cameraZoom = math.min(math.max(cameraZoom, cameraZoomBounds[1]), cameraZoomBounds[2])
			else
				cameraZoom = math.max(cameraZoom, 0)
			end
			
			UpdateCamera()
		end
	end
	
	-- ====================
	-- CAMERA ROTATE
	-- ====================
	local pressed = UserInputService:IsMouseButtonPressed(Enum.UserInputType.MouseButton1)
	if pressed then
		UserInputService.MouseBehavior = Enum.MouseBehavior.LockCurrentPosition
		local rotation = userInputService:GetMouseDelta()
		cameraRotation = cameraRotation + rotation*math.rad(cameraMouseRotateSpeed)
	else
		UserInputService.MouseBehavior = Enum.MouseBehavior.Default
	end
end

-- ====================
-- CAMERA MOVE
-- ====================
local function PlayerChanged()
	local movement = torso.Position - playerPosition
	cameraPosition = cameraPosition + movement
	playerPosition = torso.Position
		
	UpdateCamera()
end
-- ========================================
-- ========================================






-- ========================================
-- DEVICE CHECK
-- ========================================
-- Determine whether the user is on a mobile device

if UserInputService.TouchEnabled then
	-- The user is on a mobile device, use Touch events
UserInputService.TouchPan:Connect(TouchMove)
UserInputService.TouchRotate:Connect(TouchRotate)
UserInputService.TouchPinch:Connect(TouchZoom)
else
	
	-- The user is not on a mobile device use Input events
UserInputService.InputBegan:Connect(Input)
UserInputService.InputChanged:Connect(Input)
UserInputService.InputEnded:Connect(Input)

	-- Camera controlled by player movement
	wait(2)
	RunService:BindToRenderStep("PlayerChanged", Enum.RenderPriority.Camera.Value-1, PlayerChanged)
end	
-- ========================================
-- ========================================
		

			
		

			
				
				Copy Code
			
			
				Light Theme
				
					
					
				
			
		

Create a Binoculars Script

This example creates a binoculars script that decreases the player’s Camera/FieldOfView|FieldOfView and UserInputService/MouseDeltaSensitivity|MouseDeltaSensitivity when a player with a UserInputService/MouseEnabled|MouseEnabled left mouse clicks. The script also points the player’s Camera towards the DataType/Vector3|Vector3 world position of the mouse click determined by the Mouse|Mouse’s Mouse/Hit|Mouse.Hit.p property.

When the player left mouse clicks again, the player’s camera reverts back to the a custom Enum/CameraType|CameraType with the same field of view and Camera/CFrame|CFrame as before the player zoomed in with the script.

While the player uses the binoculars, the script locks the player’s mouse to the center of the screen by setting the player’s UserInputType/MouseBehavior|MouseBehavior to LockCenter. The player’s camera moves when the player moves their mouse according to the InputObject/Delta|InputObject.Delta property passed by UserInputService/InputChanged|InputChanged indicating the mouse’s DataType/Vector2|Vector2 change in screen position.

In order for this example to work as expected, it should be placed in a LocalScript.

			
			
				Create a Binoculars Script

			
			
			
				Expected Output
			
			
				Expand
				
			
		

			
			local UserInputService = game:GetService("UserInputService")

local Players = game:GetService("Players")
local player = Players.LocalPlayer
local character = player.CharacterAdded:Wait()
local head = character:WaitForChild("Head", false)

local mouse = player:GetMouse()

local zoomed = false
local camera = game.Workspace.CurrentCamera
local target = nil
local originalProperties =
{
	FieldOfView = nil,
	_CFrame = nil,
	MouseBehavior = nil,
	MouseDeltaSensitivity = nil
}

local AngleX,TargetAngleX = 0,0
local AngleY,TargetAngleY = 0,0

-- Reset camera back to CFrame and FieldOfView before zoom
local function ResetCamera()
	target = nil
	camera.CameraType = Enum.CameraType.Custom
	camera.CFrame = originalProperties._CFrame
	camera.FieldOfView = originalProperties.FieldOfView
	
	UserInputService.MouseBehavior = originalProperties.MouseBehavior
	UserInputService.MouseDeltaSensitivity = originalProperties.MouseDeltaSensitivity
end

local function ZoomCamera()
	-- Allow camera to be changed by script
	camera.CameraType = Enum.CameraType.Scriptable
		
	-- Store camera properties before zoom
	originalProperties._CFrame = camera.CFrame
	originalProperties.FieldOfView = camera.FieldOfView
	originalProperties.MouseBehavior = UserInputService.MouseBehavior
	originalProperties.MouseDeltaSensitivity = UserInputService.MouseDeltaSensitivity

	-- Zoom camera
	target = mouse.Hit.p
	local eyesight = head.Position
	camera.CFrame = CFrame.new(eyesight, target)
	camera.Focus = CFrame.new(target)
	camera.FieldOfView = 10
	
	-- Lock and slow down mouse
	UserInputService.MouseBehavior = Enum.MouseBehavior.LockCenter
	UserInputService.MouseDeltaSensitivity = 1
	
	-- Reset zoom angles
	AngleX,TargetAngleX = 0,0
	AngleY,TargetAngleY = 0,0
end

-- Toggle camera zoom/unzoom
local function MouseClick()
	if zoomed then
		-- Unzoom camera
		ResetCamera()
	else
		-- Zoom in camera
		ZoomCamera()
	end
	
	zoomed = not zoomed
end

local cameraRotation = Vector2.new(0,math.rad(-60))
local function MouseMoved(input)
	if zoomed then
		local sensitivity = 0.6		-- anything higher would make looking up and down harder; recommend anything between 0~1
		local smoothness = 0.05		-- recommend anything between 0~1

		local delta = Vector2.new(input.Delta.x/sensitivity,input.Delta.y/sensitivity) * smoothness

		local X = TargetAngleX - delta.y
		local Y = TargetAngleY - delta.x
		TargetAngleX = (X >= 80 and 80) or (X <= -80 and -80) or X
		TargetAngleY = (Y >= 80 and 80) or (Y <= -80 and -80) or Y
		
		AngleX = AngleX + (TargetAngleX - AngleX) *0.35
		AngleY = AngleY + (TargetAngleY - AngleY) *0.15
		
		camera.CFrame = CFrame.new(head.Position, target)
		* CFrame.Angles(0,math.rad(AngleY),0)
		* CFrame.Angles(math.rad(AngleX),0,0)
	end
end

local function InputBegan(input, gameProcessedEvent)
	if input.UserInputType == Enum.UserInputType.MouseButton1 then
		MouseClick()
	end
end

local function InputChanged(input, gameProcessedEvent)
	if input.UserInputType == Enum.UserInputType.MouseMovement then
		MouseMoved(input)
	end
end

if UserInputService.MouseEnabled then
	UserInputService.InputBegan:Connect(InputBegan)
	UserInputService.InputChanged:Connect(InputChanged)
end
		

			
		

			
				
				Copy Code
			
			
				Light Theme
				
					
					
				
			
		