NetSerialization.h

Go to the documentation of this file.

// Copyright Epic Games, Inc. All Rights Reserved.
 
/*=============================================================================
    NetworkSerialization.h: 
    Contains custom network serialization functionality.
=============================================================================*/
 
#pragma once
 
#include "Stats/Stats.h"
#include "UObject/ObjectMacros.h"
#include "UObject/Class.h"
#include "Misc/NetworkVersion.h"
#include "UObject/CoreNet.h"
#include "EngineLogs.h"
#include "Net/Core/Serialization/QuantizedVectorSerialization.h"
 
#include <type_traits>
 
#include "NetSerialization.generated.h"
 
template<typename ValueType>
bool SerializeOptionalValue(const bool bIsSaving, FArchive& Ar, ValueType& Value, const ValueType& DefaultValue)
{
    bool bNotDefault = (bIsSaving && (Value != DefaultValue));
    Ar.SerializeBits(&bNotDefault, 1);
    if (bNotDefault)
    {
        // Non-default value, need to save or load it.
        Ar << Value;
    }
    else if (!bIsSaving)
    {
        // Loading, and should use default
        Value = DefaultValue;
    }
 
    return bNotDefault;
}
 
template<typename ValueType>
bool NetSerializeOptionalValue(const bool bIsSaving, FArchive& Ar, ValueType& Value, const ValueType& DefaultValue, class UPackageMap* PackageMap)
{
    bool bNotDefault = (bIsSaving && (Value != DefaultValue));
    Ar.SerializeBits(&bNotDefault, 1);
    if (bNotDefault)
    {
        // Non-default value, need to save or load it.
        bool bLocalSuccess = true;
        Value.NetSerialize(Ar, PackageMap, bLocalSuccess);
    }
    else if (!bIsSaving)
    {
        // Loading, and should use default
        Value = DefaultValue;
    }
 
    return bNotDefault;
}
 
#if 0
 
USTRUCT()
struct FExampleStruct
{
    GENERATED_USTRUCT_BODY()
    
    
    bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
    {
        // Your code here!
        return true;
    }
 
    bool NetDeltaSerialize(FNetDeltaSerializeInfo & DeltaParms)
    {
        // Your code here!
        return true;
    }
}
 
template<>
struct TStructOpsTypeTraits< FExampleStruct > : public TStructOpsTypeTraitsBase2< FExampleStruct >
{
    enum 
    {
        WithNetSerializer = true,
        WithNetDeltaSerializer = true,
    };
};
 
#endif
 
namespace UE::Net::Private
{
 
// ScaleFactor is multiplied before send and divided by post receive. A higher ScaleFactor means more precision.
// MaxBitsPerComponent is the maximum number of bits to use per component. This is only a maximum. A header is
// written (size = Log2 (MaxBitsPerComponent)) to indicate how many bits are actually used. 
template<int32 ScaleFactor, int32 MaxBitsPerComponent>
bool LegacyReadPackedVector(FVector3f& Value, FArchive& Ar)
{
    uint32 Bits = 0;
 
    // Serialize how many bits each component will have
    Ar.SerializeInt( Bits, MaxBitsPerComponent );
 
    int32  Bias = 1<<(Bits+1);
    uint32 Max  = 1<<(Bits+2);
    uint32 DX   = 0;
    uint32 DY   = 0;
    uint32 DZ   = 0;
    
    Ar.SerializeInt( DX, Max );
    Ar.SerializeInt( DY, Max );
    Ar.SerializeInt( DZ, Max );
    
    float fact = (float)ScaleFactor;
 
    Value.X = (float)(static_cast<int32>(DX)-Bias) / fact;
    Value.Y = (float)(static_cast<int32>(DY)-Bias) / fact;
    Value.Z = (float)(static_cast<int32>(DZ)-Bias) / fact;
 
    return true;
}
 
}
 
template<int32 ScaleFactor, int32 MaxBitsPerComponent>
bool WritePackedVector(FVector3f Value, FArchive& Ar)
{
    return UE::Net::WriteQuantizedVector(ScaleFactor, Value, Ar);
}
 
