@quenty/viewport 5.4.1 → 5.5.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.5.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/viewport@5.4.1...@quenty/viewport@5.5.0) (2022-11-08)
+
+**Note:** Version bump only for package @quenty/viewport
+
+
+
+
+
 ## [5.4.1](https://github.com/Quenty/NevermoreEngine/compare/@quenty/viewport@5.4.0...@quenty/viewport@5.4.1) (2022-11-04)
 
 **Note:** Version bump only for package @quenty/viewport

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/viewport",
-  "version": "5.4.1",
+  "version": "5.5.0",
   "description": "Rendering functionality for viewportFrames",
   "keywords": [
     "Roblox",
@@ -45,5 +45,5 @@
   "devDependencies": {
     "@quenty/insertserviceutils": "^6.0.1"
   },
-  "gitHead": "8b9877c26a3fc753409a5114e56717837291279d"
+  "gitHead": "3432599d8ed7bf7f0436d7cd5495925543450117"
 }

package/src/Client/Viewport.lua

@@ -1,4 +1,17 @@
 --[=[
+	Creates a ViewportFrame with size fitting and drag controls. This means that the
+	viewport will center the camera around the given instance, and allow the user
+	to control the camera itself.
+
+	```lua
+	local viewport = Viewport.new()
+	viewport:SetInstance(instance)
+
+	maid:GiveTask(viewport:Render({
+		Parent = target;
+	}):Subscribe())
+	```
+
 	@class Viewport
 ]=]
 
@@ -26,6 +39,12 @@ local Viewport = setmetatable({}, BasicPane)
 Viewport.ClassName = "Viewport"
 Viewport.__index = Viewport
 
+--[=[
+	Constructs a new viewport. Unlike a normal [BasicPane] this will not render anything
+	immediately. See [Viewport.Render] for details.
+
+	@return Viewport
+]=]
 function Viewport.new()
 	local self = setmetatable(BasicPane.new(), Viewport)
 
@@ -55,8 +74,28 @@ function Viewport.new()
 	return self
 end
 
+--[=[
+	Creates a Viewport and render it to Blend. The following properties are supported
+
+	* Ambient - Color3
+	* AnchorPoint - Vector2
+	* FieldOfView - number
+	* Instance - Instance
+	* LayoutOrder - number
+	* LightColor - Color3
+	* Parent - Instance
+	* Position - UDim2
+	* Size - Vector3
+	* Transparency - number
+
+	Properties may be anything Blend would take as computable. See [Blend] for details.
+
+	@param props { string }
+	@return Observable<Instance>
+]=]
 function Viewport.blend(props)
 	assert(type(props) == "table", "Bad props")
+
 	return Observable.new(function(sub)
 		local maid = Maid.new()
 
@@ -93,24 +132,51 @@ function Viewport.blend(props)
 	end)
 end
 
+
+--[=[
+	Sets the field of view on the viewport.
+
+	@param transparency number
+]=]
 function Viewport:SetTransparency(transparency)
 	assert(type(transparency) == "number", "Bad transparency")
 
 	self._transparency.Value = transparency
 end
 
+--[=[
+	Sets the field of view on the viewport.
+
+	@param fieldOfView number
+]=]
 function Viewport:SetFieldOfView(fieldOfView)
 	assert(type(fieldOfView) == "number", "Bad fieldOfView")
 
 	self._fieldOfView.Value = fieldOfView
 end
 
+--[=[
+	Set the instance to be rendered. The instance will be reparented
+	to the viewport.
+
+	:::warning
+	The instance you set here will NOT be destroyed by the viewport. This lets the
+	performance be optimized or the instance used in good transitions. However,
+	be sure to destroy it if you need to.
+	:::
+
+	@param instance Instance?
+]=]
 function Viewport:SetInstance(instance)
 	assert(typeof(instance) == "Instance" or instance == nil, "Bad instance")
 
 	self._current.Value = instance
 end
 
+--[=[
+	Notifies the viewport of the instance size changing. We don't connect to
+	any events here because the instance can be anything.
+]=]
 function Viewport:NotifyInstanceSizeChanged()
 	self._notifyInstanceSizeChanged:Fire()
 end
@@ -131,6 +197,26 @@ function Viewport:RotateBy(deltaV2, doNotAnimate)
 	end
 end
 
+--[=[
+	Renders the viewport. Allows the following properties.
+
+	* Ambient - Color3
+	* AnchorPoint - Vector2
+	* LayoutOrder - number
+	* LightColor - Color3
+	* Parent - Instance
+	* Position - UDim2
+	* Size - Vector3
+	* Transparency - number
+
+	:::warning
+	This should only be called once per a Viewport instance, since the Instance property is
+	not duplicated.
+	:::
+
+	@param props { any }
+	@return Observable<ViewportFrame>
+]=]
 function Viewport:Render(props)
 	local currentCamera = ValueObject.new()
 	self._maid:GiveTask(currentCamera)
@@ -212,4 +298,4 @@ function Viewport:Render(props)
 	};
 end
 
-return Viewport
+return Viewport

package/src/Client/Viewport.story.lua

@@ -15,7 +15,7 @@ return function(target)
 	local viewport = Viewport.new()
 	maid:GiveTask(viewport)
 
-	maid:GivePromise(InsertServiceUtils.promiseAsset(182451181))
+	maid:GivePromise(InsertServiceUtils.promiseAsset(182451181)) --The account must own the asset in order to insert it.
 		:Then(function(crate)
 			viewport:SetInstance(crate)
 		end)
@@ -27,4 +27,4 @@ return function(target)
 	return function()
 		maid:DoCleaning()
 	end
-end
+end

package/src/Client/ViewportControls.lua

@@ -1,4 +1,5 @@
 --[=[
+	Controls for [Viewport]
 	@class ViewportControls
 ]=]
 
@@ -14,6 +15,12 @@ local ViewportControls = setmetatable({}, BaseObject)
 ViewportControls.ClassName = "ViewportControls"
 ViewportControls.__index = ViewportControls
 
+--[=[
+    Create the controls for dragging.
+    @param viewport Instance
+    @param viewportModel Viewport
+    @return BaseObject
+]=]
 function ViewportControls.new(viewport, viewportModel)
 	local self = setmetatable(BaseObject.new(viewport), ViewportControls)
 
@@ -80,4 +87,4 @@ function ViewportControls:_stopDrag()
 	self._maid._dragging = nil
 end
 
-return ViewportControls
+return ViewportControls