maya-glTF 插件使用指南

功能概述

什么是 maya-glTF？

maya-glTF 是一款专为 Autodesk Maya 设计的 glTF 2.0 格式导出插件。glTF（GL Transmission Format）是一种高效的 3D 模型传输格式，被广泛应用于游戏开发、AR/VR 和 Web 3D 场景中。通过这款插件，你可以将 Maya 中的 3D 模型、材质和动画快速导出为 glTF 或 GLB 格式，轻松对接现代 3D 应用生态。

核心功能一览

• 完整场景导出：支持导出包含模型、材质、相机和层级关系的完整场景
• 双格式支持：同时支持文本格式（.gltf）和二进制格式（.glb）
• 灵活资源管理：三种二进制资源处理方式（外部 .bin 文件、复制源文件或完全嵌入）
• 动画导出：支持关键帧动画导出，保留模型变换动画数据
• 材质转换：支持 Lambert、Blinn、Phong 等传统材质以及 StingrayPBS 物理材质的转换

快速上手

如何安装插件？

🔧 安装步骤：

1. 首先克隆仓库到本地：git clone https://gitcode.com/gh_mirrors/ma/maya-glTF
2. 根据你的操作系统，将文件复制到相应目录：

Windows 系统：

• 脚本文件（项目根目录/scripts/glTFExport.py 和 glTFTranslatorOpts.mel）→ C:/Users/<你的用户名>/Documents/maya/<版本号>/scripts
• 插件文件（项目根目录/plug-ins/glTFTranslator.py）→ C:/Users/<你的用户名>/Documents/maya/<版本号>/plug-ins

macOS 系统：

• 脚本文件 → Library/Preferences/Autodesk/maya/<版本号>/scripts
• 插件文件 → Library/Preferences/Autodesk/maya/<版本号>/plug-ins

Linux 系统：

• 脚本文件 → $MAYA_APP_DIR/maya/<版本号>/scripts
• 插件文件 → $MAYA_APP_DIR/maya/<版本号>/plug-ins

⚠️ 注意：如果插件目录不存在，请手动创建。确保替换路径中的 <版本号> 为你的 Maya 实际版本（如 2023、2024 等）。

如何验证安装是否成功？

🔧 验证步骤：

首先→ 启动 Maya，打开「插件管理器」（Window → Settings/Preferences → Plug-in Manager） 其次→ 在插件列表中找到「glTFTranslator.py」 最后→ 勾选「Loaded」选项启用插件，此时你会在导出格式中看到「glTF Export」选项

如何导出第一个模型？

假设你已经在 Maya 中创建了一个简单场景，现在需要将其导出为 glTF 格式：

🔧 导出步骤：

1. 点击菜单栏「File → Export All...」（目前暂不支持「Export Selection...」）
2. 在弹出的对话框中，选择「Files of Type」为「glTF Export」
3. 设置导出选项（具体选项说明见「核心配置」章节）
4. 选择保存路径并点击「Export All」完成导出

核心配置

如何通过菜单配置导出选项？

当你选择「glTF Export」格式后，会看到导出选项面板，主要包含三大类配置：

如何通过脚本导出模型？

除了通过菜单导出，你还可以在 Maya 的脚本编辑器中使用 Python 代码导出模型，这对于批量处理或集成到工作流中非常有用：

import glTFExport  # 导入导出模块
# 导出为 GLB 格式，使用默认配置
glTFExport.export(r"C:\Projects\my_model.glb")  # 文件路径需替换为你的实际路径

# 高级配置示例
glTFExport.export(
    r"C:\Projects\animated_model.gltf",  # 导出为 glTF 文本格式
    resource_format='bin',  # 使用外部 bin 文件存储二进制数据
    anim='keyed',  # 导出关键帧动画
    vflip=True  # 翻转 UV 坐标的 V 轴
)

关键配置参数详解

以下是导出时可配置的核心参数，你可以根据项目需求选择合适的设置：

参数名称	可选值	默认值	推荐设置	说明
resource_format	bin, source, embedded	bin	bin	二进制资源处理方式
anim	none, keyed	keyed	根据需求	动画导出模式
vflip	true, false	true	true	是否翻转 UV 坐标的 V 轴

resource_format 参数说明：

• bin：生成单独的 .bin 文件存储二进制数据（推荐用于大多数场景）
• source：将图片等资源文件复制到输出目录（适合需要单独管理纹理的情况）
• embedded：所有资源嵌入到 .gltf 文件中（适合单个文件分发）

anim 参数说明：

• none：不导出动画数据（适合静态模型）
• keyed：导出当前关键帧动画（适合需要保留动画的场景）

⚠️ 注意：vflip 参数默认设为 true，这是因为大多数 OpenGL 渲染器期望 UV 坐标的 V 轴与 Maya 相反。只有在确认目标渲染器不需要翻转时才设置为 false。

常见问题

导出失败怎么办？

当你遇到导出失败时，可以按照以下步骤排查：

1. 检查日志：打开 Maya 的脚本编辑器（Window → General Editors → Script Editor）查看错误信息
2. 简化场景：尝试导出简单几何体验证基本功能是否正常
3. 材质检查：确保场景中没有使用不支持的材质类型（推荐使用 StingrayPBS 材质获得最佳效果）
4. 更新插件：确保使用最新版本的插件，可能已修复已知问题

为什么导出的模型材质看起来不一样？

Maya 的材质系统与 glTF 的 PBR（物理基于渲染）材质系统存在差异。当你发现导出的材质与 Maya 中显示效果不同时：

• 推荐解决方案：使用 StingrayPBS 材质重新创建材质，这是与 glTF PBR 材质最匹配的 Maya 材质类型
• 替代方案：传统材质（Lambert、Blinn、Phong）会通过近似算法转换为 PBR 材质，但可能需要手动调整金属度和粗糙度参数

如何导出包含动画的模型？

要导出带动画的模型，确保：

1. 模型已设置关键帧动画
2. 导出时将 anim 参数设置为 'keyed'（菜单中选择"Keyed"选项）
3. 对于复杂骨骼动画，目前插件主要支持基本变换动画（位移、旋转、缩放）

导出的文件太大怎么办？

如果导出的 glTF/GLB 文件体积过大：

• 对于 .gltf 格式，选择 resource_format='bin' 而非 'embedded'
• 考虑使用 GLB 格式（.glb），它通常比 .gltf + .bin 组合更小
• 优化纹理大小和分辨率，避免不必要的高分辨率纹理
• 检查是否导出了不需要的相机或灯光数据

最佳实践

模型准备建议

为获得最佳导出效果，在建模阶段建议：

1. 清理场景：删除未使用的节点、材质和图层
2. 规范命名：使用英文命名模型和材质，避免特殊字符
3. UV 优化：确保 UV 不重叠且在 0-1 范围内
4. 材质精简：每个模型使用尽可能少的材质，推荐使用 StingrayPBS 材质

工作流建议

1. 版本控制：始终保留 Maya 源文件，glTF 作为导出产物
2. 测试验证：导出后使用 glTF 验证工具检查文件完整性（如 glTF Validator）
3. 格式选择：单机应用优先选择 GLB 格式，Web 应用可根据需求选择 glTF + 外部资源

通过遵循这些指南，你可以充分利用 maya-glTF 插件的强大功能，将 Maya 中的创作无缝对接现代 3D 应用生态。