@quenty/draw 4.2.0 → 4.2.1-canary.402.a911cda.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+## [4.2.1-canary.402.a911cda.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/draw@4.2.0...@quenty/draw@4.2.1-canary.402.a911cda.0) (2023-08-23)
+
+
+### Features
+
+* Add Draw.line, Draw.direction, Draw.sphereCast, Draw.blockCast, and better draw semantics ([6d78106](https://github.com/Quenty/NevermoreEngine/commit/6d78106879fb6daa5bf5a28711aed746ed0a6f3e))
+* Add Draw.raycast() ([1071969](https://github.com/Quenty/NevermoreEngine/commit/10719695aede9bc9b16f7c311a98dcd5120c43ac))
+
+
+
+
+
 # [4.2.0](https://github.com/Quenty/NevermoreEngine/compare/@quenty/draw@4.1.1...@quenty/draw@4.2.0) (2022-10-11)
 
 

package/LICENSE.md

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2014-2022 Quenty
+Copyright (c) 2014-2023 James Onnen (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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quenty/draw",
-  "version": "4.2.0",
+  "version": "4.2.1-canary.402.a911cda.0",
   "description": "A utility library to debug things in 3D space for Roblox.",
   "keywords": [
     "Roblox",
@@ -28,5 +28,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "69c2153865684748d0a8d6806f1ff999685c2e55"
+  "gitHead": "a911cdaf4f1039b599528cec17b027f4660e4fd8"
 }

package/src/Shared/Draw.lua

@@ -55,6 +55,105 @@ function Draw.setRandomColor()
 	Draw.setColor(Color3.fromHSV(math.random(), 0.5+0.5*math.random(), 1))
 end
 
+--[=[
+	Draws a line between two points
+
+	@param start Vector3
+	@param finish Vector3
+	@param color Color3 -- Optional
+	@param parent Instance? -- Optional
+	@param meshDiameter number -- Optional
+	@param diameter number -- Optional
+	@return Instance
+]=]
+function Draw.line(start, finish, color, parent, meshDiameter, diameter)
+	start = assert(Draw._toVector3(start), "Bad start")
+	finish = assert(Draw._toVector3(finish), "Bad finish")
+	color = Draw._toColor3(color)
+
+	return Draw.ray(Ray.new(start, finish - start), color, parent, meshDiameter, diameter)
+end
+
+--[=[
+	Draws a line between directions
+
+	@param origin Vector3
+	@param direction Vector3
+	@param color Color3 -- Optional
+	@param parent Instance? -- Optional
+	@param meshDiameter number -- Optional
+	@param diameter number -- Optional
+	@return Instance
+]=]
+function Draw.direction(origin, direction, color, parent, meshDiameter, diameter)
+	origin = assert(Draw._toVector3(origin), "Bad origin")
+	direction = assert(Draw._toVector3(direction), "Bad direction")
+	color = Draw._toColor3(color)
+
+	return Draw.ray(Ray.new(origin, direction), color, parent, meshDiameter, diameter)
+end
+
+--[=[
+	Draws a spherecast
+
+	@param origin Vector3
+	@param radius number
+	@param direction Vector3
+	@param color Color3
+	@param parent Parent
+]=]
+function Draw.sphereCast(origin, radius, direction, color, parent)
+	return Draw.ray(Ray.new(origin, direction), color, parent, 2*radius)
+end
+
+--[=[
+	Draws a spherecast
+
+	@param cframe CFrame
+	@param size Vector3
+	@param direction Vector3
+	@param color Color3
+	@param parent Parent
+]=]
+function Draw.blockcast(cframe, size, direction, color, parent)
+	cframe = assert(Draw._toCFrame(cframe), "Bad cframe")
+	size = assert(Draw._toVector3(size), "Bad size")
+	color = Draw._toColor3(color)
+	parent = parent or Draw.getDefaultParent()
+
+	local folder = Instance.new("Folder")
+	folder.Name = "Blockcast"
+	folder.Archivable = false
+
+	-- Draw beginning and end for now...
+	-- TODO: Convex hull
+	Draw.box(cframe, size, color).Parent = folder
+	Draw.box(cframe + direction, size, color).Parent = folder
+
+	folder.Parent = parent
+
+	return folder
+end
+
+--[=[
+	Draws a raycast for debugging
+
+	```lua
+	Draw.raycast(origin, direction)
+	```
+
+	@param origin Vector3
+	@param direction Vector3
+	@param color Color3 -- Optional
+	@param parent Instance? -- Optional
+	@param meshDiameter number -- Optional
+	@param diameter number -- Optional
+	@return Instance
+]=]
+function Draw.raycast(origin, direction, color, parent, meshDiameter, diameter)
+	return Draw.direction(origin, direction, color, parent, meshDiameter, diameter)
+end
+
 --[=[
 	Draws a ray for debugging.
 
@@ -73,7 +172,7 @@ end
 function Draw.ray(ray, color, parent, meshDiameter, diameter)
 	assert(typeof(ray) == "Ray", "Bad typeof(ray) for Ray")
 
-	color = color or Draw._defaultColor
+	color = Draw._toColor3(color) or Draw._defaultColor
 	parent = parent or Draw.getDefaultParent()
 	meshDiameter = meshDiameter or 0.2
 	diameter = diameter or 0.2
@@ -150,7 +249,7 @@ end
 	@param color Color3
 ]=]
 function Draw.updateRay(part, ray, color)
-	color = color or part.Color
+	color = Draw._toColor3(color) or part.Color
 
 	local diameter = part.Size.x
 	local rayCenter = ray.Origin + ray.Direction/2
@@ -186,6 +285,8 @@ end
 	@return Instance
 ]=]
 function Draw.text(adornee, text, color)
+	color = Draw._toColor3(color)
+
 	if typeof(adornee) == "Vector3" then
 		local attachment = Instance.new("Attachment")
 		attachment.WorldPosition = adornee
@@ -309,13 +410,9 @@ end
 	@return BasePart
 ]=]
 function Draw.point(position, color, parent, diameter)
-	if typeof(position) == "CFrame" then
-		position = position.Position
-	end
-
-	assert(typeof(position) == "Vector3", "Bad position")
+	position = assert(Draw._toVector3(position), "Bad position")
+	color = Draw._toColor3(color) or Draw._defaultColor
 
-	color = color or Draw._defaultColor
 	parent = parent or Draw.getDefaultParent()
 	diameter = diameter or 1
 
@@ -364,9 +461,8 @@ end
 	@return BasePart
 ]=]
 function Draw.labelledPoint(position, label, color, parent)
