Дружній NPC та основи Pathfinding

using Godot;

/// <summary>
/// Точка pathfinding-графа платформера, а також початок/кінець знайденого шляху. Position зберігається
/// у ГЛОБАЛЬНИХ координатах, тому її можна напряму використовувати як ціль руху незалежно від того,
/// як TileMapLayer розташований відносно карти рівня.
/// </summary>
/// <remarks>
/// Це лише контейнер даних без логіки (окрім допоміжного GetFlagString()). Булеві прапорці описують
/// оточення точки: край платформи, стіна поруч, місце приземлення після падіння.
/// </remarks>
public class PointInfo
{
    /// <summary>Точка приземлення: місце на землі, куди потрапляє агент, якщо зійде з краю платформи і впаде.</summary>
    public bool IsFallTile;

    /// <summary>Лівий край платформи: під точкою є тайл, а зліва від нього тайла немає (обрив).</summary>
    public bool IsLeftEdge;

    /// <summary>Правий край платформи: під точкою є тайл, а справа від нього тайла немає (обрив).</summary>
    public bool IsRightEdge;

    /// <summary>Зліва від точки, на тій самій висоті, стоїть тайл (стіна блокує рух вліво).</summary>
    public bool IsLeftWall;

    /// <summary>Справа від точки, на тій самій висоті, стоїть тайл (стіна блокує рух вправо).</summary>
    public bool IsRightWall;

    /// <summary>
    /// true - це не точка графа, а позиційна точка: початок або кінець шляху, створені з реальної
    /// позиції агента чи цілі (з PointID = -10000).
    /// </summary>
    public bool IsPositionPoint;

    /// <summary>
    /// Ідентифікатор точки в AStar2D-графі. Для позиційних точок (IsPositionPoint) дорівнює -10000,
    /// бо вони до графа не додаються.
    /// </summary>
    public long PointID;

    /// <summary>Координати точки у глобальному (world) просторі Godot.</summary>
    public Vector2 Position;

    /// <summary>Порожній конструктор - дозволяє створити об'єкт через ініціалізатор об'єкта (object initializer).</summary>
    public PointInfo() { }

    /// <summary>
    /// Основний конструктор: створює точку з ідентифікатором та позицією. Усі прапорці залишаються
    /// false і виставляються окремо під час побудови графа.
    /// </summary>
    public PointInfo(long pointId, Vector2 position)
    {
        PointID = pointId;
        Position = position;
    }

    /// <summary>
    /// Повертає короткий текстовий опис активних прапорців для debug-логів.
    /// </summary>
    /// <returns>
    /// Рядок із літер: "L" - лівий край, "R" - правий край, "lw" - ліва стіна, "rw" - права стіна,
    /// "F" - точка приземлення, "P" - позиційна точка. Приклад: "LrwF" - лівий край + права стіна +
    /// точка приземлення. Якщо жоден прапорець не виставлений - порожній рядок.
    /// </returns>
    public string GetFlagString()
    {
        var s = new System.Text.StringBuilder(); // StringBuilder дозволяє ефективно збирати рядок із частин
        if (IsLeftEdge) s.Append('L');
        if (IsRightEdge) s.Append('R');
        if (IsLeftWall) s.Append("lw");      // Двосимвольний, щоб не плутати з 'L'
        if (IsRightWall) s.Append("rw");     // Двосимвольний, щоб не плутати з 'R'
        if (IsFallTile) s.Append('F');
        if (IsPositionPoint) s.Append('P');
        return s.ToString();
    }
}

using Godot;
using System.Collections.Generic;

/// <summary>
/// Базовий клас карти рівня. Створює PlatformPathfinder на основі TileMapLayer, надає його іншим
/// нодам через <see cref="IPlatformPathfinder"/> і (за бажанням) малює debug-граф. Конкретні рівні
/// (Level1Map, Level2Map, ...) успадковують цей клас і зазвичай не потребують власного коду -
/// щонайбільше налаштування, специфічного для рівня, у методі <see cref="OnPathfindingReady"/>.
/// </summary>
public partial class LevelMapBase : Node2D, IPlatformPathfinder
{
    [Export]
    public bool ShowDebugGraph = true;                  // Чи малювати точки та лінії графа
    [Export]
    public int JumpDistance = 5;                        // Макс. горизонтальна дальність стрибка (у ТАЙЛАХ) - для перестрибування прірви
    [Export]
    public int JumpHeight = 4;                          // Макс. висота стрибка між точками (у тайлах, не в пікселях)
    [Export]
    public int StepDistance = 2;                        // Макс. горизонтальна відстань (у тайлах) для ЗВИЧАЙНОГО кроку (сходинки, виступи)
    [Export]
    public int JumpHeadroom = 2;                        // Мін. кількість вільних тайлів над точками відриву та приземлення стрибка
    [Export]
    public NodePath NavigationLayerPath = "ForegroundNav"; // Дочірній TileMapLayer, за яким будується граф

