设置与控制

此页面介绍如何在创建后控制、配置和查询补间动画。

控制方法

使用 VRCTweenHandle 的实例方法控制补间动画：

方法	描述
`tweenHandle.Play()`	继续播放暂停的补间动画。
`tweenHandle.Pause()`	暂停正在播放的补间动画。返回句柄以支持链式调用。
`tweenHandle.Kill()`	停止并移除补间动画。
`tweenHandle.Complete()`	立即完成补间动画并跳转到其结束值。
`tweenHandle.Restart()`	从头重新启动补间动画。
`tweenHandle.Flip()`	翻转播放方向。如果已暂停则不会开始播放。
`tweenHandle.PlayBackwards()`	设置方向为向后并播放。
`tweenHandle.PlayForwards()`	设置方向为向前并播放。
`tweenHandle.Goto(float to, bool andPlay)`	跳转到指定的时间位置（秒）。如果 `andPlay` 为 true，则跳转后播放；否则暂停。用于将补间动画与网络时间同步。
`VRCTween.KillAll()`	停止所有活动的补间动画。
`gameObject.KillAllTweens()`	停止一个 GameObject 上的所有补间动画。

查询属性

使用 VRCTweenHandle 的属性查询补间动画状态：

属性	类型	描述
`tweenHandle.IsValid`	bool	如果句柄引用了一个补间动画则为 true（`default` 句柄为 false）。
`tweenHandle.IsPlaying`	bool	如果补间动画当前正在播放则为 true。
`tweenHandle.IsActive`	bool	如果补间动画存在且未被停止则为 true。
`tweenHandle.Elapsed`	float	已过去的时间（秒）。
`tweenHandle.Duration`	float	总时长（秒）。
`tweenHandle.IsBackwards`	bool	如果补间动画当前正在向后播放则为 true。

补间设置

配置方法返回句柄以支持链式调用。大多数设置（OnComplete、SetLoops、SetDelay、SetUpdate、From、SetSpeedBased）应在创建补间动画后立即应用。在补间动画开始播放后（即当前帧之后）应用的设置可能无效。但 SetDuration、SetEase 和 ChangeEndValue 可以在活动补间动画上随时调用。

OnComplete

设置补间动画完成时触发的回调。返回句柄以支持链式调用。目标回调方法必须为 public。

// Use custom event names for different tweens.
door.TweenPosition(openPosition, 1f, VRCTweenEase.OutQuad)
    .OnComplete(this, nameof(OnDoorOpened));

window.TweenScale(Vector3.zero, 2f, VRCTweenEase.InQuad)
    .OnComplete(this, nameof(OnWindowClosed));

public void OnDoorOpened()
{
    Debug.Log("Door opened!");
}

public void OnWindowClosed()
{
    Debug.Log("Window closed!");
}

callback: The UdonBehaviour to receive the callback (pass this).
eventName: The name of the custom event to call. Must be public.

OnRewind

设置补间动画回退到起始位置时（向后播放到达位置 0）触发的回调。返回句柄以支持链式调用。目标回调方法必须为 public。

audioSource.TweenVolume(1f, 2f, VRCTweenEase.InSine)
    .OnRewind(this, nameof(OnFadeComplete));

public void OnFadeComplete()
{
    Debug.Log("Backwards playback reached start!");
}

callback: The UdonBehaviour to receive the callback (pass this).
eventName: The name of the custom event to call. Must be public.

note

OnRewind only fires when backwards playback reaches position 0. It does not fire on Restart().

SetLoops

设置补间动画的循环次数。返回句柄以支持链式调用。

tweenHandle.SetLoops(5, VRCTweenLoopType.Restart);

loops：循环次数。使用 -1 表示无限循环。
loopType：循环行为：
- VRCTweenLoopType.Restart (0)：从头重新开始。
- VRCTweenLoopType.Yoyo (1)：先向前再向后播放。
- VRCTweenLoopType.Incremental (2)：每次循环叠加到上一个结束值。

SetDelay

设置补间动画开始前的延迟。返回句柄以支持链式调用。负值、NaN 或 Infinity 值将被静默忽略。参见输入验证。

tweenHandle.SetDelay(1.5f);

delay：延迟时间（秒）。

SetUpdate

设置补间动画的更新类型。返回句柄以支持链式调用。

tweenHandle.SetUpdate(VRCTweenUpdateType.LateUpdate);

updateType：何时更新补间动画：
- VRCTweenUpdateType.Update (0)：在 Update 中。
- VRCTweenUpdateType.LateUpdate (1)：在 LateUpdate 中。
- VRCTweenUpdateType.FixedUpdate (2)：在 FixedUpdate 中。
- VRCTweenUpdateType.PostLateUpdate (3)：在所有 LateUpdate 调用之后。用于覆盖摄像机、IK 或其他 LateUpdate 驱动的变换。

