Record.h

// Ensures this header is only included once during compilation to prevent redefinition errors.
#pragma once

// Includes core Unreal Engine types and macros (e.g., FString, TArray, UPROPERTY) required for the struct and class definitions.
#include "CoreMinimal.h"

// Includes the base class for Blueprint Function Libraries, allowing the creation of Blueprint-callable functions.
#include "Kismet/BlueprintFunctionLibrary.h"

// Includes the GameID enum, used to specify game-specific parsing logic for records.
#include "GameID.h"

// Includes the FormID struct, representing unique identifiers for records in non-Morrowind games.
#include "FormID.h"

// Includes the Subrecord struct, used to store subrecords within a record.
#include "Subrecord.h"

// Includes the generated header for this file, created by Unreal Engine for USTRUCT and UCLASS definitions.
#include "Record.generated.h"

// Defines a struct representing a record, a higher-level data structure in Bethesda game file formats (e.g., .ESM, .ESP).
// Marked as BlueprintType to allow use in Blueprints, enabling modders and designers to interact with records.
USTRUCT(BlueprintType)
struct FRecord
{
    GENERATED_BODY()

    // The 4-byte type identifier of the record (e.g., "NPC_", "WEAP"), stored as an FString for Blueprint compatibility.
    UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Record", meta=(ToolTip="4-byte type identifier (e.g., NPC_)."))
    FString Type;

    // Flags indicating record properties, such as compression status (e.g., bit 0x00040000 for compressed fields).
    UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Record", meta=(ToolTip="Record flags (e.g., compression status)."))
    int32 Flags;

    // FormID uniquely identifying the record, used in non-Morrowind games (e.g., Skyrim, Oblivion).
    UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Record", meta=(ToolTip="FormID identifying the record."))
    FFormID FormId;

    // Array of subrecords containing the record's detailed data.
    UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Record", meta=(ToolTip="Subrecords containing record data."))
    TArray<FSubrecord> Subrecords;

    // Default constructor, initializing fields to safe defaults.
    FRecord()
        : Type(TEXT(""))
        , Flags(0)
        , FormId(0)
        , Subrecords()
    {
    }

    // Parameterized constructor to initialize a record with specific values.
    FRecord(const FString& InType, int32 InFlags, const FFormID& InFormId, const TArray<FSubrecord>& InSubrecords)
        : Type(InType)
        , Flags(InFlags)
        , FormId(InFormId)
        , Subrecords(InSubrecords)
    {
    }

    // Equality operator to compare two records based on all fields.
    bool operator==(const FRecord& Other) const
    {
        return Type == Other.Type && Flags == Other.Flags && FormId == Other.FormId && Subrecords == Other.Subrecords;
    }

    // Inequality operator, defined using the equality operator for consistency.
    bool operator!=(const FRecord& Other) const
    {
        return !(*this == Other);
    }
};

// Defines a hash function for FRecord, enabling use in hash-based containers like TMap or TSet.
// Combines hashes of all fields using XOR for a unique value.
FORCEINLINE uint32 GetTypeHash(const FRecord& Record)
{
    return GetTypeHash(Record.Type) ^ GetTypeHash(Record.Flags) ^ GetTypeHash(Record.FormId) ^ GetTypeHash(Record.Subrecords);
}

// Declares a Blueprint Function Library for record-related utilities.
// Provides parsing, file/byte reading, writing, and data access functions, all Blueprint-accessible.
UCLASS()
class UNREALCREATIONENGINE_API URecordHelper : public UBlueprintFunctionLibrary
{
    GENERATED_BODY()

public:
    // Core parsing function to read a record from an FArchive.
    // Not Blueprint-exposed due to FArchive, but used internally by other functions.
    // Parameters:
    // - OutRecord: The FRecord struct to populate with parsed data.
    // - Archive: The FArchive to read from.
    // - GameID: Specifies the game format for parsing logic.
    // - bSkipSubrecords: If true, skips parsing subrecords.
    // Returns: True if parsing was successful, false otherwise.
    static bool ReadRecord(FRecord& OutRecord, FArchive& Archive, EGameID GameID, bool bSkipSubrecords);

    // Reads a record from a file, handling game-specific logic and optional subrecord skipping.
    // Blueprint-callable for easy use in modding workflows.
    // Parameters:
    // - OutRecord: The FRecord to populate.
    // - FilePath: Path to the file to read from.
    // - GameID: Specifies the game format.
    // - bSkipSubrecords: If true, skips subrecords.
    // Returns: True if the record was successfully read, false otherwise.
    UFUNCTION(BlueprintCallable, Category = "Record", meta=(ToolTip="Reads a record from a file with game-specific logic."))
    static bool ReadRecordFromFile(FRecord& OutRecord, const FString& FilePath, EGameID GameID, bool bSkipSubrecords);

    // Reads a record from a byte array, useful for in-memory data or network transmission.
    // Blueprint-callable for flexibility in data sources.
    // Parameters:
    // - OutRecord: The FRecord to populate.
    // - ByteArray: The byte array to read from.
    // - GameID: Specifies the game format.
    // - bSkipSubrecords: If true, skips subrecords.
    // Returns: True if the record was successfully read, false otherwise.
    UFUNCTION(BlueprintCallable, Category = "Record", meta=(ToolTip="Reads a record from a byte array with game-specific logic."))
    static bool ReadRecordFromBytes(FRecord& OutRecord, const TArray<uint8>& ByteArray, EGameID GameID, bool bSkipSubrecords);

