James Baxter

Get Accurate Bounds of a Skeletal Mesh

Sun, 15 May 2022 10:25:38 +0100

Uses the Physics Asset to compute an accurate reference-pose bounding box for a skeletal mesh asset. This typically has more utility than the default skeletal mesh bounds which can often be arbitrarily inflated or scaled.

bool UMyFunctionLibrary::GetAccurateReferencePoseBounds(FBox& AABB, const USkeletalMesh* Mesh)
{
	AABB = FBox(EForceInit::ForceInitToZero);

	if (!Mesh) { return false; }
	if (!Mesh->GetPhysicsAsset()) { return false; }

	for (const USkeletalBodySetup* BodySetups : Mesh->GetPhysicsAsset()->SkeletalBodySetups)
	{
		const FReferenceSkeleton& RefSkeleton = Mesh->GetSkeleton()->GetReferenceSkeleton();
		FTransform ComponentSpaceBoneTransform = FTransform::Identity;

		int32 BoneIndex = RefSkeleton.FindBoneIndex(BodySetups->BoneName);
		while (BoneIndex != INDEX_NONE)
		{
			const FTransform& BoneLocalTM = RefSkeleton.GetRefBonePose()[BoneIndex];
			ComponentSpaceBoneTransform = ComponentSpaceBoneTransform * BoneLocalTM;

			BoneIndex = RefSkeleton.GetParentIndex(BoneIndex);
		}

		AABB += BodySetups->AggGeom.CalcAABB(ComponentSpaceBoneTransform);
	}

	return true;
}

Get Actor Components from Blueprint Generated Class

Sun, 15 May 2022 10:11:42 +0100

Allows you to retrieve actor component configuration and data from a Blueprint Generated Class, similar to the Class Default Object for C++ Classes. There are optional optimizations for filtering by name, and for returning multiple components.

Single Component Implementation

const UActorComponent* UMyFunctionLibrary::GetClassComponentTemplate(FName& FoundComponentName, const TSubclassOf<AActor> ActorClass, const TSubclassOf<UActorComponent> ComponentClass, const FName ComponentName /*= NAME_None*/)
{
	if (IsValid(ActorClass) && IsValid(ComponentClass))
	{
		UBlueprintGeneratedClass* CurrentBPClass = Cast<UBlueprintGeneratedClass>(ActorClass);
		while (CurrentBPClass)
		{
			// Not all BP's have an SCS (apparently)
			if (CurrentBPClass->SimpleConstructionScript)
			{
				if (ComponentName != NAME_None)
				{
					// Find Matching Node
					const USCS_Node* FoundNode = CurrentBPClass->SimpleConstructionScript->FindSCSNode(ComponentName);
					if (FoundNode && FoundNode->ComponentClass->IsChildOf(ComponentClass))
					{
						if (const UActorComponent* FoundComponent = FoundNode->GetActualComponentTemplate(CurrentBPClass))
						{
							FoundComponentName = ComponentName;
							return FoundComponent;
						}
					}
				}
				else
				{
					// No specified name, just return first component class that matches.
					const TArray<USCS_Node*>& AllSCSNodes = CurrentBPClass->SimpleConstructionScript->GetAllNodes();
					for (const USCS_Node* NodeItr : AllSCSNodes)
					{
						if (NodeItr->ComponentClass->IsChildOf(ComponentClass))
						{
							FoundComponentName = NodeItr->GetVariableName();
							return NodeItr->GetActualComponentTemplate(CurrentBPClass);
						}
					}
				}
			}

			// Didn't find an explicit entry in this class, check inherited component overrides.
			if (UInheritableComponentHandler* Handler = CurrentBPClass->GetInheritableComponentHandler(false))
			{
				if (ComponentName != NAME_None)
				{
					const FComponentKey FoundKey = Handler->FindKey(ComponentName);
					if (FoundKey.IsValid())
					{
						if (const UActorComponent* FoundComponent = Handler->GetOverridenComponentTemplate(FoundKey))
						{
							FoundComponentName = ComponentName;
							return FoundComponent;
						}
					}
				}
				else
				{
					TArray<FComponentOverrideRecord>::TIterator InheritedComponentItr = Handler->CreateRecordIterator();
					for (InheritedComponentItr; InheritedComponentItr; ++InheritedComponentItr)
					{
						const FComponentOverrideRecord& Record = *InheritedComponentItr;
						if (Record.ComponentClass->IsChildOf(ComponentClass) && Record.ComponentTemplate)
						{
							FoundComponentName = Record.ComponentKey.GetSCSVariableName();
							return Record.ComponentTemplate;
						}
					}
				}
			}

			// Wasn't found in this class or it's inherited vars. Check the Super BP Class
			CurrentBPClass = Cast<UBlueprintGeneratedClass>(CurrentBPClass->GetSuperClass());
		}

		// If we get this far, didn't find a Blueprint template. Get the component properties from the native CDO if possible.
		if (const AActor* CDO = ActorClass.GetDefaultObject())
		{
			if (ComponentName == NAME_None)
			{
				if (const UActorComponent* FoundComponent = CDO->FindComponentByClass(ComponentClass))
				{
					FoundComponentName = ComponentName;
					return FoundComponent;
				}
			}
			else
			{
				for (const UActorComponent* ComponentItr : CDO->GetComponents())
				{
					if (ComponentItr->GetFName() == ComponentName && ComponentItr->GetClass()->IsChildOf(ComponentClass))
					{
						FoundComponentName = ComponentItr->GetFName();
						return ComponentItr;
					}

					return nullptr;
				}
			}
		}
	}

	FoundComponentName = NAME_None;
	return nullptr;
}

