MotionForge for Maya — 사용 가이드

텍스트 한 줄로 캐릭터 모션을 만들고, 내 캐릭터에 옮기고, Cascadeur로 보내는 Maya 플러그인입니다. Blender 애드온 MotionForge v0.5.0을 Maya 2027로 이식했습니다. 모든 엔진은 내 컴퓨터에서 돌아가며 인터넷으로 아무것도 보내지 않습니다.

English: index.md

0.2.0 새 기능

0.1.0에서 올라오는 경우: 0.2.0을 설치한 뒤 MotionForge 창에서 Install Engines를 한 번 눌러 주세요. 엔진 폴더의 MotionBricks 런타임을 새 것으로 바꾸고, 사람(SOMA Human)이 쓰는 모델과 스타일도 받습니다. 옆의 Check for Updates는 내려받지 않고 무엇이 새로운지 알려 줍니다.

새로 추가

MotionBricks에 사람이 들어옴 - MotionBricks 패널의 +를 누르면 SOMA Human과 Unitree G1 Robot 중에서 고릅니다. 사람도 로봇과 같은 Style, Go, Speed, Generate Motion, Bake, Live, Retarget을 씁니다. - 사람의 스타일 14개(idle, walk, slow walk, jog, run, injured, stealth, scared, zombie, happy, boxing, gun, 팔꿈치·손 기기)는 Install Engines가 함께 설치합니다. 빠진 것이 있으면 Styles 상자의 Make Missing이 Kimodo로 만들고, Save as Style은 구운(Bake) 또는 생성한 테이크를 내 스타일로 저장합니다. - Install Engines가 사람용 모델(380 MB)을 NVIDIA 라이선스와 함께 받습니다. 별도의 mayapy에서 CPU로 돌기 때문에 GPU가 필요 없습니다.

사람과 로봇 모두 테이크 - 캐릭터마다 테이크 목록(+ Take / - Take / Show Take)이 있습니다. 테이크는 자기 스타일, 방향 또는 타겟, 속도, 시드, 길이를 갖고 씬과 함께 저장됩니다. - 테이크는 하나의 타임라인에 차례로 이어지고(예: 1-30, 31-90, 91-135프레임), Generate Motion은 체크된 테이크를 앞 테이크가 끝난 자리에서 이어서 만듭니다. Bake는 하나의 애니메이션으로 기록합니다.

포즈 투 포즈 - 사람의 테이크에서 End on Pose Key를 켭니다. 캐릭터를 옮기고 돌리고 포즈를 잡아 도착할 프레임(예: 50, 100)에 키를 넣으면, 각 테이크는 자기 키까지 시작한 포즈에서 만들어집니다. 키 간격은 30fps 기준 19~59프레임입니다. - Poses to Use(1~4)와 Transition Early By로 멈추지 않고 여러 포즈를 지나며 움직입니다. Arrive in a Clip Pose는 스타일 클립의 한 포즈에서 끝나는 테이크를 만듭니다.

MMD 캐릭터 양방향 - maya_mmd_tools를 설치하면 Retarget 패널에 MMD 상자가 생깁니다: Import MMD Model (PMX), Import MMD Motion (VMD). - 불러온 모델은 소스(목록에 MMD: <이름>, VMD 키를 다른 테이크처럼 옮김)로도, 타겟(Rig Type을 MMD model로, Auto-Detect로도 찾음)으로도 쓸 수 있습니다. 본은 MMD 이름으로 읽어서 upperarm_L이든 left_arm이든 똑같이 동작합니다. - 굽기 동안 다리를 FK로 바꿔서 다리 IK가 다리를 붙잡지 않습니다. 첫 프레임부터 무릎이 키대로 서 있고, 스킨이 묶인 D본 다리가 함께 움직이며, IK 컨트롤러도 발을 따라갑니다. Reset All은 IK를 다시 켭니다. 팔·팔꿈치·손·목 솔버는 건드리지 않습니다.

바뀐 점

