Reconnection

//A nullable FVector, so a vector can be meaningfully absent instead of overloading
//FVector::ZeroVector or a sentinel like (MAX_flt, MAX_flt, MAX_flt) to mean "none".
//Null is the default state.
//
//The API mirrors FVector. Three rules cover the whole surface:
//  - anything FVector returns as a vector comes back as an FPRVector that is null
//    if any operand was null
//  - anything FVector returns as a scalar comes back as a TOptional<double> that is
//    unset if any operand was null
//  - anything FVector answers with a bool answers false when an operand is null,
//    except Equals and operator==, which treat two nulls as equal and a null as
//    never equal to a set vector
//
//Mutators do nothing while null, so a null vector cannot be half-written into a set
//one. Construction from FVector is implicit, so every function also accepts a plain
//FVector.
USTRUCT( BlueprintType, meta = ( HasNativeMake = "...MakePRVector", HasNativeBreak = "...BreakPRVector" ) )
struct PROJECTRECONNECTION_API FPRVector
{
    GENERATED_BODY()
public:
    //The one constant FVector has no counterpart for.
    static FPRVector Null();

    bool IsSet() const;
    bool IsNull() const;

    //Asserts when null. Prefer Get( Default ) or TryGet() unless the value is
    //already known to be set.
    const FVector& GetValue() const;
    const FVector& Get( const FVector& DefaultValue ) const;

    //Leaves OutValue untouched when null.
    bool TryGet( FVector& OutValue ) const;

    //Component access returns TOptional rather than a reference. FVector's
    //reference-returning overloads have no counterpart here, because handing out a
    //reference into a null vector would let a caller write one component and leave
    //the other two undefined.
    TOptional<double> GetX() const;
    TOptional<double> Component( int32 Index ) const;

    //Vector in, vector out: null if either operand is null.
    FPRVector operator+( const FPRVector& V ) const;
    FPRVector Cross( const FPRVector& V ) const;

    //Vector in, scalar out: unset if either operand is null.
    TOptional<double> Dot( const FPRVector& V ) const;
    TOptional<double> Size() const;
    static TOptional<double> Dist( const FPRVector& V1, const FPRVector& V2 );

    //Two nulls are equal. A null never equals a set vector, whatever the set one holds.
    bool operator==( const FPRVector& V ) const;
    bool Equals( const FPRVector& V, double Tolerance = UE_KINDA_SMALL_NUMBER ) const;

    //ResultIfZero defaults to null, so an unnormalizable vector reports itself as one
    //rather than quietly reporting itself as zero.
    FPRVector GetSafeNormal( double Tolerance = UE_SMALL_NUMBER,
                             const FPRVector& ResultIfZero = FPRVector() ) const;

private:
    //Only meaningful when bIsSet, and kept zeroed while null so serialized data
    //stays stable.
    UPROPERTY( EditAnywhere, BlueprintReadOnly, meta = ( EditCondition = "bIsSet" ) )
    FVector Value = FVector::ZeroVector;

    UPROPERTY( EditAnywhere, BlueprintReadOnly, meta = ( DisplayName = "Has Value" ) )
    bool bIsSet = false;
};
                        

//Blueprints have no unset float and no TOptional, so the struct's C++ surface cannot
//map one to one. Two shapes cover the gap: scalar results come back as a bool plus an
//out parameter, and functions that mutate the vector take it as a ref parameter.
//
//Only the members Blueprints genuinely cannot represent are missing: GetValue (it
//asserts on null, so Get Or Default and Try Get stand in), ToOptional and FromOptional,
//the compound assignment operators (a node output feeding a Set does the same job),
//and NetSerialize and GetTypeHash, which the engine calls directly.
UCLASS()
class PROJECTRECONNECTION_API UPRVectorLibrary : public UBlueprintFunctionLibrary
{
    GENERATED_BODY()
public:
    //Registered as the struct's NativeMakeFunc and NativeBreakFunc, so the standard
    //Make and Break nodes work on FPRVector exactly as they do on FVector.
    static FPRVector MakePRVector( FVector Value );
    static void BreakPRVector( const FPRVector& PRVector, FVector& Value, bool& bHasValue );

    //BlueprintAutocast, so a plain FVector pin connects straight into an FPRVector pin.
    static FPRVector Conv_VectorToPRVector( FVector Value );
};

