Devtricks

Iris - Network serializers

2026-02-08T00:00:00+00:00

In this article we will explore Iris’ serialization by implementing a custom network serializer.

Introduction

Unreal Engine’s legacy replication system offers a very simplistic way to support replication to non-POD properties by implementing NetSerialize or NetDeltaSerialize, depending on whether atomic or differential replication is needed. In this model, serialization logic is executed as part of building replication data and may be re-run per connection, including when sending initial state to newly connected players.

Iris serialization differs in that it Quantizes and stores replicated state internally, allowing work to be reused across relevant connections. By centralizing and sharing this work instead of performing it separately per client, Iris reduces per-connection overhead thus, improving scalability.

However, implementing custom serializers in Iris is more involved than in the legacy system, as there are many moving pieces one must understand before writing one.

As Epic developer Peter Engstrom explained (source):

Generally speaking we would like for people to not having to 
implement serializer at all and cover the most common use cases.

...

...not implementing one if one can avoid it can be a big 
maintenance win.

- Peter Engstrom

That said, there are still scenarios where a custom serializer is necessary - such as edge cases not covered natively or for maximum bandwidth optimization (e.g., the engine’s own FHitResult custom serialization). In this article, we’ll explore the key pieces involved and implement a serializer for a simple struct.

Network Serialization in Iris

In the Iris replication system, the serialization process follows a very specific pipeline to ensure data is compressed, compared, and applied to our target. Here is the sequence of events in the order they occur:

Quantize: Converts high-precision “Source” data (like a 32-bit float) into a compressed “Internal” representation (like a scaled integer).
IsEqual: Called during dirty-checking to determine if quantized state changed since last replication. If true, serialization is skipped entirely.
Serialize: Takes the quantized “Internal” state and writes it into the bitstream using a FNetBitStreamWriter.
Deserialize: Reads the bits from the FNetBitStreamReader and reconstructs the “Internal” (quantized) state on the receiving end.
Dequantize: Reverses the quantization process, converting the quantized data back into the original “External” types (like a FVector).
Apply: Serializers that want to be selective about which members to modify in the target instance when applying state should implement Apply where the serializer is responsible for setting the members of the target instance.

So… what is sent over the network? You send over the network exactly and precisely what you write in your FNetBitStreamWriter within your Serialize function.

Note: Serialize and Deserialize are the only strictly required functions. Quantize and Dequantize are optional unless your “Source” data (like a class) must be converted into a simpler “Internal” POD type for serialization. Apply is optional and only used if you need custom logic to write the final value back to the target.

Serializing a struct in Iris

Before we get started I recommend you opening NetSerializer.h to have an inline documentation at hand.

The struct we will be serializing in this example is the following one:

USTRUCT(BlueprintType)
struct FMyStruct
{
	GENERATED_BODY()
	
	UPROPERTY(EditAnywhere, BlueprintReadOnly)
	FVector StartLocation = FVector::ZeroVector;

	UPROPERTY(EditAnywhere, BlueprintReadOnly)
	FVector ImpactPoint = FVector::ZeroVector;

	UPROPERTY(BlueprintReadOnly)
	bool bHasImpactPoint = false;

	UPROPERTY(BlueprintReadOnly, NotReplicated)
	float Distance;
};

Our serialization intentions are as follows:

Serialize always StartLocation and bHasImpactPoint
If bHasImpactPoint, serialize ImpactPoint, but only if StartLocation has a different value (thus saving some bits).
Compute Distance on the receiving end.

Note that we desire to serialize the struct with the intention of sending around on RPCs and replicate it.

Before we start

Remember that the intention of this article is purely informative and, as I mentioned in the introduction, it is important to understand the burden and time consumption involved in maintaining custom Iris serializers. In most cases, it is preferable to design within Iris’ constraints rather than introduce a custom serializer. Before writing one, carefully consider whether your use case really needs it - and most importantly (specially if you are new to Iris), don’t guess performance: profile.

I decided to serialize FMyStruct for this tutorial since it is a non-polymorphyc struct that doesn’t contain pointer references or dynamic state (e.g. FString or TArray), so in my opinion it is the perfect candidate for an introduction. With that said, Iris supports polymorphic serializers and a series of tools to enable dynamic serialization.

Since the documentation is scarce at the time of writing, I recommend the reader to look at the Iris\Serialization\ directory in GithHub, specially I suggest paying attention to the following files for what concerns this article:

NetSerializer.h: Here you will find the definition and documentation of each variable, function, class and struct that can be part of your network serializers. Contains very valuable information of how Iris’ serializers work.
PolymorphicNetSerializerImpl.h: In this header you will find the definition and documentation for implementing polymorphic struct serializers (such as FGameplayEffectContextHandle).
NetSerializerArrayStorage.h: Main hub for dynamic storage serialization.
Iris/ReplicationState/PropertyNetSerializerInfoRegistry.h: Here you will find a series of useful macros to register/forward your net serializers.

Pay attention to the comments within the showcased code sections, they provide important context!

Declaring the serializer

The first step to do when declaring a serializer is figuring out which serializer config we need, in this case, since our struct isn’t polymorphic, we use FNetSerializerConfig:

Header file (.h):

USTRUCT()
struct FMyStructNetSerializerConfig : public FNetSerializerConfig
{
	GENERATED_BODY()
};

namespace UE::Net
{
	UE_NET_DECLARE_SERIALIZER(FMyStructNetSerializer, MYGAME_API);
}

Note: Polymorphic structs require to use FPolymorphicStructNetSerializerConfig.

Registering the serializer

If we want replication for our type to occur through our custom Iris net serializer, we need to register it to the FPropertyNetSerializerInfoRegistry via some macros:

Implementation file (.cpp):

namespace UE::Net
{
	struct FMyStructNetSerializer
	{
		...

	private:
		class FRegistryDelegates final : public FNetSerializerRegistryDelegates
		{
		public:
			virtual ~FRegistryDelegates() override;
			virtual void OnPreFreezeNetSerializerRegistry() override;
		};

		static FRegistryDelegates RegistryDelegates;
	};

	FMyStructNetSerializer::FRegistryDelegates FMyStructNetSerializer::RegistryDelegates;

	...
}

namespace UE::Net
{
	static const FName PropertyNetSerializerRegistry_NAME_MyStruct("MyStruct");
	UE_NET_IMPLEMENT_NAMED_STRUCT_NETSERIALIZER_INFO(PropertyNetSerializerRegistry_NAME_MyStruct, FMyStructNetSerializer);

	FMyStructNetSerializer::FRegistryDelegates::~FRegistryDelegates()
	{
		UE_NET_UNREGISTER_NETSERIALIZER_INFO(PropertyNetSerializerRegistry_NAME_MyStruct);
	}

	void FMyStructNetSerializer::FRegistryDelegates::OnPreFreezeNetSerializerRegistry()
	{
		UE_NET_REGISTER_NETSERIALIZER_INFO(PropertyNetSerializerRegistry_NAME_MyStruct);
	}
}

In the case we are inheriting our struct from one that has already a net serializer implemented, we can forward* their serialization.

Note: Net Serializer forwarding allows you to reuse an existing serializer for a different type. For instance, LyraGameplayEffectContext.cpp uses FGameplayEffectContext for serialization via the UE_NET_IMPLEMENT_FORWARDING_NETSERIALIZER_AND_REGISTRY_DELEGATES macro. The engine also offers another utility to forward serialization of a Struct to a last resort net serializer via the UE_NET_IMPLEMENT_NAMED_STRUCT_LASTRESORT_NETSERIALIZER_AND_REGISTRY_DELEGATES macro (don’t use unless extrictly necessary).

Implementing the serializer

Now that we’ve let Iris know it should use our serializer, let’s fill the gaps, we’ll start by defining our serializer struct:

Implementation file (.cpp):

namespace UE::Net
{
	struct FMyStructNetSerializer
	{
		static const uint32 Version = 0;
		
		/** These flags help to define the amount of data we'll need to replicate for a specific event. */
		enum EReplicationFlags : uint8
		{
			HasImpact = 1U,
			ImpactDifferentStart = 2U,
		};

		/** Number of flags in the above enum. */
		static constexpr uint32 ReplicatedFlagCount = 2U;
		
		/** 
		* Quantized storage representing our type. Sizes are determined by type's QuantizeType.
		* this is not the amount of data we send around
		*/
		struct FQuantizedType
		{
			uint64 StartLocation[4];
			uint64 ImpactPoint[4];
			uint8 ReplicationFlags;
		};

		/**
		* Needed in order to calculate external state size and alignment
		* and provide default implementations of some functions.
		*/
		typedef FMyStruct SourceType;

		/**
		* A typedef for the QuantizedType is optional unless the SourceType isn't POD. Assumed to be SourceType if not specified.
		* The QuantizedType needs to be POD.
		*/
		typedef FQuantizedType QuantizedType;
		
		typedef FMyStructNetSerializerConfig ConfigType;

		/** DefaultConfig is optional but highly recommended as the serializer can then be used without requiring special configuration setup. */
		static const ConfigType DefaultConfig;
		
		static void Serialize(FNetSerializationContext&, const FNetSerializeArgs&);
		static void Deserialize(FNetSerializationContext&, const FNetDeserializeArgs&);
		static void Quantize(FNetSerializationContext&, const FNetQuantizeArgs& Args);
		static void Dequantize(FNetSerializationContext&, const FNetDequantizeArgs& Args);		
		static bool IsEqual(FNetSerializationContext&, const FNetIsEqualArgs&);
		static void Apply(FNetSerializationContext&, const FNetApplyArgs&);

	private:
		/** Registering our Net Serializer */
		class FRegistryDelegates final : public FNetSerializerRegistryDelegates
		{
		public:
			virtual ~FRegistryDelegates() override;
			virtual void OnPreFreezeNetSerializerRegistry() override;
		};

		static FRegistryDelegates RegistryDelegates;
	};

	const FMyStructNetSerializer::ConfigType FMyStructNetSerializer::DefaultConfig;
	FMyStructNetSerializer::FRegistryDelegates FMyStructNetSerializer::RegistryDelegates;
	
	/** Macro that Constructs our Net Serializer and provides Iris our struct's size and alignment. */
	UE_NET_IMPLEMENT_SERIALIZER(FMyStructNetSerializer);

	...
}

Once it’s defined we can start implementing each one of our methods immediately below UE_NET_IMPLEMENT_SERIALIZER(FMyStructNetSerializer);. For that, we’ll go in the order of operations defined in the above section.

1. Quantize

First, we Quantize our data:

Implementation file (.cpp):

void FMyStructNetSerializer::Quantize(FNetSerializationContext& Context, const FNetQuantizeArgs& Args)
{
	const SourceType& Source = *reinterpret_cast<const SourceType*>(Args.Source);
	QuantizedType TempValue = {};

	// We set our replication flags based on "Source" state.
	uint8 ReplicationFlags = 0;
	ReplicationFlags |= Source.bHasImpactPoint ? EReplicationFlags::HasImpact : 0U;
	ReplicationFlags |= Source.StartLocation != Source.ImpactPoint ? EReplicationFlags::ImpactDifferentStart : 0U;

	TempValue.ReplicationFlags = ReplicationFlags;

	// Start location quantize
	{
		// We use the FVectorNetQuantizeNetSerializer to Quantize the StartLocation vector.
		const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

		FNetQuantizeArgs MemberArgs = Args;
		MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
		MemberArgs.Source = NetSerializerValuePointer(&Source.StartLocation);
		MemberArgs.Target = NetSerializerValuePointer(&TempValue.StartLocation[0]);
		VectorSerializer.Quantize(Context, MemberArgs);
	}

	// Impact point quantize
	if ((TempValue.ReplicationFlags & HasImpact) && (TempValue.ReplicationFlags & ImpactDifferentStart))
	{
		const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

		FNetQuantizeArgs MemberArgs = Args;
		MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
		MemberArgs.Source = NetSerializerValuePointer(&Source.ImpactPoint);
		MemberArgs.Target = NetSerializerValuePointer(&TempValue.ImpactPoint[0]);
		VectorSerializer.Quantize(Context, MemberArgs);
	}

	// Finally assign by ref our quantized data to target
	QuantizedType& Target = *reinterpret_cast<QuantizedType*>(Args.Target);
	Target = TempValue;
}

