BoxCast is a simple, flexible, and fast solution intended for casting boxes in the Roblox Engine.
How Does BoxCast work?
BoxCast essentially works by calculating a derived verisions of the origin & the direction you provided, and then cast a ray using those dervied values.
How fast can it be?
BoxCast can be really fast. In the benchmarks, I have seen an average of 200 microseconds. Check the benchs folder in the repro for the benchmarks.
Install BoxCast
BoxCast can be downloaded through the following:
Using Rojo manually: Grab the src folder from the repro, which you can get by going to the desired release, and grabbing the source zip.
Using Wally: To download BoxCast using Wally, paste the following under dependencies in wally.toml :
sinlerdev/boxcast/@X.X.X , replace the Xs with the version you want to install.
Using Studio: Grab the BoxCast rbxm from the desired release.
Usage
Using BoxCast is as simple as any normal raycasting!
local BoxCast = require(path)
local Caster = BoxCaster.new({
Thickness = 4, -- The amount of planes to be casted
Quality = 5, -- the amount of lines to be casted per plane
PointsAdvancement = 1, -- determines how BoxCast should loop through the Quality number , default = 1,
PlaneAdvancement = 1, determines how BoxCast should loop through the Thickness number -- default = 1,
PointDistance = 1, -- determines the distance between each point/ray, default = 1,
PlaneDistance = 1, -- determines the distance between each plane, default = 1
Ignore {} -- A list of BaseParts to ignore
})
local result = Caster:cast(Vector3.new(0,0,0), Vector3.new(0, 100, 0)) -- :cast() also accepts an additional raycastparams in case you want to use a different params for each operation.
if result then
prints(result) -- prints a table of what was hit.
end
Notes
Results returned from ...:cast are considered immutable, so, directly adding/removing content from them is considered bad practice.
If you want to extend the length of a plane while maintaining the same Quality, consider use PointDistance and it’s sister PlaneDistance when you have the same situation with Thickness.
Only use PointAdvancement & PlaneAdvancement if you want to cast more rays within the same area (Thickness * Quality)
Contribution
Contributing is heavily welcomed. You can start contributing by opening a pull request/issue at the repro.
V0.2.0 Update || Algorithm fixes and more Customization
This update comes with new features & bugfixes, so there is no reason to not update!
Changes:
New Config’ options:
PointDistance and PlaneDistance , determines how close the points/planes are, while PlaneAdvancement determines how BoxCast should manage Thickness , similar to PointAdvancement for Quality .
A new debugger is in place, toggle DEBUG_MODE in the module to use it.
Improvements to the algorithm; Casts should accurately shape boxes now.
Minor performance improvements.
Installation
For manual rojo installation: Grab the src folder from the source code ZIP in this release
For rojo using Wally: Place sinlerdev/boxcast/@0.2.0 under dependencies
For studio: Download BoxCastV0.2.rbxm in this release
Notice
I made a mistake in explaining PointAdvancement. Basically, if we had 4 as Quality and 0.1 as PointAdvancement, BoxCast will loop for 40 times (aka, casting 40 rays instead of 4 when using 1, aka, the default). Same goes for PlaneAdvancement and Thickness.
The post and the repro will be updated to specify this info.
When I was writing this module, I forgot that the direction paramater in workspace:Raycast is relative to the origin, (as it should), so this makes the additional calculation for direction cause issues and isn’t necessary at all
Installation
For manual rojo installation: Grab the src folder from the source code ZIP in this release
For rojo using Wally: Place sinlerdev/boxcast/@0.2.1 under dependencies
For studio: Download BoxCastV0.2.1.rbxm in this release
V0.2.2 Critical Patch || Bugfix for CFrame creation & New Debugger performance improvements
This is a critical patch that is recommended to update to as fast as you can to fix a bug that literally affects the whole shape building feature/mechanism.
Changes:
Debugger Performance Improvements:
The debugger now creates all the parts it needs on Caster creation, and then reuse them on cast() calls.
Critical Fix for CFrame creation
Pre-V0.2.2, direction was unintentionally treated as a point of space in CFrame.lookAt.
Installation
For manual rojo installation: Grab the src folder from the source code ZIP in this release
For rojo using Wally: Place sinlerdev/boxcast/@0.2.2 under dependencies
For studio: Download BoxCastV0.2.2.rbxm in this release
Notice
V0.2.2 is likely the last version I will publish for V0.2.x, as I am currently working on V0.3 which might be not as compatible as you think.
Starting from V0.3, I will introduce a pre-computation model for the shape building, and a reshape() that will recompute some properties depending on what you changed.
You will be fine to update if your usage of BoxCast treat a caster object immutable
I have released an uncopylocked place for you all to learn and test BoxCast. There are multiple things you should be aware of:
This game uses a single-script architecture, although it was optimized to be readable and simple as much as possible for novice developers.
This game contains a sword that has a simple sword detecting system developed exclusively for demonstrating purpose on what is possible with BoxCast , which users from other modules like RaycastHitbox by @TeamSwordphin or ClientCast by @PysephDEV may find familiar. It is also possible because of the flexible properties BoxCast offers. The sword mesh is from the toolbox, as I don’t model stuff.
This update pretty much brings a lot to the table from both a GC-safety and visualizer overhaul point of view.
Changes
Visualizer Overhaul
Now the visualizer is able to cast a huge number of rays smoothly
GC-Safety and Pre-computation
Now, vectors that are used to calculate the final origins are pre-computed and stored on Casters construction instead, avoiding more work for the GC.
A new Caster:rebuild() method has been added, allowing for rebuilding/recomputing specific vectors depending on what has been changed.
Keep in mind that Caster:rebuild() does what you tell it to do, so calling the method twice with the same properties will cause in two calculations instead of one.
Installation
For manual rojo installation: Grab the src folder from the source code ZIP in this release
For rojo using Wally: Place sinlerdev/boxcast@0.3.0 under dependencies
For studio: Download BoxCastV0.3.rbxm in this release
Notices
The playground has been updated.
While you can find a documentation in the repro, it is highly recommended to leave it due to its incompleteness status
