Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

애니메이션 트리

소개

:ref:`AnimationPlayer <class_AnimationPlayer>`를 통해 Godot는 모든 게임 엔진에서 찾을 수 있는 가장 유연한 애니메이션 시스템 중 하나를 보유하고 있습니다. 노드 또는 리소스의 거의 모든 속성을 애니메이션화하는 기능과 전용 변환, 베지어, 함수 호출, 오디오 및 하위 애니메이션 트랙이 매우 독특합니다.

그러나 고정된 크로스페이드 전환 시간만 설정할 수 있으므로 ``AnimationPlayer``를 통한 해당 애니메이션 블렌딩 지원은 제한됩니다.

:ref:`AnimationTree <class_AnimationTree>`는 고급 전환을 처리하도록 설계된 노드입니다.

AnimationPlayer

시작하기 전에 AnimationTree 노드에는 자체 애니메이션이 포함되어 있지 않다는 점을 알아두세요. 대신 AnimationPlayer 노드에 포함된 애니메이션을 사용합니다. ``AnimationPlayer``에서 애니메이션을 생성, 편집 또는 가져온 다음 ``AnimationTree``를 사용하여 재생을 제어합니다.

AnimationPlayer 및 AnimationTree``는 2D 및 3D 장면 모두에서 사용할 수 있습니다. 3D 장면과 해당 애니메이션을 가져올 때 `이름 접미사 <https://docs.godotengine.org/en/stable/tutorials/assets_pipeline/importing_3d_scenes/node_type_customization.html#animation-loop-loop-cycle>`_를 사용하여 프로세스를 단순화하고 올바른 속성으로 가져올 수 있습니다. 마지막에 가져온 Godot 씬에는 ``AnimationPlayer 노드에 애니메이션이 포함됩니다. 가져온 장면을 Godot에서 직접 사용하는 경우는 거의 없기 때문에(인스턴스화되거나 상속됨) 가져온 장면을 포함하는 새 씬에 AnimationTree 노드를 배치할 수 있습니다. 그런 다음 가져온 씬에서 생성된 AnimationPlayer``를 ``AnimationTree 노드로 지정합니다.

Godot 애셋 라이브러리

CharacterBody3D``를 루트로 사용하는 플레이어를 위해 새로운 씬이 생성되었습니다. 이 씬 내에서 원본 ``.dae``(Collada) 파일이 인스턴스화되고 ``AnimationTree 노드가 생성되었습니다.

프로젝트 생성하기

``AnimationTree``를 사용하려면 루트 노드를 설정해야 합니다. 애니메이션 루트 노드는 하위 노드를 포함하고 평가하여 애니메이션을 출력하는 클래스입니다. 하위 노드에는 3가지 유형이 있습니다.

1. 연결된 ``AnimationPlayer``의 애니메이션을 참조하는 애니메이션 노드.

2. 하위 노드를 혼합하는 데 사용되며 중첩될 수 있는 애니메이션 루트 노드.

3. 노드의 2D 그래프인 ``AnimationNodeBlendTree``에 사용되는 Animation Blend 노드입니다. Blend 노드는 여러 입력 포트를 사용하고 하나의 출력 포트를 제공합니다.

루트 노드 중 몇 가지가 사용 가능합니다:

• AnimationNodeAnimation: 목록에서 애니메이션을 선택하여 재생합니다. 이것은 가장 간단한 루트 노드이며 일반적으로 루트로 사용되지 않습니다.

• AnimationNodeBlendTree: 그래프에 여러 노드를 자식 노드로 포함합니다. 믹스, 블렌드2, 블렌드3, 원샷 등과 같은 다양한 블렌드 노드를 사용할 수 있습니다.

• AnimationNodeBlendSpace1D: 두 애니메이션 노드 간의 선형 블렌딩을 허용합니다. 애니메이션 간 믹스를 위해 1D 블렌드 공간에서 블렌드 위치를 제어합니다.

