OSC 参数字典

简体中文 | English

先找到参数，查看单位和方向，再选择映射或计算。表格列出 OGB／SPS 与 Sensa 定位使用的路径。在参数图解中可以搜索读数、移动目标、映射量程，再导出轨迹或发送到 WebSensa。

Node 的 OSC 服务接收与发现参数，共享 OscParameterStore保留来源、顺序、接收时间与内容变化时间。后续标量、定位与空间计算由同一 TypeScript 运行时处理，Electron 和浏览器工作台显示该应用快照。

用图解理解数值

公开参数图解按浏览器语言打开，手动切换后在当前标签页记住选择。分享时直接复制页面地址即可。应用参数详情可打开随包页面；保留相邻 assets，即可离线打开 docs/parameter-geometry.html。

先选择参数，再拖动橙色目标，观察靠近、进入、接触区域时读数怎样变化。十一个场景都有 3D、平面投影和精确滑条。蓝色表示接收范围，橙色表示目标信号的形状，灰色外形帮助理解 Socket／Plug 的相对位置；橙色操作柄放大显示，方便拖动。SPS 四点定位的四个颜色关联测量球、标签和参数行。

页面下方的“OSC 参数含义与来源”列出当前参数组的说明。展开实际参数名，可查看它测量什么、范围与单位、怎样用于联动，以及对应的官方或项目来源。工作台中打开 OSC → 参数，点击参数名称，也可在“参数含义”中阅读这些解释；先确认完整路径，再添加映射草稿。

图解按完整 XYZ 计算距离。XZ 视图将空间投到一个平面，SPS 四点定位的绿色部分另标出当前 Y 高度的可测切片。“可用值”体现 Close 或有效性条件，通过这些条件的数值可作为建立映射时的参考。实际联动按工作台指南配置。

参数按名称字典序显示，同一前缀的短名称在前，例如 PenOthers 在 PenOthersClose 之前。前缀中的 * 代表实例名：Sensa/SPS/Example/P0 的完整地址为 /avatar/parameters/Sensa/SPS/Example/P0。Shader ID 使用下文规定的十进制数。

Three.js／OrbitControls随资源打包；WebGL2不可用时切换 SVG。MIT 声明位于 assets/parameter-geometry-3d.LICENSE.txt。图解操作

说明来自哪里

“测量定义”说明参数怎样产生，“联动用法”帮助选择映射。页面按以下来源标注，官方说明采用便于理解的译述：

通用 Contacts 文档解释检测规则；本页高级 Proximity 字段的具体后缀、坐标框和速度语义来自上表官方 Beta 安装包实现，Contact 说明保留了对应方法和包摘要，方便复核。

先选择需要的信息

SPS 四点定位的 Unity 测量组件与桌面共享下文的五字段和固定几何。外部 OGB 参数由 Avatar 使用的生成器提供，可在参数列表中核对完整路径。

需要组合多个参数时，可在工作台建立计算信号，进行加权平均、差值、比例或向量长度计算，再映射到目标轴。定位计算直接选择已经解算的坐标或速度指标；每个输入保留来源和有效性条件。

OGB 与 VRCFury 参数

Orf 表示 Socket，Pen 表示 Plug。Self 表示检测自身的匹配目标，Others 表示检测其他 Avatar 的匹配目标。Sensa 按 OSC 来源、完整实例路径与类别配对。图解中的 SPS2 · PenOthersNewRoot / PenOthersNewTip 和 SPS1 · PenOthers / PenOthersClose 对应两种参数几何。

深度相关数值按检测形状之间的距离变化。正对 Socket 的移动最容易与进入深浅对应；横移、倾斜和作者设置的尺寸也会改变读数，因此映射时应以自己希望的起点和终点校准。Close=1 表示匹配目标进入该 Contact 定义的有效区域，适合作为动作生效条件；身体外形与区域边界的关系由作者的形状设置决定。SPS2 的 OgbDepth 使用 Receiver 半径 R=1、根球半径 r=0.01 的模型；图解可以帮助观察两路数值如何配合。

实际参数名以 Avatar 发布内容为准。完整生成表、形状和尺寸见OGB 详表，依据固定生成器源码与官方 OGB 消费端。

Raycast 补充信号：命中与距离

