Humanoid

Humanoid : Instance

Overview

Humanoid 객체는 단순한 모델 인스턴스를 실제 캐릭터처럼 동작하도록 만드는 핵심 요소로, 이를 통해 캐릭터는 게임 속에서 걷거나 점프하는 기본적인 움직임을 수행하며 다양한 오브젝트와 상호작용할 수 있습니다.

Humanoid는 최상위 오브젝트인 Model(Character)의 하위에 속하며, 캐릭터의 행동과 상태를 제어하는 Humanoid, 캐릭터의 중심을 담당하는 HumanoidRootPart, 머리·몸통·양팔·양다리로 이루어진 6개의 MeshPart, 그리고 22개의 Bone으로 구성된 Skeleton 구조로 이루어져 있습니다.

Properties

AirControl

number

휴머노이드가 공중에서 이동 입력에 반응하는 정도를 정의하며, 기본값은 0.9입니다.

값이 0에 가까울수록 점프나 낙하 중에 방향 전환이 잘 되지 않고, 1에 가까울수록 공중에서도 지상에 가까운 제어감을 느낄 수 있습니다.

Code Samples

Humanoid.AirControl = 0.5

AutoJumpEnabled

bool

현재 지원되지 않습니다.

Code Samples

AutoRotate

bool

현재 지원되지 않습니다.

Code Samples

AutomaticScalingEnabled

bool

현재 지원되지 않습니다.

Code Samples

BlendSpace

BlendSpace

사용할 블렌드스페이스를 지정하는 속성입니다.

블렌드스페이스는 캐릭터의 속도나 이동 방향과 같은 매개변수를 기반으로 여러 애니메이션을 보간하여, 상황에 맞게 부드럽게 전환되고 혼합된 애니메이션을 재생하는 기능입니다.

Code Samples

Humanoid.BlendSpace = BasicBlendSpace

CameraOffset

Vector3

이 속성 대신 Camera의 CameraOffset 속성 사용을 권장합니다.

Code Samples

CapsuleHeight

number

휴머노이드의 충돌 판정을 담당하는 캡슐의 세로 높이를 지정하는 속성으로 기본값은 164입니다.

캐릭터의 실제 메시 크기와 무관하게 충돌 영역에만 영향을 주며, 값이 커지면 캐릭터가 더 큰 충돌체를 가진 것처럼 동작합니다.

Code Samples

Humanoid.CapsuleHeight = 82

CapsuleRadius

number

휴머노이드의 충돌 캡슐의 반지름을 정의하는 속성으로 기본값은 24입니다.

값을 줄이면 좁은 통로나 작은 공간을 통과할 수 있고, 크게 하면 충돌 판정이 넓어져 다른 오브젝트와의 상호작용 범위가 커집니다.

Code Samples

Humanoid.CapsuleRadius = 12

CharacterMeshPos

Vector3

휴머노이드의 메시 위치를 기준 좌표에서 얼마나 이동시킬지 지정하는 속성입니다. 기본값은 (0, -85, 0)입니다.

주로 캐릭터 메시와 충돌 캡슐 사이의 정렬을 보정하거나, 커스텀 리그에서 외형을 약간 이동시킬 때 사용됩니다.

Code Samples

Humanoid.CharacterMeshPos = Vector3.new(0, -1, 0)

DefaultBlendSpace

BlendSpace

{Description Slot}

Code Samples

Humanoid.DefaultBlendSpace = BasicBlendSpace

DisplayDistanceType

Enum.HumanoidDisplayDistanceType

Code Samples

DisplayName

string

현재 지원되지 않습니다.

Code Samples

FallingDeceleration

number

휴머노이드가 공중에서 낙하할 때 속도가 줄어드는 정도를 제어하는 속성입니다. 기본값은 2,500입니다.

값이 0이면 낙하 중에 별도의 감속이 적용되지 않고, 값이 클수록 떨어지는 동안 점차 속도가 줄어들어 더 부드럽게 착지하는 느낌을 줄 수 있습니다.

