@quenty/camera 14.40.0 → 14.41.0

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [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
+
 # [14.40.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/camera@14.39.0...@quenty/camera@14.40.0) (2026-05-29)
 
 **Note:** Version bump only for package @quenty/camera

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/camera",
-  "version": "14.40.0",
+  "version": "14.41.0",
   "description": "Quenty's camera system for Roblox",
   "keywords": [
     "Roblox",
@@ -31,27 +31,27 @@
     "@quenty/acceltween": "2.7.0",
     "@quenty/baseobject": "10.13.0",
     "@quenty/cframeutils": "5.5.6",
-    "@quenty/cubicspline": "10.12.0",
-    "@quenty/draw": "7.14.0",
+    "@quenty/cubicspline": "10.12.1",
+    "@quenty/draw": "7.14.1",
     "@quenty/ducktype": "5.11.0",
-    "@quenty/inputobjectutils": "4.30.0",
+    "@quenty/inputobjectutils": "4.30.1",
     "@quenty/loader": "10.11.0",
     "@quenty/maid": "3.9.0",
     "@quenty/math": "2.7.5",
     "@quenty/nevermore-test-runner": "1.4.0",
-    "@quenty/qframe": "10.22.0",
-    "@quenty/rx": "13.28.2",
-    "@quenty/servicebag": "11.18.0",
+    "@quenty/qframe": "10.22.1",
+    "@quenty/rx": "13.28.3",
+    "@quenty/servicebag": "11.18.1",
     "@quenty/spring": "10.12.0",
-    "@quenty/valueobject": "13.31.0",
+    "@quenty/valueobject": "13.31.1",
     "@quenty/vector3utils": "10.11.0",
     "@quentystudios/jest-lua": "3.10.0-quenty.2"
   },
   "devDependencies": {
-    "@quenty/camerastoryutils": "10.21.0"
+    "@quenty/camerastoryutils": "10.21.1"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "f4a374a0a294ee8900aa5cb68ab138b0acf3e0ae"
+  "gitHead": "75291c76133c2b87b71c620125800dd3d72b7fe1"
 }

package/src/Client/CameraStack.lua

@@ -76,7 +76,7 @@ function CameraStack.PrintCameraStack(self: CameraStack): ()
 end
 
 --[=[
-	Gets the camera current on the top of the stack
+	Gets the camera currently on the top of the stack
 	@return CameraEffect
 ]=]
 function CameraStack.GetTopCamera(self: CameraStack): CameraEffectUtils.CameraLike

package/src/Client/CameraStackService.lua

@@ -1,7 +1,7 @@
 --!nonstrict
 --[=[
 	Holds camera states and allows for the last camera state to be retrieved. Also
-	initializes an impulse and default camera as the bottom of the stack. Is a singleton.
+	initializes an impulse and default camera at the bottom of the stack. Is a singleton.
 
 	@class CameraStackService
 ]=]
@@ -173,7 +173,7 @@ function CameraStackService.GetRawDefaultCamera(self: CameraStackService): Defau
 end
 
 --[=[
-	Gets the camera current on the top of the stack
+	Gets the camera currently on the top of the stack
 	@return CameraEffect
 ]=]
 function CameraStackService.GetTopCamera(self: CameraStackService): CameraEffectUtils.CameraLike

package/src/Client/Controls/ConstrainedLookControls.lua

@@ -0,0 +1,220 @@
+--!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
+	end, false, unpack(self._dragBeginTypes))
+
+	ContextActionService:BindAction(self._key .. "Rotate", function(_, _, inputObject)
+		self._gamepadRotateModel:HandleThumbstickInput(inputObject)
+	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

package/src/Client/Effects/DefaultCamera.lua

@@ -1,6 +1,6 @@
 --!strict
 --[=[
-	Hack to maintain default camera control by binding before and after the camera update cycle
+	Hack to maintain default camera control by binding before and after the camera update cycle.
 	This allows other cameras to build off of the "default" camera while maintaining the same Roblox control scheme.
 
 	This camera is automatically setup by the [CameraStackService](/api/CameraStackService).

package/src/Client/Effects/ZoomedCamera.lua

@@ -1,8 +1,8 @@
 --!strict
 --[=[
 	Allow freedom of movement around a current place, much like the classic script works now.
-	Not intended to be use with the current character script
-	Intended to be used with a SummedCamera, relative.
+	Not intended to be used with the current character script.
+	Intended to be used with a [SummedCamera], relative.
 
 	```lua
 	local zoom = ZoomedCamera.new()

package/src/Client/Utility/CameraStateTweener.lua

@@ -1,8 +1,8 @@
 --!strict
 --[=[
 	Makes transitions between states easier. Uses the `CameraStackService` to tween in and
-	out a new camera state Call `:Show()` and `:Hide()` to do so, and make sure to
-	call `:Destroy()` after usage
+	out a new camera state. Call `:Show()` and `:Hide()` to do so, and make sure to
+	call `:Destroy()` after usage.
 
 	@class CameraStateTweener
 ]=]
@@ -89,7 +89,7 @@ end
 
 --[=[
 	Shows the camera to fade in.
-	@param doNotAnimate? boolean -- Optional, defaults to animating
+	@param doNotAnimate boolean? -- Optional, defaults to animating
 ]=]
 function CameraStateTweener.Show(self: CameraStateTweener, doNotAnimate: boolean?)
 	self:SetTarget(1, doNotAnimate)
@@ -97,7 +97,7 @@ end
 
 --[=[
 	Hides the camera to fade in.
-	@param doNotAnimate? boolean -- Optional, defaults to animating
+	@param doNotAnimate boolean? -- Optional, defaults to animating
 ]=]
 function CameraStateTweener.Hide(self: CameraStateTweener, doNotAnimate: boolean?)
 	self:SetTarget(0, doNotAnimate)
@@ -158,6 +158,10 @@ function CameraStateTweener.GetCameraBelow(self: CameraStateTweener): CameraEffe
 	return self._cameraBelow
 end
 
+--[=[
+	Sets the epsilon to stop animating
+	@param epsilon number?
+]=]
 function CameraStateTweener:SetEpsilon(epsilon: number?)
 	self._fadeBetween.Epsilon = epsilon
 end