Raycast Hitbox Module: For all your melee needs!

Current Version: V.2.1 EXPERIMENTAL (6/05/2020)

  • Experiencing inaccuracy problems? Try downloading an older version (pre 2.0) below to test.
  • V2.0+ works best on the client-side, unlike older versions


Hi there! I just released a module that focuses on raycast hitboxing, so things like melee weapons will probably be the most useful. But feel free to let me know what other projects you will use this for!


Example Place

Direct download
RaycastHitboxShowcaseV2.rbxl (87.6 KB)
(do note that these places won’t be updated, so if this module gets an update, you have to do it)
(debug rays are by default on, so performance is decreased but will be smooth once you disable them)

I realized my post about raycasting hitbox has been blowing up lately in the scripting support category, so I decided to just compile any questions you guys have or if you want to have a go at it yourself, then this thread will be the hub for that. Let me know what improvements you want and I will be more than happy to implement it!

Original Post & Examples

A few years back, I’ve been intrigued by the design of MORDHAU and Chivalry since I wanted accurate hitboxing while making it simple to do across a variety of different weapon shapes and sizes. Here’s a timestamp of how MORDHAU did their hitbox for their swords which may prove to be helpful.

Warning: Does include realistic depiction of blood so please be aware before opening

It basically fires a ray from an attachment placed on the weapon every frame. Do note that the red lines are visualizations purposes only, they do not last that long.

I also made it so you can adjust the placements of where the raycasting starts via attachments so I can fit it on different weapon shapes easily without hardcoding it. Here is the same system but the attachments are spread out a little to compensate for larger hitboxes.

How To Use

It is very simple. More information can be read in the module itself. But basically, each attachment will be the points where the raycasting will shoot out of. By default, the module searches for attachments named “DmgPoint” (can be changed). We can do this:


and that’s it for the physical modifications! Now, I’m going to make an example script that is inside the model we just created that should work:

local RaycastHitbox = require(RaycastHitboxModule)

local Damage = 10