template<int32 ScaleFactor, int32 MaxBitsPerComponent>
bool WritePackedVector(FVector3d Vector, FArchive& Ar)
{
    return UE::Net::WriteQuantizedVector(ScaleFactor, Vector, Ar);
}
 
template<int32 ScaleFactor, int32 MaxBitsPerComponent>
bool ReadPackedVector(FVector3f& Value, FArchive& Ar)
{
    if (Ar.EngineNetVer() >= FEngineNetworkCustomVersion::PackedVectorLWCSupport && Ar.EngineNetVer() != FEngineNetworkCustomVersion::Ver21AndViewPitchOnly_DONOTUSE)
    {
        return UE::Net::ReadQuantizedVector(ScaleFactor, Value, Ar);
    }
    else
    {
        return UE::Net::Private::LegacyReadPackedVector<ScaleFactor, MaxBitsPerComponent>(Value, Ar);
    }
}
 
template<int32 ScaleFactor, int32 MaxBitsPerComponent>
bool ReadPackedVector(FVector3d& Value, FArchive& Ar)
{
    if (Ar.EngineNetVer() >= FEngineNetworkCustomVersion::PackedVectorLWCSupport && Ar.EngineNetVer() != FEngineNetworkCustomVersion::Ver21AndViewPitchOnly_DONOTUSE)
    {
        return UE::Net::ReadQuantizedVector(ScaleFactor, Value, Ar);
    }
    else
    {
        FVector3f AsFloat;
        const bool bRet =  UE::Net::Private::LegacyReadPackedVector<ScaleFactor, MaxBitsPerComponent>(AsFloat, Ar);
        Value = FVector3d(AsFloat);
        return bRet;
    }
}
 
template<int32 ScaleFactor, int32 MaxBitsPerComponent>
bool SerializePackedVector(FVector3f& Value, FArchive& Ar)
{
    Ar.UsingCustomVersion(FEngineNetworkCustomVersion::Guid);
 
    if (Ar.EngineNetVer() >= FEngineNetworkCustomVersion::PackedVectorLWCSupport && Ar.EngineNetVer() != FEngineNetworkCustomVersion::Ver21AndViewPitchOnly_DONOTUSE)
    {
        return UE::Net::SerializeQuantizedVector<ScaleFactor>(Value, Ar);
    }
    else
    {
        check(Ar.IsLoading());
        return UE::Net::Private::LegacyReadPackedVector<ScaleFactor, MaxBitsPerComponent>(Value, Ar);
    }
}
 
template<int32 ScaleFactor, int32 MaxBitsPerComponent>
bool SerializePackedVector(FVector3d& Value, FArchive& Ar)
{
    Ar.UsingCustomVersion(FEngineNetworkCustomVersion::Guid);
 
    if (Ar.EngineNetVer() >= FEngineNetworkCustomVersion::PackedVectorLWCSupport && Ar.EngineNetVer() != FEngineNetworkCustomVersion::Ver21AndViewPitchOnly_DONOTUSE)
    {
        return UE::Net::SerializeQuantizedVector<ScaleFactor>(Value, Ar);
    }
    else
    {
        check(Ar.IsLoading());
        FVector3f AsFloat(Value);
        const bool bRet = UE::Net::Private::LegacyReadPackedVector<ScaleFactor, MaxBitsPerComponent>(AsFloat, Ar);
        Value = FVector3d(AsFloat);
        return bRet;
    }
}
 
// --------------------------------------------------------------
 
template<int32 MaxValue, uint32 NumBits>
struct TFixedCompressedFloatDetails
{
                                                                    // NumBits = 8:
    static constexpr int32 MaxBitValue = (1 << (NumBits - 1)) - 1;  //   0111 1111 - Max abs value we will serialize
    static constexpr int32 Bias = (1 << (NumBits - 1));             //   1000 0000 - Bias to pivot around (in order to support signed values)
    static constexpr int32 SerIntMax = (1 << (NumBits - 0));        // 1 0000 0000 - What we pass into SerializeInt
    static constexpr int32 MaxDelta = (1 << (NumBits - 0)) - 1;     //   1111 1111 - Max delta is
};
 
