Language:
Page Info
Engine Version:

Objects

Choose your OS:

Unreal has a robust system for handling game objects. The base class for objects in Unreal is UObject. The UCLASS macro can be used to tag classes derived from UObject so that the UObject handling system is aware of them.

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 Functions 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 an automatically generated name. Best practice to use for simple cases.

NewNamedObject<class>()

Creates a new instance using a specified name along with a few other optional parameters. Asserts if the name conflicts within the new instance's Outer.

ConstructObject<class>()

Creates a new instance providing all available creation options. Use only when flexibility is required.

new

Use to construct Objects in certain low level circumstances, such as when the constructor requires arguments.

See UObject Instance Creation for detailed info on the various methods of creating instances of UObject classes for gameplay.

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. Note that the GENERATED_BODY macro sets the member access level to "public" rather than the language default of "private" in the current version of the engine.

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

Object destruction is handled automatically by the garbage collection system when an Object is no longer referenced by the engine. This means that no UPROPERTY pointers, or engine containers or smart pointer class instances (such as TArray<UObject*> or TWeakPtr<UObject*>) have any pointers 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.