• AnimationNodeBlendSpace2D: 세 애니메이션 노드 간의 선형 블렌딩을 허용합니다. 애니메이션 간 믹스를 위해 2D 블렌드 공간에서 블렌드 위치를 제어합니다.

• AnimationNodeStateMachine: 그래프에 여러 노드를 자식 노드로 포함합니다. 각 노드는 상태로 사용되며, 상태를 전환하는 데 사용되는 여러 기능이 있습니다.

블렌드 트리

AnimationNodeBlendTree``를 만들면 하단 패널의 AnimationTree 탭에 빈 2D 그래프가 표시됩니다. 기본적으로 ``Output 노드만 포함됩니다.

애니메이션을 재생하려면 노드를 출력에 연결해야 합니다. Add 노드.. 메뉴에서 또는 빈 공간을 마우스 오른쪽 버튼으로 클릭하여 노드를 추가할 수 있습니다.

가장 간단한 연결은 Animation 노드를 출력에 직접 연결하는 것입니다. 이렇게 하면 애니메이션이 재생됩니다.

2D에서는 다음 코드를 사용합니다:

블렌드2 / 블렌드3

이 노드는 사용자가 지정한 혼합 값에 따라 2개 또는 3개의 입력을 혼합합니다.

블렌딩에서는 **필터**를 사용하여 블렌딩할 트랙과 블렌딩하지 않을 트랙을 개별적으로 제어할 수 있습니다. 이는 애니메이션을 서로 겹쳐서 배치하는 데 유용할 수 있습니다.

보다 복잡한 블렌딩을 위해서는 블렌드 공간을 대신 사용하는 것이 좋습니다.

원샷

이 노드는 애니메이션을 한 번 실행하고 완료되면 반환합니다. 페이드 인 및 페이드 아웃에 대한 블렌드 시간과 필터를 사용자 정의할 수 있습니다.

GDScriptC#

# Play child animation connected to "shot" port.
animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE)
# Alternative syntax (same result).
animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE

# Abort child animation connected to "shot" port.
animation_tree.set("parameters/OneShot/request", AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT)
# Alternative syntax (same result).
animation_tree["parameters/OneShot/request"] = AnimationNodeOneShot.ONE_SHOT_REQUEST_ABORT

# Get current state (read-only).
animation_tree.get("parameters/OneShot/active"))
# Alternative syntax (same result).
animation_tree["parameters/OneShot/active"]

시간탐색

이 노드를 사용하면 in 입력에 연결된 애니메이션의 시간을 검색할 수 있습니다. 특정 재생 위치부터 Animation``를 재생하려면 이 노드를 사용합니다. 참고로 탐색 요청 값은 초 단위로 측정되므로 처음부터 애니메이션을 재생하려면 ``0.0 값을 설정하고, 3초 이후부터 애니메이션을 재생하려면 값을 ``3.0``로 설정하세요.

GDScriptC#

# Play child animation from the start.
animation_tree.set("parameters/TimeSeek/seek_request", 0.0)
# Alternative syntax (same result).
animation_tree["parameters/TimeSeek/seek_request"] = 0.0

# Play child animation from 12 second timestamp.
animation_tree.set("parameters/TimeSeek/seek_request", 12.0)
# Alternative syntax (same result).
animation_tree["parameters/TimeSeek/seek_request"] = 12.0

타이머(Timer) 예제

이 노드를 사용하면 in 입력에 연결된 애니메이션의 속도를 조정할 수 있습니다. 애니메이션 속도는 scale 매개변수의 숫자로 곱해집니다. 스케일을 0으로 설정하면 애니메이션이 일시 중지됩니다. 스케일을 음수로 설정하면 애니메이션이 거꾸로 재생됩니다.

변환

이 노드는 StateMachine의 단순화된 버전입니다. 애니메이션을 입력에 연결하면 현재 상태 인덱스에 따라 재생할 애니메이션이 결정됩니다. 크로스페이드 전환 시간을 지정할 수 있습니다. 인스펙터에서는 입력 포트 개수 변경, 입력 재배열, 삭제 등이 가능합니다.

