身体动画使用示例

编写一个角色，使其走向目标并在到达时打招呼、按提示执行手势、指向场景对象，并报告自定义移动情况。

这四个场景脚本 ConvaiBodyAnimationController 并直接调用其配套组件，适用于需要超出已编写内容之外行为的角色 ConvaiBodyAnimationSet 而后端动作会自行触发。每个示例都假设该角色已经有一个可用的 ConvaiBodyAnimationController ——参见 身体动画快速入门 如果还没有的话。

走向目标并在到达时打招呼

当场景触发器触发时，一名导游角色会走向一个路径点，然后只有在它确实到达目的地而不是在途中被打断时，才会播放一个打招呼手势。

using UnityEngine;
using Convai.Modules.BodyAnimation;
using Convai.Modules.BodyAnimation.Components;

public sealed class GreetOnArrival : MonoBehaviour
{
    [SerializeField] private Transform greetingSpot;

    private ConvaiBodyAnimationController _bodyAnimation;
    private ConvaiNavMeshLocomotion _locomotion;

    private void Awake()
    {
        _bodyAnimation = GetComponent<ConvaiBodyAnimationController>();
        _locomotion = GetComponent<ConvaiNavMeshLocomotion>();
    }

    private void OnEnable() => _locomotion.MoveEnded += OnMoveEnded;
    private void OnDisable() => _locomotion.MoveEnded -= OnMoveEnded;

    public void WalkToGreetingSpot() => _locomotion.MoveTo(greetingSpot.position);

    private void OnMoveEnded(bool reachedDestination)
    {
        if (!reachedDestination) return; // interrupted or stopped short — do not greet

        BodyAnimationActionHandle handle = _bodyAnimation.PlayAction("wave",
            new ActionPlayOptions { HoldSeconds = 2f });
        if (handle.Failed)
            Debug.LogWarning($"Greeting did not play: {handle.FailureReason}");
    }
}

MoveEnded 报告 true 用于一次到达，以及 false 用于取消或被中断的移动，因此只有当角色确实到达那里时，问候才会播放。

按提示播放手势

当场景逻辑判定受训者做对了什么时，一名训练师角色会点头做出肯定手势，与 Convai 发送的任何内容无关。

using UnityEngine;
using Convai.Modules.BodyAnimation;
using Convai.Modules.BodyAnimation.Components;

public sealed class TrainerCues : MonoBehaviour
{
    private ConvaiBodyAnimationController _bodyAnimation;

    private void Awake() => _bodyAnimation = GetComponent<ConvaiBodyAnimationController>();

    public async void PlayAffirmativeCue()
    {
        BodyAnimationActionHandle handle = _bodyAnimation.PlayAction("yes");
        if (handle.Failed)
        {
            Debug.LogWarning($"Affirmative cue did not play: {handle.FailureReason}");
            return;
        }

        bool completedNaturally = await handle.Completion;
        if (!completedNaturally)
            Debug.Log("Affirmative cue was interrupted before it finished.");
    }
}

PlayAction 从不返回 null失败。调用前请检查 handle.Failed 而不是进行空值检查——失败的句柄仍会立即完成，因此 await handle.Completion 始终可以安全调用。

指向场景对象

当玩家询问某个展品时，博物馆导览员会指向该展品三秒，使用展品自身的 Transform 因此，如果展品在保持期间移动，手势会重新瞄准。

using UnityEngine;
using Convai.Modules.BodyAnimation;
using Convai.Modules.BodyAnimation.Components;

public sealed class PointOutExhibit : MonoBehaviour
{
    [SerializeField] private Transform exhibit;

    private ConvaiBodyAnimationController _bodyAnimation;

    private void Awake() => _bodyAnimation = GetComponent<ConvaiBodyAnimationController>();

    public async void PointAtExhibit()
    {
        BodyAnimationPointingHandle handle = _bodyAnimation.PointAt(exhibit, holdSeconds: 3f);
        if (handle.Failed)
        {
            Debug.LogWarning($"Pointing did not play: {handle.FailureReason}");
            return;
        }

        await handle.Completion;
    }
}

PointAt 会选择角度上与展品最接近的已编写指向动画片段——参见 排查身体动画 如果手臂始终瞄准偏离目标。

从自定义移动器报告移动

过场角色由补间而不是 ConvaiNavMeshLocomotion，但在行走时仍需要 Gaze 注视路径。向 ConvaiTravelIntent 每一帧报告即可赋予其这种行为，无需涉及 NavMesh。

using UnityEngine;
using Convai.Runtime.Embodiment;

public sealed class TweenMover : MonoBehaviour
{
    [SerializeField] private Transform destination;
    [SerializeField] private float speed = 2f;

    private ConvaiTravelIntent _travelIntent;

    private void Awake()
    {
        _travelIntent = GetComponent<ConvaiTravelIntent>();
        if (_travelIntent == null)
            _travelIntent = gameObject.AddComponent<ConvaiTravelIntent>();
    }

    private void Update()
    {
        Vector3 toDestination = destination.position - transform.position;
        toDestination.y = 0f;

        if (toDestination.magnitude < 0.1f)
        {
            _travelIntent.ClearTravel();
            _travelIntent.ClearSubject();
            return;
        }

        transform.position += toDestination.normalized * speed * Time.deltaTime;
        _travelIntent.ReportTravelTo(destination.position, speed01: 1f);
    }
}

ReportTravelTo 会报告移动方向并将 destination 在一次调用中将其命名为主题，这正是行走时会获得周期性侧目注视的原因。报告刻意不是 NavMesh 功能： 角色控制器、根运动或第三方导航也是同样的报告方式。停止重复的报告会自行过期，因此不需要单独的“停止”调用，除非 ClearTravel.

下一步

播放动作和手势配置移动身体动画故障排查