    private static readonly PackedScene graphPointScene =
        ResourceLoader.Load<PackedScene>("res://Scenes/GraphPoint/GraphPoint.tscn"); // Сцена візуальної debug-точки

    private PlatformPathfinder _pathfinder;

    public override void _EnterTree()
    {
        // Реєструємось саме тут, а не в _Ready: Godot викликає _EnterTree для всього піддерева
        // ще до першого _Ready, тож агенти гарантовано знайдуть групу незалежно від порядку нодів
        // у сцені.
        AddToGroup(IPlatformPathfinder.GroupName);
    }

    public override void _Ready()
    {
        var navigationLayer = GetNodeOrNull<TileMapLayer>(NavigationLayerPath);
        if (navigationLayer == null)
        {
            GD.PushError($"{Name}: no TileMapLayer found at '{NavigationLayerPath}' - pathfinding graph cannot be built.");
            return;
        }

        _pathfinder = new PlatformPathfinder(navigationLayer, JumpDistance, JumpHeight, StepDistance, JumpHeadroom, ShowDebugGraph);
        _pathfinder.Build();

        if (ShowDebugGraph)
        {
            SpawnDebugVisuals();
            QueueRedraw(); // Запускає один виклик _Draw, який намалює закешовані debug-лінії
        }

        OnPathfindingReady();
    }

    /// <summary>
    /// Перевизначте у похідному класі рівня, щоб виконати налаштування, специфічне для рівня, одразу
    /// після побудови pathfinding-графа. Викликається в кінці _Ready.
    /// </summary>
    protected virtual void OnPathfindingReady()
    {
    }

    public override void _Draw()
    {
        if (!ShowDebugGraph || _pathfinder == null) { return; }

        // Лише відтворюємо закешовані відрізки - сам граф уже побудований.
        foreach (var (a, b, color) in _pathfinder.DebugLines)
        {
            DrawLine(ToLocal(a), ToLocal(b), color);
        }
    }

    private void SpawnDebugVisuals()
    {
        foreach (var spec in _pathfinder.VisualPointSpecs)
        {
            // Створюємо нову візуальну точку. Коренем сцени GraphPoint має бути Node2D
            // (або його нащадок, наприклад Sprite2D), бо позицію задаємо через GlobalPosition.
            var visualPoint = graphPointScene.Instantiate<Node2D>();

            if (spec.Color != null)
            {
                visualPoint.Modulate = (Color)spec.Color;
            }
            if (spec.Scale != 1.0f && spec.Scale > 0.1f)
            {
                visualPoint.Scale = new Vector2(spec.Scale, spec.Scale);
            }

            AddChild(visualPoint);

            visualPoint.ZIndex = 100;

            visualPoint.GlobalPosition = _pathfinder.GlobalFromTile(spec.Tile);
        }
    }

    public Stack<PointInfo> GetPlatform2DPath(Vector2 startGlobalPos, Vector2 endGlobalPos)
        => _pathfinder?.GetPlatform2DPath(startGlobalPos, endGlobalPos) ?? new Stack<PointInfo>();

    public Vector2I GlobalToTile(Vector2 globalPosition)
        => _pathfinder?.GlobalToTile(globalPosition) ?? Vector2I.Zero;
}

using Godot;

/// <summary>
/// Базовий клас ігрових сутностей, які шукають шлях і мають анімації. Додає до
/// PathfindingAgent2D керування анімаціями (idle/walk/spawn/die), стани життєвого циклу
/// (поява, смерть, видалення) та перевизначення _PhysicsProcess, яке вимикає pathfinding,
/// поки сутність не в стані "ходьби". Ціль за замовчуванням - нод із групи TargetGroupName
/// (або TargetOverride, якщо його задано).
/// </summary>
public abstract partial class PathfindingGameEntity2D : PathfindingAgent2D
{
    [ExportGroup("Animation")]
    [Export] public string IdleAnimName = "idle";
    [Export] public string WalkAnimName = "walk";
    [Export] public string SpawnAnimName = "undie";
    [Export] public string DieAnimName = "die";

