Humanoid

Humanoid : Instance

Overview

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

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

Properties

AutoJumpEnabled

bool

현재 지원되지 않습니다.

Code Samples

AutoRotate

bool

현재 지원되지 않습니다.

Code Samples

AutomaticScalingEnabled

bool

현재 지원되지 않습니다.

Code Samples

CameraOffset

Vector3

현재 지원되지 않습니다.

Code Samples

DisplayDistanceType

Enum.HumanoidDisplayDistanceType

현재 지원되지 않습니다.

Code Samples

DisplayName

string

현재 지원되지 않습니다.

Code Samples

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

Jump

bool

현재 지원되지 않습니다.

Code Samples

JumpHeight

number

이 속성은 휴머노이드가 점프했을 때 도달할 수 있는 최대 높이를 cm 단위로 결정합니다.

기본값은 81.639입니다.

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

Code Samples

JumpPower

number

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

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

Code Samples

Humanoid.JumpPower = 1000

MaxHealth

number

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

Code Samples

print(Humanoid.MaxHealth)

MaxSlopeAngle

number

현재 지원되지 않습니다.

Code Samples

MoveDirection

Vector3

현재 지원되지 않습니다.

Code Samples

PlatformStand

bool

현재 지원되지 않습니다.

Code Samples

RootPart

BasePart

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

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

Code Samples

print(Humanoid.RootPart)

Sit

bool

현재 지원되지 않습니다.

Code Samples

WalkSpeed

number

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

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

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

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

Code Samples

HHmanoid.WalkSpeed = 4000

WalkToPoint

Vector3

현재 지원되지 않습니다.

Code Samples

HitboxType

Enum.HitboxType

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

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

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

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

Code Samples

print(Humanoid.HitBoxType)

LookCameraDirection

bool

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

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

Code Samples

Humanoid.LookCameraDirection = true

DefaultBlendSpace

BlendSpace

Code Samples

Humanoid.DefaultBlendSpace = BasicBlendSpace

BlendSpace

BlendSpace

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

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

Code Samples

Humanoid.BlendSpace = BasicBlendSpace

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

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()

UnequipTools

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

Parameters

Return

void

Code Samples

Humanoid:UnequipTools()

RemoveAccessories

현재 지원되지 않습니다.

Parameters

Return

void

Code Samples

TakeDamage

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

Parameters

number InDamage

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

Return

void

Code Samples

Humanoid:TakeDamage(100)

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()

ChangeState

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

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

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

Parameters

Enum.HumanoidStateType StateType

변경할 상태입니다.

Return

void

Code Samples

Humanoid:ChangeState(Enum.HumanoidStateType.Physics)

SetStateEnabled

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

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

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

Parameters

Enum.HumanoidStateType InHumanoidStateType

활성화 여부를 설정할 상태입니다.

bool bInEnabled

활성화 여부입니다.

Return

void

Code Samples

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

GetState

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

Parameters

Return

Enum.HumanoidStateType

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

Code Samples

print(Humanoid:GetState())

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)

MoveToFinished

현재 지원되지 않습니다.

Parameters

Code Samples

PlatformStanding

현재 지원되지 않습니다.

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

Landed

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

Parameters

Code Samples

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

PlatformStandingMoving

현재 지원되지 않습니다.