Godot 애니메이션
도구 선택
| 필요 상황 | 사용할 도구 |
|---|---|
| 코드에서 즉시 실행되는 모션 (UI 팝업, 넉백, 페이드 아웃) | Tween (create_tween()) |
| 제작된 클립 (걷기 사이클, 문, 컷씬) | AnimationPlayer |
| 프레임 단위 2D 스프라이트 | AnimatedSprite2D + SpriteFrames, 또는 AnimationPlayer가 Sprite2D.frame 키잉 |
| 블렌딩 및 상태 로직 (대기↔달리기↔점프, 8방향 이동) | AnimationTree (상태 머신 또는 블렌드 공간 사용) |
| 절차적 뼈 조준, 발 배치, 물체 잡기 | SkeletonModifier3D 계열 (IK, LookAt, constraints) |
godot-mcp 애니메이션 도구
| 작업 | 도구 |
|---|---|
| 씬에 AnimationPlayer/AnimationTree 기본 구조 추가 | godot_animation_setup_scene |
| 클립 생성, 목록 보기 또는 읽기 | godot_animation_create_clip, godot_animation_list_clips, godot_animation_read_clip |
| 키 추가 또는 제거 | godot_animation_add_keyframe, godot_animation_remove_keyframe |
| AnimationTree 상태 머신 또는 블렌드 공간 계획 | godot_animation_build_state_machine_plan, godot_animation_build_blend_space_plan |
godot_help tool="<name>"을 사용하여 인수 템플릿을 확인하세요. godot_validate_scene으로 검증한 후 씬을 실행하여 모션을 확인합니다. 씬 트리 증거만으로는 애니메이션이 올바르게 보이는지 입증할 수 없습니다. 런타임 스크린샷 또는 수동 확인을 사용하세요 (godot-interactive 참조).
AnimationPlayer
- 클립은 AnimationLibraries에 저장됩니다. 기본 라이브러리는 빈 이름
""을 가지므로play("walk")는play("/walk")의 단축이며, 다른 라이브러리는play("combat/slash")와 같이 사용합니다. - 트랙 경로는
root_node(기본값.., 플레이어의 부모)에 상대적입니다:NodePath("Sprite2D:frame"),NodePath(".:position"). - 모든 애니메이션 속성의 기본값을 포함하는
RESET애니메이션을 유지하세요. 에디터는 이를 사용하여 상태를 복원하고 더티 씬 diff를 방지합니다. - 코드에서 시간을 폴링하는 대신 Call Method 트랙에서 메서드를 호출하세요 (발소리, 히트박스 생성 등).
- 섹션 또는 마커로 재생 (4.4+):
play_section_with_markers("attack", &"windup_end", &"recover_start")를 사용하여 클립의 일부를 반복하거나 건너뜁니다. animation_finished(anim_name)는 루프되지 않는 클립에서 발생합니다. 4.7에서는current_animation_changed인수가anim_name으로 이름이 변경되었습니다. Callable로 연결하면 변경 사항이 문제되지 않습니다.- 4.6:
get_queue()는Array[StringName]을 반환하고is_animation_active()가 추가되었습니다.
@onready var anim: AnimationPlayer = $AnimationPlayer
func attack() -> void:
anim.play("attack")
await anim.animation_finished
anim.play("idle")
AnimationTree
AnimationTree (anim_player = ../AnimationPlayer, active = true)
└── tree_root: AnimationNodeStateMachine
├── Locomotion: AnimationNodeBlendSpace2D (속도에 따른 idle/walk/run)
├── Jump, Fall, Land
└── Attack (AnimationNodeBlendTree를 통한 OneShot)
@onready var tree: AnimationTree = $AnimationTree
@onready var playback: AnimationNodeStateMachinePlayback = tree.get("parameters/playback")
func _physics_process(_delta: float) -> void:
tree.set("parameters/Locomotion/blend_position", velocity / max_speed)
if not is_on_floor() and velocity.y > 0.0:
playback.travel("Fall")
- 매개변수 경로는 트리에서 가져옵니다. 인스펙터에서 매개변수 위로 마우스를 가져가면 정확한 경로를 복사할 수 있습니다.
- 데이터 기반 전환에는 전진 조건(advance conditions) 또는 표현식(
advance_expression)을 사용하고, 코드 기반 전환에는travel()을 사용하세요. - 원샷(공격, 피격)의 경우
parameters/<OneShot>/request를AnimationNodeOneShot.ONE_SHOT_REQUEST_FIRE로 설정하세요. AnimationNodeExtension(4.4, 실험적)을 사용하면 GDScript에서 사용자 정의 블렌드 노드를 작성할 수 있습니다.
Tween
var t := create_tween().set_trans(Tween.TRANS_BACK).set_ease(Tween.EASE_OUT)
t.tween_property(self, "scale", Vector2.ONE * 1.2, 0.12)
t.tween_property(self, "scale", Vector2.ONE, 0.12)
# 병렬 단계
t = create_tween().set_parallel()
t.tween_property(sprite, "modulate:a", 0.0, 0.3)
t.tween_property(sprite, "position:y", sprite.position.y - 20.0, 0.3)
t.chain().tween_callback(queue_free)
# 4.4+: 재사용 가능한 트윈 중첩
var shake := create_tween()
for i in 4:
shake.tween_property(camera, "offset", Vector2(randf_range(-6, 6), randf_range(-6, 6)), 0.03)
var seq := create_tween()
seq.tween_subtween(shake)
seq.tween_property(camera, "offset", Vector2.ZERO, 0.05)
# 4.4+: Engine.time_scale가 느려져도 애니메이션 지속 (히트스톱, 슬로우모션 중 UI)
create_tween().set_ignore_time_scale().tween_property(ui, "modulate:a", 1.0, 0.2)
# 4.7+: 시그널이 발생할 때까지 시퀀스 일시 중지
var intro := create_tween()
intro.tween_property(title, "modulate:a", 1.0, 0.5)
intro.tween_await(dialogue_box.closed)
intro.tween_property(title, "modulate:a", 0.0, 0.5)
규칙:
create_tween()으로 노드에 바인딩된 트윈은 해당 노드가 사라지면 함께 사라집니다. 충돌하는 트윈을 시작하기 전에 이전 트윈을 종료하세요:if _t and _t.is_valid(): _t.kill().- 일시 중지된 트리는
set_pause_mode(Tween.TWEEN_PAUSE_PROCESS)를 설정하지 않으면 트윈을 일시 중지합니다. - 물리 몸체를 움직이는 트윈에는
set_process_mode(Tween.TWEEN_PROCESS_PHYSICS)를 사용하세요.
3D 스켈레탈 애니메이션
- glTF (
.glb)에서 애니메이션을 가져옵니다. 가져온 후가 아니라 고급 가져오기 대화상자에서 루프 모드와 클립 분할을 설정하세요. - 리타겟팅: 가져오기 시
SkeletonProfileHumanoidBoneMap을 사용하여 휴머노이드 모델 간에 애니메이션을 공유합니다.RetargetModifier3D(4.4+)는 런타임에 골격 간 포즈를 복사합니다. - SkeletonModifier3D 스택 (
Skeleton3D의 자식, 순서대로 처리):LookAtModifier3D(4.4+): 각도 제한이 있는 머리 및 눈 트래킹.SpringBoneSimulator3D(4.4+): 머리카락, 꼬리, 천 같은 흔들림,SpringBoneCollision*3D와 함께 사용.AimModifier3D,CopyTransformModifier3D,ConvertTransformModifier3D(4.5+): 뼈 제약 조건.- IK (4.6+):
TwoBoneIK3D(팔과 다리, 결정적),FABRIK3D/CCDIK3D/JacobianIK3D(반복 체인),SplineIK3D(Path3D를 따라 척추와 촉수),JointLimitationCone3D제한 및BoneTwistDisperser3D와LimitAngularVelocityModifier3D로 자연스러운 결과 제공. 이전SkeletonIK3D는 더 이상 사용되지 않습니다. ModifierBoneTarget3D(4.5+): 뼈를 따라가는 Node3D로, IK 대상 또는 부착 지점으로 유용.
- 발 IK 레시피: 각 발에서 아래로 레이캐스트, hit 지점으로 대상 Marker3D를 이동, 각 다리에
TwoBoneIK3D구동, 가장 낮은 발 델타만큼 엉덩이 오프셋.
디버깅
- 클립이 재생되지만 아무것도 움직이지 않음: 트랙 경로가
root_node에 대해 잘못되었거나, AnimationTree가 활성 상태여서 플레이어를 덮어쓰고 있습니다. - 속성이 되돌아감: 다른 트랙이나 RESET이 같은 속성을 키잉하거나, 트윈과 애니메이션이 충돌합니다.
- 상태 머신이 멈춤: 전환 조건과
switch_mode를 확인하고playback.get_current_node()를 관찰하세요. - 3D에서 지터 발생: 물리 보간을 활성화하거나, 움직임과 동일한 프로세스 모드로 애니메이션하세요.