FormIDHelper.h

#pragma once

// Include the minimal set of Unreal Engine headers required for core functionality.
// Provides access to essential types like FString and macros like UPROPERTY.
#include "CoreMinimal.h"

// Include IFileManager for file operations (optional, not strictly needed here).
#include "HAL/FileManager.h"

// Include the BlueprintFunctionLibrary base class header.
// Enables the creation of a static function library accessible in Blueprints without instantiation.
#include "Kismet/BlueprintFunctionLibrary.h"

// Include the FormID header to access the FFormID struct definition.
// Necessary for function parameters that operate on FFormID instances.
#include "FormID.h"

// Include the generated header for this class, containing reflection code.
// Required for Unreal Engine's reflection system to support Blueprint integration and serialization.
#include "FormIDHelper.generated.h"

// Define the FExtendedFormID struct, which extends FFormID with plugin context.
// Marked as USTRUCT(BlueprintType) to enable its use as a variable type in Blueprints.
USTRUCT(BlueprintType)
struct FExtendedFormID
{
    GENERATED_BODY()

    // The base FormID, representing the raw identifier.
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category = "FormID")
    FFormID FormID;

    // The name of the parent plugin file (e.g., "MyPlugin.esp").
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category = "FormID")
    FString ParentPluginName;

    // Array of master plugin file names that this plugin depends on.
    UPROPERTY(BlueprintReadWrite, EditAnywhere, Category = "FormID")
    TArray<FString> Masters;

    // Default constructor initializing members to safe defaults.
    FExtendedFormID()
        : FormID(0)
        , ParentPluginName(TEXT(""))
        , Masters()
    {
    }

    // Equality operator to compare two FExtendedFormIDs.
    bool operator==(const FExtendedFormID& Other) const
    {
        return FormID == Other.FormID && ParentPluginName == Other.ParentPluginName && Masters == Other.Masters;
    }

    // Inequality operator derived from equality.
    bool operator!=(const FExtendedFormID& Other) const
    {
        return !(*this == Other);
    }
};

// Define a class UFormIDHelper as a static Blueprint function library.
// Inherits from UBlueprintFunctionLibrary to provide utility functions for FFormID operations in Blueprints.
// Marked with UCLASS() for reflection and UNREALCREATIONENGINE_API for DLL export/import across modules.
UCLASS()
class UNREALCREATIONENGINE_API UFormIDHelper : public UBlueprintFunctionLibrary
{
    // Macro required for all UCLASSes to generate reflection code.
    // Ensures the class is recognized by Unreal Engine's reflection system for Blueprint exposure.
    GENERATED_BODY()

public:
    // Function to convert a FormID to a hexadecimal string representation.
    // Marked as UFUNCTION(BlueprintPure) to indicate it has no side effects and can be used in Blueprint graphs.
    // Categorized under "FormID" for easy discovery in the Blueprint function library.
    // Takes an FFormID and returns an FString formatted as "0xXXXXXXXX".
    UFUNCTION(BlueprintPure, Category = "FormID")
    static FString ToString(const FFormID& FormID);

    // Function to compare two FormIDs for equality.
    // BlueprintPure ensures it is side-effect-free and usable in Blueprint logic.
    // Categorized under "FormID" for organization in Blueprint menus.
    // Takes two FFormID parameters and returns true if their Values are equal, false otherwise.
    UFUNCTION(BlueprintPure, Category = "FormID")
    static bool Equals(const FFormID& A, const FFormID& B);

    // Function to check if a FormID is valid (non-zero Value).
    // BlueprintPure allows safe use in Blueprint calculations or conditions.
    // Categorized under "FormID" for clarity in Blueprint interfaces.
    // Takes an FFormID and returns true if its Value is non-zero, false if zero.
    UFUNCTION(BlueprintPure, Category = "FormID")
    static bool IsValid(const FFormID& FormID);

    // Function to extract the plugin index from a standard FormID (non-ESL).
    // BlueprintPure ensures it is safe for Blueprint computations.
    // Categorized under "FormID" for accessibility in Blueprint nodes.
    // Takes an FFormID and returns the plugin index (bits 24-31) as an int32.
    UFUNCTION(BlueprintPure, Category = "FormID")
    static int32 GetPluginIndex(const FFormID& FormID);

    // Function to extract the record index from a standard FormID (non-ESL).
    // BlueprintPure indicates no side effects, suitable for Blueprint data processing.
    // Categorized under "FormID" for organization in Blueprint function lists.
    // Takes an FFormID and returns the record index (bits 0-23) as an int32.
    UFUNCTION(BlueprintPure, Category = "FormID")
    static int32 GetRecordIndex(const FFormID& FormID);