template<int32 MaxValue, uint32 NumBits, typename T UE_REQUIRES(std::is_floating_point_v<T> && NumBits < 32)>
bool WriteFixedCompressedFloat(const T Value, FArchive& Ar)
{
    using Details = TFixedCompressedFloatDetails<MaxValue, NumBits>;
 
    bool clamp = false;
    int64 ScaledValue;
    if ( MaxValue > Details::MaxBitValue )
    {
        // We have to scale this down
        const T Scale = T(Details::MaxBitValue)/MaxValue;
        ScaledValue = FMath::TruncToInt(Scale * Value);
    }
    else
    {
        // We will scale up to get extra precision. But keep is a whole number preserve whole values
        constexpr int32 Scale = Details::MaxBitValue / MaxValue;
        ScaledValue = FMath::RoundToInt( Scale * Value );
    }
 
    uint32 Delta = static_cast<uint32>(ScaledValue + Details::Bias);
 
    if (Delta > Details::MaxDelta)
    {
        clamp = true;
        Delta = static_cast<int32>(Delta) > 0 ? Details::MaxDelta : 0;
    }
 
    Ar.SerializeInt( Delta, Details::SerIntMax );
 
    return !clamp;
}
 
template<int32 MaxValue, uint32 NumBits, typename T UE_REQUIRES(std::is_floating_point_v<T> && NumBits < 32)>
bool ReadFixedCompressedFloat(T& Value, FArchive& Ar)
{
    using Details = TFixedCompressedFloatDetails<MaxValue, NumBits>;
 
    uint32 Delta;
    Ar.SerializeInt(Delta, Details::SerIntMax);
    T UnscaledValue = static_cast<T>( static_cast<int32>(Delta) - Details::Bias );
 
    if constexpr (MaxValue > Details::MaxBitValue)
    {
        // We have to scale down, scale needs to be a float:
        constexpr T InvScale = MaxValue / (T)Details::MaxBitValue;
        Value = UnscaledValue * InvScale;
    }
    else
    {
        constexpr int32 Scale = Details::MaxBitValue / MaxValue;
        constexpr T InvScale = T(1) / (T)Scale;
 
        Value = UnscaledValue * InvScale;
    }
 
    return true;
}
 
// --------------------------------------------------------------
// MaxValue is the max abs value to serialize. If abs value of any vector components exceeds this, the serialized value will be clamped.
// NumBits is the total number of bits to use - this includes the sign bit!
//
// So passing in NumBits = 8, and MaxValue = 2^8, you will scale down to fit into 7 bits so you can leave 1 for the sign bit.
template<int32 MaxValue, uint32 NumBits>
bool SerializeFixedVector(FVector3f &Vector, FArchive& Ar)
{
    if (Ar.IsSaving())
    {
        bool success = true;
        success &= WriteFixedCompressedFloat<MaxValue, NumBits>(Vector.X, Ar);
        success &= WriteFixedCompressedFloat<MaxValue, NumBits>(Vector.Y, Ar);
        success &= WriteFixedCompressedFloat<MaxValue, NumBits>(Vector.Z, Ar);
        return success;
    }
 
    ReadFixedCompressedFloat<MaxValue, NumBits>(Vector.X, Ar);
    ReadFixedCompressedFloat<MaxValue, NumBits>(Vector.Y, Ar);
    ReadFixedCompressedFloat<MaxValue, NumBits>(Vector.Z, Ar);
    return true;
}
 