//Paired with the library so a graph can branch on null as execution flow rather than
//threading a bool through every downstream node.
UENUM( BlueprintType )
enum class EPRVectorBranch : uint8
{
    HasValue,
    Null
};
                        

//The first real adoption site. Click to move needs to answer "has the player chosen a
//destination yet?" on every tick of a held input. The previous shape was an FVector
//plus a separate bHasDestination flag, which is two things to keep in agreement.
class PROJECTRECONNECTION_API AExplorationPlayerController : public APlayerController
{
protected:
    void HandleSetDestinationStarted();
    void HandleSetDestinationTriggered();
    void HandleSetDestinationReleased();

    //Runs a cursor trace and writes the hit location, leaving the destination null
    //when the trace lands on nothing.
    void UpdateDestinationFromCursor();

    //Null until a cursor trace lands somewhere, so "no destination yet" is part of the
    //value rather than a separate flag that can drift out of step with it.
    FPRVector CachedDestination;

    float FollowTime = 0.0f;
};
                        

# One type per file. Every enum, struct, class, and function library gets its own
# header, including a helper enum that exists only for the type beside it.
#
# No Public/ and Private/ split. A header and its .cpp sit next to each other in a
# folder named for the feature. The module root is the include root.

Source/ProjectReconnection/
    Math/
        PRVector.h            # the struct
        PRVector.cpp
        PRVectorBranch.h      # the enum it is used with
        PRVectorLibrary.h     # the Blueprint function library for it
        PRVectorLibrary.cpp
    Player/
        ExplorationPlayerController.h
        ExplorationPlayerController.cpp
    UI/
        Subsystem/
            UIMenuManager.h
            UIMenuManager.cpp

# This layout depends on PublicIncludePaths.Add( ModuleDirectory ) in
# ProjectReconnection.Build.cs. Unreal Build Tool only adds the module root
# automatically through its legacy include paths, which modern build settings turn
# off, so removing that line breaks every include in the module.
#
# Include your own headers by their path from the module root:
#   #include "Math/PRVector.h"        yes
#   #include "../Math/PRVector.h"     no
                        

//Keep Unreal's type prefixes (F, U, A, E, I). On top of that:
//
//Types that do not extend an Unreal class are prefixed PR. Plain structs, plain
//classes, and enums we author are project types and carry the project prefix.
struct FPRVector { ... };               //ours, no Unreal base
enum class EPRVectorBranch : uint8 {};  //ours

//Types that extend an Unreal class do not take the PR prefix. They are named for
//what they are.
class UUIMenuManager : public UEnhancedInputLocalPlayerSubsystem { ... };
class AExplorationPlayerController : public APlayerController { ... };

//The one place PR appears on an Unreal-derived class is when it is part of the name
//of the project type the class serves, not a prefix on the class itself:
//UPRVectorLibrary is the function library for FPRVector.

//Comments are written //words here, with no space after the slashes. This applies to
//documentation comments too; a multi-line comment is several // lines, never a block
//comment.
                        

# WBP_Objectives

- Path: `/Game/UI/Widgets/WBP_Objectives.WBP_Objectives`
- Parent: `UserWidget`

## Variables

- **Objective**: `text` = `"Get to the Chopper!"` - editable

## Functions

### UpdateObjectiveText()

    Set Text  (Text <- Get Objective, self <- Get ObjectiveText)

## Graphs

### EventGraph (Ubergraph)

    Event Construct
    Event Pre Construct
    UpdateObjectiveText
    Event Tick

## Asset dependencies

- `/Game/UI/Widgets/WBP_Objectives.WBP_Objectives_C`
                        

# For every Content/**/BP_Thing.uasset there is a Content/**/BP_Thing.bp.md committed
# beside it. Git diffs the Markdown; GitHub renders it in the PR.
#
#   Content/TurnManagerAssets/
#     BP_CombatManager.uasset      binary, unreviewable
#     BP_CombatManager.bp.md       what a reviewer actually reads

git add Content/TurnManagerAssets/BP_CombatManager.uasset
git commit -m "combat: end turn when enemies are cleared"
  [bp-digest] serializing 1 Blueprint(s) via Unreal (this takes a minute)
  [bp-digest] updated 1 digest(s)
  [bp-digest] staged them