GDScriptC#

# Play child animation connected to "state_2" port.
animation_tree.set("parameters/Transition/transition_request", "state_2")
# Alternative syntax (same result).
animation_tree["parameters/Transition/transition_request"] = "state_2"

# Get current state name (read-only).
animation_tree.get("parameters/Transition/current_state")
# Alternative syntax (same result).
animation_tree["parameters/Transition/current_state"]

# Get current state index (read-only).
animation_tree.get("parameters/Transition/current_index"))
# Alternative syntax (same result).
animation_tree["parameters/Transition/current_index"]

상태머신

AnimationNodeStateMachine``를 만들면 하단 패널의 AnimationTree 탭에 빈 2D 그래프가 표시됩니다. 기본적으로 ``Start 및 End 상태가 포함되어 있습니다.

상태를 추가하려면 마우스 오른쪽 버튼을 클릭하거나 상자 안에 플러스 아이콘이 있는 새 노드 생성 버튼을 사용하세요. 애니메이션, 블렌드스페이스, 블렌드트리 또는 다른 StateMachine을 추가할 수 있습니다. 이러한 보다 복잡한 하위 노드 중 하나를 편집하려면 상태 오른쪽에 있는 연필 아이콘을 클릭하세요. 원래 StateMachine으로 돌아가려면 패널 왼쪽 상단에 있는 **Root**를 클릭하세요.

StateMachine이 유용한 작업을 수행하려면 먼저 상태를 전환과 연결해야 합니다. 전환을 추가하려면 오른쪽 화살표가 있는 선인 connect 노드 버튼을 클릭하고 두 상태 사이를 드래그합니다. 상태 간에 각 방향으로 하나씩 2개의 전환을 생성할 수 있습니다.

3개의 전환 유형이 있습니다:

• 즉시: 즉시 다음 상태로 전환합니다.

• 동기화: 즉시 다음 상태로 전환하지만 이전 상태의 재생 위치에서 새 상태를 찾습니다.

• At End: 현재 상태 재생이 끝날 때까지 기다린 후 다음 상태 애니메이션의 시작으로 전환합니다.

전환에도 몇 가지 속성이 있습니다. 전환을 클릭하면 검사기에 표시됩니다.

• *Xfade Time*은 이 상태와 다음 상태 사이를 교차 페이드하는 시간입니다.

• *Xfade Curve*는 선형 혼합이 아닌 곡선을 따르는 크로스페이드입니다.

• *재설정*은 전환 중인 상태가 처음부터 재생되는지(true) 또는 재생되지 않는지(false) 여부를 결정합니다.

• *우선순위*는 코드의 travel() 함수와 함께 사용됩니다(나중에 자세히 설명). 트리를 통해 이동할 때는 우선순위가 낮은 전환이 선호됩니다.

• *스위치 모드*는 전환 유형입니다(위 참조). 여기에서 생성 후 변경할 수 있습니다.

• *고급 모드*는 고급 모드를 결정합니다. Disabled``인 경우 전환이 사용되지 않습니다. ``Enabled``인 경우 전환은 ``travel() 중에만 사용됩니다. ``Auto``인 경우 고급 조건 및 표현식이 true이거나 고급 조건/식이 없는 경우 전환이 사용됩니다.

사전 조건 및 사전 표현

StateMachine 전환의 마지막 2개 속성은 Advance Condition 및 ``Advance Expression.``입니다. 고급 모드가 *자동*으로 설정된 경우 전환이 진행될지 여부를 결정합니다.

사전 조건은 참/거짓 확인입니다. 텍스트 필드에 사용자 정의 변수 이름을 입력할 수 있으며 StateMachine이 이 전환에 도달하면 변수가 true*인지 확인합니다. 그렇다면 전환이 계속됩니다. 고급 조건은 **만* 변수가 *true*인지 확인하며, false인지는 확인할 수 없습니다.

