using System;
using UnityEngine;

namespace BaseGames.Enemies
{
    /// <summary>
    /// 连接段穿越能力接口（架构 07_EnemyModule §5.2）。
    ///
    /// 实现此接口的组件（EnemyAbilityBase 子类 / EnemyMovement 等）可接管特定
    /// NavLink 类型的穿越逻辑，包括动画播放、物理推进、时序控制，完全封装在能力内部。
    ///
    /// 注册：EnemyNavAgent.Awake 自动发现当前 GameObject 上实现此接口的所有组件。
    ///
    /// ────────────────────────────────────────────────────────────────────
    /// 如何扩展自定义 LinkType（超出 PB2d 内置 6 种之外）：
    ///   1. 在 Edit → Project Settings → PathBerserker2d → NavLink Type Names 追加名字
    ///      （索引从 6 开始，例如 index 6 = "wallhug"）
    ///   2. 在 <see cref="NavLinkType"/> 枚举追加同名条目（ParseLinkType 会字符串匹配）
    ///   3. 实现 INavLinkHandler，在 HandledLinkTypes 中声明该枚举值
    ///   4. EnemyNavAgent 会自动将其从 TransformBasedMovement 剥离并委托给能力
    ///
    /// 如何使用 NavTag 控制地形通行性：
    ///   - 在 PathBerserker2dSettings 中为各 NavSurface 配置 NavTag（如"water"、"lava"）
    ///   - 通过 NavAgent.GetNavTagTraversalMultiplier(int) 配置或查询通行成本（≤0 = 禁止）
    ///   - 无需在此接口扩展，PB2d 在寻路阶段自动过滤
    /// ────────────────────────────────────────────────────────────────────
    /// </summary>
    public interface INavLinkHandler
    {
        /// <summary>该处理器负责的所有连接段类型（允许一个组件处理多种类型）。</summary>
        NavLinkType[] HandledLinkTypes { get; }

        /// <summary>
        /// 运行时可行性检查：能否穿越此具体连接段（距离/高度/当前状态等）。
        /// 返回 false 时 EnemyNavAgent 记录警告并让 TransformBasedMovement 兜底。
        /// </summary>
        bool CanHandleLink(NavLinkType type, Vector2 linkStart, Vector2 linkEnd);

        /// <summary>
        /// 开始穿越。能力自行驱动动画 + 物理。
        /// <b>onComplete 必须且只能调用一次</b>；未调用将导致 NavAgent 永远卡在连接段。
        /// </summary>
        void BeginLinkTraversal(NavLinkType type, Vector2 linkStart, Vector2 linkEnd, Action onComplete);

        /// <summary>
        /// 强制中断穿越（敌人死亡 / 被击飞 / 场景切换时调用）。
        /// 调用后不得再调用 onComplete。
        /// </summary>
        void AbortLinkTraversal();
    }
}