# Staging a Blueprint regenerates and stages its digest in the same commit, so the two
# can never disagree. Commits that touch no Blueprints skip Unreal entirely and cost
# about 0.3s: the generator reads .uasset headers directly to decide whether starting
# the editor is worth it.
#
# The hook also declines to run mid-merge, mid-rebase, mid-cherry-pick, and mid-revert.
# Those commits are resolving history that already exists, and rewriting a tracked file
# underneath them would fight the operation.

python Tools/BlueprintDigest/generate.py --staged --stage   # what the hook runs
python Tools/BlueprintDigest/generate.py --all              # rebuild everything
BP_DIGEST_SKIP=1 git commit ...                             # skip for one commit
                        

# Two jobs before a commit is created:
#   1. Reconcile .uvc_timeclock.json with origin/main so parallel sessions from
#      different teammates merge instead of clobbering each other.
#   2. Regenerate the readable .bp.md digest beside any staged Blueprint, so
#      pull requests show what changed instead of "Binary file differs".
#
# Escape hatches:
#   UVC_TIMECLOCK_SKIP=1 git commit ...      skip the timeclock merge
#   UVC_TIMECLOCK_NO_FETCH=1 git commit ...  merge against the cached ref, no network
#   BP_DIGEST_SKIP=1 git commit ...          skip Blueprint digests
#   git commit --no-verify ...               skip all hooks

# Git for Windows ships its own sh but no python, so the hook probes the usual names
# rather than assuming an interpreter is on PATH. If none is found it warns and exits
# clean, because a missing interpreter should not block a teammate's commit.
for candidate in python3 python py; do
    if command -v "$candidate" >/dev/null 2>&1; then
        PYTHON="$candidate"
        break
    fi
done
                        

// Base class for every combatant. Both player characters and enemies
// inherit from AFighter so UTurnManager can drive them identically.
UCLASS()
class RECONNECTION_API AFighter : public AActor
{
    GENERATED_BODY()
public:
    AFighter();

    // Whether it is currently this fighter's turn.
    // Set true by UTurnManager before calling StartTurn().
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stored Variables")
    bool bIsTurn;

    // Rolled once at combat start; UTurnManager sorts descending
    // so the highest score acts first (classic D&D initiative order).
    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Stored Variables")
    int32 InitiativeScore;

    // Sets bIsTurn = true and broadcasts the OnStartTurn delegate
    // so Blueprint can respond with UI highlights, camera moves, etc.
    UFUNCTION(BlueprintCallable, Category="Stored Functions")
    void StartTurn();

    // Sets bIsTurn = false and broadcasts OnEndTurn,
    // which UTurnManager listens to in order to advance the queue.
    UFUNCTION(BlueprintCallable, Category="Stored Functions")
    void EndTurn();

    // Routes a typed damage value to the target's ReceiveDamage().
    // Type string ("Physical", "Magic", etc.) allows resistances later.
    UFUNCTION(BlueprintCallable, Category="Stored Functions")
    void SendDamage(float Damage, const FString& Type, AFighter* Target);

    // Applies incoming damage. Virtual so UEnemy can override
    // to cache LastDamageReceived for block utility scoring.
    UFUNCTION(BlueprintCallable, Category="Stored Functions")
    virtual void ReceiveDamage(float Damage, const FString& Type);

protected:
    virtual void BeginPlay() override;
};
                        

// Constructor: initializes bIsTurn = false and InitiativeScore = 0.
// PrimaryActorTick is disabled — all event flow is delegate-driven.
AFighter::AFighter();

// Sets bIsTurn = true and logs entry.
// UTurnManager calls this after advancing CurrentTurnIndex.
void AFighter::StartTurn();

// Sets bIsTurn = false and logs exit.
// Broadcasts OnEndTurn so UTurnManager knows to call NextTurn().
void AFighter::EndTurn();

// Logs the outgoing damage type and amount,
// then calls Target->ReceiveDamage() to apply the value.
void AFighter::SendDamage(float Damage, const FString& Type, AFighter* Target);

// Base implementation logs received damage.
// UEnemy overrides this to also cache LastDamageReceived
// so GetBlockUtility() can score based on recent incoming hits.
void AFighter::ReceiveDamage(float Damage, const FString& Type);
                        

