using UnityEngine;

namespace BaseGames.Camera
{
    /// <summary>
    /// 相机服务接口。通过 <c>ServiceLocator.GetOrDefault&lt;ICameraService&gt;()</c> 访问。
    /// </summary>
    public interface ICameraService
    {
        /// <summary>
        /// 切换到目标相机区域。
        /// <paramref name="priority"/> 用于触发区域优先级仲裁：
        /// 仅当 priority ≥ 当前激活优先级时才执行切换。
        /// 传 0（默认）时始终切换（适合 RoomController 初始化或场景加载）。
        /// <para>
        /// <paramref name="instantCut"/> = true 时使用即时切断混合（房间入口硬切：相机直接跳到目标位置、无过渡动画），
        /// 同时重置窥视偏移，避免旧房间的窥视偏移残留到新房间。
        /// 适合通过门传送后的首次相机初始化；区域内触发区域切换应保持默认 false。
        /// </para>
        /// </summary>
        void SwitchArea(CameraArea area, int priority = 0, bool instantCut = false);

        /// <summary>
        /// 释放 <paramref name="releasedArea"/>（通常由 CameraTriggerZone.OnTriggerExit 调用）。
        /// 若 <paramref name="releasedArea"/> 正是当前激活区域，切换到 <paramref name="fallback"/>；
        /// 否则无操作。
        /// </summary>
        void ReleaseArea(CameraArea releasedArea, CameraArea fallback);

        /// <summary>为全局双 VCam 设置跟随目标（Player/CameraFollowTarget）。</summary>
        void SetFollowTarget(Transform followTarget);

        /// <summary>触发屏幕抖动（指定速度矢量）。</summary>
        void TriggerImpulse(Vector3 velocity);

        /// <summary>触发屏幕抖动（向下方向）。</summary>
        void TriggerImpulse(float strength = 0.3f);

        /// <summary>
        /// 平滑过渡正交相机尺寸。<paramref name="duration"/> = 0 时瞬间切换。
        /// 适用于 Boss 战拉远、特殊演出室拉近等场景。
        /// </summary>
        void SetLensSize(float orthographicSize, float duration = 0f);
    }
}