# 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