rbxts-vex 1.0.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "rbxts-vex",
+  "main": "src/init.luau",
+  "types": "src/index.d.ts",
+  "version": "1.0.0",
+  "description": "An efficient, performance-minded voxel destruction model. Created by EternalEthel/qrisquinn (same person).",
+  "license": "MIT",
+  "author": "kunosyn",
+  "keywords": [
+    "roblox-ts",
+    "rbxts",
+    "voxel",
+    "destruction"
+  ],
+  "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/Config.luau

@@ -0,0 +1,85 @@
+--[[
+	Config
+	
+	Manages default configuration and validates user-provided settings.
+	Centralizes all tunable parameters for the Vex system.
+]]
+
+local Config = {}
+
+Config.DEFAULTS = {
+	voxelSize = 1,
+	useGreedyMesh = true,
+	maxVoxels = 10000,
+	lifetime = nil,
+	material = nil,
+	collisionGroup = "Debris",
+	anchored = false,
+	weldAdjacent = true,
+}
+
+Config.LIMITS = {
+	MIN_VOXEL_SIZE = 0.1,
+	MAX_VOXEL_SIZE = 10,
+	MIN_LIFETIME = 1,
+	MAX_VOXELS = 50000,
+}
+
+
+function Config.validate(userConfig)
+	local validated = {}
+
+	for key, defaultValue in pairs(Config.DEFAULTS) do
+		local value = userConfig[key]
+
+		if value == nil then
+			validated[key] = defaultValue
+		else
+			validated[key] = value
+		end
+	end
+
+	if validated.voxelSize < Config.LIMITS.MIN_VOXEL_SIZE then
+		warn(string.format("voxelSize %.2f below minimum, clamping to %.2f", 
+			validated.voxelSize, Config.LIMITS.MIN_VOXEL_SIZE))
+		validated.voxelSize = Config.LIMITS.MIN_VOXEL_SIZE
+	end
+
+	if validated.voxelSize > Config.LIMITS.MAX_VOXEL_SIZE then
+		warn(string.format("voxelSize %.2f above maximum, clamping to %.2f", 
+			validated.voxelSize, Config.LIMITS.MAX_VOXEL_SIZE))
+		validated.voxelSize = Config.LIMITS.MAX_VOXEL_SIZE
+	end
+
+	if validated.maxVoxels > Config.LIMITS.MAX_VOXELS then
+		warn(string.format("maxVoxels %d above limit, clamping to %d", 
+			validated.maxVoxels, Config.LIMITS.MAX_VOXELS))
+		validated.maxVoxels = Config.LIMITS.MAX_VOXELS
+	end
+
+	if validated.lifetime and validated.lifetime < Config.LIMITS.MIN_LIFETIME then
+		warn(string.format("lifetime %.1f below minimum, clamping to %.1f", 
+			validated.lifetime, Config.LIMITS.MIN_LIFETIME))
+		validated.lifetime = Config.LIMITS.MIN_LIFETIME
+	end
+
+	return validated
+end
+
+
+function Config.merge(baseConfig, overrides)
+	local merged = {}
+
+	for key, value in pairs(baseConfig) do
+		merged[key] = value
+	end
+
+	for key, value in pairs(overrides) do
+		merged[key] = value
+	end
+
+	return merged
+end
+
+
+return Config

package/src/GreedyMesher.luau