// Generates a hit value by rolling 1d20 and adding BaseAttack + AttackBuff.
// Higher result = better chance to overcome the target's defense.
int UFighter::RollToHit();

// Returns BaseDefense + DefenseBuff.
// The target's armor class equivalent — what an attacker must beat to land a hit.
float UFighter::GetDefense();

// Full attack action sequence:
//   1. Calls RollToHit() and compares against Target->GetDefense().
//   2. On a hit: calls RollDamage() for a randomized value (MinDamage..MaxDamage + DamageBuff),
//      passes it to SendDamage(), then broadcasts OnHitAttack for Blueprint VFX/SFX hooks.
//   3. On a miss: broadcasts OnHitMiss for miss animations and feedback.
//   4. Always calls EndTurn() to return control to UTurnManager.
void UFighter::Attack(UFighter* Target);

// Returns a random float in [MinDamage, MaxDamage] plus DamageBuff.
// Called inside Attack() after a successful roll-to-hit check.
float UFighter::RollDamage();

// Blueprint-native event: applies incoming damage with reduction.
//   1. Subtracts DamageReduction from Damage for an effective hit value.
//   2. Clamps CurrentHealth to [0, MaxHealth].
//   3. If CurrentHealth reaches 0, calls Die() and broadcasts OnDeath.
void UFighter::ReceiveDamage_Implementation(float Damage);
                        

// Blueprint-native event: restores health by BaseHeal, clamped to MaxHealth.
// Immediately calls EndTurn() — healing costs the fighter's full action.
void UFighter::Heal_Implementation();

// Blueprint-native event: sets DamageReduction to BaseBlock + BlockBuff.
// This value is subtracted in ReceiveDamage_Implementation for the next hit received.
// Calls EndTurn() after committing the defensive stance.
void UFighter::Block_Implementation();

// Adds BuffAmount to the named stat's buff field.
// Stat keys: "Attack", "Damage", "Defense", "Block", "Heal".
// Buff values stack additively and are included in all relevant roll calculations.
// Complements RemoveBuff(), which decrements by the same amount when a buff expires.
void UFighter::AddBuff(float BuffAmount, const FString& stat);
void UFighter::RemoveBuff(float BuffAmount, const FString& stat);
                        

// Weapon type determines which attack utility scorer is preferred.
// Designers set this per enemy in the Details panel; no code change required.
UENUM(BlueprintType)
enum class EWeaponType : uint8 { Melee, Ranged, Magic };

UCLASS(ClassGroup=(Fighters), meta=(BlueprintSpawnableComponent))
class RECONNECTION_API UEnemy : public UFighter
{
    GENERATED_BODY()
public:
    // Overrides StartTurn() to immediately call ChooseAction() after setup.
    virtual void StartTurn() override;

    // Blueprint-implementable AI entry point. The C++ implementation
    // evaluates each utility scorer and calls the highest-scoring action.
    // Designers can override this in Blueprint to create fully custom behaviors.
    UFUNCTION(BlueprintNativeEvent, BlueprintCallable, Category="Enemy|Combat")
    void ChooseAction();
    virtual void ChooseAction_Implementation();

    // Builds the Allies/Enemies rosters from the full fighter list.
    // Called once during UTurnManager::InitializeCombat().
    UFUNCTION(BlueprintCallable, Category="Enemy|Setup")
    void InitializeEnemy(const TArray<UFighter*>& AllFighters);

    // Rebuilds rosters when a fighter joins or dies mid-combat.
    UFUNCTION(BlueprintCallable, Category="Enemy|Setup")
    void UpdateAlliesAndEnemies(const TArray<UFighter*>& AllFighters);

    // Delegate receiver bound to UTurnManager's OnFighterJoined and OnFighterDeath.
    // Looks up the active UTurnManager and triggers UpdateAlliesAndEnemies.
    UFUNCTION(BlueprintCallable, Category="Enemy|Setup")
    void OnFighterListChanged(UFighter* ChangedFighter);

    // Overrides ReceiveDamage to cache LastDamageReceived before calling Super,
    // making recent incoming damage available to GetBlockUtility().
    virtual void ReceiveDamage(float Damage) override;

