동적 그래플 및 진자 역학: 구속 기구학, 케이블 장력 및 각운동량 보존 법칙

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

export type GrappleSession = {
    PlayerRoot: BasePart,
    AnchorPoints: { Vector3 }, // stack of corner pivots, index 1 is root anchor
    CurrentRopeLength: number,
    TargetRopeLength: number,
    ReelSpeed: number,
    IsActive: boolean,
    VisualBeam: Beam?,
}

local GrappleEngine = {}
GrappleEngine.__index = GrappleEngine

local GRAVITY_ACCEL = 196.2

function GrappleEngine.new(rootPart: BasePart)
    local self = setmetatable({}, GrappleEngine)
    self.PlayerRoot = rootPart
    self.AnchorPoints = {}
    self.CurrentRopeLength = 0
    self.TargetRopeLength = 0
    self.ReelSpeed = 35 // studs per second
    self.IsActive = false
    return self
end

function GrappleEngine:Attach(worldAnchor: Vector3)
    self.AnchorPoints = { worldAnchor }
    local dist = (worldAnchor - self.PlayerRoot.Position).Magnitude
    self.CurrentRopeLength = dist
    self.TargetRopeLength = dist
    self.IsActive = true
end

function GrappleEngine:Detach(): Vector3
    if not self.IsActive then return Vector3.zero end
    self.IsActive = false

    local vel = self.PlayerRoot.AssemblyLinearVelocity
    -- Add tangential release boost
    local forward = self.PlayerRoot.CFrame.LookVector
    local boost = (vel.Unit + forward * 0.4).Unit * math.max(vel.Magnitude * 1.15, 60)

    self.PlayerRoot.AssemblyLinearVelocity = boost
    self.AnchorPoints = {}
    return boost
end

function GrappleEngine:Update(dt: number)
    if not self.IsActive or #self.AnchorPoints == 0 then return end

    local activePivot = self.AnchorPoints[#self.AnchorPoints]
    local rootPos = self.PlayerRoot.Position
    local rootVel = self.PlayerRoot.AssemblyLinearVelocity
    local mass = self.PlayerRoot.AssemblyMass

    -- Check for corner wrapping
    local rayParams = RaycastParams.new()
    rayParams.FilterType = RaycastFilterType.Exclude

    local rayDir = (activePivot - rootPos)
    local hit = Workspace:Raycast(rootPos, rayDir, rayParams)
    if hit and (hit.Position - activePivot).Magnitude > 1.5 then
        -- Add new corner pivot offset slightly outward from hit surface
        local cornerPivot = hit.Position + hit.Normal * 0.5
        table.insert(self.AnchorPoints, cornerPivot)
        activePivot = cornerPivot
    elseif #self.AnchorPoints > 1 then
        -- Check if previous pivot has direct line of sight to unwrap
        local parentPivot = self.AnchorPoints[#self.AnchorPoints - 1]
        local unwrapHit = Workspace:Raycast(rootPos, parentPivot - rootPos, rayParams)
        if not unwrapHit then
            table.remove(self.AnchorPoints, #self.AnchorPoints)
            activePivot = parentPivot
        end
    end

    -- Reel in adjustment
    if self.TargetRopeLength < self.CurrentRopeLength then
        self.CurrentRopeLength = math.max(self.TargetRopeLength, self.CurrentRopeLength - self.ReelSpeed * dt)
    end

    local toPivot = (activePivot - rootPos)
    local currentDist = toPivot.Magnitude
    local radialDir = toPivot.Unit

    -- Constraint enforcement: if player exceeds rope length, apply corrective centripetal force
    if currentDist > self.CurrentRopeLength then
        local outwardSpeed = rootVel:Dot(-radialDir)
        if outwardSpeed > 0 then
            -- Remove outward velocity component
            local velocityCorrection = radialDir * outwardSpeed
            self.PlayerRoot.AssemblyLinearVelocity = rootVel + velocityCorrection
            rootVel = self.PlayerRoot.AssemblyLinearVelocity
        end

        -- Calculate centripetal tension: F = m * (v_tan^2 / r)
        local tanVel = rootVel - (radialDir * rootVel:Dot(radialDir))
        local centripetalMag = mass * (tanVel.Magnitude^2 / self.CurrentRopeLength)
        local gravityComponent = mass * GRAVITY_ACCEL * math.max(0, -radialDir.Y)

        local totalTension = radialDir * (centripetalMag + gravityComponent)
        self.PlayerRoot:ApplyAssemblyForce(totalTension)
    end
end

return GrappleEngine