이는 고급 조건에 매우 제한된 기능을 제공합니다. 하나의 속성을 기준으로 앞뒤로 전환하려면 반대 값을 갖는 변수 2개를 만들고 둘 중 하나가 true인지 확인해야 합니다. 이것이 Godot 4에 Advance Expression이 추가된 이유입니다.

고급 표현식은 고급 조건과 유사하게 작동하지만 하나의 변수가 true인지 확인하는 대신 모든 표현식을 평가합니다. 표현식은 if 문에 넣을 수 있는 모든 것입니다. 다음은 고급 표현식에서 사용할 수 있는 표현식의 예입니다.

• is_instance_valid(obj)

• is_walking == true (위와 동일하게 동작)

• is_walking && !is_idle

• 속도 피벗

• player.is_on_floor()

경고

표현식은 **대소문자를 구분**합니다. CharacterBody3D 노드의 velocity``와 같은 엔진 속성을 참조하는 경우 ``snake_case 명명 규칙을 사용해야 합니다. 스크립트 속성을 참조하는 경우 스크립트에서 사용되는 스타일과 일치해야 합니다. 이는 일반적으로 GDScript에서는 ``snake_case``이고 C#에서는 ``PascalCase``입니다.

다음은 고급 조건을 사용하여 잘못 설정된 StateMachine 전환의 예입니다.

Advance Condition에 확인할 수 없는 ! 변수가 있어서 작동하지 않습니다.

다음은 두 개의 반대 변수를 사용하여 올바르게 설정된 동일한 예입니다.

다음은 동일한 예이지만 Advance Condition 대신 Advance Expression을 사용하므로 두 변수가 필요하지 않습니다.

Advance Expressions를 사용하려면 AnimationTree 노드의 인스펙터에서 Advance Expression Base 노드를 설정해야 합니다. 기본적으로 AnimationTree 노드 자체로 설정되지만 애니메이션 변수와 함께 스크립트가 포함된 노드가 무엇이든 가리켜야 합니다.

더 보기

Advance Expression은 Godot의 Expression 클래스를 사용하여 평가됩니다. 표현식 작성에 대한 자세한 내용은 :ref:`doc_evaluating_expressions`를 참조하세요.

상태기계 여행

Godot의 StateMachine 구현의 멋진 기능 중 하나는 여행 기능입니다. 모든 중간 상태를 방문하면서 그래프가 현재 상태에서 다른 상태로 이동하도록 지시할 수 있습니다. 이는 A* 알고리즘을 통해 수행됩니다. 현재 상태에서 시작하여 대상 상태에서 끝나는 전환 경로가 없는 경우 그래프는 대상 상태로 순간 이동합니다.

이동 기능을 사용하려면 먼저 AnimationTree 노드에서 AnimationNodeStateMachinePlayback 개체를 검색한 다음(속성으로 내보냄) 여러 함수 중 하나를 호출해야 합니다.

GDScriptC#

var state_machine = animation_tree["parameters/playback"]
state_machine.travel("SomeState")

이동하기 전에 StateMachine이 실행되고 있어야 합니다. ``start()``를 호출하거나 노드를 **시작**에 연결하세요.

BlendSpace2D 및 BlendSpace1D

``BlendSpace2D``는 2차원에서 고급 블렌딩을 수행하는 노드입니다. 애니메이션을 나타내는 점을 2D 공간에 추가한 다음 점 사이의 위치를 제어하여 블렌딩을 결정합니다.

마우스 오른쪽 버튼을 클릭하거나 아이콘이 펜과 점인 점 추가 버튼을 사용하여 그래프의 어느 곳에나 이러한 점을 배치할 수 있습니다. 점을 어디에 배치하든 Delaunay를 사용하여 점 사이의 삼각형이 자동으로 생성됩니다. X와 Y의 범위를 제어하고 레이블을 지정할 수도 있습니다.