@@ -0,0 +1,189 @@
+--[[
+	GreedyMesher
+	
+	Implements greedy meshing algorithm to combine adjacent voxels
+	into larger parts, dramatically reducing part count.
+	
+	Algorithm: Scans voxel grid layer by layer, merging rectangular
+	regions of same-material voxels into single parts.
+	
+	API:
+	  - GreedyMesher.mesh(grid) -> meshes[]
+]]
+
+local GreedyMesher = {}
+
+
+local function canMerge(voxel1, voxel2)
+	if not voxel1 or not voxel2 then
+		return false
+	end
+
+	if voxel1.material ~= voxel2.material then
+		return false
+	end
+
+	if math.abs(voxel1.color.R - voxel2.color.R) > 0.01 then
+		return false
+	end
+
+	if math.abs(voxel1.color.G - voxel2.color.G) > 0.01 then
+		return false
+	end
+
+	if math.abs(voxel1.color.B - voxel2.color.B) > 0.01 then
+		return false
+	end
+
+	return true
+end
+
+
+local function createMesh(minX, minY, minZ, maxX, maxY, maxZ, material, color, voxelSize)
+	return {
+		min = Vector3.new(minX, minY, minZ),
+		max = Vector3.new(maxX, maxY, maxZ),
+		size = Vector3.new(
+			(maxX - minX + 1) * voxelSize,
+			(maxY - minY + 1) * voxelSize,
+			(maxZ - minZ + 1) * voxelSize
+		),
+		center = Vector3.new(
+			(minX + maxX) / 2 * voxelSize,
+			(minY + maxY) / 2 * voxelSize,
+			(minZ + maxZ) / 2 * voxelSize
+		),
+		material = material,
+		color = color
+	}
+end
+
+
+local function getVoxelKey(x, y, z)
+	return string.format("%d,%d,%d", x, y, z)
+end
+
+
+function GreedyMesher.mesh(grid)
+	local meshes = {}
+	local processed = {}
+
+	local minX = grid.bounds.min.X
+	local minY = grid.bounds.min.Y
+	local minZ = grid.bounds.min.Z
+	local maxX = grid.bounds.max.X
+	local maxY = grid.bounds.max.Y
+	local maxZ = grid.bounds.max.Z
+
+	for y = minY, maxY do
+		for z = minZ, maxZ do
+			for x = minX, maxX do
+				local key = getVoxelKey(x, y, z)
+
+				if grid.voxels[key] and not processed[key] then
+					local voxel = grid.voxels[key]
+					local startX = x
+					local endX = x
+
+					while endX + 1 <= maxX do
+						local nextKey = getVoxelKey(endX + 1, y, z)
+						local nextVoxel = grid.voxels[nextKey]
+
+						if not nextVoxel or processed[nextKey] or not canMerge(voxel, nextVoxel) then
+							break
+						end
+
+						endX = endX + 1
+					end
+
+					local endZ = z
+					local canExpandZ = true
+
+					while canExpandZ and endZ + 1 <= maxZ do
+						for testX = startX, endX do
+							local testKey = getVoxelKey(testX, y, endZ + 1)
+							local testVoxel = grid.voxels[testKey]
+
+							if not testVoxel or processed[testKey] or not canMerge(voxel, testVoxel) then
+								canExpandZ = false
+								break
+							end
+						end
+
+						if canExpandZ then
+							endZ = endZ + 1
+						end
+					end
+
+					local endY = y
+					local canExpandY = true
+
+					while canExpandY and endY + 1 <= maxY do
+						for testZ = z, endZ do
+							for testX = startX, endX do
+								local testKey = getVoxelKey(testX, endY + 1, testZ)
+								local testVoxel = grid.voxels[testKey]
+
+								if not testVoxel or processed[testKey] or not canMerge(voxel, testVoxel) then
+									canExpandY = false
+									break
+								end
+							end
+
+							if not canExpandY then
+								break
+							end
+						end
+
+						if canExpandY then
+							endY = endY + 1
+						end
+					end
+
+					for markY = y, endY do
+						for markZ = z, endZ do
+							for markX = startX, endX do
+								local markKey = getVoxelKey(markX, markY, markZ)
+								processed[markKey] = true
+							end
+						end
+					end
+
+					local mesh = createMesh(
+						startX, y, z,
+						endX, endY, endZ,
+						voxel.material,
+						voxel.color,
+						grid.voxelSize
+					)
+
+					table.insert(meshes, mesh)
+				end
+			end
+		end
+	end
+
+	return meshes
+end
+
+
+function GreedyMesher.createNaiveMeshes(grid)
+	local meshes = {}
+
+	for key, voxel in pairs(grid.voxels) do
+		local mesh = createMesh(
+			voxel.x, voxel.y, voxel.z,
+			voxel.x, voxel.y, voxel.z,
+			voxel.material,
+			voxel.color,
+			grid.voxelSize
+		)
+
+		table.insert(meshes, mesh)
+	end
+
+	return meshes
+end
+
+
+return GreedyMesher

