diff --git a/docs/CUSTOM_PLUGIN_GUIDE.md b/docs/CUSTOM_PLUGIN_GUIDE.md deleted file mode 100644 index 41762cb..0000000 --- a/docs/CUSTOM_PLUGIN_GUIDE.md +++ /dev/null @@ -1,577 +0,0 @@ -# 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 官方文档 - ---- - -**祝你开发愉快！** 🎉