Multiple Component Implementation

TArray<UActorComponent*> UST_CoreStatics::GetClassComponentTemplates(TArray<FName>& FoundComponentNames, const TSubclassOf<AActor> ActorClass, const TSubclassOf<UActorComponent> ComponentClass)
{
	/* Use a Map to avoid reinsertion of the same overridden template in a parent */
	TMap<FName, UActorComponent*> ComponentMap = {};

	// Check Classes
	if (IsValid(ActorClass) && IsValid(ComponentClass))
	{
		// Insert Native Components First
		if (const AActor* CDO = ActorClass.GetDefaultObject())
		{
			for (UActorComponent* ComponentItr : CDO->GetComponents())
			{
				if (ComponentItr->GetClass()->IsChildOf(ComponentClass))
				{
					ComponentMap.Emplace(ComponentItr->GetFName(), ComponentItr);
				}
			}
		}

		// Now find Blueprint Components and/or overrides
		UBlueprintGeneratedClass* BPClass = Cast<UBlueprintGeneratedClass>(ActorClass);
		if (BPClass)
		{
			// Move to the Top-Most BP Class, then move downards
			TArray<UBlueprintGeneratedClass*, TInlineAllocator<4>> GeneratedClasses;

			while (BPClass)
			{
				GeneratedClasses.Emplace(BPClass);
				BPClass = Cast<UBlueprintGeneratedClass>(BPClass->GetSuperClass());
			}

			// Now go from top-most parent to lowest descendant, checking for overrides on the way
			for (int32 Idx = GeneratedClasses.Num() - 1; Idx >= 0; Idx--)
			{
				// Not all BP's have an SCS (apparently)
				UBlueprintGeneratedClass* CurrentBPClass = Cast<UBlueprintGeneratedClass>(ActorClass);
				if (CurrentBPClass->SimpleConstructionScript)
				{
					// No specified name, just return first component class that matches.
					const TArray<USCS_Node*>& AllSCSNodes = CurrentBPClass->SimpleConstructionScript->GetAllNodes();
					for (const USCS_Node* NodeItr : AllSCSNodes)
					{
						if (NodeItr->ComponentClass->IsChildOf(ComponentClass))
						{
							ComponentMap.FindOrAdd(NodeItr->GetVariableName(), NodeItr->GetActualComponentTemplate(CurrentBPClass));
						}
					}
				}

				// Search Inherited Components
				if (UInheritableComponentHandler* Handler = CurrentBPClass->GetInheritableComponentHandler())
				{
					TArray<FComponentOverrideRecord>::TIterator InheritedComponentItr = Handler->CreateRecordIterator();
					for (InheritedComponentItr; InheritedComponentItr; ++InheritedComponentItr)
					{
						const FComponentOverrideRecord& Record = *InheritedComponentItr;
						if (Record.ComponentClass->IsChildOf(ComponentClass) && Record.ComponentTemplate)
						{
							ComponentMap.FindOrAdd(Record.ComponentKey.GetSCSVariableName(), Record.ComponentTemplate);
						}
					}
				}
			}
		}
	}

	ComponentMap.GenerateKeyArray(FoundComponentNames);

	TArray<UActorComponent*> ReturnVal = {};
	ComponentMap.GenerateValueArray(ReturnVal);

	return ReturnVal;
}

Header Declarations

/*
* Gets the template component on the actor class with the given component class.
* Supports Blueprint Classes
*
* @param ActorClass			- The Actor Blueprint/Native Class
* @param ComponentClass		- The expected type of actor component.
* @param ComponentName		- If specified, makes the search faster and only includes components with the given name.
*/
UFUNCTION(BlueprintCallable, Category = "Helpers", meta = (DeterminesOutputType = "ComponentClass"))
static const UActorComponent* GetClassComponentTemplate(FName& FoundComponentName, const TSubclassOf<AActor> ActorClass, const TSubclassOf<UActorComponent> ComponentClass, const FName ComponentName = NAME_None);

/*
* Gets all template components on the actor class with the given component class.
* Supports Blueprint Classes
*
* @param ActorClass			- The Actor Blueprint/Native Class
* @param ComponentClass		- The expected type of actor component.
*/
UFUNCTION(BlueprintCallable, Category = "Helpers", meta = (DeterminesOutputType = "ComponentClass"))
static TArray<UActorComponent*> GetClassComponentTemplates(TArray<FName>& FoundComponentNames, const TSubclassOf<AActor> ActorClass, const TSubclassOf<UActorComponent> ComponentClass);

Check SoftClass IsChildOf(x) Without Loading Class

Sat, 14 May 2022 12:02:20 +0100

Uses the Asset Registry to determine whether a SoftClass is a child of another class, without loading it. NOTE: This snippet has limited utility, traversing the asset registry may be slower than just loading the class in some cases!

void UMyAssetManager::SetAssetRegistryTempCachingEnabled(const bool bEnabled)
{
	IAssetRegistry::Get()->SetTemporaryCachingMode(bEnabled);
}

bool UMyAssetManager::SoftClassIsChildOf(const TSoftClassPtr<UObject>& SoftClass, const TSubclassOf<UObject>& Class)
{
	if (SoftClass.IsNull() || Class == nullptr)
	{
		// Class is invalid, do nothing
		return false;
	}
	else if (const UClass* LoadedClass = SoftClass.Get())
	{
		// Class is already loaded, use the fast path
		return LoadedClass->IsChildOf(Class);
	}
	else
	{
		// Use Asset Registry for Unloaded Classes
		// Caution: This may be slow if TempCaching is disabled.
		FAssetData AssetData;
		if (UAssetManager::Get().GetAssetDataForPath(SoftClass.ToSoftObjectPath(), AssetData))
		{
			if (AssetData.AssetClass == Class->GetFName())
			{
				return true;
			}
			else
			{
				// Unfortunately the temp class hierarchy data is private, so we can't walk it manually.
				TArray<FName> AncestorClasses;
				IAssetRegistry::Get()->GetAncestorClassNames(AssetData.AssetClass, AncestorClasses);

				return AncestorClasses.Contains(Class->GetFName());
			}
		}

		return false;
	}
}