Code Samples

Humanoid.FallingDeceleration = 0

FallingLateralFriction

number

휴머노이드가 공중에서 좌우로 이동할 때 적용되는 마찰 계수를 정의하는 속성이며, 기본값은 16입니다.

값이 작으면 낙하 중 좌우 이동이 미끄러지듯 부드럽게 이어지고, 크면 공중에서 방향 전환이 빠르게 제어됩니다.

Code Samples

Humanoid.FallingLateralFriction = 32

GravityScale

number

휴머노이드에 적용되는 중력의 배율을 지정하는 속성입니다. 기본값은 2.1입니다.

값이 커질수록 캐릭터가 더 빠르게 떨어지고 점프 높이가 낮아지며, 작을수록 공중에서 더 오래 체공하는 느낌을 줍니다.

Code Samples

Humanoid.GravityScale = 1

GroundFriction

number

휴머노이드가 지상에서 이동할 때 적용되는 마찰 계수를 나타내며, 기본값은 16입니다.

캐릭터가 방향을 전환할 때 체감되는 마찰에 가까우며, 값이 낮으면 커브 시 미끄러지는 느낌이 강해지고 높으면 방향 전환이 더 날카롭게 이루어집니다.

Code Samples

Humanoid.GroundFriction = 5

Health

number

휴머노이드의 현재 체력을 나타내는 속성입니다.

값은 0 이상 MaxHealth 이하 범위에서만 유효하며, 범위를 벗어난 값은 자동으로 해당 구간 내로 보정됩니다.

캐릭터가 사망 상태일 경우 이 값은 강제로 0으로 고정되며, 체력을 감소시킬 때는 속성을 직접 변경하기보다는 TakeDamage() 메서드를 사용하는 것이 권장됩니다.

체력이 0에 도달하면 휴머노이드는 자동으로 Dead 상태로 전환되며, ChangeState() 메서드를 통해 Dead 상태로 변경되는 경우에도 Health 값은 0으로 설정됩니다.

Code Samples

Humanoid.Health = 0

HealthDisplayDistance

number

현재 지원되지 않습니다.

Code Samples

HipHeight

number

현재 지원되지 않습니다.

Code Samples

HitboxType

Enum.HitboxType

휴머노이드의 피격 판정 방식을 정의하는 속성입니다.

기본값은 Single로, 캐릭터 전체를 하나의 캡슐 형태 히트박스로 감싸며 부위별 피격 판정은 지원하지 않습니다.

SixBody 또는 FittedSixBody로 설정하면 머리, 몸통, 팔, 다리 등 주요 신체 부위에 고정된 히트박스가 생성되어 부위별 판정이 가능하며, 특히 FittedSixBody는 캐릭터의 외형과 착용한 의상에 맞추어 히트박스가 세밀하게 조정됩니다.

이 값은 Workspace에서 사전에 구성해야 하며, 게임 실행 중에는 런타임에서 수정할 수 없습니다. 따라서 해당 속성은 반드시 스튜디오 편집 단계에서 미리 설정해야 합니다.

Code Samples

print(Humanoid.HitBoxType)

IgnoreBaseRotation

bool

휴머노이드가 서 있는 바닥이 회전할 때 그 회전을 입력과 카메라에 반영할지 여부를 제어하는 속성입니다.

기본값은 true이고, 기본 상태에서는 캐릭터가 회전하는 플랫폼 위에 있더라도 물리적으로는 함께 회전하지만, 입력 방향과 카메라는 그 영향을 받지 않습니다.

반대로 이 값을 false로 설정하면 바닥 회전이 캐릭터와 카메라 모두에 전달되어, 캐릭터의 조작 방향과 시점이 함께 회전하는 느낌을 줍니다.

Code Samples

print(Humanoid.IgnoreBaseRotation)
Humanoid.IgnoreBaseRotation = false

Jump

bool

휴머노이드가 점프 동작을 시도하고 있는지를 나타내는 속성입니다.

