UGameplayStatics class in Unreal Engine

Author: Vladimír Nepor
Published on

What class to select to fit the needs? How they differ each other and for what purpose are they intended?

UGameplayStatics is a static class with useful gameplay utility functions that can be called from both Blueprint and C++

Inheritance Hierarchy

Get all Actors of Class

int32 ASomeClass::GetTargetCount()
{
   TArray<AActor*> ActorsArr;
   UGameplayStatics::GetAllActorsOfClass(this, AtargetedActor::StaticClass(), ActorsArr);
   return ActorsArr.Num();
}

Apply Damage

It applies a damage. It's usually inside OnHit or similar triggerthat provides OtherActor, Damage and other parameters.

UGameplayStatics::ApplyDamage(OtherActor, Damage, GetOwner()->GetInstigatorController(), this, UDamageType::StaticClass());

An alternate way to applying damage is a TakeDamage() function provided by AActor class. As it's a virtual function, you can override it in any class inherited from AActor and process a functionality for applying a damage.

Spawn UGameplayStatics item

Plays the specified effect at the given location, rotation, fire and forget, once completed. It works also for sounds.

Dynamically creates UParticleSystem class in the runtime.

It's usually inside OnHit or similar trigger.

  • Spawn particle effect

    SpawnEmitterAtLocation

    When the effect is being spawned within the given Actor, such as existing bullet in the form of AProjectile, a following code to play a sound can be used

    if(Hitparticles) UGameplayStatics::SpawnEmitterAtLocation(this, HitPartices, GetActorLocation(), GetActorRotation());

    If a particle effect is being triggered from a different AActor, such as ACharacter (e.g. because we do not use bullet objects in the project), there's necessary to work with a trigger providing a Hit.Location, such as ,OnHit. Then there can be used something like the following code to spawn an effect.

    UGameplayStatics::SpawnEmitterAtLocation(GetWorld(), FlashFile, Hit.Location, ShotDirection.Rotation());

    SpawnEmitterAttached - Spawn into a socket pointer

    // .h file
UPROPERTY(EditAnywhere)
UParticleSystem* FlashFile;
// .cpp file
UGameplayStatics::SpawnEmitterAttached(FlashFile, Mesh, TEXT("FlashFileSocket"));

  • Spawn Sound into a socket pointer

    // .h file
UPROPERTY(EditAnywhere)
USoundBase* SoundFile;
// .cpp file
UGameplayStatics::SpawnSoundAttached(SoundFile, Mesh, TEXT("SoundFileSocket"));

Play Sound

When the sound is being played within the given Actor, such as existing bullet in the form of AProjectile, a following code to play a sound can be used

if(HitSound) UGameplayStatics::PlaySoundAtLocation(this, HitSound, GetActorLocation());

If a game sound is being triggered from a different AActor, such as ACharacter (e.g. because we do not use bullet objects in the project), there's necessary to work with a trigger providing a Hit.Location, such as ,OnHit. Then there can be used something like the following code to play a sound.

UGameplayStatics::PlaySoundAtLocation(GetWorld(), SoundFile, Hit.Location);

For sounds settings and working withe the sound, check Sound in Unreal Engine wiki page.

Get All Actors Of Class Examples

Get the names of all actors in the current editor world

#include "Kismet/BlueprintFunctionLibrary.h" // Engine
/**
 * Get the names of all actors in the current editor world
 *
 * @param bOutSuccess			If the action was a success or not
 * @param OutInfoMsg			More information about the action's result
 * 
 * @return Names of all the actors
 */
UFUNCTION(BlueprintCallable, Category = "Alex Quevillon - Get All Actors Of Class")
static TArray<FString> GetNamesOfAllActors(bool& bOutSuccess, FString& OutInfoMsg);
#include "Kismet/GameplayStatics.h" // Engine
#include "EngineUtils.h" // Engine
#include "Engine/StaticMeshActor.h" // Engine

TArray<FString> UExampleClass::GetNamesOfAllActors( bool& bOutSuccess, FString& OutInfoMsg)
{
	// Get the world from somewhere. In this case, we take the editor world.
	// But you can also get it from somewhere else. e.g. from any Actor or by loading the world asset with StaticLoadObject
	UWorld* World = GEditor ? GEditor->GetEditorWorldContext().World() : nullptr;
	if (World == nullptr)
	{
		bOutSuccess = false;
		OutInfoMsg = FString::Printf(TEXT("Get Names Of All Actors Failed - World is not valid"));
		return TArray<FString>();
	}

	// New list of names
	TArray<FString> Names = TArray<FString>();

	// List that'll receive the actors
	TArray<AActor*> Actors = TArray<AActor*>();

	// Get the actors
	UGameplayStatics::GetAllActorsOfClass(World, AActor::StaticClass(), Actors);

	// Loop through all the actors
	for (AActor* Actor : Actors)
	{
		// Get the Actor's name
		Names.Add(Actor->GetName());
	}
	
	// Return the names
	bOutSuccess = true;
	OutInfoMsg = FString::Printf(TEXT("Get Names Of All Actors Succeeded"));
	return Names;
}

Get the Mesh names of all static mesh actors in the current editor world

#include "Kismet/BlueprintFunctionLibrary.h" // Engine
/**
 * Get the Mesh names of all static mesh actors in the current editor world
 *
 * @param bOutSuccess		If the action was a success or not
 * @param OutInfoMsg		More information about the action's result
 *
 * @return Names of all the actors
 */
UFUNCTION(BlueprintCallable, Category = "Alex Quevillon - Get All Actors Of Class")
static TArray<FString> GetMeshNamesOfAllStaticMeshActors(bool& bOutSuccess, FString& OutInfoMsg);
#include "Kismet/GameplayStatics.h" // Engine
#include "EngineUtils.h" // Engine
#include "Engine/StaticMeshActor.h" // Engine
	
TArray<FString> UExampleClass::GetMeshNamesOfAllStaticMeshActors(bool& bOutSuccess, FString& OutInfoMsg)
{
	// Get the world
	UWorld* World = GEditor ? GEditor->GetEditorWorldContext().World() : nullptr;
	if (World == nullptr)
	{
		bOutSuccess = false;
		OutInfoMsg = FString::Printf(TEXT("Get Mesh Names Of All Static Mesh Actors Failed - World is not valid"));
		return TArray<FString>();
	}

	// New list of names
	TArray<FString> Names = TArray<FString>();

	// Get Actors
	TArray<AActor*> Actors = TArray<AActor*>();
	UGameplayStatics::GetAllActorsOfClass(World, AStaticMeshActor::StaticClass(), Actors);

	// Loop through all static mesh actors and get static mesh names
	for (AActor* Actor : Actors)
	{
		AStaticMeshActor* StaticMeshActor = Cast<AStaticMeshActor>(Actor);
		Names.Add(StaticMeshActor->GetStaticMeshComponent()->GetStaticMesh()->GetName());
	}

	// Return the names
	bOutSuccess = true;
	OutInfoMsg = FString::Printf(TEXT("Get Mesh Names Of All Static Mesh Actors Succeeded"));
	return Names;
}