Using Gameplay Tags in C++

Thu, 06 May 2021 18:17:56 +0100

NOTE: The following setup has been superseded by “Native Gameplay Tags” in UE4.27 and beyond. New post coming soon.

Gameplay tags are a powerful UE4 feature that allow for high-level tagging and categorisation of concepts and types. This concept of hierarchical tagging can be very powerful, and Gameplay Tags themselves have fully-featured editor support and a great API for use in native code. Gameplay Tags are used extensively in Epic’s Gameplay Abilities System, but are a standalone feature that can be used outside of this to great effect. For designer-facing systems, they can make a great replacement for hardcoded FNames and Enums.

The backbone of FGameplayTag is the FName type. Tags are essentially FName’s that use “.” as a delimiter to denote heirachy and grouping. Unlike FName however, tags must be registered within a central dictionary in order to be valid and used. This dictionary is generated during the early stages of application runtime from serialized data – which can create some nuances when it comes to the most efficient way to refer to them in C++.

Because the dictionary is created at runtime, some common practices employed when using FName (such as static const definitions of FName’s) cannot be applied to Tags. Since Tags defined in config files can also be manipulated by other developers, you run the risk of these tags being changed without your knowledge, potentially breaking code that relies on them.

Typical Usage

The most common method I’ve seen when referring to Gameplay Tags in code is to use the static ‘RequestGameplayTag’ function. Note that the FName-based constructor for FGameplayTag is intentionally private, since the system requires you to lookup tags from the dictionary. If you don’t already have the tag as a variable, this is the only way you can get valid tags in C++.

const FGameplayTag MyTag = FGameplayTag::RequestGameplayTag(FName(“MyTag.MyTagChild”));

This is not entirely foolproof though, and by digging into this function we can see where problems may arise depending on both where, and how often, we are calling it.

Race Conditions

Since we are looking these tags up from a runtime-generated source, there is an inherent data race-condtion here. For example, if you are assigning a default value in a constructor, or validating a serialized value for instance – you run the risk of the dictionary not yet being valid and therefore not being able to retrieve your tags.
Lookup / Validation Cost

Since internally this function performs a lookup into the dictionary to find a valid tag, there is also an unfixed performance cost here. While TMap lookups are *very* fast, this cost is not negligible. As your project becomes ever more complex and designers go crazy with tagging – this cost can also increase over time. It’s not unreasonable to end up with hundreds or even thousands of tags in a project.

Thankfully the engine provides us with a way to prevent these issues. Defining tags natively allows us to garauntee tags are valid, while also having a fixed lookup cost. These tags are still available to designers and blueprint users too.

Native Gameplay Tags

In order to garauntee that tags required by C++ code will always be valid and exist, and to prevent runtime lookup costs – we can register ‘Native’ tags alongside the tags that other developers may create. We can also group these tags together into singletons, for convenient access and usage all across the codebase.

Tag Singleton Class

The following is an example of a singleton class, with some retrievable tags defined as members. I’ve found that it helps to group tags which are typically used together into their own singletons, to better convey their intended usage and meaning. Note that while you could theoretically implement all the code in the header, I prefer to split into h/cpp to avoid including the substantial GameplayTagManager header all over the codebase. .h

#pragma once

#include "GameplayTagContainer.h"

// Declarations
class UGameplayTagsManager;

/* Common Tags Container */ 
struct MYGAME_API FCommonTags : public FNoncopyable
{
public:
	static FORCEINLINE const FCommonTags& Get()
	{
		checkSlow(mSingleton);
		return *mSingleton;
	}

	// Common Tags
	FORCEINLINE const FGameplayTag& Success() const { return mGenericSuccess; }
	FORCEINLINE const FGameplayTag& Failure() const { return mGenericFailure; }

private:
	// Allow module to initialize
	friend class FMyModule;

	static void Startup(UGameplayTagsManager& TagManager)
	{
		checkSlow(!mSingleton);
		mSingleton = new FCommonTags(TagManager);
	}

	static const FCommonTags* mSingleton;

	FCommonTags(UGameplayTagsManager& TagManager);

	// Common
	FGameplayTag mGenericSuccess;
	FGameplayTag mGenericFailure;
};

.cpp

#include "CommonTags.h"
#include "GameplayTagsManager.h"

const FCommonTags* FCommonTags::mSingleton = nullptr;

FCommonTags::FCommonTags(UGameplayTagsManager& TagManager)
{
	// Common
	mGenericFailure = TagManager.AddNativeGameplayTag("Failed", TEXT("Generic Failure"));
	mGenericSuccess = TagManager.AddNativeGameplayTag("Success", TEXT("Generic Success"));
};

Tag Registration

We now have a global singleton, with access protection against invalid tags. All we need to do now is register and create those singletons at the approriatte time, preferably as early as feasibly possible. There are a couple of ways you can do this, but I prefer to do this from the modules’ startup function like so. Note that in order for this to work, your module must initialize before PostEngineInit is called (the ‘Default’ loading phase is fine for this).