• Install Engines가 업데이트도 합니다. 공개된 런타임과 다른 파일은 교체되어, 예전 설치에도 새 Kimodo·ARDY·MotionBricks 런타임이 반영됩니다. 직접 만들거나 고친 스타일은 덮어쓰지 않습니다. 사람 모델과 ONNX Runtime은 Blender 애드온 설치와 공유되므로 엔진 폴더 하나로 둘 다 씁니다.
• 설치 안내에 폴더 구성을 정확히 적었습니다: 압축을 푼 Maya_MotionForge-<버전> 폴더 이름을 MotionForge로 바꿔서, MAYA_MODULE_PATH에 넣은 폴더 바로 안에 MotionForge.mod가 있게 합니다.

고친 점

• MMD 타겟의 다리. 다리 IK가 다리를 붙잡고, 기본 자세에서도 무릎을 굽혀 첫 프레임부터 접혀 있었으며, 스킨이 묶인 D본 다리가 멈춘 솔버를 읽어 FK가 움직여도 몸이 뻣뻣했습니다.
• 그룹으로 등록한 MMD 모델(Set Selected가 만드는 것)을 MMD 모델로 인식합니다.
• Live Path 목록의 테이크마다 길이가 따로 있습니다.

1. 준비물

2. 설치

2-1. 모듈 등록 (한 번만)

zip 안에는 Maya_MotionForge-<버전> 폴더 하나가 들어 있습니다. 압축을 풀고 그 폴더를 항상 쓸 위치로 옮긴 뒤 이름을 MotionForge로 바꿉니다 (예: C:\Users\<사용자>\Documents\maya\modules\MotionForge). MotionForge.mod가 그 폴더 바로 안에 있어야 합니다 (...\MotionForge\MotionForge.mod — 한 단계 더 안쪽이면 안 됩니다). MotionForge.mod는 그 폴더의 맨 위에 그대로 두세요 — 바로 옆의 scripts\, plug-ins\ 폴더를 가리키고 있어서 .mod 파일만 복사하면 동작하지 않습니다. 폴더 위치는 아무 데나 좋습니다 — 문서 폴더가 OneDrive로 리디렉션되어 있다면 탐색기에 보이는 실제 경로를 쓰세요.

그다음 그 폴더를 MAYA_MODULE_PATH에 넣습니다. 방법은 둘 중 하나입니다.

• 환경 변수: Windows > 시스템 속성 > 환경 변수 > 사용자 변수 새로 만들기 — MAYA_MODULE_PATH = C:\Users\<사용자>\Documents\maya\modules\MotionForge. 이미 있으면 뒤에 ;C:\Users\<사용자>\Documents\maya\modules\MotionForge를 이어 붙입니다.
• Maya.env: 해당 버전의 Maya.env 파일(예: C:\Users\<사용자>\Documents\maya\2027\Maya.env)에 같은 줄을 추가합니다.

MAYA_MODULE_PATH = C:\Users\<사용자>\Documents\maya\modules\MotionForge

Maya를 다시 시작하세요.

2-2. 플러그인 켜기

Windows > Settings/Preferences > Plug-in Manager에서 MotionForge의 Loaded를 켭니다. 매번 켜지게 하려면 Auto load도 켜세요. 메뉴 바에 MotionForge 메뉴가 생기면 성공입니다.

2-3. 셸프 (선택)

Script Editor의 Python 탭에서 한 번 실행합니다.

exec(open(r"C:\Users\<사용자>\Documents\maya\modules\MotionForge\scripts\motionforge_shelf.py").read())

MotionForge 셸프가 생깁니다: Load · Window · Connect · Rig · Generate · Kimodo · MB · Retarget · Reload. 여러 번 실행해도 셸프가 중복되지 않습니다.

3. 처음 설정 — 엔진 폴더

MotionForge > Set Engine Folder...에서 엔진 폴더를 고릅니다. 폴더 안은 이렇게 생겼습니다.

<엔진 폴더>\
├── ardy\          ARDY (bin\ardy-server.exe, models\*.gguf, assets\cskel27\)
├── kimodo\        Kimodo (생성기 + 텍스트 인코더)
└── motionbricks\  MotionBricks (DLL + 스타일)
    └── soma\      사람: ONNX 모델, ONNX Runtime, 스타일 14개