package/src/VoxelGrid.luau

@@ -0,0 +1,246 @@
+--[[
+	VoxelGrid
+	
+	Handles conversion of parts into 3D voxel grids.
+	Manages coordinate transformations and grid data structures.
+	
+	API:
+	  - VoxelGrid.fromPart(part, voxelSize) -> grid
+	  - VoxelGrid.fromModel(model, voxelSize) -> grid
+]]
+
+local VoxelGrid = {}
+
+local EPSILON = 0.01
+
+
+local function createGrid()
+	return {
+		voxels = {},
+		bounds = {
+			min = Vector3.new(math.huge, math.huge, math.huge),
+			max = Vector3.new(-math.huge, -math.huge, -math.huge)
+		},
+		material = Enum.Material.Plastic,
+		color = Color3.new(0.5, 0.5, 0.5),
+		voxelSize = 1
+	}
+end
+
+
+local function worldToGrid(worldPos, origin, voxelSize)
+	local relative = worldPos - origin
+
+	return Vector3.new(
+		math.floor(relative.X / voxelSize + 0.5),
+		math.floor(relative.Y / voxelSize + 0.5),
+		math.floor(relative.Z / voxelSize + 0.5)
+	)
+end
+
+
+local function gridToWorld(gridPos, origin, voxelSize)
+	return origin + Vector3.new(
+		gridPos.X * voxelSize,
+		gridPos.Y * voxelSize,
+		gridPos.Z * voxelSize
+	)
+end
+
+
+local function getGridKey(x, y, z)
+	return string.format("%d,%d,%d", x, y, z)
+end
+
+
+local function addVoxel(grid, x, y, z, material, color)
+	local key = getGridKey(x, y, z)
+
+	grid.voxels[key] = {
+		x = x,
+		y = y,
+		z = z,
+		material = material or grid.material,
+		color = color or grid.color
+	}
+
+	grid.bounds.min = Vector3.new(
+		math.min(grid.bounds.min.X, x),
+		math.min(grid.bounds.min.Y, y),
+		math.min(grid.bounds.min.Z, z)
+	)
+
+	grid.bounds.max = Vector3.new(
+		math.max(grid.bounds.max.X, x),
+		math.max(grid.bounds.max.Y, y),
+		math.max(grid.bounds.max.Z, z)
+	)
+end
+
+
+function VoxelGrid.fromPart(part, voxelSize)
+	if not part:IsA("BasePart") then
+		warn("VoxelGrid.fromPart requires a BasePart")
+		return nil
+	end
+
+	local grid = createGrid()
+	grid.voxelSize = voxelSize
+	grid.material = part.Material
+	grid.color = part.Color
+
+	local size = part.Size
+	local cframe = part.CFrame
+
+	local origin = cframe.Position - Vector3.new(
+		size.X / 2,
+		size.Y / 2,
+		size.Z / 2
+	)
+
+	local numVoxelsX = math.max(1, math.ceil(size.X / voxelSize))
+	local numVoxelsY = math.max(1, math.ceil(size.Y / voxelSize))
+	local numVoxelsZ = math.max(1, math.ceil(size.Z / voxelSize))
+
+	for x = 0, numVoxelsX - 1 do
+		for y = 0, numVoxelsY - 1 do
+			for z = 0, numVoxelsZ - 1 do
+				local worldPos = origin + Vector3.new(
+					(x + 0.5) * voxelSize,
+					(y + 0.5) * voxelSize,
+					(z + 0.5) * voxelSize
+				)
+
+				local region = Region3.new(
+					worldPos - Vector3.new(voxelSize/2, voxelSize/2, voxelSize/2),
+					worldPos + Vector3.new(voxelSize/2, voxelSize/2, voxelSize/2)
+				):ExpandToGrid(4)
+
+				local parts = workspace:FindPartsInRegion3(region, part, 1)
+
+				if #parts > 0 then
+					addVoxel(grid, x, y, z, part.Material, part.Color)
+				end
+			end
+		end
+	end
+
+	grid.origin = origin
+	grid.rotation = cframe - cframe.Position
+
+	return grid
+end
+
+
+function VoxelGrid.fromModel(model, voxelSize, maxVoxels)
+	if not model:IsA("Model") and not model:IsA("BasePart") then
+		warn("VoxelGrid.fromModel requires a Model or BasePart")
+		return nil
+	end
+
+	local parts = {}
+
+	if model:IsA("BasePart") then
+		table.insert(parts, model)
+	else
+		for _, descendant in ipairs(model:GetDescendants()) do
+			if descendant:IsA("BasePart") then
+				table.insert(parts, descendant)
+			end
+		end
+	end
+
+	if #parts == 0 then
+		warn("No parts found in model")
+		return nil
+	end
+
+	local grid = createGrid()
+	grid.voxelSize = voxelSize
+
+	local globalMin = Vector3.new(math.huge, math.huge, math.huge)
+	local globalMax = Vector3.new(-math.huge, -math.huge, -math.huge)
+
+	for _, part in ipairs(parts) do
+		local size = part.Size
+		local pos = part.Position
+
+		local partMin = pos - size / 2
+		local partMax = pos + size / 2
+
+		globalMin = Vector3.new(
+			math.min(globalMin.X, partMin.X),
+			math.min(globalMin.Y, partMin.Y),
+			math.min(globalMin.Z, partMin.Z)
+		)
+
+		globalMax = Vector3.new(
+			math.max(globalMax.X, partMax.X),
+			math.max(globalMax.Y, partMax.Y),
+			math.max(globalMax.Z, partMax.Z)
+		)
+	end
+
+	grid.origin = globalMin
+
+	local voxelCount = 0
+
+	for _, part in ipairs(parts) do
+		local size = part.Size
+		local cframe = part.CFrame
+
+		local numVoxelsX = math.max(1, math.ceil(size.X / voxelSize))
+		local numVoxelsY = math.max(1, math.ceil(size.Y / voxelSize))
+		local numVoxelsZ = math.max(1, math.ceil(size.Z / voxelSize))
+
+		for x = 0, numVoxelsX - 1 do
+			for y = 0, numVoxelsY - 1 do
+				for z = 0, numVoxelsZ - 1 do
+					if maxVoxels and voxelCount >= maxVoxels then
+						warn(string.format("Reached maxVoxels limit (%d), stopping voxelization", maxVoxels))
+						return grid
+					end
+
+					local localPos = Vector3.new(
+						(x - numVoxelsX/2 + 0.5) * voxelSize,
+						(y - numVoxelsY/2 + 0.5) * voxelSize,
+						(z - numVoxelsZ/2 + 0.5) * voxelSize
+					)
+
+					local worldPos = cframe:PointToWorldSpace(localPos)
+					local gridPos = worldToGrid(worldPos, grid.origin, voxelSize)
+
+					addVoxel(grid, gridPos.X, gridPos.Y, gridPos.Z, part.Material, part.Color)
+					voxelCount = voxelCount + 1
+				end
+			end
+		end
+	end
+
+	return grid
+end
+
+
+function VoxelGrid.getVoxelCount(grid)
+	local count = 0
+
+	for _ in pairs(grid.voxels) do
+		count = count + 1
+	end
+
+	return count
+end
+
+
+function VoxelGrid.getVoxel(grid, x, y, z)
+	local key = getGridKey(x, y, z)
+	return grid.voxels[key]
+end
+
+
+function VoxelGrid.iterator(grid)
+	return pairs(grid.voxels)
+end
+
+
+return VoxelGrid

