using System.Collections;

namespace BaseGames.World
{
    /// <summary>
    /// 房间流式加载管理器接口。
    /// <para>
    /// <see cref="RoomController"/> 在 Start() 中通过 ServiceLocator 查找此接口，
    /// 若存在则将自身注册，由管理器控制相机初始化时机（避免 Dormant 房间抢占相机）。
    /// 若不存在（非流式模式）则退回原有行为。
    /// </para>
    /// <para>
    /// <see cref="Streaming.TransitionDirector"/> 通过此接口操作流式管理器，
    /// 完全解耦于具体实现类，便于测试和替换。
    /// </para>
    /// </summary>
    public interface IRoomStreamingManager
    {
        /// <summary>房间加载完成后，RoomController.Start() 调用此方法将自身注册到流式管理器。</summary>
        void RegisterRoomController(RoomController controller);

        /// <summary>当前处于 Active 状态的房间 ID。</summary>
        string CurrentRoomId { get; }

        /// <summary>
        /// 立即将指定房间加入预加载队列。
        /// 若房间已加载或已在队列中则忽略。
        /// 用于快速传送预热、玩家即将触碰的门口等主动预加载场景。
        /// </summary>
        void PreloadRoom(string roomId);

        /// <summary>
        /// 查询目标房间是否已处于 Dormant 状态，可立即执行无等待的激活。
        /// </summary>
        bool IsRoomDormant(string roomId);

        /// <summary>
        /// 激活目标房间（Dormant → Active）并将前一个房间置于冷却状态。
        /// 目标房间必须已处于 Dormant 状态。由 <see cref="Streaming.TransitionDirector"/> 在过渡时调用。
        /// </summary>
        IEnumerator ActivateRoomCoroutine(string targetRoomId, SpawnContext context);

        /// <summary>
        /// 若房间尚未加载则先加载，完成后激活。
        /// 用于非流式冷启动路径（如游戏初始化、快速传送落地）。
        /// </summary>
        IEnumerator LoadAndActivateRoomCoroutine(string roomId, SpawnContext context);

        /// <summary>
        /// 获取指定房间的当前流式状态。
        /// 若房间不在流式系统中（未加载或 ID 不存在），返回 <see cref="RoomState.Unloaded"/>。
        /// </summary>
        RoomState GetRoomState(string roomId);
    }
}