@rbxts/gizmos 1.0.0 → 1.2.0

package/README.md

@@ -41,7 +41,7 @@ Gizmos.log("Frame:", tick());
 
 ## Features
 
-- **Shapes**: Lines, rays, paths, points, cubes, circles, spheres, pyramids
+- **Shapes**: Lines, rays, paths, points, cubes, circles, spheres, pyramids, cones
 - **Raycasts**: Visualize raycasts, spherecasts, and blockcasts with hit detection
 - **Text**: World-space and on-screen text rendering
 - **Colors**: Built-in color presets (red, green, blue, yellow, cyan, magenta, orange, purple, white, gray, black)
@@ -62,6 +62,7 @@ Gizmos.log("Frame:", tick());
 - `drawCircle(position: Vector3, radius: number, normal?: Vector3)` - Draw circle
 - `drawSphere(position: Vector3 | CFrame, radius: number)` - Draw sphere
 - `drawPyramid(position: Vector3 | CFrame, size: number, height: number)` - Draw pyramid
+- `drawCone(apex: Vector3, direction: Vector3, range: number, halfAngleDeg: number, segments?: number)` - Draw cone (apex + axis + slant range + half-angle); resolution adapts to the cone's shape, with an optional `segments` override
 - `drawCFrame(cf: CFrame, size?: number, color?: Color3)` - Draw CFrame axes
 
 ### Raycasts

package/out/index.d.ts