From

反转补间动画，使其从目标值开始并动画到对象的当前值。这对于"从某处出现"的动画很有用，例如对象动画到其放置位置。仅适用于非虚拟补间动画（变换、UI、精灵等）。必须在创建后立即调用。返回句柄以支持链式调用。

public GameObject notification;

void Start()
{
    // Object is at its final position in the scene.
    // This tween starts it at (0, 10, 0) and animates TO the current position.
    notification.TweenPosition(new Vector3(0, 10, 0), 1f, VRCTweenEase.OutBounce)
        .From();
}

SetSpeedBased

将补间动画设置为基于速度。启用后，duration 参数变为每秒单位数而不是总秒数。当你希望无论距离如何都保持一致的移动速度时，这很有用。返回句柄以支持链式调用。

// Move at 5 units per second, regardless of distance
gameObject.TweenPosition(targetPos, 5f, VRCTweenEase.Linear)
    .SetSpeedBased();

// Walk along a path at 3 units per second
gameObject.TweenPath(waypoints, 3f, VRCTweenPathType.CatmullRom, false, 10, VRCTweenEase.Linear)
    .SetSpeedBased();

note

SetSpeedBased 必须在创建补间动画后立即调用。如果在补间动画开始播放后应用则无效。

SetEase

覆盖补间动画的缓动函数。你可以传入 VRCTweenEase 预设或自定义 AnimationCurve。对于曲线，时间轴（0 到 1）映射到补间动画的进度，值轴映射到插值因子。返回句柄以支持链式调用。可以在活动补间动画上调用。

// Preset ease
tweenHandle.SetEase(VRCTweenEase.OutBounce);

// Custom curve
public AnimationCurve customEase;

void Start()
{
    gameObject.TweenPosition(new Vector3(0, 5, 0), 2f, VRCTweenEase.Linear)
        .SetEase(customEase);
}

easeType：一个 VRCTweenEase 值。
curve：一个 Unity AnimationCurve。在检查器中编辑它以可视化地调整缓动形状。

SetDuration

更改补间动画的时长（秒）。返回句柄以支持链式调用。可以在活动补间动画上调用。负值、NaN 或 Infinity 值将被静默忽略。参见输入验证。

tweenHandle.SetDuration(3f);

duration：新的时长（秒）。

ChangeEndValue

更改补间动画的目标值。返回句柄以支持链式调用。可以在活动补间动画上调用。不安全的值（NaN、Infinity 或极端数值）将被静默忽略。参见输入验证。

当 snapStartValue 为 true 时，起始值会捕捉到补间动画的当前值。这对于重用补间动画很有用，使动画从对象当前所在位置开始，而不是跳回原始起始位置。

tweenHandle.ChangeEndValue(new Vector3(10, 0, 0), true);

newEndValue：新的目标值。必须与补间动画的类型匹配（位置/旋转/缩放为 Vector3，淡入淡出为 float，颜色补间为 Color，RectTransform 补间为 Vector2）。
snapStartValue：如果为 true，起始值更新为当前值。

note

ChangeEndValue 适用于变换、UI、精灵、音频以及虚拟 float/int 补间动画。不支持虚拟 Color/Vector3 补间动画、渲染器（MaterialPropertyBlock）补间动画、灯光补间动画或路径补间动画。

补间重用

对于频繁重定向的补间动画（例如每帧或响应快速输入），重用句柄可以避免每帧分配。对于由交互触发的一次性动画，创建新的补间动画更简单且效果良好。DOTween 内部使用池化，因此开销很小。

VRCTweenHandle _moveHandle;

void Start()
{
    // Create the tween once with infinite loops so it stays alive after completing.
    _moveHandle = gameObject.TweenPosition(Vector3.zero, 1f, VRCTweenEase.OutQuad)
        .SetLoops(-1, VRCTweenLoopType.Restart)
        .Pause();
}

public void MoveTo(Vector3 target, float duration)
{
    // Reconfigure and restart without allocating.
    _moveHandle.ChangeEndValue(target, true)
        .SetDuration(duration)
        .SetEase(VRCTweenEase.OutCubic);
    _moveHandle.Restart();
}

方向控制

你可以在动画播放过程中反转补间动画的播放方向。与停止并在相反方向创建新的补间动画不同，这可以保留缓动曲线。动画会平滑地改变方向，而不会重新开始缓动。

VRCTweenHandle _fadeHandle;

void Start()
{
    _fadeHandle = audioSource.TweenVolume(1f, 2f, VRCTweenEase.InSine)
        .OnRewind(this, nameof(OnFadeOut))
        .Pause();
}

public void OnZoneEnter()
{
    _fadeHandle.PlayForwards();
}

public void OnZoneExit()
{
    _fadeHandle.PlayBackwards();
}

public void OnFadeOut()
{
    // Backwards playback reached the start
}