FMyModule::StartupModule
{
	// Bind to the register delegate so that we can register native gameplay tags.
	// Note: This *MUST* be done before PostEngineInit!
	UGameplayTagsManager::Get().OnLastChanceToAddNativeTags().AddRaw(this, &FMyModule::RegisterNativeGameplayTags);
}

void FMyModule::RegisterNativeGameplayTags()
{
	UGameplayTagsManager& Manager = UGameplayTagsManager::Get();

	// Initialize Tag singletons here.
	FCommonTags::Startup(Manager);
	FSomeOtherTags::Startup(Manager);

	// etc..

	Manager.OnLastChanceToAddNativeTags().RemoveAll(this);
}

Using these tags around the codebase is now both fixed-cost and safer.

const FGameplayTag SuccessTag = FCommonTags::Get().Success();
const FGameplayTag FailedTag = FCommonTags::Get().Failed();

Happy Coding!

Replicating UObjects: Building a Flexible Inventory System

Fri, 15 May 2020 17:01:03 +0100

Out-of-the-box, there are two primary types in Unreal Engine which have what we consider “first-class” support for the replication and networking system. These are Actors, and through them, Actor Components. For almost any conceivable situation, this is absolutely all we need. Both types support their own replicated properties, they can be safely created and destroyed at runtime on demand, and they support networked function calls, known as RPC’s.

One important difference, however, is the method of replication. The replication/RPC data is sent across the network via an ActorChannel – and as the name implies, these are only suitable for Actors. Channels can be created and destroyed at will (e.g, network relevancy, dormancy etc.) – but they are required to send network information from one connection to another.

ActorComponents and UObjects cannot create their own channels (or at least, the engine does not provide an implementation of this). This means that any object that needs to be created/destroyed via the network must piggyback off of an existing Actor and it’s channel. Thankfully, the engine provides such a solution, in the form of UObject::ReplicateSubobjects(). The Replication System will make calls to this function when considering an object for replication, and gives it a chance to append subobjects and their properties.

AActor provides a default implementation for replicating its components properties in ActorReplication.cpp. Components that are marked as replicated are maintained in a separate “ReplicatedComponents” list, which is then checked through during AActor::ReplicateSubobjects():

bool WroteSomething = false;

for (UActorComponent* ActorComp : ReplicatedComponents)
{
	if (ActorComp && ActorComp->GetIsReplicated())
	{
		WroteSomething |= ActorComp->ReplicateSubobjects(Channel, Bunch, RepFlags);
		WroteSomething |= Channel->ReplicateSubobject(ActorComp, *Bunch, *RepFlags);
	}
}

return WroteSomething;

We can borrow some of this implementation to add support for other custom UObject-derived types too. However, we also need to do some work on the Object side of things, as adding properties to the channel is not enough.

The Replicated UObject Class

Lets first create the base class for our new replicated UObject. The following is a suggested implementation, for a basic Actor Sub-Object. Some common useful helper functions have been added too, such as a getter for the UWorld and the AActor itself.

UCLASS()
class UMyAwesomeObject : public UObject
{
	GENERATED_BODY()
public:
	UMyAwesomeObject();
	
	// Allows the Object to get a valid UWorld from it's outer.
	virtual UWorld* GetWorld() const override
	{
		if (const UObject* MyOuter = GetOuter())
		{
			return MyOuter->GetWorld();
		}

		return nullptr;
	}
	
	UFUNCTION(BlueprintPure, Category = "My Object")
	AActor* GetOwningActor() const
	{
		return GetTypedOuter<AActor>();
	}
	
	virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override
	{
		// Add any Blueprint properties
		// This is not required if you do not want the class to be "Blueprintable"
		if (const UBlueprintGeneratedClass* BPClass = Cast<UBlueprintGeneratedClass>(GetClass()))
		{
			BPClass->GetLifetimeBlueprintReplicationList(OutLifetimeProps);
		}
	}
	
	virtual bool IsSupportedForNetworking() const override
	{
		return true;
	}
	
	virtual int32 GetFunctionCallspace(UFunction* Function, FFrame* Stack) override
	{
		check(GetOuter() != nullptr);
		return GetOuter()->GetFunctionCallspace(Function, Stack);
	}
	
	// Call "Remote" (aka, RPC) functions through the actors NetDriver
	virtual bool CallRemoteFunction(UFunction* Function, void* Parms, struct FOutParmRec* OutParms, FFrame* Stack) override
	{
		check(!HasAnyFlags(RF_ClassDefaultObject));

		AActor* Owner = GetOwningActor();
		UNetDriver* NetDriver = Owner->GetNetDriver();
		if (NetDriver)
		{
			NetDriver->ProcessRemoteFunction(Owner, Function, Parms, OutParms, Stack, this);
			return true;
		}

		return false;
	}
	
	/*
	* Optional
	* Since this is a replicated object, typically only the Server should create and destroy these
	* Provide a custom destroy function to ensure these conditions are met.
	*/
	UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "My Object")
	void Destroy()
	{
		if (!IsPendingKill())
		{
			checkf(GetOwningActor()->HasAuthority() == true, TEXT("Destroy:: Object does not have authority to destroy itself!"));
			
			OnDestroyed();
			MarkPendingKill();
		}
	}
	
protected:
	virtual void OnDestroyed()
	{
		// Notify Owner etc.
	}
};

That’s pretty much all there is too it, we have now created a UObject that when created with a valid ‘Actor’ as the outer, can replicate both native and Blueprint properties, as well as correctly route RPC’s through the parent actor.

Notice that we are still bound by the usual rules that apply to Multiplayer in UE4 – Replication of properties is as always from Server->Client, and if we want to reference these objects over the network – they must either be Default Subobjects, or created by the Server at runtime and allowed to replicate through the Actor Channel.