MotionForge > Engine Status를 누르면 Script Editor에 엔진마다 ready 또는 빠진 것이 출력됩니다.

업데이트. Install Engines는 업데이트도 합니다. 공개된 런타임과 다른 파일은 교체되어, 예전 설치에도 새 Kimodo·ARDY·MotionBricks 런타임이 반영되고 사람 스타일도 함께 받습니다. Check for Updates(창, 또는 MotionForge > Check for Engine Updates)는 내려받지 않고 무엇이 새로운지 알려 주며, 새 것이 있으면 버튼이 Update Engines로 바뀝니다. 직접 만들거나 고친 스타일은 덮어쓰지 않습니다. 사람 모델과 ONNX Runtime은 Blender 애드온 설치와 공유되므로 엔진 폴더 하나로 둘 다 씁니다.

4. 화면 구성

창에는 Blender와 같은 순서, 같은 이름으로 7개 패널이 있고, 모든 버튼이 동작합니다.

1. MotionForge — 엔진, 연결, 리그, HumanIK
2. Text to Motion — 텍스트로 테이크 만들기
3. Live Path — 실시간 조종
4. Kimodo — Kimodo 엔진 (여러 캐릭터)
5. MotionBricks — 걷기 엔진 (여러 캐릭터, 라이브, 스타일)
6. Retarget — 내 캐릭터에 옮기기
7. Send to Cascadeur — Cascadeur로 보내고 받아오기

창의 모든 설정과 목록(테이크, 웨이포인트, 포즈키, 라이브 테이크, Kimodo·MotionBricks 캐릭터, Share 목록)은 씬과 함께 저장됩니다. 씬을 다시 열면 그대로 돌아옵니다.

맨 위의 한 줄에 방금 누른 버튼의 결과나 오류가 표시됩니다.

5. 첫 번째 애니메이션 (5분)

1. MotionForge > Connect ARDY — 모델을 불러옵니다 (수 초).
2. MotionForge > Create Rig — 27관절 리그와 몸 메쉬가 생깁니다.
3. MotionForge > Generate Motion... — 프롬프트에 a person walks forward를 입력합니다.
4. 키프레임이 들어가고, 씬이 엔진 속도(ARDY는 20fps)와 실시간 재생으로 맞춰집니다. 재생해 보세요.

첫 생성은 텍스트 인코더를 준비하느라 오래 걸릴 수 있습니다 (이 PC 기준 약 100초). 두 번째부터는 빠릅니다. 창의 Generate 버튼은 백그라운드로 생성하므로 그동안에도 Maya를 계속 쓸 수 있습니다. 진행 상황은 상태 줄에 나옵니다.

6. 패널별 사용법

6-1. MotionForge — 엔진, 연결, 리그

mGear (설치되어 있으면)

mGear(오픈소스, MIT)를 마야에 설치해 두면 MotionForge 캐릭터에 mGear EPIC 바이패드 컨트롤 리그를 씌울 수 있습니다. AI가 만든 테이크가 mGear 컨트롤(FK·IK 모두)에 키로 들어가고, 캐릭터는 그 컨트롤을 따라 움직입니다. 생성된 모션을 일반 키프레임 작업처럼 다듬을 수 있습니다. mGear가 없으면 이 버튼들은 비활성화되고 이유가 표시됩니다.

• mGear는 한 씬에 바이패드 하나만 빌드합니다. 다른 캐릭터에 쓰려면 먼저 Remove 하세요.
• 무릎·팔꿈치처럼 경첩으로 굽는 관절은 FK와 IK 모두 원래 동작과 0.5cm 이내로 맞습니다. IK 다리·팔의 폴 벡터는 매 프레임 실제로 굽는 평면에 놓입니다.

6-2. Text to Motion — 테이크

테이크는 한 번의 생성 단위입니다. 각자 프롬프트·길이·시드·대상 리그·경로 커브를 가집니다. 테이크가 없으면 "Start here" 안내가 나옵니다.

웨이포인트 — "이 프레임에 여기를 지나가라"

