HitboxClass | v1.1A | A Powerful OOP-based Hitbox Module


Releases | Documentation

What Is HitboxClass?

HitboxClass is an OOP-based hitbox module designed to be a powerful solution to hitboxes in a variety of games, such as fighting games and RPGs. HitboxClass enables developers with incredibly easy access to client-sided hitboxes and abstracts all the networking for you so you don't need to worry about it!

The flexibility of the module allows developers to easily handle anything that needs a hitbox, whether it be a projectile hitbox, melee hitbox, server-sided hitbox, or a client-sided hitbox, you name it!

Why use HitboxClass?

HitboxClass abstracts all the networking for you, so you don't need to lift a finger in order to access synced client-sided hitboxes. The surplus of methods available to modify the hitbox how you please allows you to really do whatever you want with it. It's powerful, easy to use, and incredibly easy to implement!

It’s well-documented! Everything is laid out in the Github.

Also, everything is 100% type-checked! This allows for easy organization and helping you avoid usage errors!


Automatic Client-Side Replication:

  • HitboxClass automatically sets up client-side replication so you don’t have to!
  • All methods used on the hitbox on the server are replicated to the client!

Flexible Options

  • The amount of options provided by the module allows you to design the hitbox how you want it to function! This includes:

    • Calculating on the client vs the server.
    • Debounces for same-character hits.
    • IDs between hitboxes.
    • Dot product checks for magnitude hitboxes.
    • And more!

Velocity Prediction:

  • Server-sided hitboxes when “welded” using the WeldTo method to a part use that part’s velocity to guess where the part is on the client! For instance, if put on the HumanoidRootPart on my character, you can see the difference between a hitbox using velocity prediction and one that doesn’t use it!

(Thank you @beansinmybathroom for the method!)

Velocity Prediction Showcase

The hitbox using velocity prediction is shown in green, both are on the server!

Click here if you can’t see it!

How to Use

After setting it up properly according to the Github:

First, require the module.

Next, setup your Hitbox Parameters:

local ReplicatedStorage = game:GetService("ReplicatedStorage")
local HitboxClass = require(ReplicatedStorage.Modules.HitboxClass)
local HitboxTypes = require(ReplicatedStorage.Modules.HitboxClass.Types)

local hitboxParams = {
	SizeOrPart = 5,
	DebounceTime = 1,
	Debug = true,
} :: HitboxTypes.HitboxParams
	A magnitude hitbox that can hit anybody, with 1 second between possible hits for each character!
	It'll also show itself in red!

Then make a new hitbox with your parameters. The HitboxClass.new function will return the hitbox and whether or not it successfully connected to the client. This will always be true if this is a server hitbox.

local newHitbox, connected = HitboxClass.new(hitboxParams)

Finally, connect to the HitSomeone signal and start the hitbox!



Things to Note

HitboxClass does not secure remotes for you!

  • Other than ensuring signals fire back only what they list in the documentation, it’s up to you to ensure a hit was within reason. Make sure you validate responses sent back from client-sided hitboxes!

HitboxClass has script-injecting behavior!

  • When HitboxClass is first required, it sets up a RemoteEvent and adds a LocalScript to StarterPlayerScripts, as well as giving the LocalScript to anyone there before the module is required!

HitboxClass is built for Humanoids!

  • If you want to add support for non-Humanoids, go for it! I’ve only ever needed to check for Humanoids, so this module is built with them in mind.


Latest Release (the .rbxm file): Github

All the documentation is here!


Nothing is being detected!

  • Make sure the entities you are looking for are in the Alive folder you set. HitboxClass only searches the Alive folder for entities to hit.


Here’s a couple examples of the hitboxes in action from a game I’m working on!

Click here if you can’t see it!

Click here if you can’t see it!

Thanks for checking it out! Let me know if you have any issues!


Thank you for this lovely resource! I have always looked for a Hitbox system that automatically replicates AND uses OOP. This is very helpful and will be very useful for combat games and more! :grin:

Thank you for your contribution to the forum, and I hope more people recognize this resource. In addition, good luck on your fighting game as it appears you’re working on one! It looks interesting and I’d love to try it out on any account of release. :slight_smile:


This is amazing, man! I adore that it is in OOP because, in the past few months, I have been using and creating OOP-based things exclusively.

Regardless of when it’s used, I will surely use this.
Maintain your excellent work!


For some reason I cannot open the file on studio on my Mac. Can you please add a different source so I can download it. Thanks : ) Great work btw!


How would you make something like a projectile with vfx? Like keep the vfx and hitbox synced, both should be client sided/


You could access the HitboxCache within the HitboxClass module on the client!

Once the client makes the hitbox, fire to the client to start the VFX along with the tick value/ID of the hitbox you made, then inside the function you handle the VFX, you get the reference for the hitbox through the tick value/ID and then coordinate the positioning of the hitbox with the VFX as needed using the methods provided.

This would desync the hitbox on the server, the severity depending on how much you modify the hitbox through the client. Obviously you’d want to check on the server whether or not the hit they give is valid.