package/src/VoxelPool.luau

@@ -0,0 +1,144 @@
+--[[
+	VoxelPool
+	
+	Object pool for voxel parts. Reuses parts instead of constantly
+	creating/destroying them for better performance.
+	
+	API:
+	  - VoxelPool.get(size, material, color, collisionGroup) -> Part
+	  - VoxelPool.release(part)
+	  - VoxelPool.clear()
+]]
+
+local VoxelPool = {}
+
+local pool = {}
+local activeCount = 0
+
+local MAX_POOL_SIZE = 1000
+local CONTAINER_NAME = "VoxelDebris"
+
+
+local function getContainer()
+	local container = workspace:FindFirstChild(CONTAINER_NAME)
+
+	if not container then
+		container = Instance.new("Folder")
+		container.Name = CONTAINER_NAME
+		container.Parent = workspace
+	end
+
+	return container
+end
+
+
+local function createKey(size, material, color)
+	return string.format("%.1f_%.1f_%.1f_%s_%d_%d_%d",
+		size.X, size.Y, size.Z,
+		tostring(material),
+		math.floor(color.R * 255),
+		math.floor(color.G * 255),
+		math.floor(color.B * 255)
+	)
+end
+
+
+function VoxelPool.get(size, material, color, collisionGroup)
+	local key = createKey(size, material, color)
+
+	if pool[key] and #pool[key] > 0 then
+		local part = table.remove(pool[key])
+		part.Anchored = false
+		part.CanCollide = true
+		part.Transparency = 0
+		part.Parent = getContainer()
+		activeCount = activeCount + 1
+
+		return part
+	end
+
+	local part = Instance.new("Part")
+	part.Size = size
+	part.Material = material
+	part.Color = color
+	part.TopSurface = Enum.SurfaceType.Smooth
+	part.BottomSurface = Enum.SurfaceType.Smooth
+	part.Anchored = false
+	part.CanCollide = true
+	part.Parent = getContainer()
+
+	if collisionGroup then
+		part.CollisionGroup = collisionGroup
+	end
+
+	activeCount = activeCount + 1
+
+	return part
+end
+
+
+function VoxelPool.release(part)
+	if not part or not part:IsA("BasePart") then
+		return
+	end
+
+	local key = createKey(part.Size, part.Material, part.Color)
+
+	if not pool[key] then
+		pool[key] = {}
+	end
+
+	if #pool[key] >= MAX_POOL_SIZE then
+		part:Destroy()
+		activeCount = math.max(0, activeCount - 1)
+		return
+	end
+
+	for _, child in ipairs(part:GetChildren()) do
+		if child:IsA("WeldConstraint") or child:IsA("Weld") then
+			child:Destroy()
+		end
+	end
+
+	part.Parent = nil
+	part.CFrame = CFrame.new(0, -10000, 0)
+	part.Anchored = true
+	part.CanCollide = false
+	part.Velocity = Vector3.new(0, 0, 0)
+	part.RotVelocity = Vector3.new(0, 0, 0)
+
+	table.insert(pool[key], part)
+	activeCount = math.max(0, activeCount - 1)
+end
+
+
+function VoxelPool.clear()
+	for key, parts in pairs(pool) do
+		for _, part in ipairs(parts) do
+			if part and part:IsA("Instance") then
+				part:Destroy()
+			end
+		end
+	end
+
+	pool = {}
+	activeCount = 0
+end
+
+
+function VoxelPool.getStats()
+	local pooledCount = 0
+
+	for _, parts in pairs(pool) do
+		pooledCount = pooledCount + #parts
+	end
+
+	return {
+		active = activeCount,
+		pooled = pooledCount,
+		total = activeCount + pooledCount
+	}
+end
+
+
+return VoxelPool