-	if typeof(position) == "CFrame" then
-		position = position.Position
-	end
+	position = assert(Draw._toVector3(position), "Bad position")
+	color = Draw._toColor3(color)
 
 	local part = Draw.point(position, color, parent)
 
@@ -386,6 +482,8 @@ end
 	@return Model
 ]=]
 function Draw.cframe(cframe)
+	cframe = assert(Draw._toCFrame(cframe), "Bad cframe")
+
 	local model = Instance.new("Model")
 	model.Name = "DebugCFrame"
 
@@ -430,6 +528,8 @@ end
 ]=]
 function Draw.part(template, cframe, color, transparency)
 	assert(typeof(template) == "Instance" and template:IsA("BasePart"), "Bad template")
+	cframe = Draw._toCFrame(cframe)
+	color = Draw._toColor3(color)
 
 	local part = template:Clone()
 	for _, child in pairs(part:GetChildren()) do
@@ -486,10 +586,14 @@ end
 	@return BasePart
 ]=]
 function Draw.box(cframe, size, color)
+	cframe = assert(Draw._toCFrame(cframe), "Bad cframe")
+	size = assert(Draw._toVector3(size), "Bad size")
+	color = Draw._toColor3(color)
+
+	assert(typeof(cframe) == "CFrame", "Bad cframe")
 	assert(typeof(size) == "Vector3", "Bad size")
 
 	color = color or Draw._defaultColor