在 SensaComponent 的补充信号中选择 Raycast，可从指定原点沿其本地 +Z 方向测量表面距离。原点留空时使用组件所在对象；最大量程按米配置，支持正数至 1000。此功能需要 VRChat SDK 3.10.3+，Sensa 显式关闭 ApplyTransformScale，因此量程保持米制。

参数前缀为 Sensa/<id>/Aux<index>/<role>：<index> 是从 0 开始的补充信号序号，<role> 为 Inspector 中选择的角色标识，例如 Vibrate 或 GateEnable。角色用于区分参数名，桌面映射中再选择需要的控制用途。以实例 Body 的第一个 Vibrate 信号为例：

量程为 0.3 m、命中距离为 0.1 m 时，_Distance 约为 0.1，_Ratio 约为 1/3。先用 _Hit 确认命中，再读取距离：当前生成组件采用 SDK 默认的 DoNothing 未命中行为，未命中时 _Hit=false，两路距离保留最近的命中值，首次命中前为 0。

三字段对应官方 SDK 的原生 VRCRaycast 报告；官方 Raycast 参数说明解释了命中、距离比例和世界距离，以及未命中行为的选择。Sensa 将它们声明为本地、不同步的表达参数，并在 FX 中声明匹配类型。已核对最低支持版本 3.10.3 的 API 与参数绑定。Unity 配置 · 官方 SDK 3.10.3 安装包

Contact 直接定位（SDK Beta）：十二个公开字段

为所选自身根点使用专用球形 Sender，在 Avatar 根设置零偏移、各轴对齐的 Proximity Receiver。Receiver 使用独立碰撞通道且只接收 Self。Sensa 在 SDK 3.10.6-beta.3 开启 advancedParameters=true，在 Beta.2 开启 advancedProximityParameters=true。坐标框为 AvatarRootMeters：以 Avatar 根为原点，坐标轴随根旋转，保留物理米单位。设置与 SDK 核验依据

SDK Beta.3 的高级报告可用于任意 Receiver 类型，并新增 _SenderLossyScaleX/Y/Z（Sender 关联 Transform 的世界缩放）与 _PointSeparation（Sender 和 Receiver 最近内部点之间的世界距离，米）。它们描述原生 Contact 形状；Sensa 的 Distance 根据根点 XYZ 计算距 Avatar 原点的距离。Sensa 当前生成以下十二个公开字段，位置／速度解算和预设使用这套协议。使用额外原生报告时，由作者在 Animator 中声明对应 Float 并配置 OSC 可见性。官方发布说明 · 额外报告的读法与默认值

全部路径以 Sensa/Contact/<id>/ 开头，<id> 只占一层路径。下表按字典序排列，共享前缀的短名称在前。Proximity_SenderType 为 Int，其余十一个字段为 Float。

例如，Z 从 0.05 m 变到 0.15 m 表示沿接收器 Z 轴移动了 0.10 m，可将这两个端点校准为希望的动作范围。相对速率 0.4 m/s 描述该时刻的运动快慢；Proximity 变化率 0.4/s 则描述接近值每秒增加 0.4。按这三种含义分别选择位置、速度或接近变化的映射。

SDK 选择匹配 Sender 中 Proximity 严格大于零且最大的对象；Beta.3 在两个 Proximity 都为 1 时，以较小的 PointSeparation 决定目标。中点位移通过接收形状旋转的逆变换转换，保留米单位，未按缩放或半径归一化。报告速度取近似接触点处的相对速度，包含角运动项；形状旋转时，可能与中点位置的导数不同。没有选中 Sender 时，SDK 写入类型 0 和零 XYZ／速度。原生报告未提供时间戳、序号或稳定 Sender ID。

桌面要求同一来源与完整实例的十二字段齐全、类型为 Self、Proximity 为正、数值有限、位置在 Radius 边界及小量数值容差内，且 Radius 受支持。Sample 目标每 50 ms 推进，按 changedAtMs 检查的年龄上限为 1000 ms；较短的正数 osc.inputTimeoutMs 优先，重复相同计数不续期。Contact 消失、字段缺失、Radius／坐标非法或活动停用／冻结时，相关空间动作停止。

