578 lines
15 KiB
Markdown
578 lines
15 KiB
Markdown
# Maya 自定义插件添加指南
|
||
|
||
本指南将帮助你在 NexusLauncher 的 Maya 插件系统中添加自己的工具和插件。
|
||
|
||
---
|
||
|
||
## 📁 目录结构说明
|
||
|
||
```
|
||
template_plugins/maya/2023/
|
||
├── shelves/ # 工具架文件（.mel 格式）
|
||
├── scripts/ # Python/MEL 脚本
|
||
├── plug-ins/ # Maya 插件文件（.py 或 .mll）
|
||
├── icons/ # 工具图标
|
||
└── README.md # 基础说明文档
|
||
```
|
||
|
||
---
|
||
|
||
## 🎯 添加方式概览
|
||
|
||
根据你的需求，有三种主要的添加方式：
|
||
|
||
| 方式 | 适用场景 | 难度 |
|
||
|------|---------|------|
|
||
| **1. 添加工具架按钮** | 快速添加 Python 脚本工具 | ⭐ 简单 |
|
||
| **2. 添加 Maya 插件** | 创建 Maya 命令或节点 | ⭐⭐ 中等 |
|
||
| **3. 添加启动脚本** | 自动执行初始化代码 | ⭐ 简单 |
|
||
|
||
---
|
||
|
||
## 方式 1: 添加工具架按钮
|
||
|
||
### 适用场景
|
||
- 你有一个 Python 脚本工具想要快速访问
|
||
- 需要在工具架上添加按钮
|
||
- 不需要注册 Maya 命令
|
||
|
||
### 步骤
|
||
|
||
#### 1.1 准备你的 Python 脚本
|
||
|
||
将你的 Python 脚本放到 `scripts/` 目录：
|
||
|
||
```
|
||
scripts/
|
||
├── userSetup.py # 启动脚本（已存在）
|
||
├── nexus_test.py # 示例脚本（已存在）
|
||
└── my_custom_tool.py # 👈 你的新脚本
|
||
```
|
||
|
||
**示例脚本** (`my_custom_tool.py`):
|
||
|
||
```python
|
||
#!/usr/bin/env python
|
||
# -*- coding: utf-8 -*-
|
||
"""
|
||
我的自定义工具
|
||
"""
|
||
import maya.cmds as cmds
|
||
|
||
def run_my_tool():
|
||
"""执行我的工具"""
|
||
# 你的工具逻辑
|
||
cmds.confirmDialog(
|
||
title='My Tool',
|
||
message='Hello from my custom tool!',
|
||
button=['OK']
|
||
)
|
||
print("[MyTool] Tool executed successfully")
|
||
|
||
def show_ui():
|
||
"""显示工具界面"""
|
||
# 如果有 UI，在这里创建
|
||
pass
|
||
```
|
||
|
||
#### 1.2 准备图标（可选）
|
||
|
||
将图标文件放到 `icons/` 目录：
|
||
|
||
```
|
||
icons/
|
||
├── nexus_test.png # 示例图标（已存在）
|
||
└── my_tool_icon.png # 👈 你的图标（32x32 或 64x64 PNG）
|
||
```
|
||
|
||
> **提示**: 如果没有图标，可以使用文字标签代替
|
||
|
||
#### 1.3 编辑工具架文件
|
||
|
||
编辑 `shelves/shelf_NexusLauncher.mel`，在文件末尾的 `}` 之前添加新按钮：
|
||
|
||
```mel
|
||
shelfButton
|
||
-enableCommandRepeat 1
|
||
-flexibleWidthType 3
|
||
-flexibleWidthValue 32
|
||
-enable 1
|
||
-width 35
|
||
-height 34
|
||
-manage 1
|
||
-visible 1
|
||
-preventOverride 0
|
||
-annotation "我的自定义工具 - 点击运行"
|
||
-enableBackground 0
|
||
-backgroundColor 0 0 0
|
||
-highlightColor 0.321569 0.521569 0.65098
|
||
-align "center"
|
||
-label "MT"
|
||
-labelOffset 0
|
||
-rotation 0
|
||
-flipX 0
|
||
-flipY 0
|
||
-useAlpha 1
|
||
-font "boldLabelFont"
|
||
-imageOverlayLabel "MT"
|
||
-overlayLabelColor 1 1 1
|
||
-overlayLabelBackColor 0.2 0.8 0.5 0.9
|
||
-image "my_tool_icon.png"
|
||
-image1 "my_tool_icon.png"
|
||
-style "iconOnly"
|
||
-marginWidth 0
|
||
-marginHeight 1
|
||
-command "import my_custom_tool\nmy_custom_tool.run_my_tool()"
|
||
-sourceType "python"
|
||
-commandRepeatable 1
|
||
-flat 1
|
||
;
|
||
```
|
||
|
||
**关键参数说明**:
|
||
- `-annotation`: 鼠标悬停时的提示文字
|
||
- `-label`: 按钮文字标签（如果没有图标会显示）
|
||
- `-imageOverlayLabel`: 图标上的文字叠加层
|
||
- `-overlayLabelBackColor`: 文字背景颜色 (R G B Alpha)
|
||
- `-image`: 图标文件名（在 icons/ 目录中）
|
||
- `-command`: 点击按钮时执行的 Python 代码
|
||
|
||
#### 1.4 测试
|
||
|
||
1. 通过 NexusLauncher 启动 Maya 2023
|
||
2. 检查 NexusLauncher 工具架是否出现新按钮
|
||
3. 点击按钮测试功能
|
||
|
||
---
|
||
|
||
## 方式 2: 添加 Maya 插件
|
||
|
||
### 适用场景
|
||
- 需要注册自定义 Maya 命令
|
||
- 需要创建自定义节点
|
||
- 需要更深度的 Maya API 集成
|
||
|
||
### 步骤
|
||
|
||
#### 2.1 创建插件文件
|
||
|
||
在 `plug-ins/` 目录创建你的插件文件：
|
||
|
||
```
|
||
plug-ins/
|
||
├── nexus_example_plugin.py # 示例插件（已存在）
|
||
└── my_custom_plugin.py # 👈 你的新插件
|
||
```
|
||
|
||
**插件模板** (`my_custom_plugin.py`):
|
||
|
||
```python
|
||
#!/usr/bin/env python
|
||
# -*- coding: utf-8 -*-
|
||
"""
|
||
我的自定义 Maya 插件
|
||
"""
|
||
import sys
|
||
import maya.api.OpenMaya as om
|
||
|
||
|
||
def maya_useNewAPI():
|
||
"""告诉 Maya 使用 Python API 2.0"""
|
||
pass
|
||
|
||
|
||
class MyCustomCommand(om.MPxCommand):
|
||
"""自定义命令类"""
|
||
|
||
kPluginCmdName = 'myCustomCmd' # 命令名称
|
||
|
||
def __init__(self):
|
||
om.MPxCommand.__init__(self)
|
||
|
||
@staticmethod
|
||
def cmdCreator():
|
||
return MyCustomCommand()
|
||
|
||
def doIt(self, args):
|
||
"""执行命令"""
|
||
print(f'[MyPlugin] Custom command executed!')
|
||
om.MGlobal.displayInfo('My custom plugin is working!')
|
||
|
||
# 在这里添加你的命令逻辑
|
||
# 例如：创建对象、修改场景等
|
||
|
||
|
||
def initializePlugin(plugin):
|
||
"""初始化插件"""
|
||
pluginFn = om.MFnPlugin(plugin, 'YourName', '1.0', 'Any')
|
||
try:
|
||
pluginFn.registerCommand(
|
||
MyCustomCommand.kPluginCmdName,
|
||
MyCustomCommand.cmdCreator
|
||
)
|
||
print(f'[MyPlugin] Plugin loaded: {MyCustomCommand.kPluginCmdName}')
|
||
except:
|
||
sys.stderr.write(f'Failed to register command: {MyCustomCommand.kPluginCmdName}')
|
||
raise
|
||
|
||
|
||
def uninitializePlugin(plugin):
|
||
"""卸载插件"""
|
||
pluginFn = om.MFnPlugin(plugin)
|
||
try:
|
||
pluginFn.deregisterCommand(MyCustomCommand.kPluginCmdName)
|
||
print(f'[MyPlugin] Plugin unloaded: {MyCustomCommand.kPluginCmdName}')
|
||
except:
|
||
sys.stderr.write(f'Failed to deregister command: {MyCustomCommand.kPluginCmdName}')
|
||
raise
|
||
```
|
||
|
||
#### 2.2 配置自动加载
|
||
|
||
编辑 `scripts/userSetup.py`，在 `load_nexus_plugins()` 函数中添加你的插件：
|
||
|
||
```python
|
||
def load_nexus_plugins():
|
||
"""Load NexusLauncher plugins"""
|
||
try:
|
||
plugin_path = os.environ.get('MAYA_PLUG_IN_PATH', '')
|
||
|
||
if not plugin_path:
|
||
print("[NexusLauncher] MAYA_PLUG_IN_PATH not set, skipping plugin load")
|
||
return
|
||
|
||
print(f"[NexusLauncher] MAYA_PLUG_IN_PATH: {plugin_path}")
|
||
|
||
# 要加载的插件列表
|
||
plugins_to_load = [
|
||
"nexus_example_plugin.py",
|
||
"my_custom_plugin.py", # 👈 添加你的插件
|
||
]
|
||
|
||
for plugin_file in plugins_to_load:
|
||
if cmds.pluginInfo(plugin_file, query=True, loaded=True):
|
||
print(f"[NexusLauncher] Plugin already loaded: {plugin_file}")
|
||
else:
|
||
try:
|
||
cmds.loadPlugin(plugin_file)
|
||
print(f"[NexusLauncher] ✓ Loaded plugin: {plugin_file}")
|
||
|
||
# 设置为自动加载
|
||
cmds.pluginInfo(plugin_file, edit=True, autoload=True)
|
||
print(f"[NexusLauncher] ✓ Set plugin to auto-load")
|
||
except Exception as e:
|
||
print(f"[NexusLauncher] Failed to load plugin {plugin_file}: {e}")
|
||
|
||
except Exception as e:
|
||
print(f"[NexusLauncher] Error loading plugins: {e}")
|
||
```
|
||
|
||
#### 2.3 测试插件
|
||
|
||
1. 通过 NexusLauncher 启动 Maya 2023
|
||
2. 检查脚本编辑器输出，确认插件已加载
|
||
3. 在 Maya 命令行或脚本编辑器中测试命令：
|
||
|
||
```python
|
||
import maya.cmds as cmds
|
||
cmds.myCustomCmd() # 执行你的自定义命令
|
||
```
|
||
|
||
---
|
||
|
||
## 方式 3: 添加启动脚本
|
||
|
||
### 适用场景
|
||
- 需要在 Maya 启动时自动执行某些操作
|
||
- 设置环境变量或全局配置
|
||
- 加载第三方库
|
||
|
||
### 步骤
|
||
|
||
#### 3.1 编辑 userSetup.py
|
||
|
||
在 `scripts/userSetup.py` 文件末尾添加你的初始化代码：
|
||
|
||
```python
|
||
def my_custom_startup():
|
||
"""我的自定义启动函数"""
|
||
try:
|
||
print("[MyStartup] Running custom startup code...")
|
||
|
||
# 在这里添加你的启动逻辑
|
||
# 例如：
|
||
# - 设置默认渲染器
|
||
# - 加载常用插件
|
||
# - 配置工作区
|
||
# - 连接到资产管理系统
|
||
|
||
import maya.cmds as cmds
|
||
|
||
# 示例：设置默认单位为厘米
|
||
cmds.currentUnit(linear='cm')
|
||
print("[MyStartup] ✓ Set default unit to cm")
|
||
|
||
# 示例：设置默认时间单位为 24fps
|
||
cmds.currentUnit(time='film')
|
||
print("[MyStartup] ✓ Set default time unit to 24fps")
|
||
|
||
print("[MyStartup] ✓ Custom startup completed")
|
||
|
||
except Exception as e:
|
||
print(f"[MyStartup] Error during startup: {e}")
|
||
|
||
|
||
# 在 Maya 启动完成后执行
|
||
cmds.evalDeferred(my_custom_startup)
|
||
```
|
||
|
||
---
|
||
|
||
## 🔧 高级技巧
|
||
|
||
### 1. 动态重载工具架
|
||
|
||
如果你在开发过程中频繁修改工具架，可以使用 `RELOAD_SHELF.py` 快速重载：
|
||
|
||
```python
|
||
# 在 Maya 脚本编辑器中执行
|
||
import sys
|
||
sys.path.append(r'E:\Zoroot\Dev\NexusLauncher\template\plugins\maya\2023')
|
||
import RELOAD_SHELF
|
||
RELOAD_SHELF.reload_shelf()
|
||
```
|
||
|
||
### 2. 使用相对导入
|
||
|
||
如果你的工具有多个模块，可以创建包结构：
|
||
|
||
```
|
||
scripts/
|
||
├── my_tool/
|
||
│ ├── __init__.py
|
||
│ ├── core.py
|
||
│ ├── ui.py
|
||
│ └── utils.py
|
||
└── userSetup.py
|
||
```
|
||
|
||
在工具架按钮中使用：
|
||
|
||
```mel
|
||
-command "from my_tool import ui\nui.show_window()"
|
||
```
|
||
|
||
### 3. 添加菜单项
|
||
|
||
除了工具架按钮，你还可以在 `userSetup.py` 中添加自定义菜单：
|
||
|
||
```python
|
||
def create_custom_menu():
|
||
"""创建自定义菜单"""
|
||
try:
|
||
import maya.cmds as cmds
|
||
|
||
# 检查菜单是否已存在
|
||
if cmds.menu('NexusMenu', exists=True):
|
||
cmds.deleteUI('NexusMenu')
|
||
|
||
# 创建菜单
|
||
main_window = mel.eval('$tmpVar=$gMainWindow')
|
||
custom_menu = cmds.menu(
|
||
'NexusMenu',
|
||
label='NexusTools',
|
||
parent=main_window,
|
||
tearOff=True
|
||
)
|
||
|
||
# 添加菜单项
|
||
cmds.menuItem(
|
||
label='My Tool',
|
||
command='import my_custom_tool; my_custom_tool.run_my_tool()',
|
||
parent=custom_menu
|
||
)
|
||
|
||
cmds.menuItem(divider=True, parent=custom_menu)
|
||
|
||
cmds.menuItem(
|
||
label='About',
|
||
command='cmds.confirmDialog(title="About", message="NexusTools v1.0")',
|
||
parent=custom_menu
|
||
)
|
||
|
||
print("[NexusLauncher] ✓ Created custom menu")
|
||
|
||
except Exception as e:
|
||
print(f"[NexusLauncher] Error creating menu: {e}")
|
||
|
||
# 在启动时执行
|
||
cmds.evalDeferred(create_custom_menu)
|
||
```
|
||
|
||
### 4. 调试技巧
|
||
|
||
**查看环境变量**:
|
||
```python
|
||
import os
|
||
print(os.environ.get('MAYA_SHELF_PATH'))
|
||
print(os.environ.get('MAYA_PLUG_IN_PATH'))
|
||
```
|
||
|
||
**检查插件加载状态**:
|
||
```python
|
||
import maya.cmds as cmds
|
||
print(cmds.pluginInfo(query=True, listPlugins=True))
|
||
```
|
||
|
||
**查看工具架列表**:
|
||
```python
|
||
import maya.cmds as cmds
|
||
print(cmds.lsUI(type='shelfLayout'))
|
||
```
|
||
|
||
---
|
||
|
||
## 📋 常见问题
|
||
|
||
### Q1: 工具架按钮不显示图标？
|
||
|
||
**A**: 检查以下几点：
|
||
1. 图标文件是否在 `icons/` 目录中
|
||
2. 文件名是否正确（区分大小写）
|
||
3. 图标格式是否为 PNG
|
||
4. `XBMLANGPATH` 环境变量是否正确设置
|
||
|
||
### Q2: Python 脚本找不到模块？
|
||
|
||
**A**: 确保：
|
||
1. 脚本在 `scripts/` 目录中
|
||
2. `PYTHONPATH` 和 `MAYA_SCRIPT_PATH` 已正确设置
|
||
3. 使用 `import` 时不需要包含 `.py` 后缀
|
||
|
||
### Q3: 插件加载失败？
|
||
|
||
**A**: 检查：
|
||
1. 插件文件语法是否正确
|
||
2. 是否包含 `maya_useNewAPI()` 函数（API 2.0）
|
||
3. `initializePlugin()` 和 `uninitializePlugin()` 是否正确实现
|
||
4. 查看脚本编辑器的错误信息
|
||
|
||
### Q4: 修改后没有生效？
|
||
|
||
**A**: 尝试：
|
||
1. 完全关闭 Maya 重新启动
|
||
2. 使用 `RELOAD_SHELF.py` 重载工具架
|
||
3. 检查是否修改了正确版本的文件（2023/2025）
|
||
|
||
### Q5: 工具架在非 NexusLauncher 启动时也出现？
|
||
|
||
**A**: 这是正常的，因为 Maya 会保存工具架配置。解决方法：
|
||
- 系统已配置为临时工具架，不会保存到配置文件
|
||
- 如果仍然出现，删除 `Documents\maya\2023\prefs\shelves\shelf_NexusLauncher.mel`
|
||
|
||
---
|
||
|
||
## 🎓 学习资源
|
||
|
||
### Maya Python API
|
||
- [Maya Python API 2.0 文档](https://help.autodesk.com/view/MAYAUL/2023/ENU/?guid=Maya_SDK_py_ref_index_html)
|
||
- [Maya Commands 参考](https://help.autodesk.com/cloudhelp/2023/ENU/Maya-Tech-Docs/Commands/index.html)
|
||
|
||
### MEL 脚本
|
||
- [MEL 命令参考](https://help.autodesk.com/cloudhelp/2023/ENU/Maya-Tech-Docs/Commands/index.html)
|
||
- [工具架按钮参数说明](https://help.autodesk.com/cloudhelp/2023/ENU/Maya-Tech-Docs/Commands/shelfButton.html)
|
||
|
||
---
|
||
|
||
## 📝 最佳实践
|
||
|
||
1. **命名规范**
|
||
- 使用有意义的名称
|
||
- 避免与 Maya 内置命令冲突
|
||
- 使用前缀区分自己的工具（如 `nexus_`, `my_`）
|
||
|
||
2. **错误处理**
|
||
- 始终使用 try-except 包裹关键代码
|
||
- 提供清晰的错误信息
|
||
- 使用 `print()` 输出调试信息
|
||
|
||
3. **代码组织**
|
||
- 将复杂工具拆分为多个模块
|
||
- 使用函数和类组织代码
|
||
- 添加文档字符串说明
|
||
|
||
4. **性能优化**
|
||
- 避免在启动时执行耗时操作
|
||
- 使用 `cmds.evalDeferred()` 延迟执行
|
||
- 只加载必要的插件
|
||
|
||
5. **版本兼容**
|
||
- 如果支持多个 Maya 版本，注意 API 差异
|
||
- 在 `2023/` 和 `2025/` 目录分别维护
|
||
- 测试不同版本的兼容性
|
||
|
||
---
|
||
|
||
## 🚀 快速开始示例
|
||
|
||
### 完整示例：添加一个"创建立方体"工具
|
||
|
||
**1. 创建脚本** (`scripts/create_cube_tool.py`):
|
||
|
||
```python
|
||
#!/usr/bin/env python
|
||
# -*- coding: utf-8 -*-
|
||
"""
|
||
创建立方体工具
|
||
"""
|
||
import maya.cmds as cmds
|
||
|
||
def create_custom_cube():
|
||
"""创建一个自定义立方体"""
|
||
# 创建立方体
|
||
cube = cmds.polyCube(name='CustomCube', width=2, height=2, depth=2)[0]
|
||
|
||
# 设置颜色
|
||
cmds.polyColorPerVertex(cube, rgb=(1, 0.5, 0), colorDisplayOption=True)
|
||
|
||
# 移动到原点上方
|
||
cmds.move(0, 1, 0, cube)
|
||
|
||
print(f"[CreateCube] Created cube: {cube}")
|
||
cmds.select(cube)
|
||
|
||
return cube
|
||
```
|
||
|
||
**2. 添加工具架按钮** (编辑 `shelves/shelf_NexusLauncher.mel`):
|
||
|
||
```mel
|
||
shelfButton
|
||
-annotation "Create Custom Cube"
|
||
-label "Cube"
|
||
-imageOverlayLabel "CB"
|
||
-overlayLabelBackColor 0.8 0.5 0.2 0.9
|
||
-command "import create_cube_tool\ncreate_cube_tool.create_custom_cube()"
|
||
-sourceType "python"
|
||
;
|
||
```
|
||
|
||
**3. 测试**
|
||
- 启动 Maya
|
||
- 点击工具架上的 "CB" 按钮
|
||
- 应该会创建一个橙色的立方体
|
||
|
||
---
|
||
|
||
## 📞 获取帮助
|
||
|
||
如果遇到问题：
|
||
1. 检查 Maya 脚本编辑器的错误信息
|
||
2. 查看本指南的"常见问题"部分
|
||
3. 参考示例插件代码
|
||
4. 查阅 Maya 官方文档
|
||
|
||
---
|
||
|
||
**祝你开发愉快！** 🎉
|