These objects will also, like components, share the Network Relevancy, Dormancy and Frequency properties of their owning Actor. There is no way around that – if you want an Object that is always network-relevant, it’s actor must be always relevant too. For most cases, using an Actor or a Component is still a preferred (and less engineered) method of getting data from one connection to another.

Adding to the Subobject List

Now that we have our Object, all we need to do is create one and tell the actor to replicate it. Some important points, the Outer of the object should *always* be the Actor – and the Actor needs to be able to gather a reference to it somehow. The following is a basic example for an actor that contains both a single object, and an array of objects:

UCLASS()
class AMyAwesomeActor : public AActor
{
	GENERATED_BODY()
public:
	AMyAwesomeActor(const FObjectInitializer& OI);
	
	virtual bool ReplicateSubobjects(UActorChannel *Channel, FOutBunch *Bunch, FReplicationFlags *RepFlags) override
	{
		bool bWroteSomething = Super::ReplicateSubobjects(Channel, Bunch, RepFlags);
		
		// Single Object
		bWroteSomething |= Channel->ReplicateSubobject(MyObject, *Bunch, *RepFlags);
		
		// Array of Objects
		bWroteSomething |= Channel->ReplicateSubobjectList(ArrayOfMyObject, *Bunch, *RepFlags);
		
		return bWroteSomething;
	}
	
	virtual void GetLifetimeReplicatedProps( TArray< FLifetimeProperty > & OutLifetimeProps ) const override
	{
		Super::GetLifetimeReplicatedProps(OutLifetimeProps);
		
		// Replicating these properties is optional, but likely useful.
		DOREPLIFETIME(AMyAwesomeActor, MyObject);
		DOREPLIFETIME(AMyAwesomeActor, ArrayOfMyObject);
	}
	
protected:
	// Note: These properties do not neccesarily need to be replicated, but they likely would be in most cases.
	UPROPERTY(Replicated, BlueprintReadWrite, Category = "My Object")
	UMyAwesomeObject* MyObject;
	
	UPROPERTY(Replicated, BlueprintReadWrite, Category = "My Object")
	TArray<UMyAwesomeObject*> ArrayOfMyObject;
};

Like any network-relevant object, the lifespan of the object should be managed by the Server.

Note that the UPROPERTY() references to those objects (the array and the pointer) do not necccesarily need to be replicated, you could just as easily populate them in the same manner as AActor manages it’s internal list of ReplicatedComponents. Most of the time however, I suspect this will be wanted for most implementations.

Improving The System

We now have a reasonable system for replicating arbitrary Sub-Objects. Just like Components, these objects support all the usual UE4 networking features via the ActorChannel.

But there is one caveat to this implementation, and that is that we have to create a special Actor subclass to handle the replication of the Object. What can we do if we want to compartmentalise this into a common system that can be shared and used by any actor class? Imagine a scenario where you want to add an “Inventory” to an Actor, containing UObject-based Inventory “Slots”. Ultimately, this is the way the Hardpoint and Weapon system works in Project Orion.

Now it should be noted, that we still *always* want to ensure we create the UObjects using the Actor as the Outer. While ActorComponents can also provide an implementation for ReplicateSubobjects() – but importantly: subobjects are always created client-side using the Actor as the Outer.

I feel the need to put that in bold – because I learned the hard way that creating sub-objects with a non-actor outer can cause lots of obscure issues in regards to destruction and GC of the objects.

Slot-Driven Inventory System

With all of this in mind, the following is a nicer, more contained system for creating and replicating Subobjects, but in a way which allows us to support any existing actor class. The implementation below is a barebones similar example to my own slot-based inventory system that I put together for Project Orion.

The Inventory Slot

Some additional convenience properties for accessing the Inventory Component that manages us (note, there are other ways to reference the Inventory, but this is a convenient method).

UCLASS()
class UInventorySlot : public UMyAwesomeObject
{
	GENERATED_BODY()
public:
	/*
	* Accessor for the relevant inventory component
	*/
	UFUNCTION(BlueprintPure, Category = "Slot")
	UInventoryComponent* GetInventory() const
	{
		return ComponentOwnerPrivate;
	}
	
	virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override
	{
		Super::GetLifetimeReplicatedProps();
		
		DOREPLIFETIME_CONDITION(UInventorySlot, ComponentOwnerPrivate, COND_InitialOnly);
	}
	
private:
	friend class UInventoryComponent;

	UPROPERTY(Replicated)
	UInventoryComponent* ComponentOwnerPrivate;
};

The Inventory Component

UCLASS(meta = (BlueprintSpawnableComponent))
class UInventoryComponent : public UActorComponent
{
	GENERATED_BODY()
public:
	UInventoryComponent::UInventoryComponent(const FObjectInitializer& OI)
		: Super(OI)
	{
		// Component must be replicated to replicate sub-objects
		SetIsReplicatedByDefault(true);
	}
	
	virtual void GetLifetimeReplicatedProps(TArray<FLifetimeProperty>& OutLifetimeProps) const override
	{
		Super::GetLifetimeReplicatedProps(OutLifetimeProps);

		DOREPLIFETIME(UInventoryComponent, Slots);
	}
	
	virtual bool ReplicateSubobjects(UActorChannel* Channel, FOutBunch* Bunch, FReplicationFlags* RepFlags) override
	{
		bool bWroteSomething = Super::ReplicateSubobjects(Channel, Bunch, RepFlags);

		bWroteSomething |= Channel->ReplicateSubobjectList(Slots, *Bunch, *RepFlags);
		return bWroteSomething;
	}

