跳转至

Maya DCC 环境动态编排与个性化定制手册 (Maya Rez & Customization Manual)

  • Target Audience: 技术美术 (TA)、绑定师、模型师、流程开发人员
  • Owner: @micho
  • Status: Approved
  • Scope: ASWF Rez 3.5 + Autodesk Maya (2024–2027) + AYON 1.7 / Lynmio Pipeline

1. 核心设计原则

依照 VES Handbook (第 10 章 流程开发与数字资产管理) 与 ASWF (Academy Software Foundation) 工业标准,Lynmio 内部严格执行 “宿主环境零污染” (Zero Host Contamination) 原则:

[!IMPORTANT] 严禁将任何第三方插件、商业授权、工具架或脚本直接安装进操作系统全局目录或本机 Maya 用户偏好目录(如 ~/Library/Preferences/Autodesk/maya/)。

本机 Maya 必须保持出厂级纯白纸状态;所有插件与环境均在启动瞬间由 ASWF Rez 根据上下文动态计算、沙盒挂载并注入。

flowchart TD
    Launcher["AYON 启动器 / launch_maya_2027_rez.sh"] --> RezResolver["ASWF Rez 解析引擎 (rez-env)"]

    subgraph RepoTopology ["Rez 4-Tier 仓库拓扑"]
        Central["central/ 基础环境 (platform, os, maya)"]
        Ext["ext/ 共享免费/开源扩展 (br_deformers)"]
        Entitled["entitled/ 授权门禁套件 (shapes, zoo_tools, scripts)"]
        Int["int/ 项目与机位元包 (seat_micho_maya)"]
    end

    RezResolver --> RepoTopology
    RepoTopology --> Injection["动态注入环境变量 (MAYA_MODULE_PATH / PYTHONPATH / MAYA_SHELF_PATH)"]
    Injection --> CleanMaya["启动出厂纯净 Maya 2027 进程"]

2. 三层定制工作流 (The 3-Tier Customization Architecture)

“不能污染原生目录”并不代表“剥夺美术师的界面自定义权力”。在 Rez 动态编排体系下,个性化定制被划分为清晰的三层结构:

flowchart LR
    L1["Layer 1: 零门槛交互层<br/>(Maya 界面即改即用)"] -->|满意后固化| L3["Layer 3: 资产化固化层<br/>(Rez 跨机漫游包)"]
    L2["Layer 2: 极速脚本热开发<br/>(Python 秒级重载)"] -->|稳定后发布| L3

Layer 1: 零门槛交互层(在 Maya 界面里随意调整)

  • 适用场景:日常建模/绑定时的即兴微调(改快捷键、调整视口色彩、从 Script Editor 随手拖按钮上 Shelf、设置 Marking Menu)。
  • 操作方式:与原生 Maya 完全一致!直接在 Maya 窗口中操作即可:
  • 改快捷键:打开 Windows > Settings/Preferences > Hotkey Editor,新建专属 Hotkey Set(如 Micho_Keys),随意绑定后保存;
  • 拖 Shelf 按钮:高亮 Script Editor 里的代码,中键拖拽到当前 Shelf 上;
  • 改 Marking Menu:打开 Windows > Settings/Preferences > Marking Menu Editor 随意定制。
  • 隔离保障: Maya 会将这部分修改保存在本机偏好目录 ~/Library/Preferences/Autodesk/maya/2027/prefs/。因为所有插件均来自 Rez 外部挂载,即便你在排查问题时彻底清空或重置本地 prefs/,核心管线插件和商业授权依然毫发无损,重新启动脚本即可一秒恢复满血。

Layer 2: 极速脚本热开发(秒级生效,无需重启)

  • 适用场景:自主编写 Python 建模/装配小工具,并将其接入 Maya 顶部 Lynmio Tools 菜单。
  • 开发步骤:
  • 存放脚本: 将你的 Python 脚本(例如 quick_align.py)放入个人工具包目录: pipeline/packages/entitled/micho_modeling_scripts/1.0.0/scripts/
  • 声明菜单入口: 打开同目录下的 lynmio_menu.py,在 build_menu() 函数中加入菜单项:
    cmds.menuItem(
        label="Quick Align Tool",
        command=lambda *args: __import__("quick_align").main(),
        parent=custom_menu
    )
    
  • 在 Maya 中热重载(无需重启): 在 Maya Script Editor 的 Python 标签页中执行以下两行代码,菜单秒级重绘刷新:
    import importlib, lynmio_menu
    importlib.reload(lynmio_menu)
    lynmio_menu.build_menu()
    

Layer 3: 资产化固化与跨机漫游(固化为 Rez 包)

  • 适用场景:当你在 Mac Studio 上调校好了一套完美的 Shelf、Marking Menu 或快捷键映射,希望在 Windows 笔记本(如 XPS 15)或新部署的机器上无缝 100% 对齐。
  • 固化操作流程:

1. 工具架固化 (Shelf)

