[공유] HONAMI ANIMATION SYSTEM for Unity.

https://github.com/loyal-studio/Honami-Animation-System

GitHub - loyal-studio/Honami-Animation-System: Honami Animation System is a complete, from-scratch alternative to Unity's built-

---

이 글은 Honami 저장소의 README, 인에디터 문서, 그리고 Runtime/Editor 소스 코드를 기반으로 작성되었습니다.
GLM-5.2 / Humanize-Korean v1.5

Unity Animator Controller를 대체하려는 비주얼 에디터, Honami

"영상 편집하듯 Unity 안에서 애니메이션을 만든다 — 시각적으로, UI로, 코드 거의 없이."

Unity로 게임을 만들면서 "이 애니메이터 상태 머신, 진짜 최선인가?"라고 한 번쯤 생각해 본 적이 있을 겁니다. 수십 개의 상태가 선으로 얽히고, 조건이 겹치고, 블렌드 트리 안에 블렌드 트리가 들어가고… 결국 "스파게티 그래프"라는 별명이 붙은 Unity의 Animator Controller.

Honami Animation System은 LOYAL Studio(우크라이나)가 만든 Unity 6용 오픈소스(MIT) 애니메이션 시스템으로, Unity의 Animator Controller를 비주얼 에디터들로 대체하는 것을 목표로 합니다. 빠른 템포의 액션 게임 Daisen의 모든 애니메이션을 구동하는 실전 테스트된 시스템이기도 합니다.

이 글에서는 Honami의 개발 철학과 핵심 특징을 정리해 봅니다.

---

왜 만들었는가 — 개발 철학

Honami의 철학은 README와 인에디터 문서 곳곳에 선명하게 드러납니다.

1. "영상 편집기 같은 UI"

Honami는 상태 머신을 코드로 짜는 것이 아니라 영상 편집 툴처럼 다룬다는 철학에서 출발합니다. 트랙에 무언가를 올리고, 스크럽하고, 미리보고, 조정하는 — 노드 그래프, 타임라인, 아바타/마스크 에디터 등 각각의 전용 도구가 그 사고방식을 따릅니다.

"Honami는 애니메이터가 그래프를 만들고 프로그래머가 게임플레이 코드를 작성하는 식의 분업을 전제로 합니다. 그것이 전부의 분업입니다."

이 한 문장이 Honami의 방향성을 가장 잘 요약합니다. 애니메이터가 코드 없이 작업할 수 있도록, 그래서 프로그래머와 애니메이터가 서로의 영역을 침범하지 않도록 설계됐습니다.

2. "게임 애니메이션은 동적인 시뮬레이션이다"

인에디터 문서(OverviewPage.cs)는 이렇게 말합니다.

"Honami는 게임 애니메이션은 동적이고 반응하는 시뮬레이션이다라는 철학 위에 구축되었습니다."

"Honami는 현대 게임 애니메이션의 가장 큰 문제 — 상태 폭발, 스파게티 그래프, 시각적 피드백 부족 — 를 해결합니다. 애니메이터가 애니메이터를 위해 설계했지만, 개발자에게 완벽히 퍼포먼스가 나오도록 엔지니어링했습니다."

"표현력"과 "성능"을 동시에 잡겠다는 야심입니다.

3. 솔직한 범위 선언 (Honest Scope)

가장 인상적인 부분입니다. Honami는 자신을 만능 메카님 대체재가 아니다라고 분명히 선언합니다.

"Honami는 Humanoid 리타겟팅이 없고, 블렌드 트리는 1D 전용이며(2D 블렌드 스페이스 없음), 오버레이는 마스크 레이어를 사용합니다(애디티브/에임 오프셋은 로드맵). 애셋 스토어 Humanoid 클립이나 2D 블렌드 스페이스 로코모션에 의존하는 프로젝트라면, Unity의 기본 Animator가 여전히 더 나은 선택입니다."

과장 없이 자신이 뭘 잘하고 뭘 못하는지 말하는 이 태도는 신뢰를 줍니다.

---

핵심 특징

노드 그래프 기반의 모듈형 상태 머신

단순한 평면 상태 머신이 아니라, 타입이 있는 커스텀 노드와 서브노드로 모듈화된 그래프를 제공합니다. 주요 내장 노드:

노드	설명
Animation Node	단일 클립, 시작/끝 시간 트리밍 가능
Blend Tree Node	1D 블렌드 (Standard / Simple 두 모드)
Random Animation Node	가중치 랜덤 클립 선택, 연결된 애니메이터 간 동기화 지원
Sequencer Node	한 타임라인에 클립 꿰기 (윈드업 → 타격 → 회복)
Portal Entrance/Exit Node	가상 순간이동 쌍. 런타임 비용 제로
Any State / Repeater Node	글로벌 진입점, 쿨다운·반복 횟수 제한 가능 (연타 친화적)

그리고 상태에 부착하는 서브노드(MaskSwitcher, JitterSpeed, JitterWeight, SmoothBoneWeight, Log 등)로 상태가 활성일 때만 작동하는 런타임 수정자를 만들 수 있습니다.

4가지 전환 타입 — 특히 "Victim"

HonamiTransitionType은 Standard, Victim, Smart, Inertial 네 가지. 그중 Victim 전환은 단연 돋보입니다 — 전환 도중 "희생"되는 상태의 속도를 가속하고 가중치를 곡선으로 낮춰 튀김(popping) 없는 스냅피한 공격 캔슬을 만들어냅니다.

Trigger는 실제로 발화할 때만 소비

Unity의 SetTrigger는 조건이 맞지 않아도 소비돼 버리는 골칫거리였습니다. Honami는 조건 평가를 "tentative" 버퍼로 모았다가 전환이 실제로 커밋될 때만 트리거를 소비합니다. 발화하지 않은 트리거는 다음 프레임까지 살아있습니다.

이벤트는 상태에, 클립이 아닌 곳에

