# FAQ.2 — .mzp 자동 설치 실패 시 수동 설치

## 개요

| 항목 | 내용 |
|------|------|
| 용도 | `.mzp` 자동 설치 실패 / Permission denied 지속 |
| 방법 | Max에서 경로 조회 → 파일 수동 복사 |
| 권장 선행 | 가능하면 **[FAQ.1 — 설치 시 Permission denied / scripts 쓰기 권한](../faq01-install-permission/)** 먼저 시도 |
| 이미지 | `04`~`14` (경로조회~복사 / Macro등록 / 실행완료) |

---

## 버전 안내 (중요)

- **Max 2025 이상**: `startup`의 메뉴 등록 파일(`os_bipedPlus_menu.ms`)이 필요합니다.
- **Max 2024 이하**: 메뉴용 `.ms`(`_register_menu.ms` → `os_bipedPlus_menu.ms`)가 **없거나 필요 없을 수 있습니다.**
  → 이 경우 **메뉴 `.ms` 복사는 제외해도 됩니다.**
  → 경로 등록용 `os_bipedPlus_path.ms`(`_register_path.ms`)는 가능하면 그대로 등록하세요.

---

## 0. 패키지 준비 (.mzp 압축 해제)

1. 해당 Max 버전용 `.mzp` 준비  
   (예: `biped_plus_v2_2_3_max2025.mzp`)
2. 복사본 확장자를 `.zip`으로 바꿔 압축 해제  
   (또는 압축 프로그램으로 `.mzp`를 직접 열기)
3. 압축을 풀면 아래처럼 보여야 합니다.

![.mzp unzip result — os_bipedPlus_package, install.ms, installer.py](05_mzp_unzipped.png)

> 위 화면은 `.mzp` 파일을 압축 해제한 결과입니다.  
> `os_bipedPlus_package` 폴더, `install.ms`, `installer.py` 가 보이면 정상입니다.

구조 요약:

```text
(압축해제)/
├── install.ms
├── installer.py
└── os_bipedPlus_package/
    ├── os_bipedPlus/
    ├── _register_menu.ms   ← Max 2025+ (2024 이하는 없을 수 있음 → 제외 OK)
    ├── _register_path.ms
    └── ...
```

---

## 1. 3ds Max에서 설치 경로 조회

수동 설치의 핵심은 **내 PC의 정확한 경로**를 먼저 확인하는 것입니다.

1. 해당 버전 Max 실행
2. `F11` → MAXScript Listener
3. 아래 명령 실행:

```maxscript
format "userScripts = %\n" (getDir #userScripts)
format "userStartup = %\n" (getDir #userStartupScripts)
format "userMacros  = %\n" (getDir #userMacros)
```

4. Listener에 경로가 출력됩니다.

![MAXScript Listener — userScripts / userStartup / userMacros paths](04_max_listener_paths.png)

> 위 화면은 3ds Max에서 스크립트를 실행한 결과입니다.  
> `userScripts` / `userStartup` / `userMacros` 경로가 `OK`와 함께 나오면 성공입니다.  
> 경로 중간 계정명은 PC마다 다르며, 예시에서는 `username`으로 표기합니다.

텍스트로 보면 대략 이런 형태입니다:

```text
userScripts = C:\Users\username\AppData\Local\Autodesk\3dsMax\2025 - 64bit\ENU\scripts\
userStartup = C:\Users\username\AppData\Local\Autodesk\3dsMax\2025 - 64bit\ENU\scripts\startup\
userMacros  = C:\Users\username\AppData\Local\Autodesk\3dsMax\2025 - 64bit\ENU\usermacros\
```

5. 출력된 **실제 경로**를 메모한 뒤 **Max 전부 종료**

> 가이드에 적힌 경로를 그대로 쓰지 말고, Listener에 나온 경로로 가세요.

---

## 2. 도구 폴더 복사 (mzp → scripts)

`.mzp` 안에 있는 **`os_bipedPlus_package` 폴더**를 3ds Max의 **scripts 폴더(`userScripts`)** 로 복사·붙여넣기 합니다.

![Copy os_bipedPlus_package from .mzp extract to userScripts folder](06_copy_package_to_scripts.png)

