FormIDHelper.cpp

// Include the header for UFormIDHelper, which declares the class and its static functions.
// Ensures the implementations in this file match the declared interface.
#include "FormIDHelper.h"

// Include the header for FFormID, which defines the struct used by these functions.
// Provides access to the Value member for bit manipulation and comparisons.
#include "FormID.h"

// Include for FPaths, used in NormalizePluginName for file path operations.
#include "Misc/Paths.h"

// Include for IFileManager, used in ValidatePluginFiles to check file existence.
#include "HAL/FileManager.h"

// Implementation of ToString, a static function of UFormIDHelper.
// Converts a FormID to a hexadecimal string representation, e.g., "0x00000001".
// Used for debugging, logging, or displaying FormIDs in a human-readable format in Blueprints or C++.
FString UFormIDHelper::ToString(const FFormID& FormID)
{
    // Use FString::Printf to format the FormID's Value as an 8-digit hexadecimal number.
    // TEXT("0x%08X") ensures a "0x" prefix and zero-padding for consistency (e.g., "0x00000001").
    // Cast Value to uint32 to match the unsigned format specifier %X, avoiding warnings.
    return FString::Printf(TEXT("0x%08X"), static_cast<uint32>(FormID.Value));
}

// Implementation of Equals, a static function of UFormIDHelper.
// Compares two FormIDs to determine if they are equal.
// Useful in Blueprints or C++ for validation, branching, or data comparison.
bool UFormIDHelper::Equals(const FFormID& A, const FFormID& B)
{
    // Compare the Value members of both FormIDs.
    // Returns true if they are equal, false otherwise, making it a pure operation with no side effects.
    return A.Value == B.Value;
}

// Implementation of IsValid, a static function of UFormIDHelper.
// Checks if a FormID is valid, where a valid FormID has a non-zero Value.
// Essential for ensuring FormIDs refer to actual records before processing in Blueprints or C++.
bool UFormIDHelper::IsValid(const FFormID& FormID)
{
    // Return true if the FormID's Value is non-zero, indicating a valid record.
    // A Value of 0 is typically considered invalid in Bethesda game file formats.
    // This is a pure operation, as it only reads the Value and performs a comparison.
    return FormID.Value != 0;
}

// Implementation of GetPluginIndex, a static function of UFormIDHelper.
// Extracts the plugin index from a standard (non-ESL) FormID.
// The plugin index, stored in the first byte (bits 24-31), identifies the plugin file (.ESP or .ESM).
int32 UFormIDHelper::GetPluginIndex(const FFormID& FormID)
{
    // Shift the FormID's Value right by 24 bits to isolate the top byte (bits 24-31).
    // Apply a bitmask (0xFF) to ensure only the last 8 bits are considered, extracting the plugin index.
    // Cast Value to uint32 for unsigned bit operations to avoid signed arithmetic warnings.
    // Returns the index as an int32, a pure operation that only reads the Value.
    return (static_cast<uint32>(FormID.Value) >> 24) & 0xFF;
}

// Implementation of GetRecordIndex, a static function of UFormIDHelper.
// Extracts the record index from a standard (non-ESL) FormID.
// The record index, stored in the last 3 bytes (bits 0-23), identifies a specific record within the plugin.
int32 UFormIDHelper::GetRecordIndex(const FFormID& FormID)
{
    // Apply a bitmask (0xFFFFFF) to isolate the last 24 bits (bits 0-23) of the FormID's Value.
    // Cast Value to uint32 for unsigned bit operations to avoid signed arithmetic warnings.
    // Returns the record index as an int32, a pure operation with no side effects.
    return static_cast<uint32>(FormID.Value) & 0xFFFFFF;
}

// Implementation of IsESL, a static function of UFormIDHelper.
// Determines if a FormID belongs to an ESL (Elder Scrolls Light) plugin.
// ESL plugins, used in Skyrim Special Edition and Fallout 4, have a top byte of 0xFE.
bool UFormIDHelper::IsESL(const FFormID& FormID)
{
    // Shift the FormID's Value right by 24 bits to isolate the top byte (bits 24-31).
    // Compare it to 0xFE to check if it indicates an ESL plugin.
    // Cast Value to uint32 for unsigned bit operations to avoid signed arithmetic warnings.
    // Returns true if the top byte is 0xFE, false otherwise, in a pure and safe operation.
    return (static_cast<uint32>(FormID.Value) >> 24) == 0xFE;
}