    // --- Utility scorers (one per possible action) ---
    // Each returns a float score; ChooseAction_Implementation picks the highest.
    UFUNCTION(BlueprintCallable, Category="Enemy|Utility")
    float GetAttackUtility();   // Aggression vs closest visible enemy
    float GetMeleeUtility();    // Preferred weapon type affinity
    float GetRangedUtility();
    float GetMagicUtility();
    float GetSelfHealUtility(); // Urgency based on own health ratio
    float GetAllyHealUtility(); // Need based on most wounded visible ally
    float GetBlockUtility();    // Reactivity based on last hit received
    float GetBuffUtility();     // Reward for buffing when no active buffs exist

    // All weights are EditAnywhere so designers tune behavior per-enemy
    // in the Details panel without touching any C++.
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    float AttackUtilityWeight;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    bool bHasMelee;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    bool bHasRanged;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    bool bHasMagic;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    float HealUtilityWeight;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    bool bHasSelfHeal;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    bool bHasAllyHeal;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    float BuffUtilityWeight;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    bool bHasBuff;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    float BlockUtilityWeight;
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category="Enemy|Utility|Weight")
    bool bHasBlock;

    UFUNCTION(BlueprintCallable, Category="Enemy|StorageAccess")
    UFighter* GetClosestEnemy();
    UFUNCTION(BlueprintCallable, Category="Enemy|StorageAccess")
    UFighter* GetLowestAlly();

private:
    TArray<UFighter*> Allies;
    TArray<UFighter*> Enemies;
    float LastDamageReceived;   // Cached for block utility
    int ClosestEnemyIndex;
    int LowestAllyIndex;

    UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Enemy|Weapon",
              meta=(AllowPrivateAccess="true"))
    EWeaponType CurrentWeaponType = EWeaponType::Melee;
};
                        

// Iterates every fighter in AllFighters (provided by UTurnManager).
// Checks whether each fighter's owner also carries a UEnemy component:
//   - Same faction (UEnemy present): added to the Allies array.
//   - Opposing faction (no UEnemy): added to the Enemies array.
// Skips self to avoid self-targeting.
void UEnemy::InitializeEnemy(const TArray<UFighter*>& AllFighters);

// Same logic as InitializeEnemy but clears both arrays first.
// Called mid-combat whenever a fighter joins or dies,
// ensuring utility scorers always work against a fresh roster.
void UEnemy::UpdateAlliesAndEnemies(const TArray<UFighter*>& AllFighters);

// Receives the UFighter* that changed (join or death) from UTurnManager delegates.
// Iterates world objects to find the active UTurnManager,
// then calls UpdateAlliesAndEnemies with its current Fighters array.
void UEnemy::OnFighterListChanged(UFighter* ChangedFighter);

// Calls Super::ReceiveDamage() for standard health reduction,
// then stores the Damage value in LastDamageReceived
// so GetBlockUtility() can score the block action based on recent pressure.
void UEnemy::ReceiveDamage(float Damage);
                        

// Attack utility — drives aggression toward the nearest visible enemy.
//   1. Finds the closest enemy by horizontal distance and records its index.
//   2. Returns 0 if no enemies are in range (for melee) or if no line-of-sight exists.
//   3. Scores via -ln(healthRatio) so near-dead targets produce exponentially
//      higher values, making finishing moves feel natural.
//   4. Final score is multiplied by AttackUtilityWeight (designer-tunable).
float UEnemy::GetAttackUtility();

// Weapon affinity scalars — preferred weapon type scores 1.0;
// off-type variants score lower to bias the AI toward its equipped weapon.
// Returns 0 if the enemy doesn't possess that weapon type.
float UEnemy::GetMeleeUtility();
float UEnemy::GetRangedUtility();
float UEnemy::GetMagicUtility();

// Self-heal utility — exponential urgency scaled by own health ratio.
//   Returns FLT_MAX (force-heal) when health drops to or below 10%,
//   guaranteeing survival over any other action at critical thresholds.
float UEnemy::GetSelfHealUtility();

// Ally-heal utility — finds the most wounded visible ally and scores
// by their need using the same exponential curve as self-heal.
// LowestAllyIndex is stored so ChooseAction knows which ally to target.
float UEnemy::GetAllyHealUtility();

// Block utility — reactive defense scored on recent incoming damage.
//   Uses exp(damageRatio * weight) - 1 so enemies who just took a heavy hit
//   will prioritize blocking next turn proportionally to how hard they were hit.
float UEnemy::GetBlockUtility();