    // Writes a record to a file, preserving its structure and game-specific format.
    // Blueprint-callable for saving records to disk.
    // Parameters:
    // - Record: The FRecord to write.
    // - FilePath: Path to the file to write to.
    // - GameID: Specifies the game format for serialization.
    // Returns: True if the record was successfully written, false otherwise.
    UFUNCTION(BlueprintCallable, Category = "Record", meta=(ToolTip="Writes a record to a file with game-specific logic."))
    static bool WriteRecordToFile(const FRecord& Record, const FString& FilePath, EGameID GameID);

    // Serializes a record to a byte array, useful for network transmission or storage.
    // Blueprint-callable for flexible data handling.
    // Parameters:
    // - Record: The FRecord to serialize.
    // - OutByteArray: The byte array to write the serialized data to.
    // - GameID: Specifies the game format for serialization.
    // Returns: True if the record was successfully serialized, false otherwise.
    UFUNCTION(BlueprintCallable, Category = "Record", meta=(ToolTip="Serializes a record to a byte array with game-specific logic."))
    static bool WriteRecordToBytes(const FRecord& Record, TArray<uint8>& OutByteArray, EGameID GameID);

    // Gets the record's 4-byte type identifier.
    // BlueprintPure indicates this function has no side effects and can be used in Blueprint graphs.
    // Parameters:
    // - Record: The FRecord to get the type from.
    // Returns: The 4-byte type identifier as an FString.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Gets the 4-byte type identifier."))
    static FString GetType(const FRecord& Record);

    // Gets the record's flags.
    // BlueprintPure for use in Blueprint logic without side effects.
    // Parameters:
    // - Record: The FRecord to get the flags from.
    // Returns: The flags as an int32.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Gets the record flags."))
    static int32 GetFlags(const FRecord& Record);

    // Gets the record's FormID.
    // BlueprintPure for Blueprint accessibility.
    // Parameters:
    // - Record: The FRecord to get the FormID from.
    // Returns: The FormID as an FFormID struct.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Gets the FormID."))
    static FFormID GetFormId(const FRecord& Record);

    // Gets the array of subrecords.
    // BlueprintPure for Blueprint use.
    // Parameters:
    // - Record: The FRecord to get the subrecords from.
    // Returns: The array of FSubrecord structs.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Gets the subrecords."))
    static TArray<FSubrecord> GetSubrecords(const FRecord& Record);

    // Checks if the record is compressed based on its flags.
    // BlueprintPure for use in conditional logic in Blueprints.
    // Parameters:
    // - Record: The FRecord to check.
    // Returns: True if the record is compressed, false otherwise.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Returns true if the record is compressed."))
    static bool AreFieldsCompressed(const FRecord& Record);

    // Retrieves the first subrecord matching the specified type (e.g., "NAME").
    // BlueprintPure for Blueprint-friendly data access.
    // Parameters:
    // - Record: The FRecord to search.
    // - SubrecordType: The type of subrecord to find.
    // - OutSubrecord: The found FSubrecord, if any.
    // Returns: True if a matching subrecord was found, false otherwise.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Gets the first subrecord with the specified type, if it exists."))
    static bool GetSubrecordByType(const FRecord& Record, const FString& SubrecordType, FSubrecord& OutSubrecord);

    // Checks if a subrecord with the specified type exists.
    // BlueprintPure for conditional checks in Blueprints.
    // Parameters:
    // - Record: The FRecord to check.
    // - SubrecordType: The type of subrecord to look for.
    // Returns: True if a subrecord with the specified type exists, false otherwise.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Returns true if a subrecord with the specified type exists."))
    static bool HasSubrecord(const FRecord& Record, const FString& SubrecordType);

    // Returns the number of subrecords in the record.
    // BlueprintPure for use in Blueprint logic.
    // Parameters:
    // - Record: The FRecord to get the subrecord count from.
    // Returns: The number of subrecords as an int32.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Gets the number of subrecords in the record."))
    static int32 GetSubrecordCount(const FRecord& Record);

    // Validates the record (non-empty type, valid FormID for non-Morrowind).
    // BlueprintPure for validation in Blueprints.
    // Parameters:
    // - Record: The FRecord to validate.
    // - GameID: The game format to determine FormID validity.
    // Returns: True if the record is valid, false otherwise.
    UFUNCTION(BlueprintPure, Category = "Record", meta=(ToolTip="Returns true if the record is valid (non-empty type, valid FormID)."))
    static bool IsValidRecord(const FRecord& Record, EGameID GameID);

    // Clears all subrecords from the record.
    // BlueprintCallable for modifying records in Blueprints.
    // Parameters:
    // - Record: The FRecord to clear subrecords from.
    UFUNCTION(BlueprintCallable, Category = "Record", meta=(ToolTip="Clears all subrecords from the record."))
    static void ClearSubrecords(FRecord& Record);
};