// Implementation of GetESLIndex, a static function of UFormIDHelper.
// Retrieves the ESL index from a FormID if it belongs to an ESL plugin.
// The ESL index, stored in bits 12-23, represents the plugin's position in the load order.
int32 UFormIDHelper::GetESLIndex(const FFormID& FormID)
{
    // Check if the FormID is an ESL using IsESL to ensure correct processing.
    if (IsESL(FormID))
    {
        // Shift the Value right by 12 bits to align bits 12-23 with the lower bits.
        // Apply a bitmask (0xFFF) to isolate these 12 bits, extracting the ESL index.
        // Cast Value to uint32 for unsigned bit operations to avoid signed arithmetic warnings.
        // Return the index as an int32, a pure operation that only reads the Value.
        return (static_cast<uint32>(FormID.Value) >> 12) & 0xFFF;
    }
    // If the FormID is not an ESL, return -1 to indicate the ESL index is not applicable.
    // Ensures consistent behavior for non-ESL FormIDs.
    return -1;
}

// Implementation of GetESLRecordIndex, a static function of UFormIDHelper.
// Retrieves the record index from a FormID if it belongs to an ESL plugin.
// The record index, stored in bits 0-11, identifies a specific record within the ESL plugin.
int32 UFormIDHelper::GetESLRecordIndex(const FFormID& FormID)
{
    // Check if the FormID is an ESL using IsESL to validate the FormID type.
    if (IsESL(FormID))
    {
        // Apply a bitmask (0xFFF) to isolate the last 12 bits (bits 0-11) of the Value.
        // Cast Value to uint32 for unsigned bit operations to avoid signed arithmetic warnings.
        // Return the record index as an int32, a pure operation with no side effects.
        return static_cast<uint32>(FormID.Value) & 0xFFF;
    }
    // If the FormID is not an ESL, return -1 to indicate the ESL record index is not applicable.
    // Maintains consistency in return values for non-ESL FormIDs.
    return -1;
}

// Implementation of CreateExtendedFormID, a static function of UFormIDHelper.
// Creates an FExtendedFormID instance with the given parent plugin name, masters, and raw FormID value.
// Normalizes plugin names and validates the existence of plugin files.
FExtendedFormID UFormIDHelper::CreateExtendedFormID(const FString& InParentPluginName, const TArray<FString>& InMasters, int32 InRawId)
{
    FExtendedFormID ExtendedFormID;
    ExtendedFormID.FormID = FFormID(InRawId);
    ExtendedFormID.ParentPluginName = NormalizePluginName(InParentPluginName);
    ExtendedFormID.Masters.Reserve(InMasters.Num());
    for (const FString& Master : InMasters)
    {
        ExtendedFormID.Masters.Add(NormalizePluginName(Master));
    }
    ValidatePluginFiles(ExtendedFormID);
    return ExtendedFormID;
}

// Implementation of NormalizePluginName, a static function of UFormIDHelper.
// Normalizes a plugin name to a full file path, adding ".esp" if no extension is present.
// Ensures consistent handling of plugin file paths across different systems.
FString UFormIDHelper::NormalizePluginName(const FString& PluginName)
{
    FString Normalized = PluginName;
    FPaths::NormalizeFilename(Normalized);
    if (!Normalized.Contains(TEXT(".")))
    {
        Normalized += TEXT(".esp");
    }
    return FPaths::ConvertRelativePathToFull(FPaths::ProjectContentDir() / Normalized);
}

// Implementation of ValidatePluginFiles, a static function of UFormIDHelper.
// Checks if the plugin files specified in the FExtendedFormID exist on disk.
// Logs warnings for any missing files and returns true if all files are found, false otherwise.
bool UFormIDHelper::ValidatePluginFiles(const FExtendedFormID& ExtendedFormID)
{
    IFileManager& FileManager = IFileManager::Get();
    bool bAllValid = true;
    if (!ExtendedFormID.ParentPluginName.IsEmpty() && !FileManager.FileExists(*ExtendedFormID.ParentPluginName))
    {
        UE_LOG(LogTemp, Warning, TEXT("Parent plugin file does not exist: %s"), *ExtendedFormID.ParentPluginName);
        bAllValid = false;
    }
    for (const FString& Master : ExtendedFormID.Masters)
    {
        if (!Master.IsEmpty() && !FileManager.FileExists(*Master))
        {
            UE_LOG(LogTemp, Warning, TEXT("Master plugin file does not exist: %s"), *Master);
            bAllValid = false;
        }
    }
    return bAllValid;
}