1. Follow Waypoints를 켭니다.
2. 타임라인을 원하는 프레임에 두고 + 를 누르면 MF_Waypoint_01 로케이터가 생깁니다 (선택한 물체 위치 또는 원점, 리그가 바라보는 방향으로).
3. 목록에서 고르고 Frame / Enabled로 프레임과 사용 여부를 고칠 수 있습니다.
4. Face Waypoint Direction을 켜면 로케이터의 +Z 방향을 바라보게 합니다.
5. 웨이포인트는 리그 기준으로 읽습니다. 리그를 그룹에 넣고 옮기거나 돌려도 놓은 자리로 걸어갑니다.

포즈 키 — "이 프레임에 이 자세를 취해라"

1. Use Pose Keys를 켭니다.
2. 원하는 프레임에서 + 를 누르면 리그 복사본 MF_Pose_001이 생깁니다.
3. Pose Key(키를 고르면 Pose ) 버튼 — 그 프레임으로 가서 포즈 리그를 선택합니다.
4. IK On — 팔·다리에 Maya ikHandle(회전 평면 + 폴 벡터)을 달아 손·발로 자세를 잡습니다. IK Off를 누르면 잡은 자세는 관절에 남고 핸들은 지워집니다.
5. Pin: Whole Body(전신 고정) / Parts(LH·RH·LF·RF 중 고른 손발만 고정, 나머지는 모델이 만듦).
6. Generate Take.

6-3. Live Path — 실시간 조종

캐릭터가 걷는 동안 콘(원뿔)을 끌어 방향을 바꿉니다. 키는 Bake를 누를 때만 들어갑니다.

1. ARDY가 연결되어 있어야 합니다.
2. + 로 라이브 테이크를 추가하고 Prompt·Rig·Seed·Enabled를 정합니다.
3. Add Target — 조종용 콘 MF_Live_Target_1이 생기고 선택됩니다.
4. Start Live — 콘을 끌거나 돌리세요. Esc 또는 Stop Live로 멈춥니다.
5. Bake(키로 기록) 또는 Discard(버리기). Reset All은 ARDY 리그의 키를 지우고 쉬는 자세(T포즈)로 되돌리며, 타임라인을 첫 프레임으로 돌립니다. 리타겟해 둔 캐릭터(6-6)도 함께 리셋됩니다.
6. Share 목록(6-6)에 캐릭터가 있으면 라이브 중에 함께 따라 움직입니다 (키 없이 자세만). Bake하면 키로 채워집니다.

6-4. Kimodo

Kimodo는 테이크마다 엔진을 따로 실행합니다. 한 테이크에 수십 초~수 분 걸리며, 백그라운드로 돌아갑니다.

1. With a Body / With Fingers를 고르고 + 로 캐릭터를 만듭니다.
2. With Fingers를 끄면 30관절, 켜면 손가락까지 77관절입니다.
3. 몸: 77관절은 ARDY의 실제 스킨, 30관절은 관절 위에 씌운 간단한 몸(프록시)입니다.
4. 캐릭터마다 Enabled · Prompt · Seed를 따로 정합니다 (목록에서 골라 편집).
5. - 는 목록에서 빼기 또는 씬에서 삭제(물어봄), Add Selected는 씬에서 고른 SOMA 골격(BVH·FBX로 가져온 것 포함)을 목록에 넣습니다.
6. Duration · Denoising Steps(기본 20) · Prompt Strength · Constraint Strength · Reduce Foot Skating 등을 정하고 Generate Motion — 켜진 캐릭터마다 차례로 생성되고, 다 된 것부터 키가 들어갑니다. 생성 중 버튼은 Stop Waiting이 됩니다 (진행 중인 테이크는 끝까지 갑니다).
7. Reset All — 목록의 모든 Kimodo 캐릭터 키를 지우고 쉬는 자세(T포즈)로 되돌리며, 타임라인을 첫 프레임으로 돌립니다. 테이크를 리타겟해 둔 캐릭터(6-6)도 함께 리셋됩니다.
8. Export SOMA BVH / Reload Engine.

6-5. MotionBricks — 걷기

입력 없이 스타일대로 걷게 합니다. Generate Motion은 계획만 세우고 바로 재생됩니다 (메모리에서 미리보기). Bake를 눌러야 키가 들어갑니다.