마지막으로 블렌드 모드를 변경할 수도 있습니다. 기본적으로 블렌딩은 가장 가까운 삼각형 내부의 점을 보간하여 발생합니다. 2D 애니메이션(프레임별)을 처리할 때 Discrete 모드로 전환하는 것이 좋습니다. 또는 개별 애니메이션 간에 전환할 때 현재 재생 위치를 유지하려는 경우 Carry 모드가 있습니다. 이 모드는 Blend 메뉴에서 변경할 수 있습니다.

BlendSpace1D는 BlendSpace2D와 동일하게 작동하지만 1차원(선)으로 작동합니다. 삼각형은 사용되지 않습니다.

Sync mode

Both BlendSpace1D and BlendSpace2D have a Sync Mode property that controls how animations advance when they are blended. This replaces the older boolean sync property and offers more precise control.

There are four modes available:

• None (default): Inactive animations are frozen and do not advance. Only the currently active (highest-weight) animation moves forward.

• Independent: Inactive animations advance with a weight of 0. This matches the behavior of the old sync = true setting.

• Cyclic Mutable: All animations are time-scaled so their phases stay aligned. The shared cycle length is computed dynamically from the active blend weights, which means a single unblended animation plays at its normal speed. This is useful when all your animations have the same logical cycle (e.g. locomotion loops) but may differ slightly in length.

• Cyclic Constant: All animations are time-scaled to complete one full cycle in exactly Cyclic Length seconds, regardless of their individual lengths. Set the cyclic_length property to your desired cycle duration (must be greater than 0).

경고

Cyclic sync modes require that all blend points use AnimationNodeAnimation with a finite, immutable length. If any blend point uses a different node type, a warning will be shown and cyclic sync will not take effect:

참고

When using either cyclic mode with animations of different lengths, applying an AnimationNodeTimeSeek to the output will break synchronization. In that case, use AnimationNodeAnimation.use_custom_timeline to normalize animation lengths before syncing.

더 나은 블렌딩을 위해

혼합 결과가 결정적(재현 가능하고 항상 일관됨)이 되려면 혼합 속성 값에 특정 초기 값이 있어야 합니다. 예를 들어 블렌딩할 두 애니메이션의 경우 한 애니메이션에는 속성 트랙이 있고 다른 애니메이션에는 속성 트랙이 없으면 블렌딩된 애니메이션은 후자의 애니메이션에 초기 값의 속성 트랙이 있는 것처럼 계산됩니다.

Skeleton3D 뼈에 대해 위치/회전/크기 조정 3D 트랙을 사용할 때 초기 값은 뼈 나머지입니다. 다른 속성의 경우 초기 값은 0``이고 트랙이 ``RESET 애니메이션에 있는 경우 첫 번째 키프레임 값이 대신 사용됩니다.

예를 들어 다음 AnimationPlayer에는 두 개의 애니메이션이 있지만 그 중 하나에는 위치에 대한 속성 트랙이 없습니다.

이는 해당 위치를 ``Vector2(0, 0)``로 처리하는 애니메이션이 부족함을 의미합니다.

이 문제는 위치에 대한 속성 트랙을 RESET 애니메이션에 초기 값으로 추가하여 해결할 수 있습니다.

참고

RESET 애니메이션은 원래 객체를 로드할 때 기본 포즈를 정의하기 위해 존재한다는 점에 유의하세요. 프레임이 하나만 있는 것으로 가정되며 타임라인을 사용하여 재생되지 않을 것으로 예상됩니다.

또한 회전 3D 트랙과 보간 유형이 선형 각도 또는 입방 각도로 설정된 2D 회전용 속성 트랙은 혼합 애니메이션으로 초기 값에서 180도를 초과하는 회전을 방지한다는 점을 명심하세요.

이는 Skeleton3D가 애니메이션을 블렌딩할 때 뼈가 몸체를 관통하는 것을 방지하는 데 유용할 수 있습니다. Therefore, Skeleton3D's Bone Rest values should be as close to the midpoint of the movable range as possible. 이는 휴머노이드 모델의 경우 T 포즈로 가져오는 것이 바람직하다는 것을 의미합니다.