// Implementation of IsValidPluginExtension, a static function of UFormIDHelper.
// Determines if a plugin name has a valid file extension for Bethesda game plugins.
// Valid extensions are .esm, .esp, and .esl (case-insensitive).
bool UFormIDHelper::IsValidPluginExtension(const FString& PluginName)
{
    return PluginName.EndsWith(TEXT(".esm"), ESearchCase::IgnoreCase) ||
           PluginName.EndsWith(TEXT(".esp"), ESearchCase::IgnoreCase) ||
           PluginName.EndsWith(TEXT(".esl"), ESearchCase::IgnoreCase);
}

// Implementation of GetObjectIndex, a static function of UFormIDHelper.
// Retrieves the record index within the plugin for the given FExtendedFormID.
// Handles both standard and ESL FormIDs appropriately.
int32 UFormIDHelper::GetObjectIndex(const FExtendedFormID& ExtendedFormID)
{
    if (IsESL(ExtendedFormID.FormID))
    {
        return GetESLRecordIndex(ExtendedFormID.FormID);
    }
    return GetRecordIndex(ExtendedFormID.FormID);
}

// Implementation of GetPluginName, a static function of UFormIDHelper.
// Determines the plugin file path associated with the FExtendedFormID's FormID.
// Considers the mod index and master dependencies to select the correct plugin.
FString UFormIDHelper::GetPluginName(const FExtendedFormID& ExtendedFormID)
{
    int32 ModIndex = GetPluginIndex(ExtendedFormID.FormID);
    if (ExtendedFormID.Masters.Num() > 0)
    {
        if (ModIndex == 0)
        {
            return ExtendedFormID.Masters[0];
        }
        else if (ModIndex < ExtendedFormID.Masters.Num())
        {
            return ExtendedFormID.Masters[ModIndex];
        }
    }
    return ExtendedFormID.ParentPluginName;
}

// Implementation of GetAllPluginNames, a static function of UFormIDHelper.
// Collects all plugin file paths (parent and masters) associated with the FExtendedFormID.
// Useful for operations requiring the full set of dependent plugins.
TArray<FString> UFormIDHelper::GetAllPluginNames(const FExtendedFormID& ExtendedFormID)
{
    TArray<FString> AllPlugins;
    AllPlugins.Add(ExtendedFormID.ParentPluginName);
    AllPlugins.Append(ExtendedFormID.Masters);
    return AllPlugins;
}

// Implementation of HasMaster, a static function of UFormIDHelper.
// Checks if a specific plugin is listed as a master dependency in the FExtendedFormID.
// Normalizes the master name for consistent comparison.
bool UFormIDHelper::HasMaster(const FExtendedFormID& ExtendedFormID, const FString& MasterName)
{
    FString NormalizedMaster = NormalizePluginName(MasterName);
    return ExtendedFormID.Masters.Contains(NormalizedMaster);
}

// Implementation of GetPluginLoadOrderIndex, a static function of UFormIDHelper.
// Estimates the load order index for the plugin based on the number of master dependencies.
// A higher number of masters typically indicates a later load order.
int32 UFormIDHelper::GetPluginLoadOrderIndex(const FExtendedFormID& ExtendedFormID)
{
    return ExtendedFormID.Masters.Num();
}

// Implementation of IsLessThan, a static function of UFormIDHelper.
// Compares two FExtendedFormIDs based on their plugin names (case-insensitive) and object indices.
// Used for sorting or ordering FormIDs in collections.
bool UFormIDHelper::IsLessThan(const FExtendedFormID& A, const FExtendedFormID& B)
{
    FString PluginA = GetPluginName(A).ToLower();
    FString PluginB = GetPluginName(B).ToLower();
    if (PluginA != PluginB)
    {
        return PluginA < PluginB;
    }
    return GetObjectIndex(A) < GetObjectIndex(B);
}