	/*
	* Creates a new Inventory Slot of the given SlotClass
	*/
	UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "Slots", meta = (DeterminesOutputType = "SlotClass"))
	UInventorySlot* CreateSlot(const TSubclassOf<UInventorySlot> SlotClass)
	{
		if (SlotClass && !SlotClass->HasAnyClassFlags(CLASS_Abstract))
		{
			AActor* lOwner = GetOwner();
			
			checkf(lOwner != nullptr, TEXT("Invalid Inventory Owner"));
			checkf(lOwner->HasAuthority(), TEXT("Called without Authority!"));

			// Use the Actor as the Outer.
			UInventorySlot* NewSlot = NewObject<UInventorySlot>(lOwner, SlotClass);
			checkf(NewSlot != nullptr, TEXT("Unable to create inventory slot"));

			// Set immediately for replication
			NewSlot->ComponentOwnerPrivate = this;
			Slots.Add(NewSlot);

			return NewSlot;
		}
		
		return nullptr;
	}
	
	/*
	* Destroys a slot
	*/
	UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "Slots")
	bool DestroySlot(UInventorySlot* InSlot)
	{
		if (InSlot)
		{
			AActor* lOwner = GetOwner();

			checkf(lOwner != nullptr, TEXT("Invalid Inventory Owner"));
			checkf(lOwner->HasAuthority(), TEXT("Called without Authority!"));

			const int32 RemovedIndex = Slots.Remove(InSlot);
			if (RemovedIndex != INDEX_NONE)
			{
				InSlot->DestroySlot();
				return true;
			}
		}
		
		return false;
	}

	/*
	* Clears and destroys all Slots
	*/
	UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly, Category = "Slots")
	void DestroyAllSlots()
	{
		AActor* lOwner = GetOwner();

		checkf(lOwner != nullptr, TEXT("DestroySlot:: Invalid Inventory Owner"));
		checkf(lOwner->HasAuthority(), TEXT("DestroySlot:: Called without Authority!"));

		for (UInventorySlot* SlotItr : Slots)
		{
			if (IsValid(SlotItr))
			{
				SlotItr->DestroySlot();
			}
		}

		Slots.Empty();
	}
	
protected:
	// Ensure we destroy all objects when components is destroyed/unregistered
	virtual void OnUnregister() override
	{
		const AActor* lOwner = GetOwner();
		if (lOwner && lOwner->HasAuthority())
		{
			DestroyAllSlots();
		}
		
		Super::OnUnregister()
	}
	
private:
	/*
	* Slots maintained by this component
	*/
	UPROPERTY(Replicated)
	TArray<UInventorySlot*> Slots;
};

Happy Coding!

Better Burst Counters

Thu, 16 Apr 2020 22:13:09 +0100

ShooterGame is arguably one of the most comprehensive samples Epic Games has given us for Unreal Engine 4. Studying it is something of a rite-of-passage for C++ developers, especially given the overall popularity of shooters and Unreals’ heritage. It’s incredibly useful for familiarising yourself with how Unreal expects you to build your game, particularly if that game happens to involve shooting at things.

I can tell you on good authority that the sample has served as the basis for a huge number of FPS games over the last few years, ranging from ARK to PUBG and even Hell Let Loose. The sample is very comprehensive, and I still return to it regularly for reminders and ideas. If you’re interested or involved in building multiplayer projects in UE4, it’s certainly something you should take the time to look at.

Although quite dated at this point, the sample is still full of useful code and utilities and Epic even add new items to it now and again to show off new engine features (such as Replication Graph).

Whether you choose to base your project on the sample, make the switch to Gameplay Abilities, or start entirely from scratch – ShooterGame is great for teaching you the basics of handling multiplayer gameplay. This article will look at how we can improve on one of these ideas in particular.

Note: This article assumes some degree of familiarity with UE4’s replication system and the ShooterGame project.

What’s a Burst Counter?

A Burst Counter isn’t really a known term (I’ve also seen the technique described as a Flash Counter) – but the concept is quite straightforward. In a Multiplayer FPS game – a player needs to know when other players are firing weapons. Typically this is done purely so that we can play effects, like muzzle flashes and audio. There are lots of ways you can do this, and ShooterGame showcases the following method:

UCLASS(Abstract, Blueprintable)
class AShooterWeapon : public AActor
{
	GENERATED_UCLASS_BODY()

// etc...
	
protected:
	UPROPERTY(Transient, ReplicatedUsing=OnRep_BurstCounter)
	int32 BurstCounter;
	
	UFUNCTION()
	void OnRep_BurstCounter()
	{
		if (BurstCounter > 0)
		{
			SimulateWeaponFire();
		}
		else
		{
			StopSimulatingWeaponFire();
		}
	}
};

This modified snippet should give you a general idea of what’s going on – the Server increments the BurstCounter member each time the weapon fires a shot, and resets it to zero when the player stops firing. This replicated value is then received and used by non-local players to start and stop firing effects, such as muzzle flashes and audio. That’s really all there is to it (the player who is firing the weapon handles this locally).

This is much simpler (and cheaper!) than attempting to synchronize the entire weapon state across all connections. This is also a preferred approach to using Multicast RPCs, for several key reasons:

This is a property that will be changing often. We want to get all the updates to this property that we can, but we also want to allow the engines’ network prioritisation to stagger these updates based on relevancy if it needs to.
We want to leave the unreliable RPC buffer free for more important data, such as Character Movement and/or other mechanics that must remain responsive. (This matters more as we scale up).
We still want to know if a player has fired, even if we miss a few updates. (Becomes more important as we flesh out the implementation below)

