OtakuSolutions API Reference

fast-ref 默认通过内置功能优化面向游戏引擎的 FBX Export。我们充分理解各工作室有独特的流程与定制需求。

fast-ref 内所有组件均基于 3ds Max 标准节点 设计。因此 只要在 Export 后不保存场景文件，即可自由编辑数据结构以对接内部工具。

⚠️ 最重要原则：Export 后切勿保存场景。
保存会导致 fast-ref 引用系统数据丢失，无法正常管理。

1. Reset All References 功能（v1.0.4~）

自 v1.0.4 起提供的 Reset All References 可将所有引用转为普通场景对象，在与 fast-ref 链接无关的状态下自由作业。

路径： Tools → Edit → Reset All References (Merge All)

该功能会自动：

清理所有命名空间与后缀
解除层级结构（Hierarchy）
扁平化图层结构
移除 fast-ref 系统数据

需要与内部 Export 工具临时对接时，先执行此功能再 Export。

⚠️ 再次强调： Reset 后不要保存场景，仅 Export 即可。

Merge All Options（可在 General Options 中设置）

执行 Reset All References 时应用的后缀清理选项可在 General Options 对话框中修改。

路径： Tools → General Options → Merge All Options

选项	默认值	说明	默认值意图
*Force Remove Node Suffix (.r)**	✅ ON	从节点名移除 `.r1`, `.r2` 后缀	游戏引擎按节点名映射骨骼/网格，残留后缀可能导致重定向与脚本引用失效
*Force Remove Layer Suffix (.r)**	⬜ OFF	从图层名移除后缀（同名时自动合并）	同一资源多次放置时可能意外合并图层，故默认 OFF
*Force Remove SelectionSet Suffix (.r)**	✅ ON	从 SelectionSet 名移除后缀（同名时自动合并）	Export 脚本常按 SelectionSet 名指定分组，残留后缀可能导致兼容问题

2. Script API 支持

计划提供 Fast-Ref Script API 以满足更高级的自动化。内部 TA 可通过 Python 脚本自动化引用查询、添加、删除、Merge 等操作。

import sys, os, pymxs
_p = os.path.join(pymxs.runtime.getDir(pymxs.runtime.Name("userScripts")), "os_fast_ref_package")
if _p not in sys.path: sys.path.append(_p)

from os_fast_ref.api import FastRefAPI

api = FastRefAPI()
result = api.merge_all_references(
    remove_node_suffix=True,
    remove_layer_suffix=True,
    remove_selectionset_suffix=True,
)
print(result['message'])
# → "Merge 완료: 3개 성공, 0개 실패"

API_Guide_Link : https://docs.otakusolutions.com/api/fast-ref/merge-all-references?lang=en

3. 手动编辑参考事项

若不使用 API 或 Reset 功能而自行编写脚本编辑，请参考以下规则：

移除命名空间： 删除 : 前的字符串。（例：Mable:Root.r1 → Root.r1）
移除后缀： 删除 .r* 形式后缀。（例：Root.r1 → Root）
解除层级： 对以 [REF] 开头的节点的子级执行 Unparent。
整理图层： 将以 [REF] 开头的图层下的子图层移到顶层，然后删除 [REF] 图层。

💡 最推荐的方式

最高效的对接方式是向我们分享贵司当前的内部 Export 环境与需求。在提供指南的过程中，常会找到比预期更简单的方案。

若在结构理解或对接过程中需要技术支持，请随时联系我们。

OtakuSolutions 积极支持您构建灵活的流程。