// Buff utility — rewards the first buff action highly (score = 1.0),
// then diminishes per already-active buff using 0.5 / BuffTracker.Num().
// Prevents enemies from wasting turns stacking redundant buffs.
float UEnemy::GetBuffUtility();
                        

// Returns all 15 combat stats in a flat array in this order:
//   InitiativeScore, MaxHealth, CurrentHealth,
//   MinDamage, MaxDamage, DamageBuff,
//   BaseAttack, AttackBuff,
//   BaseDefense, DefenseBuff,
//   BaseBlock, BlockBuff,
//   BaseHeal, HealBuff,
//   DamageReduction
// Used by the UI to populate the stat panel without needing
// direct references to individual properties.
TArray<float> UFighter::GetAllStats();

// Blueprint-native event: routes outgoing damage to the target.
// Base implementation calls Target->ReceiveDamage(Damage) directly.
// Blueprint can override to insert hit effects, sounds, or damage-type logic.
void UFighter::SendDamage_Implementation(float Damage, UFighter* Target);

// Blueprint-native event: handles fighter death.
// C++ signals the event; Blueprint implements death animations,
// loot drops, VFX spawning, and any game-over state transitions.
void UFighter::Die_Implementation();
                        

// Five multicast delegates give Blueprint full observability over combat state.
// UI, cameras, audio, and narrative systems bind to these without any C++ changes.
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnTurnChanged,   UFighter*, CurrentFighter);
DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnRoundStarted);
DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnCombatEnded);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnFighterDeath,  UFighter*, DeadFighter);
DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnFighterJoined, UFighter*, NewFighter);

UCLASS(ClassGroup=(Custom), meta=(BlueprintSpawnableComponent))
class RECONNECTION_API UTurnManager : public UActorComponent
{
    GENERATED_BODY()
public:
    UTurnManager();

    // The sorted fighter roster — publicly readable so UEnemy can query it.
    UPROPERTY(BlueprintReadOnly,  Category="Turn Manager") TArray<UFighter*> Fighters;
    UPROPERTY(BlueprintReadOnly,  Category="Turn Manager") int32 CurrentTurnIndex;
    UPROPERTY(BlueprintReadOnly,  Category="Turn Manager") int32 CurrentRound;
    UPROPERTY(BlueprintReadWrite, Category="Turn Manager") bool  bCombatActive;
    UPROPERTY(BlueprintReadOnly,  Category="Turn Manager") int32 EnemiesLeft = 0;
    // Set in Blueprint to control which level loads when all enemies die.
    UPROPERTY(BlueprintReadWrite, Category="Turn Manager") FName NextLevel;

    // Broadcast-assignable events — wire anything from Blueprint
    UPROPERTY(BlueprintAssignable, Category="Turn Manager|Events") FOnTurnChanged   OnTurnChanged;
    UPROPERTY(BlueprintAssignable, Category="Turn Manager|Events") FOnRoundStarted  OnRoundStarted;
    UPROPERTY(BlueprintAssignable, Category="Turn Manager|Events") FOnCombatEnded   OnCombatEnded;
    UPROPERTY(BlueprintAssignable, Category="Turn Manager|Events") FOnFighterDeath  OnFighterDeath;
    UPROPERTY(BlueprintAssignable, Category="Turn Manager|Events") FOnFighterJoined OnFighterJoined;

    // Scans the world for UFighter components, binds delegates, sorts by initiative.
    UFUNCTION(BlueprintCallable, Category="Turn Manager") void InitializeCombat();
    // Activates combat, resets state, and starts the first fighter's turn.
    UFUNCTION(BlueprintCallable, Category="Turn Manager") void StartCombat();
    // Advances CurrentTurnIndex, wraps at end of round, hands off to next fighter.
    UFUNCTION(BlueprintCallable, Category="Turn Manager") void NextTurn();
    UFUNCTION(BlueprintCallable, Category="Turn Manager") UFighter* GetCurrentFighter();
    // Descending sort by InitiativeScore — highest acts first.
    UFUNCTION(BlueprintCallable, Category="Turn Manager") void SortFightersByInitiative();
    // Removes fighter, adjusts index, calls EndCombat() if only one side remains.
    UFUNCTION(BlueprintCallable, Category="Turn Manager") void RemoveFighter(UFighter* Fighter);
    UFUNCTION(BlueprintCallable, Category="Turn Manager") void EndCombat();

private:
    // Bound to each fighter's OnDeath delegate during InitializeCombat().
    UFUNCTION() void HandleFighterDeath(UFighter* DeadFighter);
    // Bound to each fighter's OnEndTurn delegate — simply calls NextTurn().
    UFUNCTION() void HandleFighterEndTurn(UFighter* Fighter);
};
                        

