# 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 及以下可能不存在 → 可跳过）
    ├── _register_path.ms
    └── ...
```

---

## 1. 在 3ds Max 中查询安装路径

手动安装的关键是先确认 **本机准确路径**。

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` 一起出现即为成功。  
> 路径中的账户名因电脑而异，示例使用 `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)

> 将 Macro 创建脚本粘贴到 Scripting Editor 后运行即可。

```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 注册完成。  
> 路径中的账户名因电脑而异，示例可能显示 `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. 点击工具栏按钮，**确认窗口是否打开**。

> **Macro 按钮启动**是优先验证方式，而非 OS Tools 菜单。

---

## 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