Unity 定位组件与构建流程

简体中文 | English

使用可编辑的 Sensa 作者组件构建 Avatar。NDMF 在构建副本读取设置，生成原生 Contact、约束、FX 动画与菜单，再移除作者脚本。本页说明构建顺序、生成资产和各阶段检查。

先选择测量方式

三个根点预制件的 Target 都可明确指定自己 Avatar 内的骨骼／空物体 Transform、SPS Socket／Plug、Sensa Component 或原生 Contact。骨骼与普通标记可以直接作为目标；选择原生 Contact 时读取其形状中心，选择 SPS 时读取其作者根点几何。定位和单位 · Contact SDK 报告

多个现成 SPS 目标可使用 Automatic SPS Setup，统一选择 SPS 四点定位或 Contact 直接定位。只测根点时只读取位置和旋转；开启尖端、配对 Plug 标记或抓取把手时才需要 Plug 长度。Shader 捕获通过独立作者预制件配置自己的 Producer ID 与桌面区域。

放置并配置预制件

1. 安装 Unity 组件包的 VPM 依赖：NDMF 1.5.0+、Modular Avatar 1.10.0+ 及配套 VRChat Avatars SDK。使用 SPS 作者目标时另装官方 VRCFury。Contact 直接定位已适配 3.10.6-beta.3 的 advancedParameters，同时兼容 Beta.2 的 advancedProximityParameters。
2. 从 GameObject → Sensa 创建所选方式，或把对应预制件放到 Avatar 层级内。检查 Target 指向希望测量的根点。
3. SPS 四点定位和 Contact 预制件默认实例名为 Root。测量多个点时使用不同的实例名，例如 Root、Chest、Hand。Collision Channel 留空时按实例名稳定分配；仅在需要手动管理通道时填写覆盖值。复制后改实例名即可得到独立的自动通道。
4. Shader 捕获使用唯一的 Producer Id（1–65535），并在桌面桥固定同一 ID。按Shader 设置配置呈现区域和捕获注册。
5. 正常执行 Avatar 构建或使用 NDMF 的处理后预览。在生成层级中检查测量组件，再按桌面指南检查参数、校准和输入启用。

作者宿主保持普通 GameObject。它的 Transform 可以作为测量参照，生成的 Contact、约束和动画也需要留在构建结果里。

创建随骨骼移动的参考平面

1. 在 Avatar 内选中要跟随的骨骼或 SPS 对象，通过 GameObject → Sensa → Tracking Frame 创建；也可放入 SensaTrackingFrame.prefab。
2. 检查参考坐标系（reference）。这里统一接受 Transform、SPS Socket／Plug、Sensa Component 或原生 Contact。菜单会尝试填入选中的目标；在 Avatar 根创建时，手动指定参照。
3. 设置唯一实例名称（instanceName），默认 Frame，最多 40 个 ASCII 字母、数字、下划线或连字符。选择定位方式（trackingMethod）：SPS 四点定位或 Contact 直接定位。
4. 用**原点偏移（positionOffset）放置平面中心，用坐标轴旋转（度）（rotationOffset）**调整朝向。两项基于已解析根点的局部轴；位置偏移在附加旋转前应用。Inspector 的六个轴向按钮可快速指定深度方向，Scene 的移动／旋转手柄用于细调。
5. 检查 Scene 中的 XY 平面与 +Z 箭头：+Z 是深度正方向，+X 向右，+Y 向上。**坐标轴标记间距（axisLength）**是 Origin 到 Forward／Right 标记的距离，按 Avatar 根制作单位计算，默认 0.2，可设 0.05～0.5。
6. 为同一 Avatar 内的测量目标 P 添加所选方式的根点预制件：SensaSpsRootProbe.prefab 或 SensaContactRootProbe.prefab。指定目标并使用独立实例名，例如 Target；已有同坐标框的测量实例可直接复用。
7. 构建后，在桌面确认目标、Origin 和 Forward 都提供有效坐标。在“流程 → 空间计算预设 → 跟随移动平面”选择目标与平面 Origin，检查生成草稿，再保存并连接输出。

生成的三点分别命名为 <名称>_Origin、<名称>_Forward、<名称>_Right。源参照随骨骼移动和转动，实际测量框架放在 Avatar 根下，通过 ParentConstraint 跟随平移、旋转。三点间距继承 Avatar 缩放，保持各向一致；骨骼自身缩放可改变偏移后原点的位置，轴长保持 Avatar 根制作尺寸。SPS 作者几何继续遵循其均匀缩放要求。