package/src/index.d.ts

@@ -0,0 +1,100 @@
+export interface VexOptions {
+    /**
+     * Bigger voxels = better performance.
+     * @default 1
+     */
+    voxelSize?: number;
+
+    /**
+     * Default optimization option, keep it on.
+     * @default true
+     */
+    useGreedyMesh?: boolean;
+
+    /**
+     * Max number of voxels which can be created, mainly a safety measure to prevent lag.
+     * @default 10000
+     */
+    maxVoxels?: number;
+
+    /**
+     * How long before cleaning up voxels.
+     */
+    lifetime?: number;
+
+    /**
+     * The material of the voxels.
+     */
+    material?: Enum.Material;
+
+    /**
+     * The collision group of the voxels.
+     * @default "Debris"
+     */
+    collisionGroup?: string;
+
+    /**
+     * Whether the voxels should be anchored or not.
+     * @default false
+     */
+    anchored?: boolean;
+
+    /**
+     * Whether to weld adjacent voxels together.
+     * @default true
+     */
+    weldAdjacent?: boolean;
+}
+
+export interface VoxelStructure {
+    /**
+     * Destroys the VoxelStructure and its physical Model/BasePart.
+     */
+    Destroy(): void;
+
+    /**
+     * Cleans up the voxels in the pool.
+     */
+    Cleanup(): void;
+
+    /**
+     * Applies Force to voxels in the structure from a specified position.
+     * @param force The Force to apply to the voxels.
+     * @param position The position at which to apply Force from.
+     */
+    ApplyForce(force: Vector3, position: Vector3): void;
+
+    /**
+     * Gets the current number of voxels.
+     * @returns The current number of voxels.
+     */
+    GetVoxelCount(): number;
+}
+
+export interface VoxelPoolStats {
+    readonly active: number;
+    readonly pooled: number;
+    readonly total: number;
+}
+
+declare const Vex: {
+    /**
+     * 
+     * @param source The BasePart or Model to voxelize.
+     * @param options Configuration settings.
+     * @returns A VoxelStructure instance.
+     */
+    new(source: BasePart | Model, options?: Readonly<VexOptions>): VoxelStructure;
+
+    /**
+     * @returns Stats about the current state of the voxel pool.
+     */
+    getPoolStats(): VoxelPoolStats;
+
+    /**
+     * Clears the voxel pool.
+     */
+    clearPool(): void;
+}
+
+export default Vex;

