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

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [5.0.1-canary.238.2c4d310.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/camera@5.0.0...@quenty/camera@5.0.1-canary.238.2c4d310.0) (2021-12-29)
+
+**Note:** Version bump only for package @quenty/camera
+
+
+
+
+
+# [5.0.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/camera@4.4.0...@quenty/camera@5.0.0) (2021-12-22)
+
+**Note:** Version bump only for package @quenty/camera
+
+
+
+
+
 # [4.4.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/camera@4.3.1...@quenty/camera@4.4.0) (2021-12-18)
 
 

package/README.md

@@ -1,10 +1,10 @@
 ## Camera
 <div align="center">
-  <a href="http://quenty.github.io/api/">
+  <a href="http://quenty.github.io/NevermoreEngine/">
     <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
   </a>
   <a href="https://discord.gg/mhtGUS8">
-    <img src="https://img.shields.io/badge/discord-nevermore-blue.svg" alt="Discord" />
+    <img src="https://img.shields.io/discord/385151591524597761?color=5865F2&label=discord&logo=discord&logoColor=white" alt="Discord" />
   </a>
   <a href="https://github.com/Quenty/NevermoreEngine/actions">
     <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/build.yml/badge.svg" alt="Build and release status" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/camera",
-  "version": "4.4.0",
+  "version": "5.0.1-canary.238.2c4d310.0",
   "description": "Quenty's camera system for Roblox",
   "keywords": [
     "Roblox",
@@ -25,23 +25,23 @@
     "Quenty"
   ],
   "dependencies": {
-    "@quenty/acceltween": "^2.0.0",
-    "@quenty/baseobject": "^3.2.0",
-    "@quenty/cframeutils": "^2.0.0",
-    "@quenty/cubicspline": "^3.2.0",
-    "@quenty/inputobjectutils": "^2.0.1",
-    "@quenty/loader": "^3.1.1",
-    "@quenty/maid": "^2.0.1",
-    "@quenty/math": "^2.0.0",
-    "@quenty/qframe": "^3.3.0",
-    "@quenty/servicebag": "^3.2.1",
-    "@quenty/spring": "^2.2.0"
+    "@quenty/acceltween": "2.0.1-canary.238.2c4d310.0",
+    "@quenty/baseobject": "3.2.1-canary.238.2c4d310.0",
+    "@quenty/cframeutils": "2.0.1-canary.238.2c4d310.0",
+    "@quenty/cubicspline": "3.2.1-canary.238.2c4d310.0",
+    "@quenty/inputobjectutils": "2.0.2-canary.238.2c4d310.0",
+    "@quenty/loader": "3.1.2-canary.238.2c4d310.0",
+    "@quenty/maid": "2.0.2-canary.238.2c4d310.0",
+    "@quenty/math": "2.0.1-canary.238.2c4d310.0",
+    "@quenty/qframe": "3.3.1-canary.238.2c4d310.0",
+    "@quenty/servicebag": "3.2.2-canary.238.2c4d310.0",
+    "@quenty/spring": "3.0.1-canary.238.2c4d310.0"
   },
   "devDependencies": {
-    "@quenty/camerastoryutils": "^3.3.0"
+    "@quenty/camerastoryutils": "3.3.1-canary.238.2c4d310.0"
   },
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6eb398e9fb81191f0815885f807ab0cb3bb9bad1"
+  "gitHead": "2c4d310b84afd0570d89667dc5d4aa69a0ef304a"
 }

package/src/Client/CameraStackService.lua

