동적 복셀 지형 아키텍처: 실시간 스무스 터레인 API, 복셀 밀도 연산 및 파편 물리 엔진

--!strict
-- VoxelMiningEngine.luau
-- 로블록스 스튜디오용 실시간 복셀 지형 절삭 및 파편 제어 모듈

local Workspace = game:GetService("Workspace")
local Debris = game:GetService("Debris")
local TweenService = game:GetService("TweenService")

local Terrain = Workspace.Terrain

export type MiningConfig = {
    MinDigRadius: number,
    MaxDigRadius: number,
    CooldownSec: number,
    MaxDebrisPerHit: number,
}

local VoxelMiningEngine = {}
VoxelMiningEngine.__index = VoxelMiningEngine

function VoxelMiningEngine.new(config: MiningConfig?)
    local self = setmetatable({}, VoxelMiningEngine)
    self.Config = config or {
        MinDigRadius = 2.0,
        MaxDigRadius = 6.0,
        CooldownSec = 0.25,
        MaxDebrisPerHit = 6,
    }
    self.PlayerCooldowns = {} :: { [Player]: number }
    return self
end

function VoxelMiningEngine:CanMine(player: Player): boolean
    local now = os.clock()
    local lastTime = self.PlayerCooldowns[player] or 0
    if now - lastTime >= self.Config.CooldownSec then
        self.PlayerCooldowns[player] = now
        return true
    end
    return false
end

function VoxelMiningEngine:CarveTerrain(centerPos: Vector3, radius: number): (Enum.Material, number)
    local clampedRadius = math.clamp(radius, self.Config.MinDigRadius, self.Config.MaxDigRadius)

    -- 파괴 전 중심 위치의 지형 재질 샘플링
    local sampleRegion = Region3.new(centerPos - Vector3.new(2,2,2), centerPos + Vector3.new(2,2,2))
    sampleRegion = sampleRegion:ExpandToGrid(4)
    local materials, occupancies = Terrain:ReadVoxels(sampleRegion, 4)

    local dominantMaterial = Enum.Material.Rock
    if materials[1] and materials[1][1] and materials[1][1][1] ~= Enum.Material.Air then
        dominantMaterial = materials[1][1][1]
    end

    -- 실시간 스무스 터레인 감산 연산
    Terrain:FillBall(centerPos, clampedRadius, Enum.Material.Air)

    return dominantMaterial, clampedRadius
end

function VoxelMiningEngine:SpawnDebris(centerPos: Vector3, material: Enum.Material, count: number)
    local debrisFolder = Workspace:FindFirstChild("MiningDebris")
    if not debrisFolder then
        debrisFolder = Instance.new("Folder")
        debrisFolder.Name = "MiningDebris"
        debrisFolder.Parent = Workspace
    end

    local spawnCount = math.clamp(count, 1, self.Config.MaxDebrisPerHit)
    for _ = 1, spawnCount do
        local chunk = Instance.new("Part")
        chunk.Size = Vector3.new(math.random(6, 12) / 10, math.random(6, 12) / 10, math.random(6, 12) / 10)
        chunk.Material = material
        chunk.Color = Terrain:GetMaterialColor(material)
        chunk.Position = centerPos + Vector3.new(
            math.random(-15, 15) / 10,
            math.random(0, 20) / 10,
            math.random(-15, 15) / 10
        )
        chunk.CanCollide = false
        chunk.CanTouch = false
        chunk.CanQuery = false
        chunk.Parent = debrisFolder

        -- 사방으로 튀는 물리 충격 속도 부여
        local impulse = Vector3.new(
            math.random(-25, 25),
            math.random(15, 35),
            math.random(-25, 25)
        )
        chunk.AssemblyLinearVelocity = impulse

        -- 자동 페이드아웃 및 가비지 수거
        task.delay(1.2, function()
            if chunk and chunk.Parent then
                local tween = TweenService:Create(chunk, TweenInfo.new(0.4), { Transparency = 1 })
                tween:Play()
                tween.Completed:Connect(function()
                    chunk:Destroy()
                end)
            end
        end)
    end
end

function VoxelMiningEngine:ExecuteMine(player: Player, targetHit: Vector3, radius: number): boolean
    if not self:CanMine(player) then
        return false
    end

    local mat, finalRadius = self:CarveTerrain(targetHit, radius)
    self:SpawnDebris(targetHit, mat, math.floor(finalRadius * 1.2))
    return true
end

return VoxelMiningEngine