@boyangsicwastaken/muchachohitbox 1.0.0

package/index.d.ts

@@ -0,0 +1,53 @@
+interface SignalConnection {
+	Connected: boolean;
+	Disconnect(): void;
+	Destroy(): void;
+}
+
+interface Signal<T extends unknown[]> {
+	Fire(...args: T): void;
+	FireDeferred(...args: T): void;
+	Connect(fn: (...args: T) => void): SignalConnection;
+	Once(fn: (...args: T) => void): SignalConnection;
+	DisconnectAll(): void;
+	GetConnections(): SignalConnection[];
+	Destroy(): void;
+	Wait(): LuaTuple<T>;
+}
+
+type DetectionMode = "Default" | "ConstantDetection" | "HitOnce" | "HitParts";
+
+interface Hitbox {
+	Visualizer: boolean;
+	VisualizerColor: Color3;
+	VisualizerTransparency: number;
+
+	DetectionMode: DetectionMode;
+	AutoDestroy: boolean;
+	Key: string;
+
+	OverlapParams: OverlapParams;
+
+	Size: Vector3 | number;
+	Shape: Enum.PartType;
+	CFrame: CFrame | BasePart;
+	Offset: CFrame;
+
+	VelocityPrediction: boolean;
+	VelocityPredictionTime: number;
+
+	Touched: Signal<[hit: BasePart, humanoid: Humanoid | undefined]>;
+	TouchEnded: Signal<[part: BasePart]>;
+
+	Start(): void;
+	Stop(): void;
+	Destroy(): void;
+}
+
+interface MuchachoHitbox {
+	CreateHitbox(): Hitbox;
+	FindHitbox(key: string): Hitbox | undefined;
+}
+
+declare const MuchachoHitbox: MuchachoHitbox;
+export = MuchachoHitbox;

package/out/DictDiff.luau

@@ -0,0 +1,20 @@
+local module = {}
+
+local function find(a, tbl)
+	for _, a_ in ipairs(tbl) do 
+		if a_==a then return true end 
+	end
+end
+
+function module.difference(a, b)
+	local ret = {}
+	for _, v in ipairs(a) do
+		if not find(v,b) then table.insert(ret, v) end
+	end
+	
+	return ret
+end
+
+
+return module
+

package/out/GoodSignal.luau