@@ -1,6 +1,9 @@
---- 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.
--- @module CameraStackService
+--[=[
+	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.
+
+	@class CameraStackService
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -17,6 +20,10 @@ assert(RunService:IsClient(), "[CameraStackService] - Only require CameraStackSe
 
 local CameraStackService = {}
 
+--[=[
+	Initializes a new camera stack. Should be done via the ServiceBag.
+	@param serviceBag ServiceBag
+]=]
 function CameraStackService:Init(serviceBag)
 	assert(ServiceBag.isServiceBag(serviceBag), "Not a valid service bag")
 
@@ -58,12 +65,20 @@ function CameraStackService:Init(serviceBag)
 	end)
 end
 
+--[=[
+	Prevents the default camera from being used
+	@param doNotUseDefaultCamera boolean
+]=]
 function CameraStackService:SetDoNotUseDefaultCamera(doNotUseDefaultCamera)
 	assert(not self._stack, "Already initialized")
 
 	self._doNotUseDefaultCamera = doNotUseDefaultCamera
 end
 
+--[=[
+	Pushes a disable state onto the camera stack
+	@return function -- Function to cancel disable
+]=]
 function CameraStackService:PushDisable()
 	assert(self._stack, "Not initialized")
 
@@ -76,8 +91,9 @@ function CameraStackService:PushDisable()
 	end
 end
 
---- Outputs the camera stack
--- @treturn nil
+--[=[
+	Outputs the camera stack. Intended for diagnostics.
+]=]
 function CameraStackService:PrintCameraStack()
 	assert(self._stack, "Stack is not initialized yet")
 
@@ -86,39 +102,65 @@ function CameraStackService:PrintCameraStack()
 	end
 end
 
---- Returns the default camera
--- @treturn SummedCamera DefaultCamera + ImpulseCamera
+--[=[
+	Returns the default camera
+	@return SummedCamera -- DefaultCamera + ImpulseCamera
+]=]
 function CameraStackService:GetDefaultCamera()
 	assert(self._defaultCamera, "Not initialized")
 
 	return self._defaultCamera
 end
 
---- Returns the impulse camera. Useful for adding camera shake
--- @treturn ImpulseCamera
+--[=[
+	Returns the impulse camera. Useful for adding camera shake.
+
+	Shaking the camera:
+	```lua
+	self._cameraStackService:GetImpulseCamera():Impulse(Vector3.new(0.25, 0, 0.25*(math.random()-0.5)))
+	```
+
+	You can also sum the impulse camera into another effect to layer the shake on top of the effect
+	as desired.
+
+	```lua
+	-- Adding global custom camera shake to a custom camera effect
+	local customCameraEffect = ...
+	return (customCameraEffect + self._cameraStackService:GetImpulseCamera()):SetMode("Relative")
+	```
+
+	@return ImpulseCamera
+]=]
 function CameraStackService:GetImpulseCamera()
 	assert(self._impulseCamera, "Not initialized")
 
 	return self._impulseCamera
 end
 
---- Returns the default camera without any impulse cameras
--- @treturn DefaultCamera
+--[=[
+	Returns the default camera without any impulse cameras
+	@return DefaultCamera
+]=]
 function CameraStackService:GetRawDefaultCamera()
 	assert(self._rawDefaultCamera, "Not initialized")
 
 	return self._rawDefaultCamera
 end
 
+--[=[
+	Gets the camera current on the top of the stack
+	@return CameraEffect
+]=]
 function CameraStackService:GetTopCamera()
 	assert(self._stack, "Not initialized")
 
 	return self._stack[#self._stack]
 end
 
---- Retrieves the top state off the stack
--- @treturn[1] CameraState
--- @treturn[2] nil
+--[=[
+	Retrieves the top state off the stack at this time
+	@return CameraState?
+]=]
 function CameraStackService:GetTopState()
 	assert(self._stack, "Stack is not initialized yet")
 
@@ -139,9 +181,12 @@ function CameraStackService:GetTopState()
 	end
 end
 
---- Returns a new camera state that retrieves the state below its set state
--- @treturn[1] CustomCameraEffect
--- @treturn[1] NewStateToUse
+--[=[
+	Returns a new camera state that retrieves the state below its set state.
+
+	@return CustomCameraEffect -- Effect below
+	@return (CameraState) -> () -- Function to set the state
+]=]
 function CameraStackService:GetNewStateBelow()
 	assert(self._stack, "Stack is not initialized yet")
 
@@ -166,10 +211,12 @@ function CameraStackService:GetNewStateBelow()
 	end
 end
 
---- Retrieves the index of a state
--- @tparam CameraState state
--- @treturn number Index of state
--- @treturn nil If non on stack
+--[=[
+	Retrieves the index of a state
+	@param state CameraEffect
+	@return number? -- index
+
+]=]
 function CameraStackService:GetIndex(state)
 	assert(self._stack, "Stack is not initialized yet")
 
@@ -180,15 +227,25 @@ function CameraStackService:GetIndex(state)
 	end
 end
 
+--[=[
+	Returns the current stack.
+
+	:::warning
+	Do not modify this stack, this is the raw memory of the stack
+	:::
+
+	@return { CameraState<T> }
+]=]
 function CameraStackService:GetStack()
 	assert(self._stack, "Not initialized")
 
 	return self._stack
 end
 
---- Removes the state from the stack
--- @tparam CameraState state
--- @treturn nil
+--[=[
+	Removes the state from the stack
+	@param state CameraState
+]=]
 function CameraStackService:Remove(state)
 	assert(self._stack, "Stack is not initialized yet")
 
@@ -199,9 +256,10 @@ function CameraStackService:Remove(state)
 	end
 end
 
---- Adds a state to the stack
--- @tparam CameraState state
--- @treturn nil
+--[=[
+	Adds the state from the stack
+	@param state CameraState
+]=]
 function CameraStackService:Add(state)
 	assert(self._stack, "Stack is not initialized yet")
 

package/src/Client/CameraState.lua

@@ -1,5 +1,7 @@
---- Data container for the state of a camera.
--- @classmod CameraState
+--[=[
+	Data container for the state of a camera.
+	@class CameraState
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -9,14 +11,21 @@ local CameraFrame = require("CameraFrame")
 local CameraState = {}
 CameraState.ClassName = "CameraState"
 
+--[=[
+	Returns true if the result is a camera state
+	@param value any
+	@return boolean
+]=]
 function CameraState.isCameraState(value)
 	return getmetatable(value) == CameraState
 end
 
---- Builds a new camera stack
--- @constructor
--- @param[opt=nil] camera
--- @treturn CameraState
+--[=[
+	Constructs a new CameraState
+	@param cameraFrame CameraFrame | Camera
+	@param cameraFrameDerivative CameraFrame?
+	@return CameraState
+]=]
 function CameraState.new(cameraFrame, cameraFrameDerivative)
 	local self = setmetatable({}, CameraState)
 
@@ -36,6 +45,10 @@ function CameraState.new(cameraFrame, cameraFrameDerivative)
 	return self
 end
 
+--[=[
+	@prop cframe CFrame
+	@within CameraState
+]=]
 function CameraState:__index(index)
 	if index == "CFrame" then
 		return self.CameraFrame.CFrame
@@ -66,55 +79,10 @@ function CameraState:__newindex(index, value)
 	end
 end
 
--- function CameraState.__add(a, b)
--- 	assert(CameraState.isCameraState(a) and CameraState.isCameraState(b),
--- 		"CameraState + non-CameraState attempted")
-
--- 	return CameraState.new(a.QFrame + b.QFrame, a.FieldOfView + b.FieldOfView)
--- end
-
--- function CameraState.__sub(a, b)
--- 	assert(CameraState.isCameraState(a) and CameraState.isCameraState(b),
--- 		"CameraState - non-CameraState attempted")
-
--- 	return CameraState.new(a.QFrame - b.QFrame, a.FieldOfView - b.FieldOfView)
--- end
-
--- function CameraState.__unm(a)
--- 	return CameraState.new(-a.QFrame, -a.FieldOfView)
--- end
-
--- function CameraState.__mul(a, b)
--- 	if type(a) == "number" and CameraState.isCameraState(b) then
--- 		return CameraState.new(a*b.QFrame, a*b.FieldOfView)
--- 	elseif CameraState.isCameraState(b) and type(b) == "number" then
--- 		return CameraState.new(a.QFrame*b, a.FieldOfView*b)
--- 	elseif CameraState.isCameraState(a) and CameraState.isCameraState(b) then
--- 		return CameraState.new(a.QFrame*b.QFrame, a.FieldOfView*b.FieldOfView)
--- 	else
--- 		error("CameraState * non-CameraState attempted")
--- 	end
--- end
-
--- function CameraState.__div(a, b)
--- 	if CameraState.isCameraState(a) and type(b) == "number" then
--- 		return CameraState.new(a.QFrame/b, a.FieldOfView/b)
--- 	else
--- 		error("CameraState * non-CameraState attempted")
--- 	end
--- end
-
--- function CameraState.__pow(a, b)
--- 	if CameraState.isCameraState(a) and type(b) == "number" then
--- 		return CameraState.new(a.QFrame^b, a.FieldOfView^b)
--- 	else
--- 		error("CameraState ^ non-CameraState attempted")
--- 	end
--- end
-
---- Set another camera state. Typically used to set Workspace.CurrentCamera's state to match this camera's state
--- @tparam Camera camera A CameraState to set, also accepts a Roblox Camera
--- @treturn nil
+--[=[
+	Set another camera state. Typically used to set Workspace.CurrentCamera's state to match this camera's state
+	@param camera Camera -- A CameraState to set, also accepts a Roblox Camera
+]=]
 function CameraState:Set(camera)
 	camera.FieldOfView = self.FieldOfView
 	camera.CFrame = self.CFrame

package/src/Client/CameraUtils.lua

@@ -1,19 +1,60 @@
---- Utility methods for cameras
--- @module CameraUtils
+--[=[
+	Utility methods for cameras. These are great for viewport frames.
+
+	```lua
+	-- Sample viewport frame fitting of a model
+	local viewportFrame = ...
+	local camera = viewportFrame.CurrentCamera
+	local model = viewportFrame:FindFirstChildWhichIsA("Model")
+
+	RunService.RenderStepped:Connect(function()
+		local cframe, size = model:GetBoundingBox()
+		local size = viewportFrame.AbsoluteSize
+		local aspectRatio = size.x/size.y
+		local dist = CameraUtils.fitBoundingBoxToCamera(size, camera.FieldOfView, aspectRatio)
+		camera.CFrame = cframe.p + CFrame.Angles(0, math.pi*os.clock() % math.pi, -math.pi/8)
+			:vectorToWorldSpace(Vector3.new(0, 0, -dist))
+	end)
+	```
+
+	@class CameraUtils
+]=]
 
 local CameraUtils = {}
 
+--[=[
+	Computes the diameter of a cubeid
+
+	@param size Vector3
+	@return number
+]=]
 function CameraUtils.getCubeoidDiameter(size)
 	return math.sqrt(size.x^2 + size.y^2 + size.z^2)
 end
 
---- Use spherical bounding box to calculate how far back to move a camera
--- See: https://community.khronos.org/t/zoom-to-fit-screen/59857/12
+--[=[
+	Use spherical bounding box to calculate how far back to move a camera
+	See: https://community.khronos.org/t/zoom-to-fit-screen/59857/12
+
+	@param size Vector3 -- Size of the bounding box
+	@param fovDeg number -- Field of view in degrees (vertical)
+	@param aspectRatio number -- Aspect ratio of the screen
+	@return number -- Distance to move the camera back from the bounding box
+]=]
 function CameraUtils.fitBoundingBoxToCamera(size, fovDeg, aspectRatio)
 	local radius = CameraUtils.getCubeoidDiameter(size)/2
 	return CameraUtils.fitSphereToCamera(radius, fovDeg, aspectRatio)
 end
 
+--[=[
+	Fits a sphere to the camera, computing how far back to zoom the camera from
+	the center of the sphere.
+
+	@param radius number -- Radius of the sphere
+	@param fovDeg number -- Field of view in degrees (vertical)
+	@param aspectRatio number -- Aspect ratio of the screen
+	@return number -- Distance to move the camera back from the bounding box
+]=]
 function CameraUtils.fitSphereToCamera(radius, fovDeg, aspectRatio)
 	local halfFov = 0.5 * math.rad(fovDeg)
 	if aspectRatio < 1 then
@@ -23,6 +64,13 @@ function CameraUtils.fitSphereToCamera(radius, fovDeg, aspectRatio)
 	return radius / math.sin(halfFov)
 end
 
+--[=[
+	Checks if a position is on screen on a camera
+
+	@param camera Camera
+	@param position Vector3
+	@return boolean
+]=]
 function CameraUtils.isOnScreen(camera, position)
 	local _, onScreen = camera:WorldToScreenPoint(position)
 	return onScreen

package/src/Client/CameraUtils.story.lua

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

package/src/Client/Controls/CameraControls.lua

@@ -1,5 +1,7 @@
---- Interface between user input and camera controls
--- @classmod CameraControls
+--[=[
+	Interface between user input and camera controls
+	@class CameraControls
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -11,7 +13,7 @@ local Maid = require("Maid")
 local GamepadRotateModel = require("GamepadRotateModel")
 local InputObjectUtils = require("InputObjectUtils")
 
---- Stolen directly from ROBLOX's core scripts.
+-- Stolen directly from ROBLOX's core scripts.
 -- Looks like a simple integrator.
 -- Called (zoom, zoomScale, 1) returns zoom
 local function rk4Integrator(position, velocity, t)
@@ -175,7 +177,7 @@ function CameraControls:SetRotatedCamera(rotatedCamera)
 	return self
 end
 
---- This code was the same algorithm used by ROBLOX. It makes it so you can zoom easier at further distances.
+-- This code was the same algorithm used by Roblox. It makes it so you can zoom easier at further distances.
 function CameraControls:_handleMouseWheel(inputObject)
 	if self._zoomedCamera then
 		local delta = math.clamp(-inputObject.Position.Z, -1, 1)*1.4
@@ -210,7 +212,7 @@ function CameraControls:_handleTouchPinch(scale, velocity, userInputState)
 	end
 end
 
---- This is also a ROBLOX algorithm. Not sure why screen resolution is locked like it is.
+-- This is also a Roblox algorithm. Not sure why screen resolution is locked like it is.
 function CameraControls:_mouseTranslationToAngle(translationVector)
 	local xTheta = (translationVector.x / 1920)
 	local yTheta = (translationVector.y / 1200)

package/src/Client/Controls/CameraGamepadInputUtils.lua

@@ -1,6 +1,6 @@
----
--- @module CameraGamepadInputUtils
--- @author Quenty
+--[=[
+	@class CameraGamepadInputUtils
+]=]
 
 local CameraGamepadInputUtils = {}
 

package/src/Client/Controls/GamepadRotateModel.lua

@@ -1,5 +1,7 @@
---- Rotation model for gamepad controls
--- @classmod GamepadRotateModel
+--[=[
+	Rotation model for gamepad controls
+	@class GamepadRotateModel
+]=]
 
 local require = require(script.Parent.loader).load(script)
 

package/src/Client/Effects/CameraEffectUtils.lua

@@ -0,0 +1,19 @@
+--[=[
+	A CameraEffect is something that can be resolved into a CameraState providing source
+	@class CameraEffectUtils
+]=]
+
+--[=[
+	Represents an effect that can be used in combination with other effects.
+	@interface CameraEffect
+	.CameraState CameraState
+	@within CameraEffectUtils
+]=]
+
+--[=[
+	Something that is like a camera
+	@type CameraLike CameraEffect | CameraState
+	@within CameraEffectUtils
+]=]
+
+return {}

package/src/Client/Effects/CustomCameraEffect.lua

@@ -1,5 +1,7 @@
---- For effects that can be easily bound in scope
--- @classmod CustomCameraEffect
+--[=[
+	For effects that can be easily bound in scope
+	@class CustomCameraEffect
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -8,8 +10,11 @@ local SummedCamera = require("SummedCamera")
 local CustomCameraEffect = {}
 CustomCameraEffect.ClassName = "CustomCameraEffect"
 
---- Constructs a new custom camera effect
--- @tparam function getCurrentStateFunc to return a function state
+--[=[
+	Constructs a new custom camera effect
+	@param getCurrentStateFunc () -> CameraState -- Custom effect generator
+	@return CustomCameraEffect
+]=]
 function CustomCameraEffect.new(getCurrentStateFunc)
 	local self = setmetatable({}, CustomCameraEffect)
 
@@ -22,6 +27,12 @@ function CustomCameraEffect:__add(other)
 	return SummedCamera.new(self, other)
 end
 
+--[=[
+	The current state.
+	@readonly
+	@prop CameraState CameraState
+	@within CustomCameraEffect
+]=]
 function CustomCameraEffect:__index(index)
 	if index == "CameraState" then
 		return self._getCurrentStateFunc()

package/src/Client/Effects/DefaultCamera.lua

@@ -1,6 +1,10 @@
--- 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
--- @classmod DefaultCamera
+--[=[
+	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).
+	@class DefaultCamera
+]=]
 
 local require = require(script.Parent.loader).load(script)
 
@@ -13,6 +17,11 @@ local SummedCamera = require("SummedCamera")
 local DefaultCamera = {}
 DefaultCamera.ClassName = "DefaultCamera"
 
+--[=[
+	Constructs a new DefaultCamera
+
+	@return DefaultCamera
+]=]
 function DefaultCamera.new()
 	local self = setmetatable({}, DefaultCamera)
 
@@ -25,6 +34,10 @@ function DefaultCamera:__add(other)
 	return SummedCamera.new(self, other)
 end
 
+--[=[
+	Overrides the global field of view in the cached camera state
+	@param fieldOfView number
+]=]
 function DefaultCamera:OverrideGlobalFieldOfView(fieldOfView)
 	self._cameraState.FieldOfView = fieldOfView
 end
@@ -33,6 +46,13 @@ function DefaultCamera:OverrideCameraState(cameraState)
 	self._cameraState = cameraState or error("No CameraState")
 end
 
+--[=[
+	Binds the camera to RunService RenderStepped event.
+
+	:::tip
+	Be sure to call UnbindFromRenderStep when using this.
+	:::
+]=]
 function DefaultCamera:BindToRenderStep()
 	RunService:BindToRenderStep("DefaultCamera_Preupdate", Enum.RenderPriority.Camera.Value-2, function()
 		self._cameraState:Set(Workspace.CurrentCamera)
@@ -45,11 +65,20 @@ function DefaultCamera:BindToRenderStep()
 	self._cameraState = CameraState.new(Workspace.CurrentCamera)
 end
 
+--[=[
+	Unbinds the camera from the RunService
+]=]
 function DefaultCamera:UnbindFromRenderStep()
 	RunService:UnbindFromRenderStep("DefaultCamera_Preupdate")
 	RunService:UnbindFromRenderStep("DefaultCamera_PostUpdate")
 end
 
+--[=[
+	The current state.
+	@readonly
+	@prop CameraState CameraState
+	@within DefaultCamera
+]=]
 function DefaultCamera:__index(index)
 	if index == "CameraState" then
 		return rawget(self, "_cameraState")