@quenty/camera 4.4.0 → 5.0.1-canary.238.2c4d310.0

package/src/Client/Utility/CameraFrame.lua

@@ -1,6 +1,7 @@
----
--- @classmod CameraFrame
--- @author Quenty
+--[=[
+	Represents a camera state at a certain point. Can perform math on this state.
+	@class CameraFrame
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -10,6 +11,12 @@ local CameraFrame = {}
 CameraFrame.ClassName = "CameraFrame"
 CameraFrame.__index = CameraFrame
 
+--[=[
+	Constructs a new CameraFrame
+	@param qFrame QFrame
+	@param fieldOfView number
+	@return CameraFrame
+]=]
 function CameraFrame.new(qFrame, fieldOfView)
 	local self = setmetatable({}, CameraFrame)
 
@@ -19,10 +26,40 @@ function CameraFrame.new(qFrame, fieldOfView)
 	return self
 end
 
+--[=[
+	Returns whether a value is a CameraFrame
+	@param value any
+	@return boolean
+]=]
 function CameraFrame.isCameraFrame(value)
 	return getmetatable(value) == CameraFrame
 end
 
+--[=[
+	@prop CFrame CFrame
+	@within CameraFrame
+]=]
+
+--[=[
+	@prop Position Vector3
+	@within CameraFrame
+]=]
+
+--[=[
+	@prop FieldOfView number
+	@within CameraFrame
+]=]
+
+--[=[
+	@prop QFrame QFrame
+	@within CameraFrame
+]=]
+
+--[=[
+	@prop QFrame QFrame
+	@within CameraFrame
+]=]
+
 function CameraFrame:__index(index)
 	if index == "CFrame" then
 		return QFrame.toCFrame(self.QFrame) or warn("[CameraFrame] - NaN")
@@ -48,13 +85,19 @@ function CameraFrame:__newindex(index, value)
 
 		local q = self.QFrame
 		rawset(self, "QFrame", QFrame.new(value.x, value.y, value.z, q.W, q.X, q.Y, q.Z))
-	elseif index == "FieldOfView" or index == "QFrame" or index == "QFrameDerivative" then
+	elseif index == "FieldOfView" or index == "QFrame" then
 		rawset(self, index, value)
 	else
 		error(("'%s' is not a valid index of CameraState"):format(tostring(index)))
 	end
 end
 
+--[=[
+	Linearly adds the camera frames together.
+	@param a CameraFrame
+	@param b CameraFrame
+	@return CameraFrame
+]=]
 function CameraFrame.__add(a, b)
 	assert(CameraFrame.isCameraFrame(a) and CameraFrame.isCameraFrame(b),
 		"CameraFrame + non-CameraFrame attempted")
@@ -62,6 +105,12 @@ function CameraFrame.__add(a, b)
 	return CameraFrame.new(a.QFrame + b.QFrame, a.FieldOfView + b.FieldOfView)
 end
 
+--[=[
+	Linearly subtractions the camera frames together.
+	@param a CameraFrame
+	@param b CameraFrame
+	@return CameraFrame
+]=]
 function CameraFrame.__sub(a, b)
 	assert(CameraFrame.isCameraFrame(a) and CameraFrame.isCameraFrame(b),
 		"CameraFrame - non-CameraFrame attempted")
@@ -69,10 +118,21 @@ function CameraFrame.__sub(a, b)
 	return CameraFrame.new(a.QFrame - b.QFrame, a.FieldOfView - b.FieldOfView)
 end
 
+--[=[
+	Inverts the QFrame and the field of view.
+	@param a CameraFrame
+	@return CameraFrame
+]=]
 function CameraFrame.__unm(a)
 	return CameraFrame.new(-a.QFrame, -a.FieldOfView)
 end
 
+--[=[
+	Multiplies the camera frame with the given value
+	@param a CameraFrame | number
+	@param b CameraFrame | number
+	@return CameraFrame
+]=]
 function CameraFrame.__mul(a, b)
 	if type(a) == "number" and CameraFrame.isCameraFrame(b) then
 		return CameraFrame.new(a*b.QFrame, a*b.FieldOfView)
@@ -85,6 +145,12 @@ function CameraFrame.__mul(a, b)
 	end
 end
 
+--[=[
+	Divides the camera frame by the value
+	@param a CameraFrame
+	@param b number
+	@return CameraFrame
+]=]
 function CameraFrame.__div(a, b)
 	if CameraFrame.isCameraFrame(a) and type(b) == "number" then
 		return CameraFrame.new(a.QFrame/b, a.FieldOfView/b)
@@ -93,6 +159,12 @@ function CameraFrame.__div(a, b)
 	end
 end
 
+--[=[
+	Takes the camera frame to the Nth power
+	@param a CameraFrame
+	@param b number
+	@return CameraFrame
+]=]
 function CameraFrame.__pow(a, b)
 	if CameraFrame.isCameraFrame(a) and type(b) == "number" then
 		return CameraFrame.new(a.QFrame^b, a.FieldOfView^b)
@@ -101,6 +173,12 @@ function CameraFrame.__pow(a, b)
 	end
 end
 
+--[=[
+	Compares the camera frame to make sure they're equal
+	@param a CameraFrame
+	@param b CameraFrame
+	@return boolean
+]=]
 function CameraFrame.__eq(a, b)
 	return a.QFrame == b.QFrame and a.FieldOfView == b.FieldOfView
 end

package/src/Client/Utility/CameraFrame.story.lua

@@ -1,6 +1,6 @@
----
--- @module CameraFrame.story
--- @author Quenty
+--[[
+	@class CameraFrame.story
+]]
 
 local require = require(game:GetService("ServerScriptService"):FindFirstChild("LoaderUtils", true).Parent).load(script)
 

package/src/Client/Utility/CameraStateTweener.lua

@@ -1,7 +1,10 @@
---- 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
--- @classmod CameraStateTweener
+--[=[
+	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
+
+	@class CameraStateTweener
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -14,9 +17,14 @@ local CameraStateTweener = {}
 CameraStateTweener.ClassName = "CameraStateTweener"
 CameraStateTweener.__index = CameraStateTweener
 
---- Constructs a new camera state tweener
--- @tparam ICameraEffect cameraEffect A camera effect
--- @tparam[opt=20] number speed that the camera tweener tweens at
+--[=[
+	Constructs a new camera state tweener
+
+	@param serviceBag ServiceBag -- Service bag to find the CameraStackService in
+	@param cameraEffect CameraLike -- A camera effect
+	@param speed number? -- Speed that the camera tweener tweens at. Defaults to 20
+	@return CameraStateTweener
+]=]
 function CameraStateTweener.new(serviceBag, cameraEffect, speed)
 	local self = setmetatable({}, CameraStateTweener)
 
@@ -46,29 +54,51 @@ function CameraStateTweener.new(serviceBag, cameraEffect, speed)
 	return self
 end
 
+--[=[
+	Returns percent visible, from 0 to 1.
+	@return number
+]=]
 function CameraStateTweener:GetPercentVisible()
 	return self._fadeBetween.Value
 end
 
+--[=[
+	Shows the camera to fade in.
+	@param doNotAnimate? boolean -- Optional, defaults to animating
+]=]
 function CameraStateTweener:Show(doNotAnimate)
 	self:SetTarget(1, doNotAnimate)
 end
 
+--[=[
+	Hides the camera to fade in.
+	@param doNotAnimate? boolean -- Optional, defaults to animating
+]=]
 function CameraStateTweener:Hide(doNotAnimate)
 	self:SetTarget(0, doNotAnimate)
 end
 
+--[=[
+	Returns true if we're done hiding
+	@return boolean
+]=]
 function CameraStateTweener:IsFinishedHiding()
 	return self._fadeBetween.HasReachedTarget and self._fadeBetween.Target == 0
 end
 
+--[=[
+	Hides the tweener, and invokes the callback once the tweener
+	is finished hiding.
+	@param doNotAnimate boolean? -- Optional, defaults to animating
+	@param callback function
+]=]
 function CameraStateTweener:Finish(doNotAnimate, callback)
 	self:Hide(doNotAnimate)
 
 	if self._fadeBetween.HasReachedTarget then
 		callback()
 	else
-		spawn(function()
+		task.spawn(function()
 			while not self._fadeBetween.HasReachedTarget do
 				task.wait(0.05)
 			end
@@ -77,14 +107,28 @@ function CameraStateTweener:Finish(doNotAnimate, callback)
 	end
 end
 
+--[=[
+	Gets the current effect we're tweening
+	@return CameraEffect
+]=]
 function CameraStateTweener:GetCameraEffect()
 	return self._cameraEffect
 end
 
+--[=[
+	Gets the camera below this camera on the camera stack
+	@return CameraEffect
+]=]
 function CameraStateTweener:GetCameraBelow()
 	return self._cameraBelow
 end
 
+--[=[
+	Sets the percent visible target
+	@param target number
+	@param doNotAnimate boolean? -- Optional, defaults to animating
+	@return CameraStateTweener -- self
+]=]
 function CameraStateTweener:SetTarget(target, doNotAnimate)
 	self._fadeBetween.Target = target or error("No target")
 	if doNotAnimate then
@@ -94,12 +138,22 @@ function CameraStateTweener:SetTarget(target, doNotAnimate)
 	return self
 end
 
+--[=[
+	Sets the speed of transition
+	@param speed number
+	@return CameraStateTweener -- self
+]=]
 function CameraStateTweener:SetSpeed(speed)
 	self._fadeBetween.Speed = speed
 
 	return self
 end
 
+--[=[
+	Sets whether the tweener is visible
+	@param isVisible boolean
+	@param doNotAnimate boolean? -- Optional, defaults to animating
+]=]
 function CameraStateTweener:SetVisible(isVisible, doNotAnimate)
 	if isVisible then
 		self:Show(doNotAnimate)
@@ -108,10 +162,17 @@ function CameraStateTweener:SetVisible(isVisible, doNotAnimate)
 	end
 end
 
+--[=[
+	Retrieves the fading camera being used to interpolate.
+	@return CameraEffect
+]=]
 function CameraStateTweener:GetFader()
 	return self._fadeBetween
 end
 
+--[=[
+	Cleans up the fader, preventing any animation at all
+]=]
 function CameraStateTweener:Destroy()
 	self._maid:DoCleaning()
 	setmetatable(self, nil)

package/src/Client/Utility/FieldOfViewUtils.lua

@@ -1,6 +1,7 @@
----
--- @module FieldOfViewUtils
--- @author Quenty
+--[=[
+	Utility functions involving field of view.
+	@class FieldOfViewUtils
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -8,15 +9,30 @@ local Math = require("Math")
 
 local FieldOfViewUtils = {}
 
+--[=[
+	Converts field of view to height
+	@param fov number
+	@return number
+]=]
 function FieldOfViewUtils.fovToHeight(fov)
     return 2*math.tan(math.rad(fov)/2)
 end
 
+--[=[
+	Converts height to field of view
+	@param height number
+	@return number
+]=]
 function FieldOfViewUtils.heightToFov(height)
     return 2*math.deg(math.atan(height/2))
 end
 
-
+--[=[
+	Linear way to log a value so we don't get floating point errors or infinite values
+	@param height number
+	@param linearAt number
+	@return number
+]=]
 function FieldOfViewUtils.safeLog(height, linearAt)
 	if height < linearAt then
 		local slope = 1/linearAt
@@ -26,6 +42,13 @@ function FieldOfViewUtils.safeLog(height, linearAt)
 	end
 end
 
+--[=[
+	Linear way to exponentiate field of view so we don't get floating point errors or
+	infinite values.
+	@param logHeight number
+	@param linearAt number
+	@return number
+]=]
 function FieldOfViewUtils.safeExp(logHeight, linearAt)
 	local transitionAt = math.log(linearAt)
 
@@ -36,6 +59,13 @@ function FieldOfViewUtils.safeExp(logHeight, linearAt)
 	end
 end
 
+--[=[
+	Interpolates field of view in height space, instead of degrees.
+	@param fov0 number
+	@param fov1 number
+	@param percent number
+	@return number -- Fov in degrees
+]=]
 function FieldOfViewUtils.lerpInHeightSpace(fov0, fov1, percent)
 	local height0 = FieldOfViewUtils.fovToHeight(fov0)
 	local height1 = FieldOfViewUtils.fovToHeight(fov1)