7.1 HDA 设计规范

7.1 HDA 设计规范

本节摘要：HDA（Houdini Digital Asset）= 节点网络 + 参数接口 + 版本身份。把第 4 章的山体封成 HDA 是五分钟的操作，把它封成别人愿意用的 HDA 是接口设计的功夫：参数分层暴露、命名即文档、默认值即展示、版本可回溯。本节完成主线资产的出厂封装。

五分钟封装：从网络到资产

选中山体流水线的全部节点，右键 Create Digital Asset，起名 htdev::mountain::1.0（命名空间::资产::版本，从第一天就用这个格式）。保存后原网络变成一个资产节点，Type Properties 面板里做接口编辑。

第一个动作用来完成"参数收拢"：在原始网络里，我们埋过 chi('seed')、chf('freq') 这类 promoted 参数——它们自动出现在资产面板上。2.1 说过的"把魔法数字变参数"，此刻兑现为资产接口。

接口分层：用户是谁

一个山体 HDA 至少三层参数，面向不同的手：

在 Type Properties 里用 Folder 分组并默认折叠 L3。判断标准很朴素：这个参数动错了会不会毁资产？会毁的就不是给外人玩的。

图 7.1-1 HDA 的解剖图

接口纪律清单

• 命名即文档：rock_density 而不是 density3；范围写进参数 min/max，而不是文档里一句"别超过 5"；
• 默认值即门面：用户第一次拖进场景看到的样子决定他对资产的第一印象——把最有代表性的变体设为默认；
• 危险参数加护栏：Hard Range 锁死会造成崩溃的区间（如栅格分辨率上限）；
• 输出带元信息：把种子、版本号写进 detail 属性随几何流出，出问题能溯源（呼应 6.2 的可观测性）；
• 变化走版本不走覆盖：接口语义变了就升 2.0，让旧场景继续用 1.x 存活。

⚠️ 常见坑：接口暴露了 40 个参数"以备不时之需"。参数越多，用户越不知道从哪下手，资产的实际使用率越低。每加一个参数都要能回答"谁在什么场景会动它"。

💡 关键直觉：HDA 的参数面板就是资产的 API。你做接口设计时的每一分克制，都会在别的艺术家手里变成十倍效率。

本节要点回顾

• 三层参数：艺术/技术/危险，折叠与护栏各就各位；
• 命名、默认值、范围就是资产的一半文档；
• 元信息随数据流：种子与版本可溯源；
• 语义变更走版本升级，不悄悄改行为；
• 接口克制：答不出"谁会动它"的参数不该存在。

资产出厂了。下一节把它开进别人的软件：Houdini Engine。

廕伸：接口设计的四个自检问题

HDA 的本质是"把网络变成函数"：输入是接口，输出是几何，参数是签名。函数设计的一切常识都适用，四个自检问题构成 HDA 的 code review 清单：

[HDA 接口自检]
1. 命名是用户的语言还是我的实现?(base_size 而非 grid_sx)
2. 参数分组是否对应任务的心智模型?(形状/随机/细节 而非节点顺序)
3. 默认值是否就是"好看的样子"?(首屏体验=默认值)
4. 有无非法参数组合的防护?(min>max 时的 clamp 与提示)
工具: Edit Parameter Interface 的 RMB > Import Parameters
     批量收编内部节点参数, 再统一重命名分组
​

廕伸：版本迁移的最小方案

// HDA 内 On Loaded 事件脚本 —— 版本握手(示意)
import hou
defn = hou.pwd().type().definition()
ver = defn.version()
if ver >= 2:
    # 手动迁移: 旧参数名映射到新签名
    node = hou.pwd()
    if node.parm("old_scale"):   # 旧资产升级
        v = node.parm("old_scale").eval()
        node.parm("base_size").set(v)
        node.parm("old_scale").lock(True)
​

版本纪律只有两条：签名变更必须升 minor 版本并提供迁移代码；行为变更（同参数不同结果）必须升 major 并在资产名上可见。美术最恨的不是参数多，而是"打开旧文件结果全变了"——可预测性是资产生态的地基。

再补三条来自一线的 HDA 反模式警示：其一"参数爆炸"——把内部所有旋钮都导出，接口有五十个参数等于没有参数，每次导出前先问这颗参数美术真的会调吗；其二"隐藏魔数"——Wrangle 里硬编码 0.37 之类的系数，后续维护者无从知道它是物理常数还是随手一试，一律提升为带默认值的 ch()；其三"黑箱依赖"——HDA 内部引用了本地磁盘的个人工具库，换机器即报错，资产必须自包含或显式声明依赖清单。三条的共同解药都是同一个动作：站在第一次打开这个资产的陌生用户视角重看一遍界面与文档。

最后交代 HDA 的测试形态，它是评审七问的执行载体：每个入库 HDA 配一个 test 舶场景（hip），内含三组调用——默认参数组（应产生宣传图效果）、边界参数组（极值不崩溃）、非法输入组（空几何优雅降级）。CI 里 hython 逐颗 cook 并记录结果，异常即阻塞。这套测试资产的成本约占 HDA 开发的两成，但它换来的信心是"任何改动都敢做"——资产生态的复利，从第一颗带测试的 HDA 开始积累。

再补一条文档形态的实务标准：HDA 的 Help 面板应包含三段——一段话用途声明、参数表（名称/含义/典型值/越界行为）、一个最小示例 hip 的相对路径。写作时间控制在半小时内，因为有了模板。多数团队的 HDA 文档缺位不是因为懒，而是每次都从空白页开始；给出固定三段模板并放进 HDA 创建脚本（新资产自动生成骨架），文档成本即降到可忽略——工程化的一半是给好习惯修滑梯。