338 lines
12 KiB
C#
338 lines
12 KiB
C#
using System;
|
||
using UnityEngine;
|
||
|
||
namespace Base
|
||
{
|
||
/// <summary>
|
||
/// 抽象基类，用于封装通用动画逻辑。
|
||
/// 所有的动画播放器都应继承自该类，并实现其抽象方法来控制具体的显示组件。
|
||
/// </summary>
|
||
public abstract class BaseAnimator : MonoBehaviour, ITick
|
||
{
|
||
// 通用公开字段（可在编辑器中设置）
|
||
|
||
/// <summary>
|
||
/// 动画播放的精灵序列。
|
||
/// </summary>
|
||
[SerializeField] protected Sprite[] _sprites;
|
||
|
||
/// <summary>
|
||
/// 每秒帧数，控制动画播放速度。
|
||
/// </summary>
|
||
[SerializeField] protected float _fps = 2;
|
||
|
||
/// <summary>
|
||
/// 动画暂停时显示的静态精灵。
|
||
/// 如果未设置，则默认保持当前帧。
|
||
/// </summary>
|
||
[SerializeField] protected Sprite _staticSprite;
|
||
|
||
// 通用内部状态
|
||
|
||
/// <summary>
|
||
/// 指示动画是否处于暂停状态。
|
||
/// </summary>
|
||
protected bool _isPaused;
|
||
|
||
/// <summary>
|
||
/// 用于跟踪当前帧播放时间的计时器。
|
||
/// </summary>
|
||
protected float _frameTimer;
|
||
|
||
/// <summary>
|
||
/// 当前正在显示的精灵帧索引。
|
||
/// </summary>
|
||
protected int _currentFrameIndex;
|
||
|
||
/// <summary>
|
||
/// 指示动画是否为一次性播放模式。
|
||
/// </summary>
|
||
protected bool _isOneShot;
|
||
|
||
/// <summary>
|
||
/// 抽象方法：子类必须实现此方法以获取并验证其特有的显示组件。
|
||
/// 例如：SpriteRenderer、Image等。
|
||
/// </summary>
|
||
protected abstract void ValidateComponent();
|
||
|
||
/// <summary>
|
||
/// 抽象方法：子类必须实现此方法以将给定的精灵设置到实际显示组件上。
|
||
/// </summary>
|
||
/// <param name="sprite">要显示的精灵。</param>
|
||
protected abstract void SetDisplaySprite(Sprite sprite);
|
||
|
||
/// <summary>
|
||
/// Unity生命周期方法：在脚本实例被加载时调用。
|
||
/// 主要用于初始化组件和动画的第一帧。
|
||
/// </summary>
|
||
protected virtual void Awake()
|
||
{
|
||
// 子类获取并验证其显示组件
|
||
ValidateComponent();
|
||
// 初始化动画的第一帧
|
||
ValidateStartFrame();
|
||
}
|
||
|
||
/// <summary>
|
||
/// Unity生命周期方法：在第一次帧更新之前调用。
|
||
/// 用于将当前动画器添加到全局计时器。
|
||
/// </summary>
|
||
private void Start()
|
||
{
|
||
Clock.AddTick(this);
|
||
}
|
||
|
||
/// <summary>
|
||
/// Unity生命周期方法：在MonoBehaviour被销毁时调用。
|
||
/// 用于将当前动画器从全局计时器中移除。
|
||
/// </summary>
|
||
private void OnDestroy()
|
||
{
|
||
Clock.RemoveTick(this);
|
||
}
|
||
|
||
/// <summary>
|
||
/// ITick接口实现：每帧更新动画状态。
|
||
/// </summary>
|
||
public void Tick()
|
||
{
|
||
// 如果游戏对象不活跃，则不进行更新
|
||
if (!gameObject.activeSelf)
|
||
return;
|
||
|
||
var deltaTime = Time.deltaTime;
|
||
// 如果动画处于暂停状态，则处理暂停逻辑
|
||
if (_isPaused)
|
||
{
|
||
HandlePausedState();
|
||
return;
|
||
}
|
||
|
||
// 否则，播放动画
|
||
PlayAnimation(deltaTime);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 验证并设置动画的初始帧。
|
||
/// </summary>
|
||
protected void ValidateStartFrame()
|
||
{
|
||
// 确保有精灵序列且不为空以显示有效帧
|
||
if (_sprites != null && _sprites.Length > 0)
|
||
{
|
||
// 确保当前帧索引在有效范围内
|
||
_currentFrameIndex = Mathf.Clamp(_currentFrameIndex, 0, _sprites.Length - 1);
|
||
// 调用抽象方法设置当前帧的精灵
|
||
SetDisplaySprite(_sprites[_currentFrameIndex]);
|
||
}
|
||
else
|
||
{
|
||
// 如果没有精灵，则调用抽象方法清空显示组件的精灵
|
||
SetDisplaySprite(null);
|
||
// 如果没有精灵可显示，默认隐藏游戏对象
|
||
gameObject.SetActive(false);
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// 处理动画处于暂停状态时的显示逻辑。
|
||
/// </summary>
|
||
protected void HandlePausedState()
|
||
{
|
||
// 如果设置了静态精灵，则优先显示静态精灵
|
||
if (_staticSprite)
|
||
{
|
||
// 调用抽象方法显示静态精灵
|
||
SetDisplaySprite(_staticSprite);
|
||
}
|
||
// 否则，保持当前显示的精灵（SetDisplaySprite已在NextFrame或ValidateStartFrame中设置），无需额外操作。
|
||
}
|
||
|
||
/// <summary>
|
||
/// 根据时间增量播放动画。
|
||
/// </summary>
|
||
/// <param name="deltaTime">自上一帧以来的时间增量。</param>
|
||
protected void PlayAnimation(float deltaTime)
|
||
{
|
||
// 如果没有精灵序列或序列为空，则清空显示并隐藏游戏对象
|
||
if (_sprites == null || _sprites.Length == 0)
|
||
{
|
||
// 确保显示组件的精灵被清除
|
||
SetDisplaySprite(null);
|
||
// 没有精灵可显示，隐藏游戏对象
|
||
gameObject.SetActive(false);
|
||
return;
|
||
}
|
||
|
||
// 更新帧计时器
|
||
_frameTimer += deltaTime;
|
||
// 计算每帧的持续时间
|
||
var frameDuration = 1f / _fps;
|
||
|
||
// 检查是否满足帧切换条件，如果一帧时间过去，则切换到下一帧
|
||
while (_frameTimer >= frameDuration)
|
||
{
|
||
_frameTimer -= frameDuration;
|
||
NextFrame();
|
||
// 如果是一次性播放模式，并且动画已播放到最后一帧并暂停，则跳出循环，防止在同一帧内进行二次处理
|
||
if (_isOneShot && _currentFrameIndex == _sprites.Length - 1 && _isPaused)
|
||
{
|
||
return;
|
||
}
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// 切换到动画的下一帧。
|
||
/// </summary>
|
||
protected void NextFrame()
|
||
{
|
||
// 如果没有精灵序列或序列为空，则直接返回
|
||
if (_sprites == null || _sprites.Length == 0) return;
|
||
|
||
// 增加帧索引
|
||
_currentFrameIndex++;
|
||
|
||
// 检查是否播放到精灵序列的末尾
|
||
if (_currentFrameIndex >= _sprites.Length)
|
||
{
|
||
// 如果是一次性播放模式
|
||
if (_isOneShot)
|
||
{
|
||
// 播放到最后一帧后停止，并保持在最后一帧
|
||
_currentFrameIndex = _sprites.Length - 1;
|
||
// 确保显示最后一帧
|
||
SetDisplaySprite(_sprites[_currentFrameIndex]);
|
||
// 调用一次性动画结束处理
|
||
FinishOneShotAnimation();
|
||
return; // 停止进一步处理
|
||
}
|
||
else
|
||
{
|
||
// 循环播放模式下，重置到第一帧
|
||
_currentFrameIndex = 0;
|
||
}
|
||
}
|
||
|
||
// 调用抽象方法更新显示组件的精灵
|
||
SetDisplaySprite(_sprites[_currentFrameIndex]);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 处理一次性动画播放结束时的逻辑。
|
||
/// </summary>
|
||
protected void FinishOneShotAnimation()
|
||
{
|
||
_isOneShot = false; // 结束一次性播放模式
|
||
_isPaused = true; // 动画暂停
|
||
gameObject.SetActive(false); // 隐藏当前游戏对象
|
||
// TODO: 如果有动画结束回调，可以在这里触发
|
||
// _onOneShotFinished?.Invoke();
|
||
}
|
||
|
||
/// <summary>
|
||
/// 设置动画的暂停状态。
|
||
/// </summary>
|
||
/// <param name="paused">如果为true，动画将暂停；如果为false，动画将继续播放。</param>
|
||
public void SetPaused(bool paused) => _isPaused = paused;
|
||
|
||
/// <summary>
|
||
/// 设置新的精灵序列用于动画播放。
|
||
/// 设置后动画将从第一帧开始播放，并重置暂停和一次性播放模式。
|
||
/// </summary>
|
||
/// <param name="newSprites">新的精灵数组。</param>
|
||
public void SetSprites(Sprite[] newSprites)
|
||
{
|
||
_sprites = newSprites;
|
||
|
||
// 如果有新的精灵数组且不为空，则立即显示第一帧
|
||
if (_sprites != null && _sprites.Length > 0)
|
||
{
|
||
_currentFrameIndex = 0; // 重置当前帧索引为第一帧
|
||
SetDisplaySprite(_sprites[_currentFrameIndex]); // 立即显示第一帧
|
||
}
|
||
else
|
||
{
|
||
SetDisplaySprite(null); // 如果没有精灵，则清空显示组件的精灵
|
||
gameObject.SetActive(false); // 如果没有精灵可显示，隐藏游戏对象
|
||
}
|
||
|
||
// 重置帧计时器，以确保从新精灵序列的开头开始播放
|
||
_frameTimer = 0f;
|
||
_isOneShot = false; // 设置新精灵时，取消一次性播放模式
|
||
_isPaused = false; // 默认开始播放
|
||
}
|
||
|
||
/// <summary>
|
||
/// 将动画状态恢复到初始设置。
|
||
/// 通常恢复到第一帧并暂停。
|
||
/// </summary>
|
||
public void Restore()
|
||
{
|
||
_currentFrameIndex = 0;
|
||
_isOneShot = false; // 重置时取消一次性播放模式
|
||
_isPaused = true; // 默认恢复后暂停
|
||
_frameTimer = 0f;
|
||
|
||
// 如果有精灵序列且不为空，则恢复到第一帧并尝试显示
|
||
if (_sprites != null && _sprites.Length > 0)
|
||
{
|
||
SetDisplaySprite(_sprites[_currentFrameIndex]); // 恢复到第一帧
|
||
// 如果游戏对象当前不活跃，则激活它使其可见
|
||
if (!gameObject.activeSelf)
|
||
{
|
||
gameObject.SetActive(true);
|
||
}
|
||
}
|
||
else
|
||
{
|
||
SetDisplaySprite(null); // 如果没有精灵，则清空显示
|
||
gameObject.SetActive(false); // 隐藏游戏对象
|
||
}
|
||
}
|
||
|
||
/// <summary>
|
||
/// 以一次性播放模式播放动画。
|
||
/// 动画将从第一帧播放到最后一帧，然后停止并隐藏游戏对象。
|
||
/// </summary>
|
||
public void PlayOneShot()
|
||
{
|
||
// 如果没有精灵序列或序列为空，则发出警告并隐藏游戏对象
|
||
if (_sprites == null || _sprites.Length == 0)
|
||
{
|
||
Debug.LogWarning("无法播放一次性动画：未分配精灵。", this);
|
||
gameObject.SetActive(false); // 没有精灵可显示，隐藏游戏对象
|
||
return;
|
||
}
|
||
|
||
// 重置动画状态为一次性播放模式
|
||
_isOneShot = true;
|
||
_isPaused = false;
|
||
_currentFrameIndex = 0;
|
||
_frameTimer = 0f;
|
||
|
||
// 确保游戏对象处于激活状态才能播放
|
||
if (!gameObject.activeSelf)
|
||
{
|
||
gameObject.SetActive(true);
|
||
}
|
||
|
||
// 立即显示第一帧
|
||
SetDisplaySprite(_sprites[_currentFrameIndex]);
|
||
}
|
||
|
||
/// <summary>
|
||
/// 设置动画的每秒帧数（FPS）。
|
||
/// FPS值将被限制在最小0.1，以防止除零或过小的帧率。
|
||
/// </summary>
|
||
/// <param name="newFPS">新的每秒帧数。</param>
|
||
public void SetFPS(float newFPS) => _fps = Mathf.Max(0.1f, newFPS);
|
||
|
||
/// <summary>
|
||
/// 设置动画暂停时显示的静态精灵。
|
||
/// </summary>
|
||
/// <param name="sprite">新的静态精灵。</param>
|
||
public void SetStaticSprite(Sprite sprite) => _staticSprite = sprite;
|
||
}
|
||
}
|