Maya에는 BVH 가져오기가 없어서 MotionForge가 직접 읽습니다 (회전 순서, fps 포함).

6-6. Retarget — 내 캐릭터에 옮기기

1. Source Rig — 비워 두면 가장 최근에 테이크를 넣은 리그. 목록에서 다른 MotionForge 리그를 고를 수 있습니다. 라이브 테이크가 Bake 전이면 먼저 Bake하고, 키가 없는 리그는 현재 자세를 옮깁니다.
2. MMD 모델은 양방향으로 쓸 수 있습니다(maya_mmd_tools 설치 필요). 이 패널 맨 위 MMD 상자에 Import MMD Model (PMX)와 Import MMD Motion (VMD) 버튼이 있고, 가져온 모델은 이 목록에 MMD: <이름>으로 나타나며 키는 테이크와 같은 방식으로 복사됩니다. 테이크를 MMD 모델에 입히려면 Rig Type을 MMD model로 두세요(Auto-Detect도 찾아 줍니다). 뼈는 MMD 이름으로 읽으므로 팔을 upperarm_L이라 부르는 모델도 left_arm이라 부르는 모델도 똑같이 동작합니다. 몸통과 팔다리가 매핑되며, 손가락과 비틀림 본은 아직 매핑되지 않습니다.
3. 받을 캐릭터의 조인트(또는 몸 메쉬)를 선택하고 Set Selected (또는 Target Rig에 이름). 네임스페이스가 붙은 참조 캐릭터(Hero:Hips)도 그대로 됩니다. 가져온 툴이 골격을 몸 메쉬 아래에 나눠 둔 경우(MetaHuman Builder의 MMB_bodyShapeBof4|spine_04)에는 메쉬로 등록되고, 그 아래 모든 조인트가 리타겟됩니다. 몸 골격 옆에 같은 이름의 골격이 하나 더 있는 캐릭터(메타휴먼 헤드 리그)는 몸 골격을 구동하고 그 복제 골격이 이를 따라갑니다. 라이브·Bake 모두 그렇습니다.
4. Rig Type은 보통 자동 감지. 마야 애니메이터가 실제로 쓰는 컨트롤 리그 두 가지가 목록에 있습니다: HumanIK Control Rig와 mGear EPIC 바이패드. 테이크는 그 컨트롤에 키로 들어가고(골반과 다리는 HumanIK 이펙터로 — 이 솔버가 읽는 것은 그 채널입니다), 캐릭터는 컨트롤을 따라 움직입니다.
5. Method — MotionForge(관절별 복사) / HumanIK (Maya)(두 리그를 HumanIK 캐릭터로 정의하고 Maya HumanIK로 구동 후 베이크).
6. Retarget to Character.

Share With Characters — 한 테이크를 여러 캐릭터에 자동으로

1. + — 선택한 캐릭터로 행을 추가합니다. 행마다 Source(비우면 활성 리그) · Character · Rig Type · Enabled.
2. Fill Characters After Generating이 켜져 있으면 Generate·Bake 직후 자동으로 채웁니다. Fill Characters는 지금 바로.
3. 라이브(ARDY·MotionBricks) 중에는 캐릭터가 자세로 따라옵니다. 같은 캐릭터의 두 번째 골격(메타휴먼 헤드 리그)도 함께 따라갑니다.

Reset All(Live Path·Kimodo·MotionBricks)은 이 캐릭터들도 함께 리셋합니다. 키를 지우고 캐릭터 자신의 쉬는 자세 — 마야의 바인드 포즈(Go to Bind Pose가 되돌리는 그 자세)로 돌아갑니다. 메타휴먼 바디는 바인드 당시의 자세 전체(루트에 -90)로 돌아가며, 회전 채널을 0으로 미는 방식이 아니므로 넘어져 바닥 아래로 내려가지 않습니다. 이 자세는 캐릭터가 지금 서 있는 모습이 아니라 골격에 기록된 바인드 포즈에서 읽습니다. 라이브 실행은 팔로워의 본을 키 없이 세팅하므로, 중간에 멈춘 캐릭터는 애니메이션이 전혀 없는 것처럼 보이는데, 그 자세를 쉬는 자세로 기억해서 리셋이 테이크가 가 있던 곳으로 걸어가 버렸습니다. 바인드 포즈가 아예 없는 골격(MotionForge가 만들고 스킨하지 않은 리그)은 처음 봤을 때의 자세로, MotionForge가 보기 전에 이미 키가 있던 캐릭터는 테이크가 시작하는 지점으로 돌아갑니다. 행과 Target Rig는 씬에 저장되므로, 이전 세션에서 채워 둔 캐릭터도 되돌아갑니다.