@@ -8,6 +8,12 @@
  */
 
 interface Gizmos {
+	/**
+	 * Whether gizmos are enabled and will be rendered
+	 * @default true
+	 */
+	enabled: boolean;
+
 	/**
 	 * Whether to automatically clear gizmos each frame
 	 * @default true
@@ -85,6 +91,20 @@ interface Gizmos {
 	 */
 	drawPyramid(position: Vector3 | CFrame, size: number, height: number): void;
 
+	/**
+	 * Draw a wireframe cone with its apex at a point, opening along a direction.
+	 *
+	 * Wider cones automatically get more slant lines and intermediate cross-section
+	 * rings so short/wide shapes (e.g. a melee hit volume) read as a solid 3D cone
+	 * rather than a sparse X.
+	 * @param apex Tip of the cone (e.g. the attacker's position)
+	 * @param direction Axis the cone opens along (need not be normalized)
+	 * @param range Slant length — straight-line distance from the apex to the base rim
+	 * @param halfAngleDeg Half-angle of the cone in degrees (axis to slant edge)
+	 * @param segments Optional base-rim resolution override; defaults to a value adapted to the rim size (clamped 16–48)
+	 */
+	drawCone(apex: Vector3, direction: Vector3, range: number, halfAngleDeg: number, segments?: number): void;
+
 	/**
 	 * Draw a CFrame as colored axes (red = right, green = up, blue = -look)
 	 * @param cf CFrame to visualize

package/out/init.lua

@@ -7,6 +7,7 @@ local trailers = {}
 
 local hitColor, missColor = 'green', 'red'
 
+Gizmos.enabled = true
 Gizmos.clear = true
 
 local colors = {
@@ -174,19 +175,20 @@ local function drawCube(pos: Vector3 | CFrame, size: Vector3)
 	})
 end
 
-local function drawCircle(pos: Vector3, radius: number, normal: Vector3?)
-	local segments = 16
-	normal = normal or Vector3.yAxis
-	local cf = CFrame.lookAlong(pos, normal)
+local function helper_circlePoints(cf: CFrame, radius: number, segments: number): {Vector3}
 	local angle = 2 * math.pi / segments
-
 	local points = {}
 	for i = 1, segments do
 		local localpoint = Vector3.new(math.cos(i * angle), math.sin(i * angle), 0) * radius
-		local point = cf:PointToWorldSpace(localpoint)
-		table.insert(points, point)
+		table.insert(points, cf:PointToWorldSpace(localpoint))
 	end
-	wfh:AddPath(points, true)
+	return points
+end
+
+local function drawCircle(pos: Vector3, radius: number, normal: Vector3?)
+	normal = normal or Vector3.yAxis
+	local cf = CFrame.lookAlong(pos, normal)
+	wfh:AddPath(helper_circlePoints(cf, radius, 16), true)
 end
 
 local function drawSphere(pos: Vector3 | CFrame, radius: number)
@@ -210,6 +212,40 @@ local function drawPyramid(pos: Vector3 | CFrame, size: number, height: number)
 	wfh:AddPath({points[3], points[5], points[4]}, false)
 end
 
+local function drawCone(apex: Vector3, direction: Vector3, range: number, halfAngleDeg: number, segments: number?)
+	local dir = direction.Unit
+	local halfAngle = math.rad(halfAngleDeg)
+	local height = range * math.cos(halfAngle)
+	local radius = range * math.sin(halfAngle)
+	local baseCenter = apex + dir * height
+	local cf = CFrame.lookAlong(baseCenter, dir)
+
+	-- Base resolution scales with the rim size so wide cones stay smooth,
+	-- clamped so tiny cones aren't overdrawn and huge ones aren't sparse.
+	segments = segments or math.clamp(math.round(radius * 6), 16, 48)
+
+	-- Base rim.
+	local rim = helper_circlePoints(cf, radius, segments)
+	wfh:AddPath(rim, true)
+
+	-- Slant lines (rim -> apex). Wider cones get more so the volume reads as a
+	-- cone rather than a sparse X; narrow cones fall back to 4 like before.
+	local slantCount = math.clamp(math.round(halfAngleDeg / 3.75), 4, 16)
+	for j = 0, slantCount - 1 do
+		wfh:AddLine(apex, rim[math.floor(j / slantCount * segments) + 1])
+	end
+
+	-- Intermediate cross-section rings help a wide/short cone read as a solid
+	-- volume; narrow cones get none. Each ring sits at fraction t of the height,
+	-- where the cone radius is t * radius.
+	local ringCount = math.clamp(math.floor(halfAngleDeg / 22.5), 0, 3)
+	for k = 1, ringCount do
+		local t = k / (ringCount + 1)
+		local ringCf = CFrame.lookAlong(apex + dir * height * t, dir)
+		wfh:AddPath(helper_circlePoints(ringCf, radius * t, segments), true)
+	end
+end
+
 local function drawCFrame(cf: CFrame, size: number, color: Color3)
 	size = size or 1
 	local color3 = wfh.Color3
@@ -368,6 +404,12 @@ function Gizmos:drawPyramid(position: Vector3 | CFrame, size: number, height: nu
 	end)
 end
 
+function Gizmos:drawCone(apex: Vector3, direction: Vector3, range: number, halfAngleDeg: number, segments: number?)
+	table.insert(commands, function()
+		drawCone(apex, direction, range, halfAngleDeg, segments)
+	end)
+end
+
 function Gizmos:drawCFrame(cf: CFrame, size: number?, color: Color3?)
 	table.insert(commands, function()
 		drawCFrame(cf, size, color)
@@ -442,6 +484,7 @@ function Gizmos:test()
 	Gizmos:drawCircle(p, 0.5) n()
 	Gizmos:drawSphere(p+y*0.5, 0.5) n()
 	Gizmos:drawPyramid(p, 1, 1) n()
+	Gizmos:drawCone(p, y, 1, 30) n()
 	Gizmos:drawCFrame(CFrame.new(p)) n()
 	Gizmos:drawText(p, 'Hello') n()
 	Gizmos:drawRaycast(p, z, nil) n()
@@ -456,12 +499,35 @@ function Gizmos:test()
 		Gizmos:drawCircle(p, 0.15)
 		p += Vector3.xAxis*1
 	end
+
+	-- Cones from narrow/long to wide/short, including the melee hit-volume case
+	-- (range 7, halfAngle 45). Each should read clearly as a 3D cone.
+	Gizmos:setColor('cyan')
+	Gizmos:drawCone(Vector3.new(0,  0, 16), y, 4, 10)   -- narrow / long
+	Gizmos:drawCone(Vector3.new(8,  0, 16), y, 4, 30)
+	Gizmos:drawCone(Vector3.new(20, 0, 16), y, 7, 45)   -- wide / short (melee)
+	Gizmos:drawCone(Vector3.new(34, 0, 16), y, 4, 60)   -- very wide
 end
 
 findOrMakeGizmos()
 findOrMakeLabel()
 
+local previousEnabled = true
+
 local function Update(dt)
+	if not Gizmos.enabled then
+		if previousEnabled then
+			-- Just disabled, clear everything
+			wfh:Clear()
+			if label then
+				label.Text = ''
+			end
+			previousEnabled = false
+		end
+		commands = {}
+		return
+	end
+	previousEnabled = true
 	local t = tick()
 	if t ~= wfh:GetAttribute('lastUpdateTime') then
 		wfh:SetAttribute('lastUpdateTime', t)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@rbxts/gizmos",
-	"version": "1.0.0",
+	"version": "1.2.0",
 	"description": "TypeScript port of sg3cko's Gizmos library - Debug drawing utilities for Roblox including shapes, raycasts, paths, and world-space text.",
 	"main": "out/init.lua",
 	"scripts": {