Nexus/doc

Nexus Maya 文档中心

快速开始

• 代码入口：2025/scripts/userSetup.py — Maya 启动时自动执行，负责：

  • 模块系统初始化（modules 目录）
  • 图标路径（XBMLANGPATH）设置
  • 架子（shelves）加载
  • 脚本路径加入与插件加载/卸载

• 启动调试（Windows PowerShell）：

  # 设置调试输出并启动 Maya
  $env:TOOL_DEBUG = "1"
  Start-Process "C:\Program Files\Autodesk\Maya2025\bin\maya.exe"
  

  或在 Maya 的 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 目录
2. 插件包目录：存放在 plug-ins 目录
3. 自动加载：userSetup.py 在启动时自动解析 .mod 文件并加载插件

模块定义文件格式

以 modules/ahoge.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 文件：

   + 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 中运行：

import userSetup
userSetup.cleanup_on_exit()

重新加载模块

在 Maya Python 中运行：

import userSetup
userSetup.load_project_modules()

查看已加载的模块插件

在 Maya Script Editor 中运行：

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

• 改进内容:

  • ✅ 全部翻译为英文（注释、文档字符串、UI 标签）
  • ✅ 修正语法问题
  • ✅ 跨平台剪贴板支持（Windows/macOS/Linux）
  • ✅ Python 2.7/3.x 兼容性（添加 __future__ 导入）
  • ✅ 改进错误处理与用户反馈
  • ✅ 兼容 Maya 2025

• 跨平台剪贴板实现:

  • Windows: echo | clip 命令，支持管道字符转义
  • macOS: pbcopy 命令
  • Linux: xclip 或 xsel 作为备选

• 使用方法:

  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