    [ExportGroup("Targeting")]
    // Явна ціль для конкретного екземпляра (наприклад, NPC, що йде за іншим NPC, а не за гравцем).
    // Якщо задана - завжди має пріоритет над пошуком за групою. null означає
    // "шукати за групою", а не "цілі немає".
    [Export] public Node2D TargetOverride;
    [Export] public string TargetGroupName = "Player";

    protected AnimatedSprite2D AnimSprite { get; private set; }

    protected bool IsSpawning { get; set; }
    protected bool IsDying { get; private set; }
    protected bool IsDead { get; private set; }

    /// <summary>
    /// Нод, до якого сутність зараз прямує. Обчислюється щоразу заново, а не кешується, тому
    /// призначення <see cref="TargetOverride"/> під час гри (або зміна складу групи) діє одразу.
    /// Відсутність цілі - допустимий стан: код, що читає цю властивість, трактує null як
    /// "зараз нічого робити".
    ///
    /// Для TargetOverride окремо перевіряється <see cref="IsInstanceValid"/>: якщо нод-ціль
    /// видалили, C#-посилання на нього залишається не-null, але будь-який доступ кидає
    /// ObjectDisposedException. Тому видалена ціль просто замінюється пошуком за групою.
    /// Із груп Godot видалений нод прибирає сам, там додаткова перевірка не потрібна.
    /// </summary>
    protected Node2D TargetRef =>
        TargetOverride != null && IsInstanceValid(TargetOverride)
            ? TargetOverride
            : GetTree().GetFirstNodeInGroup(TargetGroupName) as Node2D;

    /// <summary>True, поки сутність у стані, який призупиняє звичайний рух за шляхом.</summary>
    protected virtual bool MovementSuspended => IsSpawning || IsDying || IsDead;

    protected override void OnAgentReady()
    {
        AnimSprite = GetNodeOrNull<AnimatedSprite2D>("AnimatedSprite2D");
        if (AnimSprite == null)
        {
            GD.PushError(
                $"{Name}: Required child node 'AnimatedSprite2D' (type: AnimatedSprite2D) not found. " +
                "Add it as a child of this node. Entity is disabled.");
            DisableEntity();
            return;
        }

        AnimSprite.AnimationFinished += OnAnimationFinished;
        StartSpawning();
    }

    /// <summary>Пункт призначення за замовчуванням - поточна позиція <see cref="TargetRef"/>.</summary>
    protected override Vector2? GetDestination() => TargetRef?.GlobalPosition;

    public override void _PhysicsProcess(double delta)
    {
        if (IsDead) { return; }

        if (MovementSuspended)
        {
            // Pathfinding пропускаємо, але гравітацію застосовуємо, щоб сутність стояла на землі.
            Vector2 velocity = Velocity;
            if (!IsOnFloor())
            {
                velocity.Y += Gravity * (float)delta;
            }
            velocity.X = 0f;
            Velocity = velocity;
            MoveAndSlide();
            return;
        }

        base._PhysicsProcess(delta);
        UpdateMovementAnimation();
    }

    /// <summary>Перемикає анімацію між idle та walk залежно від поточного руху.</summary>
    protected virtual void UpdateMovementAnimation()
    {
        bool moving = CurrentTarget != null || Mathf.Abs(Velocity.X) > 1f;

        if (Mathf.Abs(Velocity.X) > 1f)
        {
            AnimSprite.FlipH = Velocity.X < 0f;
        }

        if (moving)
        {
            if (AnimSprite.Animation != WalkAnimName)
            {
                AnimSprite.Play(WalkAnimName);
            }
        }
        else if (AnimSprite.Animation != IdleAnimName)
        {
            AnimSprite.Play(IdleAnimName);
        }
    }

    /// <summary>Запускає анімацію появи.</summary>
    protected virtual void StartSpawning()
    {
        IsSpawning = true;
        AnimSprite.Play(SpawnAnimName);
    }