이 값이 true로 설정되면 휴머노이드는 점프 상태로 전환되며, 점프가 완료되거나 중간에 취소되면 자동으로 false로 돌아갑니다.

플레이어 입력(스페이스바, 터치 조작 등)에 의해 자동으로 true로 전환되지만, 스크립트를 통해 직접 값을 설정하여 강제로 점프를 발생시킬 수도 있습니다.

Code Samples

print(Humanoid.Jump)

JumpHeight

number

휴머노이드가 점프했을 때 도달할 수 있는 최대 높이를 cm 단위로 결정하며, 기본값은 135입니다.

이 속성을 0으로 설정하면 휴머노이드는 점프할 수 없게 되지만, 점프를 완전히 제한하려면 값을 변경하기보다는 Humanoid:SetStateEnabled() 메서드를 사용해 Jumping 상태를 비활성화하는 것이 권장됩니다.

ℹ️ Overdare Studio 기본 설정: 스튜디오에서는 JumpHeight가 기본 점프 속성으로 사용되며, 크리에이터가 별도 변경하지 않는 한 JumpPower 대신 이 값을 기준으로 점프 동작이 계산됩니다.

Code Samples

Humanoid.JumpHeight = 200

JumpPower

number

휴머노이드가 점프할 때 위로 가해지는 힘의 크기를 정의하는 속성입니다.

기본값은 400이며, 실제 점프 높이는 Workspace.Gravity에 설정된 중력 값의 영향을 함께 받습니다.

이 속성을 0으로 설정하면 휴머노이드는 점프할 수 없게 되지만, 점프를 완전히 제한하려면 값을 변경하기보다는 Humanoid:SetStateEnabled() 메서드를 사용해 Jumping 상태를 비활성화하는 것이 권장됩니다.

Code Samples

Humanoid.JumpPower = 1000

LookCameraDirection

bool

카메라가 휴머노이드 캐릭터의 바라보는 방향을 따라가도록 할지 여부를 지정하는 속성입니다.

이 속성 대신 UserGameSettings.RotationType을 사용하는 것이 권장됩니다.

Code Samples

Humanoid.LookCameraDirection = true

MaxAcceleration

number

휴머노이드가 지상에서 가속할 수 있는 최대 속도를 정의하는 속성입니다.

값이 클수록 입력에 빠르게 반응하여 즉각적으로 최고 속도에 도달할 수 있으며, 낮게 설정하면 캐릭터의 움직임이 점진적이고 무거워집니다.

주로 게임의 조작감(가벼움 vs 묵직함)을 조정할 때 사용됩니다.

Code Samples

Humanoid.MaxAcceleration = 1500

MaxHealth

number

휴머노이드 최대 체력을 지정하는 속성입니다.

Code Samples

print(Humanoid.MaxHealth)

MaxJumpCount

number

휴머노이드가 연속해서 점프할 수 있는 최대 횟수를 지정하는 속성입니다. 기본값은 1이며, 이 경우 일반적인 단일 점프만 가능합니다.

값을 2 이상으로 설정하면 이중 점프나 그 이상의 연속 점프를 구현할 수 있으며, 0으로 지정하면 점프 자체가 불가능해집니다.

Code Samples

Humanoid.MaxJumpCount = 2

MaxSlopeAngle

number

휴머노이드가 오를 수 있는 최대 경사 각도를 정의합니다.

기본값은 45이며, 설정된 값보다 가파른 경사면에서는 휴머노이드가 미끄러져 내려가거나 이동할 수 없으며, 낮게 설정할수록 더 평평한 지형에서만 이동이 가능합니다.

Code Samples

Humanoid.MaxSlopeAngle = 60

MoveDirection

Vector3

현재 지원되지 않습니다.

Code Samples

PlatformStand

bool

현재 지원되지 않습니다.

Code Samples

RootPart

BasePart

휴머노이드의 중심 파트인 HumanoidRootPart를 가리키는 속성입니다. (읽기 전용)

