using UnityEngine;
using Unity.Cinemachine;

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>运行时设置跟随目标（Player/CameraFollowTarget），激活区域时自动同步到专属 VCam。</summary>
        void SetFollowTarget(Transform followTarget);

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

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

        /// <summary>
        /// 平滑过渡视野尺寸（可视半高，世界单位）。<paramref name="duration"/> = 0 时瞬间切换。
        /// 透视相机下自动换算为 FOV，与正交相机的 OrthographicSize 语义等价。
        /// 适用于 Boss 战拉远、特殊演出室拉近等场景。
        /// </summary>
        void SetLensSize(float visibleHalfHeight, float duration = 0f);

        /// <summary>
        /// 进入过场模式，激活指定 VCam（优先级高于所有区域相机），Brain 自动混合。
        /// VCam 的 Follow / LookAt / Lens 由设计者在 Inspector 中配置，接口不强制覆写。
        /// </summary>
        void EnterCutsceneMode(CinemachineCamera cutsceneCamera);

        /// <summary>
        /// 退出过场模式，撤销过场 VCam 的优先级，Brain 自动混合回当前区域相机。
        /// </summary>
        void ExitCutsceneMode();

        /// <summary>
        /// 通知相机系统玩家的面朝方向，使方向感知偏置立即响应。
        /// 由 PlayerController 在精灵翻转时调用（<c>OnFlip</c>）。
        /// direction: +1 = 朝右，-1 = 朝左，0 = 清除外部输入（回退到速度估算）。
        /// </summary>
        void SetPlayerFacing(int direction);
    }
}