@quenty/draw 2.1.0 → 2.2.1-canary.238.f89c386.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [2.2.1-canary.238.f89c386.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/draw@2.2.0...@quenty/draw@2.2.1-canary.238.f89c386.0) (2021-12-30)
+
+**Note:** Version bump only for package @quenty/draw
+
+
+
+
+
+# [2.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/draw@2.1.0...@quenty/draw@2.2.0) (2021-10-02)
+
+
+### Features
+
+* Can update ray appearance for performance reasons ([ae6cbd3](https://github.com/Quenty/NevermoreEngine/commit/ae6cbd35f22105519fa2ca11c1e456be8b4d6771))
+
+
+
+
+
 # [2.1.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/draw@2.0.0...@quenty/draw@2.1.0) (2021-09-22)
 
 

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014 Quenty
+Copyright (c) 2014-2021 Quenty
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,10 +1,10 @@
 ## Draw
 <div align="center">
-  <a href="http://quenty.github.io/api/">
-    <img src="https://img.shields.io/badge/docs-website-green.svg" alt="Documentation" />
+  <a href="http://quenty.github.io/NevermoreEngine/">
+    <img src="https://github.com/Quenty/NevermoreEngine/actions/workflows/docs.yml/badge.svg" alt="Documentation status" />
   </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" />
@@ -13,6 +13,8 @@
 
 A utility library to debug things in 3D space for Roblox. Each method will always return an object you can use to cleanup the resulting drawing.
 
+<div align="center"><a href="https://quenty.github.io/NevermoreEngine/api/Draw">View docs →</a></div>
+
 ## Installation
 ```
 npm install @quenty/draw --save

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/draw",
-  "version": "2.1.0",
+  "version": "2.2.1-canary.238.f89c386.0",
   "description": "A utility library to debug things in 3D space for Roblox.",
   "keywords": [
     "Roblox",
@@ -28,5 +28,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "6288c63115f31544fce6663d018826e81ef01c7f"
+  "gitHead": "f89c3863db94c96adc936ea31a49e0c770756dd0"
 }

package/src/Shared/Draw.lua

@@ -1,5 +1,25 @@
---- Debug drawing library useful for debugging 3D abstractions
--- @module Draw
+--[=[
+	Debug drawing library useful for debugging 3D abstractions. One of
+	the more useful utility libraries.
+
+	These functions are incredibly easy to invoke for quick debugging.
+	This can make debugging any sort of 3D geometry really easy.
+
+	```lua
+	-- A sample of a few API uses
+	Draw.point(Vector3.new(0, 0, 0))
+	Draw.terrainCell(Vector3.new(0, 0, 0))
+	Draw.cframe(CFrame.new(0, 10, 0))
+	Draw.text(Vector3.new(0, -10, 0), "Testing!")
+	```
+
+	:::tip
+	This library should not be used to render things in production for
+	normal players, as it is optimized for debug experience over performance.
+	:::
+
+	@class Draw
+]=]
 
 local Workspace = game:GetService("Workspace")
 local RunService = game:GetService("RunService")
@@ -12,27 +32,43 @@ local ORIGINAL_DEFAULT_COLOR = Color3.new(1, 0, 0)
 local Draw = {}
 Draw._defaultColor = ORIGINAL_DEFAULT_COLOR
 
---- Sets the Draw's drawing color
--- @tparam {Color3} color The color to set
+--[=[
+	Sets the Draw's drawing color.
+	@param color Color3 -- The color to set
+]=]
 function Draw.setColor(color)
 	Draw._defaultColor = color
 end
 
+--[=[
+	Resets the drawing color.
+]=]
 function Draw.resetColor()
 	Draw._defaultColor = ORIGINAL_DEFAULT_COLOR
 end
 
---- Sets the Draw library to use a random color
+--[=[
+	Sets the Draw library to use a random color.
+]=]
 function Draw.setRandomColor()
 	Draw.setColor(Color3.fromHSV(math.random(), 0.5+0.5*math.random(), 1))
 end
 
---- Draws a ray for debugging
--- @param ray The ray to Draw
--- @tparam[opt] {color3} color The color to Draw in
--- @tparam[opt] {Instance} parent
--- @tparam[opt] {number} diameter
--- @tparam[opt] {number} meshDiameter
+--[=[
+	Draws a ray for debugging.
+
+	```lua
+	local ray = Ray.new(Vector3.new(0, 0, 0), Vector3.new(0, 10, 0))
+	Draw.ray(ray)
+	```
+
+	@param ray Ray
+	@param color Color3? -- Optional color to draw in
+	@param parent Instance? -- Optional parent
+	@param diameter number? -- Optional diameter
+	@param meshDiameter number? -- Optional mesh diameter
+	@return BasePart
+]=]
 function Draw.ray(ray, color, parent, meshDiameter, diameter)
 	assert(typeof(ray) == "Ray", "Bad typeof(ray) for Ray")
 
@@ -58,6 +94,7 @@ function Draw.ray(ray, color, parent, meshDiameter, diameter)
 	part.Transparency = 0.5
 
 	local rotatedPart = Instance.new("Part")
+	rotatedPart.Name = "RotatedPart"
 	rotatedPart.Anchored = true
 	rotatedPart.Archivable = false
 	rotatedPart.CanCollide = false
@@ -68,6 +105,7 @@ function Draw.ray(ray, color, parent, meshDiameter, diameter)
 	rotatedPart.Parent = part
 
 	local lineHandleAdornment = Instance.new("LineHandleAdornment")
+	lineHandleAdornment.Name = "DrawRayLineHandleAdornment"
 	lineHandleAdornment.Length = ray.Direction.Magnitude
 	lineHandleAdornment.Thickness = 5*diameter
 	lineHandleAdornment.ZIndex = 3
@@ -78,6 +116,7 @@ function Draw.ray(ray, color, parent, meshDiameter, diameter)
 	lineHandleAdornment.Parent = rotatedPart
 
 	local mesh = Instance.new("SpecialMesh")
+	mesh.Name = "DrawRayMesh"
 	mesh.Scale = Vector3.new(0, 1, 0) + Vector3.new(meshDiameter, 0, meshDiameter) / diameter
 	mesh.Parent = part
 
@@ -86,6 +125,61 @@ function Draw.ray(ray, color, parent, meshDiameter, diameter)
 	return part
 end
 
+--[=[
+	Updates the rendered ray to the new color and position.
+	Used for certain scenarios when updating a ray on
+	renderstepped would impact performance, even in debug mode.
+
+	```lua
+	local ray = Ray.new(Vector3.new(0, 0, 0), Vector3.new(0, 10, 0))
+	local drawn = Draw.ray(ray)
+
+	RunService.RenderStepped:Connect(function()
+		local newRay = Ray.new(Vector3.new(0, 0, 0), Vector3.new(0, 10*math.sin(os.clock()), 0))
+		Draw.updateRay(drawn, newRay Color3.new(1, 0.5, 0.5))
+	end)
+	```
+
+	@param part Ray part
+	@param ray Ray
+	@param color Color3
+]=]
+function Draw.updateRay(part, ray, color)
+	color = color or part.Color
+
+	local diameter = part.Size.x
+	local rayCenter = ray.Origin + ray.Direction/2
+
+	part.CFrame = CFrame.new(rayCenter, ray.Origin + ray.Direction) * CFrame.Angles(math.pi/2, 0, 0)
+	part.Size = Vector3.new(diameter, ray.Direction.Magnitude, diameter)
+	part.Color = color
+
+	local rotatedPart = part:FindFirstChild("RotatedPart")
+	if rotatedPart then
+		rotatedPart.CFrame = CFrame.new(ray.Origin, ray.Origin + ray.Direction)
+	end
+
+	local lineHandleAdornment = rotatedPart and rotatedPart:FindFirstChild("DrawRayLineHandleAdornment")
+	if lineHandleAdornment then
+		lineHandleAdornment.Length = ray.Direction.Magnitude
+		lineHandleAdornment.Thickness = 5*diameter
+		lineHandleAdornment.Color3 = color
+	end
+end
+
+--[=[
+	Render text in 3D for debugging. The text container will
+	be sized to fit the text.
+
+	```lua
+	Draw.text(Vector3.new(0, 10, 0), "Point")
+	```
+
+	@param adornee Instance | Vector3 -- Adornee to rener on
+	@param text string -- Text to render
+	@param color Color3? -- Optional color to render
+	@return Instance
+]=]
 function Draw.text(adornee, text, color)
 	if typeof(adornee) == "Vector3" then
 		local attachment = Instance.new("Attachment")
@@ -177,21 +271,44 @@ function Draw._textOnAdornee(adornee, text, color)
 	return billboardGui
 end
 
-function Draw.sphere(vector3, radius, color, parent)
-	return Draw.point(vector3, color, parent, radius*2)
+--[=[
+	Renders a sphere at the given point in 3D space.
+
+	```lua
+	Draw.sphere(Vector3.new(0, 10, 0), 10)
+	```
+
+	Great for debugging explosions and stuff.
+
+	@param position Vector3 -- Position of the sphere
+	@param radius number -- Radius of the sphere
+	@param color Color3? -- Optional color
+	@param parent Instance? -- Optional parent
+	@return BasePart
+]=]
+function Draw.sphere(position, radius, color, parent)
+	return Draw.point(position, color, parent, radius*2)
 end
 
---- Draws a point for debugging
--- @tparam {Vector3} vector3 Point to Draw
--- @tparam[opt] {color3} color The color to Draw in
--- @tparam[opt] {Instance} parent
--- @tparam[opt] {number} diameter
-function Draw.point(vector3, color, parent, diameter)
-	if typeof(vector3) == "CFrame" then
-		vector3 = vector3.p
+--[=[
+	Draws a point for debugging in 3D space.
+
+	```lua
+	Draw.point(Vector3.new(0, 25, 0), Color3.new(0.5, 1, 0.5))
+	```
+
+	@param position Vector3 | CFrame -- Point to Draw
+	@param color Color3? -- Optional color
+	@param parent Instance? -- Optional parent
+	@param diameter number? -- Optional diameter
+	@return BasePart
+]=]
+function Draw.point(position, color, parent, diameter)
+	if typeof(position) == "CFrame" then
+		position = position.p
 	end
 
-	assert(typeof(vector3) == "Vector3", "Bad vector3")
+	assert(typeof(position) == "Vector3", "Bad position")
 
 	color = color or Draw._defaultColor
 	parent = parent or Draw.getDefaultParent()
@@ -204,7 +321,7 @@ function Draw.point(vector3, color, parent, diameter)
 	part.BottomSurface = Enum.SurfaceType.Smooth
 	part.CanCollide = false
 	part.CastShadow = false
-	part.CFrame = CFrame.new(vector3)
+	part.CFrame = CFrame.new(position)
 	part.Color = color
 	part.Name = "DebugPoint"
 	part.Shape = Enum.PartType.Ball
@@ -226,18 +343,41 @@ function Draw.point(vector3, color, parent, diameter)
 	return part
 end
 
-function Draw.labelledPoint(vector3, label, color, parent)
-	if typeof(vector3) == "CFrame" then
-		vector3 = vector3.p
+--[=[
+	Renders a point with a label in 3D space.
+
+	```lua
+	Draw.labelledPoint(Vector3.new(0, 10, 0), "AI target")
+	```
+
+	@param position Vector3 | CFrame -- Position to render
+	@param label string -- Label to render on the point
+	@param color Color3? -- Optional color
+	@param parent Instance? -- Optional parent
+	@return BasePart
+]=]
+function Draw.labelledPoint(position, label, color, parent)
+	if typeof(position) == "CFrame" then
+		position = position.p
 	end
 
-	local part = Draw.point(vector3, color, parent)
+	local part = Draw.point(position, color, parent)
 
 	Draw.text(part, label, color)
 
 	return part
 end
 
+--[=[
+	Renders a CFrame in 3D space. Includes each axis.
+
+	```lua
+	Draw.cframe(CFrame.Angles(0, math.pi/8, 0))
+	```
+
+	@param cframe CFrame
+	@return Model
+]=]
 function Draw.cframe(cframe)
 	local model = Instance.new("Model")
 	model.Name = "DebugCFrame"
@@ -268,6 +408,17 @@ function Draw.cframe(cframe)
 	return model
 end
 
+--[=[
+	Renders a box in 3D space. Great for debugging bounding boxes.
+
+	```lua
+	Draw.box(Vector3.new(0, 5, 0), Vector3.new(10, 10, 10))
+	```
+	@param cframe CFrame | Vector3 -- CFrame of the box
+	@param size Vector3 -- Size of the box
+	@param color Color3 -- Optional Color3
+	@return BasePart
+]=]
 function Draw.box(cframe, size, color)
 	assert(typeof(size) == "Vector3", "Bad size")
 
@@ -302,10 +453,33 @@ function Draw.box(cframe, size, color)
 	return part
 end
 
+--[=[
+	Renders a region3 in 3D space.
+
+	```lua
+	Draw.region3(Region3.new(Vector3.new(0, 0, 0), Vector3.new(10, 10, 10)))
+	```
+
+	@param region3 Region3 -- Region3 to render
+	@param color Color3? -- Optional color3
+	@return BasePart
+]=]
 function Draw.region3(region3, color)
 	return Draw.box(region3.CFrame, region3.Size, color)
 end
 
+--[=[
+	Renders a terrain cell in 3D space. Snaps the position
+	to the nearest position.
+
+	```lua
+	Draw.terrainCell(Vector3.new(0, 0, 0))
+	```
+
+	@param position Vector3 -- World space position
+	@param color Color3? -- Optional color to render
+	@return BasePart
+]=]
 function Draw.terrainCell(position, color)
 	local size = Vector3.new(4, 4, 4)
 
@@ -318,16 +492,38 @@ function Draw.terrainCell(position, color)
 	return part
 end
 
+--[=[
+	Draws a vector in 3D space.
+
+	```lua
+	Draw.vector(Vector3.new(0, 0, 0), Vector3.new(0, 1, 0))
+	```
+
+	@param position Vector3 -- Position of the vector
+	@param direction Vector3 -- Direction of the vector. Determines length.
+	@param color Color3? -- Optional color
+	@param parent Instance? -- Optional instance
+	@param meshDiameter number? -- Optional diameter
+	@return BasePart
+]=]
 function Draw.vector(position, direction, color, parent, meshDiameter)
 	return Draw.ray(Ray.new(position, direction), color, parent, meshDiameter)
 end
 
+--[=[
+	Retrieves the default parent for the current execution context.
+	@return Instance
+]=]
 function Draw.getDefaultParent()
 	if not RunService:IsRunning() then
 		return Workspace.CurrentCamera
 	end
 
-	return RunService:IsServer() and Workspace or Workspace.CurrentCamera
+	if RunService:IsServer() then
+		return Workspace
+	else
+		return Workspace.CurrentCamera
+	end
 end
 
 return Draw