이 파트는 캐릭터가 3D 공간에서 걷거나 뛰는 동작을 제어하는 기준점 역할을 하며, 일반적으로 화면에는 보이지 않습니다.

Code Samples

print(Humanoid.RootPart)

RotationSpeed

number

휴머노이드가 초(s)당 회전할 수 있는 속도를 도(º) 단위로 정의합니다. 기본값은 3,000입니다.

값을 낮추면 캐릭터가 방향을 바꿀 때 느리게 회전하고, 높이면 더 즉각적으로 시선을 돌립니다.

Code Samples

Humanoid.RotationSpeed = 180

Sit

bool

현재 지원되지 않습니다.

Code Samples

StompJumpMultiplier

number

휴머노이드가 다른 캐릭터를 밟았을 때 적용되는 점프 배율을 지정하는 속성입니다. 기본값은 0이며, 이 경우 밟더라도 추가 도약이 발생하지 않습니다.

값을 1 이상으로 설정하면 밟는 순간 일반 점프와 유사한 높이로 튀어 오르고, 더 큰 값을 주면 강한 바운스 효과를 만들 수 있습니다.

Code Samples

Humanoid.StompJumpMultiplier = 1.5

UseJumpPower

bool

휴머노이드가 점프 높이를 계산할 때 JumpPower 값을 사용할지 여부를 지정하는 속성입니다. 기본값은 false이며, 기본적으로는 JumpHeight가 적용됩니다.

이 값을 true로 설정하면 점프 높이는 JumpPower와 Workspace.Gravity 값의 조합으로 결정됩니다.

Code Samples

Humanoid.UseJumpPower = true
Humanoid.JumpPower = 600

WalkSpeed

number

이 속성은 휴머노이드가 초당 이동할 수 있는 속도를 정의하며, 기본값은 500입니다.

모바일 환경에서는 Studio에서 키보드로 조작할 때와 달리 조이스틱을 끝까지 기울이지 않으면 실제 이동 속도가 WalkSpeed 값보다 낮게 적용될 수 있습니다.

이 값을 0으로 지정하면 캐릭터는 움직이지 못하게 고정되며, 플레이어 입력 역시 무효화됩니다.

또한 오버데어의 기본 애니메이션 스크립트는 캐릭터의 실제 이동 속도에 맞추어 걷기와 달리기 애니메이션의 재생 속도를 자동으로 조정합니다.

Code Samples

Humanoid.WalkSpeed = 4000

WalkToPoint

Vector3

현재 지원되지 않습니다.

Code Samples

WalkingDeceleration

number

휴머노이드가 이동을 멈출 때 감속되는 정도를 나타내며, 기본값은 2,500입니다.

값이 크면 캐릭터가 즉시 멈추고, 값이 작으면 관성처럼 미끄러지듯 멈춥니다.

Code Samples

Humanoid.WalkingDeceleration = 500

Methods

AddAccessory

현재 지원되지 않습니다.

Parameters

Instance InAccessory

Return

void

Code Samples

ApplyDescription

입력된 HumanoidDescription 정보에 맞게 캐릭터의 외형을 변경합니다.

HumanoidDescription 객체는 복사된 뒤 휴머노이드에 저장되어, 이후 캐릭터의 외형 정의로 활용됩니다.

Parameters

HumanoidDescription InDescription	설정할 외형 정보입니다.
Enum.AssetTypeVerification InAssetTypeVerification	외형 정보에 포함된 에셋을 어떤 방식으로 검증할지 지정하는 속성입니다. (현재는 Default 값만 지원됩니다)

Return

void

Code Samples

local Workspace = game:GetService("Workspace")
local HumanoidDescription = Workspace:WaitForChild("HumanoidDescription")
Humanoid:ApplyDescription(HumanoidDescription, Enum.AssetTypeVerification.Default)

ApplyDescriptionReset

현재 지원되지 않습니다.

Parameters

HumanoidDescription InDescription
Enum.AssetTypeVerification InAssetTypeVerification