Scene 同时显示所选定位方式的覆盖范围。参与当前计算的点都要位于有效区域：默认模板使用目标 P、Origin 与 Forward；需要另一条方向时使用 Right。各标记分别沿用原协议的 Sample 检查。较短轴间距会放大方向读数的噪声，默认 0.2 的实际误差和快速运动下的效果可在客户端用已知姿态核对。测量目标与平面标记选择同一种坐标框；独立 Point／Pose 使用自己的 ReferenceLocal 参照，适合直接在该参照下测量。深度、偏移与角度计算

作者脚本怎样进入构建

Sensa 作者组件均实现 VRC.SDKBase.IEditorOnly：SensaComponent、SensaAutoSetup、SensaFixedRootProbe、SensaContactRootProbe、SensaShaderCapture、SensaTrackingFrame、SensaPointProbe、SensaPoseSocket、SensaPosePlug 和内部实验用 SensaQuickStart。

内部 QuickStart 保留作合成实验室入口。日常定位使用根点或跟随平面预制件，也可选 Point／Pose。

IEditorOnly 负责标识作者脚本，生成时机由 NDMF 插件安排。保留宿主对象、只移除作者组件，能让运行时的骨骼、参照点和生成物继续工作。

构建顺序

Sensa 使用一个 NDMF 生成入口。包依赖中已包含 NDMF 与 Modular Avatar；SDK 回调负责检查生成是否完成。

跟随平面也在同一 Generating 入口生成：读取独立根点作者后、自动 SPS 配置前创建三点，随后在基础 SensaComponent 清理前移除 Tracking Frame 作者。生成物继续由既有 SPS／Contact 协议处理。

每次构建通过 BuildContext.GetState 记录已生成状态。SPS 四点定位、Contact、Shader 与其他作者共用这一调度，运行时协议各自保持独立。SDK 的 -1026 检查只诊断残留设置，实际生成始终在前段 NDMF 执行。

表中的顺序也已在 SDK 3.10.6-beta.3、NDMF 1.14.8、Modular Avatar 1.18.7 和 VRCFury 1.1434.0 安装包中核对。VRCFury 当前还会把 SDK 的组件清理延后至 int.MaxValue；Sensa 自行完成作者清理，因此也适用 SDK 的默认顺序。其他工具可注册更晚的 SDK 回调，Contact 数量检查描述的是 Sensa 所在的 NDMF 检查点。

资产与引用怎样处理

生成器在构建副本上工作。目标、骨骼、PhysBone 和 Raycast 参照须属于当前 Avatar；基础组件先检查引用，再创建原生组件，便于在配置错误时定位问题。

Sensa 创建供 MA 合并的临时 Animator／菜单／参数，交给 NDMF 保存构建资产。原生根点 Shader 随包提供，位于 Runtime/Shaders/SensaRootTelemetry.shader；构建直接引用该资产。更新组件包后重新构建即可采用当前编码器。

SPS 四点定位和 Contact 的根缩放检查按约束的实际目标与 MA Merge Animator 的 relativePathRoot 判断。Avatar 根保持固定尺度，子对象可按自身需要缩放。Shader 采样另外校验原始轴向、量化后的轴向和世界均匀缩放，帮助在构建时发现会产生无效编码的设置。

三种根点方案都会先检查原生 Contact 的根点偏移和旋转：偏移须为有限数值，旋转须为有限且非零的四元数，并在读取时归一化，原始 Contact 配置保持可编辑。Shader 同时检查父级与 Avatar 共同形成的最终世界基，避免层层累积的小幅非均匀缩放生成持续无效的编码。Sensa Pose Socket 会在生成任何接收器前检查已有参数声明，重复的参数名会给出构建提示；实例名与配对通道仅使用规定的 ASCII 字符。

基础 SensaComponent 的原生 Contact 持续跟随配置的轴／骨骼，相关参数在 FX 中保持可写。Socket 量程与 Contact 尺寸使用所选轴的局部单位，轴缩放为 1 时数值等于米；SPS 四点定位和 Contact 直接定位仍分别采用上表的坐标契约。补充 Contact 信号配置与 Sender 相同的碰撞标签；已有参数信号只引用原参数，保留它原来的类型。

官方资料与核验范围

本次于 **2026-10-23（北京时间）**核对以下官方资料与源代码：

这些资料用于确定实现与排序。Unity EditMode 契约已编写，本次尚未在 Unity Editor 执行；各项实际结果见验证记录。Avatar 上传、客户端 OSC、渲染与设备联动分别验收。

Unity 包 · 自动配置 · 依赖与测量范围