local NewHitbox = RaycastHitbox:Initialize(script.Parent.Model)
NewHitbox.OnHit:Connect(function(hit, humanoid)
     --- Do not put events on a loop, else you will memory leak and it will damage multiple times!!


Don’t know if it works? Go into the module and turn on DebugRays and move the brick around to see if any rays are being drawn. Congratulations, you successfully created your own raycast hitbox thing! Now use this newfound knowledge on your own tools, models, etc.

Initialize function is recursive, so you can also call it on your own character and the script will find your attachments automatically.

Why Raycasting over Touched, Region3, etc… ?

I had a little thought process on the end of this thread, so you can check it out if you’re curious on why I opted to go for raycast.


  • HitStart only hits a target once (so multiple rays don’t hit the same target). Call HitStop to reset this target pool so you can hit the same targets again.
  • No multi-hit support (or Multi-hit support if PartMode is enabled)
  • No Specific Team or NPC damage support (but there is an IgnoreList inside it)
  • Wide objects requires a lot of attachments to be working correctly

I wrote this in a rush, but hopefully I’ve got everything down. Thanks for reading all.

Update Log

Current Version V.2.1 EXPERIMENTAL (6/05/2020)
  • Now uses new Raycast API!
  • Removed Hitbox.ignoreList
  • Added Hitbox.raycastParams
  • OnHit now returns 3 arguments: hit, humanoid, raycastResults

Previous Versions
V.2.0 EXPERIMENTAL (5/30/2020)
  • Removed RaycastHitbox:DebugMode
  • Removed HitStart([damage value]) argument
  • Removed DontCheckForTransparency
  • New HitboxObject:DebugMode
  • Major Performance Improvements
    RaycastHitboxV2.rbxm (8.4 KB)
V.1.53 BETA (4/03/2020)
  • Updated some outdated API
  • Clarified some troubleshooting steps
  • Added a new troubleshooting question
  • Added warnings whenever it detects rays are not being shown
    RaycastHitbox153.lua (17.9 KB)
V.1.52 BETA (3/25/2020)
  • Fixed LinkAttachment position errors
V.1.51 BETA (3/24/2020)
  • Fixed SetPoints position errors (should now be as accurate as attachments)
  • Credits to @Shurikanz for the find
V.1.5 BETA (3/23/2020)
  • New HitboxObject:RemovePoints
  • New HitboxObject:LinkAttachments
  • New HitboxObject:UnlinkAttachments
V.1.3 & V.1.4 BETA (1/28/2020)
  • Initialize should now return a hitbox and not nil
  • Mild performance increases
  • New Function: PartsMode (documentation is in the script)
1.21 BETA (10/30/2019)
  • Removed RaycastHitbox:HitStart
  • Removed RaycastHitbox:HitStop
  • DebugRays remade with constraints/attachments to help low-end devices
  • Initialization performance improved
1.2 BETA (10/27/2019)
  • New HitboxObject:SetPoints(Instance part, table vectorPoints)
  • New RaycastHitbox:DebugMode(boolean true/false)
  • Recursive now supports all instance types (no longer have to be a model!)
  • Ignore list now automatically includes Terrain
1.1 BETA (10/24/2019)
  • Deprecated RaycastHitbox:HitStart
  • Deprecated RaycastHitbox:HitStop
  • RaycastHitbox now returns HitboxObject
  • New HitboxObject:HitStart
  • New HitboxObject:HitStop
  • New HitboxObject.OnHit:Connect(Instance part, Instance humanoid)
  • New RaycastHitbox:GetHitbox(Instance model)
  • Possible Issue - Heartbeat loop might not successfully disconnect when deinitializing, but happens sometimes (need confirmation)
1.0 BETA
  • Initial Release

To-Do List
  • Priority hitboxes, think Smash Tipper (Roy is still better though)
  • Simple Example tool or model that uses this

Like this module? Please consider donating a little to support my future works!

My other modules:
Inverse Kinematics and Procedural Animation
Part Pooling

Laggy players can't register weapon hits, best way to get around without "trusting the client"
Experimental Inverse Kinematic and Procedural Animations
How to make a perfect hitbox?
How do I make a clean hitbox?
Custom Enemies and Hit Detection
Alternative to welding hit-boxes?
A better way of hit detection when .Touched isn't available?
Touched Randomly works
Ways to implement melee hit detection?
Simple Punch Script
Best method for hitbox detection?
Is it a bad idea to handle hitboxes with GetTouchingParts?
Most Efficient and Performance wise method for Cube-like Hitboxes?
How to make a good melee? with a good hitbox
What is the best way to cast large projectiles?
Making a making a hitbox more accurate?
Is it even possible to have an accurate weapon hitbox that grabs all touching parts (including noncollide)?
Detecting If A Tool Is Interacting With An Object
MeleeHitboxModule not following model until after a hit
How to make my skill detect players and do damage?
Is there such a thing as good square shaped hitbox detection for combat?
Best method for hitbox detection?
Lag with BasePart.Touched
How do u throw a sword w/ FastCast module?
What is your best way to create a hitbox?
Scripting Resources Mega List
Better way to detect hits for a combat system
Attacks Effecting Multiple Targets
Weapons only doing damage after reaching a keyframe
Combat Warriors Information
Best way to go about punching system collision detection?
Best way to go about punching system collision detection?
Unique game concept - Looking for a scripter
Touched Event Alternatives?
Part Pooling - Increase performance with many parts
How to debounce Touch events client side?
Why do some stuff stop working in my game? [Closed]
Could a TextLabel (or buttons) detect if there is a Humanoid on It?
Combat doesn't detect hit sometimes?

Awesome module! Very useful and very accurate! I suggest adding a way so you can control what happens when you hit something. For example if I wanted to be able to also hit certain parts with my weapon to destroy them I could. Have it so it will return “hit” like the touched function does. Just a suggestion! Would make this module 10/10 just by having that feature! Good work! Keep it up!


Awesome, Thank you for considering the request!

I’ll provide further feedback when I get to it.



I asked a friend to make a more optimized version of the script.

I also notice that you are using a lot of Rays, can it be reduced to using only a few maybe 5?

One in the top left, top right, bottom left, bottom right, and middle along with the Hitbox

Instead of creating many horizontal Rays can you create less with Vertical Rays and still have the same or better performance?

Perhaps the Attachement could automatically be created and all you need to do is create a HitBox part, then use CFrame to get the size and sides of the part then create Damage points depending on how big it is.


Okay now I have to use it given that it’s an open source resource now. I absolutely have to.

From the moment I first saw those hitboxes in action, that became one of my new favourite development-related threads. Being able to work with the logic behind it is a blessing and I thank you very much for sharing this resource with the community.

Melee hitboxes are definitely a rising topic on the DevForum as developers are creating more melee-centric games and a common question throughout the forums is how to achieve accurate hitboxes while accounting for several factors, up to determining which method is most performant and suitable.

Setting the thread to watching to keep up with any discussion. Thank you so much for this.


Thank you! I planned on something like that but ran out of time to make yesterday :sleepy: If I have time today I will absolutely update it with that functionality.


Very nice, I’m really bad at scripting so there’s not really any feedback i can give.

But this looks very neat and theres not alot of hitbox modules


This feature looks AMAZING! Completely ignoring the practical uses for is the ‘SwordShieldMan’ looks cool twirling around a sword covered with red laser beams (aka. hitbox thingies).

In terms of practical uses, I believe this is going to be amazing to use, especially since detecting the.Touched event on a low end device is… Ya know…

Unfortunately as much as I love the rays following the weapon I feel my players may not feel the same way so I guess I wont have that enabled in my projects :frowning:

In conclusion just thank you, this is such a well made solution to one of the most irritating problems on roblox and I didn’t even have to go through a pack of harribos keeping my mind focused enough to script it!

Just to confirm, the thing about using the beams was a joke @ScriptingSupport


AFAIK the rays are only intended for debugging purposes and you aren’t meant to actually enable them within a production environment.


Ah thank you! Before I could reply to your DM, I see you already edited it so I’ll just reply here instead. Let’s start from the top.

  1. There are some slight changes in the optimized version that I think are unnecessary, but overall I think it is ultimately an improvement. DebugRay code was copied directly from the raycasting wiki so take it up with the writers :upside_down_face:. Still at work, so I’ll look at the optimizations a bit more thoroughly later.

  2. I assume you are talking about the SwordNShield NPC above. I’m not sure what you mean by vertical rays, but I suppose if I am visualizing it correctly, something like a ray starting from a sword handguard to the end of it’s blade tip. There is a possibility that you can increase performance with vertical rays like this, but speedy swiping motions will not have a guarantee that it will hit if the target are between the vertical rays between the last and current frame. This will be no different than using a touched event imo (faster physics = less likely to hit).

  3. Automatic attachment generation sounds neat, and I can probably try something like that. Though this may become intricate and difficult if it has meshes or weird shapes, and may even reduce performance depending on its complexity.

Overall, for simple swords, I would just string the attachments along the blade, and maximum 15 of them. Though the SwordNShield NPC has no problem having over 180+ rays being made at once.


I went to art school, this is what they call a master piece

This shouldn’t be a problem if you use a Block Part as a HitBox, so it wouldn’t have weird shapes.

I see, then that could be an option for the Users to choose which type of Ray they want to use depending on the performance they want.


Can confirm, also went to an art school. Even Michelangelo will tremble at your pure brilliancy. Picasso lovers, watch yourself.

I do like the idea of vertical rays, in a way people can sacrifice accuracy for more performance so you’re right. Regarding block part as a hitbox, I suppose something like an irregular scythe weapon where the angles aren’t always rectangular and you want something especially accurate, it might not work but for most common use cases, I can see it working like you described.


Awesome module, however before i am going to use this ill be waiting for some more events to come out. I am currently creating lightsabers and i need the onhit event. So definately using this in the future!


New Update: V.1.1

Hey all, just updated some minor but beneficial changes to the module. You can read more in the “How To Use” and “Update Log” in the main thread if you want to know the changes. Thank you to those who have helped thus far, it was a great learning experience. I will keep updating it and optimizing as need be (and as much as I can within my limited timeframe!)

In summary, the Initialize function now returns a HitboxObject which you can use HitStart or HitStop on. It also has a new onhit function (example in the main thread). I’ve filled out some more information directly in the module, and the HitStart and HitStop used directly on the RaycastHitboxModule is deprecated (so use the returned HitboxObject instead). This variable system also allows you to manage multiple hitboxes, a good example is if you have a dual wielding sword character, you can disable hitboxes for one of the swords while keeping the other off hand on.


How computationally expensive is this? It doesn’t look too bad, but I imagine swords with large hitboxes (and many of them) would have a lot of overhead.

Very nice work :slight_smile:

1 Like

There are definitely room for improvements, but from what I’ve tested, the performance was a lot better than using Region3 and Touched (in large quantities). The ShieldNSword npc above stretched about 181 raycasts a frame, and even in live production games with a plethora of other computation happening, server was still very smooth, fps drops were minimal, and this is also tested with multiple SwordNShield npcs at once. Though, if you’re really worried, it doesn’t hurt to test it out yourself.

Edit: Most games dont really have oversized swords, so honestly you should be doing 7 - 15 attachments per weapon, 1 stud apart for the most efficiency. It takes hundreds of rays a second to even consider performance drops.


For some reason, was not efficient on my testing.
There are a few points you should certainly consider for next update.

  1. Ignore should automatically include the terrain.
  2. Support for multiple hitboxes, such that sword skill hitboxes are bigger than normal attack hitboxes
  3. have damage with initialize function? Instead of passing it, every time you attack, you could have it set in the metatable.

If possible could you share a sword model that contains the sword (or any other free model scripted with this module) so that we could see how you require the module etc?

However, all in all, this module is really amazing and I appreciated trying it out, thanks!

What I’m currently using for touched event is setting a loop that gets the touching parts of a non-cancollide part in the tool, representing hitbox.

1 Like

Thank you for your insights. What performance problems were you encountering in particular? I can probably do a quick mockup example later for you.

Regarding 2., V.1.1 should have support for multiple hit boxes, you just need a separate model containing those new attachments and then call initialize on that one. Unless I’m not understanding what you’re requesting then I apologize.


The raycasts are from old point to current point, yes?

If so, then rather than attachments there should be an option to pass a table of positions and a root part to do said positions relative to. This would reduce instance management and be preferable in my opinion.

Yeah, I edited the script so that the sword has is made of tables, each one being the hitbox.
And regarding performance, I believe the number of parts or the number of raycasts created/calculated were the reason for the lag.
Would really appreciate a quick example tool, thanks!

What was your setup? You’re usually capable of firing off hundreds of rays per frame without performance hits as short rays at inexpensive. Seems like a concern to me that you were experiencing performance hits with this, since to my understanding it does exactly that (short rays per frame).

1 Like