    /// <summary>Запускає анімацію смерті.</summary>
    protected virtual void StartDying()
    {
        IsDying = true;
        StopPathfindTimer();
        AnimSprite.Play(DieAnimName);
    }

    /// <summary>Обробляє завершення анімацій, якими керує цей клас (поява, смерть).</summary>
    protected virtual void OnAnimationFinished()
    {
        string currentAnim = AnimSprite.Animation;

        if (currentAnim == DieAnimName && IsDying)
        {
            Cleanup();
            return;
        }

        if (currentAnim == SpawnAnimName && IsSpawning)
        {
            IsSpawning = false;
            StartPathfindTimer();
            AnimSprite.Play(IdleAnimName);
            return;
        }
    }

    /// <summary>Фінальне прибирання перед видаленням сутності з дерева.</summary>
    protected virtual void Cleanup()
    {
        IsDead = true;
        StopPathfindTimer();
        SetPhysicsProcess(false);
        QueueFree();
    }

    /// <summary>
    /// Вимикає сутність після помилки налаштування: вона стає неактивною й невидимою,
    /// але лишається у дереві сцени, тож її можна оглянути в редакторі.
    /// </summary>
    protected void DisableEntity()
    {
        SetProcess(false);
        SetPhysicsProcess(false);
        Visible = false;
    }
}

using Godot;

/// <summary>
/// Базовий клас для дружніх сутностей (NPC), які просто йдуть за ціллю
/// (<see cref="PathfindingGameEntity2D.TargetRef"/>): підходять, зупиняються на комфортній відстані
/// й знову рушають, коли ціль відійде далеко. Бойової поведінки тут немає - лише рух.
/// </summary>
public abstract partial class PathfindingGameFriendly2D : PathfindingGameEntity2D
{
    [ExportGroup("Follow")]
    [Export] public float StopDistance = 40f;   // На цій відстані та ближче NPC зупиняється

    // NPC знову рушає, лише коли ціль віддалиться більше ніж на ResumeDistance (> StopDistance).
    // Без цього проміжку ціль, що повільно рухається або коливається біля межі StopDistance,
    // змушувала б NPC раз у раз перемикатися між станами "зупинитись" і "іти".
    [Export] public float ResumeDistance = 60f;

    private bool isWaiting;

    /// <summary>
    /// Поки NPC чекає, стоїть на землі й у нього не лишилось шляху (CurrentTarget == null), фізику
    /// не обробляємо взагалі - рахувати нічого. Умова IsOnFloor() не дає "заморозити" NPC посеред
    /// стрибка чи падіння, а CurrentTarget == null - додатковий запобіжник. Прапорець isWaiting
    /// виставляється під час першого ж перерахунку шляху, де ціль опинилась у межах StopDistance.
    /// </summary>
    public override void _PhysicsProcess(double delta)
    {
        if (isWaiting && CurrentTarget == null && IsOnFloor())
        {
            return;
        }
        base._PhysicsProcess(delta);
    }

    /// <summary>
    /// Повертає позицію цілі, а коли NPC уже достатньо близько й вирішив зупинитись - null,
    /// щоб система руху просто завершила шлях, а не "дотискала" останні пікселі до цілі.
    /// </summary>
    protected override Vector2? GetDestination()
    {
        Vector2? targetPosition = base.GetDestination();
        if (targetPosition == null)
        {
            isWaiting = false;
            return null;
        }

        float distance = GlobalPosition.DistanceTo(targetPosition.Value);
        bool wasWaiting = isWaiting;

        if (isWaiting)
        {
            if (distance > ResumeDistance) { isWaiting = false; }
        }
        else if (distance <= StopDistance)
        {
            isWaiting = true;
            // Одразу обриваємо поточний шлях. Інакше NPC дійшов би до кінця вже побудованого
            // шляху (найчастіше він складається з єдиної точки прямо в позиції цілі) і
            // зупинився б упритул до неї, хоч би яким великим було StopDistance.
            ClearCurrentPath();
        }

        if (VerboseLogging && isWaiting != wasWaiting)
        {
            GD.Print($"{Name}: {(isWaiting ? "stopping" : "resuming")} (distance {distance:F1}, StopDistance {StopDistance}, ResumeDistance {ResumeDistance}).");
        }

        return isWaiting ? null : targetPosition;
    }
}