Objects

Explanations of the basic gameplay elements, Actors and Objects.

Choose your operating system:

Windows

macOS

Linux

The UCLASS Macro

The UCLASS macro gives the UObject a reference to a UCLASS that describes its Unreal-based type. Each UCLASS maintains one Object called the 'Class Default Object', or CDO for short. The CDO is essentially a default 'template' Object, generated by the class constructor and unmodified thereafter. Both the UCLASS and the CDO can be retrieved for a given Object instance, though they should generally be considered read-only. The UCLASS for an Object instance can be accessed at any time using the GetClass() function.

A UCLASS contains a set of properties and functions that define the class. These are normal C++ functions and variables available to native code, but tagged with Unreal-specific metadata that controls how they behave within the Object system. For more details about the tagging syntax, see the Programming Reference .

Note that a UObject class can also include native-only properties that do not exist within the corresponding UCLASS.

Properties And Function Types

UObjects can have member variables (known as properties) or functions of any type. However, in order for the Unreal Engine to recognize and manipulate those variables or functions, they must be marked with special macros and must conform to certain type standards. For detail on those stanards, see the Properties and UFunctions reference pages.

Object Creation

There are several functions that can be used to create new UObject instances as well as the standard new operator; each of which have their own use case:


Method	Description
`NewObject<class>`	Creates a new instance with optional parameters for all available creation options. Offers a wide range of flexibility, including simple use cases with an automatically generated name.
`new`	Use to construct Objects in certain low level circumstances, such as when the constructor requires arguments.

Functionality Provided by UObjects

It is not required or even appropriate to use this system in all cases, but there are many benefits to doing so, including:

Garbage collection
Reference updating
Reflection
Serialization
Automatic updating of default property changes
Automatic property initialization
Automatic editor integration
Type information available at runtime
Network replication

For more detail on each of these systems, see the Unreal Object Handling documentation.

The Unreal Header Tool

In order to harness the functionality provided by UObject-derived types, a preprocessing step needs to be run on the header files for these types in order to collate the information it needs. This preprocessing step is performed by the UnrealHeaderTool, or UHT for short.

UObject-derived types have a certain structure that needs to be adhered to, which we will cover here.

Header File Format

While a UObject's implementation in a source (.cpp) file is just like any other C++ class, its definition in a header (.h) file must adhere to a certain basic structure in order to work properly with Unreal Engine 4. Using the editor's "New C++ Class" command is the easiest way to set up a correctly-formatted header file. A basic header file for a UObject-derived class might look like this, assuming the UObject derivative is called UMyObject and the project in which it was created is called MyProject:

#pragma once

#include 'Object.h'
#include 'MyObject.generated.h'

/**
 * 
 */
UCLASS()
class MYPROJECT_API UMyObject : public UObject
{
    GENERATED_BODY()

};

The Unreal-specific parts of this are as follows:

#include "MyObject.generated.h"

This line is expected to be the the last #include directive in the file. If this header file needs to know about other classes, they can be forward declared anywhere in the file, or included above MyObject.generated.h.

UCLASS()

The UCLASS macro makes UMyObject visible to Unreal Engine 4. The macro supports a variety of Class Specifiers that determine which features are turned on or off for the class.

class MYPROJECT_API UMyObject : public UObject

Specifying MYPROJECT_API is necessary if MyProject wishes to expose the UMyObject class to other modules. This is most useful for modules or plugins that will be included by game projects and which deliberately expose classes to provide portable, self-contained functionality across multiple projects.

GENERATED_BODY()

The GENERATED_BODY macro takes no arguments, but sets up the class to support the infrastructure required by the engine. It is required for all UCLASSes.

Updating Objects

Ticking refers to how Objects are updated in Unreal Engine. All Objects have the ability to be ticked each frame, allowing you to perform any update calculations or actions that are necessary.

Objects do not possess any built-in update ability; however, this ability can be added when necessary by inheriting from the FTickableGameObject class using the inherits class specifier. They can then implement the Tick() function, which will be called each frame by the Engine. Note that most in-game Objects will be Actors , which can tick at user-set minimum intervals rather than once per frame.

Destroying Objects

Note that Weak Pointers have no impact on whether an Object is garbage collected or not.

Object destruction is handled automatically by the garbage collection system when an Object is no longer referenced. This means that no UPROPERTY pointers, or engine containers or smart pointer class instances should have any strong references to it. When the garbage collector runs, unreferenced Objects that are found will be deleted. In addition, the function MarkPendingKill() can be called directly on an Object, and this function will set all pointers to the Object to NULL, as well as remove the Object from global searches. Once again, the Object will be fully deleted on the next garbage collection pass.