This is just something I came up with off the top of my head, the idea I had in mind for this module is to keep the hitboxes synced across the server-client model, but you absolutely can do that if you want!

So im using the module on server itself and using the Useclient option, so your telling me to do that then access the hitbox on the client through the cache folder, then according to that move the hitbox and use my vfx?
Will it still properly send over hits to the .HitSomeone function?

I’m working on a RPG game, and this module has saved me from many, I want to thank you for making this beautiful module!


Just get the hitbox cache with the GetHitboxCache method, and then find the correct hitbox to modify. The HitSomeone signal should still fire even after modifying the hitbox directly on the client.


There won’t be any difference if I put it in serverstorage instead, right?

Don’t put it in ServerStorage, the client needs to see the module as well.


Ok ty, also another question, is it normal that even if I use the “UseClient” option the hitbox is like really delayed?
Edit: I just had to weld it to the HRP :expressionless:

One more question, is it necessary to require the “HitboxTypes” cuz from it doesn’t really look like it’s necessary except for the tips, or is there like any other benefits. Also forgot to say that this module is awesome :grin:

You don’t need to unless you want to type-check, no. But it lets studio auto-complete if you do, so I’d recommend it since it helps keeps usage errors low.

Thank you!


Yeah, I’ll keep using it because why not. One thing I noticed when using the ‘weldto’ method is that the hitbox doesn’t weld immediately. Is this because of Roblox, or can it be fixed?

For client-sided hitboxes, it has to send the packet to the client for it to react, so depending on the ping the client has, it could take that length of time for all commands to reach the client.

It’s not something that can be fixed, just a fact of how networking works, that’s why commands on server-sided hitboxes should be instant. :+1:

If server-sided hitboxes are delayed, then that’s an issue with the module that I’ll need to look into, but with how I have the module set up it sets the position prior to the hitbox checking for hits, so that shouldn’t be the case. It could also be the code being delayed somehow before calling the WeldTo method.

I’ve got a couple things I wanna do when I get the time, including adding an initial WeldTo parameter to the HitboxParams. I’ll update the post + leave a comment when I’m finished with it.

1 Like

Even when using the serverside option, there’s still a delay at the beginning, but it becomes completely fine after a frame or two. Perhaps it’s because of how I’m implementing it? Could you check to see if I’ve made any mistakes? Thank you!

local HitboxParams = {
		SizeOrPart = Vector3.new(6.5,7.5,Range),
		DebounceTime = 1,
		UseClient = Player,
		Blacklist = {self.Character},
		InitialPosition = self.Character.HumanoidRootPart.CFrame + self.Character.HumanoidRootPart.CFrame.LookVector * Range/2,
		Debug = true
	} :: HitboxTypes.HitboxParams

	local newHitbox, connected = HitboxModule.new(HitboxParams)
	newHitbox:WeldTo(self.Character.HumanoidRootPart, CFrame.new(0,0,0-Range/2))

Another really cool thing you could add to the HitboxParams is a ‘Debris’ parameter that would automatically destroy the hitbox after a certain amount of time, like ‘Debris = Time’. If not defined, you will have to destroy it manually.

Video of the delay:

Ah, I see, it’s likely because the server sees you standing still the moment you run it, then it finally sees you move.

It could be delayed on the server because of your position being updated on the server at a delayed time, that’s because of networking having a natural delay of going to and from the server and client. That’s not something I can fix. It actually is welded to the character but since the server still sees you standing still it keeps it still.

Try moving for a couple seconds and then punch while moving as well, does the hitbox move from the beginning or does it stay still before updating?

Doesn’t look like there’s any mistakes in your code. If the client-sided option is being delayed even though you weld before you start the hitbox, which should be fine since I use a reliable remote event, then that’s strange and I’ll have to look into it.

Edit: I just realized that it’s snapping into place after you start moving with it. I’ll use your code when I get home tonight and DM you about it once I try it out. :+1:


Oh I get what I did wrong, the mistake was that I created the hitbox outside of the function I used.
But it’s still delayed for a frame or two , not a big deal ig.
Also, may I ask a question, what is “connected” after “newHitbox” used for? Is it like really necessary?


The connected part is to check to see if a client-sided hitbox made a connection to the client, it waits for a response back for a max of 1.5 seconds. If the client lets the server know it made the hitbox, it’ll return true, if it timed out because the client didn’t respond back in time, it returns false.

The point is to allow you to add some sort of callback if the client doesn’t respond. For instance, you could destroy the hitbox object and make a new one that’s server-sided to use instead, or just ignore the action entirely, and not apply cooldowns or whatever until a proper hitbox is made and it’s able to be used properly.

This always returns true if it’s a server-sided hitbox, since if the server wasn’t gonna respond it probably wouldn’t have ran the code to make the hitbox in the first place lol. So you don’t really need it there if it’s a server sided hitbox, just assign the object to a variable and ignore the connected boolean.

I’ll look into the delay issue when I get the time, I haven’t had any issues with it being delayed, so if you can recreate the issue in a new place and send it to me that’d be wonderful.

1 Like