In this step, we set our ReplicationFlags based on the Source state. If bHasImpactPoint is false, we skip both the quantization and transmission of ImpactPoint. Similarly, we compare ImpactPoint to StartLocation; if they are identical, we avoid sending ImpactPoint over the network, as we can simply use the StartLocation value we’ve already provided.

The remainder of the implementation is syntax sugar, primarily acting as a wrapper to forward the specialized Quantize calls to the appropriate sub-serializers.

Note: Further Quantization is possible in FVector, see: FVectorNetQuantize10NetSerializer, FVectorNetQuantize100NetSerializer in PackedVectorNetSerializers.h.

2. IsEqual

This function is a requirement if your FNetSerializer has a Quantize function. IsEqual job is to compare the Quantized (internal) state of a property against its previously cached version to see if anything has actually changed.

If IsEqual returns true, Iris assumes the data is identical and completely skips serialization, saving you from sending a redundant packet. Note that you have to implement both branches, when the data is quantized, and dequantized.

Implementation file (.cpp):
  
bool FMyStructNetSerializer::IsEqual(FNetSerializationContext& Context, const FNetIsEqualArgs& Args)
{
	if (Args.bStateIsQuantized)
	{
		// If the data is quantized we can simply Memcmp it
		const QuantizedType& QuantizedValue0 = *reinterpret_cast<const QuantizedType*>(Args.Source0);
		const QuantizedType& QuantizedValue1 = *reinterpret_cast<const QuantizedType*>(Args.Source1);
		return FPlatformMemory::Memcmp(&QuantizedValue0, &QuantizedValue1, sizeof(QuantizedType)) == 0;
	}
	else
	{
		const SourceType& SourceValue0 = *reinterpret_cast<const SourceType*>(Args.Source0);
		const SourceType& SourceValue1 = *reinterpret_cast<const SourceType*>(Args.Source1);

		if (SourceValue0.bHasImpactPoint != SourceValue1.bHasImpactPoint)
		{
			return false;
		}
		
		/**
		* When the data is dequantize it, we quantize it again to compare it
		* This is a bit expensive, so bear in mind, you could also perform
		* a normal == comparison.
		*/
		QuantizedType QuantizedValue0 = {};
		QuantizedType QuantizedValue1 = {};

		FNetQuantizeArgs QuantizeArgs = {};
		QuantizeArgs.NetSerializerConfig = Args.NetSerializerConfig;

		QuantizeArgs.Source = NetSerializerValuePointer(Args.Source0);
		QuantizeArgs.Target = NetSerializerValuePointer(&QuantizedValue0);
		Quantize(Context, QuantizeArgs);

		QuantizeArgs.Source = NetSerializerValuePointer(Args.Source1);
		QuantizeArgs.Target = NetSerializerValuePointer(&QuantizedValue1);
		Quantize(Context, QuantizeArgs);

		return FPlatformMemory::Memcmp(&QuantizedValue0, &QuantizedValue1, sizeof(QuantizedType)) == 0;
	}
}

3. Serialize

The next step is to send the quantized data over the network:

Implementation file (.cpp):