This initial implementation looks good then – but it only really works well with looping effects, and you’ll soon find out why. Property Replication in UE4 is reliable, but it is also lossy. What this really means is that you are not guaranteed to receive every change made to a variable; you are only guaranteed to receive the eventual state. This is a common tripping point, especially if you only test multiplayer in the editor and not on a real-world connection. (Don’t do this – package and test often).

At the top-level – the replication system in UE4 works by having the Server iterate over all replicated properties at the end of the frame, comparing them to last sent state, and sending the new values to each connection where neccesary. In the real-world, these changes take variable amounts of time to reach each client, and some of those changes may end up being skipped entirely (from the clients point of view at least).

In addition, because the counter is reset to zero when the player stops firing, a single shot may cause the server to not register any change at all (the counter increments then immediatelly resets). The result is that clients may never be notified about single-shots and short bursts.

The following is a method for solving this issue, and we can even save some bandwidth at the same time. What we really want to know when we get an update is whether the player fired the weapon at all, and ideally whether they are still firing or not. We also want to catch those pesky short-bursts and single shots. This approach is a much more resilient implementation, let’s start by replacing the int32 counter with a USTRUCT() like so:

USTRUCT()
struct FRepBurstInfo
{
	GENERATED_BODY()
public:
	void ShotFired()
	{
		bIsFiring = true;
		ShotCounter++;
	}

	void StoppedFiring()
	{
		bIsFiring = false;
	}	

	bool WasShotFired(const FRepBurstInfo& Other) const
	{
		return ShotCounter != Other.ShotCounter;
	}
	
	bool HasBurstStopped() const
	{
		return !bIsFiring;
	}

	FRepBurstInfo()
		: ShotCounter(0)
		, bIsFiring(false)
	{}

protected:
	UPROPERTY() uint16 ShotCounter;
	UPROPERTY() bool bIsFiring;
};

And update the weapon class accordingly…

UCLASS()
class AWeapon : public AActor
{
	GENERATED_BODY()
public:
	void HandleFireShot()
	{
		// Firing implementation goes here.
		
		BurstCounter.ShotFired();
	}
	
	void StopFire()
	{
		// Stop firing implementation goes here.
		
		BurstCounter.StoppedFiring();
	}

protected:
	UPROPERTY(Transient, ReplicatedUsing = "OnRep_BurstCounter")
	FRepBurstInfo BurstCounter;
	
	// Optional 'PreviousValue' parameter allows us to compare the new value to the old one when received.
	UFUNCTION()
	void OnRep_BurstCounter(const FRepBurstInfo& PreviousValue);
}

We will implement the body of OnRep_BurstCounter() below – but the first thing you may notice is that we have immediately saved nearly 2-bytes of data per counter, simply by reducing the counter itself to a uint16. Think about it – we only care about absolute values for a counter, and we certainly don’t need the full range that 32-bits gives us!

In a typical shooter, this counter will likely be changing and therefore replicating very often. Making small trimmings here can have a huge impact on the total bandwidth use of the game. While I’d advise caution against premature optimization, it doesn’t hurt to keep these things in mind as you go. Personally, I find the process of working out how to squeeze data into smaller and smaller packets is one of more enjoyable aspects of network programming.

We will be compressing this down even further (to a mere byte!) – but for now, let’s check we understand the new behavior:

Each time we fire a shot, we set bIsFiring to true and increment the counter.
Each time we stop firing, we set bIsFiring to false – but we *DON’T* reset the counter.

The client can now gather more information from each update, and from fewer bits! Better still, we are much more resilient to lossy changes and single shots. The counter will always replicate after a shot is fired even if we are no longer firing. It will eventually wrap of course, but that’s not a problem – we don’t care about the value, we only care about the changes.

We could start using this straight away, but there’s one thing we haven’t taken into consideration which is Network Relevancy (also known as “culling”). When an actor moves too far away from the player, it is “culled” by the networking system. This can be tuned per-actor/class, but is generally done because objects that are nowhere near the player typically don’t affect them. This is an essential concept for optimization and large-scale online games. When an actor is culled, it is fully destroyed by the client – as far as they are concerned it no longer exists at all.

When the actor comes back into networking range, the Server tells the client to spawn the actor, and updates it with the latest state of all replicated properties. Remember that we are no longer resetting the counter to zero when firing stops, and since the counter will likely differ from the construction-time value of zero, the RepNotify will be immediatelly called and trigger our effects.

We don’t want this to happen each time another player pops back into range, and thankfully we can solve this easily. A simple trick is to check the CreationTime property of the actor when the RepNotify is called, and skip the rest of the method if it equals the current world time. The final implementation of OnRep_BurstCounter() therefore looks like this:

void AWeapon::OnRep_BurstCounter(const FRepBurstInfo& PreviousValue)
{
	const bool bFiredAnyShots = BurstCounter.WasShotFired(PreviousValue);
	if (bFiredAnyShots)
	{
		// Don't start new effects if this is an actor coming back to relevancy range.
		const bool bIsOpenChannelPacket = GetWorld()->TimeSince(CreationTime) == 0.f;
		if (bIsOpenChannelPacket == false)
		{
			OnBurstStarted();
		}
		
		// We may have fired a burst then immediately stopped (e.g, shotgun, semi-auto etc.)
		if (BurstCounter.StoppedFiring(PreviousValue))
		{
			OnBurstStopped();
		}
	}
	// Burst count may have wrapped and be undetectable.
	// If we stopped firing but were firing previously, ensure the stop event still fires
	else if (BurstCounter.HasBurstStopped() && !PreviousValue.HasBurstStopped())
	{
		OnBurstStopped();
	}
}