template<int32 MaxValue, uint32 NumBits>
bool SerializeFixedVector(FVector3d &Vector, FArchive& Ar)
{
    if (Ar.IsSaving())
    {
        bool success = true;
        success &= WriteFixedCompressedFloat<MaxValue, NumBits>(Vector.X, Ar);
        success &= WriteFixedCompressedFloat<MaxValue, NumBits>(Vector.Y, Ar);
        success &= WriteFixedCompressedFloat<MaxValue, NumBits>(Vector.Z, Ar);
        return success;
    }
    else
    {
        ReadFixedCompressedFloat<MaxValue, NumBits>(Vector.X, Ar);
        ReadFixedCompressedFloat<MaxValue, NumBits>(Vector.Y, Ar);
        ReadFixedCompressedFloat<MaxValue, NumBits>(Vector.Z, Ar);
        return true;
    }
}
// --------------------------------------------------------------
 
USTRUCT(meta = (HasNativeMake = "/Script/Engine.KismetMathLibrary.MakeVector_NetQuantize", HasNativeBreak = "/Script/Engine.KismetMathLibrary.BreakVector_NetQuantize"))
struct FVector_NetQuantize : public FVector
{
    GENERATED_USTRUCT_BODY()
 
    FVector_NetQuantize() = default;
 
    explicit inline FVector_NetQuantize(EForceInit E)
    : FVector(E)
    {}
 
    inline FVector_NetQuantize(double InX, double InY, double InZ)
    : FVector(InX, InY, InZ)
    {}
 
    inline FVector_NetQuantize(const FVector &InVec)
    {
        FVector::operator=(InVec);
    }
 
    bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
    {
        bOutSuccess = SerializePackedVector<1, 20>(*this, Ar);
        return true;
    }
};
 
template<>
struct TStructOpsTypeTraits< FVector_NetQuantize > : public TStructOpsTypeTraitsBase2< FVector_NetQuantize >
{
    enum 
    {
        WithNetSerializer = true,
        WithNetSharedSerialization = true,
    };
};
 
USTRUCT(meta = (HasNativeMake = "/Script/Engine.KismetMathLibrary.MakeVector_NetQuantize10", HasNativeBreak = "/Script/Engine.KismetMathLibrary.BreakVector_NetQuantize10"))
struct FVector_NetQuantize10 : public FVector
{
    GENERATED_USTRUCT_BODY()
 
    FVector_NetQuantize10() = default;
 
    explicit inline FVector_NetQuantize10(EForceInit E)
    : FVector(E)
    {}
 
    inline FVector_NetQuantize10(double InX, double InY, double InZ)
    : FVector(InX, InY, InZ)
    {}
 
    inline FVector_NetQuantize10(const FVector &InVec)
    {
        FVector::operator=(InVec);
    }
 
    bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
    {
        bOutSuccess = SerializePackedVector<10, 24>(*this, Ar);
        return true;
    }
};
 
template<>
struct TStructOpsTypeTraits< FVector_NetQuantize10 > : public TStructOpsTypeTraitsBase2< FVector_NetQuantize10 >
{
    enum 
    {
        WithNetSerializer = true,
        WithNetSharedSerialization = true,
    };
};
 
USTRUCT(meta = (HasNativeMake = "/Script/Engine.KismetMathLibrary.MakeVector_NetQuantize100", HasNativeBreak = "/Script/Engine.KismetMathLibrary.BreakVector_NetQuantize100"))
struct FVector_NetQuantize100 : public FVector
{
    GENERATED_USTRUCT_BODY()
 
    FVector_NetQuantize100() = default;
 
    explicit inline FVector_NetQuantize100(EForceInit E)
    : FVector(E)
    {}
 
    inline FVector_NetQuantize100(double InX, double InY, double InZ)
    : FVector(InX, InY, InZ)
    {}
 
    inline FVector_NetQuantize100(const FVector3f& InVec) : FVector(InVec) {}
    inline FVector_NetQuantize100(const FVector3d& InVec) : FVector(InVec) {}
 
    bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
    {
        bOutSuccess = SerializePackedVector<100, 30>(*this, Ar);
        return true;
    }
};
 