Contact 直接定位通过 SensaPoint 映射 X／Y／Z／Distance 或 VelocityX／VelocityY／VelocityZ／Speed／ProximitySpeed。端点校准、曲线、输出限位、空间启用与停止沿用现有流程。SPS 四点定位的 Sensa/SPS/<id>/{P0,P1,P2,P3,Sample} 和按制作尺度解释的 AvatarRootLocal 保留既有定义。定位说明 · 工作台

SPS 四点定位：四路近接与一个活动样本

生产端为明确选择的 Socket／Plug 根中心建立一个专用球形 Sender，四个球形 Receiver 固定在 Avatar 根坐标中，只接受自己的专用碰撞通道。每实例共五个 Contact，跟踪所选 Transform 根中心。生产端

五个公开测量参数

所有值均为 Float。一个 <id> 只占一层路径；实例名与专用碰撞通道须在 Avatar 内唯一。

FX 每个采样状态目标持续 0.05 秒：先复制 RawP0–RawP3 到 P0–P3，再写 Sample；Sample 从 1/32 到 1 循环，目标周期 1.6 秒。更新节奏还受动画、Contact 与 OSC 调度影响。根点静止时沿用最近的 P 值，并通过变化的 Sample 检查采样是否持续。共享常量、接收检查

Sample 的寿命按值最后变化时间 changedAtMs计算，正常运行时默认 1000 ms。运行时使用正数 osc.inputTimeoutMs 配置，否则回退为 1000 ms；解码器再将其上限限制为 1250 ms。因此配置更小会更严格，配置超过 1250 ms 也不会延长上限。重复发送同一个 Sample 只更新接收时间，不续期。缺少参数、Sample=0、非 n/32、冻结、超时或拟合失败均使坐标失效。运行时寿命选择

菜单选择测量目标

除每对象的五个测量 Float 外，Automatic 的 Exclusive 策略还生成 Sensa/Select/<group>，类型 Int，默认 0=Off，1…N 按 Targets 顺序选择对象；Dedicated 没有该组选择器。这个控制项由 MA 注册为表达参数，localOnly=true、saved=false，每次加载从默认值开始，按 VRChat OSC 配置决定可见性。选择器实现、MA 参数规则、VRChat OSC 配置

固定几何、距离公式与范围

所有坐标与半径均为 Avatar 根局部单位：中心 c=(0,1,0)，半跨度 h=0.35，Receiver 半径 R=2，标记半径 r=0.001。

球形 Sender 与 Receiver 的未饱和近接模型及反算为：

p = clamp(1 - max(0, d - r) / R, 0, 1)
d = R × (1 - p) + r

d 是锚点中心到标记中心的距离；加 r 是因为 Proximity 描述靠近 Receiver 中心的 Sender 表面。四个已知非共面锚点的真实距离足以唯一确定这个局部 XYZ。实现还要求 RMS 距离残差≤0.01、坐标在 X/Z=[-2,2]、Y=[-1,3] 内；残差反映四路距离与计算位置的一致程度。VRChat Contact 定义、重建实现

可用空间是四个球形覆盖区的交集，扣除饱和区与边界。以 c 为中心、半径约 2 - √3×0.35 ≈ 1.394 的球提供内接参考；p 阈值、饱和孔和数值边界进一步限定实际有效区域。上限 p<0.999 要求 d>0.003，故每个锚点附近约 0.003 局部单位（以局部米计为 3 mm）的区域被排除；下限 p>0.001 对应 d<1.999。世界尺寸随 Avatar 根缩放变化。

缩放、采样与菜单控制

设作者 Avatar 根的均匀世界缩放为 s_author，VRChat 的缩放因子为 ScaleFactor，则 Receiver 世界半径为 2 × s_author × ScaleFactor。官方 Contact 半径上限为缩放后的 3 m；生产端预留 0.001 m，使用：

maxScale = (3 - 0.001) / (2 × s_author)

超出门限时停用 Contact、清零公开采样并写 Sample=0；构建时拒绝不受支持的非均匀 Avatar 根缩放、根 ScaleConstraint 与根缩放动画。目标骨骼可以缩放，专用标记只跟随根中心，不把目标缩放带入已知球半径。s_author=1 且 ScaleFactor=1 时一个局部单位才等于一世界米。门控实现、VRChat 缩放后限制

