로블록스 커스텀 카메라 시스템 개발: 2차 스프링 물리, 숄더 오프셋 및 스피어캐스트 충돌 방지

--!strict
local Workspace = game:GetService("Workspace")
local RunService = game:GetService("RunService")
local UserInputService = game:GetService("UserInputService")
local Players = game:GetService("Players")

local CameraController = {}

local camera = Workspace.CurrentCamera
local player = Players.LocalPlayer

local yaw = 0
local pitch = 0
local targetDistance = 12
local currentDistance = 12

-- 스프링 물리 상태 (위치, 속도, 강도, 감쇠)
local springPos = Vector3.zero
local springVel = Vector3.zero
local SPRING_STIFFNESS = 140
local SPRING_DAMPING = 22

local SPHERE_RADIUS = 0.6
local RAY_PARAMS = RaycastParams.new()
RAY_PARAMS.FilterType = RaycastFilterType.Exclude

function CameraController.Init()
    camera.CameraType = Enum.CameraType.Scriptable
    UserInputService.MouseBehavior = Enum.MouseBehavior.LockCenter
    
    UserInputService.InputChanged:Connect(function(input, processed)
        if processed then return end
        if input.UserInputType == Enum.UserInputType.MouseMovement then
            local sensitivity = 0.003
            yaw -= input.Delta.X * sensitivity
            pitch = math.clamp(pitch - (input.Delta.Y * sensitivity), -1.2, 1.2)
        end
    end)
    
    RunService.RenderStepped:Connect(CameraController.Update)
end

function CameraController.Update(dt: number)
    local char = player.Character
    if not char then return end
    local head = char:FindFirstChild("Head") :: BasePart?
    if not head then return end
    
    RAY_PARAMS.FilterDescendantsInstances = { char }
    
    -- 1. 기준 초점 CFrame 및 우측 숄더 오프셋 설정
    local focusCFrame = CFrame.new(head.Position) * CFrame.Angles(0, yaw, 0) * CFrame.Angles(pitch, 0, 0)
    local desiredOffset = Vector3.new(2.2, 1.0, 0) -- 우측 어깨 오프셋
    
    -- 2. 2차 스프링 적분 계산
    local force = (desiredOffset - springPos) * SPRING_STIFFNESS - (springVel * SPRING_DAMPING)
    springVel += force * dt
    springPos += springVel * dt
    
    -- 3. 스피어캐스트를 통한 3D 벽 충돌 사전 예측
    local rayOrigin = head.Position
    local targetCamPos = (focusCFrame * CFrame.new(springPos)).Position - (focusCFrame.LookVector * targetDistance)
    local castDirection = targetCamPos - rayOrigin
    
    local hit = Workspace:Spherecast(rayOrigin, SPHERE_RADIUS, castDirection, RAY_PARAMS)
    local adjustedDistance = targetDistance
    if hit and hit.Instance and hit.Instance.CanCollide then
        adjustedDistance = math.max(1.5, (hit.Position - rayOrigin).Magnitude - SPHERE_RADIUS)
    end
    
    -- 거리 보간으로 부드러운 카메라 줌인/줌아웃
    currentDistance += (adjustedDistance - currentDistance) * math.min(1, dt * 25)
    
    -- 4. 최종 카메라 CFrame 적용
    local finalCFrame = focusCFrame * CFrame.new(springPos) * CFrame.new(0, 0, currentDistance)
    camera.CFrame = finalCFrame
end

return CameraController