Maya 保存的本地 Shelf 文件位于: ~/Library/Preferences/Autodesk/maya/2027/prefs/shelves/shelf_Lynmio.mel

  1. 将该 .mel 拷贝至个人配置包的 shelves/ 目录: pipeline/packages/entitled/micho_modeling_scripts/1.0.0/shelves/shelf_Lynmio.mel
  2. 在该包的 package.py 中添加环境变量追加:
    def commands():
        env.MAYA_SHELF_PATH.append("{root}/shelves")
    
  3. 以后无论在任何一台机器、任何新系统中启动 Maya,该工具架均会自动无缝出现在顶栏,无需手动 Import。

2. 快捷键固化 (Hotkeys)

在 Hotkey Editor 中导出你的快捷键配置文件 userHotkeys_Micho.mel,放入包的 scripts/ 目录中。在 userSetup.py 中通过延迟执行自动激活:

import maya.cmds as cmds
import maya.utils as utils

def _init_hotkeys():
    if "Micho_Keys" in cmds.hotkeySet(query=True, hotkeySetArray=True) or []:
        cmds.hotkeySet("Micho_Keys", edit=True, current=True)

utils.executeDeferred(_init_hotkeys)


3. Rez 仓库结构与授权门禁 (Entitlement Governance)

Lynmio 流程将包划分为 4 个层级,定义于 pipeline/configs/rezconfig.py:

仓库层级 路径 包含内容 治理与访问控制
central pipeline/packages/central 基础平台与宿主(platform, arch, os, maya) 统一由基础架构维护,基础环境不包含业务逻辑
ext pipeline/packages/ext 跨团队/免费开源工具(如 br_deformers) 所有人与渲染农场均可加载,无许可限制
entitled pipeline/packages/entitled 商业授权与专属工具(shapes, zoo_tools, advanced_skeleton 等) 严格授权门禁:通过 pre_commands() 验证系统用户名,非授权机器/用户直接熔断拦截
int pipeline/packages/int 最终启动元包(proj_lynmio_default, seat_micho_maya) 按工位与项目组合依赖

授权门禁实现规范

商业工具包(如 SHAPES、Zoo Tools)必须在其 package.py 中强制加入系统用户名校验,防止商业凭证或仅限个人使用的授权泄漏到公共农场:

# package.py 门禁示例
def pre_commands():
    import getpass
    allowed_seats = {"micho", "michomac"}
    current_user = getpass.getuser().lower()
    if current_user not in allowed_seats:
        raise PackageCommandError(
            f"License Entitlement Error: User '{current_user}' is not entitled to seat '{name}'."
        )

4. 常用运维与启动指令

1. 终端一键拉起工作环境

# 执行封装好的启动器(已绑定 Maya 2027 + 个人机位全量工具)
~/studio-lynmio/pipeline/tools/maya/launch_maya_2027_rez.sh

2. 诊断环境依赖解析 (Dry-run / Context Resolve)

# 检查 rez-env 解析出的所有环境变量注入
export PATH="/Users/micho/studio-lynmio/pipeline/dist/bin:$PATH"
export REZ_CONFIG_FILE="/Users/micho/studio-lynmio/pipeline/configs/rezconfig.py"

rez-env seat_micho_maya -- env | grep -E "MAYA_|PYTHONPATH"

3. 在 AYON Desktop 中集成

  1. 打开 AYON Server 管理面板(https://pipeline.lynmio.com);
  2. 导航至 Studio Settings > Applications > Maya;
  3. 将可执行文件路径设置为: /Users/micho/studio-lynmio/pipeline/tools/maya/launch_maya_2027_rez.sh
  4. 艺术家在 AYON Launcher 界面点击 Maya 图标时,即会自动通过 Rez 挂载全套工程管线。

5. 避坑指南 (Troubleshooting)

  1. macOS Xcode 系统命名冲突 (/usr/bin/rez):
  2. 现象:在终端直接打 rez-env 报错找不到命令,或打 rez 提示 Rez: out of memory / Rez: error。
  3. 原因:macOS 历史系统自带 Xcode 旧 Carbon 编译工具 /usr/bin/rez。
  4. 对策:ASWF Rez 必须使用全局包装器 /Users/micho/studio-lynmio/pipeline/dist/bin/,并在 PATH 中优先置顶。

  5. 严禁在 Rez 包中使用 userSetup.mel:

  6. 现象:多个插件包里都有 userSetup.mel,结果只有一个插件生效,其余插件静默失效。
  7. 原因:Maya 启动时只会读取在 MAYA_SCRIPT_PATH 里找到的第一个 userSetup.mel 并忽略后续所有文件。
  8. 对策:全部改用 userSetup.py,Maya 会按顺序执行 PYTHONPATH 下找到的每一个 userSetup.py。所有 UI 相关的初始化逻辑必须用 maya.utils.executeDeferred() 包裹。

  9. Linux 与 macOS 图标路径差异:

  10. 现象:在 macOS 上正常显示的工具架图标,放到 Linux 渲染机或工作站上全部变成问号或空白。
  11. 原因:Linux 版 Maya 解析 XBMLANGPATH 时,路径末尾必须带 /%B 通配符。
  12. 对策:在 package.py 中写分支判断:
    if system.platform == "linux":
        env.XBMLANGPATH.append("{root}/icons/%B")
    else:
        env.XBMLANGPATH.append("{root}/icons")