애니메이션 간의 최단 회전 경로보다 Bone Rests의 최단 회전 경로가 우선시되는 것을 볼 수 있습니다.

이동을 위해 블렌드 애니메이션으로 Skeleton3D 자체를 180도 이상 회전해야 하는 경우 루트 모션을 사용할 수 있습니다.

루트 모션

3D 애니메이션으로 작업할 때 애니메이터가 루트 뼈대 뼈를 사용하여 나머지 뼈대에 모션을 제공하는 인기 있는 기술이 있습니다. 이를 통해 계단이 실제로 아래 바닥과 일치하는 방식으로 캐릭터에 애니메이션을 적용할 수 있습니다. 또한 시네마틱 중에 객체와의 정확한 상호 작용이 가능합니다.

Godot에서 애니메이션을 재생할 때 이 뼈대를 *루트 모션 트랙*으로 선택할 수 있습니다. 이렇게 하면 뼈대 변형이 시각적으로 취소됩니다(애니메이션은 그대로 유지됩니다).

그런 다음 AnimationTree API를 통해 실제 모션을 변환으로 검색할 수 있습니다.

GDScriptC#

# Get the motion delta.
animation_tree.get_root_motion_position()
animation_tree.get_root_motion_rotation()
animation_tree.get_root_motion_scale()

# Get the actual blended value of the animation.
animation_tree.get_root_motion_position_accumulator()
animation_tree.get_root_motion_rotation_accumulator()
animation_tree.get_root_motion_scale_accumulator()

이는 캐릭터 움직임을 제어하기 위해 :ref:`CharacterBody3D.move_and_slide <class_CharacterBody3D_method_move_and_slide>`와 같은 함수에 제공될 수 있습니다.

노드, RootMotionView 도구도 있습니다. 캐릭터와 애니메이션의 사용자 정의 바닥 역할을 할 씬을 배치할 수 있습니다(이 노드는 게임 중에 기본적으로 비활성화되어 있습니다).

코드에서 제어

트리를 구축하고 미리 본 후에 남은 유일한 질문은 "이 모든 것을 코드에서 어떻게 제어합니까?"입니다.

노드 애니메이션은 단지 리소스일 뿐이므로 이를 사용하는 모든 인스턴스 간에 공유된다는 점을 명심하세요. 노드의 값 설정은 이 ``AnimationTree``를 사용하는 씬의 모든 인스턴스에 직접적인 영향을 미칩니다. 이는 일반적으로 바람직하지 않지만 몇 가지 멋진 사용 사례가 있습니다. 애니메이션 트리의 일부를 복사하여 붙여넣거나 다른 애니메이션 트리에서 복잡한 레이아웃(예: StateMachine 또는 블렌드 공간)과 함께 노드를 재사용할 수 있습니다.

실제 애니메이션 데이터는 AnimationTree 노드에 포함되어 있으며 속성을 통해 액세스됩니다. 실시간으로 수정될 수 있는 모든 매개변수를 보려면 AnimationTree 노드의 "매개변수" 섹션을 확인하세요.

이는 AnimationPlayer 또는 심지어 AnimationTree 자체에서 애니메이션을 적용할 수 있게 하여 매우 복잡한 애니메이션 로직을 허용하므로 편리합니다.

코드에서 이러한 값을 수정하려면 속성 경로를 얻어야 합니다. 매개변수 위에 마우스를 올려놓으면 찾을 수 있습니다.

다음과 같은 스크립트를 만드세요:

GDScriptC#

animation_tree.set("parameters/eye_blend/blend_amount", 1.0)
# Alternate syntax (same result)
animation_tree["parameters/eye_blend/blend_amount"] = 1.0

참고

StateMachine의 고급 표현식은 매개변수 아래에서 찾을 수 없습니다. 이는 AnimationTree 자체가 아닌 다른 스크립트에 보관되어 있기 때문입니다. Advance `Conditions`는 매개변수 아래에서 찾을 수 있습니다.