Unreal Engine Basics 03 - Gameplay

Unreal Engine Basics
Chapter 3: Gameplay
Nick Prühs

Objectives
• Learning how to expose class fields and functions to blueprints
• Writing basic Unreal gameplay code, such as spawning actors,
accessing components and listening for events
• Getting familiar with gameplay concepts in the context of Unreal, such
as damage and collision

UPROPERTY
• For the Unreal reflection system to be able to discover C++ fields, we
need to annotate them with the UPROPERTY macro
 This is required for the garbage collector to observe these properties.
Forgetting to annotate a field of type UObject (or subtypes) can
result in crashes when trying to access that field!
 We can specify the behavior of the Unreal Editor with respect to
these fields by adding additional specifiers as parameters to that
macro.
/** Class of the projectile to fire. */
UPROPERTY(EditDefaultsOnly)
TSubclassOf<AActor> ProjectileClass;

UPROPERTY – Accessibility Specifiers
Specifier Description
VisibleDefaultsOnly Only visible in property windows for archetypes, and cannot be
edited.
VisibleInstanceOnly Only visible in property windows for instances, not for
archetypes, and cannot be edited.
VisibleAnywhere Visible in all property windows, but cannot be edited.
EditDefaultsOnly Can be edited by property windows, but only on archetypes.
EditInstanceOnly Can be edited by property windows, but only on instances, not
on archetypes.
EditAnywhere Can be edited by property windows, on archetypes and
instances.

UPROPERTY – Accessibility & Other Specifiers
BlueprintReadOnly Can be read by Blueprints, but not modified.
BlueprintReadWrite Can be read or written from a Blueprint.
Category Category of the property when displayed in Blueprint editing
tools.
Config Value can be saved to the .ini file associated with the class and
will be loaded when created.
Replicated Replicated over the network.
ReplicatedUsing=
FunctionName
Replicated over the network, with a callback function which is
executed when the property is updated. Must be a UFUNCTION
(see later).