We’re almost there – but we can squeeze even more out of this. Now that we have these properties in a USTRUCT(), we can override the serialization behavior for when it is sent through the network. UE4 naturally provides a great system for this, and for more information you can check out Giuseppe Portelli’s fantastic article on the subject here.

By default, UE4 is able to replicated USTRUCT() members individually (so long as the struct is a member variable) – it will not replicate the entire struct if you only change a few of it’s properties. Note that if you decide to add your own NetSerialize() function, whatever you serialize will be sent each time as the engine assumes you know what you are doing.

Here is the final version of the Burst Counter struct, with an additional exposed option for byte/short compression, and a more optimal network footprint. Note that the option to compress to a byte cannot be changed at runtime, as this would break serialization between the Server and Client.

#define MAX_BURST_COUNT_BYTE 0x003f		// 63 (6 bits)
#define MAX_BURST_COUNT_SHORT 0x3fff	// 16383 (14 bits)

USTRUCT(BlueprintType, meta = (DisplayName = "Burst Info"))
struct FRepBurstInfo
{
	GENERATED_BODY()
public:
	FORCEINLINE void ShotFired()
	{
		bIsFiring = true;
		ShotCounter = (ShotCounter + 1) % (bCompressByte ? MAX_BURST_COUNT_BYTE : MAX_BURST_COUNT_SHORT);
	}

	FORCEINLINE void StoppedFiring()
	{
		bIsFiring = false;
	}
	
	FORCEINLINE bool WasShotFired(const FRepBurstInfo& Other) const
	{
		return ShotCounter != Other.ShotCounter;
	}
	
	FORCEINLINE bool HasBurstStopped() const
	{
		return !bIsFiring;
	}

	bool NetSerialize(FArchive& Ar, class UPackageMap* Map, bool& bOutSuccess)
	{
		Ar.SerializeBits(&bCompressByte, 1);
		Ar.SerializeBits(&bIsIncrementing, 1);
		Ar.SerializeBits(&ShotCounter, bCompressByte ? 6 : 14);

		bOutSuccess = true;
		return true;
	}

	FRepBurstInfo()
		: ShotCounter(0)
		, bIsFiring(false)
		, bCompressByte(true)
	{}

protected:
	UPROPERTY(Transient, BlueprintReadOnly, Category = "Burst Counter")
	uint16 ShotCounter;
	
	UPROPERTY(Transient, BlueprintReadOnly, Category = "Burst Counter")
	bool bIsFiring;
	
	UPROPERTY(EditDefaultsOnly, BlueprintReadOnly, Category = "Burst Counter")
	bool bCompressByte;
};

// This special template class is required to let UE4 know we have a NetSerialize() function.
template<>
struct TStructOpsTypeTraits<FHT_RepBurstInfo> : public TStructOpsTypeTraitsBase2<FHT_RepBurstInfo>
{
	enum
	{
		WithNetSerializer = true,
		WithNetSharedSerialization = true, // We can use the Shared serialization method as we do not have any pointer members.
	};
};

What we’re doing here is packing the properties of our USTRUCT() into the equivalent of 8 or 16 bits, depending on the value of bCompressByte. Compressing this way gives us fewer available bits for the counter, but ask yourself – how likely is it that the player will fire 60+ shots between replication frames? (Spoiler: very unlikely). Even if they do, most of the time we aren’t interested in how many shots were fired, we just want to be made aware of changes.

Of course, if you *do* want to know how many shots were fired between updates, you can add a utility function to the struct like this. This is subject to wrapping issues of course, but only in very extreme cases.

uint16 FRepBurstInfo::NumShotsFired(const FRepBurstInfo& Previous) const
{
	if (WasShotFired(Previous))
	{
		// If > previous we haven't wrapped
		if (ShotCounter > Previous.ShotCounter)
		{
			return ShotCounter - Previous.ShotCounter;
		}
		// If < previous value, we just wrapped. 99% of the time this should be fine unless the fire rate is utterly stupendous
		else if (ShotCounter < Previous.ShotCounter)
		{
			const uint16 DiffFromMax = (bCompressByte ? MAX_BURST_COUNT_BYTE : MAX_BURST_COUNT_SHORT) - Previous.ShotCounter;
			return ShotCounter + DiffFromMax + 1;
		}
	}

	return 0;
}

To be honest, the use of uint16 and the optional toggle may be superfluos here – you could avoid the optional bCompressByte and leave 7 bits for the counter. If it’s any help deciding, I am yet to require the full 16-bit counter on any project I’ve worked on to date (even with the crazy fire rates of weapons in Project Orion).

BONUS – AUTO-LOOPING

So we’ve managed to provide the client with more information in a smaller data packet – a great win! However one sneaky issue remains that becomes very noticeable with non-looping effects – and it’s something that only typically presents itself in a high-traffic game and/or on a poor connection…

VIDEO

Notice the stuttering effect of the players weapon? What’s happening here is that even though we are receiving all those nice low-cost updates to the burst counter, we are receiving them at variable time. Jitter and latency is not constant, and while using looping audio and FX is great for hiding the seams, they are typically more difficult to author and use.

A great way to fix this issue, or at least mask it, is to simulate a steady stream of packets by starting/stopping a looping timer when shots are fired. If we know the firing rate of the weapon and we know the player is firing, all we need to do is setup a looping timer to keep simulating the effects between updates.

This eliminates the stuttering issue, and while it may not be 100% accurate (e.g, players may appear to fire more shots than they really are in poor network conditions) – it’s much more preferable to the staccato-like effect of before:

VIDEO