@kunosyn/shatterbox 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 savruun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+<div align="center">
+  <p>
+    <img src=https://i.imgur.com/j2pg7CB.png />
+  </p>
+</div>
+
+<div align="center">
+  <a href=https://www.npmjs.com/package/@rbxts*/shatterbox>
+    <img src=https://img.shields.io/npm/v/@rbxts*/shatterbox />
+  </a>
+  <a href=https://www.npmjs.com/package/@rbxts*/shatterbox>
+    <img src=https://img.shields.io/npm/dt/rbxts-shatterbox />
+  </a>
+</div>
+
+## About
+
+
+> [!IMPORTANT]
+> I am also NOT currently in the rbxts org, this means you will have to drag shatterbox into your node_modules/@rbxts folder before use.
+
+
+### Installation
+Install package via [NPM](https://www.npmjs.com/package/@rbxts*/shatterbox):
+
+```sh
+npm i rbxts-shatterbox
+```
+
+Drag shatterbox folder from @rbxts*/shatterbox into node_modules/@rbxts.
+
+*Done!*
+
+### Usage Example
+Here's some basic examples of using the shatterbox module:

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@kunosyn/shatterbox",
+  "version": "0.0.1",
+  "description": "Voxel destruction, simple and optimized.",
+  "keywords": [
+    "roblox-ts",
+    "rbxts",
+    "voxel",
+    "destruction",
+    "shatterbox"
+  ],
+  "homepage": "https://github.com/savruun/rbxts-shatterbox#readme",
+  "bugs": {
+    "url": "https://github.com/savruun/rbxts-shatterbox/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/savruun/rbxts-shatterbox.git"
+  },
+  "license": "MIT",
+  "author": "kunosyn",
+  "main": "src/init.luau",
+  "types": "src/index.d.ts",
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "build": "rbxtsc --rojo dev.project.json"
+  },
+  "devDependencies": {
+    "@rbxts/compiler-types": "^3.0.0-types.0",
+    "@rbxts/types": "^1.0.907",
+    "roblox-ts": "^3.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/src/Effects.d.ts

@@ -0,0 +1,134 @@
+/// <reference types="@rbxts/types" />
+
+import { DestroyedVoxelInfo } from "./types";
+
+interface Effects {
+    Default: (voxel: BasePart, info: DestroyedVoxelInfo) => void;
+    BumpyFloorBreakWalls: (voxel: BasePart, info: DestroyedVoxelInfo) => void;
+    Rough: (voxel: BasePart, info: DestroyedVoxelInfo) => void;
+
+    /**
+     * This effect assumes a spherical hitbox (Shape "Ball").
+     * The inner 33% of voxels are removed.
+     * Starting at the point where voxels are no longer removed, voxels are black. There is a gradient until around the edges, where the voxels should be their original color.
+     */
+    MapVoxelSpace: (voxel: BasePart, info: DestroyedVoxelInfo) => void;
+}
+
+declare const Effects: Effects;
+export = Effects
+
+// local Effects = { }
+
+// local function map(x, a_0, a_1, b_0, b_1)
+//     return b_0 + (b_1 - b_0)*(x - a_0)/(a_1 - a_0)
+// end
+
+// local raycastParams = RaycastParams.new()
+// raycastParams.FilterType = Enum.RaycastFilterType.Include
+
+// local Shatterbox
+// Effects._SetRef = function(shatterbox)
+//     Shatterbox = shatterbox
+// end
+
+// Effects.Default = function(voxel)
+//     voxel:Destroy()
+// end
+
+// Effects.BumpyFloorBreakWalls = function(voxel, info)
+//     if info.IsAlreadyDebris then return end
+
+//     local O = info.UserData.CastOrigin or info.CuttingPart.CFrame.Position
+//     local toVoxel = voxel.Position - O
+//     -- retrieves the untouched original part, to check if the voxel should be considered a floor
+//     local castTo = Shatterbox:GetOriginalPart(info.DirtyGroupID)
+
+//     raycastParams.FilterDescendantsInstances = { castTo }
+
+//     castTo.Parent = workspace
+//     local hitResult = workspace:Raycast(O - toVoxel * 0.01, toVoxel * 1.01, raycastParams)
+//     castTo.Parent = nil
+
+//     if hitResult and hitResult.Normal:FuzzyEq(Vector3.yAxis, 0.01) then -- if the normal is facing up, it is a floor
+
+//         voxel.Position += Vector3.yAxis * (math.random() - 0.5) -- add some random vertical offset to floor voxels
+
+//     else -- everything else becomes a falling voxel using puppeteer
+
+//         Shatterbox:Puppeteer(voxel) -- start controlled replication of "voxel" to clients (tween between replication of CFrames)
+
+//         voxel.AssemblyLinearVelocity = toVoxel.Unit * (math.random() * 25 + 50)
+//     end
+// end
+
+
+// function Effects.Rough (voxel, info)
+//     if info.IsAlreadyDebris then -- the voxel is already debris
+//         -- fully contained debris is destroyed
+//         if not info.IsEdge then
+//             voxel:Destroy()
+//         end 
+        
+//         return
+//     end
+
+//     local roll = math.random()
+
+//     if info.IsEdge and roll < 0.8 then -- 80% of edge voxels become "edge debris"
+//         voxel.CFrame *= CFrame.Angles(math.random() * 2 * math.pi, math.random() * 2 * math.pi, math.random() * 2 * math.pi)
+//         voxel.Size *= math.random() + 1
+//         return
+//     end
+
+//     -- a small percentage of voxels are destroyed
+//     if roll > 0.05 then voxel:Destroy()
+//         return;
+//     end 
+
+//     -- all other voxels are flying debris
+
+//     voxel.Anchored = false
+//     voxel.CanCollide = false
+//     voxel.AssemblyLinearVelocity = (Vector3.new(math.random(), math.random(), math.random()) - Vector3.one * 0.5) * 80
+//     voxel.AssemblyAngularVelocity = (Vector3.new(math.random(), math.random(), math.random()) - Vector3.one * 0.5) * 20
+
+//     -- remember to destroy the voxel
+//     game.Debris:AddItem(voxel, 3)
+// end
+
+// -- This effect assumes a spherical hitbox (Shape "Ball").
+// -- This is an example show you how to use voxel space to perform calculations that are consistent regardless of the gridsize or orientation of voxels.
+// -- The inner 33% of voxels are removed.
+// -- Starting at the point where voxels are no longer removed, voxels are black. There is a gradient until around the edges, where the voxels should be their original color.
+// function Effects.MapVoxelSpace(voxel, info)
+//     if info.IsAlreadyDebris then return end
+
+//     -- the radius of the spherical hitbox
+//     local R = info.CuttingPart.Size * 0.5
+
+//     -- from the center of the sphere, how many voxels away the edge of the sphere is on each axis (in local space)
+//     local MaxVoxelDist = Shatterbox:VoxelCountVector(voxel, math.min(R.X, R.Y, R.Z)*Vector3.one)
+
+//     -- from the center of the current voxel, how many voxels away the center of the sphere is on each axis (in local space)
+//     local VoxelDist = Shatterbox:VoxelDistanceVector(voxel, info.CuttingPart.CFrame.Position):Min(MaxVoxelDist)
+
+//     -- The magnitude of this vector is guaranteed to be in the range 0 to close to 1 because spheres hold a consistent magnitude
+//     local NormalDist = (VoxelDist / MaxVoxelDist).Magnitude
+
+//     -- destroy voxels close to the center (inner 33% by default)
+//     local NormalDistThreshold = 0.33
+
+//     if NormalDist < NormalDistThreshold then
+//         voxel:Destroy()
+//         return
+//     end
+
+//     -- map and clamp the range [NormalDistThreshold, 1] to the range [1, 0]
+//     -- So where the voxels begin to appear, they start at black, and where the voxels end, they should be their original color.
+//     local Shade = math.clamp(map(NormalDist, NormalDistThreshold,1, 1,0), 0, 1)
+
+//     voxel.Color = voxel.Color:Lerp(Color3.new(), Shade)
+// end
+
+// return Effects

package/src/Effects.luau

@@ -0,0 +1,114 @@
+local Effects = { }
+
+local function map(x, a_0, a_1, b_0, b_1)
+    return b_0 + (b_1 - b_0)*(x - a_0)/(a_1 - a_0)
+end
+
+local raycastParams = RaycastParams.new()
+raycastParams.FilterType = Enum.RaycastFilterType.Include
+
+local Shatterbox
+Effects._SetRef = function(shatterbox)
+    Shatterbox = shatterbox
+end
+
+Effects.Default = function(voxel, info)
+    voxel:Destroy()
+end
+
+Effects.BumpyFloorBreakWalls = function(voxel, info)
+    if info.IsAlreadyDebris then return end
+
+    local O = info.UserData.CastOrigin or info.CuttingPart.CFrame.Position
+    local toVoxel = voxel.Position - O
+    -- retrieves the untouched original part, to check if the voxel should be considered a floor
+    local castTo = Shatterbox:GetOriginalPart(info.DirtyGroupID)
+
+    raycastParams.FilterDescendantsInstances = { castTo }
+
+    castTo.Parent = workspace
+    local hitResult = workspace:Raycast(O - toVoxel * 0.01, toVoxel * 1.01, raycastParams)
+    castTo.Parent = nil
+
+    if hitResult and hitResult.Normal:FuzzyEq(Vector3.yAxis, 0.01) then -- if the normal is facing up, it is a floor
+
+        voxel.Position += Vector3.yAxis * (math.random() - 0.5) -- add some random vertical offset to floor voxels
+
+    else -- everything else becomes a falling voxel using puppeteer
+
+        Shatterbox:Puppeteer(voxel) -- start controlled replication of "voxel" to clients (tween between replication of CFrames)
+
+        voxel.AssemblyLinearVelocity = toVoxel.Unit * (math.random() * 25 + 50)
+    end
+end
+
+
+function Effects.Rough (voxel, info)
+    if info.IsAlreadyDebris then -- the voxel is already debris
+        -- fully contained debris is destroyed
+        if not info.IsEdge then
+            voxel:Destroy()
+        end 
+        
+        return
+    end
+
+    local roll = math.random()
+
+    if info.IsEdge and roll < 0.8 then -- 80% of edge voxels become "edge debris"
+        voxel.CFrame *= CFrame.Angles(math.random() * 2 * math.pi, math.random() * 2 * math.pi, math.random() * 2 * math.pi)
+        voxel.Size *= math.random() + 1
+        return
+    end
+
+    -- a small percentage of voxels are destroyed
+    if roll > 0.05 then voxel:Destroy()
+        return;
+    end 
+
+    -- all other voxels are flying debris
+
+    voxel.Anchored = false
+    voxel.CanCollide = false
+    voxel.AssemblyLinearVelocity = (Vector3.new(math.random(), math.random(), math.random()) - Vector3.one * 0.5) * 80
+    voxel.AssemblyAngularVelocity = (Vector3.new(math.random(), math.random(), math.random()) - Vector3.one * 0.5) * 20
+
+    -- remember to destroy the voxel
+    game.Debris:AddItem(voxel, 3)
+end
+
+-- This effect assumes a spherical hitbox (Shape "Ball").
+-- This is an example show you how to use voxel space to perform calculations that are consistent regardless of the gridsize or orientation of voxels.
+-- The inner 33% of voxels are removed.
+-- Starting at the point where voxels are no longer removed, voxels are black. There is a gradient until around the edges, where the voxels should be their original color.
+function Effects.MapVoxelSpace(voxel, info)
+    if info.IsAlreadyDebris then return end
+
+    -- the radius of the spherical hitbox
+    local R = info.CuttingPart.Size * 0.5
+
+    -- from the center of the sphere, how many voxels away the edge of the sphere is on each axis (in local space)
+    local MaxVoxelDist = Shatterbox:VoxelCountVector(voxel, math.min(R.X, R.Y, R.Z)*Vector3.one)
+
+    -- from the center of the current voxel, how many voxels away the center of the sphere is on each axis (in local space)
+    local VoxelDist = Shatterbox:VoxelDistanceVector(voxel, info.CuttingPart.CFrame.Position):Min(MaxVoxelDist)
+
+    -- The magnitude of this vector is guaranteed to be in the range 0 to close to 1 because spheres hold a consistent magnitude
+    local NormalDist = (VoxelDist / MaxVoxelDist).Magnitude
+
+    -- destroy voxels close to the center (inner 33% by default)
+    local NormalDistThreshold = 0.33
+
+    if NormalDist < NormalDistThreshold then
+        voxel:Destroy()
+        return
+    end
+
+    -- map and clamp the range [NormalDistThreshold, 1] to the range [1, 0]
+    -- So where the voxels begin to appear, they start at black, and where the voxels end, they should be their original color.
+    local Shade = math.clamp(map(NormalDist, NormalDistThreshold,1, 1,0), 0, 1)
+
+    voxel.Color = voxel.Color:Lerp(Color3.new(), Shade)
+end
+
+return Effects

package/src/Settings.luau

@@ -0,0 +1,75 @@
+--#selene: allow(unused_variable)
+
+local Settings = {}
+
+-- These all-caps named settings cannot be changed at runtime. The rest are okay to do so.
+
+Settings.USE_CLIENT_SERVER = true -- Set this to false if you don't want to use client-server functionality (false = fully server side destructions)
+
+--Settings.USE_OBJECTCACHE = false -- whether or not to use ObjectCache (not fully implemented)
+--	Settings.CACHE_INITIAL_SIZE = 10000 -- The initial size of the part Caches
+
+
+
+Settings.SkipInstanceCheck = function(i : Instance)
+
+	-- return true if you want to skip the instance "i"
+
+	return false
+end
+
+
+
+Settings.NonDivisibleInteraction = "FALL" :: "FALL"|"DESTROY"|"NONE" -- What happens to destructible parts that cannot be divided by Shatterbox
+
+
+
+-- Smooth cleanup settings
+
+Settings.UseSmoothCleanup = true -- If false, the CleanupDelay will be ignored and no smooth cleanups will happen at all.
+
+Settings.DefaultSmoothCleanupDelay = 60 -- the default smooth cleanup delay if none is provided. Setting the CleanupDelay to 0 or a negative number disables smooth cleanup for that destruction.
+
+
+-- Part division settings
+
+Settings.MaxDivisionsPerFrame = 1000 -- Limits the count of part subdivisions per frame using `Destroy` (1 division = up to 8 new parts before greedy meshing)
+
+Settings.DefaultGridSize = 1
+
+Settings.MaxOpsPerFrame = 10 -- Limits the number of calls to GetPartsInPart every frame using `Destroy`
+
+Settings.UsePriorityQueue = true -- If true, newer operations take precedence over old ones, if false, round-robin processing is used
+	Settings.PrioritizeRecentN = 10 -- If using priority queue, the most recent N (default 10) operations are prioritized using round-robin
+
+
+
+-- Greedy meshing settings
+
+Settings.UseGreedyMeshing = true
+
+Settings.GMTraversalsPerFrame = 10000 -- How many times greedy meshing can iterate through a 3D grid for each worker. Effectively limits the number of visited cells per frame
+
+Settings.GMPartCreationsPerFrame = 500 -- How many parts greedy meshing should try to make every frame once the worker is finished traversing. This is a soft-limit, not a hard-limit, for smooth visual display
+
+Settings.GMWorkerCount = 5 -- How many greedy meshing workers there are. Each worker performs calculations for a single dirty group before displaying the meshed output
+
+
+
+-- Puppet voxel settings
+
+Settings.PuppetMaxCount = 8191 -- HARD CAP 8191
+
+Settings.PuppetSleepVelocity = 0.1 -- How slow a puppet has to be moving to not get replicated (and eventually become anchored)
+
+Settings.PuppetAnchorTimeout = 1 -- How long a puppet master moving slower than PuppetSleepVelocity has before becoming anchored (seconds)
+
+Settings.PuppetReplicationFrequency = 20 -- How frequently puppet CFrames are sent to each client (default 20 fps/Hz target replication frequency)
+
+Settings.ClientTweenPuppets = true -- If true, the client will tween between puppet CFrame replications (Client-side only setting)
+
+Settings.ClientTweenDistanceLimit = 300 -- Voxels farther than 100 studs away don't get interpolated
+
+
+
+return Settings