Communitygithub.com

godot-animation

Godot 4.x 게임 애니메이션 - AnimationPlayer 클립 및 라이브러리, AnimationTree 상태 머신 및 블렌드 공간, 스프라이트 애니메이션, Tween(4.4 서브트윈 및 4.7 tween_await 포함), 애니메이션 섹션 및 마커, 3D 스켈레탈 애니메이션, 리타겟팅, 4.6 IK 프레임워크(TwoBoneIK3D, FABRIK3D, CCDIK3D, SplineIK3D). 캐릭터 애니메이션, UI 모션, 컷씬, 절차적 모션 또는 애니메이션을 게임플레이 상태에 연결하는 데 사용합니다. godot-mcp godot_animation_* 도구와 함께 사용합니다.

godot-animation란 무엇인가요?

이 스킬은 Godot 4.x 엔진에서 게임 애니메이션을 구현하기 위한 포괄적인 가이드입니다. AnimationPlayer를 사용한 클립 기반 애니메이션, AnimationTree를 활용한 상태 머신 및 블렌드 공간 구성, Tween을 통한 코드 기반 절차적 애니메이션, 3D 스켈레탈 애니메이션 및 IK(역운동학) 프레임워크를 다룹니다. godot-mcp 도구와 연동되어 애니메이션 설정, 클립 생성/읽기/수정, 키프레임 추가 및 제거, 상태 머신 및 블렌드 공간 계획을 명령줄이나 AI 에이전트에서 직접 수행할 수 있습니다. 4.4의 서브트윈, 4.7의 tween_await, 4.6의 새로운 IK 노드 계열 등 각 버전별 최신 기능을 포함하며, 디버깅 팁까지 제공하여 실제 게임 개발 워크플로우에서 바로 활용할 수 있도록 설계되었습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Yuki-az-23/noit-godot-skills/tree/HEAD/skills/godot-animation

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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)에서 애니메이션을 가져옵니다. 가져온 후가 아니라 고급 가져오기 대화상자에서 루프 모드와 클립 분할을 설정하세요.
  • 리타겟팅: 가져오기 시 SkeletonProfileHumanoid BoneMap을 사용하여 휴머노이드 모델 간에 애니메이션을 공유합니다. 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 구동, 가장 낮은 발 델타만큼 엉덩이 오프셋.

디버깅

  1. 클립이 재생되지만 아무것도 움직이지 않음: 트랙 경로가 root_node에 대해 잘못되었거나, AnimationTree가 활성 상태여서 플레이어를 덮어쓰고 있습니다.
  2. 속성이 되돌아감: 다른 트랙이나 RESET이 같은 속성을 키잉하거나, 트윈과 애니메이션이 충돌합니다.
  3. 상태 머신이 멈춤: 전환 조건과 switch_mode를 확인하고 playback.get_current_node()를 관찰하세요.
  4. 3D에서 지터 발생: 물리 보간을 활성화하거나, 움직임과 동일한 프로세스 모드로 애니메이션하세요.

관련 스킬