Subrecord.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, which is used to specify game-specific parsing logic for subrecords.
#include "GameID.h"

// Includes the generated header for this file, which is automatically created by Unreal Engine for USTRUCT and UCLASS definitions, ensuring proper reflection and serialization.
#include "Subrecord.generated.h"

// Defines a struct that represents a subrecord, a common data structure in Bethesda game file formats (e.g., .ESM, .ESP, .ESL).
// Marked as BlueprintType to allow its use in Blueprints, making it accessible to designers and modders.
USTRUCT(BlueprintType)
struct FSubrecord
{
    GENERATED_BODY()

    // The 4-byte type identifier of the subrecord (e.g., "NAME", "DATA"), stored as an FString for easy manipulation in Blueprints.
    // BlueprintReadOnly and EditAnywhere allow it to be read in Blueprints and edited in the editor.
    UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Subrecord", meta=(ToolTip="4-byte type identifier (e.g., NAME)."))
    FString Type;

    // The raw binary data of the subrecord, stored as a TArray of uint8 (bytes), which can be interpreted based on the subrecord type.
    // Also BlueprintReadOnly and EditAnywhere for accessibility in Blueprints and the editor.
    UPROPERTY(BlueprintReadOnly, EditAnywhere, Category = "Subrecord", meta=(ToolTip="Raw binary data of the subrecord."))
    TArray<uint8> RawData;

    // Default constructor, initializing Type to an empty string and RawData to an empty array.
    FSubrecord()
        : Type(TEXT(""))
        , RawData()
    {
    }

    // Parameterized constructor to initialize the subrecord with a given type and raw data.
    FSubrecord(const FString& InType, const TArray<uint8>& InRawData)
        : Type(InType)
        , RawData(InRawData)
    {
    }

    // Equality operator to compare two subrecords based on their Type and RawData.
    // Useful for checking if two subrecords are identical, which can be important for data validation or comparison in Blueprints or C++.
    bool operator==(const FSubrecord& Other) const
    {
        return Type == Other.Type && RawData == Other.RawData;
    }

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

// Defines a hash function for FSubrecord, allowing it to be used in Unreal Engine's hash-based containers like TMap or TSet.
// Combines the hashes of Type and RawData using XOR to create a unique hash value.
// FORCEINLINE improves performance by suggesting the compiler inline this function.
FORCEINLINE uint32 GetTypeHash(const FSubrecord& Subrecord)
{
    return GetTypeHash(Subrecord.Type) ^ GetTypeHash(Subrecord.RawData);
}

// Declares a Blueprint Function Library class that provides utility functions for working with subrecords.
// This class is designed to be used in Blueprints, offering functions to read and manipulate subrecords.
// UNREALCREATIONENGINE_API ensures the class is exported for use across modules if needed.
UCLASS()
class UNREALCREATIONENGINE_API USubrecordHelper : public UBlueprintFunctionLibrary
{
    GENERATED_BODY()

public:
    // Static function to read a subrecord from an FArchive, which is an Unreal Engine serialization object.
    // This function is not exposed to Blueprints due to the use of FArchive, a C++-only type.
    // It serves as the core parsing logic, handling game-specific differences based on EGameID.
    // DataLengthOverride allows optional specification of data length, defaulting to 0 if unused.
    static bool ReadSubrecord(FSubrecord& OutSubrecord, FArchive& Archive, EGameID GameID, int32 DataLengthOverride = 0);

    // Blueprint-callable function to read a subrecord from a file specified by its path.
    // Abstracts the file reading process, creating an FArchive internally and calling ReadSubrecord.
    // Allows modders to read subrecords directly from files in Blueprints without dealing with low-level details.
    UFUNCTION(BlueprintCallable, Category = "Subrecord", meta=(ToolTip="Reads a subrecord from a file with game-specific logic."))
    static bool ReadSubrecordFromFile(FSubrecord& OutSubrecord, const FString& FilePath, EGameID GameID, int32 DataLengthOverride = 0);

    // Blueprint-callable function to read a subrecord from a byte array.
    // Useful for reading subrecords from in-memory data, such as data received over a network or pre-loaded assets.
    // Creates an FArchive from the byte array and calls ReadSubrecord.
    UFUNCTION(BlueprintCallable, Category = "Subrecord", meta=(ToolTip="Reads a subrecord from a byte array with game-specific logic."))
    static bool ReadSubrecordFromBytes(FSubrecord& OutSubrecord, const TArray<uint8>& ByteArray, EGameID GameID, int32 DataLengthOverride = 0);

    // Pure Blueprint function to get the Type of a subrecord.
    // Marked as BlueprintPure, indicating it has no side effects and can be used in Blueprint graphs for data access.
    UFUNCTION(BlueprintPure, Category = "Subrecord", meta=(ToolTip="Gets the 4-byte type identifier."))
    static FString GetType(const FSubrecord& Subrecord);

    // Pure Blueprint function to get the RawData of a subrecord.
    // Also BlueprintPure, allowing modders to access the binary data in Blueprints for further processing or display.
    UFUNCTION(BlueprintPure, Category = "Subrecord", meta=(ToolTip="Gets the raw binary data."))
    static TArray<uint8> GetRawData(const FSubrecord& Subrecord);
};