Unity는 Animation Event를 .anim 클립 안에 구워넣지만, Honami는 이벤트 마커를 상태에 둡니다. 같은 클립이 상태마다 다른 이벤트를 발생시키고, .anim 파일은 깨끗하게 재사용됩니다. Local(인스펙터 UnityEvent)과 Global(C# 서브클래스) 두 채널로 나뉩니다.

가중치 기반 퍼본 마스크

Unity의 AvatarMask는 이진(뼈가 들어가거나 안 들어가거나)인 반면, Honami는 뼈마다 0~1 가중치를 줄 수 있습니다. 모든 마스크를 하나의 _maskAtlas NativeArray로 팩해서 [BurstCompile] IAnimationJob(HonamiLayerBlendJob) 하나로 블렌드하므로, 전환 중에도 마스크가 부드럽게 보간됩니다.

링크드 브레인 — 분산된 월드 좌표 조율

HonamiLinkedAnimator(부모 "브레인")가 자식/태그 기반으로 호출을 전파하고, HonamiLinkedAction은 글로벌 레지스트리 기반의 분산 시스템입니다. PlayClosest(거리 정렬), PlayPropagated(delay = distance / speed인 충격파 방식) 같은 호출로 별도 코드 없이 주변 전파 애니메이션을 만들 수 있습니다.

리깅 & IK — 최종 보정 패스

LookAt, Point, PivotFixer, PseudoPhysics, FootIK, AntiJitter, ScaleFixer, SpaceSwitcher, BoneReplacer 등의 컨스트레인트가 샘플링 이후 마스터 애니메이션은 그대로 둔 채 보정만 가합니다. Unity의 풋 IK는 끄고 자체 HonamiFootIKRig로 처리합니다.

---

아키텍처 — 어떻게 그 철학을 구현했나

Animator 컴포넌트는 재사용, Controller 슬롯은 비움

HonamiAnimator는 [RequireComponent(typeof(Animator))]로 Animator를 그대로 쓰되 컨트롤러를 비우고, 자체 PlayableGraph를 구동합니다.

제로 할당 런타임

파라미터는 NativeArray(float/int/bool/trigger)에 저장되고 정수 해시(Dictionary)로 조회됩니다. 모든 API에는 문자열과 해시 두 오버로드가 있어 핫패스가 할당을 만들지 않습니다.

결정론적 수동 업데이트

그래프를 DirectorUpdateMode.Manual로 만들고 Tick(double dt)을 노출해 네트워크/결정론적 시뮬레이션을 지원합니다.

애니메이션 LOD

애니메이터마다 FPS Cap을 걸어 멀리 있는 캐릭터를 15/30 FPS로 평가(보간 옵션) — 무료 LOD.

GUID 기반 상태 참조

상태가 직접 참조가 아닌 GUID 문자열로 서로를 가리킵니다. 덕분에 상속된 가상 상태와 포탈 베이킹이 가능해집니다.

Unity에서 마이그레이션

AnimatorToHonamiConverterWindow가 기존 AnimatorController의 파라미터·레이어·상태·블렌드 트리(평탄화)·전환을 일방향 변환합니다(2D 블렌드 트리/비헤이비어는 수동 조정 필요라는 경고와 함께).

---

Unity Animator와 비교

측면	Unity Animator	Honami
엔진	⚠️ 폐쇄형 네이티브 메카님 루프 (블랙박스, 확장 불가)	✅ 검사 가능한 PlayableGraph 위의 직접 C# 평가 스택
로직 스타일	⚠️ 평면 상태 머신, 전환 스파게티 경향	✅ 타입형 커스텀 노드 + 서브노드로 모듈화
마스크	⚠️ 이진 (뼈가 들어감/안 들어감)	✅ 뼈당 0~1 가중치
이벤트	⚠️ 클립에 구워짐	✅ 상태에 부착 (클립은 재사용 가능)
Trigger	⚠️ 발화하지 않아도 소비됨	✅ 전환 커밋 시에만 소비
성능	네이티브라 빠르지만 검사 불가	✅ 제로 할당, Burst 컴파일, FPS Cap LOD

---

기술 스택 요약

• 플랫폼: Unity 6 (6000.0)
• 언어: C#, allowUnsafeCode 활성화
• 에디터 UI: UIElements + GraphView API (HonamiGraphView)
• 성능: Burst, Unity.Collections(NativeArray), IAnimationJob
• 엔진: Playables API (AnimationPlayableOutput, AnimationLayerMixerPlayable, AnimationScriptPlayable)
• 라이선스: MIT · 버전: 0.1.0-beta.4
• 설치: UPM git URL (https://github.com/loyal-studio/Honami-Animation-System.git)

---

그래서 누가 써야 하나

Honami는 모든 프로젝트를 위한 메카님 대체재가 아닙니다 — 스스로 그렇게 말합니다. 하지만 다음 상황에서는 강점이 또렷해집니다.

• 코드 주도의 빠른 액션 게임 (전환 캔슬, 연타, 스냅피한 반응이 중요한 경우)
• 복잡하거나 이국적인 릭 (Humanoid가 아닌 무기·차량·문·터렛·크리처 등)
• 애니메이터와 프로그래머의 명확한 분업이 필요한 팀
• 시각적 피드백이 부족해 고통받는 기존 워크플로

반면 애셋 스토어 Humanoid 클립 + 2D 블렌드 스페이스 로코모션에 의존하는 프로젝트라면, 아직은 Unity 기본 Animator가 더 나은 선택입니다.

---

로드맵

Honami는 아직 베 타(0.1.0-beta.4) 단계이며, 다음 기능들이 로드맵에 올라와 있습니다:

• 🎬 Cinematic Director — 시네마틱 연출 도구
• 📊 2D Blend Trees — 2D 블렌드 스페이스 지원
• ➕ Additive Layers — 애디티브 애니메이션 레이어
• 🌊 Inertialization — 관성화 기반 부드러운 전환

---

마치며

Honami가 인상적인 까닭은 기능이 많아서가 아닙니다. 자신이 뭘 잘하는지, 뭘 못하는지 솔직하게 말하는 태도, 그리고 "애니메이터를 위해 설계했되 개발자에게도 퍼포먼스가 나오도록 엔지니어링했다"는 양쪽을 동시에 챙기려는 균형 감각에 있습니다.

영상 편집하듯 애니메이션을 만들겠다는 철학, 제로 할당 런타임, 가중치 마스크, 분산된 링크드 브레인까지. Mecanim의 답답함을 느끼고 있었다면 한 번 살펴볼 만한 깊이 있는 프로젝트입니다.

• 저장소: github.com/loyal-studio/Honami-Animation-System
• 실전 사례: Daisen (Steam)

---