---

# 插件安装方法

> slug: installation

## 1. 注册账号及申请许可证

**1. 在 OtakuSolutions 完成注册（[https://otakusolutions.com/zh/](https://otakusolutions.com/zh/)）**

![](installation/image.png)

**2. 点击 Fast-Ref 的「申请试用」**

![](installation/image1.png)

**3. 管理员批准后，确认许可证发放**

**4. 选择对应的 Max 版本后，下载 mzp 安装文件**

![](installation/image2.png)

---

## 2. 💻 下载并安装 .mzp 文件

![](installation/image3.png)

- **首次启动 3dsMax**。
- 将下载的 **mzp 文件拖入 3dsMax 界面**，即可一键完成安装（将自动匹配您所使用的 3dsMax 版本）。

![](installation/image4.png)

- 此步骤用于确认安装的白名单路径。出于安全考虑，安装程序仅在指定路径下运行。Autodesk 默认路径通常如下所示，若不一致请确认后再安装。

```
# Autodesk 默认路径
C:\Users\<用户名>\AppData\Local\Autodesk\3dsMax\<version>...
```

- 路径无误请点击 **[是 / Yes]**，若不是预期路径请点击 **[否 / No]**，并将截图发送至 OtakuSolutions。

![](installation/image5.png)

- 此对话框在插件已安装时显示。路径无误则点击 **[是 / Yes]**。

![](installation/image6.png)

- 安装完成时会显示上述信息，点击 **Yes** 后 3dsMax 将重启。

### 在 Self 面板中注册

Customize UI → 'OtakuSolutions_Tools' → Fast-Ref

参考上方图示，将宏键注册到 Self 面板中。

![](installation/image7.png)

---

### 通过菜单访问（2025 及以上）

3dsMax 2025 及更高版本会出现 **OS Tools** 菜单，也可通过该菜单访问插件。

![](installation/image8.png)

---

# 许可证激活

> slug: license-activation

## 确认已发放的许可证

许可证通常会通过邮件发送。

如未收到邮件，可在 OtakuSolutions → **[我的账户] → [我的产品]** 中查看许可证代码。

![](license-activation/image.png)

![](license-activation/image1.png)

## ✅ 选择许可证认证方式

请根据您的工作环境选择合适的认证方式。

### 方案 A：在线认证（常规情况）

所有工具都有 **License → License Managing** 菜单。点击后，输入发放的许可证代码和邮箱，然后点击 **[Update License]** 进行更新。

![](license-activation/image2.png)

![](license-activation/image3.png)

然后点击 **Machine ID → [Add] → [确认机器 ID] → [Register Current License]**，将许可证信息和机器 ID 注册到服务器。

![](license-activation/image4.png)

重启工具后，若菜单显示 **License \<ONLINE\>** 则表示认证成功。

---

### 方案 B：离线认证（防火墙环境）

工作场所的防火墙可能会阻止在线许可证认证。

此时可使用**离线认证**方式稳定安装工具。

若与认证服务器连接失败，工具将自动切换至 **[离线认证模式]**。

点击 **[在网页生成代码]** 进入认证页面，按步骤依次输入 **1. 邮箱 / 2. 许可证代码 / 3. 机器 ID**。

![](license-activation/image5.png)

![](license-activation/image6.png)

认证成功后将生成离线代码。将其粘贴到离线代码输入框中，然后点击 **[认证]** 按钮。

![](license-activation/image7.png)

重启工具后，若菜单显示 **License \<OFFLINE\>** 则表示离线认证成功。

![](license-activation/image8.png)

---

# 更新方法

> slug: update-guide

## 插件更新方法

新版本发布后，请更新以应用最新功能和错误修复。

### 自动检查更新

插件启动时会自动检查新版本。若出现更新提示，请按照指示操作。

也可通过 **Help → Check for Update** 手动确认当前版本是否为最新版本。

### 下载最新版本

1. 前往 OtakuSolutions → **[我的产品]** 页面下载最新版本。
2. 无需卸载现有插件，直接安装新的 .mzp 文件。
3. 现有设置和许可证将保持不变。

> 📧 更新消息通过邮件订阅通知。建议订阅邮件。

![](update-guide/image.png)

---

# 防火墙白名单设置方法

> slug: firewall-setup

![](firewall-setup/image.png)

## 🔒 防火墙设置指南

公司安装的防火墙可能导致无法进行在线许可证认证。

此时可按照以下步骤获取所需信息，并提供给网络管理员。

### 🛠️ 确认方法

1. 启动工具后点击 **License** 菜单
2. 选择 **"Guide: Firewall Setup"**
3. 将显示的信息提供给服务器或安全负责人

### 💡 替代方案

若无法访问网络，可通过 **License 菜单 → "Offline License"** 使用离线认证。

> 离线认证详情请参考 [许可证激活指南](../02_license-activation/)。

---

# 团队许可证管理

> slug: team-license-management

![](team-license-management/image.png)

## 👥 团队许可证管理

购买了 1 个及以上 OtakuSolutions 产品的企业或个人，将被授予**团队负责人（LEADER）**权限，可自由向团队成员分配或收回许可证。

在个人资料菜单的 **「团队许可证」** 页面进行管理，许可证按产品分组，一目了然。

---

## 📊 仪表板

页面顶部可查看许可证使用情况。

| 项目 | 说明 |
| --- | --- |
| **总许可证数** | 持有的所有许可证数量 |
| **已激活许可证** | 当前已分配给团队成员并在使用中的许可证数量 |
| **未分配** | 尚未分配、可供使用的许可证数量 |

---

## 🔧 功能说明

| 按钮 | 状态 | 说明 |
| --- | --- | --- |
| **分配** | 未分配许可证 | 将未分配的许可证分配给团队成员的邮箱。分配后该成员可立即使用产品。 |
| **更改** | 已分配许可证 | 将已分配的许可证更改为另一名团队成员。 |
| **收回** | 已分配许可证 | 收回已分配的许可证，使其恢复为未分配状态。收回后该许可证将被**停用**。 |

---

## ⚙️ 附加选项

| 选项 | 说明 |
| --- | --- |
| **仅显示未分配** | 开启后仅显示未分配的许可证，便于快速查找空余许可证。 |
| **按产品折叠/展开** | 许可证按产品分组，可折叠不需要查看的分组。 |

---

## 💡 注意事项

- 分配时填写的邮箱必须是**已注册 OtakuSolutions 账户的邮箱**。
- 收回的许可证随时可以重新分配给其他成员。

---

# [FAQ] 解决 "Not an Autodesk path" 安装错误指南

> slug: faq-not-an-autodesk-path-error

> **注意**：必须将 `os_fast_ref_package` 文件夹整体复制，不能只复制文件夹内的文件。

![image.png](faq-not-an-autodesk-path-error/image.png)

---

### 第 4 步. 注册宏与菜单

在 3ds Max 的 **MAXScript Listener**（`F11` 键）中，**全选 → 复制 → 粘贴**以下脚本，然后按 `Enter` 运行。

> 此脚本会自动检测您的 3ds Max 版本：
>
> - **2025 及以上**：自动注册 OS Tools 菜单
> - **2022 ~ 2024**：引导您通过 Customize UI 注册

```maxscript
(
    local scriptsDir = getDir #userScripts
    local macrosDir = getDir #userMacros
    local startupDir = getDir #userStartupScripts
    local toolDir = scriptsDir + "\\os_fast_ref_package\\"

    local maxVer = (maxVersion())[1]
    local is2025orLater = maxVer >= 27000

    if not (doesDirectoryExist toolDir) then (
        messageBox "在 scripts 路径中找不到 os_fast_ref_package 文件夹。\n请先完成第 3 步。" title:"错误"
    ) else (
        local macroFile = macrosDir + "\\os_fast_ref.mcr"
        local toolDirSlash = substituteString toolDir "\\" "/"
        local pyCode = "import sys; tool_dir = r'" + toolDirSlash + "'; sys.path.insert(0, tool_dir) if tool_dir not in sys.path else None; from os_fast_ref.main import openWindow; openWindow()"

        local f = createFile macroFile
        format "macroScript Osfastref\n" to:f
        format "    category:\"OtakuSolutions_Tools\"\n" to:f
        format "    toolTip:\"os_fast_ref\"\n" to:f
        format "    buttonText:\"os_fast_ref\"\n" to:f
        format "(\n" to:f
        format "    python.Execute \"%\"\n" pyCode to:f
        format ")\n" to:f
        close f
        macros.load macroFile

        if is2025orLater then (
            local menuSrc = toolDir + "_register_menu.ms"
            local menuDst = startupDir + "\\os_fast_ref_menu.ms"
            if doesFileExist menuSrc then (
                copyFile menuSrc menuDst
            )
            messageBox "安装完成！请重启 3ds Max。\n\n重启后：\n  Main Menu > OS Tools > os_fast_ref" title:"os_fast_ref 安装完成"
        ) else (
            messageBox "安装完成！请重启 3ds Max。\n\n启动方式：\n  Customize > Customize User Interface\n  Category: OtakuSolutions_Tools\n  将 os_fast_ref 按钮拖到工具栏" title:"os_fast_ref 安装完成"
        )
    )
)
```

执行成功后，将显示如下完成提示。

![image.png](faq-not-an-autodesk-path-error/image_1.png)

---

### 第 5 步. 重启 3ds Max

**完全退出** 3ds Max 后**重新启动**。

---

### 第 6 步. 确认启动

| **3ds Max 版本** | **启动方式** |
| --- | --- |
| **2025 及以上** | 顶部菜单栏 → **`OS Tools`** → **`os_fast_ref`** |
| **2022 ~ 2024** | **`Customize`** → **`Customize User Interface`** → Category: **`OtakuSolutions_Tools`** → 将 **`os_fast_ref`** 按钮拖到工具栏 |

---

### FAQ

**Q. 第 4 步提示"在 scripts 路径中找不到 os_fast_ref_package 文件夹"。**

→ 请确认第 3 步中 `os_fast_ref_package` 文件夹已复制到正确位置。该文件夹必须位于 `getDir #userScripts` 输出路径的直属子目录下。

**Q. 重启后仍看不到 OS Tools 菜单。（2025）**

→ 前往 `Customize` → `Customize User Interface` → Category: `OtakuSolutions_Tools`，将 `os_fast_ref` 按钮直接拖到工具栏即可。

---

如果安装过程中遇到问题或有疑问，请随时联系我们。

- **OtakuSolutions 客户支持**

---

# [FAQ] 工具无法打开 — 解决 "Application Control / DLL load failed" 安全拦截

> slug: faq-security-block-dll-error

## 现象

在 3ds Max 中启动工具（os_bipedPlus / os_fast_ref）时，出现以下错误且窗口无法打开：

```
ImportError: DLL load failed while importing pyarmor_runtime:
An Application Control policy has blocked this file.
```

特点:
- 安装成功，但**仅在启动时**出现此错误。
- 可能仅在**特定 3ds Max 版本（例如新安装的 2027）**发生，而**同一台电脑上的其他版本（例如 2025）正常**。
- 在别人的电脑上运行完全正常。

## 先说结论（请放心）

**这不是恶意程序，而是安全软件的误报（false positive）。**

本工具为保护授权与代码版权，将 Python 代码**加密（混淆）**后发布。这是付费商业插件普遍采用的标准保护方式。

其中使用的保护运行时文件（`pyarmor_runtime.pyd`）没有单独的代码签名，因此部分 Windows 安全功能会将其**误认为"首次出现的陌生文件"**而阻止加载。

- 因此，**在安全软件中添加例外（允许）后即可立即正常运行。**
- 仅在特定 Max 版本出现的原因: 只是在**全新安装**该版本时该文件首次被加载，安全软件对此做出反应，并非工具本身或 Max 版本的问题。

## 原因（技术说明）

| 项目 | 内容 |
|------|------|
| 拦截来源 | Windows Application Control（智能应用控制 / WDAC），或杀毒软件 / EDR / 公司安全策略 |
| 拦截对象 | 未签名的保护运行时 `pyarmor_runtime.pyd` |
| 为何仅部分电脑 | 安全策略的开/关及信誉状态因电脑而异（正常现象） |

## 解决方法

### 方法 A — 在安全软件中将工具文件夹加入例外（推荐）

将以下工具安装文件夹添加到您使用的杀毒 / 安全软件的**例外（排除 / 允许列表）**中。

- os_bipedPlus:
  `%LOCALAPPDATA%\Autodesk\3dsMax\<版本>\ENU\scripts\os_bipedPlus_package`
- os_fast_ref:
  `%LOCALAPPDATA%\Autodesk\3dsMax\<版本>\ENU\scripts\os_fast_ref_package`

> 如果不知道文件夹路径，在 3ds Max 的 **MAXScript Listener（F11）** 中输入 `getDir #userScripts` 即可输出准确的上级路径。

添加例外后，**重启 3ds Max** 并再次启动工具。

### 方法 B — 检查 Windows 智能应用控制（Windows 11）

1. 打开 **设置 → 隐私和安全性 → Windows 安全中心**
2. 点击 **应用和浏览器控制**
3. 找到 **智能应用控制（Smart App Control）**
4. 如果为 **开启 / 评估（Evaluation）**，将其改为 **关闭**
5. **重启电脑**后重新启动 3ds Max

> 如果是公司/机构电脑无法更改上述设置，请让 IT 管理员将方法 A 的文件夹添加到安全例外列表。

## 如需进一步安心

您可以将例外文件夹中的文件上传到 [VirusTotal](https://www.virustotal.com/) 自行检测。我们将在未来应用代码签名（Code Signing），以避免此类误报。


---

## 문의 / Contact / お問い合わせ / 联系

설치·실행 중 문제가 지속되면 언제든지 연락 주세요.
If the problem persists during installation or launch, feel free to contact us anytime.

- **OtakuSolutions 고객지원 / Customer Support**