RawP0–RawP3 供内部 FX 采样使用。ScaleFactor 与 IsLocal 用于缩放检查和本地运行，Sensa/Select/<group> 用于菜单选择。公开根位置测量固定为 P0–P3 与 Sample，坐标框和几何由共享定义提供。

专用通道与 AllowSelf 将测量限定到本 Avatar 的根标记。整体走动或转身时，读数保持相对 Avatar 的局部意义；测量时序和误差的检查方法见定位说明。

Shader：根点位置、轴向与世界缩放

原生 Avatar 渲染组件按作者配置的原点偏移与坐标轴旋转，采样测量原点、局部 +X 和 +Z 三个蒙皮点，编码为黑白图块。两项偏移为零时，测量框架与所选根点重合。桌面桥解码明确选择的区域和 Producer ID，再把同一次采样送入 Sensa。编码器 · 桥实现

十二个公开测量参数

<id> 为 Producer ID，十进制 1…65535，无前导零，例如 Sensa/Shader/7/X。以下参数均由 Sensa 桌面桥以 OSC Float 发送，采用 Sensa 协议。

两条轴由同一三角形内的三个采样点计算。向量长度须大于 10⁻⁶，两轴夹角的正弦须大于 10⁻⁴，以排除退化测量。它们可用于计算朝向、平面法线、夹角与 X/Z 轴缩放；独立 Y 轴缩放需要另外测量。在“流程”中选择定位测量（SensaPoint），使用 Sensa/Shader/<id>/** 和对应指标，即可供计算信号或输出绑定使用，并保留完整包与时效检查。

有效单 bundle 的固定顺序是 Frame → X → Y → Z → RightX → RightY → RightZ → ForwardX → ForwardY → ForwardZ → AvatarScale → Valid=1。失效只发 Valid=0。桌面要求同一来源、同一 Producer 路径的十二字段连续到达，并检查完整性、有限值和量程。Frame 内容变化年龄最多 500 ms，更短的正数输入超时优先。共享解码器

桥先找到 QR 定位方框，再进行 Reed–Solomon 纠错、CRC32 和向前序号检查。同一 Frame 的任意测量改变、倒序、来源变化或冻结都会使测量失效；启动和恢复需要两个新的推进帧，默认冻结门限 350 ms。49×49 格图块包含 33×33 格 QR 主体和每边 8 格白色留白，捕获至少需要 196×196 物理像素。留白包含标准静区与额外位移余量；窗口尺寸改变后重新框选完整图块。

Shader 菜单另有 Sensa/Select/ShaderCapture_<ID>：Int，默认 0=Off，1=开启捕获。MA 将其注册为 localOnly=true、saved=false 的表达参数。内部 Sensa/Internal/ShaderCapture_<ID>/Selected 为 FX Int 状态记忆，默认 0，由本地 Driver 写入 0／1。生成入口 · 选择状态机

数字精度与完整性

位置量化步长为 4/65535≈6.10×10⁻⁵ 根局部单位；轴向分量为 8/32767≈2.44×10⁻⁴，零可精确表示；世界缩放为 8/65535≈1.22×10⁻⁴ 米／局部单位。理想舍入的单分量误差最多半步，实际误差另以已知位置和方向测量。图解采用与 HLSL round 一致的最近偶数舍入。

32 字节包保留 Producer ID、坐标标志、时钟序号、完整测量值与 CRC32。QR v4-H 将数据分成四组，每组 9 个数据字节和 16 个纠错字节，按 2×错误字节数＋缺失字节数≤16 的范围恢复。数据来自同一次捕获；完整性与时效检查共同决定结果是否可用。完整布局与恢复规则

诊断与位置相关信息

Sensa/Diagnostics/Shader/0/Frame|X|Y|Z|Valid 使用五字段传输形式，XYZ 为 [-1,1] 的诊断值，可用来检查图案生成、区域捕获和 OSC 传输。ID=0 在诊断命名空间中处理；原生根位置使用 1…65535 的对象 ID。诊断分流

独立 Point／Handle／Pose 实验使用各自的参考对象和完整字段。空间联动的启动步骤是：允许实验空间输入，选择来源与映射，再启用当前输入。运行条件与实际客户端检查方法见定位说明与Shader 研究记录。