204 lines
6.2 KiB
Markdown
204 lines
6.2 KiB
Markdown
# Nexus Maya 文档中心
|
||
|
||
## 快速开始
|
||
|
||
- **代码入口**：[`2025/scripts/userSetup.py`](../2025/scripts/userSetup.py) — Maya 启动时自动执行，负责：
|
||
- 模块系统初始化（`modules` 目录）
|
||
- 图标路径（`XBMLANGPATH`）设置
|
||
- 架子（shelves）加载
|
||
- 脚本路径加入与插件加载/卸载
|
||
|
||
- **启动调试**（Windows PowerShell）：
|
||
```powershell
|
||
# 设置调试输出并启动 Maya
|
||
$env:TOOL_DEBUG = "1"
|
||
Start-Process "C:\Program Files\Autodesk\Maya2025\bin\maya.exe"
|
||
```
|
||
|
||
或在 Maya 的 Python 面板中临时启用：
|
||
```python
|
||
import os; os.environ['TOOL_DEBUG'] = '1'
|
||
```
|
||
|
||
## 目录结构
|
||
|
||
```
|
||
项目根目录/
|
||
├── modules/ # Maya 模块定义文件 (.mod)
|
||
│ └── ahoge.mod # 示例：ahoge 插件模块定义
|
||
├── plug-ins/ # 外部插件包目录
|
||
│ └── ahoge/ # 示例：ahoge 插件包
|
||
│ ├── 2023/
|
||
│ ├── 2024/
|
||
│ └── 2025/
|
||
│ ├── plugins/ # 插件文件 (.mll, .py 等)
|
||
│ ├── scripts/ # MEL/Python 脚本
|
||
│ ├── icons/ # 图标资源
|
||
│ └── mtoa/ # Arnold 扩展
|
||
├── 2025/
|
||
│ ├── scripts/ # Nexus 工具脚本
|
||
│ │ ├── userSetup.py # 启动脚本
|
||
│ │ ├── animation_tools/ # 动画工具包
|
||
│ │ ├── modeling_tools/ # 建模工具包
|
||
│ │ ├── rigging_tools/ # 绑定工具包
|
||
│ │ └── dev_tools/ # 开发工具包
|
||
│ ├── shelves/ # Maya 架子文件
|
||
│ │ ├── shelf_Nexus_Animation.mel
|
||
│ │ ├── shelf_Nexus_Modeling.mel
|
||
│ │ ├── shelf_Nexus_Rigging.mel
|
||
│ │ └── shelf_Nexus_DevTools.mel
|
||
│ └── icons/ # Nexus 工具图标
|
||
└── doc/ # 项目文档
|
||
└── README.md # 本文件
|
||
```
|
||
|
||
## 模块系统（Module System）
|
||
|
||
项目使用 Maya 标准的模块系统来管理外部插件包。
|
||
|
||
### 工作原理
|
||
|
||
1. **模块定义文件** (`.mod`)：存放在 [`modules`](../modules) 目录
|
||
2. **插件包目录**：存放在 [`plug-ins`](../plug-ins) 目录
|
||
3. **自动加载**：`userSetup.py` 在启动时自动解析 `.mod` 文件并加载插件
|
||
|
||
### 模块定义文件格式
|
||
|
||
以 [`modules/ahoge.mod`](../modules/ahoge.mod) 为例：
|
||
|
||
```mod
|
||
+ MAYAVERSION:2025 PLATFORM:win64 ahoge 0.7 ../plug-ins/ahoge/2025
|
||
MAYA_PLUG_IN_PATH+:=plugins
|
||
MAYA_SCRIPT_PATH+:=scripts
|
||
XBMLANGPATH+:=icons
|
||
MTOA_EXTENSIONS_PATH+:=mtoa
|
||
```
|
||
|
||
**格式说明**：
|
||
- `+` 开头：模块定义行
|
||
- `MAYAVERSION:2025`：适用的 Maya 版本
|
||
- `PLATFORM:win64`：平台（win64/linux/darwin）
|
||
- `ahoge`：模块名称
|
||
- `0.7`：版本号
|
||
- `../plug-ins/ahoge/2025`：模块根路径（相对于 `modules` 目录）
|
||
- `MAYA_PLUG_IN_PATH+:=plugins`：插件目录（相对于模块根路径）
|
||
- `MAYA_SCRIPT_PATH+:=scripts`：脚本目录
|
||
- `XBMLANGPATH+:=icons`：图标目录
|
||
- `MTOA_EXTENSIONS_PATH+:=mtoa`：Arnold 扩展目录
|
||
|
||
### 添加新插件包
|
||
|
||
1. **准备插件包**：
|
||
```
|
||
plug-ins/
|
||
└── 你的插件/
|
||
└── 2025/
|
||
├── plugins/ # 必须包含插件文件
|
||
├── scripts/ # 可选
|
||
└── icons/ # 可选
|
||
```
|
||
|
||
2. **创建模块定义**：
|
||
在 `modules` 目录创建 `你的插件.mod` 文件：
|
||
```mod
|
||
+ MAYAVERSION:2025 PLATFORM:win64 你的插件 1.0 ../plug-ins/你的插件/2025
|
||
MAYA_PLUG_IN_PATH+:=plugins
|
||
MAYA_SCRIPT_PATH+:=scripts
|
||
XBMLANGPATH+:=icons
|
||
```
|
||
|
||
3. **重启 Maya**：插件将自动加载
|
||
|
||
### 模块系统优点
|
||
|
||
- ✅ **标准化**：使用 Maya 官方模块系统
|
||
- ✅ **可移植**：使用相对路径，项目可任意移动
|
||
- ✅ **自动化**：启动时自动解析和加载
|
||
- ✅ **灵活性**：支持多版本、多平台配置
|
||
- ✅ **隔离性**：每个插件独立管理，互不干扰
|
||
|
||
## 常用操作
|
||
|
||
### 手动触发清理
|
||
|
||
在 Maya Python 中运行：
|
||
```python
|
||
import userSetup
|
||
userSetup.cleanup_on_exit()
|
||
```
|
||
|
||
### 重新加载模块
|
||
|
||
在 Maya Python 中运行：
|
||
```python
|
||
import userSetup
|
||
userSetup.load_project_modules()
|
||
```
|
||
|
||
### 查看已加载的模块插件
|
||
|
||
在 Maya Script Editor 中运行：
|
||
```python
|
||
import maya.cmds as cmds
|
||
plugins = cmds.pluginInfo(query=True, listPlugins=True)
|
||
print("已加载插件:", plugins)
|
||
```
|
||
|
||
## 日志与变更
|
||
|
||
### 2024-12 - 模块系统重构
|
||
- **改进内容**:
|
||
- ✅ 实现 Maya 标准模块系统支持
|
||
- ✅ 添加 `modules` 目录用于 `.mod` 文件管理
|
||
- ✅ 添加 `plug-ins` 目录用于外部插件包
|
||
- ✅ 自动解析 `.mod` 文件中的 `MAYA_PLUG_IN_PATH` 定义
|
||
- ✅ 启动时自动加载模块插件
|
||
- ✅ 支持相对路径配置，项目完全可移植
|
||
|
||
### Dev Tools - Maya Icon Viewer 改进
|
||
- **文件**: [`2025/scripts/dev_tools/mayaiconview.py`](../2025/scripts/dev_tools/mayaiconview.py)
|
||
- **改进内容**:
|
||
- ✅ 全部翻译为英文（注释、文档字符串、UI 标签）
|
||
- ✅ 修正语法问题
|
||
- ✅ 跨平台剪贴板支持（Windows/macOS/Linux）
|
||
- ✅ Python 2.7/3.x 兼容性（添加 `__future__` 导入）
|
||
- ✅ 改进错误处理与用户反馈
|
||
- ✅ 兼容 Maya 2025
|
||
|
||
- **跨平台剪贴板实现**:
|
||
- Windows: `echo | clip` 命令，支持管道字符转义
|
||
- macOS: `pbcopy` 命令
|
||
- Linux: `xclip` 或 `xsel` 作为备选
|
||
|
||
- **使用方法**:
|
||
```python
|
||
from dev_tools import mayaiconview
|
||
mayaiconview.create_icon_viewer()
|
||
```
|
||
|
||
## 技术说明
|
||
|
||
### 环境变量
|
||
|
||
- `MAYA_MODULE_PATH`：Maya 模块搜索路径（自动设置）
|
||
- `XBMLANGPATH`：图标搜索路径
|
||
- `MAYA_PLUG_IN_PATH`：插件搜索路径
|
||
- `MAYA_SCRIPT_PATH`：脚本搜索路径
|
||
- `TOOL_DEBUG`：启用调试输出（设置为 "1"）
|
||
|
||
### 启动流程
|
||
|
||
1. Maya 启动
|
||
2. 执行 `userSetup.py`
|
||
3. `load_project_modules()` 扫描 `modules` 目录
|
||
4. 解析 `.mod` 文件，提取模块根路径和插件路径
|
||
5. 自动加载插件（`.mll`, `.so`, `.bundle`, `.py`）
|
||
6. 加载 Nexus 工具（scripts, plugins, shelves）
|
||
7. 初始化完成
|
||
|
||
### 兼容性
|
||
|
||
- **Maya 版本**：2018+（推荐 2025）
|
||
- **平台**：Windows, macOS, Linux
|
||
- **Python**：2.7 / 3.x
|