Return

void

Code Samples

ChangeState

휴머노이드의 상태를 지정된 HumanoidStateType 값으로 전환하여 현재 수행 중인 동작을 변경합니다.

다만 휴머노이드의 동작 특성상 일부 상태는 반영되지 않을 수 있습니다. 예를 들어 공중에 있을 때 Landed 상태로 설정하면 적용되지 않습니다.

상태 변경은 LocalScript에서 처리해야 합니다.

Parameters

Enum.HumanoidStateType StateType	변경할 상태입니다.

Return

void

Code Samples

Humanoid:ChangeState(Enum.HumanoidStateType.Physics)

EquipTool

휴머노이드가 지정된 Tool을 장착하도록 합니다.

이미 다른 도구를 장착 중이라면 먼저 해제한 뒤, 새로 전달된 도구를 장착합니다.

Parameters

Instance InTool	장착할 Tool입니다.

Return

void

Code Samples

Humanoid:EquipTool(Tool)

GetAccessories

현재 지원되지 않습니다.

Parameters

Return

Tuple

Code Samples

GetAppliedDescription

휴머노이드에 적용된 외형 정보(HumanoidDescription)를 반환합니다.

반환된 객체를 통해 현재 캐릭터의 외형 구성을 확인할 수 있으며, 필요할 경우 ApplyDescription() 메서드를 사용해 동일한 외형을 다른 캐릭터에 적용할 수도 있습니다.

외형 정보가 설정되어 있지 않은 경우 nil을 반환합니다.

Parameters

Return

HumanoidDescription	설정된 외형 정보를 반환합니다.

Code Samples

local Description = Humanoid:GetAppliedDescription()

GetState

휴머노이드가 현재 어떤 행동 상태에 있는지를 HumanoidStateType 값으로 반환하며, 이를 통해 캐릭터가 점프, 낙하, 달리기 등 어떤 행동을 수행 중인지 확인할 수 있습니다.

Parameters

Return

Enum.HumanoidStateType	휴머노이드의 현재 상태를 반환합니다.

Code Samples

print(Humanoid:GetState())

LoadAnimation

(deprecated) 휴머노이드에 특정 애니메이션을 불러와 적용하고, 재생 및 제어할 수 있도록 AnimationTrack 객체를 반환합니다.

이 메서드는 더 이상 권장되지 않으며, 대신 Animator:LoadAnimation()을 사용해야 합니다.

Parameters

Animation InAnimation	사용할 애니메이션입니다.

Return

AnimationTrack	반환된 애니메이션 트랙입니다.

Code Samples

local Animation = Instance.new("Animation")
Animation.AnimationId = "ovdrassetid://18850100" -- WinAnimation01

local AnimationTrack = Humanoid:LoadAnimation(Animation)

AnimationTrack:Play()

RemoveAccessories

현재 지원되지 않습니다.

Parameters

Return

void

Code Samples

SetStateEnabled

휴머노이드가 지정된 HumanoidStateType 상태에 진입할 수 있는지를 제어합니다.

특정 상태를 비활성화하면 스크립트에서 ChangeState()를 호출하거나 조건이 충족되더라도 해당 상태로 전환되지 않습니다.

주로 점프를 막거나 Climb 상태를 비활성화하는 데 활용되며, Running과 같이 일부 상태는 이 메서드로 제어할 수 없습니다.

Parameters

Enum.HumanoidStateType InHumanoidStateType	활성화 여부를 설정할 상태입니다.
bool bInEnabled	활성화 여부입니다.

Return

void

Code Samples

Humanoid:SetStateEnabled(Enum.HumanoidStateType.Climbing, false)

TakeDamage

휴머노이드의 체력을 지정한 값만큼 감소시키며, 음수 값을 전달하면 체력이 회복됩니다.

Parameters

number InDamage	체력에 적용할 값으로, 양수는 체력을 줄이고 음수는 체력을 회복시킵니다.

Return

void