> 왼쪽: `.mzp` 압축 해제 폴더 (`.mzp inside`)  
> 오른쪽: 3ds Max `scripts` 폴더 (`userScripts`)  
> 빨간 화살표처럼 `os_bipedPlus_package`만 복사하면 됩니다. (`install.ms`, `installer.py`는 복사하지 않아도 됩니다.)

| 원본 | 대상 |
|------|------|
| `(압축해제)\os_bipedPlus_package\` | `(userScripts)\os_bipedPlus_package\` |

이미 `os_bipedPlus_package`가 있으면 백업하거나 삭제 후 복사합니다.

완료 후 확인:

```text
(userScripts)\os_bipedPlus_package\os_bipedPlus\
(userScripts)\os_bipedPlus_package\_register_menu.ms
(userScripts)\os_bipedPlus_package\_register_path.ms
```

---

## 3. startup 폴더에 메뉴/경로 스크립트 등록

### 3-1. `scripts\startup` 폴더로 이동

Listener에서 확인한 **userScripts** 폴더(즉 `...\ENU\scripts`)로 들어간 뒤, 그 안의 **`startup`** 폴더를 엽니다.

![Open startup folder inside scripts](07_open_startup_folder.png)

> `startup` 폴더가 없으면 **새로 만들면** 됩니다.  
> (이름 정확히: `startup`)

이 경로가 Listener의 `userStartup` 입니다.

### 3-2. 파일 복사 후 이름 변경

`os_bipedPlus_package` 안에 있는 아래 파일을 `startup` 폴더로 복사한 뒤, **반드시 이름 변경**합니다.

| 원본 (package 안) | 대상 이름 (`startup` 안) | 비고 |
|------|------|------|
| `_register_path.ms` | `os_bipedPlus_path.ms` | 권장 (전 버전) |
| `_register_menu.ms` | `os_bipedPlus_menu.ms` | **Max 2025 이상** / 2024 이하는 제외 가능 |

> **Max 2024 이하**: `_register_menu.ms` / `os_bipedPlus_menu.ms` 가 패키지에 없거나, 메뉴 방식이 다를 수 있습니다.  
> 없으면 **메뉴 `.ms`는 건너뛰어도 됩니다.** (`path.ms`만 등록)

![Copy _register_path/menu.ms to startup and rename to os_bipedPlus_path/menu.ms](08_rename_register_to_menu_path.png)

> 왼쪽: package 안의 `_register_path.ms`, `_register_menu.ms`  
> 오른쪽: `startup` 폴더의 `os_bipedPlus_path.ms`, `os_bipedPlus_menu.ms`  
> 이름까지 바꿔야 Max 시작 시 등록됩니다.  
> (2024 이하에서 메뉴 `.ms`가 없으면 `path.ms`만 등록하면 됩니다.)

이미 같은 이름이 있으면 삭제/백업 후 덮어쓰세요.  
여기서 권한 오류가 나면 → **[FAQ.1 — 설치 시 Permission denied / scripts 쓰기 권한](../faq01-install-permission/)** 으로 `scripts` 권한을 먼저 수정하세요.

---

## 4. Max 재시작 → Macro로 실행

수동 설치 확인은 **메뉴보다 Macro를 먼저** 합니다.  
(`.mzp` 안에는 `.mcr`이 없으므로 Listener/에디터에서 Macro를 직접 만듭니다.)

### 4-1. Macro 생성 스크립트 실행

1. Max 재실행
2. Scripting Editor 또는 Listener(`F11`)에 아래 스크립트를 넣고 실행합니다.

![Paste Macro creation script in Scripting Editor and run](09_macro_script_editor.png)

> Scripting Editor에 Macro 생성 스크립트를 붙여넣은 뒤 실행하면 됩니다.

```maxscript
(
    local toolDir = (getDir #userScripts) + "os_bipedPlus_package\\"
    local toolDirFwd = substituteString toolDir "\\" "/"
    local mcrPath = (getDir #userMacros) + "os_bipedPlus.mcr"
    local py = "import sys; tool_dir = r'" + toolDirFwd + "'; "
    py += "sys.path.insert(0, tool_dir) if tool_dir not in sys.path else None; "
    py += "from os_bipedPlus.main import openWindow; openWindow()"
    local mcr = "macroScript Osbipedplus category:\"OtakuSolutions_Tools\" tooltip:\"os_bipedPlus\" buttonText:\"os_biped_plus\"\n"
    mcr += "(\n    python.Execute \"" + py + "\"\n)\n"
    local f = createFile mcrPath
    format "%" mcr to:f
    close f
    fileIn mcrPath
    format "Macro created: %\n" mcrPath
)
```

3. Listener에 `Macro created: ...os_bipedPlus.mcr` 과 `OK`가 나오면 성공입니다.

![Listener — Macro created: os_bipedPlus.mcr OK](10_macro_created_listener.png)

> `usermacros\os_bipedPlus.mcr` 경로와 `OK`가 보이면 Macro 등록이 끝난 상태입니다.  
> 경로 중간 계정명은 PC마다 다르며, 예시에서는 `Username`으로 보일 수 있습니다.

### 4-2. Customize에서 툴바에 Macro 등록

1. 상단 메뉴 **Customize → Customize User Interface...**

![Customize menu — Customize User Interface](11_customize_menu.png)

2. **Toolbars** 탭 → Category에서 **`OtakuSolutions_Tools`** 선택
3. Action 목록에서 **`os_bipedPlus`** 를 찾습니다.

![Customize UI — OtakuSolutions_Tools category, os_bipedPlus action](12_cui_otakusolutions_category.png)

4. `os_bipedPlus`를 **툴바로 드래그**해 버튼을 만듭니다.

![Drag os_bipedPlus action onto main toolbar](13_drag_macro_to_toolbar.png)

> Action의 `os_bipedPlus`를 메인 툴바로 끌어다 놓으면 버튼이 생깁니다.  
> 버튼에 마우스를 올리면 tooltip `os_bipedPlus`가 보입니다.

5. 툴바 버튼을 눌러 **창이 뜨는지 확인**하세요.

> 메뉴(OS Tools)보다 **Macro 버튼 실행이 우선 확인 기준**입니다.

---

## 5. (선택) 메뉴 확인 — Max 2025 이상

Macro로 실행이 되면 설치는 된 상태입니다.  
추가로 메뉴도 쓰고 싶을 때만 확인하세요.

1. 메뉴(보통 OS Tools)에 `os_bipedPlus`가 있는지 확인
2. 없으면 Listener에서:

```maxscript
fileIn ((getDir #userStartupScripts) + "os_bipedPlus_menu.ms")
```

> **Max 2024 이하**: 메뉴 `.ms`를 등록하지 않았다면 이 절은 **생략**하면 됩니다.

---

## 6. 최종 확인 — 정상 실행

툴바의 `os_bipedPlus` 버튼을 누르면 아래처럼 **BipedPlus** 창이 열리면 수동 설치 완료입니다.

![BipedPlus window open — Status Ready, License ONLINE](14_bipedplus_opened_ready.png)

> 창이 열리고 `Status: Ready`, `License <ONLINE>` 등이 보이면 정상입니다.  
> (라이선스/UI 세부 표시는 버전·환경에 따라 조금 다를 수 있습니다.)

---

## 체크리스트

- [ ] .mzp 압축 해제 확인 (os_bipedPlus_package 보임)
- [ ] Max Listener로 경로 조회함
- [ ] `os_bipedPlus_package`를 scripts(`userScripts`)에 복사·붙여넣기함
- [ ] `scripts\startup` 폴더 확인(없으면 생성)
- [ ] `_register_path.ms` → `os_bipedPlus_path.ms` 등록
- [ ] (2025+) `_register_menu.ms` → `os_bipedPlus_menu.ms` 등록 / **2024 이하는 메뉴 ms 제외 가능**
- [ ] Max 재시작 후 Macro 생성 스크립트 실행 (`os_bipedPlus.mcr`)
- [ ] Customize에서 툴바 버튼 배치 후 Macro로 실행 확인
- [ ] (선택, 2025+) 메뉴 확인 / 필요 시 `fileIn` menu.ms
- [ ] 툴바 버튼으로 BipedPlus 창이 정상 열림

---

## 안내 — 임시 조치 / 원격 지원

이 수동 설치 가이드는 **자동 설치 실패 시 임시 조치**입니다.

정확한 원인 진단과 근본 조치를 위해 **OtakuSolutions**에 연락해 주시면,  
원격 제어를 통해 확인 후 조치해 드릴 수 있습니다.

연락: [https://otakusolutions.com/en/contact](https://otakusolutions.com/en/contact)

OtakuSolutions