Class References
• Class references in Unreal are represented by pointers to UClass objects
(similar to Type references in Java or C#)
• To enforce compile-time type safety, you can use the template class
TSubclassOf
 The implementation of that template class will force you to include the
header of the referenced type – a forward declaration won’t be enough and
can lead to strange errors.
 This will automatically cause Unreal Editor windows to filter dropdowns for
selecting a class.
/** Class of the projectile to fire. */
UPROPERTY(EditDefaultsOnly)
TSubclassOf<AActor> ProjectileClass;

UCLASS Specifiers
Abstract Prevents the user from adding Actors of this class to Levels.
Blueprintable Acceptable base class for creating Blueprints.
NotBlueprintable Not an acceptable base class for creating Blueprints. (Default)
BlueprintType Type that can be used for variables in Blueprints.
Config Allowed to store data in a configuration file (.ini).
Classes can be annotated with UCLASS, another Unreal Engine macro:

UCLASS Specifiers
BlueprintSpawnableCom
ponent
Component class can be spawned by a Blueprint.
DisplayName Name of this node in a Blueprint.
Another UCLASS specifier provides additional options:
/** Adds a weapon to the actor, that fires projectiles. */
UCLASS(meta = (BlueprintSpawnableComponent))
class AWESOMESHOOTER_API UASWeaponComponent : public UActorComponent

Accessing Components in C++
In general, Actor components can be accessed by two Actor functions:
• Unfortunately, there’s no templated version of the function for getting
multiple components of a specific type.
• You should always check the return value for nullptr, in case the actor
doesn’t have the specified component.
template<class T> T* AActor::FindComponentByClass() const
TArray<UActorComponent*> AActor::GetComponentsByClass
(TSubclassOf<UActorComponent> ComponentClass) const;

Defensive Programming
• As always when writing code, you should be careful with null pointers
that can cause your game to crash when being dereferenced.
• Unreal Engine features a special function for this:
• IsValid will ensure that an object reference
 is not null
 is not pending kill (e.g. was destroyed)
 has not been garbage collected
• As UObject function, this is available almost everywhere in your code.
FORCEINLINE bool UObject::IsValid(const UObject *Test)

Spawning & Destroying Actors
• You can spawn new actors at runtime by calling one of various overloads
of the UWorld::SpawnActor function.
 Allows you to specify the type and transform of actor to spawn
 Allows you to specify additional spawn parameters, such as
o Owner of the new actor (for replication)
o Instigator of the new actor (for damage)
o How to handle spawn collisions (e.g. always spawn, adjust position, don’t
spawn)
• Access to the UWorld is provided by AActor::GetWorld() in turn.
• SpawnActor will return a nullptr if spawning fails, so you should always
check for its return value before proceeding.
• Actors can be destroyed again by calling AActor::Destroy()

UFUNCTION Specifiers
BlueprintCallable Can be executed in a Blueprint graph.
BlueprintImplementableEvent Can be implemented in a Blueprint graph.
BlueprintNativeEvent Declares an additional function named the same as the
main function, but with _Implementation added to the
end, which is where code should be written. The auto-
generated code will call the "_Implementation" method if
no Blueprint override is found.
Just as classes and fields, functions can be annotated with UFUNCTION,
another Unreal Engine macro:

BlueprintPure Does not affect the owning object in any way and can be
executed in a Blueprint graph. Usually makes sense in
conjunction with C++ const.
Category Category of the function when displayed in Blueprint
editing tools.
Exec Can be executed from the in-game console.

Client Only executed on the client that owns the object on which the function is called. Declares an
additional function named the same as the main function, but with _Implementation
added to the end. The auto-generated code will call the _Implementation method when
necessary.
Server Only executed on the server. Declares an additional function (see Client). Requires
WithValidation.
WithValidation Declares an additional function named the same as the main function, but with _Validate
added to the end. This function takes the same parameters, and returns a bool to indicate
whether or not the call to the main function should proceed.
NetMulticast Executed both locally on the server, and replicated to all clients.

Reliable Replicated over the network, and is guaranteed to arrive regardless of
bandwidth or network errors.
Unreliable Replicated over the network, but can fail due to bandwidth limitations
or network errors.

Casting in Unreal
• In general, it’s recommended to cast Unreal references using the
templated Cast function.
 Makes use of Unreal reflections
 Simlar to dynamic_cast, returns a nullptr if the types don’t match
for (UActorComponent* ActorComponent : ActorComponents)
{
UPrimitiveComponent* PrimitiveComponent = Cast<UPrimitiveComponent>(ActorComponent);
if (PrimitiveComponent != nullptr)
{
// ...
}
}

Events
You can declare events to raise and listen to by declaring a delegate (function
signature) signature first, and the event itself afterwards:
(Note the commas between the parameter types and names.)
Then, the event can be raised by calling its Broadcast method.
DECLARE_DYNAMIC_MULTICAST_DELEGATE_ThreeParams
(FASCollisionDamageComponentDamageDealtSignature,
AActor*, Actor, float, Damage, AActor*, Target);
// ...
/** Event when the actor has dealt collision damage. */
UPROPERTY(BlueprintAssignable)
FASCollisionDamageComponentDamageDealtSignature OnDamageDealt;
// Notify listeners.
OnDamageDealt.Broadcast(GetOwner(), Damage, OtherActor);

Events
You can add event listeners by calling AddDynamic for an event
• The event handler function has to be a UFUNCTION
• Don’t do this in the constructor of a class – wait until BeginPlay instead
void UASCollisionDamageComponent::BeginPlay()
{
// ...
for (UActorComponent* ActorComponent : ActorComponents)
{
UPrimitiveComponent* PrimitiveComponent = Cast<UPrimitiveComponent>(ActorComponent);
PrimitiveComponent->OnComponentBeginOverlap.AddDynamic(this,
&UASCollisionDamageComponent::OnComponentBeginOverlap);
}
}
void UASCollisionDamageComponent::OnComponentBeginOverlap
(UPrimitiveComponent* OverlappedComponent, AActor* OtherActor, UPrimitiveComponent*
OtherComp, int32 OtherBodyIndex, bool bFromSweep, const FHitResult& SweepResult)
{
UE_LOG(LogAS, Log, TEXT("Overlap!"));
}

Collision
• When a collision event occurs, both objects involved can be set to
affect or be affected by blocking, overlapping, or ignoring each other.
 Blocking occurs when both objects block each other.
o Blocking („hits“) can raise additional events by enabling „Simulation
Generates Hit Events“ for either actor
 Overlapping occurs if one actor is overlapping the other, and the
other is blocking the former.
o Overlapping will only raise events when enabling “Generate Overlap
Events” for both Actors for performance reasons
 All affected objects must have Collision Enabled for either of this to
happen

Handling Collisions in C++
• Collisions can be handled in C++ in various ways:
 By listening to UPrimitiveComponent events
o OnComponentHit
o OnComponentBeginOverlap
o OnComponentEndOverlap
 By listening to AActor events
o OnActorHit
o OnActorBeginOverlap
o OnActorEndOverlap

Handling Collisions in C++
• Collisions can be handled in C++ in various ways:
 By overriding AActor functions
o virtual void NotifyHit(class UPrimitiveComponent*
MyComp, AActor* Other, class UPrimitiveComponent*
OtherComp, bool bSelfMoved, FVector HitLocation,
FVector HitNormal, FVector NormalImpulse, const
FHitResult& Hit);
o virtual void NotifyActorBeginOverlap(AActor*
OtherActor);
o virtual void NotifyActorEndOverlap(AActor* OtherActor);

Projectiles
• As if Epic has been making shooters before, Unreal Engine features the
UProjectileMovementComponent for basic projectile movement
 Allows to specify initial speed or velocity, and maximum speed
 Can ignore gravity
 Can automatically rotate to „follow“ velocity
 Can follow targets („homing“)
 Can bounce

Taking Damage
• Actors provide a virtual function to allow gameplay code to handle damage as
desired:
• UDamageType is passed with FDamageEvent and allows you to define and handle
special types of damage, if necessary
• Instigator references to the player who was dealt damage, allowing for keeping
track of scores in match-based game modes
• Damage causer is the actual actor who dealt damage (e.g. projectile)
• Actors will notify interested listeners by raising AActor::OnTakeAnyDamage
• Damage can be negative
virtual float TakeDamage(float DamageAmount, struct FDamageEvent const&
DamageEvent, class AController* EventInstigator, AActor* DamageCauser);

Actor Lifespans
• AActor::InitialLifeSpan can be set (e.g. in editor or constructor)
to automatically destroy an Actor after a fixed timespan
• If you want to change the remaining lifespan of an Actor, use
AActor::SetLifeSpan instead.
 Passing 0.0f will prevent the actor from being destroyed
automatically.

Hint!
You can specify default values for UPROPERTY fields in the constructor of
a class.

Assignment #3 – Core Gameplay
1. Create a WeaponComponent for storing projectile references.
2. Create a HealthComponent for taking damage and destroying actors.
3. Bind input for firing projectiles.
4. Create a CollisionDamageComponent for dealing damage on overlap.
5. Create a Projectile blueprint, and add weapon and health to your
Character blueprint.
6. Store the kills each player achieved.
7. Bind input for respawning players
(APlayerController::ServerRestartPlayer).
8. Add a score limit to your game mode.
Bonus: Create a blueprint for health pickups.

References
• Epic Games. Properties. https://docs.unrealengine.com/en-
US/Programming/UnrealArchitecture/Reference/Properties/index.html, February
2020.
• Epic Games. Classes. https://docs.unrealengine.com/en-
US/Programming/UnrealArchitecture/Reference/Classes/index.html, February
2020.
• Epic Games. Functions. https://docs.unrealengine.com/en-
US/Programming/UnrealArchitecture/Reference/Functions/index.html, February
2020.
• Epic Games. Collision Overview. https://docs.unrealengine.com/en-
US/Engine/Physics/Collision/Overview/index.html, Feburary 2020.
• Epic Games. Dynamic Delegates. https://docs.unrealengine.com/en-
US/Programming/UnrealArchitecture/Delegates/Dynamic/index.html, February
2020.

See you next time!
https://www.slideshare.net/npruehs
https://github.com/npruehs/teaching-
unreal-engine/releases/tag/assignment03
npruehs@outlook.com

5 Minute Review Session
• When and why should you annotate a class field with UPROPERTY?
• How can you express class references in Unreal C++?
• How do you spawn and destroy actors?
• How can you listen to events in C++ in Unreal?
• Which collision types do exist in Unreal?
• How does the Unreal game framework support damage?

Unreal Engine Basics 03 - Gameplay

Related slideshows

More Related Content

Unreal Engine Basics 03 - Gameplay