Code Samples

Humanoid:TakeDamage(100)

UnequipTools

휴머노이드가 현재 장착하고 있는 모든 Tool을 해제합니다.

Parameters

Return

void

Code Samples

Humanoid:UnequipTools()

Events

ApplyDescriptionFinished

현재 지원되지 않습니다.

Parameters

Code Samples

Climbing

휴머노이드가 Climb 상태로 전환될 때 실행되는 이벤트입니다.

Parameters

Code Samples

local function OnClimbing()
    print("Climbing!")
end
Humanoid.Climbing:Connect(OnClimbing)

ClusterCompositionFinished

현재 지원되지 않습니다.

Parameters

Code Samples

Died

휴머노이드가 Dead 상태로 전환될 때 실행되는 이벤트로, 보통 체력이 0이 되었을 때 발생합니다.

Parameters

Code Samples

local function OnDied()
    print("Die!")
end
Humanoid.Died:Connect(OnDied)

EmoteTriggered

현재 지원되지 않습니다.

Parameters

Code Samples

FallingDown

현재 지원되지 않습니다.

Parameters

Code Samples

FreeFalling

휴머노이드가 Freefall 상태로 전환될 때 실행되는 이벤트로, 보통 공중에서 낙하할 때 발생합니다.

Parameters

Code Samples

local function OnFreeFalling()
    print("FreeFalling!")
end		
Humanoid.FreeFalling:Connect(OnFreeFalling)

GettingUp

현재 지원되지 않습니다.

Parameters

Code Samples

HealthChanged

휴머노이드의 체력이 변경될 때마다 실행되는 이벤트로, 체력이 0이 되어 Dead 상태로 전환될 때도 호출됩니다.

Parameters

number Health	변경된 체력입니다.

Code Samples

local function OnHealthChanged(health)
    print("HealthChanged!", health)
end		
Humanoid.HealthChanged:Connect(OnHealthChanged)

Jumping

휴머노이드가 Jumping 상태로 전환될 때 실행되는 이벤트입니다.

Parameters

Code Samples

local function OnJumping()
    print("Jumping!")
end		
Humanoid.Jumping:Connect(OnJumping)

Landed

휴머노이드가 Landed 상태로 전환될 때 실행되는 이벤트입니다.

Parameters

Code Samples

local function OnLanded()
    print("Landed!")
end		
Humanoid.Landed:Connect(Landed)

MoveToFinished

현재 지원되지 않습니다.

Parameters

Code Samples

PlatformStanding

현재 지원되지 않습니다.

Parameters

Code Samples

PlatformStandingMoving

현재 지원되지 않습니다.

Parameters

Code Samples

Running

휴머노이드가 Running 상태로 전환될 때 실행되는 이벤트입니다.

Parameters

Code Samples

local function OnRunning()
    print("Running!")
end		
Humanoid.Running:Connect(OnRunning)

StateChanged

휴머노이드가 다른 동작 상태로 전환될 때 실행되는 이벤트입니다.

단, 별도의 대기(idle) 상태는 존재하지 않으므로, 캐릭터가 정지했는지를 확인하려면 RootPart의 속도(AssemblyLinearVelocity)를 직접 확인해야 합니다.

Parameters

Enum.HumanoidStateType PreviousState	변경 전 상태입니다.
Enum.HumanoidStateType CurrentState	변경된 상태입니다.

Code Samples

local function OnStateChanged(prevState, newState)
    print("StateChanged!", prevState, "->", newState)
end		
Humanoid.StateChanged:Connect(OnStateChanged)

StateEnabledChanged

현재 지원되지 않습니다.

Parameters

Code Samples

Swimming

휴머노이드가 Swimming 상태로 전환될 때 실행되는 이벤트입니다.

Parameters

Code Samples

local function OnSwimming()
    print("Swimming!")
end		
Humanoid.Swimming:Connect(OnSwimming)

Touched

현재 지원되지 않습니다.

Parameters

Code Samples

See also

캐릭터