-	cframe = typeof(cframe) == "Vector3" and CFrame.new(cframe) or cframe
 
 	local part = Instance.new("Part")
 	part.Color = color
@@ -533,6 +637,8 @@ end
 	@return BasePart
 ]=]
 function Draw.region3(region3, color)
+	color = Draw._toColor3(color)
+
 	return Draw.box(region3.CFrame, region3.Size, color)
 end
 
@@ -549,6 +655,9 @@ end
 	@return BasePart
 ]=]
 function Draw.terrainCell(position, color)
+	position = assert(Draw._toVector3(position), "Bad position")
+	color = Draw._toColor3(color)
+
 	local size = Vector3.new(4, 4, 4)
 
 	local solidCell = Terrain:WorldToCell(position)
@@ -560,9 +669,9 @@ function Draw.terrainCell(position, color)
 	return part
 end
 
-
-
 function Draw.screenPointLine(a, b, parent, color)
+	color = Draw._toColor3(color)
+
 	local offset = (b - a)
 	local pos = a + offset/2
 
@@ -601,6 +710,8 @@ function Draw.screenPointLine(a, b, parent, color)
 end
 
 function Draw.screenPoint(position, parent, color, diameter)
+	color = Draw._toColor3(color)
+
 	local frame = Instance.new("Frame")
 	frame.Name = "DebugScreenPoint"
 	frame.Size = UDim2.new(0, diameter, 0, diameter)
@@ -634,6 +745,10 @@ end
 	@return BasePart
 ]=]
 function Draw.vector(position, direction, color, parent, meshDiameter)
+	position = assert(Draw._toVector3(position), "Bad position")
+	direction = assert(Draw._toVector3(direction), "Bad direction")
+	color = Draw._toColor3(color)
+
 	return Draw.ray(Ray.new(position, direction), color, parent, meshDiameter)
 end
 
@@ -652,6 +767,9 @@ end
 	@return BasePart
 ]=]
 function Draw.ring(ringPos, ringNorm, ringRadius, color, parent)
+	ringPos = assert(Draw._toVector3(ringPos), "Bad ringPos")
+	ringNorm = assert(Draw._toVector3(ringNorm), "Bad ringNorm")
+
 	local ringCFrame = CFrame.new(ringPos, ringPos + ringNorm)
 
 	local points = {}
@@ -677,6 +795,62 @@ function Draw.ring(ringPos, ringNorm, ringRadius, color, parent)
 	return folder
 end
 
+function Draw._toVector3(position)
+	if typeof(position) == "Vector3" then
+		return position
+	elseif typeof(position) == "CFrame" then
+		return position.Position
+	elseif typeof(position) == "Instance" then
+		if position:IsA("Attachment") then
+			return position.WorldPosition
+		elseif position:IsA("BasePart") then
+			return position.Position
+		elseif position:IsA("Model") then
+			return position:GetBoundingBox().p
+		else
+			return nil
+		end
+	else
+		return nil
+	end
+end
+
+function Draw._toColor3(color)
+	if typeof(color) == "Color3" then
+		return color
+	elseif typeof(color) == "BrickColor" then
+		return color.Color
+	elseif typeof(color) == "Instance" then
+		if color:IsA("BasePart") then
+			return color.Color
+		else
+			return nil
+		end
+	else
+		return nil
+	end
+end
+
+function Draw._toCFrame(cframe)
+	if typeof(cframe) == "CFrame" then
+		return cframe
+	elseif typeof(cframe) == "Vector3" then
+		return CFrame.new(cframe)
+	elseif typeof(cframe) == "Instance" then
+		if cframe:IsA("Attachment") then
+			return cframe.WorldCFrame
+		elseif cframe:IsA("BasePart") then
+			return cframe.CFrame
+		elseif cframe:IsA("Model") then
+			return (cframe:GetBoundingBox())
+		else
+			return nil
+		end
+	else
+		return nil
+	end
+end
+
 --[=[
 	Retrieves the default parent for the current execution context.
 	@return Instance