@quenty/camera 14.40.1 → 14.41.1

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [14.41.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/camera@14.41.0...@quenty/camera@14.41.1) (2026-06-05)
+
+### Bug Fixes
+
+- Pass input ([faf1d56](https://github.com/Quenty/NevermoreEngine/commit/faf1d567726e8d640d8fd0060342fc200840a640))
+
+# [14.41.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/camera@14.40.1...@quenty/camera@14.41.0) (2026-06-03)
+
+### Features
+
+- ConstrainedLookCamera ([8247ba8](https://github.com/Quenty/NevermoreEngine/commit/8247ba88b84c8f209bd1f72b7a384b907f735338))
+
 ## [14.40.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/camera@14.40.0...@quenty/camera@14.40.1) (2026-05-30)
 
 **Note:** Version bump only for package @quenty/camera

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/camera",
-  "version": "14.40.1",
+  "version": "14.41.1",
   "description": "Quenty's camera system for Roblox",
   "keywords": [
     "Roblox",
@@ -53,5 +53,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "598b2b62b36bdcbdbbd56f7db10c399831cc6eba"
+  "gitHead": "4f028984d278f4c3c77ab60ae1ce11cbaf00cb6d"
 }

package/src/Client/Controls/ConstrainedLookControls.lua

@@ -0,0 +1,222 @@
+--!strict
+--[=[
+	Input handler that drives a [ConstrainedLookCamera]. Reacts to right-click
+	drag on mouse, drag on touchscreen, and right thumbstick on gamepad.
+
+	@class ConstrainedLookControls
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local ContextActionService = game:GetService("ContextActionService")
+local RunService = game:GetService("RunService")
+local UserInputService = game:GetService("UserInputService")
+
+local ConstrainedLookCamera = require("ConstrainedLookCamera")
+local GamepadRotateModel = require("GamepadRotateModel")
+local InputObjectUtils = require("InputObjectUtils")
+local Maid = require("Maid")
+
+local ConstrainedLookControls = {}
+ConstrainedLookControls.__index = ConstrainedLookControls
+ConstrainedLookControls.ClassName = "ConstrainedLookControls"
+
+ConstrainedLookControls.MOUSE_SENSITIVITY = Vector2.new(math.pi * 4, math.pi * 1.9)
+ConstrainedLookControls.GAMEPAD_SENSITIVITY = 0.1
+ConstrainedLookControls._dragBeginTypes = { Enum.UserInputType.MouseButton2, Enum.UserInputType.Touch }
+
+export type ConstrainedLookControls = typeof(setmetatable(
+	{} :: {
+		_camera: ConstrainedLookCamera.ConstrainedLookCamera,
+		_enabled: boolean,
+		_key: string,
+		_maid: Maid.Maid?,
+		_gamepadRotateModel: GamepadRotateModel.GamepadRotateModel,
+		_lastMousePosition: Vector3?,
+		_mouseSensitivity: Vector2,
+		_gamepadSensitivity: number,
+	},
+	{} :: typeof({ __index = ConstrainedLookControls })
+))
+
+--[=[
+	Constructs a new ConstrainedLookControls bound to the given camera.
+]=]
+function ConstrainedLookControls.new(camera: ConstrainedLookCamera.ConstrainedLookCamera): ConstrainedLookControls
+	local self: ConstrainedLookControls = setmetatable({} :: any, ConstrainedLookControls)
+
+	self._camera = assert(camera, "Bad camera")
+	self._enabled = false
+	self._key = tostring(self) .. "ConstrainedLookControls"
+	self._mouseSensitivity = ConstrainedLookControls.MOUSE_SENSITIVITY
+	self._gamepadSensitivity = ConstrainedLookControls.GAMEPAD_SENSITIVITY
+	self._gamepadRotateModel = GamepadRotateModel.new()
+
+	return self
+end
+
+--[=[
+	Sets mouse sensitivity.
+]=]
+function ConstrainedLookControls.SetMouseSensitivity(self: ConstrainedLookControls, sensitivity: Vector2)
+	self._mouseSensitivity = sensitivity
+end
+
+--[=[
+	Sets gamepad sensitivity.
+]=]
+function ConstrainedLookControls.SetGamepadSensitivity(self: ConstrainedLookControls, sensitivity: number)
+	self._gamepadSensitivity = sensitivity
+end
+
+--[=[
+	Returns whether controls are enabled.
+]=]
+function ConstrainedLookControls.IsEnabled(self: ConstrainedLookControls): boolean
+	return self._enabled
+end
+
+--[=[
+	Enables input. Binds drag (MouseButton2 / Touch) and gamepad Thumbstick2.
+]=]
+function ConstrainedLookControls.Enable(self: ConstrainedLookControls)
+	if self._enabled then
+		return
+	end
+	assert(not self._maid, "Maid already defined")
+	self._enabled = true
+
+	local maid = Maid.new()
+	self._maid = maid
+
+	maid:GiveTask(self._gamepadRotateModel.IsRotating.Changed:Connect(function()
+		if self._gamepadRotateModel.IsRotating.Value then
+			self:_handleGamepadRotateStart()
+		else
+			self:_handleGamepadRotateStop()
+		end
+	end))
+
+	ContextActionService:BindAction(self._key .. "Drag", function(_, userInputState, inputObject)
+		if userInputState == Enum.UserInputState.Begin then
+			self:_beginDrag(inputObject)
+		end
+		return Enum.ContextActionResult.Pass
+	end, false, unpack(self._dragBeginTypes))
+
+	ContextActionService:BindAction(self._key .. "Rotate", function(_, _, inputObject)
+		self._gamepadRotateModel:HandleThumbstickInput(inputObject)
+		return Enum.ContextActionResult.Pass
+	end, false, Enum.KeyCode.Thumbstick2)
+
+	maid:GiveTask(function()
+		ContextActionService:UnbindAction(self._key .. "Drag")
+		ContextActionService:UnbindAction(self._key .. "Rotate")
+	end)
+
+	maid:GiveTask(function()
+		self._camera:Release()
+	end)
+end
+
+--[=[
+	Disables input and releases the camera.
+]=]
+function ConstrainedLookControls.Disable(self: ConstrainedLookControls)
+	if not self._enabled then
+		return
+	end
+	assert(self._maid, "Must be enabled")
+	self._enabled = false
+
+	self._maid:DoCleaning()
+	self._maid = nil
+	self._lastMousePosition = nil
+end
+
+function ConstrainedLookControls._beginDrag(self: ConstrainedLookControls, beginInputObject: InputObject)
+	assert(self._maid, "Must be enabled")
+
+	local maid = Maid.new()
+	self._lastMousePosition = beginInputObject.Position
+
+	local isMouse = InputObjectUtils.isMouseUserInputType(beginInputObject.UserInputType)
+	if isMouse then
+		UserInputService.MouseBehavior = Enum.MouseBehavior.LockCurrentPosition
+		maid:GiveTask(function()
+			UserInputService.MouseBehavior = Enum.MouseBehavior.Default
+		end)
+	end
+
+	maid:GiveTask(UserInputService.InputEnded:Connect(function(inputObject: InputObject)
+		if inputObject == beginInputObject then
+			self:_endDrag()
+		end
+	end))
+
+	maid:GiveTask(UserInputService.InputChanged:Connect(function(inputObject: InputObject)
+		if InputObjectUtils.isMouseUserInputType(inputObject.UserInputType) or inputObject == beginInputObject then
+			self:_handleDragMovement(inputObject)
+		end
+	end))
+
+	maid:GiveTask(function()
+		self._lastMousePosition = nil
+		self._camera:Release()
+	end)
+
+	self._maid._dragMaid = maid
+end
+
+function ConstrainedLookControls._endDrag(self: ConstrainedLookControls)
+	assert(self._maid, "Must be enabled")
+	self._maid._dragMaid = nil
+end
+
+function ConstrainedLookControls._handleDragMovement(self: ConstrainedLookControls, inputObject: InputObject)
+	if not self._lastMousePosition then
+		return
+	end
+
+	local delta = -inputObject.Delta
+	if InputObjectUtils.isMouseUserInputType(inputObject.UserInputType) then
+		delta += self._lastMousePosition - inputObject.Position
+	end
+
+	local xTheta = delta.X / 1920
+	local yTheta = delta.Y / 1200
+	local deltaAngle = Vector2.new(xTheta, yTheta) * self._mouseSensitivity
+	self._camera:RotateXY(deltaAngle)
+
+	self._lastMousePosition = inputObject.Position
+end
+
+function ConstrainedLookControls._handleGamepadRotateStart(self: ConstrainedLookControls)
+	assert(self._maid, "Must be enabled")
+
+	local maid = Maid.new()
+
+	maid:GiveTask(RunService.Stepped:Connect(function()
+		local deltaAngle = self._gamepadSensitivity * self._gamepadRotateModel:GetThumbstickDeltaAngle()
+		self._camera:RotateXY(deltaAngle)
+	end))
+
+	maid:GiveTask(function()
+		self._camera:Release()
+	end)
+
+	self._maid._dragMaid = maid
+end
+
+function ConstrainedLookControls._handleGamepadRotateStop(self: ConstrainedLookControls)
+	assert(self._maid, "Must be enabled")
+	self._maid._dragMaid = nil
+end
+
+function ConstrainedLookControls.Destroy(self: ConstrainedLookControls)
+	self:Disable()
+	self._gamepadRotateModel:Destroy()
+	setmetatable(self :: any, nil)
+end
+
+return ConstrainedLookControls

package/src/Client/Effects/ConstrainedLookCamera.lua

@@ -0,0 +1,143 @@
+--!strict
+--[=[
+	Constrains pitch and yaw within a cone.
+
+	@class ConstrainedLookCamera
+]=]
+
+local require = require(script.Parent.loader).load(script)
+
+local CameraEffectUtils = require("CameraEffectUtils")
+local CameraState = require("CameraState")
+local Spring = require("Spring")
+local SummedCamera = require("SummedCamera")
+
+local ConstrainedLookCamera = {}
+ConstrainedLookCamera.ClassName = "ConstrainedLookCamera"
+
+export type ConstrainedLookCamera =
+	typeof(setmetatable(
+		{} :: {
+			CameraState: CameraState.CameraState,
+			CFrame: CFrame,
+			AngleYaw: number,
+			AnglePitch: number,
+			TargetAngleYaw: number,
+			TargetAnglePitch: number,
+			MaxYawOffset: number,
+			MaxPitchOffset: number,
+			Speed: number,
+			SpeedYaw: number,
+			SpeedPitch: number,
+			Damper: number,
+			SpringYaw: Spring.Spring<number>,
+			SpringPitch: Spring.Spring<number>,
+		},
+		{} :: typeof({ __index = ConstrainedLookCamera })
+	))
+	& CameraEffectUtils.CameraEffect
+
+ConstrainedLookCamera._maxYawOffset = math.rad(20)
+ConstrainedLookCamera._maxPitchOffset = math.rad(15)
+
+--[=[
+	Constructs a new ConstrainedLookCamera.
+]=]
+function ConstrainedLookCamera.new(): ConstrainedLookCamera
+	local self: ConstrainedLookCamera = setmetatable({} :: any, ConstrainedLookCamera)
+
+	self.SpringYaw = Spring.new(0)
+	self.SpringPitch = Spring.new(0)
+	self.Speed = 15
+	self.Damper = 1
+
+	return self
+end
+
+function ConstrainedLookCamera.__add(self: ConstrainedLookCamera, other: CameraEffectUtils.CameraEffect)
+	return SummedCamera.new(self, other)
+end
+
+--[=[
+	Rotates the target yaw (X) and pitch (Y) by the given delta, clamped within the max offsets.
+]=]
+function ConstrainedLookCamera.RotateXY(self: ConstrainedLookCamera, delta: Vector2)
+	self.TargetAngleYaw += delta.X
+	self.TargetAnglePitch += delta.Y
+end
+
+--[=[
+	Releases input, sending spring targets back to the origin.
+]=]
+function ConstrainedLookCamera.Release(self: ConstrainedLookCamera)
+	self.TargetAngleYaw = 0
+	self.TargetAnglePitch = 0
+end
+
+--[=[
+	Snaps springs to the origin without animating.
+]=]
+function ConstrainedLookCamera.SnapToOrigin(self: ConstrainedLookCamera)
+	self.SpringYaw:SetTarget(0, true)
+	self.SpringPitch:SetTarget(0, true)
+end
+
+function ConstrainedLookCamera.__newindex(self: ConstrainedLookCamera, index, value)
+	if index == "AngleYaw" then
+		self.SpringYaw.Position = math.clamp(value, -self.MaxYawOffset, self.MaxYawOffset)
+	elseif index == "AnglePitch" then
+		self.SpringPitch.Position = math.clamp(value, -self.MaxPitchOffset, self.MaxPitchOffset)
+	elseif index == "TargetAngleYaw" then
+		self.SpringYaw.Target = math.clamp(value, -self.MaxYawOffset, self.MaxYawOffset)
+	elseif index == "TargetAnglePitch" then
+		self.SpringPitch.Target = math.clamp(value, -self.MaxPitchOffset, self.MaxPitchOffset)
+	elseif index == "MaxYawOffset" then
+		assert(value >= 0, "MaxYawOffset must be non-negative")
+		self._maxYawOffset = value
+		self.TargetAngleYaw = self.SpringYaw.Target
+	elseif index == "MaxPitchOffset" then
+		assert(value >= 0, "MaxPitchOffset must be non-negative")
+		self._maxPitchOffset = value
+		self.TargetAnglePitch = self.SpringPitch.Target
+	elseif index == "SpeedYaw" then
+		self.SpringYaw.Speed = value
+	elseif index == "SpeedPitch" then
+		self.SpringPitch.Speed = value
+	elseif index == "Speed" then
+		self.SpringYaw.Speed = value
+		self.SpringPitch.Speed = value
+	elseif index == "Damper" then
+		self.SpringYaw.Damper = value
+		self.SpringPitch.Damper = value
+	elseif ConstrainedLookCamera[index] ~= nil or index == "SpringYaw" or index == "SpringPitch" then
+		rawset(self, index, value)
+	else
+		error(`{tostring(index)} is not a valid member of ConstrainedLookCamera`)
+	end
+end
+
+function ConstrainedLookCamera.__index(self: ConstrainedLookCamera, index)
+	if index == "CameraState" then
+		local state = CameraState.new()
+		state.CFrame = self.CFrame
+		return state
+	elseif index == "CFrame" then
+		return CFrame.Angles(0, self.AngleYaw, 0) * CFrame.Angles(self.AnglePitch, 0, 0)
+	elseif index == "AngleYaw" then
+		return self.SpringYaw.Position
+	elseif index == "AnglePitch" then
+		return self.SpringPitch.Position
+	elseif index == "TargetAngleYaw" then
+		return self.SpringYaw.Target
+	elseif index == "TargetAnglePitch" then
+		return self.SpringPitch.Target
+	elseif index == "MaxYawOffset" then
+		return self._maxYawOffset
+	elseif index == "MaxPitchOffset" then
+		return self._maxPitchOffset
+	else
+		return ConstrainedLookCamera[index]
+	end
+end
+
+return ConstrainedLookCamera