package/src/init.luau

@@ -0,0 +1,226 @@
+--[[
+	Vex 2.0 - Main Module
+	
+	High-performance voxel destruction system with greedy meshing
+	and object pooling.
+	
+	API:
+	  Vex.new(model, config) -> VoxelStructure
+	  
+	  VoxelStructure:Destroy()
+	  VoxelStructure:ApplyForce(force, position)
+	  VoxelStructure:Cleanup()
+	  VoxelStructure:GetVoxelCount()
+]]
+
+local Vex = {}
+Vex.__index = Vex
+
+local Config = require(script.Config)
+local VoxelGrid = require(script.VoxelGrid)
+local GreedyMesher = require(script.GreedyMesher)
+local VoxelPool = require(script.VoxelPool)
+
+local VoxelStructure = {}
+VoxelStructure.__index = VoxelStructure
+
+
+function VoxelStructure.new(source, config)
+	local self = setmetatable({}, VoxelStructure)
+
+	self.source = source
+	self.config = Config.validate(config or {})
+	self.parts = {}
+	self.isDestroyed = false
+	self.grid = nil
+	self.cleanupConnection = nil
+
+	return self
+end
+
+
+function VoxelStructure:_generateGrid()
+	if self.grid then
+		return self.grid
+	end
+
+	local grid
+
+	if self.source:IsA("BasePart") then
+		grid = VoxelGrid.fromPart(self.source, self.config.voxelSize)
+	else
+		grid = VoxelGrid.fromModel(
+			self.source, 
+			self.config.voxelSize,
+			self.config.maxVoxels
+		)
+	end
+
+	if not grid then
+		warn("Failed to generate voxel grid")
+		return nil
+	end
+
+	self.grid = grid
+
+	return grid
+end
+
+
+function VoxelStructure:_createParts(meshes)
+	local parts = {}
+
+	for _, mesh in ipairs(meshes) do
+		local material = self.config.material or mesh.material
+		local part = VoxelPool.get(
+			mesh.size,
+			material,
+			mesh.color,
+			self.config.collisionGroup
+		)
+
+		local worldCenter = self.grid.origin + mesh.center
+		part.CFrame = CFrame.new(worldCenter)
+		part.Anchored = self.config.anchored
+
+		table.insert(parts, part)
+		table.insert(self.parts, part)
+	end
+
+	return parts
+end
+
+
+function VoxelStructure:_weldAdjacent()
+	if not self.config.weldAdjacent then
+		return
+	end
+
+	local WELD_DISTANCE = self.config.voxelSize * 1.5
+
+	for i, part1 in ipairs(self.parts) do
+		for j = i + 1, #self.parts do
+			local part2 = self.parts[j]
+
+			local distance = (part1.Position - part2.Position).Magnitude
+
+			if distance <= WELD_DISTANCE then
+				local weld = Instance.new("WeldConstraint")
+				weld.Part0 = part1
+				weld.Part1 = part2
+				weld.Parent = part1
+			end
+		end
+	end
+end
+
+
+function VoxelStructure:_setupLifetime()
+	if not self.config.lifetime then
+		return
+	end
+
+	task.delay(self.config.lifetime, function()
+		self:Cleanup()
+	end)
+end
+
+
+function VoxelStructure:Destroy()
+	if self.isDestroyed then
+		warn("Structure already destroyed")
+		return
+	end
+
+	local grid = self:_generateGrid()
+
+	if not grid then
+		return
+	end
+
+	local meshes
+
+	if self.config.useGreedyMesh then
+		meshes = GreedyMesher.mesh(grid)
+	else
+		meshes = GreedyMesher.createNaiveMeshes(grid)
+	end
+
+	self:_createParts(meshes)
+	self:_weldAdjacent()
+	self:_setupLifetime()
+
+	if self.source and self.source.Parent then
+		self.source:Destroy()
+	end
+
+	self.isDestroyed = true
+end
+
+
+function VoxelStructure:ApplyForce(force, position)
+	if not self.isDestroyed then
+		warn("Call :Destroy() before applying forces")
+		return
+	end
+
+	local FORCE_RADIUS = 20
+
+	for _, part in ipairs(self.parts) do
+		if part and part.Parent then
+			local distance = (part.Position - position).Magnitude
+
+			if distance <= FORCE_RADIUS then
+				local direction = (part.Position - position).Unit
+				local falloff = math.max(0, 1 - (distance / FORCE_RADIUS))
+				local scaledForce = force * falloff
+
+				part.AssemblyLinearVelocity = part.AssemblyLinearVelocity + direction * scaledForce.Magnitude
+			end
+		end
+	end
+end
+
+
+function VoxelStructure:Cleanup()
+	for _, part in ipairs(self.parts) do
+		if part and part.Parent then
+			VoxelPool.release(part)
+		end
+	end
+
+	self.parts = {}
+
+	if self.cleanupConnection then
+		self.cleanupConnection:Disconnect()
+		self.cleanupConnection = nil
+	end
+end
+
+
+function VoxelStructure:GetVoxelCount()
+	return #self.parts
+end
+
+
+function Vex.new(source, config)
+	if not source then
+		warn("Vex.new requires a Model or BasePart")
+		return nil
+	end
+
+	return VoxelStructure.new(source, config)
+end
+
+
+function Vex.clearPool()
+	VoxelPool.clear()
+end
+
+
+function Vex.getPoolStats()
+	return VoxelPool.getStats()
+end
+
+
+return Vex