template<>
struct TStructOpsTypeTraits< FVector_NetQuantize100 > : public TStructOpsTypeTraitsBase2< FVector_NetQuantize100 >
{
    enum 
    {
        WithNetSerializer = true,
        WithNetSharedSerialization = true,
    };
};
 
USTRUCT(meta = (HasNativeMake = "/Script/Engine.KismetMathLibrary.MakeVector_NetQuantizeNormal", HasNativeBreak = "/Script/Engine.KismetMathLibrary.BreakVector_NetQuantizeNormal"))
struct FVector_NetQuantizeNormal : public FVector
{
    GENERATED_USTRUCT_BODY()
 
    FVector_NetQuantizeNormal() = default;
 
    explicit inline FVector_NetQuantizeNormal(EForceInit E)
    : FVector(E)
    {}
 
    inline FVector_NetQuantizeNormal(double InX, double InY, double InZ)
    : FVector(InX, InY, InZ)
    {}
 
    inline FVector_NetQuantizeNormal(const FVector &InVec)
    {
        FVector::operator=(InVec);
    }
 
    bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
    {
        bOutSuccess = SerializeFixedVector<1, 16>(*this, Ar);
        return true;
    }
};
 
template<>
struct TStructOpsTypeTraits< FVector_NetQuantizeNormal > : public TStructOpsTypeTraitsBase2< FVector_NetQuantizeNormal >
{
    enum 
    {
        WithNetSerializer = true,
        WithNetSharedSerialization = true,
    };
};
 
// --------------------------------------------------------------
 
 
template<int32 MaxNum, typename T, typename A>
int32 SafeNetSerializeTArray_HeaderOnly(FArchive& Ar, TArray<T, A>& Array, bool& bOutSuccess)
{
    const uint32 NumBits = FMath::CeilLogTwo(MaxNum)+1;
    
    int32 ArrayNum = 0;
 
    // Clamp number of elements on saving side
    if (Ar.IsSaving())
    {
        ArrayNum = Array.Num();
        if (ArrayNum > MaxNum)
        {
            // Overflow. This is on the saving side, so the calling code is exceeding the limit and needs to be fixed.
            bOutSuccess = false;
            ArrayNum = MaxNum;
        }       
    }
 
    // Serialize num of elements
    Ar.SerializeBits(&ArrayNum, NumBits);
 
    // Preallocate new items on loading side
    if (Ar.IsLoading())
    {
        if (ArrayNum > MaxNum)
        {
            // If MaxNum doesn't fully utilize all bits that are needed to send the array size we can receive a larger value.
            bOutSuccess = false;
            ArrayNum = MaxNum;
        }
        Array.Reset();
        Array.AddDefaulted(ArrayNum);
    }
 
    return ArrayNum;
}
 
template<int32 MaxNum, typename T, typename A>
bool SafeNetSerializeTArray_Default(FArchive& Ar, TArray<T, A>& Array)
{
    bool bOutSuccess = true;
    int32 ArrayNum = SafeNetSerializeTArray_HeaderOnly<MaxNum, T, A>(Ar, Array, bOutSuccess);
 
    // Serialize each element in the array with the << operator
    for (int32 idx=0; idx < ArrayNum && Ar.IsError() == false; ++idx)
    {
        Ar << Array[idx];
    }
 
    // Return
    bOutSuccess &= !Ar.IsError();
    return bOutSuccess;
}
 
template<int32 MaxNum, typename T, typename A>
bool SafeNetSerializeTArray_WithNetSerialize(FArchive& Ar, TArray<T, A>& Array, class UPackageMap* PackageMap)
{
    bool bOutSuccess = true;
    int32 ArrayNum = SafeNetSerializeTArray_HeaderOnly<MaxNum, T, A>(Ar, Array, bOutSuccess);
 
    // Serialize each element in the array with the << operator
    for (int32 idx=0; idx < ArrayNum && Ar.IsError() == false; ++idx)
    {
        Array[idx].NetSerialize(Ar, PackageMap, bOutSuccess);
    }
 
    // Return
    bOutSuccess &= !Ar.IsError();
    return bOutSuccess;
}