using System;
using UnityEngine;

namespace BaseGames.World.Map
{
    /// <summary>
    /// 玩家地图位置信息提供者接口。
    /// <para>
    /// MapPanel / MinimapHUD 依赖此接口而非具体组件，
    /// 支持替换实现（单人、多人、观察者模式、重播系统等场景）。
    /// </para>
    /// 通过 <see cref="BaseGames.Core.ServiceLocator"/> 注册与获取。
    /// </summary>
    public interface IPlayerPositionProvider
    {
        /// <summary>玩家当前所在房间 ID；未在任何已知房间内时为 null 或空字符串。</summary>
        string CurrentRoomId { get; }

        /// <summary>
        /// 玩家在当前房间内的归一化坐标（0~1，基于世界坐标精确插值）。
        /// 每帧更新，可用于平滑移动图标。
        /// </summary>
        Vector2 NormalizedPositionInRoom { get; }

        /// <summary>玩家进入新房间时触发（参数为新房间 ID）。</summary>
        event Action<string> OnRoomChanged;

        /// <summary>
        /// 将世界坐标转换为所属房间 ID 和房间内归一化坐标（0~1）。
        /// 用于在指定世界坐标处创建地图标记，无需手动计算格子坐标。
        /// 坐标不在任何已知房间内时返回 false。
        /// </summary>
        bool TryGetRoomAtWorldPos(Vector3 worldPos, out string roomId, out Vector2 normalizedPos);
    }
}