Cocos UI如何精准跟随3D物体移动并保持屏幕位置稳定？

Question

在Cocos Creator 3.x中，实现UI（如血条、名称标签）精准跟随3D物体并稳定显示于屏幕指定位置（如头顶正上方），常因坐标系转换不一致导致抖动、偏移或Z轴穿透。典型问题：调用`camera.worldToScreen()`将3D世界坐标转为屏幕坐标后，直接赋值给UI节点的`position`，却忽略Canvas的适配模式（如FIT_HEIGHT）、屏幕缩放因子、UI锚点（anchorPoint）与布局组件（如Widget/AspectRatioAdapter）的干扰；更关键的是未对投影后的Z值做有效性校验——当目标物体位于相机后方或被遮挡时，仍强行渲染，引发UI“穿墙”或跳变。此外，在动态分辨率或横竖屏切换场景下，若未监听`Canvas.resize`事件并重算偏移，UI会随窗口缩放失准。如何在保证性能前提下，实现毫秒级同步、深度剔除、自适应缩放且无视觉抖动的稳定跟随？

Answer 1

```html

一、现象层：识别UI跟随失稳的典型视觉症状

• 血条在角色头顶“悬浮抖动”，帧间偏移像素级跳变（尤其在快速旋转相机时）
• 名称标签突然“穿墙”出现在场景后方，或瞬时翻转至屏幕对角线位置
• 横屏切换后UI整体缩放错位，血条宽度压缩为原尺寸30%，锚点失效
• 角色被墙体遮挡时，UI仍高亮显示，违反Z-depth可见性逻辑

二、坐标系层：解构Cocos Creator 3.x多空间转换链

关键转换路径：World → View → Clip → NDC → Screen → Canvas UI Space。其中致命断点有三：

空间	坐标范围	常见误用
NDC（标准化设备坐标）	[-1,1]×[-1,1]×[-1,1]	直接将worldToScreen()返回的z值用于剔除，未映射到[0,1]深度缓冲区间
Canvas UI Space	依赖Canvas.fitHeight等适配模式	忽略Canvas.designResolution与view.getVisibleSize()缩放比，导致像素坐标失真

三、机制层：三大核心干扰源与校验漏点

1. 适配模式污染：FIT_HEIGHT下，Canvas实际渲染区域高度=设计分辨率高度×缩放因子，但worldToScreen()输出基于物理像素，需乘以Canvas._scaleX/_scaleY
2. 锚点-布局耦合干扰：Widget组件强制重设position，覆盖手动设置值；AspectRatioAdapter动态修改node.scale，使UI节点世界坐标失准
3. Z值有效性盲区：未校验screenPos.z < 0 || screenPos.z > 1（即物体在近裁剪面内或远裁剪面外），亦未接入camera.depthTexture做屏幕空间深度采样剔除

四、架构层：高性能稳定跟随系统设计

graph TD
  A[每帧Update] --> B{目标是否激活且可见？}
  B -->|否| C[隐藏UI并跳过计算]
  B -->|是| D[worldToScreen + 深度采样]
  D --> E[Z有效性校验 + 屏幕边界裁剪]
  E --> F[Canvas适配空间映射]
  F --> G[应用锚点偏移与Widget补偿]
  G --> H[批量提交至UI渲染队列]

五、实现层：生产就绪代码范式（含性能优化）

export class UIDockSystem extends Component {
  @property(Camera) camera: Camera = null;
  @property(Node) target: Node = null;
  private _canvas: Canvas = null;
  private _lastValidZ = -1;

  onLoad() {
    this._canvas = find('Canvas').getComponent(Canvas);
    // 监听动态适配事件
    this._canvas.node.on(CanvasResizeEvent, this._onCanvasResize, this);
  }

  update(dt: number) {
    if (!this.target || !this.camera || !this.node.active) return;

    const worldPos = this.target.worldPosition.clone();
    const screenPos = this.camera.worldToScreen(worldPos);

    // 【关键】Z深度有效性双校验
    if (screenPos.z < 0.01 || screenPos.z > 0.99) {
      this.node.active = false;
      return;
    }

    // 【关键】Canvas适配空间映射（支持FIT_HEIGHT/FIT_WIDTH/SHOW_ALL）
    const visibleSize = view.getVisibleSize();
    const scaleX = visibleSize.width / this._canvas.designResolution.width;
    const scaleY = visibleSize.height / this._canvas.designResolution.height;

    // 转换到Canvas本地坐标系（考虑anchorPoint=0.5）
    const uiX = (screenPos.x - visibleSize.width * 0.5) / scaleX;
    const uiY = (screenPos.y - visibleSize.height * 0.5) / scaleY;

    // 应用Widget补偿（若存在）
    const widget = this.node.getComponent(Widget);
    if (widget && widget.isAlignTop) {
      this.node.position = new Vec3(uiX, uiY + 30, 0); // 头顶偏移30px
    } else {
      this.node.position = new Vec3(uiX, uiY, 0);
    }
    this.node.active = true;
  }

  private _onCanvasResize() {
    // 清空缓存，触发下一帧重算
    this._lastValidZ = -1;
  }
}

六、验证层：量化稳定性指标与压测建议

• 抖动抑制：使用Vec3.distanceSquared(prevPos, currPos) < 0.5过滤亚像素抖动（避免高频微调）
• 深度精度：启用camera.depthTextureEnabled = true，采样深度纹理做逐像素遮挡判断（开销+1.2ms@1080p）
• 横竖屏一致性：在CanvasResizeEvent回调中记录view.getScaleX()，对比前后缩放比偏差>0.05则强制重置UI位置

```