@@ -0,0 +1,429 @@
+-- -----------------------------------------------------------------------------
+--               Batched Yield-Safe Signal Implementation                     --
+-- This is a Signal class which has effectively identical behavior to a       --
+-- normal RBXScriptSignal, with the only difference being a couple extra      --
+-- stack frames at the bottom of the stack trace when an error is thrown.     --
+-- This implementation caches runner coroutines, so the ability to yield in   --
+-- the signal handlers comes at minimal extra cost over a naive signal        --
+-- implementation that either always or never spawns a thread.                --
+--                                                                            --
+-- License:                                                                   --
+--   Licensed under the MIT license.                                          --
+--                                                                            --
+-- Authors:                                                                   --
+--   stravant - July 31st, 2021 - Created the file.                           --
+--   sleitnick - August 3rd, 2021 - Modified for Knit.                        --
+-- -----------------------------------------------------------------------------
+
+-- Signal types
+export type Connection = {
+	Disconnect: (self: Connection) -> (),
+	Destroy: (self: Connection) -> (),
+	Connected: boolean,
+}
+
+export type Signal<T...> = {
+	Fire: (self: Signal<T...>, T...) -> (),
+	FireDeferred: (self: Signal<T...>, T...) -> (),
+	Connect: (self: Signal<T...>, fn: (T...) -> ()) -> Connection,
+	Once: (self: Signal<T...>, fn: (T...) -> ()) -> Connection,
+	DisconnectAll: (self: Signal<T...>) -> (),
+	GetConnections: (self: Signal<T...>) -> { Connection },
+	Destroy: (self: Signal<T...>) -> (),
+	Wait: (self: Signal<T...>) -> T...,
+}
+
+-- The currently idle thread to run the next handler on
+local freeRunnerThread = nil
+
+-- Function which acquires the currently idle handler runner thread, runs the
+-- function fn on it, and then releases the thread, returning it to being the
+-- currently idle one.
+-- If there was a currently idle runner thread already, that's okay, that old
+-- one will just get thrown and eventually GCed.
+local function acquireRunnerThreadAndCallEventHandler(fn, ...)
+	local acquiredRunnerThread = freeRunnerThread
+	freeRunnerThread = nil
+	fn(...)
+	-- The handler finished running, this runner thread is free again.
+	freeRunnerThread = acquiredRunnerThread
+end
+
+-- Coroutine runner that we create coroutines of. The coroutine can be
+-- repeatedly resumed with functions to run followed by the argument to run
+-- them with.
+local function runEventHandlerInFreeThread(...)
+	acquireRunnerThreadAndCallEventHandler(...)
+	while true do
+		acquireRunnerThreadAndCallEventHandler(coroutine.yield())
+	end
+end
+
+--[=[
+	@within Signal
+	@interface SignalConnection
+	.Connected boolean
+	.Disconnect (SignalConnection) -> ()
+
+	Represents a connection to a signal.
+	```lua
+	local connection = signal:Connect(function() end)
+	print(connection.Connected) --> true
+	connection:Disconnect()
+	print(connection.Connected) --> false
+	```
+]=]
+
+-- Connection class
+local Connection = {}
+Connection.__index = Connection
+
+function Connection:Disconnect()
+	if not self.Connected then
+		return
+	end
+	self.Connected = false
+
+	-- Unhook the node, but DON'T clear it. That way any fire calls that are
+	-- currently sitting on this node will be able to iterate forwards off of
+	-- it, but any subsequent fire calls will not hit it, and it will be GCed
+	-- when no more fire calls are sitting on it.
+	if self._signal._handlerListHead == self then
+		self._signal._handlerListHead = self._next
+	else
+		local prev = self._signal._handlerListHead
+		while prev and prev._next ~= self do
+			prev = prev._next
+		end
+		if prev then
+			prev._next = self._next
+		end
+	end
+end
+
+Connection.Destroy = Connection.Disconnect
+
+-- Make Connection strict
+setmetatable(Connection, {
+	__index = function(_tb, key)
+		error(("Attempt to get Connection::%s (not a valid member)"):format(tostring(key)), 2)
+	end,
+	__newindex = function(_tb, key, _value)
+		error(("Attempt to set Connection::%s (not a valid member)"):format(tostring(key)), 2)
+	end,
+})
+
+--[=[
+	@within Signal
+	@type ConnectionFn (...any) -> ()
+
+	A function connected to a signal.
+]=]
+
+--[=[
+	@class Signal
+
+	A Signal is a data structure that allows events to be dispatched
+	and observed.
+
+	This implementation is a direct copy of the de facto standard, [GoodSignal](https://devforum.roblox.com/t/lua-signal-class-comparison-optimal-goodsignal-class/1387063),
+	with some added methods and typings.
+
+	For example:
+	```lua
+	local signal = Signal.new()
+
+	-- Subscribe to a signal:
+	signal:Connect(function(msg)
+		print("Got message:", msg)
+	end)
+
+	-- Dispatch an event:
+	signal:Fire("Hello world!")
+	```
+]=]
+local Signal = {}
+Signal.__index = Signal
+
+--[=[
+	Constructs a new Signal
+
+	@return Signal
+]=]
+function Signal.new<T...>(): Signal<T...>
+	local self = setmetatable({
+		_handlerListHead = false,
+		_proxyHandler = nil,
+		_yieldedThreads = nil,
+	}, Signal)
+
+	return self
+end
+
+--[=[
+	Constructs a new Signal that wraps around an RBXScriptSignal.
+
+	@param rbxScriptSignal RBXScriptSignal -- Existing RBXScriptSignal to wrap
+	@return Signal
+
+	For example:
+	```lua
+	local signal = Signal.Wrap(workspace.ChildAdded)
+	signal:Connect(function(part) print(part.Name .. " added") end)
+	Instance.new("Part").Parent = workspace
+	```
+]=]
+function Signal.Wrap<T...>(rbxScriptSignal: RBXScriptSignal): Signal<T...>
+	assert(
+		typeof(rbxScriptSignal) == "RBXScriptSignal",
+		"Argument #1 to Signal.Wrap must be a RBXScriptSignal; got " .. typeof(rbxScriptSignal)
+	)
+
+	local signal = Signal.new()
+	signal._proxyHandler = rbxScriptSignal:Connect(function(...)
+		signal:Fire(...)
+	end)
+
+	return signal
+end
+
+--[=[
+	Checks if the given object is a Signal.
+
+	@param obj any -- Object to check
+	@return boolean -- `true` if the object is a Signal.
+]=]
+function Signal.Is(obj: any): boolean
+	return type(obj) == "table" and getmetatable(obj) == Signal
+end
+
+--[=[
+	@param fn ConnectionFn
+	@return SignalConnection
+
+	Connects a function to the signal, which will be called anytime the signal is fired.
+	```lua
+	signal:Connect(function(msg, num)
+		print(msg, num)
+	end)
+
+	signal:Fire("Hello", 25)
+	```
+]=]
+function Signal:Connect(fn)
+	local connection = setmetatable({
+		Connected = true,
+		_signal = self,
+		_fn = fn,
+		_next = false,
+	}, Connection)
+
+	if self._handlerListHead then
+		connection._next = self._handlerListHead
+		self._handlerListHead = connection
+	else
+		self._handlerListHead = connection
+	end
+
+	return connection
+end
+
+--[=[
+	@deprecated v1.3.0 -- Use `Signal:Once` instead.
+	@param fn ConnectionFn
+	@return SignalConnection
+]=]
+function Signal:ConnectOnce(fn)
+	return self:Once(fn)
+end
+
+--[=[
+	@param fn ConnectionFn
+	@return SignalConnection
+
+	Connects a function to the signal, which will be called the next time the signal fires. Once
+	the connection is triggered, it will disconnect itself.
+	```lua
+	signal:Once(function(msg, num)
+		print(msg, num)
+	end)
+
+	signal:Fire("Hello", 25)
+	signal:Fire("This message will not go through", 10)
+	```
+]=]
+function Signal:Once(fn)
+	local connection
+	local done = false
+
+	connection = self:Connect(function(...)
+		if done then
+			return
+		end
+
+		done = true
+		connection:Disconnect()
+		fn(...)
+	end)
+
+	return connection
+end
+
+function Signal:GetConnections()
+	local items = {}
+
+	local item = self._handlerListHead
+	while item do
+		table.insert(items, item)
+		item = item._next
+	end
+
+	return items
+end
+
+-- Disconnect all handlers. Since we use a linked list it suffices to clear the
+-- reference to the head handler.
+--[=[
+	Disconnects all connections from the signal.
+	```lua
+	signal:DisconnectAll()
+	```
+]=]
+function Signal:DisconnectAll()
+	local item = self._handlerListHead
+	while item do
+		item.Connected = false
+		item = item._next
+	end
+	self._handlerListHead = false
+
+	local yieldedThreads = rawget(self, "_yieldedThreads")
+	if yieldedThreads then
+		for thread in yieldedThreads do
+			if coroutine.status(thread) == "suspended" then
+				warn(debug.traceback(thread, "signal disconnected; yielded thread cancelled", 2))
+				task.cancel(thread)
+			end
+		end
+		table.clear(self._yieldedThreads)
+	end
+end
+
+-- Signal:Fire(...) implemented by running the handler functions on the
+-- coRunnerThread, and any time the resulting thread yielded without returning
+-- to us, that means that it yielded to the Roblox scheduler and has been taken
+-- over by Roblox scheduling, meaning we have to make a new coroutine runner.
+--[=[
+	@param ... any
+
+	Fire the signal, which will call all of the connected functions with the given arguments.
+	```lua
+	signal:Fire("Hello")
+
+	-- Any number of arguments can be fired:
+	signal:Fire("Hello", 32, {Test = "Test"}, true)
+	```
+]=]
+function Signal:Fire(...)
+	local item = self._handlerListHead
+	while item do
+		if item.Connected then
+			if not freeRunnerThread then
+				freeRunnerThread = coroutine.create(runEventHandlerInFreeThread)
+			end
+			task.spawn(freeRunnerThread, item._fn, ...)
+		end
+		item = item._next
+	end
+end
+
+--[=[
+	@param ... any
+
+	Same as `Fire`, but uses `task.defer` internally & doesn't take advantage of thread reuse.
+	```lua
+	signal:FireDeferred("Hello")
+	```
+]=]
+function Signal:FireDeferred(...)
+	local item = self._handlerListHead
+	while item do
+		local conn = item
+		task.defer(function(...)
+			if conn.Connected then
+				conn._fn(...)
+			end
+		end, ...)
+		item = item._next
+	end
+end
+
+--[=[
+	@return ... any
+	@yields
+
+	Yields the current thread until the signal is fired, and returns the arguments fired from the signal.
+	Yielding the current thread is not always desirable. If the desire is to only capture the next event
+	fired, using `Once` might be a better solution.
+	```lua
+	task.spawn(function()
+		local msg, num = signal:Wait()
+		print(msg, num) --> "Hello", 32
+	end)
+	signal:Fire("Hello", 32)
+	```
+]=]
+function Signal:Wait()
+	local yieldedThreads = rawget(self, "_yieldedThreads")
+	if not yieldedThreads then
+		yieldedThreads = {}
+		rawset(self, "_yieldedThreads", yieldedThreads)
+	end
+
+	local thread = coroutine.running()
+	yieldedThreads[thread] = true
+
+	self:Once(function(...)
+		yieldedThreads[thread] = nil
+		task.spawn(thread, ...)
+	end)
+
+	return coroutine.yield()
+end
+
+--[=[
+	Cleans up the signal.
+
+	Technically, this is only necessary if the signal is created using
+	`Signal.Wrap`. Connections should be properly GC'd once the signal
+	is no longer referenced anywhere. However, it is still good practice
+	to include ways to strictly clean up resources. Calling `Destroy`
+	on a signal will also disconnect all connections immediately.
+	```lua
+	signal:Destroy()
+	```
+]=]
+function Signal:Destroy()
+	self:DisconnectAll()
+
+	local proxyHandler = rawget(self, "_proxyHandler")
+	if proxyHandler then
+		proxyHandler:Disconnect()
+	end
+end
+
+-- Make signal strict
+setmetatable(Signal, {
+	__index = function(_tb, key)
+		error(("Attempt to get Signal::%s (not a valid member)"):format(tostring(key)), 2)
+	end,
+	__newindex = function(_tb, key, _value)
+		error(("Attempt to set Signal::%s (not a valid member)"):format(tostring(key)), 2)
+	end,
+})
+
+return table.freeze({
+	new = Signal.new,
+	Wrap = Signal.Wrap,
+	Is = Signal.Is,
+})

package/out/Types.luau

@@ -0,0 +1,61 @@
+local Goodsignal = require(script.Parent.GoodSignal)
+
+local types = {}
+
+export type HitboxProperties = {
+	Visualizer: boolean,
+	DetectionMode: ("Default" | "ConstantDetection" | "HitOnce" | "HitParts"),
+	AutoDestroy: boolean,	
+	Key: string,
+
+	OverlapParams: OverlapParams,
+
+	Size: Vector3,
+	Shape: Enum.PartType,
+	CFrame: CFrame,
+	Offset: CFrame,
+
+	VelocityPredictionTime: number?,
+	VelocityPrediction: boolean?,
+	
+	Touched: Goodsignal.Signal<BasePart, Humanoid?>,
+	TouchEnded: Goodsignal.Signal<BasePart, Humanoid?>,
+} & any
+
+export type Hitbox = {
+	-- properties
+	Visualizer: boolean,
+	VisualizerColor: Color3?,
+	VisualizerTransparency: number,
+	
+	DetectionMode: ("Default" | "ConstantDetection" | "HitOnce" | "HitParts"),
+	AutoDestroy: boolean,	
+	Key: string,
+
+	OverlapParams: OverlapParams,
+
+	Size: Vector3,
+	Shape: Enum.PartType,
+	CFrame: CFrame,
+	Offset: CFrame,
+	
+	VelocityPredictionTime: number?,
+	VelocityPrediction: boolean?,
+	
+	-- events
+	Touched: Goodsignal.Signal<BasePart, Humanoid?>,
+	TouchEnded: Goodsignal.Signal<BasePart, Humanoid?>,
+	
+	-- methods
+	Start: (self: Hitbox) -> (),
+	Stop: (self: Hitbox) -> (),
+	Destroy: (self: Hitbox) -> (boolean),
+
+	-- dev
+	HitList: {Model}?,
+	TouchingParts: {BasePart}?,
+	Connection: RBXScriptConnection?,
+	Box: BoxHandleAdornment? | SphereHandleAdornment?,
+} & any
+
+return types

package/out/index.d.ts

@@ -0,0 +1 @@
+export {};

package/out/init.luau

@@ -0,0 +1,526 @@
+--!strict
+
+--[[
+
+
+   _____            __    _ __  ___           __
+  / ___/__  _______/ /_  (_)  |/  /___ ______/ /____  _____
+  \__ \/ / / / ___/ __ \/ / /|_/ / __ `/ ___/ __/ _ \/ ___/
+ ___/ / /_/ (__  ) / / / / /  / / /_/ (__  ) /_/  __/ /
+/____/\__,_/____/_/ /_/_/_/  /_/\__,_/____/\__/\___/_/
+
+
+
+
+
+____________________________________________________________________________________________________________________________________________________________________________
+
+	[ UPDATE LOG v1.1 :]
+1. New property!!
+	Hitbox.Key = "insert anything you want here"
+		--- This property will be used for the new function | module:FindHitbox(key)
+
+2. New function!!
+	Module:FindHitbox(Key)
+		--- Returns a hitbox using specified Key, nil otherwise
+
+3. New detection mode! | "ConstantDetection"
+	Hitbox.DetectionMode = "ConstantDetection"
+		--- The same as the default detection mode but no hit pool / debounce
+		--- You're free to customize the debounce anyway you want
+
+4, Made the scripts cleaner
+____________________________________________________________________________________________________________________________________________________________________________
+
+	[ UPDATE LOG v1.2 :]
+1. Made the code better
+
+____________________________________________________________________________________________________________________________________________________________________________
+
+	[ UPDATE LOG v1.3 :]
+1. New property
+	HitboxObject.AutoDestroy = true (Default)
+		---  With the value being false you can keep using Stop()
+		and Start() without the hitbox being destroyed.
+
+2. New metamethod
+	HitboxObject:Destroy()
+		---  This destroys the hitbox. You only need to use this
+			 When having AutoDestroy's value set to false.
+
+3. Minor bug fixes
+
+____________________________________________________________________________________________________________________________________________________________________________
+
+	[ UPDATE LOG v1.4  Experimental:]
+1. New event
+	HitboxObject.TouchEnded:Connect(instance)
+				Description
+					--- The event fires once a part stops touching the hitbox
+				Arguments
+					--- Instance part: Returns the part that the hitbox stopped touching
+
+____________________________________________________________________________________________________________________________________________________________________________
+
+		 UPDATE LOG v1.5  Stable:]
+1. Reverted touch ended, will add back after the bug is fixed
+
+____________________________________________________________________________________________________________________________________________________________________________
+
+		 UPDATE LOG v1.6  Stable:]
+1. Touch ended is back! It has been fixed
+2. HitboxObject.Key is now generated automatically
+3. Minor changes
+
+____________________________________________________________________________________________________________________________________________________________________________
+
+		 UPDATE LOG v2.0 Experimental:]
+1. Added VelocityPrediction and VelocityPredictionTime property
+2. You can now set the color and transparency of a hitbox
+2. Minor fixes
+3. Code now uses type checking
+____________________________________________________________________________________________________________________________________________________________________________
+
+	Example code:
+		local module = require(game.ServerStorage.MuchachoHitbox)
+
+		local hitbox = module.CreateHitbox()
+		hitbox.Size = Vector3.new(10,10,10)
+		hitbox.CFrame = workspace.Part
+
+		-- IF YOU WANT TO ADD VELOCITY PREDICTION
+		hitbox.VelocityPrediction = true
+		hitbox.VelocityPredictionTime = .2
+
+		hitbox.Touched:Connect(function(hit, hum)
+			print(hit)
+			hum:TakeDamage(10)
+		end)
+
+		hitbox:Start()
+
+
+	Alright thats all for the example code, its a pretty simple module, you could make a module similar to this yourself.
+	And maybe even make it better.
+
+	If you encounter any bugs, please tell me in the comment section, or you could DM me on discord
+	sushimaster#7840
+
+	❤ SushiMaster
+____________________________________________________________________________________________________________________________________________________________________________
+
+
+	[MuchachoHitbox Documentation]
+
+		* local Module = require(MuchachoHitbox)
+				--- Require the module
+
+
+			[ FUNCTIONS ]
+
+		* Module.CreateHitbox()
+				Description
+					--- Creates a hitbox
+
+		* Module:FindHitbox(Key)
+				Description
+					--- Returns a hitbox with specified Key
+
+		* HitboxObject:Start()
+				Description
+					--- Starts the hitbox.
+
+		* HitboxObject:Stop()
+				Description
+					--- Stops the hitbox and resets the debounce.
+
+		* HitboxObject:Destroy()
+				Description
+					--- Destroys the hitbox. Use this when you have
+						HitboxObject.AutoDestroy set to false
+
+			[ EVENTS ]
+
+		* HitboxObject.Touched:Connect(hit, humanoid)
+				Description
+					--- If the hitbox touches a humanoid, it'll return information on them
+					--- The hitbox can detect parts depending on the detection mode
+				Arguments
+					--- Instance part: Returns the part that the hitbox hit first
+					--- Instance humanoid: Returns the Humanoid object
+
+		* HitboxObject.TouchEnded:Connect(instance)
+				Description
+					--- The event fires once a part stops touching the hitbox
+				Arguments
+					--- Instance part: Returns the part that the hitbox stopped touching
+
+			[ PROPERTIES ]
+
+		* HitboxObject.OverlapParams: OverlapParams
+				Description
+					--- Takes in a OverlapParams object
+
+		* HitboxObject.Visualizer: boolean
+				Description
+					--- Turns on or off the visualizer part
+
+		* HitboxObject.CFrame: CFrame / Instance
+				Description
+					--- Sets the hitbox CFrame to the CFrame
+					--- If its an instance, then the hitbox would follow the instance
+
+		* HitboxObject.Shape: Enum.PartType.Block / Enum.PartType.Ball
+				Description
+					--- Defaults to block
+					--- Sets the hitbox shape to the property
+
+		* HitboxObject.Size: Vector3 / number
+				Description
+					--- Sets the size of the hitbox
+					--- It uses Vector3 if the shape is block
+					--- It uses number if the shape is ball
+
+		* HitboxObject.Offset: CFrame
+				Description
+					--- Hitbox offset
+
+		* HitboxObject.DetectionMode: string | "Default" , "HitOnce" , "HitParts" , "ConstantDetection"
+				Description
+					--- Default value set to "Default"
+					--- Changes on how the detection works
+
+		* HitboxObject.Key: String
+				Description
+					--- The key property for the find hitbox function
+					--- MuchachoHitbox automatically generates a randomized key for you but you can change it. The module will save the hitbox, and can be found using | Module:FindHitbox(Key)
+
+		* HitboxObject.AutoDestroy: boolean
+				Description
+					--- Default value is set to true
+					--- When set to true, :Stop() atomatically destroys the hitbox.
+					--- Does not destroy the hitbox when set to false. You'll
+						have to use :Destroy() to delete the hitbox.
+
+		* HitboxObject.VelocityPrediction: boolean
+				Description
+					--- Default value is set to false
+					--- When set to true, hitbox automatically predicts the velocity of the CFrame property if it is an instance. By "VelocityPredictionTime" amount of time
+
+		* HitboxObject.VelocityPredictionTime: number
+				Description
+					--- Default value is set to 0.1
+					--- When "VelocityPrediction" is set to true, this property determines how far in the future the hitbox will check for parts.
+
+		* HitboxObject.VisualizerColor: Color3
+				Description
+					--- Sets the color of the visualizer part
+
+		* HitboxObject.VisualizerTransparency: number
+				Description
+					--- Sets the transparency of the visualizer part
+
+			[ DETECTION MODES ]
+
+		* Default
+				Description
+					--- Checks if a humanoid exists when this hitbox touches a part. The hitbox will not return humanoids it has already hit for the duration
+					--- the hitbox has been active.
+
+		* HitParts
+				Description
+					--- OnHit will return every hit part, regardless if it's ascendant has a humanoid or not.
+					--- OnHit will no longer return a humanoid so you will have to check it. The hitbox will not return parts it has already hit for the
+					--- duration the hitbox has been active.
+
+		* HitOnce
+				Description
+					--- Hitbox will stop as soon as it detects a humanoid
+
+		* ConstantDetection
+				Description
+					--- The default detection mode but no hitlist / debounce
+
+____________________________________________________________________________________________________________________________________________________________________________
+
+]]
+local rs = game:GetService("RunService")
+local hs = game:GetService("HttpService")
+
+local GoodSignal = require(script.GoodSignal)
+local DictDiff = require(script.DictDiff)
+local Types = require(script.Types)
+
+local muchacho_hitbox = {}
+muchacho_hitbox.__index = muchacho_hitbox
+
+local adornment_form = {
+	["Proportion"] = {
+		[Enum.PartType.Ball] = "Radius",
+		[Enum.PartType.Block] = "Size",
+	},
+
+	["Shape"] = {
+		[Enum.PartType.Ball] = "SphereHandleAdornment",
+		[Enum.PartType.Block] = "BoxHandleAdornment",
+	},
+}
+
+local get_CFrame = {
+	["Instance"] = function(point)
+		return point.CFrame
+	end,
+
+	["CFrame"] = function(point)
+		return point
+	end,
+}
+
+
+local hitboxes = {}
+
+-- public functions
+function muchacho_hitbox.CreateHitbox()
+	local self = setmetatable({}, muchacho_hitbox) :: Types.Hitbox
+	self.DetectionMode = "Default"
+	self.AutoDestroy = true
+
+	self.Visualizer = true
+	self.VisualizerColor = Color3.fromRGB(255,0,0)
+	self.VisualizerTransparency = .8
+
+	self.VelocityPrediction = false
+	self.VelocityPredictionTime = 0.1
+
+	self.OverlapParams = OverlapParams.new()
+
+	self.Size = Vector3.new(0,0,0)
+	self.Shape = Enum.PartType.Block
+	self.CFrame = CFrame.new(0,0,0)
+	self.Offset = CFrame.new(0,0,0)
+
+	self.Key = hs:GenerateGUID(false)
+
+	self.HitList = {}
+	self.TouchingParts = {}
+
+	self.Touched = GoodSignal.new()
+	self.TouchEnded = GoodSignal.new()
+
+	return self
+end
+
+function muchacho_hitbox:FindHitbox(key) -- deprecated
+	if hitboxes[key] then
+		return hitboxes[key]
+	else
+		return nil
+	end
+end
+
+-- public methods
+function muchacho_hitbox.Start(self: Types.Hitbox)
+	if hitboxes[self.Key] then
+		error("A hitbox with this Key has already been started. Change the key if you want to start this hitbox.")
+	end
+
+	hitboxes[self.Key] = self
+
+	-- looping the hitbox
+	task.spawn(function()
+		self._Connection = rs.Heartbeat:Connect(function()
+			self:_visualize()
+			self:_cast()
+		end)
+	end)
+end
+
+function muchacho_hitbox.Stop(self: Types.Hitbox)
+	local hitbox = muchacho_hitbox:FindHitbox(self.Key)
+
+	if not hitbox then
+		error("Hitbox has already been stopped")
+	end
+
+	-- clear hitbox
+	self:_clear()
+
+	if not self.AutoDestroy then return end
+
+	-- terminate hitbox
+	self.Touched:DisconnectAll()
+	self.TouchEnded:DisconnectAll()
+	--setmetatable(self, nil)
+end
+
+function muchacho_hitbox:Destroy()
+	local hitbox: Types.Hitbox = muchacho_hitbox:FindHitbox(self.Key)
+
+	if not hitbox then
+		error("Hitbox has already been destroyed")
+	end
+
+	-- clear hitbox
+	self:_clear()
+
+	-- terminate hitbox
+	self.Touched:DisconnectAll()
+	self.TouchEnded:DisconnectAll()
+	--setmetatable(self, nil)
+end
+
+
+-- private methods
+function muchacho_hitbox._CastSpatialQuery(self: Types.Hitbox) : {BasePart}?
+	local point_type: CFrame | string = typeof(self.CFrame)
+	local point_cframe: CFrame = self:_PredictVelocity() or get_CFrame[point_type](self.CFrame)
+
+	local parts
+	local hitboxCFrame: CFrame = point_cframe * self.Offset
+
+	if self.Shape == Enum.PartType.Block then
+		parts = workspace:GetPartBoundsInBox(hitboxCFrame, self.Size, self.OverlapParams)
+	elseif self.Shape == Enum.PartType.Ball then
+		parts = workspace:GetPartBoundsInRadius(hitboxCFrame.Position, self.Size, self.OverlapParams)
+	else
+		error("Part type: " .. self.Shape .. " isn't compatible with muchachoHitbox")
+	end
+
+	return parts
+end
+
+function muchacho_hitbox._cast(self: Types.Hitbox, part: BasePart)
+	local mode = self.DetectionMode
+	local parts = self:_CastSpatialQuery()
+
+	self:_FindTouchEnded(parts)
+
+	for _, hit in pairs(parts) do
+		local character: Model = hit:FindFirstAncestorOfClass("Model") or hit.Parent
+		local humanoid: Humanoid? = character:FindFirstChildOfClass("Humanoid")
+
+		-- detection mode
+		if mode == "Default" then
+			if humanoid and not table.find(self.HitList, humanoid) then
+				table.insert(self.HitList, humanoid)
+
+				self:_InsertTouchingParts(hit)
+
+				self.Touched:Fire(hit, humanoid)
+			end
+
+		elseif mode == "ConstantDetection" then
+
+			if humanoid then
+				self:_InsertTouchingParts(hit)
+
+				self.Touched:Fire(hit, humanoid)
+			end
+
+		elseif mode == "HitOnce" then
+
+			if humanoid then
+				self:_InsertTouchingParts(hit)
+
+				self.Touched:Fire(hit, humanoid)
+				self.TouchEnded:Fire(hit)
+
+				self:Destroy()
+				break
+			end
+
+		elseif mode == "HitParts" then
+			self:_InsertTouchingParts(hit)
+
+			self.Touched:Fire(hit, nil)
+
+		end
+	end
+end
+
+function muchacho_hitbox._visualize(self: Types.Hitbox)
+	if not self.Visualizer then return end
+
+	local predictedCFrame = self:_PredictVelocity()
+
+	local point_type: string = typeof(self.CFrame)
+	local point_cframe: CFrame = predictedCFrame or get_CFrame[point_type](self.CFrame)
+
+	local proportion = adornment_form.Proportion[self.Shape]
+
+	if not self._Box then
+		local newBox = Instance.new(adornment_form.Shape[self.Shape])
+		newBox.Name = "Visualizer"
+		newBox.Adornee = workspace.Terrain
+		newBox[proportion] = self.Size
+		newBox.CFrame = point_cframe * self.Offset
+		newBox.Color3 = self.VisualizerColor
+		newBox.Transparency = self.VisualizerTransparency
+		newBox.Parent = workspace.Terrain
+		self._Box = newBox
+	else
+		self._Box.CFrame = point_cframe * self.Offset
+	end
+end
+
+function muchacho_hitbox._PredictVelocity(self: Types.Hitbox): CFrame | nil
+	if self.VelocityPrediction then
+		local PredictionTime: number = self.VelocityPredictionTime
+		local part: BasePart = self.CFrame
+		local constant: number = 1/PredictionTime
+
+		if PredictionTime > 0 and typeof(part) == "Instance" then
+			--local velocityVector =  part.CFrame:VectorToObjectSpace(part.AssemblyLinearVelocity) / constant
+			--local predictedCFrame = part.CFrame * CFrame.new(velocityVector)
+			local Velocity = part.AssemblyLinearVelocity --// Normally this would be their ping
+			local PredictedPosition = part.Position + Velocity * PredictionTime
+			local PredictedCFrame = CFrame.new(PredictedPosition) * (part.CFrame - part.Position)
+
+
+			return PredictedCFrame
+		end
+	end
+
+	return nil
+end
+
+function muchacho_hitbox:_clear()
+	self.HitList = {}
+
+	if self._Connection then
+		self._Connection:Disconnect()
+	end
+
+	if self.Key then
+		hitboxes[self.Key] = nil
+	end
+
+	if self._Box then
+		self._Box:Destroy()
+		self.Box = nil
+	end
+end
+
+function muchacho_hitbox._InsertTouchingParts(self: Types.Hitbox, part)
+	if table.find(self.TouchingParts, part) then return end
+
+	table.insert(self.TouchingParts, part)
+end
+
+function muchacho_hitbox._FindTouchEnded(self: Types.Hitbox, parts: {BasePart}?)
+	if #self.TouchingParts == 0 then return end
+
+	local mode = self.DetectionMode
+	local differences = DictDiff.difference(self.TouchingParts, parts)
+
+	if differences then
+		for _, diff in ipairs(differences) do
+			self.TouchEnded:Fire(diff)
+			table.remove(self.TouchingParts, table.find(self.TouchingParts, diff))
+		end
+	end
+end
+
+
+
+return muchacho_hitbox

package/package.json

@@ -0,0 +1,29 @@
+{
+	"name": "@boyangsicwastaken/muchachohitbox",
+	"version": "1.0.0",
+	"description": "typescript port for muchachohitbox module",
+	"main": "out/init.luau",
+	"scripts": {
+		"build": "rbxtsc",
+		"watch": "rbxtsc -w"
+	},
+	"keywords": [],
+	"author": "",
+	"license": "ISC",
+	"types": "index.d.ts",
+	"files": [
+		"out",
+		"index.d.ts",
+		"!**/*.tsbuildinfo"
+	],
+	"publishConfig": {
+		"access": "public"
+	},
+	"devDependencies": {
+		"@rbxts/compiler-types": "^3.0.0-types.0",
+		"@rbxts/types": "^1.0.905",
+		"prettier": "^3.8.1",
+		"roblox-ts": "^3.0.0",
+		"typescript": "^5.9.3"
+	}
+}