    // Function to determine if a FormID belongs to an ESL (Elder Scrolls Light) plugin.
    // BlueprintPure allows use in Blueprint logic without modifying state.
    // Categorized under "FormID" for easy access in Blueprint interfaces.
    // Takes an FFormID and returns true if the top byte is 0xFE (indicating ESL), false otherwise.
    UFUNCTION(BlueprintPure, Category = "FormID")
    static bool IsESL(const FFormID& FormID);

    // Function to get the ESL index from a FormID if it is an ESL plugin.
    // BlueprintPure ensures it is safe for Blueprint calculations.
    // Categorized under "FormID" for clarity in Blueprint menus.
    // Takes an FFormID and returns the ESL index (bits 12-23) as an int32, or -1 if not ESL.
    UFUNCTION(BlueprintPure, Category = "FormID")
    static int32 GetESLIndex(const FFormID& FormID);

    // Function to get the record index from a FormID if it is an ESL plugin.
    // BlueprintPure indicates it can be used in Blueprint logic without side effects.
    // Categorized under "FormID" for organization in Blueprint function libraries.
    // Takes an FFormID and returns the ESL record index (bits 0-11) as an int32, or -1 if not ESL.
    UFUNCTION(BlueprintPure, Category = "FormID")
    static int32 GetESLRecordIndex(const FFormID& FormID);

    // New functions for FExtendedFormID support

    // Function to create an FExtendedFormID with plugin context.
    // BlueprintCallable allows it to be invoked from Blueprints to construct an FExtendedFormID instance.
    // Categorized under "FormID" for consistency with other FormID-related functions.
    UFUNCTION(BlueprintCallable, Category = "FormID")
    static FExtendedFormID CreateExtendedFormID(const FString& InParentPluginName, const TArray<FString>& InMasters, int32 InRawId);

    // Function to normalize a plugin name to a full file path, adding .esp if no extension is present.
    // BlueprintPure indicates it has no side effects and is suitable for Blueprint computations.
    // Includes a tooltip for clarity in Blueprint interfaces.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Converts a plugin name to a full file path, adding .esp if needed."))
    static FString NormalizePluginName(const FString& PluginName);

    // Function to validate the existence of plugin files, logging warnings if any are missing.
    // BlueprintCallable since it performs logging, which is a side effect.
    // Includes a tooltip describing its purpose.
    UFUNCTION(BlueprintCallable, Category = "FormID", meta=(ToolTip="Checks if plugin files exist, logging warnings if missing."))
    static bool ValidatePluginFiles(const FExtendedFormID& ExtendedFormID);

    // Function to check if a plugin name has a valid extension (.esm, .esp, or .esl).
    // BlueprintPure ensures it is side-effect-free and usable in Blueprint logic.
    // Includes a tooltip for Blueprint users.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Returns true if the plugin name has a valid extension."))
    static bool IsValidPluginExtension(const FString& PluginName);

    // Function to retrieve the record index within the plugin for an FExtendedFormID.
    // BlueprintPure allows its use in Blueprint calculations without modifying state.
    // Includes a tooltip for clarity.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Gets the record index within the plugin."))
    static int32 GetObjectIndex(const FExtendedFormID& ExtendedFormID);

    // Function to retrieve the plugin file path for an FExtendedFormID.
    // BlueprintPure indicates it is a read-only operation suitable for Blueprints.
    // Includes a tooltip describing its output.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Gets the plugin file path for this FormID."))
    static FString GetPluginName(const FExtendedFormID& ExtendedFormID);

    // Function to retrieve all plugin file paths (parent and masters) for an FExtendedFormID.
    // BlueprintPure ensures it is safe for Blueprint data retrieval.
    // Includes a tooltip explaining the returned array.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Gets all plugin file paths (parent and masters)."))
    static TArray<FString> GetAllPluginNames(const FExtendedFormID& ExtendedFormID);

    // Function to check if a specific plugin is listed as a master dependency in an FExtendedFormID.
    // BlueprintPure allows its use in Blueprint conditions without side effects.
    // Includes a tooltip for user guidance.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Returns true if the plugin is a master dependency."))
    static bool HasMaster(const FExtendedFormID& ExtendedFormID, const FString& MasterName);

    // Function to estimate the load order index for an FExtendedFormID’s plugin.
    // BlueprintPure indicates it is a computation without side effects.
    // Includes a tooltip explaining the load order concept.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Estimates load order index (0-based, higher means later)."))
    static int32 GetPluginLoadOrderIndex(const FExtendedFormID& ExtendedFormID);

    // Function to compare two FExtendedFormIDs based on plugin names and object indices.
    // BlueprintPure ensures it is suitable for Blueprint comparisons.
    // Includes a tooltip describing the comparison logic.
    UFUNCTION(BlueprintPure, Category = "FormID", meta=(ToolTip="Compares plugin names (case-insensitive) and indices."))
    static bool IsLessThan(const FExtendedFormID& A, const FExtendedFormID& B);
};