| Download Model |
VoxelDestruct is a voxelating destruction tool created for developers to add destruction to their games in the most performance friendly way using greedy meshing, part caching, and client off loading.
Making Destructible Parts
To make a destructible part you need to tag your part named after your attribute setting, by default the name is “Breakable”.
Tagging a model will make all of its children (parts only) destructible as well.
Methods
Require the module to begin using methods. You can get the stored part cache with vox.Cache
local vox = require(game:GetService("ReplicatedStorage"):WaitForChild("VoxelDestruction"))
local cache = vox.Cache -- If you ever need it for checking if parts belong to this module?
.destroy()
function breaker.destroy(
focus: Part | MeshPart,
parameters: OverlapParams?,
voxelSize: number?,
debrisCount: number?,
reset: number?
)
Used for singular destruction.
- Returns a table of debris and a table of affected walls.
- The cframe and size parameters are required but everything else is optional with defaults, some defaults are applied through settings.
focus: Part | MeshPart
The part representing the shape, size, and position of your destruction.
parameters: OverlapParams?
The parameters for whitelisting or blacklisting destructible parts.
Example:
local params = OverlapParams.new()
params.FilterType = Enum.RaycastFilterType.Include -- .Exclude for BlackList
params.FilterDescendantsInstances = {game.Workspace.Baseplate}
voxelSize: number?
The detail-providing voxel size of your destruction.
- If passed as nil your intersections are not voxelized and are returned instead of voxels
- If passed as 0 and Relativity setting is true then relativity is applied
- If passed as 0 and Relativity setting is false then VoxelDefault setting is applied
debrisCount: number?
The quantity of debris produced.
- If passed as nil all the debris will be returned
reset: number?
The timer until destruction is cleaned up.
.hitbox()
Used to create hitboxes from parts, meshparts, or models.
function breaker.hitbox(
focus: Part | MeshPart,
parameters: OverlapParams?,
voxelSize: number?,
debrisCount: number?,
reset: number?
)
Controls
hitbox:Start()
Starts your hitbox.
- Your hitbox can be restarted by calling
:Start()while it is active without needing to call:Stop()first. It will stop itself then start again. - Will fire the
hitbox.Started:Connect()event
hitbox:Stop()
Stops your hitbox.
- Will disconnect connections associated with all parts in the assembly and reset the hitbox.collisions data to 0 if the hitbox.revert parameter is true
- Will fire the
hitbox.Stopped:Connect()event passing the present debris and affected destructible parts from the hitboxes runtime from start to stop
hitbox:Fire()
Will activate the hitbox once.
- If destructible parts are detected it will fire the
hitbox.Collision:Connect()event passing the collision’s debris and affected parts
hitbox:IsActive()
Returns a boolean displaying whether or not the hitbox is running or stopped.
hitbox:GetRuntimeParts()
Will return the all the created debris and affected destructible parts from the hitbox’s runtime between when it was started and stopped.
hitbox:GetLifetimeParts()
Will return the all the created debris and affected destructible parts from the hitbox’s runtime between when it was started and stopped.
Inherited Parameters
All of these parameters are inherited from the .destroy() method, check the method description above for more information on their use.
focus: Part | MeshPart,
parameters: OverlapParams?,
voxelSize: number?,
debrisCount: number?,
reset: number?
Events
hitbox.Started:Connect(function()
print("Started")
end)
Fires when the hitbox is activated with the :Start() method.
hitbox.Stopped:Connect(function(debris, walls)
print("Stopped")
end)
Fires when the hitbox is stopped.
- Returns all the debris created and breakable parts affected during the runtime of the hitbox, starting from when the hitbox was activated to when it was deactivated
hitbox.Collision:Connect(function(debris, walls)
print("Collision detected")
end)
Fires when a hitbox interacts with a destructible part in any way.
- Returns the debris created from the interaction as well as the walls affected
Do NOT destroy debris and destructible parts when finished using them!
Instead use the
.cleanup()method of the module.
You can pass either a single part or a table of parts to the
.cleanup()method.
Instead of using :Destroy() to destroy debris and affected destructible parts you need to use the .cleanup() method of the module since destroyed parts cannot be returned to cache.
- If the useCache setting is true and the parts are stored in cache they will be returned, otherwise they will be destroyed if either of those conditions are false
It is optional to cleanup the hitbox object since ROBLOX’s garbage collection should clean up the object once it is no longer in scope, since it is good practice to free up any references immediately use hitbox = nil when you no longer need the hitbox.
Settings
Inside of the module’s hierarchy you will find a “Settings” module containing default settings that change the functionality of your methods. Defaults have been set to be what I deem to be the most appropriate settings for immediate use.
Settings.Tag= "Breakable"
The name of the tag which you must apply to all parts or models that you want to use this module on.
Settings.OnClient = false
Whether or not the destruction is off loaded onto clients.
Settings.OnServer = false
If OnClient is true, whether or not the server uses un-replicated destruction. This is intended to allow server NPCs to go walk through destruction, it is recommended to keep this false as it can lag the server.
Settings.RecordDestruction = false
Whether or not the server will store destruction and hitboxes and generate them for players who join the server. This is meant to combat not being able to see destruction when you join a server if destruction is offloaded to clients, depending on how much destruction is stored it may take some time before destruction generates on clients.
Settings.ResetModel = false
Whether or not tagged models repair the whole model.
Settings.ResetYields = false
Whether or not parts and models yield repairing while humanoids are standing inside of them. This is meant to combat players and NPCs getting stuck in walls and glitched out of the map when destruction gets repaired.
Settings.ResetDefault = 60
The default reset time applied if the reset parameter is passed as 0.
Settings.ResetMinimum = 3
The minimum reset time applied if the reset parameter is pass as a number greater than zero.
Settings.CutoutSize = 1
The scalar multiplier to the focus parameter’s size meant to provide more or less voxel detail. This can be between .75 - .9 for best detail. It is recommended to keep this as 1 as its a developer setting.
Settings.GridLock = false
Whether or not decimals will be dropped from the focus parameter’s position and size properties.
Settings.DebrisContainer = game:GetService("Workspace")
Where debris will be placed upon creation.
Settings.DebrisDefaultBehavior = false
Whether or not debris will have default behaviors like anchoring and reset timers.
Settings.DebrisAnchored = false
Whether or not debris are anchored by default.
The DebrisDefaultBehavior setting must be true for this to be used.
Settings.DebrisReset = 10
Whether or not debris have a reset timer applied by default.
The DebrisDefaultBehavior setting must be true for this to be used.
Settings.Relativity = true
Whether or not relativity is applied to voxels’ size if the VoxelSize parameter is passed as 0.
If true, the VoxelRelative setting will be used. If false, the VoxelDefault setting will be used.
Settings.VoxelRelative = 1/8
The relative size of voxels to the focus parameter’s size.
This setting is used if the VoxelSize parameter is passed as 0 and the Relativity setting is true.
Settings.VoxelDefault = 1
The default size of voxels.
This setting is used if the VoxelSize parameter is passed as 0 and the ***Relativity setting is false.
Settings.VoxelMinimum = 1
If the VoxelSize parameter is passed as a number greater than zero then it cannot be below this number.
Settings.HitboxRelative = 1/3
The relative distance to hitbox size that must be travelled before the hitbox destroys again.
For hitboxes, if the VoxelSize parameter is passed and the Relativity setting is true then this setting will be used.
Settings.GreedyMeshing = true
Whether or not greedy meshing is used. It is recommended to always keep this on.
Settings.RunService = false
Whether or not a run service loop is used instead of listening for hitbox cframe changes. This setting being true results in destruction every frame but it very performance heavy, it is recommended to keep this setting off.
Settings.PartCache = true
Whether or not parts will be cached to prevent instancing lag, it is recommended to keep this setting true.
Settings.CachePrecreated = 10000
The size of the cache.
The PartCache setting must be true for this setting to be used.
Settings.CacheExtra = 100
The number of parts created when the cache is emptied.
The PartCache setting must be true for this setting to be used.
Update 2.1: New Features!
- Simplified method parameters, .Destroy() now takes a focus part/meshpart.
- Meshparts can now be used as a focus
- New .Repair() method to repair models and parts before their timer ends.
- Client-Sided destruction via the OnClient setting
- Un-Replicated server destruction via the OnServer setting
- Destruction storage via the RecordDestruction setting so that newly joined players can see old destruction on their clients
- The ResetModel setting allows models to be repaired as a whole
- The ResetYields setting allows destruction repairing to yield while players stand in it, used to prevent being stuck in walls that get repaired