void FMyStructNetSerializer::Serialize(FNetSerializationContext& Context, const FNetSerializeArgs& Args)
{
	// Acquire the quantized data.
	const QuantizedType& Value = *reinterpret_cast<const QuantizedType*>(Args.Source);
	
	// This is where we write to send fluff through the network
	FNetBitStreamWriter* Writer = Context.GetBitStreamWriter();

	// We send our replication flags (using just 2 bits)
	const uint8 ReplicationFlags = Value.ReplicationFlags;
	Writer->WriteBits(ReplicationFlags, ReplicatedFlagCount);

	// Start location
	{
		UE_NET_TRACE_SCOPE(StartLocation, *Writer, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
		const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

		FNetSerializeArgs VectorNetSerializeArgs = Args;
		VectorNetSerializeArgs.Source = NetSerializerValuePointer(&Value.StartLocation[0]);
		VectorNetSerializeArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
		VectorSerializer.Serialize(Context, VectorNetSerializeArgs);
	}
	
	// Impact point
	if ((Value.ReplicationFlags & HasImpact) && (Value.ReplicationFlags & ImpactDifferentStart))
	{
		UE_NET_TRACE_SCOPE(ImpactPoint, *Writer, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
		const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

		FNetSerializeArgs VectorNetSerializeArgs = Args;
		VectorNetSerializeArgs.Source = NetSerializerValuePointer(&Value.ImpactPoint[0]);
		VectorNetSerializeArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
		VectorSerializer.Serialize(Context, VectorNetSerializeArgs);
	}
}

As seen above, we write our replication flags directly to the FNetBitStreamWriter using only 2 bits. The other two properties simply forward their serialization logic to the FVectorNetQuantizeNetSerializer. By checking the flags first, we ensure ImpactPoint bits are only written when necessary, keeping the packet small.

4. Deserialize

Third, we deserialize the quantized data:

Implementation file (.cpp):

void FMyStructNetSerializer::Deserialize(FNetSerializationContext& Context, const FNetDeserializeArgs& Args)
{
	QuantizedType& Target = *reinterpret_cast<QuantizedType*>(Args.Target);

	// This is where we read the quantized data from
	FNetBitStreamReader* Reader = Context.GetBitStreamReader();
	
	// We read the flags (2 bits) and store them in Target
	Target.ReplicationFlags = Reader->ReadBits(ReplicatedFlagCount);

	// Start location
	{
		UE_NET_TRACE_SCOPE(StartLocation, *Reader, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
		const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

		FNetDeserializeArgs MemberArgs = Args;
		MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
		MemberArgs.Target = NetSerializerValuePointer(&Target.StartLocation[0]);
		VectorSerializer.Deserialize(Context, MemberArgs);
	}

	// Impact point
	if ((Target.ReplicationFlags & HasImpact) && (Target.ReplicationFlags & ImpactDifferentStart))
	{
		UE_NET_TRACE_SCOPE(ImpactPoint, *Reader, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
		const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

		FNetDeserializeArgs MemberArgs = Args;
		MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
		MemberArgs.Target = NetSerializerValuePointer(&Target.ImpactPoint[0]);
		VectorSerializer.Deserialize(Context, MemberArgs);
	}
}

Deserialize will read from the FNetBitStreamReader the quantized data we serialized. Note how our replication flags get passed along and are actually avoiding us to read data we don’t need.

5. Dequantize

After we deserialize we need to recompose our data back to a dequantized state:

Implementation file (.cpp):

void FMyStructNetSerializer::Dequantize(FNetSerializationContext& Context, const FNetDequantizeArgs& Args)
{
	const QuantizedType& Source = *reinterpret_cast<const QuantizedType*>(Args.Source);
	SourceType& Target = *reinterpret_cast<SourceType*>(Args.Target);

	const uint8 ReplicationFlags = Source.ReplicationFlags;
	
	// Start location
	{
		const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

		FNetDequantizeArgs MemberArgs = Args;
		MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
		MemberArgs.Source = NetSerializerValuePointer(&Source.StartLocation[0]);
		MemberArgs.Target = NetSerializerValuePointer(&Target.StartLocation);
		VectorSerializer.Dequantize(Context, MemberArgs);
	}

	/**
	* The logic below Dequantizes ImpactPoint if deemed necessary by our flags.
	* ImpactPoint is set to StartLocation if they aren't different.
	*/
	if (ReplicationFlags & HasImpact)
	{
		if (ReplicationFlags & ImpactDifferentStart)
		{
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetDequantizeArgs MemberArgs = Args;
			MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			MemberArgs.Source = NetSerializerValuePointer(&Source.ImpactPoint[0]);
			MemberArgs.Target = NetSerializerValuePointer(&Target.ImpactPoint);
			VectorSerializer.Dequantize(Context, MemberArgs);
		}
		else
		{
			Target.ImpactPoint = Target.StartLocation;
		}
	}
	else
	{
		// We reset it to 0 intentionally, although we could simply skip it.
		Target.ImpactPoint = FVector::ZeroVector;
	}
	
	Target.bHasImpactPoint = (ReplicationFlags & HasImpact) ? 1 : 0;
}

After deserializing, we must recompose the data into its original form. Here, we dequantize StartLocation and check our flags to determine how to handle ImpactPoint. If the flags indicate the impact point is identical to the start, we simply copy the value over, otherwise, we either dequantize ImpactPoint or zero it out.

By the end of this process, the Target struct is fully restored. Note that while I left Distance out here to handle it in Apply, it would be equally valid to compute it during this stage.

6. (Optional) Apply

In this example Apply is not necessary, but I’m implementing it for demonstration. This step occurs after dequantization and is responsible for writing the data into the actual target. While Iris does this automagically by default, overriding it allows you to skip specific properties or perform additional logic/fixup - like calculating Distance - before the game uses the values.

Implementation file (.cpp):

void FMyStructNetSerializer::Apply(FNetSerializationContext& Context, const FNetApplyArgs& Args)
{
	const SourceType& Source = *reinterpret_cast<const SourceType*>(Args.Source);
	SourceType& Target = *reinterpret_cast<SourceType*>(Args.Target);

	Target.bHasImpactPoint = Source.bHasImpactPoint;
	Target.ImpactPoint = Source.ImpactPoint;
	Target.StartLocation = Source.StartLocation;
	Target.Distance = (Target.ImpactPoint - Target.StartLocation).Size();
}

Et voila, serializer done! That was… interesting!

Full code

I provide below the full code of the complete serializer so that you can copy and paste it directly without the need of going fragment by fragment:

Header file (.h): 

USTRUCT(BlueprintType)
struct FMyStruct
{
	GENERATED_BODY()
	
	UPROPERTY(EditAnywhere, BlueprintReadOnly)
	FVector StartLocation = FVector::ZeroVector;

	UPROPERTY(EditAnywhere, BlueprintReadOnly)
	FVector ImpactPoint = FVector::ZeroVector;

	UPROPERTY(BlueprintReadOnly)
	bool bHasImpactPoint = false;

	UPROPERTY(BlueprintReadOnly, NotReplicated)
	float Distance;
};

USTRUCT()
struct FMyStructNetSerializerConfig : public FNetSerializerConfig
{
	GENERATED_BODY()
};

namespace UE::Net
{
	UE_NET_DECLARE_SERIALIZER(FMyStructNetSerializer, MYGAME_API);
}

Implementation file (.cpp):

namespace UE::Net
{
	struct FMyStructNetSerializer
	{
		// Version
		static const uint32 Version = 0;
		
		enum EReplicationFlags : uint8
		{
			HasImpact = 1U,
			ImpactDifferentStart = 2U,
		};

		static constexpr uint32 ReplicatedFlagCount = 2U;
		
		struct FQuantizedType
		{
			uint64 StartLocation[4];
			uint64 ImpactPoint[4];
			uint8 ReplicationFlags;
		};

		typedef FMyStruct SourceType;
		typedef FQuantizedType QuantizedType;
		typedef FMyStructNetSerializerConfig ConfigType;

		static const ConfigType DefaultConfig;
		
		static void Serialize(FNetSerializationContext&, const FNetSerializeArgs&);
		static void Deserialize(FNetSerializationContext&, const FNetDeserializeArgs&);
		static void Quantize(FNetSerializationContext&, const FNetQuantizeArgs& Args);
		static void Dequantize(FNetSerializationContext&, const FNetDequantizeArgs& Args);
		static bool IsEqual(FNetSerializationContext&, const FNetIsEqualArgs&);

		static void Apply(FNetSerializationContext&, const FNetApplyArgs&);

	private:
		class FRegistryDelegates final : public FNetSerializerRegistryDelegates
		{
		public:
			virtual ~FRegistryDelegates() override;
			virtual void OnPreFreezeNetSerializerRegistry() override;
		};

		static FRegistryDelegates RegistryDelegates;
	};

	const FMyStructNetSerializer::ConfigType FMyStructNetSerializer::DefaultConfig;
	FMyStructNetSerializer::FRegistryDelegates FMyStructNetSerializer::RegistryDelegates;
	
	UE_NET_IMPLEMENT_SERIALIZER(FMyStructNetSerializer);
	
	void FMyStructNetSerializer::Serialize(FNetSerializationContext& Context, const FNetSerializeArgs& Args)
	{
		const QuantizedType& Value = *reinterpret_cast<const QuantizedType*>(Args.Source);

		FNetBitStreamWriter* Writer = Context.GetBitStreamWriter();

		// Replicated flags
		const uint8 ReplicationFlags = Value.ReplicationFlags;
		Writer->WriteBits(ReplicationFlags, ReplicatedFlagCount);

		// Start location
		{
			UE_NET_TRACE_SCOPE(StartLocation, *Writer, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetSerializeArgs VectorNetSerializeArgs = Args;
			VectorNetSerializeArgs.Source = NetSerializerValuePointer(&Value.StartLocation[0]);
			VectorNetSerializeArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			VectorSerializer.Serialize(Context, VectorNetSerializeArgs);
		}
		
		// Impact point
		if ((Value.ReplicationFlags & HasImpact) && (Value.ReplicationFlags & ImpactDifferentStart))
		{
			UE_NET_TRACE_SCOPE(ImpactPoint, *Writer, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetSerializeArgs VectorNetSerializeArgs = Args;
			VectorNetSerializeArgs.Source = NetSerializerValuePointer(&Value.ImpactPoint[0]);
			VectorNetSerializeArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			VectorSerializer.Serialize(Context, VectorNetSerializeArgs);
		}
	}

	void FMyStructNetSerializer::Deserialize(FNetSerializationContext& Context, const FNetDeserializeArgs& Args)
	{
		QuantizedType TempValue = {};

		FNetBitStreamReader* Reader = Context.GetBitStreamReader();
		TempValue.ReplicationFlags = Reader->ReadBits(ReplicatedFlagCount);

		// Start location
		{
			UE_NET_TRACE_SCOPE(StartLocation, *Reader, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetDeserializeArgs MemberArgs = Args;
			MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			MemberArgs.Target = NetSerializerValuePointer(&TempValue.StartLocation[0]);
			VectorSerializer.Deserialize(Context, MemberArgs);
		}

		// Impact point
		if ((TempValue.ReplicationFlags & HasImpact) && (TempValue.ReplicationFlags & ImpactDifferentStart))
		{
			UE_NET_TRACE_SCOPE(ImpactPoint, *Reader, Context.GetTraceCollector(), ENetTraceVerbosity::Verbose);
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetDeserializeArgs MemberArgs = Args;
			MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			MemberArgs.Target = NetSerializerValuePointer(&TempValue.ImpactPoint[0]);
			VectorSerializer.Deserialize(Context, MemberArgs);
		}

		QuantizedType& Target = *reinterpret_cast<QuantizedType*>(Args.Target);
		Target = TempValue;
	}

	void FMyStructNetSerializer::Quantize(FNetSerializationContext& Context, const FNetQuantizeArgs& Args)
	{
		const SourceType& Source = *reinterpret_cast<const SourceType*>(Args.Source);
		QuantizedType TempValue = {};

		uint8 ReplicationFlags = 0;

		ReplicationFlags |= Source.bHasImpactPoint ? EReplicationFlags::HasImpact : 0U;
		ReplicationFlags |= Source.StartLocation != Source.ImpactPoint ? EReplicationFlags::ImpactDifferentStart : 0U;

		TempValue.ReplicationFlags = ReplicationFlags;

		// Start location
		{
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetQuantizeArgs MemberArgs = Args;
			MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			MemberArgs.Source = NetSerializerValuePointer(&Source.StartLocation);
			MemberArgs.Target = NetSerializerValuePointer(&TempValue.StartLocation[0]);
			VectorSerializer.Quantize(Context, MemberArgs);
		}

		// Impact point
		if ((TempValue.ReplicationFlags & HasImpact) && (TempValue.ReplicationFlags & ImpactDifferentStart))
		{
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetQuantizeArgs MemberArgs = Args;
			MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			MemberArgs.Source = NetSerializerValuePointer(&Source.ImpactPoint);
			MemberArgs.Target = NetSerializerValuePointer(&TempValue.ImpactPoint[0]);
			VectorSerializer.Quantize(Context, MemberArgs);
		}

		// Finally copy-over quantized data to target
		QuantizedType& Target = *reinterpret_cast<QuantizedType*>(Args.Target);
		Target = TempValue;
	}

	void FMyStructNetSerializer::Dequantize(FNetSerializationContext& Context, const FNetDequantizeArgs& Args)
	{
		const QuantizedType& Source = *reinterpret_cast<const QuantizedType*>(Args.Source);
		SourceType& Target = *reinterpret_cast<SourceType*>(Args.Target);

		const uint8 ReplicationFlags = Source.ReplicationFlags;
		
		// Start location
		{
			const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

			FNetDequantizeArgs MemberArgs = Args;
			MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
			MemberArgs.Source = NetSerializerValuePointer(&Source.StartLocation[0]);
			MemberArgs.Target = NetSerializerValuePointer(&Target.StartLocation);
			VectorSerializer.Dequantize(Context, MemberArgs);
		}

		// Impact point
		if (ReplicationFlags & HasImpact)
		{
			if (ReplicationFlags & ImpactDifferentStart)
			{
				const FNetSerializer& VectorSerializer = UE_NET_GET_SERIALIZER(FVectorNetQuantizeNetSerializer);

				FNetDequantizeArgs MemberArgs = Args;
				MemberArgs.NetSerializerConfig = NetSerializerConfigParam(VectorSerializer.DefaultConfig);
				MemberArgs.Source = NetSerializerValuePointer(&Source.ImpactPoint[0]);
				MemberArgs.Target = NetSerializerValuePointer(&Target.ImpactPoint);
				VectorSerializer.Dequantize(Context, MemberArgs);
			}
			else
			{
				Target.ImpactPoint = Target.StartLocation;
			}
		}
		else
		{
			Target.ImpactPoint = FVector::ZeroVector;
		}
		
		Target.bHasImpactPoint = (ReplicationFlags & HasImpact) ? 1 : 0;
	}

	bool FMyStructNetSerializer::IsEqual(FNetSerializationContext& Context, const FNetIsEqualArgs& Args)
	{
		if (Args.bStateIsQuantized)
		{
			const QuantizedType& QuantizedValue0 = *reinterpret_cast<const QuantizedType*>(Args.Source0);
			const QuantizedType& QuantizedValue1 = *reinterpret_cast<const QuantizedType*>(Args.Source1);
			return FPlatformMemory::Memcmp(&QuantizedValue0, &QuantizedValue1, sizeof(QuantizedType)) == 0;
		}
		else
		{
			const SourceType& SourceValue0 = *reinterpret_cast<const SourceType*>(Args.Source0);
			const SourceType& SourceValue1 = *reinterpret_cast<const SourceType*>(Args.Source1);
	
			if (SourceValue0.bHasImpactPoint != SourceValue1.bHasImpactPoint)
			{
				return false;
			}
			
			QuantizedType QuantizedValue0 = {};
			QuantizedType QuantizedValue1 = {};
	
			FNetQuantizeArgs QuantizeArgs = {};
			QuantizeArgs.NetSerializerConfig = Args.NetSerializerConfig;
	
			QuantizeArgs.Source = NetSerializerValuePointer(Args.Source0);
			QuantizeArgs.Target = NetSerializerValuePointer(&QuantizedValue0);
			Quantize(Context, QuantizeArgs);
	
			QuantizeArgs.Source = NetSerializerValuePointer(Args.Source1);
			QuantizeArgs.Target = NetSerializerValuePointer(&QuantizedValue1);
			Quantize(Context, QuantizeArgs);
	
			return FPlatformMemory::Memcmp(&QuantizedValue0, &QuantizedValue1, sizeof(QuantizedType)) == 0;
		}
	}

	void FMyStructNetSerializer::Apply(FNetSerializationContext& Context, const FNetApplyArgs& Args)
	{
		const SourceType& Source = *reinterpret_cast<const SourceType*>(Args.Source);
		SourceType& Target = *reinterpret_cast<SourceType*>(Args.Target);

		Target.bHasImpactPoint = Source.bHasImpactPoint;
		Target.ImpactPoint = Source.ImpactPoint;
		Target.StartLocation = Source.StartLocation;
		Target.Distance = (Target.ImpactPoint - Target.StartLocation).Size();

		UE_LOG(LogTemp, Warning, TEXT("FMyStructNetSerializer::Apply"));
	}
}

namespace UE::Net
{
	static const FName PropertyNetSerializerRegistry_NAME_MyStruct("MyStruct");
	UE_NET_IMPLEMENT_NAMED_STRUCT_NETSERIALIZER_INFO(PropertyNetSerializerRegistry_NAME_MyStruct, FMyStructNetSerializer);
	
	FMyStructNetSerializer::FRegistryDelegates::~FRegistryDelegates()
	{
		UE_NET_UNREGISTER_NETSERIALIZER_INFO(PropertyNetSerializerRegistry_NAME_MyStruct);
	}
	
	void FMyStructNetSerializer::FRegistryDelegates::OnPreFreezeNetSerializerRegistry()
	{
		UE_NET_REGISTER_NETSERIALIZER_INFO(PropertyNetSerializerRegistry_NAME_MyStruct);
	}
}

Conclusion

Well, that was certainly an adventure! I’m sure you can now see why Peter Engstrom said, “Not implementing one if one can avoid it can be a big maintenance win”.

Iris serializers offer many more options than I was able to explore in this article. I encourage you all to do your own experiments and exploration (please, don’t just take my word for it!), let this post serve as a helping hand to get you started!

And… yeah! Feel free to contact me (and follow me! hehe) if you find any issues with the article or have any questions about the whole topic.

Enjoy, vori.

Iris - Replication filters

2025-11-09T00:00:00+00:00

In this article we will dive a tiny little bit on Iris’ replication system and we’ll learn how to setup a simple replication filter.

Introduction - Being an early adopter

Most of my articles/tutorials revolve around the vanilla replication system of Unreal Engine, which is still pretty industry standard to date. However, Epic’s been cooking now for several years a new implementation to their replication system called Iris.

Iris has been designed from the ground up to minimize the CPU overhead introduced by property replication by maintaining a quantized copy of all replicated data, sharing work amongst connections, providing thus, the opportunity to do more work in parallel; alongside Iris’ default push-based replication model.

Epic’s intention with Iris is for it to become industry standard, some games, like Splitgate, are making use of it. Although as Epic points out on the Iris’ FAQ - the system is still Experimental and lacks support of basic features like replays.

With that said, early adoption helps the industry tremendously to uncover hidden bugs and priorize developments efforts, and sometimes, even cross-collaborations arise! See the recent CD Projekt + Epic work in The Witcher 4 technical demo:

The replication filter

A replication filter is a system that determines what objects are replicated to which connections.

We’ve done this already in my previous proc-gen article overriding Unreal’s legacy AActor::IsNetRelevantFor function. This function is evaluated whenever the Actor’s replication is considered for update, which is normally tied to its NetUpdateFrequency. Returning false for an arbitrary connection would mean that such connection won’t get sent the last replication update for the Actor.

bool AProjectile::IsNetRelevantFor(const AActor* RealViewer, const AActor* ViewTarget, const FVector& SrcLocation) const
{
	if (const APlayerController* PC = Cast<APlayerController>(RealViewer))
	{
		// The projectile's owner is never relevant since it runs its own local simulation
		const APlayerController* ProjectileOnwer = GetPlayerOwner();
		return (GetPlayerOwner() != PC) && (Super::IsNetRelevantFor(RealViewer, ViewTarget, SrcLocation));
	}
	return Super::IsNetRelevantFor(RealViewer, ViewTarget, SrcLocation);
}

In the code above, we are disallowing replication to the projectile’s owner. As pointed aswell in the procgen article, there are probably better ways to do this through the Replication Graph.

The replication filter in Iris

However, Iris does not support the Replication Graph, since it has its own scheme for prioritizing and filtering objects to different connections. In this section, we’ll learn how to setup a simple replication filter in Iris, mimicking the example we saw above.

void AProjectile::BeginPlay()
{
	Super::BeginPlay();
	
	if (HasAuthority())
	{
		UReplicationSystem* ReplicationSystem = UE::Net::FReplicationSystemUtil::GetReplicationSystem(this);
		UEngineReplicationBridge* ActorReplicationBridge = UE::Net::FReplicationSystemUtil::GetActorReplicationBridge(this);
		UE::Net::FNetRefHandle RepActorNetRefHandle = ActorReplicationBridge->GetReplicatedRefHandle(this);

		constexpr int32 MaxConnections = 100; // Replace for max amount of connections supported on your game.
		TBitArray<> Connections;
		Connections.Init(false, MaxConnections);

		const APlayerController* PlayerController = GetPlayerOwner();
		if (PlayerController && PlayerController->GetNetConnection())
		{
			UE::Net::FConnectionHandle ConnectionId = PlayerController->GetNetConnection()->GetConnectionHandle();
			Connections.Insert(true, ConnectionId.GetParentConnectionId());
			ReplicationSystem->SetConnectionFilter(RepActorNetRefHandle, Connections, UE::Net::ENetFilterStatus::Disallow);
		}
	}
}

In the above code we’ve disallowed replication to the projectile owner player. Note how the above code is event-driven rather than poll-based.

Similar logic applies to add allowed connections by using UE::Net::ENetFilterStatus::Allow.

The same way, to clear the filter, we can simply do the following:

void AProjectile::ClearFilter()
{	
	if (HasAuthority())
	{
		UReplicationSystem* ReplicationSystem = UE::Net::FReplicationSystemUtil::GetReplicationSystem(this);
		UEngineReplicationBridge* ActorReplicationBridge = UE::Net::FReplicationSystemUtil::GetActorReplicationBridge(this);
		UE::Net::FNetRefHandle RepActorNetRefHandle = ActorReplicationBridge->GetReplicatedRefHandle(this);

		TBitArray<> NoConnections;
		ReplicationSystem->SetConnectionFilter(RepActorNetRefHandle, NoConnections, UE::Net::ENetFilterStatus::Disallow);

	}
}

With this, now you know how to skip or allow replication to specific connections, however, this is just a start!

Additional resources

Besides this post, you can also take a look in these resources/files:

Engine\Plugins\Runtime\ReplicationSystemTestPlugin\Source\Private\Tests\ReplicationSystem\Filtering\TestFiltering.cpp: A test suite for filtering replication to connections.
Official Epic filtering documentation: Provides more in depth examples as well as other types of filtering - such as group or dynamic filters.

Finally, I strongly recommend everyone to take a look at Epic’s Unreal Fest talk about Iris, where they dive into the design behind the Iris replication system:

Thanks Epic!

Conclusion

Today we explored together a simple way to set up replication filters in Iris with a very trivial example.

As I always say, I encourage you all to do your own experiments and exploration, let this article serve as a helping hand to get started in the matter!

As always, feel free to contact me (and follow me! hehe) if you find any issues with the article or have any questions about the whole topic.

Enjoy, vori.

Networked Physics and UNetworkPhysicsComponent in Unreal Engine 5.4

2024-05-04T00:00:00+00:00

In a previous article we saw a very premature version of the physics prediction system that now bundles with Unreal Engine. Now, in Unreal Engine 5.4 the system has matured a lot and in todays article we will do a hands-on together.

Introduction

Predicting and correcting physics is one of the most complicated topics when it comes to network prediction. The nature of the complexity comes by the fact that if we hit a chain of physics objects on the client, we’d expect all the physics to react instantaneously, without having to wait for the server. But not only that, these physics objects should smoothly correct their position on the clients if there are incongruences with what the server expects. So you can imagine how difficult this can get with complex physics chain reactions.

Fortunately, Epic has been working lately in a solution for all these problems bundled in their Networked Physics solution. Before digging onto the matter, I strongly recommend everyone to take a look to this article, where Epic digs further on the different physics replication modes they brought to the engine with this new system.

Note: This code is deprecated in modern Unreal Engine versions (UE 5.7 +). Please refer to this tutorial by MBobbo (a key contributor to the system) for the updated implementation.

Making a rolling boulder

I decided to make this post as I couldnt find any simple example around the engine on how to use properly the new Networked Physics system. The ‘rolling boulder’ we are going to create may serve as a “hello world” for those that would like to get introduced in the matter, as this new system can be used to make any type of vehicle or physics controllable object. Because… what’s easier than a rolling sphere?

However, this tutorial comes with a big disclaimer, as we are in a very early r&d phase, and we dont have yet any official technical documentation on the matter, other than the engine itself, and… my own assumptions!

So… as I always say, don’t trust random articles from the internet and please, do your own research! If you think that any of the information shared in here is off, you can always contact me on twitter and we can fix it together as a community effort! Now… lets get into it :D!

The setup

In order to activate the feature, open Project Settings and within the Physics tab, turn on Enable Physics Prediction.

There are other settings you might want to explore!

Then, lets not forget to enable the following settings in the same tab:

One of the core components of the new physics system is the UNetworkPhysicsComponent, and to date, this component enforces us to wrap our movement code in another component, so we’ll have a physics movement component and a controllable pawn that holds said component, let’s create the pawn:

Pay close attention to the replication settings, as they will play a relevant role in our implementation. Worth noting that the physics replication mode we are choosing for our boulder is Resimulation; in addition im leveraging a really low Net Update Frequency (not using Iris yet!), simply to show how great this system is.

And to finish up the setup, let me share with you my root static mesh settings that we use for the physics simulation:

Main important points from the image above is that, we need to turn on physics simulation, set the collision channel to something sensitive, and finally, ensure that the Component Replicates flag is off, we don’t need it, we are replicating the transform of our boulder by other means.

Note: It is highly recommended to raise the replicated movement quantization levels so that the physics replication system will have more data to work on, you can find these settings under Replication -> Advanced.

Coding the physics boulder movement

The way I’ve found other systems in the engine forward their physics input to the server is by means of the UNetworkPhysicsComponent. This component not only takes care of that, it also mantains historical records of both inputs and states, enabling the rewind and resimulation of physics simulations, crucial for maintaining consistency and accuracy in multiplayer environments. So, let’s make use of these features!

The UNetworkPhysicsComponent requires us to create two structs, which hold the input and the state of our physics simulation:

/** Ball inputs from the player controller */
USTRUCT()
struct FBallInputs
{
	GENERATED_BODY()

	FBallInputs()
		: SteeringInput(0.f)
		, ThrottleInput(0.f)
		, TravelDirection(FRotator::ZeroRotator)
		, JumpCount(0)
	{}

	// Steering output to physics system. Range -1...1
	UPROPERTY()
	float SteeringInput;

	// Accelerator output to physics system. Range -1...1
	UPROPERTY()
	float ThrottleInput;

	// Desired direction
	UPROPERTY()
	FRotator TravelDirection;

	/** Counter for user jumps */
	UPROPERTY()
	int32 JumpCount;
};

/** Ball state data that will be used in the state history to rewind the simulation at some point in time */
USTRUCT()
struct FNetworkBallStates : public FNetworkPhysicsData
{
	GENERATED_BODY()

	/**  Serialize data function that will be used to transfer the struct across the network */
	bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess);
};

template<>
struct TStructOpsTypeTraits<FNetworkBallStates> : public TStructOpsTypeTraitsBase2<FNetworkBallStates>
{
	enum
	{
		WithNetSerializer = true,
	};
};

/** Ball Inputs data that will be used in the inputs history to be applied while simulating */
USTRUCT()
struct FNetworkBallInputs : public FNetworkPhysicsData
{
	GENERATED_BODY()

	/** List of incoming control inputs coming from the local client */
	UPROPERTY()
	FBallInputs BallInputs;

	/**  Apply the data onto the network physics component */
	virtual void ApplyData(UActorComponent* NetworkComponent) const override;

	/**  Build the data from the network physics component */
	virtual void BuildData(const UActorComponent* NetworkComponent) override;

	/**  Serialize data function that will be used to transfer the struct across the network */
	bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess);

	/** Interpolate the data in between two inputs data */
	virtual void InterpolateData(const FNetworkPhysicsData& MinData, const FNetworkPhysicsData& MaxData) override;

	/** Merge data into this input */
	virtual void MergeData(const FNetworkPhysicsData& FromData) override;
};

template<>
struct TStructOpsTypeTraits<FNetworkBallInputs> : public TStructOpsTypeTraitsBase2<FNetworkBallInputs>
{
	enum
	{
		WithNetSerializer = true,
	};
};

struct FPhysicsBallTraits
{
	using InputsType = FNetworkBallInputs;
	using StatesType = FNetworkBallStates;
};

Note that, in my case I don’t require to keep track of any state of my boulder, but I still need to create the struct since the system requires it so.

Following next, the declaration of my movement class, I decided to use a UPawnMovementComponent in this case:

CLASS(meta = (BlueprintSpawnableComponent))
class MYPROJECT_API URollingBallMovementComponent : public UPawnMovementComponent
{
	GENERATED_UCLASS_BODY()
	
public:

	/** Overridden to allow registration with components NOT owned by a Pawn. */
	virtual void SetUpdatedComponent(USceneComponent* NewUpdatedComponent) override;

	/** Return true if it's suitable to create a physics representation of the Ball at this time */
	virtual bool ShouldCreatePhysicsState() const override;

	/** Used to create any physics engine information for this component */
	virtual void OnCreatePhysicsState() override;

	/** Used to shut down and physics engine structure for this component */
	virtual void OnDestroyPhysicsState() override;

	void InitializeBall();

	virtual void AsyncPhysicsTickComponent(float DeltaTime, float SimTime);

	UFUNCTION(BlueprintCallable)
	void SetThrottleInput(float InThrottle);

	UFUNCTION(BlueprintCallable)
	void SetSteeringInput(float InSteering);

	UFUNCTION(BlueprintCallable)
	void SetTravelDirectionInput(FRotator InTravelDirection);

	UFUNCTION(BlueprintCallable)
	void Jump();

public:

	// Ball inputs
	FBallInputs BallInputs;

	// Ball state
	FTransform BallWorldTransform;
	FVector BallForwardAxis;
	FVector BallRightAxis;

private:

	UPROPERTY()
	TObjectPtr<UNetworkPhysicsComponent> NetworkPhysicsComponent = nullptr;

	Chaos::FRigidBodyHandle_Internal* RigidHandle;
	FBodyInstance* BodyInstance;
	int32 PreviousJumpCount = 0;
};

And finally, the implementation:

URollingBallMovementComponent::URollingBallMovementComponent(const FObjectInitializer& ObjectInitializer)
	: Super(ObjectInitializer)
{
	SetIsReplicatedByDefault(true);

	static const FName NetworkPhysicsComponentName(TEXT("PC_NetworkPhysicsComponent"));
	NetworkPhysicsComponent = CreateDefaultSubobject<UNetworkPhysicsComponent, UNetworkPhysicsComponent>(NetworkPhysicsComponentName);
	NetworkPhysicsComponent->SetNetAddressable(); // Make DSO components net addressable
	NetworkPhysicsComponent->SetIsReplicated(true);
}

void URollingBallMovementComponent::SetUpdatedComponent(USceneComponent* NewUpdatedComponent)
{
	UNavMovementComponent::SetUpdatedComponent(NewUpdatedComponent);
	PawnOwner = NewUpdatedComponent ? Cast<APawn>(NewUpdatedComponent->GetOwner()) : nullptr;
}

bool URollingBallMovementComponent::ShouldCreatePhysicsState() const
{
	if (!IsRegistered() || IsBeingDestroyed())
	{
		return false;
	}

	// only create 'Physics' Ball in game
	UWorld* World = GetWorld();
	if (World->IsGameWorld())
	{
		FPhysScene* PhysScene = World->GetPhysicsScene();

		if (PhysScene && UpdatedComponent && UpdatedPrimitive)
		{
			return true;	
		}
	}

	return false;
}

void URollingBallMovementComponent::OnCreatePhysicsState()
{
	Super::OnCreatePhysicsState();

	// only create Physics Ball in game
	UWorld* World = GetWorld();
	if (World->IsGameWorld())
	{
		InitializeBall();
			
		if (NetworkPhysicsComponent)
		{
			NetworkPhysicsComponent->CreateDataHistory<FPhysicsBallTraits>(this);
		}
	}

	// Initializing phys handle
	if (UPrimitiveComponent* Mesh = Cast<UPrimitiveComponent>(UpdatedComponent))
	{
		BodyInstance = Mesh->GetBodyInstance();
	}	
}

void URollingBallMovementComponent::OnDestroyPhysicsState()
{
	Super::OnDestroyPhysicsState();

	if (UpdatedComponent)
	{
		UpdatedComponent->RecreatePhysicsState();
	}
	if (NetworkPhysicsComponent)
	{
		NetworkPhysicsComponent->RemoveDataHistory();
	}
}

void URollingBallMovementComponent::InitializeBall()
{
	if (UpdatedComponent && UpdatedPrimitive)
	{
		SetAsyncPhysicsTickEnabled(true);
	}
}

void URollingBallMovementComponent::AsyncPhysicsTickComponent(float DeltaTime, float SimTime)
{
	Super::AsyncPhysicsTickComponent(DeltaTime, SimTime);

	if (!BodyInstance)
	{
		return;
	}

	if (const auto Handle = BodyInstance->ActorHandle)
	{
		RigidHandle = Handle->GetPhysicsThreadAPI();
	}
	
	UWorld* World = GetWorld();
	if (World && RigidHandle)
	{
		const FTransform WorldTM(RigidHandle->R(), RigidHandle->X());
		BallWorldTransform = WorldTM;
		BallForwardAxis = BallWorldTransform.GetUnitAxis(EAxis::X);
		BallRightAxis = BallWorldTransform.GetUnitAxis(EAxis::Y);

		const FVector DesiredForwardVector = BallInputs.TravelDirection.Vector();
		const FVector DesiredRightVector = FRotationMatrix(BallInputs.TravelDirection).GetScaledAxis(EAxis::Y);

		// Update the simulation forces/impulses...
		if (BallInputs.JumpCount != PreviousJumpCount)
		{
			RigidHandle->SetLinearImpulse(FVector(0,0,500.f), true);
		}

		RigidHandle->AddForce(BallInputs.ThrottleInput * DesiredForwardVector * 80000.f, true);
		RigidHandle->AddForce(BallInputs.SteeringInput * DesiredRightVector * 80000.f, false);

		// Set prev frame vars
		PreviousJumpCount = BallInputs.JumpCount;
	}
}

void URollingBallMovementComponent::SetThrottleInput(float InThrottle)
{
	const float FinalThrottle = FMath::Clamp(InThrottle, -1.f, 1.f);
	BallInputs.ThrottleInput = InThrottle;
}

void URollingBallMovementComponent::SetSteeringInput(float InSteering)
{
	const float FinalSteering = FMath::Clamp(InSteering, -1.f, 1.f);
	BallInputs.SteeringInput = InSteering;
}

void URollingBallMovementComponent::SetTravelDirectionInput(FRotator InTravelDirection)
{
	BallInputs.TravelDirection = InTravelDirection;
}

void URollingBallMovementComponent::Jump()
{
	BallInputs.JumpCount++;
}

bool FNetworkBallInputs::NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
{
	FNetworkPhysicsData::SerializeFrames(Ar);

	Ar << BallInputs.SteeringInput;
	Ar << BallInputs.ThrottleInput;
	Ar << BallInputs.TravelDirection;
	Ar << BallInputs.JumpCount;

	bOutSuccess = true;
	return bOutSuccess;
}

void FNetworkBallInputs::ApplyData(UActorComponent* NetworkComponent) const
{
	if (URollingBallMovementComponent* BallMover = Cast<URollingBallMovementComponent>(NetworkComponent))
	{
		BallMover->BallInputs = BallInputs;
	}
}

void FNetworkBallInputs::BuildData(const UActorComponent* NetworkComponent)
{
	if (NetworkComponent)
	{
		if (const URollingBallMovementComponent* BallMover = Cast<const URollingBallMovementComponent>(NetworkComponent))
		{
			BallInputs = BallMover->BallInputs;
		}
	}
}

void FNetworkBallInputs::InterpolateData(const FNetworkPhysicsData& MinData, const FNetworkPhysicsData& MaxData)
{
	const FNetworkBallInputs& MinInput = static_cast<const FNetworkBallInputs&>(MinData);
	const FNetworkBallInputs& MaxInput = static_cast<const FNetworkBallInputs&>(MaxData);

	const float LerpFactor = MaxInput.LocalFrame == LocalFrame
		? 1.0f / (MaxInput.LocalFrame - MinInput.LocalFrame + 1) // Merge from min into max
		: (LocalFrame - MinInput.LocalFrame) / (MaxInput.LocalFrame - MinInput.LocalFrame); // Interpolate from min to max


	BallInputs.ThrottleInput = FMath::Lerp(MinInput.BallInputs.ThrottleInput, MaxInput.BallInputs.ThrottleInput, LerpFactor);
	BallInputs.SteeringInput = FMath::Lerp(MinInput.BallInputs.SteeringInput, MaxInput.BallInputs.SteeringInput, LerpFactor);
	BallInputs.TravelDirection = FMath::Lerp(MinInput.BallInputs.TravelDirection, MaxInput.BallInputs.TravelDirection, LerpFactor);
	BallInputs.JumpCount = LerpFactor < 0.5 ? MinInput.BallInputs.JumpCount : MaxInput.BallInputs.JumpCount;
}

void FNetworkBallInputs::MergeData(const FNetworkPhysicsData& FromData)
{
	// Perform merge through InterpolateData
	InterpolateData(FromData, *this);
}

bool FNetworkBallStates::NetSerialize(FArchive& Ar, UPackageMap* Map, bool& bOutSuccess)
{
	FNetworkPhysicsData::SerializeFrames(Ar);
	return true;
}

Note that the implementation above is just a “hello world”, it doesnt do any input sanitization in the server for simplicity.

If you did everything correctly, now you should have something as follows:

The above video was recorded with average latency everywhere (server and client). At the end of the video I display the difference between jump inputs being sent through the NetworkPhysicsComponent, and Jumps performed only on the client; you can see how the later get corrected, making the local sphere snap back to the ground.

Note: The Physics Resimulation replication mode currently has some bugs in PIE, where if you try to add more than one client, it starts behaving erratically.

Implementation details

Now that we all are in the same page, I think its worth noting different details from the implementation from above.

At the start of our physics simulation (OnCreatePhysicsState), we let the NetworkPhysicsComponent know which data it should handle for our physics simulations. It’s like magic – super simple to use! We just need to specify the data’s type, the component holding it, and then implement overrides for input and state handling. ApplyData and BuildData are key here; they smoothly transfer data between our movement component and the NetworkPhysicsComponent, which takes care of all the nitty-gritty details of state and input management for us.

The input processing goes like this: during AsyncPhysicsTickComponent, inputs are first applied locally, then the server catches up. This allows for predictive autonomous proxy simulation followed by server validation

Now, we’re mostly dealing with continuous input streams, like movement directions or camera orientation (TravelDirection), which are straightforward. However, sending one-frame events, like a jump action, is still a puzzle. I’ve experimented with boolean input variables, such as bJump, but encountered issues – the server sometimes missed the update because the variable reset before the NetworkPhysicsComponent could transmit it. This led me to try alternative approaches, like using JumpCount to increment with each jump action. However, I’m not entirely certain if this method aligns with Epic’s recommended practices.

Another thing worth to note is that, if you look at the other physics examples around in the engine, they explicitly process the input in OnPhysScenePreTick, part of the Physics Scene. I’m however not sure of the extra-implications of this and I would love to know; but at least, in this minimal example we got something working in less than 400 lines of code.

Additional resources

Besides this post, you can also take a look at different systems from the engine that also make use of this technology:

UChaosVehicleMovementComponent: Chaos simple vehicle system.
UMoverNetworkPhysicsLiaisonComponent: Physics-based Mover.

Finally, I strongly recommend everyone to take a look at Epic’s GDC talk about Chaos, where they talk a bit about their new physics system:

Thanks Epic!

Conclusion

Today we explored together the UNetworkPhysicsComponent and coded together a “hello world” physics boulder.

Note that this toy example uses a very simple setup for preview purposes. But I’d like to support it following the best practices, for that reason I’ll be mantaining it in my experimental arcade vehicle sample repo. Feel free to open issues or pull request to the sample, I’ll be vigilante, the main intention is to create a “hello world” example the community could learn from. And of course, along with that I’ll try to keep this article updated!

As always, feel free to contact me (and follow me! hehe) if you find any issues with the article or have any questions about the whole topic.

Enjoy, vori.

How to use the Contextual Animation Plugin in your Multiplayer Games (UE 5.3+) w/ Doğa

2024-03-01T00:00:00+00:00

In this post we will learn how to use the Contextual Animation Plugin for our synced animations. This article wouldn’t be possible without Doğa’s contributions.

Introduction

Unreal Engine released with a Contextual Animation System to create synced animations for specific actions, we could hear about it first in the Unreal Engine 5 revelation video:

This system allows us to play animations that require some sort of synchronization, in both transform, and timing. In order to activate the feature, open Edit and within Plugins windows, turn on Motion Warping and Contextual Animation.

How to setup a Contextual Animation

All the Actors part of a Contextual Animation require to have a ContextualAnimSceneActorComponent. The Plugin handles alignment of these Actors using Motion Warping. Therefore, only the Actor initiating the interaction and requiring synchronization towards the designated transform needs to be equipped with a MotionWarpingComponent.

Contextual Anim Scene

Once we have granted all the required components to our Actors we can create our first Contextual Anim Scene Asset. For that, create a Contextual Anim Scene (CAS) asset in the Content Browser.

If we open the newly created asset, we’ll find a viewport, a timeline and a series of properties we’ll tackle next. But first let’s focus on the Roles Asset.

This Data Asset defines the multiple roles by name in our Contextual Animation as in the image below.

We recommend to provide somewhat generic names, as these assets are meant to be reused amongst multiple Contextual Anim Scenes. In the image Interactor is the Actor that starts the interaction, and Target is the Actor we interact with.

Then, in the CAS asset we assign the Roles Asset we just created, and for our example, we set Target as the Primary Role (the Actor we want to interact with). Then, add as many entries to the Override Preview Data array as participants are in our contextual animation, defined also by the Roles Asset.

In our case we have two participants, so we extend the array with two elements as follows:

In my case, the female mannequin starts the interaction.

Note: Contextual Animations can also be used against non-animated Actors (ie: sitting on a chair), which would also need to be part of your Roles Asset.

Animation Sequence requirements (and Montages)

After configuring our CAS asset with all the required properties we are ready to start creating animation tracks. But before we start, let’s take a look at the requirements of the Animation Sequences composing our animation track.

The Contextual Animations System employs motion warping internally to warp the selected participants to a specific Transform. This ensures that animations are played correctly at the intended time and position, allowing for perfectly synced animations during gameplay, consistent with the original vision from the animation software (Maya, Blender…).

In our case, the Interactor should move towards Target before starting our takedown animation, for that we’ll enable Root Motion in the Animation Sequence of the Montage of our Interactor and then, we’ll add a Motion Warping Anim Notify State for the duration that we want the warp to last (the shorter, the faster our character will reach to the destination to play the Contextual Animation).

The Warp Target Name will be used later to define the synchronization transform in the CAS asset.

Note: Visit the motion warping documentation to know more about this feature and all the variables you’ll find in the Anim Notify State.

In our case, our Target Montage doesn’t need any additional configuration. However, if any character animation within the CAS Asset entails movement, Root Motion will be essential for their Montages, so that the character will move alongside the Root Bone’s movement.

Note: Each animation track in the CAS asset consists of the combination of animations for all of our participants.

Creating a new track

To create a new animation track click on the button New AnimSet located at the top of the CAS Asset; it will promp you a window in which you can add a montage per participant (if applicable).

You can also tweak the Collision Behaviour between the participants and their attachment logic. For example, in the case of a takedown animation we would insert the attacker’s montage in the Interactor animation and the death montage in the Target animation.

After adding the montages, you can click on them in the animation track to adjust further parameters. Here we’ll find Mesh to scene, which will let you adjust the transform of your Actor to play the synced animation properly.

If done properly you’ll have something like this:

Our preview looks great! But if we want this to work during gameplay we have to configure motion warping in our CAS Asset. For that, add a new member on the Warp Point Definitions array, then on its properties write the name you’ve wrote in Warp Target Name in the previous section using the Primary Actor (Target) as the Mode, and finally, click on Update Warp Points. This will add a warping point in our Target Actor which will make the Motion Warping configured in our montage warp towards it.

Once done, we can add more AnimSets if we’d like to add varied montages to this Contextual Animation (ie: different takedown animations), the Selection Criteria will ensure we play a proper one.

Contextual Animation Selection Criteria

As previously indicated, a CAS can have multiple AnimSets, where each can contain its own set of Selection Criterias. In Contextual Animation Assets (CAS), the Selection Criteria sets the rules for determining which Anim Set fits the bill.

In simple terms, these Selection Criterias help pick out the right AnimSet for the job. At the beginning of the execution, the AnimSets undergo evaluation in a random order. The first one that meets all the Selection Criteria is chosen. But if none of them meet the criteria, no one will get selected.

Adding a Selection Criteria

To add a selection criteria, navigate to the Montage added within your CAS. Within it, you’ll discover a Selection Criteria array.

Within this array, you can incorporate multiple selection criterias, which can be defined using both C++ and Blueprints. The plugin comes with a few:

Contextual Anim Selection Criterion Cone: Checks if the target is inside a user defined Cone. If it is, the Criteria passes.
Contextual Anim Selection Criterion Distance: Checks that the target is withing a distance range, can be evaluated in 3D or 2D.
Contextual Anim Selection Criterion Trigger Area: Checks if the target is in a user defined 3D area, if it is, the Criterion passes.

Some of these criterias come with debug visualization.

How to play a Contextual Animation during gameplay

Playing Contextual Animations in Blueprints and C++ is very easy, all it takes is 2 functions:

In the example above I’m playing the contextual animation inside an Ability instigated by the attacker, therefore Primary will be the Victim and Secondary the attacker, like in the CAS. Once our bindings are setup, we can start the Contextual Anim Scene.

Extra functionalities

The Contextual Anim Scene Actor Component defines a series of delegates we can use to react to different events occouring during the Anim Set.

Contextual Animations can also be earlied out if desired by calling EarlyOutContextualAnimScene from Contextual Anim Scene Actor Component.

Multiplayer details

Contextual Animations implement multiplayer support for you, so you shouldn’t have to worry about anything when it comes to making them work in multiplayer.

At the time of writing Contextual Animations should be called only from the server or from an autonomous proxy (ROLE_AutonomousProxy) and they do not support prediction. To give an example of this, in the Ability example from above I’m starting the Anim Scene only on Authority.

If you’ve done everything correctly, you’ll be able to do many cool things (courtesy of Doğa):

Conclusion

Hey!

I hope you found interesting this pseudo article/tutorial.

This was possible thanks to my friend Doğa, who not only proactively shared his knowledge with us by the means of collaborating in the writing of this article, but also shared two very cool examples he crafted. I think a very nice way to thank him would be to follow on his social media!

Now as a I always say, happy deving!

Enjoy, vori.

Mover in Unreal Engine 5.4

2024-02-03T00:00:00+00:00

Unreal Engine introduced Mover 2.0 in 5.4, this post showcases my first (second) impressions and an overview of the system.

Introduction

Epic Games recently introduced a new and experimental Movement Component in 5.4, called Mover, so… let’s take a look.

In order to activate the feature, open Edit and within Plugins windows, turn on the following:

How does it work?

The following video I’ve recorded showcases the state of the system at the release date of the Plugin during UE 5.4:

Note: At the time of writing, Mover 2.0 is only obtainable through the git version of the engine, branch 5.4 or ue5-main.

Additional resources

In the video I mention two resources:

Conclusion

Thanks for watching!

Hopefully, and as I also said previously, I you are as hyped as I am with this new feature! :)

Enjoy, vori.

Convenient Multiplayer Logging in UE5

2024-01-04T00:00:00+00:00

Hello and happy new year! Many of you asked me how I measured the accuracy in my network clock article.

This technique can be generalized to infinite use cases, so I decided to generalize it and write about it in this small article. So I hope you like it and find it useful.

Overview

This article explains how to access the server instance from a client in PIE (Play in Editor), thus, easing logging of value discrepancy between server and client. This technique has served me in the past to debug synced variables. In essence, expect something as follows:

LogEntry: Client Stamina: 29.25 | Server Stamina: 29.23

As you can see, the same log entry contains the value of the stamina in the client and in the server captured in the same frame. The trick here is accessing the server instance from the client instance, this trick will only work in the editor, so its strictly useful for editor debugging/logging.

The implementation

To obtain a Server Player Controller from a client, first we have to find the server world, only existing within the editor context:

UWorld* UMyDevelopmentStatics::FindPlayInEditorAuthorityWorld()
{
	check(GEngine);

	// Find the server world (any PIE world will do, in case they are running without a dedicated server, but the ded. server world is ideal)
	UWorld* ServerWorld = nullptr;
#if WITH_EDITOR
	for (const FWorldContext& WorldContext : GEngine->GetWorldContexts())
	{
		if (WorldContext.WorldType == EWorldType::PIE)
		{
			if (UWorld* TestWorld = WorldContext.World())
			{
				if (WorldContext.RunAsDedicated)
				{
					// Ideal case
					ServerWorld = TestWorld;
					break;
				}
				else if (ServerWorld == nullptr)
				{
					ServerWorld = TestWorld;
				}
				else
				{
					// We already have a candidate, see if this one is 'better'
					if (TestWorld->GetNetMode() < ServerWorld->GetNetMode())
					{
						return ServerWorld;
					}
				}
			}
		}
	}
#endif
	return ServerWorld;
}

The function above was conveniently implemented in Lyra, so we can make use of it. The next function will use the previous function to get the Server Player Controller:

APlayerController* UMyDevelopmentStatics::FindPlayInEditorAuthorityPlayerController(APlayerController* ClientController)
{
#if WITH_EDITOR
	UWorld* ServerWorld = UMyDevelopmentStatics::FindPlayInEditorAuthorityWorld();
	if (ServerWorld != nullptr)
	{
		for (FConstPlayerControllerIterator Iterator = ServerWorld->GetPlayerControllerIterator(); Iterator; ++Iterator)
		{
			APlayerController* ServerController = Iterator->Get();

			const FUniqueNetIdRepl& ServerPlayerUniqueId = ServerController->PlayerState->GetUniqueId();
			const FUniqueNetIdRepl& ClientPlayerUniqueId = ClientController->PlayerState->GetUniqueId();

			if (ServerPlayerUniqueId == ClientPlayerUniqueId)
			{
				return ServerController;
			}
		}
	}
#endif
	return nullptr;
}

As we can see, we simply iterate through the player controllers of the server world until we find the one matching (so that the Player UniqueId matches). Thus, if we call the function from our client, the function returns the server Player Controller related to our client Player Controller.

A simple example

In the example below, we want to print the server value alongside the client value of Stamina from our CMC.

// From a client...

float ServerStamina = 0.f;
if (APlayerController* ServerPlayerController = UMyDevelopmentStatics::FindPlayInEditorAuthorityPlayerController(GetPlayerController()))
{
	if( AMyCharacter* ServerPawn = Cast<AMyCharacter>(ServerPlayerController->GetPawn()))
	{
		ServerStamina = ServerPawn->GetMyCharacterMovementComponent()->Stamina;
	}
	Print("LogEntry: Client Stamina: %f | Server Stamina: %f", Stamina, ServerStamina);
}

Conclusion

Thanks for reading!

I hope this clarifies the magic I made back then when I measured the clock. Now! Feel free to use it wherever you like! Trust me, you’ll find usecases :D

Enjoy, vori.

Lazy loading the Ability System Component (GAS) in Multiplayer games

2023-11-10T00:00:00+00:00

Hello! In this post we’ll learn together how to Lazy Load the Ability System Component in our multiplayer games to reduce memory usage!

Introduction

The Ability System Component (ASC) can be a bit resource-intensive, especially when dealing with World Actors that require it, like Damageables. If our world is populated with such Actors, their memory footprint can become noticeable.

Taking a cue from Epic and the insights shared by Tranek in the excellent GASDocumentation, Fortnite adopts a smart approach. They lazily load their ASCs in their World Actors just when they’re needed, dodging the memory hit until it’s absolutely necessary. This memory optimization is a significant boost for scalability; since ASC World Actors won’t carry that footprint unless explicitly interacted with.

Think of it like this: buildings, trees, and damageable props on standby with a lower cost, only racking up the memory bill when they step into the gameplay spotlight.

But before we start, I would love to thank my dear friend KaosSpectrum for his significant research and collaboration on the topic; without him, this wouldn’t have been possible.

The implementation

So… let’s take a look on how we can implement this. Bear with me, as Epic hasn’t posted this anywhere online, so if you spot any error, feel free to report it!

The first step is to create an Actor type that will hold this behaviour, in my case I called it AMyGameplayActor. It is critical that your actor implements the IAbilitySystemInterface interface, as we’ll require to override the GetAbilitySystemComponent function.

In this Actor, I’ve defined an Enum EAbilitySystemCreationPolicy that determines the ASC loading behaviour:

/**
 *	Defines how a the Ability System is loaded (if ever).
 */
UENUM(BlueprintType)
enum class EAbilitySystemCreationPolicy : uint8
{
	Never UMETA(ToolTip = "The Ability System will be always null"),
	Lazy UMETA(ToolTip = "The Ability System will be null in the client until it is used in the server"),
	Always UMETA(ToolTip = "The Ability System is loaded when the Actor loads"),
};

I’ve also defined other relevant properties for the implementation, such as the Ability System Component class, the Attribute mutation buffer, or the runtime ASC transient property:

protected:
	UPROPERTY(EditDefaultsOnly, Category="Abilities")
	TSubclassOf<UMyAbilitySystemComponent> AbilitySystemComponentClass;

	UPROPERTY(Transient)
	TObjectPtr<UMyAbilitySystemComponent> AbilitySystemComponent = nullptr;

private:

	UPROPERTY(Transient, ReplicatedUsing=OnRep_ReplicatedAbilitySystemComponent)
	TObjectPtr<UMyAbilitySystemComponent> ReplicatedAbilitySystemComponent = nullptr;

	struct FPendingAttributeReplication
	{
		FPendingAttributeReplication()
		{
		}

		FPendingAttributeReplication(const FGameplayAttribute& InAttribute, const FGameplayAttributeData& InNewValue)
		{
			Attribute = InAttribute;
			NewValue = InNewValue;
		}

		FGameplayAttribute Attribute;
		FGameplayAttributeData NewValue;
	};

	TArray<struct FPendingAttributeReplication> PendingAttributeReplications;

Gameplay Actors need to replicate by default, so we setup their constructor appropriately:

AMyGameplayActor::AMyGameplayActor(const FObjectInitializer& ObjectInitializer) : Super(ObjectInitializer)
{
	PrimaryActorTick.bCanEverTick = true;
	PrimaryActorTick.bStartWithTickEnabled = false;
	AbilitySystemComponentClass = UMyAbilitySystemComponent::StaticClass();

	bReplicates = true;
}

Then, we create a the relevant functions to create the ASC and to Initialize it:

void AMyGameplayActor::CreateAbilitySystem()
{
	AbilitySystemComponent = NewObject<UMyAbilitySystemComponent>(this, AbilitySystemComponentClass);
	AbilitySystemComponent->SetIsReplicated(true);
	AbilitySystemComponent->SetReplicationMode(EGameplayEffectReplicationMode::Minimal);
	AbilitySystemComponent->RegisterComponent();
}

void AMyGameplayActor::InitializeAbilitySystem()
{
	check(AbilitySystemComponent);
	AbilitySystemComponent->InitAbilityActorInfo(this, this);

	if (HasAuthority())
	{
		// @TODO: Grant Abilities

		// @TODO: Grant and initialize Attributes
	}

	// @TODO: Add static gameplay tags server/client
}

Following next, we override and implement the functions below to accomodate to the ASC creation policies we defined:

void AMyGameplayActor::PreInitializeComponents()
{
	Super::PreInitializeComponents();

	if (AbilitySystemComponentCreationPolicy == EAbilitySystemCreationPolicy::Always && GetNetMode() != NM_Client)
	{
		check(!AbilitySystemComponent);
		CreateAbilitySystem();
		InitializeAbilitySystem();
		ForceNetUpdate();
	}
}

void AMyGameplayActor::PreReplication(IRepChangedPropertyTracker& ChangedPropertyTracker)
{
	Super::PreReplication(ChangedPropertyTracker);
	if (!ReplicatedAbilitySystemComponent && AbilitySystemComponent && AbilitySystemComponentCreationPolicy != EAbilitySystemCreationPolicy::Never)
	{
		MARK_PROPERTY_DIRTY_FROM_NAME(ThisClass, ReplicatedAbilitySystemComponent, this);
		ReplicatedAbilitySystemComponent = AbilitySystemComponent;
	}
}

void AMyGameplayActor::GetLifetimeReplicatedProps(TArray< FLifetimeProperty >& OutLifetimeProps) const
{
	Super::GetLifetimeReplicatedProps(OutLifetimeProps);

	FDoRepLifetimeParams Params;
	Params.bIsPushBased = true;

	DOREPLIFETIME_WITH_PARAMS_FAST(ThisClass, ReplicatedAbilitySystemComponent, Params);
}

UAbilitySystemComponent* AMyGameplayActor::GetAbilitySystemComponent() const
{
	if (!AbilitySystemComponent && HasAuthority() && AbilitySystemComponentCreationPolicy == EAbilitySystemCreationPolicy::Lazy && GetWorld() && !IsUnreachable())
	{
		AMyGameplayActor* MutableActor = const_cast<AMyGameplayActor*>(this);
		MutableActor->CreateAbilitySystem();
		MutableActor->InitializeAbilitySystem();
		MutableActor->ForceNetUpdate();
	}
	return AbilitySystemComponent;
}

void AMyGameplayActor::ApplyPendingAttributesFromReplication()
{
	check(AbilitySystemComponent);

	if (PendingAttributeReplications.Num() > 0)
	{
		for (const FPendingAttributeReplication& Pending : PendingAttributeReplications) 
		{
			AbilitySystemComponent->DeferredSetBaseAttributeValueFromReplication(Pending.Attribute, Pending.NewValue);
		}
		PendingAttributeReplications.Empty();
	}
}

void AMyGameplayActor::OnRep_ReplicatedAbilitySystemComponent()
{
	AbilitySystemComponent = ReplicatedAbilitySystemComponent;
	if (AbilitySystemComponent)
	{
		InitializeAbilitySystem();
		ApplyPendingAttributesFromReplication();
	}
}

void AMyGameplayActor::SetPendingAttributeFromReplication(const FGameplayAttribute& Attribute, const FGameplayAttributeData& NewValue)
{
	PendingAttributeReplications.Emplace(FPendingAttributeReplication(Attribute, NewValue));
}

As we can see, if the policy is Lazy, the first time we call GetAbilitySystemComponent() through any of the ASC API functions, the ASC will get created and initialized. The PreReplication overriden function and our proxy ReplicatedAbilitySystemComponent variable will make sure AbilitySystemComponent will get to the client and Server properly.

Pending Attribute Replication

When the Ability System Component gets created in the server, it takes latency time before it reaches the client, and during that time, Attributes might need to replicate (accounting for Net Priority and Frequency on the owning Actors).

During this time, we need to hold the attribute changes somewhere until the ASC is available in the Client, for that, we use the PendingAttributeReplications Array defined in our Gameplay Actor.

To buffer the Attribute mutations, we need to route Attribute replication through our Gameplay Actor. In our base Attribute class we have in our game define the following macro:

#define MYGAMEPLAYATTRIBUTE_REPNOTIFY(ClassName, PropertyName, OldValue) \
{ \
	static FProperty* ThisProperty = FindFieldChecked(ClassName::StaticClass(), GET_MEMBER_NAME_CHECKED(ClassName, PropertyName)); \
	if (!GetOwningAbilitySystemComponent()) \
	{ \
		if (AMyGameplayActor* GameplayActor = Cast(GetOwningActor())) \
		{ \
			GameplayActor->SetPendingAttributeFromReplication(FGameplayAttribute(ThisProperty), PropertyName); \
		} \
		return; \
	} \
	else \
	{ \
		GetOwningAbilitySystemComponent()->SetBaseAttributeValueFromReplication(FGameplayAttribute(ThisProperty), PropertyName, OldValue); \
	} \
}

Then, in our child Attribute Sets, we have to implement our OnRep as follows:

void UMyAttributeSet_Health::OnRep_Health(const FGameplayAttributeData& OldHealth)
{
	MYGAMEPLAYATTRIBUTE_REPNOTIFY(UMyAttributeSet_Health, Health, OldHealth); 
}

void UMyAttributeSet_Health::OnRep_Shield(const FGameplayAttributeData& OldShield)
{
	MYGAMEPLAYATTRIBUTE_REPNOTIFY(UMyAttributeSet_Health, Shield, OldShield);
}

As we can see, the macro we created calls SetPendingAttributeFromReplication we defined in our AMyGameplayActor from the Attribute Set OnRep functions, which fill our buffer Array PendingAttributeReplications which gets consumed in ApplyPendingAttributesFromReplication, when the ASC reaches the client in AMyGameplayActor.

ApplyPendingAttributesFromReplication calls DeferredSetBaseAttributeValueFromReplication which will ensure we have the most up to date attribute values on the client:

void UMyAbilitySystemComponent::DeferredSetBaseAttributeValueFromReplication(const FGameplayAttribute& Attribute, float NewValue)
{
	const float OldValue = ActiveGameplayEffects.GetAttributeBaseValue(Attribute);
	ActiveGameplayEffects.SetAttributeBaseValue(Attribute, NewValue);
	SetBaseAttributeValueFromReplication(Attribute, NewValue, OldValue);
	// TODO: You can process deferred delegates here
}

void UMyAbilitySystemComponent::DeferredSetBaseAttributeValueFromReplication(const FGameplayAttribute& Attribute, const FGameplayAttributeData& NewValue)
{
	const float OldValue = ActiveGameplayEffects.GetAttributeBaseValue(Attribute);
	ActiveGameplayEffects.SetAttributeBaseValue(Attribute, NewValue.GetBaseValue());
	SetBaseAttributeValueFromReplication(Attribute, NewValue.GetBaseValue(), OldValue);
	// TODO: You can process deferred delegates here
}

Conclusion

Thanks for reading!

Now you’ll have a way to save some memory from your ASC Gameplay Actors! I hope you found this article helpful!

I’m going to leave a remaining challenge to the curious reader: Deferred delegates! These deferred delegates should happen when the ASC reaches the client in our Gameplay Actor, and it would give us the possibility to react to the buffered changes. If you get to implement this, feel free to share it!

Enjoy, vori.

Replicating stateful sounds and animations

2023-09-17T00:00:00+00:00

Hello! In this post we’ll expose a very simple pattern you can use to replicate any long stateful sound or animation. In addition, we’ll learn about some caveats when it comes to replication order guarantees.

Introduction

There are times when we want to replicate a long animation and still have it playing in the correct timeframe when a client joins. While the Gameplay Ability System does this with the PlayMontageAndWait node, GAS is not always appropriate for all of our use cases.

The same problem also occurs with music or other animated elements, such as an elevator. In all the cases, we want late joiners to see our ingredients in the correct state by the time they join.

The solution

So… how can we solve this? The solution relies on using time! Yes, that simple!

If we store and replicate in a variable the time at which an action took place, we can figure out by the time someone joins to our game, where the animation/sound should be at for that client. Let’s picture it this way:

Player 1 starts playing an animation at t0 = 34 s
Player 2 joins the game at t1 = 38 s
By the time Player 2 joined, the animation has already advanced (t1 - t0) 4 seconds
Player 2 should start playing the animation of Player 1 at t = 4 s.

Let’s see how we can translate this to code.

A practical example

In our imaginary game, characters can play the flute, and we want the melody to be synchronised between them, but that isnt complicated, since a Multicast can do the job. However, the melody is long, and we want incoming connections to hear the melody properly even if the player started playing it at an earlier time. These requirements made already the feature stateful; so… we have to discard Multicasts.

Coding our solution

One of the first concepts we should understand before coding this solution is that the GameState is guaranteed to be valid when any Actor on client calls BeginPlay, this is important since we will rely on a GameState replicated clock to set the correct animation/sound state.

To replicate to our simulated proxies the time at which we started playing the melody we are going to use a replicated property LastTimePlayedMelody that replicates only to simulated proxies.

// Represents the time at which the melody was played
UPROPERTY(ReplicatedUsing = OnRepLastTimePlayedMelody)
float LastTimePlayedMelody = 0.f;

void AMyPawn::GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const
{
	Super::GetLifetimeReplicatedProps(OutLifetimeProps);

	// We make sure only simulated proxies get this repli property
	DOREPLIFETIME_CONDITION(AMyPawn, LastTimePlayedMelody, COND_SimulatedOnly);
}

To play the melody at a specific time we are going to use SpawnSoundAttached, since it contains a parameter StartTime that we can input to start the sound at a time. For that, we created the following function that we should call locally, which starts playing a melody inmediately. As we can see, the function also notifies the server so that the rest of the clients can also play it.

void AMyPawn::PlayMelody(float StartTime)
{
	UGameplayStatics::SpawnSoundAttached(FluteSong, GetMesh(), NAME_None, 
		FVector::ZeroVector, EAttachLocation::KeepRelativeOffset, 
		false, 1.f, 1.f, StartTime);

	if (IsLocallyControlled())
	{
		if (HasAuthority())
		{
			LastTimePlayedMelody = GetWorld()->GetTimeSeconds();
		}
		else
		{
			ServerPlayMelody();
		}
	}
}

void AMyPawn::ServerPlayMelody()
{
	LastTimePlayedMelody = GetWorld()->GetTimeSeconds();
	if (GetWorld()->GetNetMode() != ENetMode::NM_DedicatedServer)
	{
		PlayMelody(0.f);
	}
}

In the server we should set LastTimePlayedMelody, which will replicate through the OnRep. In the case we are in a Listen Server, we should also play the melody.

Then, in the OnRep we do as follows:

void AMyPawn::OnRepLastTimePlayedMelody()
{
	if (GetWorld()->TimeSeconds == CreationTime)
	{
		return;
	}

	AGameStateBase* GameState = GetWorld()->GetGameState();
	if (!GameState)
	{
		return;
	}

	const float SoundTime = GameState->GetServerWorldTimeSeconds() - LastTimePlayedMelody;

	if (SoundTime < FluteSong->GetDuration())
	{
		PlayMelody(SoundTime);
	}
}

We calculate the time at which the sound should be at by substracting the current server time GameState->GetServerWorldTimeSeconds() with the OnRep variable. If the SoundTime is lesser than the total duration of the Sound, we can start playing the sound at the exact point!

If we were to use the same technique with animations, we can use UAnimInstance::Montage_Play which also has the analogous InTimeToStartMontageAt.

Problems: Late joiners

However, we are not done. If we execute the code from above we will notice that our late joiners dont execute anything, this is because in the OnRep code from above, we are doing two very specific conditions:

if (GetWorld()->TimeSeconds == CreationTime)
{
	return;
}

AGameStateBase* GameState = GetWorld()->GetGameState();
if (!GameState)
{
	return;
}

These two conditions basically skip the OnRep, as we dont want to use it on the first spawn packet. But why? We do this because the GameState isnt guaranteed to be replicated at the time our OnRep gets called. Then, how do we solve this?

As we mentioned previously:

GameState is guaranteed to be valid when any Actor on client calls BeginPlay.

So… let’s code our late join support in BeginPlay!

BeginPlay guarantees

As I said above, GameState will be valid when client-side BeginPlay is called.

However, having a valid GameState isn’t enough, since we also need to have up-to-date properties by the time BeginPlay is called on the client. Now, we can only guarantee that our properties have replicated by then in runtime spawned replicated Actors. The Actors that are pre-placed in the level (also called Net Startup Actors) don’t guarantee correct replicated state in BeginPlay.

So, in this case, we can safely assume that, in our Character, since it isn’t a Net Startup Actor, the variables will be up to date for the client in BeginPlay:

void AMyPawn::BeginPlay()
{
	Super::BeginPlay();

	if (GetLocalRole() == ENetRole::ROLE_SimulatedProxy)
	{
		AGameStateBase* GameState = GetWorld()->GetGameState();
		const float SoundTime = GameState->GetServerWorldTimeSeconds() - LastTimePlayedMelody;

		if (SoundTime < FluteSong->GetDuration())
		{
			PlayMelody(SoundTime);
		}
	}
}

When we execute the BeginPlay of other Characters (simulated proxies) in our client, we can access the GameState (which will be valid) to retrieve GetServerWorldTimeSeconds, and then using the same technique we saw in the OnRep, we can play the melody at the specified time.

What about Net Startup Actors?

In the case of Net Startup Actors we can’t rely on BeginPlay, so we wouldn’t put any initialization specific code on it.

In this case, we can develop a more generic solution… however… it is very ugly:

void AMyNetStartupActor::OnRepLastTimePlayedMelody()
{
	AGameStateBase* GameState = GetWorld()->GetGameState();
	if (!GameState)
	{
		// Silly hack to prevent early initialization, if the GameState isn't valid we wait until it is to be able to get our clock
		FTimerHandle DummyTimer;
		GetWorld()->GetTimerManager().SetTimer(DummyTimer, this, &ThisClass::OnRepLastTimePlayedMelody, 0.1f, false);
		return;
	}

	const float SoundTime = GameState->GetServerWorldTimeSeconds() - LastTimePlayedMelody;

	if (SoundTime < FluteSong->GetDuration())
	{
		PlayMelody(SoundTime);
	}
}

Unfortuntely, waiting for the GameState is the only solution. We can implement this in a more elegant manner orchestrating our initialization with a subsystem or other methods, but this inconsistency between Net Startup and non-Net Startup Actors makes networking more difficult, by default.

I really wish this gets changed in the future, but to date, this is our safest bet.

Conclusion

Thanks for reading!

This article covers a very simplistic pattern you can use to replicate stateful tracked ingredients, such as sounds or animations, and also covers the problem between Net Startup and non-Net Startup Actors.

There are many things that could be improved about the techniques presented in the article, such as using a better synced clock, improving the waiting GameState method, or even employing another techniques to replicate tracks without depending on time.

However you got a chance to reason about different initialization techniques, and I hope that this article made you understand how important order is in multiplayer.

Enjoy, vori.

Physics Network Prediction in Unreal Engine 5.3 Preview

2023-07-30T00:00:00+00:00

Unreal Engine introduced Physics prediction in 5.3, this post showcases a little demo project using it.

Introduction

Wow! I didn’t see that coming! Epic Games introduced an experimental Physics prediction feature in 5.3, so… let’s take a look.

In order to activate the feature, open Project Settings and within the Physics tab, turn on Enable Physics Prediction.

There are other settings you might want to explore!

How does it work?

The following video I’ve recorded showcases the state of the system at the release date of UE 5.3 Preview.

Conclusion

Thanks for watching!

Hopefully you are as hyped as I am with this new feature! :)

Enjoy, vori.

Understanding Unreal Engine’s DORM_Initial dormancy setting

2023-07-02T00:00:00+00:00

This article is a collaboration with WizardCell and on it, you’ll learn how DORM_Initial works and why you should be careful with it.

Introduction

If we read the description of the DORM_Initial dormancy setting, we see what follows:

This actor is initially dormant for all connection if it was placed in map.

Which made me understand that this setting would work like DORM_DormantAll just with a couple extra optimizations. But it isn’t the case, let’s see what are the implications of using this setting.

`DORM_DormantAll` versus `DORM_Initial`

When an Actor becomes relevant to a connection, all the properties of said Actor are sent to the connection, no matter whether the Actor is DORM_DormantAll or DORM_Awake. That means that the state the client receives from the Actor will be consistent of what the server sees about it.

However, that is not the case of DORM_Initial Actors, as they will not send any C++ replicated property if a connection becomes relevant:

Watch out! Blueprint replicated properties ignore Actor dormancy settings.

How to use `DORM_Initial`

So shall I simply not use DORM_Initial? No, you should! DORM_Initial Actors won’t be considered for replication at all even under relevancy, and sometimes that can be a huge optimization.

To ensure incoming connections get the new values over DORM_Initial Actors, you should call FlushNetDormancy on them before updating their properties. This will make the Actor to become DORM_DormantAll but only when strictly needed.

What about calling `ForceNetUpdate` to also flush the dormancy?

Be very careful with this, as ForceNetUpdate also calls FlushNetDormancy but its guarded with a NetDriver check:

void AActor::ForceNetUpdate()
{
	...

	if (GetLocalRole() == ROLE_Authority)
	{
		// ForceNetUpdate on the game net driver only if we are the authority...
		if (NetDriver && NetDriver->GetNetMode() < ENetMode::NM_Client) // ... and not a client
		{
			NetDriver->ForceNetUpdate(this);

			if (NetDormancy > DORM_Awake)
			{
				FlushNetDormancy();
			}
		}
	}

	...
}

So, if the NetDriver is Null at the moment you call ForceNetUpdate*, the Actor will never call FlushNetDormancy, causing it to stay in a DORM_Initial state. For that reason it is always recommended to explicitly call FlushNetDormancy when dealing with DORM_Initial Actors.

*Worlds don’t get a NetDriver until UWorld::Listen is called.

Conclusion

Thanks for reading!

Let’s hope everything is clear! Feel free to reach us out if there are questions! And I encourage every reader to check WizardCell’s articles.

If you want to know more about Dormancy, visit Epic’s official documentation!

Enjoy, WizardCell and vori.

Devtricks

Iris - Network serializers

Introduction

Network Serialization in Iris

Serializing a struct in Iris

Before we start

Declaring the serializer

Registering the serializer

Implementing the serializer

1. Quantize

2. IsEqual

3. Serialize

4. Deserialize

5. Dequantize

6. (Optional) Apply

Full code

Conclusion

Iris - Replication filters

Introduction - Being an early adopter

The replication filter

The replication filter in Iris

Additional resources

Conclusion

Networked Physics and UNetworkPhysicsComponent in Unreal Engine 5.4

Introduction

Making a rolling boulder

The setup

Coding the physics boulder movement

Implementation details

Additional resources

Conclusion

How to use the Contextual Animation Plugin in your Multiplayer Games (UE 5.3+) w/ Doğa

Introduction

How to setup a Contextual Animation

Contextual Anim Scene

Animation Sequence requirements (and Montages)

Creating a new track

Contextual Animation Selection Criteria

Adding a Selection Criteria

How to play a Contextual Animation during gameplay

Extra functionalities

Multiplayer details

Conclusion

Mover in Unreal Engine 5.4

Introduction

How does it work?

Additional resources

Conclusion

Convenient Multiplayer Logging in UE5

Overview

The implementation

A simple example

Conclusion

Lazy loading the Ability System Component (GAS) in Multiplayer games

Introduction

The implementation

Pending Attribute Replication

Conclusion

Replicating stateful sounds and animations

Introduction

The solution

A practical example

Coding our solution

Problems: Late joiners

BeginPlay guarantees

What about Net Startup Actors?

Conclusion

Physics Network Prediction in Unreal Engine 5.3 Preview

Introduction

How does it work?

Conclusion

Understanding Unreal Engine’s DORM_Initial dormancy setting

Introduction

DORM_DormantAll versus DORM_Initial

How to use DORM_Initial

What about calling ForceNetUpdate to also flush the dormancy?

Conclusion

`DORM_DormantAll` versus `DORM_Initial`

How to use `DORM_Initial`

What about calling `ForceNetUpdate` to also flush the dormancy?