Flip() 切换方向但不会开始播放。如果补间动画已暂停，需要单独调用 Play()。
PlayBackwards() 和 PlayForwards() 都设置方向并开始播放。
向后播放到起始位置的补间动画不会自动停止。它们保持存活状态，以便你可以再次反转方向。如果需要，在 OnDestroy 中手动停止它们。
OnRewind 仅在向后播放到达位置 0 时触发。不会在 Restart() 时触发。

使用 Goto 跳转

使用 Goto 将补间动画跳转到特定的时间位置。这对于将长时间运行的补间动画与网络时间同步特别有用，以便晚加入者看到正确的状态。

[UdonSynced] float _tweenStartTime;
VRCTweenHandle _syncedTween;

void Start()
{
    _syncedTween = gameObject.TweenPosition(targetPos, 10f, VRCTweenEase.Linear)
        .SetLoops(-1, VRCTweenLoopType.Restart);
}

public override void OnDeserialization()
{
    float elapsed = (float)(Networking.GetServerTimeInSeconds() - _tweenStartTime);
    _syncedTween.Goto(elapsed, true);
}

andPlay 参数控制补间动画在跳转后是播放还是暂停。传入 true 从新位置继续播放，传入 false 则停在该位置。

路径类型

路径类型	描述
`VRCTweenPathType.Linear`	路径点之间的直线段。
`VRCTweenPathType.CatmullRom`	使用 Catmull-Rom 样条的平滑曲线路径。

缓动类型

缓动类型	描述
`VRCTweenEase.Linear`	恒定速度。
`VRCTweenEase.InSine`	正弦波 - 平滑加速。
`VRCTweenEase.OutSine`	正弦波 - 平滑减速。
`VRCTweenEase.InOutSine`	正弦波 - 两端平滑。
`VRCTweenEase.InQuad`	二次方 - 加速。
`VRCTweenEase.OutQuad`	二次方 - 减速。
`VRCTweenEase.InOutQuad`	二次方 - 先加速后减速。
`VRCTweenEase.InCubic`	三次方 - 加速（更明显）。
`VRCTweenEase.OutCubic`	三次方 - 减速（更明显）。
`VRCTweenEase.InOutCubic`	三次方 - 先加速后减速（更明显）。
`VRCTweenEase.InQuart`	四次方 - 强加速。
`VRCTweenEase.OutQuart`	四次方 - 强减速。
`VRCTweenEase.InOutQuart`	四次方 - 先强加速后强减速。
`VRCTweenEase.InQuint`	五次方 - 非常强的加速。
`VRCTweenEase.OutQuint`	五次方 - 非常强的减速。
`VRCTweenEase.InOutQuint`	五次方 - 先非常强的加速后非常强的减速。
`VRCTweenEase.InExpo`	指数 - 爆发性加速。
`VRCTweenEase.OutExpo`	指数 - 爆发性减速。
`VRCTweenEase.InOutExpo`	指数 - 先爆发性加速后爆发性减速。
`VRCTweenEase.InCirc`	圆形 - 平滑、圆润的加速。
`VRCTweenEase.OutCirc`	圆形 - 平滑、圆润的减速。
`VRCTweenEase.InOutCirc`	圆形 - 两端平滑、圆润。
`VRCTweenEase.InElastic`	弹性 - 有弹性的开始。
`VRCTweenEase.OutElastic`	弹性 - 有弹性的结束。
`VRCTweenEase.InOutElastic`	弹性 - 两端有弹性。
`VRCTweenEase.InBack`	回退 - 开始时轻微过冲。
`VRCTweenEase.OutBack`	回退 - 结束时轻微过冲。
`VRCTweenEase.InOutBack`	回退 - 两端轻微过冲。
`VRCTweenEase.InBounce`	弹跳 - 弹跳的开始。
`VRCTweenEase.OutBounce`	弹跳 - 弹跳的结束。
`VRCTweenEase.InOutBounce`	弹跳 - 两端弹跳。

tip

尝试不同的缓动类型，找到适合你动画的感觉。VRCTweenEase.OutQuad 非常适合 UI，VRCTweenEase.OutElastic 增加俏皮的弹性，VRCTweenEase.InOutSine 创造平滑自然的运动。

控制方法​

查询属性​

补间设置​

OnComplete​

OnRewind​

SetLoops​

SetDelay​

SetUpdate​

From​

SetSpeedBased​

SetEase​

SetDuration​

ChangeEndValue​

补间重用​

方向控制​

使用 Goto 跳转​

路径类型​

缓动类型​

控制方法

查询属性

补间设置

OnComplete

OnRewind

SetLoops

SetDelay

SetUpdate

From

SetSpeedBased

SetEase

SetDuration

ChangeEndValue

补间重用

方向控制

使用 Goto 跳转

路径类型

缓动类型