// BeginPlay calls InitializeCombat() automatically.
// StartCombat() is intentionally separate so Blueprint can delay the
// start with cutscenes, dialogue, or camera transitions.
void UTurnManager::BeginPlay();

// World scan phase:
//   1. Calls GetAllActorsOfClass to iterate every actor.
//   2. Checks each for a UFighter component; skips those without one.
//   3. Adds valid fighters to the Fighters array.
//   4. Binds each fighter's OnDeath and OnEndTurn delegates
//      to HandleFighterDeath and HandleFighterEndTurn respectively.
//   5. If the actor also has a UEnemy component:
//      - Calls InitializeEnemy() to build that enemy's ally/enemy rosters.
//      - Binds OnFighterJoined and OnFighterDeath to the enemy's
//        OnFighterListChanged so its rosters self-update mid-combat.
//      - Increments EnemiesLeft.
//   6. Broadcasts OnFighterJoined for each fighter (UI can react).
//   7. Calls SortFightersByInitiative() to finalize turn order.
void UTurnManager::InitializeCombat();

// Activation phase:
//   1. Guards against an empty Fighters array.
//   2. Sets bCombatActive = true, CurrentTurnIndex = 0, CurrentRound = 1.
//   3. Broadcasts OnRoundStarted.
//   4. Clears any stale bIsTurn flags from all fighters.
//   5. Calls StartTurn() on the first fighter in sorted order
//      and broadcasts OnTurnChanged.
void UTurnManager::StartCombat();
                        

// Advances the combat queue:
//   1. Guards against inactive combat or an empty roster.
//   2. Increments CurrentTurnIndex.
//   3. If the index exceeds the last slot, wraps to 0,
//      increments CurrentRound, and broadcasts OnRoundStarted.
//   4. Clears lingering bIsTurn flags across all fighters.
//   5. Calls StartTurn() on the new CurrentFighter
//      and broadcasts OnTurnChanged.
void UTurnManager::NextTurn();

// Returns Fighters[CurrentTurnIndex] if the index is valid, else nullptr.
UFighter* UTurnManager::GetCurrentFighter();

// Sorts Fighters descending by InitiativeScore using a lambda comparator.
// Ties are resolved by the natural array order (earlier discovery = higher priority).
// Called once at the end of InitializeCombat().
void UTurnManager::SortFightersByInitiative();

// Delegate receiver bound during InitializeCombat.
// Calls NextTurn() as long as bCombatActive is true.
void UTurnManager::HandleFighterEndTurn(UFighter* Fighter);
                        

// Safely removes a dead or retreating fighter from the sorted roster:
//   1. Finds the fighter's index; returns immediately if not found.
//   2. Removes the fighter from the array.
//   3. Adjusts CurrentTurnIndex to stay valid:
//      - If removed index is before current: decrement index.
//      - If removed index equals current and now out-of-bounds: wrap to 0.
//   4. If only one fighter (or zero) remain, calls EndCombat().
void UTurnManager::RemoveFighter(UFighter* Fighter);

// Sets bCombatActive = false and broadcasts OnCombatEnded.
// Blueprint listens to this event to show victory UI, trigger cutscenes, etc.
void UTurnManager::EndCombat();

// Bound to each fighter's OnDeath delegate during InitializeCombat().
//   1. Broadcasts OnFighterDeath (UEnemy.OnFighterListChanged listeners rebuild rosters).
//   2. Calls RemoveFighter() to clean up the roster and advance turn if needed.
//   3. If the dead fighter had a UEnemy component: decrements EnemiesLeft.
//      When EnemiesLeft reaches 0, calls UGameplayStatics::OpenLevel with NextLevel
//      to progress to the next combat encounter.
void UTurnManager::HandleFighterDeath(UFighter* DeadFighter);