Update
This commit is contained in:
203
doc/README.md
Normal file
203
doc/README.md
Normal file
@@ -0,0 +1,203 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user