@rbxts/gizmos 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Colin Miller
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# @rbxts/gizmos
+
+Debug drawing library for Roblox with support for lines, rays, shapes, raycasts, and more.
+
+## Credits
+
+Original Luau implementation by **sg3cko**  
+[DevForum Post](https://devforum.roblox.com/t/roblox-gizmos-for-debug-drawing-now-available/3294608)
+
+TypeScript package by Colin Miller (SnarlyZoo)
+
+## Installation
+
+```bash
+npm install @rbxts/gizmos
+```
+
+## Usage
+
+```typescript
+import Gizmos from "@rbxts/gizmos";
+
+// Draw colored shapes
+Gizmos.setColor("red");
+Gizmos.drawLine(Vector3.zero, new Vector3(0, 10, 0));
+
+Gizmos.setColor("blue");
+Gizmos.drawSphere(new Vector3(5, 5, 5), 2);
+
+// Visualize raycasts
+const params = new RaycastParams();
+const result = workspace.Raycast(origin, direction, params);
+Gizmos.drawRaycast(origin, direction, result);
+
+// Draw text in world space
+Gizmos.drawText(new Vector3(0, 10, 0), "Player spawn point");
+
+// Log to screen
+Gizmos.log("Frame:", tick());
+```
+
+## Features
+
+- **Shapes**: Lines, rays, paths, points, cubes, circles, spheres, pyramids
+- **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)
+- **Trailing paths**: Track object movement over time
+- **Auto-clearing**: Automatically clears each frame (configurable)
+
+## API
+
+### Drawing
+
+- `setColor(color: string | Color3)` - Set drawing color
+- `setTransparency(value: number)` - Set transparency (0-1)
+- `drawLine(from: Vector3, to: Vector3)` - Draw a line
+- `drawRay(origin: Vector3, direction: Vector3)` - Draw a ray with arrow
+- `drawPath(points: Vector3[], closed?: boolean, dotsSize?: number)` - Draw connected path
+- `drawPoint(position: Vector3, size?: number)` - Draw point marker
+- `drawCube(position: Vector3 | CFrame, size: Vector3)` - Draw wireframe cube
+- `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
+- `drawCFrame(cf: CFrame, size?: number, color?: Color3)` - Draw CFrame axes
+
+### Raycasts
+
+- `drawRaycast(origin: Vector3, direction: Vector3, result?: RaycastResult)` - Visualize raycast
+- `drawSpherecast(origin: Vector3, radius: number, direction: Vector3, result?: RaycastResult)` - Visualize spherecast
+- `drawBlockcast(cf: CFrame, size: Vector3, direction: Vector3, result?: RaycastResult)` - Visualize blockcast
+
+### Text & Logging
+
+- `drawText(position: Vector3, ...args: unknown[])` - Draw text at world position
+- `log(...args: unknown[])` - Log to on-screen display
+
+### Utilities
+
+- `addToPath(name: string, position: Vector3, dotsSize?: number)` - Add point to trailing path
+- `forceUpdate()` - Manually clear and update gizmos
+- `test()` - Run visual test of all features
+
+### Properties
+
+- `clear: boolean` - Auto-clear each frame (default: true)
+
+## License
+
+MIT
+
+## Links
+
+- [Original DevForum Post](https://devforum.roblox.com/t/roblox-gizmos-for-debug-drawing-now-available/3294608)
+- [GitHub Repository](https://github.com/cmmiller26/rbxts-gizmos)

package/out/index.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Gizmos - Debug drawing library for Roblox
+ *
+ * Original Luau implementation by sg3cko
+ * https://devforum.roblox.com/t/roblox-gizmos-for-debug-drawing-now-available/3294608
+ *
+ * TypeScript package by Colin Miller (SnarlyZoo)
+ */
+
+interface Gizmos {
+	/**
+	 * Whether to automatically clear gizmos each frame
+	 * @default true
+	 */
+	clear: boolean;
+
+	/**
+	 * Set the color for subsequent draw calls
+	 * @param color Color name ('red', 'green', 'blue', 'yellow', 'cyan', 'magenta', 'orange', 'purple', 'white', 'gray', 'black') or Color3 value
+	 */
+	setColor(color: string | Color3): void;
+
+	/**
+	 * Set the transparency for subsequent draw calls
+	 * @param value Transparency value from 0 (opaque) to 1 (fully transparent)
+	 */
+	setTransparency(value: number): void;
+
+	/**
+	 * Draw a line between two points
+	 * @param from Start position
+	 * @param to End position
+	 */
+	drawLine(from: Vector3, to: Vector3): void;
+
+	/**
+	 * Draw a ray with an arrow head
+	 * @param origin Starting position of the ray
+	 * @param direction Direction and length of the ray
+	 */
+	drawRay(origin: Vector3, direction: Vector3): void;
+
+	/**
+	 * Draw a path connecting multiple points
+	 * @param points Array of Vector3 positions to connect
+	 * @param closed Whether to connect the last point back to the first
+	 * @param dotsSize Optional size of dots to draw at each point (0 = no dots)
+	 */
+	drawPath(points: Vector3[], closed?: boolean, dotsSize?: number): void;
+
+	/**
+	 * Draw a point marker at a position
+	 * @param position Location to draw the point
+	 * @param size Size of the point marker
+	 */
+	drawPoint(position: Vector3, size?: number): void;
+
+	/**
+	 * Draw a wireframe cube
+	 * @param position Center position or CFrame of the cube
+	 * @param size Size of the cube on each axis
+	 */
+	drawCube(position: Vector3 | CFrame, size: Vector3): void;
+
+	/**
+	 * Draw a wireframe circle
+	 * @param position Center position of the circle
+	 * @param radius Radius of the circle
+	 * @param normal Normal vector defining the circle's plane (defaults to Vector3.yAxis)
+	 */
+	drawCircle(position: Vector3, radius: number, normal?: Vector3): void;
+
+	/**
+	 * Draw a wireframe sphere
+	 * @param position Center position or CFrame of the sphere
+	 * @param radius Radius of the sphere
+	 */
+	drawSphere(position: Vector3 | CFrame, radius: number): void;
+
+	/**
+	 * Draw a wireframe pyramid
+	 * @param position Base center position or CFrame of the pyramid
+	 * @param size Size of the pyramid's base
+	 * @param height Height of the pyramid
+	 */
+	drawPyramid(position: Vector3 | CFrame, size: number, height: number): void;
+
+	/**
+	 * Draw a CFrame as colored axes (red = right, green = up, blue = -look)
+	 * @param cf CFrame to visualize
+	 * @param size Length of the axes
+	 * @param color Optional single color for all axes (defaults to RGB for XYZ)
+	 */
+	drawCFrame(cf: CFrame, size?: number, color?: Color3): void;
+
+	/**
+	 * Draw text at a world position
+	 * @param position World position to display the text
+	 * @param args Values to display (strings, numbers, Vector3, CFrame are automatically formatted)
+	 */
+	drawText(position: Vector3, ...args: unknown[]): void;
+
+	/**
+	 * Log text to the on-screen debug display
+	 * @param args Values to log (strings, numbers, Vector3, CFrame are automatically formatted)
+	 */
+	log(...args: unknown[]): void;
+
+	/**
+	 * Visualize a raycast with its result
+	 * @param origin Starting position of the raycast
+	 * @param direction Direction and maximum distance of the raycast
+	 * @param result RaycastResult (green if hit, red if miss)
+	 */
+	drawRaycast(origin: Vector3, direction: Vector3, result: RaycastResult | undefined): void;
+
+	/**
+	 * Visualize a spherecast with its result
+	 * @param origin Starting position of the spherecast
+	 * @param radius Radius of the sphere
+	 * @param direction Direction and maximum distance of the spherecast
+	 * @param result RaycastResult (green if hit, red if miss)
+	 */
+	drawSpherecast(origin: Vector3, radius: number, direction: Vector3, result: RaycastResult | undefined): void;
+
+	/**
+	 * Visualize a blockcast (box-shaped raycast) with its result
+	 * @param cf CFrame defining position and orientation of the block
+	 * @param size Size of the block on each axis
+	 * @param direction Direction and maximum distance of the blockcast
+	 * @param result RaycastResult (green if hit, red if miss)
+	 */
+	drawBlockcast(cf: CFrame, size: Vector3, direction: Vector3, result: RaycastResult | undefined): void;
+
+	/**
+	 * Add a point to a named trailing path (useful for visualizing movement over time)
+	 * @param name Unique identifier for this path
+	 * @param position Position to add to the path
+	 * @param dotsSize Optional size of dots to draw at each point (0 = no dots)
+	 */
+	addToPath(name: string, position: Vector3, dotsSize?: number): void;
+
+	/**
+	 * Manually force an update and clear of all gizmos
+	 */
+	forceUpdate(): void;
+
+	/**
+	 * Run a visual test showcasing all gizmo drawing functions
+	 */
+	test(): void;
+}
+
+declare const Gizmos: Gizmos;
+export = Gizmos;

package/out/init.lua

@@ -0,0 +1,486 @@
+local Gizmos = {}
+
+local wfh: WireframeHandleAdornment = nil
+local label: TextLabel = nil
+local commands = {}
+local trailers = {}
+
+local hitColor, missColor = 'green', 'red'
+
+Gizmos.clear = true
+
+local colors = {
+	red     = Color3.new(1, 0, 0),
+	green   = Color3.new(0, 1, 0),
+	blue    = Color3.new(0, 0, 1),
+	yellow  = Color3.new(1, 1, 0),
+	cyan    = Color3.new(0, 1, 1),
+	magenta = Color3.new(1, 0, 1),
+	orange  = Color3.new(1, 0.5, 0),
+	purple  = Color3.new(0.5, 0, 1),
+	white   = Color3.new(1, 1, 1),
+	gray    = Color3.new(0.5, 0.5, 0.5),
+	black   = Color3.new(0, 0, 0),
+}
+
+local function findOrMakeGizmos()
+	wfh = wfh or workspace:FindFirstChild('Gizmos')
+	if not wfh then
+		wfh = Instance.new('WireframeHandleAdornment')
+		wfh.Name = 'Gizmos'
+		wfh.Parent = workspace
+		assert(workspace.WorldPivot:FuzzyEq(CFrame.identity), 'workspace is expected to have identity CFrame')
+		wfh.Color3 = Color3.new(1, 1, 1)
+		wfh.Adornee = workspace
+		wfh.AlwaysOnTop = true
+	end
+end
+
+local function helper_getGui()
+	local localPlayer = game:GetService('Players').LocalPlayer
+	if localPlayer then
+		return localPlayer:WaitForChild('PlayerGui', 3)
+	else
+		return game:GetService('StarterGui')
+	end
+end
+
+local function findOrMakeLabel()
+	local gui = helper_getGui()
+	if not gui then return end
+	label = gui:FindFirstChild('TextLabelGizmos', true)
+	if not label then
+		local screengui = Instance.new('ScreenGui', gui)
+		screengui.Name = 'ScreenGuiGizmos'
+		label = Instance.new('TextLabel', screengui)
+		label.Name = 'TextLabelGizmos'
+		label.BackgroundTransparency = 1
+		label.Position = UDim2.new(0, 10, 1, -10)
+		label.AnchorPoint = Vector2.new(0,1)
+		label.TextXAlignment = Enum.TextXAlignment.Left
+		label.TextYAlignment = Enum.TextYAlignment.Bottom
+		label.FontFace = Font.fromEnum(Enum.Font.RobotoMono)
+		label.TextColor3 = Color3.new(1,1,1)
+		label.TextStrokeColor3 = Color3.new(0,0,0)
+		label.TextStrokeTransparency = 0.5
+		label.TextSize = 14
+	end
+end
+
+local Trailer = {}
+Trailer.__index = Trailer
+
+function Trailer.new(limit)
+	local defaultLimit = 300
+	local self = setmetatable({}, Trailer)
+	self.limit = limit or defaultLimit
+	self.values = {}
+	return self
+end
+
+function Trailer:addValue(value)
+	table.insert(self.values, value)
+	if #self.values > self.limit then
+		table.remove(self.values, 1)
+	end
+end
+
+function Trailer:getValues()
+	return self.values
+end
+
+local function setColor(color: string | Color3)
+	local color3 = if typeof(color) == 'string' then colors[color] else color
+	wfh.Color3 = color3
+end
+
+local function setTransparency(value: number)
+	wfh.Transparency = value
+end
+
+local function drawLine(from: Vector3, to: Vector3)
+	wfh:AddLine(from, to)
+end
+
+local function helper_getPerpendicularVector(v: Vector3): Vector3
+	local perp: Vector3 = Vector3.new(-v.y, v.x, 0)
+	if perp.Magnitude == 0 then
+		perp = Vector3.new(0, -v.z, v.y)
+	end
+	return perp.Unit
+end
+
+local function drawRay(origin: Vector3, direction: Vector3)
+	local endPoint = origin + direction
+	wfh:AddLine(origin, endPoint)
+
+	local arrowLength, arrowAngle = direction.Magnitude/20, math.rad(30)
+
+	local dir = direction.Unit
+	local perp = helper_getPerpendicularVector(dir)
+	local left  = endPoint - dir * arrowLength + perp * arrowLength * math.tan(arrowAngle)
+	local right = endPoint - dir * arrowLength - perp * arrowLength * math.tan(arrowAngle)
+	wfh:AddLine(endPoint, left)
+	wfh:AddLine(endPoint, right)
+end
+
+local function drawPath(points: {Vector3}, closed: boolean?, dotsSize: number?)
+	closed = closed or false
+	dotsSize = dotsSize or 0
+	wfh:AddPath(points, closed)
+	if dotsSize > 0 then
+		for _, point in ipairs(points) do
+			drawCube(point, Vector3.one * dotsSize)
+		end
+	end
+end
+
+local function drawPoint(pos: Vector3, size: number?)
+	size = size or 0.1
+	wfh:AddLines({
+		pos - Vector3.xAxis * size, pos + Vector3.xAxis * size, 
+		pos - Vector3.yAxis * size, pos + Vector3.yAxis * size, 
+		pos - Vector3.zAxis * size, pos + Vector3.zAxis * size})
+end
+
+local function drawCube(pos: Vector3 | CFrame, size: Vector3)
+	local cf = if typeof(pos) == 'Vector3' then CFrame.new(pos) else pos
+	local halfSize = size * 0.5
+	local min = -halfSize
+	local max = halfSize
+	local v = {
+		cf * min,
+		cf * Vector3.new(max.x, min.y, min.z),
+		cf * Vector3.new(max.x, min.y, max.z),
+		cf * Vector3.new(min.x, min.y, max.z),
+		cf * Vector3.new(min.x, max.y, min.z),
+		cf * Vector3.new(max.x, max.y, min.z),
+		cf * max,
+		cf * Vector3.new(min.x, max.y, max.z),
+	}
+	wfh:AddLines({
+		v[1], v[2],
+		v[2], v[3],
+		v[3], v[4],
+		v[4], v[1],
+		v[5], v[6],
+		v[6], v[7],
+		v[7], v[8],
+		v[8], v[5],
+		v[1], v[5],
+		v[2], v[6],
+		v[3], v[7],
+		v[4], v[8],
+	})
+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 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)
+	end
+	wfh:AddPath(points, true)
+end
+
+local function drawSphere(pos: Vector3 | CFrame, radius: number)
+	local cf = if typeof(pos) == 'Vector3' then CFrame.new(pos) else pos
+	drawCircle(cf.Position, radius, cf.Rotation * Vector3.xAxis)
+	drawCircle(cf.Position, radius, cf.Rotation * Vector3.yAxis)
+	drawCircle(cf.Position, radius, cf.Rotation * Vector3.zAxis)
+end
+
+local function drawPyramid(pos: Vector3 | CFrame, size: number, height: number)
+	local cf = if typeof(pos) == 'Vector3' then CFrame.new(pos) else pos
+	local hsize = size/2
+	local points = {
+		cf * Vector3.new( hsize, 0,  hsize),
+		cf * Vector3.new(-hsize, 0,  hsize),
+		cf * Vector3.new(-hsize, 0, -hsize),
+		cf * Vector3.new( hsize, 0, -hsize),
+		cf * Vector3.new(0, height, 0),
+	}
+	wfh:AddPath({points[1], points[2], points[3], points[4], points[1], points[5], points[2]}, false)
+	wfh:AddPath({points[3], points[5], points[4]}, false)
+end
+
+local function drawCFrame(cf: CFrame, size: number, color: Color3)
+	size = size or 1
+	local color3 = wfh.Color3
+	local pos = cf.Position
+	if color ~= nil then
+		setColor(color)
+		drawLine(pos, pos + cf.RightVector * size)
+		drawLine(pos, pos + cf.UpVector * size)
+		drawLine(pos, pos + -cf.LookVector * size)
+	else
+		setColor('red')
+		drawLine(pos, pos + cf.RightVector * size)
+		setColor('green')
+		drawLine(pos, pos + cf.UpVector * size)
+		setColor('blue')
+		drawLine(pos, pos + -cf.LookVector * size)
+	end
+	wfh.Color3 = color3
+end
+
+local function helper_formatText(...)
+	local args = {...}
+	local text = ''
+	for _, v in ipairs(args) do
+		local str
+		if typeof(v) == 'string' then
+			str = v
+		elseif typeof(v) == 'number' then
+			str = string.format('%.3f', v)
+		elseif typeof(v) == 'Vector3' then
+			str = string.format('(%.3f, %.3f, %.3f)', v.x, v.y, v.z)
+		elseif typeof(v) == 'CFrame' then
+			local rx,ry,rz = v:ToOrientation()
+			rx, ry, rz = math.deg(rx), math.deg(ry), math.deg(rz)
+			local pos = v.Position
+			str = string.format('pos=(%.3f, %.3f, %.3f) rot=(%.3f, %.3f, %.3f)', pos.x, pos.y, pos.z, rx, ry, rz)
+		else
+			str = tostring(v)
+		end
+		text = text .. ' ' .. str
+	end
+	return text
+end
+
+local function drawText(position: Vector3, ...)
+	local args = {...}
+	local text = helper_formatText(unpack(args))
+	local size = nil
+	wfh:AddText(position, text, size)
+end
+
+local function log(...)
+	if label then
+		local args = {...}
+		local text = helper_formatText(unpack(args))
+		label.Text = label.Text .. '\n' .. text
+	end
+end
+
+local function helper_drawHit(hit: RaycastResult)
+	drawCircle(hit.Position, 0.15, hit.Normal)
+	drawRay(hit.Position, hit.Normal * 0.3)
+end
+
+local function helper_drawRaycast(cf: CFrame, direction: Vector3, result: RaycastResult, shape: number, size: number | Vector3)
+	local color3 = wfh.Color3
+	local travel
+	if result then
+		setColor(hitColor)
+		travel = direction.Unit * result.Distance
+		helper_drawHit(result)
+	else
+		setColor(missColor)
+		travel = direction
+	end
+	if shape == 1 then
+		drawSphere(cf, size)
+		drawSphere(cf + travel, size)
+	elseif shape == 2 then
+		drawCube(cf, size)
+		drawCube(cf + travel, size)
+	end
+	drawRay(cf.Position, travel)
+	wfh.Color3 = color3
+end
+
+local function drawRaycast(origin: Vector3, direction: Vector3, result: RaycastResult)
+	helper_drawRaycast(CFrame.new(origin), direction, result, 0)
+end
+
+local function drawSpherecast(origin: Vector3, radius: number, direction: Vector3, result: RaycastResult)
+	helper_drawRaycast(CFrame.lookAlong(origin, direction), direction, result, 1, radius)
+end
+
+local function drawBlockcast(cf: CFrame, size: Vector3, direction: Vector3, result: RaycastResult)
+	helper_drawRaycast(cf, direction, result, 2, size)
+end
+
+function Gizmos:setColor(color: string | Color3)
+	table.insert(commands, function()
+		setColor(color)
+	end)
+end
+
+function Gizmos:setTransparency(value: number)
+	table.insert(commands, function()
+		setTransparency(value)
+	end)
+end
+
+function Gizmos:drawLine(from: Vector3, to: Vector3)
+	table.insert(commands, function()
+		drawLine(from, to)
+	end)
+end
+
+function Gizmos:drawRay(origin: Vector3, direction: Vector3)
+	table.insert(commands, function()
+		drawRay(origin, direction)
+	end)
+end
+
+function Gizmos:drawPath(points: {Vector3}, closed: boolean?, dotsSize: number?)
+	table.insert(commands, function()
+		drawPath(points, closed, dotsSize)
+	end)
+end
+
+function Gizmos:drawPoint(position: Vector3, size: number?)
+	table.insert(commands, function()
+		drawPoint(position, size)
+	end)
+end
+
+function Gizmos:drawCube(position: Vector3 | CFrame, size: Vector3)
+	table.insert(commands, function()
+		drawCube(position, size)
+	end)
+end
+
+function Gizmos:drawCircle(position: Vector3, radius: number, normal: Vector3?)
+	table.insert(commands, function()
+		drawCircle(position, radius, normal)
+	end)
+end
+
+function Gizmos:drawSphere(position: Vector3 | CFrame, radius: number)
+	table.insert(commands, function()
+		drawSphere(position, radius)
+	end)
+end
+
+function Gizmos:drawPyramid(position: Vector3 | CFrame, size: number, height: number)
+	table.insert(commands, function()
+		drawPyramid(position, size, height)
+	end)
+end
+
+function Gizmos:drawCFrame(cf: CFrame, size: number?, color: Color3?)
+	table.insert(commands, function()
+		drawCFrame(cf, size, color)
+	end)
+end
+
+function Gizmos:drawText(position: Vector3, ...)
+	local args = {...}
+	table.insert(commands, function()
+		drawText(position, unpack(args))
+	end)
+end
+
+function Gizmos:log(...)
+	local args = {...}
+	table.insert(commands, function()
+		log(unpack(args))
+	end)
+end
+
+function Gizmos:drawRaycast(origin: Vector3, direction: Vector3, result: RaycastResult)
+	table.insert(commands, function()
+		drawRaycast(origin, direction, result)
+	end)
+end
+
+function Gizmos:drawSpherecast(origin: Vector3, radius: number, direction: Vector3, result: RaycastResult)
+	table.insert(commands, function()
+		drawSpherecast(origin, radius, direction, result)
+	end)
+end
+
+function Gizmos:drawBlockcast(cf: CFrame, size: Vector3, direction: Vector3, result: RaycastResult)
+	table.insert(commands, function()
+		drawBlockcast(cf, size, direction, result)
+	end)
+end
+
+function Gizmos:addToPath(name: string, position: Vector3, dotsSize: number?)
+	if not trailers[name] then
+		trailers[name] = Trailer.new()
+	end
+	trailers[name]:addValue(position)
+	table.insert(commands, function()
+		drawPath(trailers[name]:getValues(), false, dotsSize)
+	end)
+end
+
+function Gizmos:forceUpdate()
+	wfh:Clear()
+	if label then
+		label.Text = ''
+	end
+	for _, command in ipairs(commands) do
+		command()
+	end
+	commands = {}
+end
+
+function Gizmos:test()
+	local p = Vector3.new(0, 0, 10)
+	local x, y, z = Vector3.xAxis, Vector3.yAxis, Vector3.zAxis
+	local function n() p += Vector3.xAxis*2 end
+
+	Gizmos:setColor('white')
+	Gizmos:setTransparency(0)
+	Gizmos:drawLine(p, p + y) n()
+	Gizmos:drawRay(p, y) n()
+	Gizmos:drawPath({ p+Vector3.new(-0.3,0,-0.3), p+Vector3.new(0.4,0,0), p+Vector3.new(0.1,0,0.5), p+Vector3.new(0.6,0,0.9)}) n()
+	Gizmos:drawPoint(p) n()
+	Gizmos:drawCube(p + y*0.5, Vector3.one) n()
+	Gizmos:drawCircle(p, 0.5) n()
+	Gizmos:drawSphere(p+y*0.5, 0.5) n()
+	Gizmos:drawPyramid(p, 1, 1) n()
+	Gizmos:drawCFrame(CFrame.new(p)) n()
+	Gizmos:drawText(p, 'Hello') n()
+	Gizmos:drawRaycast(p, z, nil) n()
+	Gizmos:drawSpherecast(p, 0.3, z, nil) n()
+	Gizmos:drawBlockcast(CFrame.new(p), Vector3.one*0.6, z, nil) n()
+	Gizmos:log('Log')
+
+	local colors = {'red', 'orange', 'yellow', 'green', 'cyan', 'blue', 'purple', 'magenta', 'black', 'gray', 'white'}
+	p = Vector3.new(0, 0, 12)
+	for _, color in ipairs(colors) do
+		Gizmos:setColor(color)
+		Gizmos:drawCircle(p, 0.15)
+		p += Vector3.xAxis*1
+	end
+end
+
+findOrMakeGizmos()
+findOrMakeLabel()
+
+local function Update(dt)
+	local t = tick()
+	if t ~= wfh:GetAttribute('lastUpdateTime') then
+		wfh:SetAttribute('lastUpdateTime', t)
+		if Gizmos.clear then
+			wfh:Clear()
+			if label then
+				label.Text = ''
+			end
+		end
+	end
+	for _, command in ipairs(commands) do
+		command()
+	end
+	commands = {}
+end
+
+local RunService = game:GetService('RunService')
+if RunService:IsRunning() then
+	RunService:BindToRenderStep('name', Enum.RenderPriority.Camera.Value-1, Update)
+end
+
+return Gizmos

package/package.json

@@ -0,0 +1,40 @@
+{
+	"name": "@rbxts/gizmos",
+	"version": "1.0.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": {
+		"build": "rbxtsc",
+		"watch": "rbxtsc -w",
+		"prepublishOnly": "npm run build"
+	},
+	"keywords": [],
+	"author": "Colin Miller",
+	"license": "MIT",
+	"type": "commonjs",
+	"types": "out/index.d.ts",
+	"files": [
+		"out",
+		"!**/*.tsbuildinfo"
+	],
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/cmmiller26/rbxts-gizmos.git"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@rbxts/compiler-types": "^3.0.0-types.0",
+		"@rbxts/types": "^1.0.891",
+		"@typescript-eslint/eslint-plugin": "^8.46.4",
+		"@typescript-eslint/parser": "^8.46.4",
+		"eslint": "^9.39.1",
+		"eslint-config-prettier": "^10.1.8",
+		"eslint-plugin-prettier": "^5.5.4",
+		"eslint-plugin-roblox-ts": "^1.3.0",
+		"prettier": "^3.6.2",
+		"roblox-ts": "^3.0.0",
+		"typescript": "^5.9.3"
+	}
+}