로블록스 커스텀 무브먼트 아키텍처: 에어 스트레이프 가속 벡터, 버니합 지면 마찰 유예 윈도우 및 운동학 컨트롤러

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

local MovementEngine = {}
MovementEngine.__index = MovementEngine

export type ControllerConfig = {
    RootPart: BasePart,
    MaxAirSpeed: number,
    AirAcceleration: number,
    GroundMaxSpeed: number,
    GroundAcceleration: number,
    FrictionCoeff: number,
    JumpPower: number,
    FrictionGraceFrames: number,
}

export type MovementState = {
    Config: ControllerConfig,
    Velocity: Vector3,
    IsGrounded: boolean,
    GraceTimer: number,
    JumpBuffered: boolean,
    RayParams: RaycastParams,
}

function MovementEngine.New(root: BasePart): MovementState
    local rayParams = RaycastParams.new()
    rayParams.FilterType = RaycastFilterType.Exclude
    rayParams.FilterDescendantsInstances = { root.Parent or root }

    local state: MovementState = {
        Config = {
            RootPart = root,
            MaxAirSpeed = 7.5,
            AirAcceleration = 120.0,
            GroundMaxSpeed = 22.0,
            GroundAcceleration = 14.0,
            FrictionCoeff = 6.0,
            JumpPower = 48.0,
            FrictionGraceFrames = 4,
        },
        Velocity = Vector3.zero,
        IsGrounded = true,
        GraceTimer = 0,
        JumpBuffered = false,
        RayParams = rayParams,
    }
    return state
end

local function Accelerate(vel: Vector3, wishdir: Vector3, wishspeed: number, accel: number, dt: number): Vector3
    local currentspeed = vel:Dot(wishdir)
    local addspeed = wishspeed - currentspeed
    if addspeed <= 0 then
        return vel
    end

    local accelspeed = math.min(accel * wishspeed * dt, addspeed)
    return vel + (wishdir * accelspeed)
end

function MovementEngine.Step(state: MovementState, inputDir: Vector3, cameraLook: Vector3, cameraRight: Vector3, dt: number)
    local root = state.Config.RootPart
    local cfg = state.Config

    -- 지면 충돌 검사
    local origin = root.Position
    local cast = Workspace:Spherecast(origin, 1.0, Vector3.new(0, -1.8, 0), state.RayParams)
    local wasGrounded = state.IsGrounded
    state.IsGrounded = (cast ~= nil)

    -- 버니합을 위한 착지 유예 프레임 설정
    if not wasGrounded and state.IsGrounded then
        state.GraceTimer = cfg.FrictionGraceFrames
    end

    -- 2D 수평 Wishdir 벡터 구성
    local camForwardFlat = Vector3.new(cameraLook.X, 0, cameraLook.Z).Unit
    local camRightFlat = Vector3.new(cameraRight.X, 0, cameraRight.Z).Unit
    local wishdir = (camForwardFlat * inputDir.Z + camRightFlat * inputDir.X)
    local wishspeed = 0

    if wishdir.Magnitude > 0.05 then
        wishdir = wishdir.Unit
        wishspeed = cfg.GroundMaxSpeed
    end

    local horizVel = Vector3.new(root.AssemblyLinearVelocity.X, 0, root.AssemblyLinearVelocity.Z)
    local vertVel = root.AssemblyLinearVelocity.Y

    if state.IsGrounded then
        if state.GraceTimer > 0 and state.JumpBuffered then
            -- 버니합 성공: 마찰 스킵 후 재도약
            vertVel = cfg.JumpPower
            state.IsGrounded = false
            state.GraceTimer = 0
            state.JumpBuffered = false
        elseif state.GraceTimer <= 0 then
            -- 지면 마찰력 적용
            local speed = horizVel.Magnitude
            if speed > 0.1 then
                local drop = speed * cfg.FrictionCoeff * dt
                horizVel = horizVel * math.max(speed - drop, 0) / speed
            end
            horizVel = Accelerate(horizVel, wishdir, wishspeed, cfg.GroundAcceleration, dt)
        else
            state.GraceTimer -= 1
        end
    else
        -- 공중 스트레이프 가속 적용
        local airWishSpeed = math.min(wishspeed, cfg.MaxAirSpeed)
        horizVel = Accelerate(horizVel, wishdir, airWishSpeed, cfg.AirAcceleration, dt)
    end

    root.AssemblyLinearVelocity = Vector3.new(horizVel.X, vertVel, horizVel.Z)
end

return MovementEngine