SMPL-X body — Target Rig가 SMPL-X/SMPL-H 골격이면 Export SMPL (.smpl)로 내보냅니다 (Gender 선택, 블렌드셰이프 Shape000…이 있으면 체형도 저장).

6-7. Send to Cascadeur

7장을 보세요.

7. Cascadeur 연동

7-1. 설치 (한 번만)

1. 창의 Install Cascadeur Plug-in(또는 메뉴) — installer\integrations\cascadeur\install_mf_maya.bat을 실행합니다. 관리자 권한을 물으면 허용하세요.
2. 마야 전용 파일 2개(mf_maya_link.py, mf_maya_apply.py)를 Cascadeur에 복사합니다.
3. Blender 애드온의 Cascadeur 플러그인과 파일 이름도 포트도 겹치지 않습니다. 둘을 같이 설치하고 동시에 켜도 됩니다.
4. Cascadeur를 다시 시작합니다.
5. Cascadeur의 Animation Scripts > MotionForge Maya Link를 실행합니다 (포트 9574).

보낼 대상은 선택한 골격입니다. MotionForge 리그뿐 아니라 내 캐릭터의 조인트를 골라도 됩니다. 아무것도 고르지 않으면 가장 최근에 테이크를 넣은 리그입니다.

7-2. 보내기

순서가 중요합니다: Cascadeur에 캐릭터가 없다면 먼저 Character and Bones로 보내고, 그다음 키·Live·받아오기를 쓰세요. 보낼 때 Cascadeur가 기록한 도착 자세를 리그에 저장해 두므로, Cascadeur나 Maya를 재시작해도 받아오기가 맞습니다.

7-3. 실시간 미러 (Live)

1. Check the Link — 링크를 한 단계씩 시험해서 어디서 막히는지 보고합니다 (Script Editor에 전체).
2. Mirror — Follow the Focus(작업 중인 창 쪽이 보냄) / Maya to Cascadeur / Cascadeur to Maya.
3. Bones — Mapped Bones / Whole Skeleton.
4. Live: Mirror This Rig — 다시 누르거나 Esc로 멈춥니다. 재생하면 프레임마다 Cascadeur에도 키가 들어갑니다.

7-4. 받아오기 (From Cascadeur)

8. Maya에서 알아두면 좋은 동작

9. Reload — Maya 재시작 없이 업데이트

MotionForge > Reload MotionForge (셸프 Reload) 새 코드를 바로 반영합니다. 실행 중이던 Live, MotionBricks 라이브, Cascadeur 미러는 먼저 멈추고, ARDY 연결은 끊깁니다. 리그·테이크·웨이포인트·포즈키·라이브 목록·Kimodo/MotionBricks 캐릭터·Share 목록·설정은 그대로 남습니다. Reload 후 창을 다시 여세요.

10. Blender와 다른 점

이식되지 않은 기능은 없습니다. 창의 모든 버튼이 동작합니다. 다만 Maya에 맞게 바뀐 부분이 있습니다.

11. 문제 해결

12. 라이선스

MotionForge for Maya는 참이슬 라이선스로 판매되며, 구매자 1인당 라이선스 1개입니다. 복제·수정·배포·재배포·재판매는 허용되지 않으며, 제공된 파일 그대로만 사용해야 합니다. 전문은 설치한 폴더의 LICENSE.txt에 있습니다.

제3자 구성 요소(NVIDIA 모델·소스, ggml)는 각자의 라이선스를 그대로 따르며 수정하지 않습니다: licenses\ 및 scripts\motionforge\core\installer\*\licenses\ 참조. Blender 애드온의 라이선스는 이 제품에 적용되지 않습니다.