Making a UCLASS – deriving from UObject

When coding with C++, you can have your own code that compiles and runs as native C++ code, with appropriate calls to new and delete to create and destroy your custom objects. Native C++ code is perfectly acceptable in your UE4 project as long as your new and delete calls are appropriately paired so that no leaks are present in your C++ code.

You can, however, also declare custom C++ classes, which behave like UE4 classes, by declaring your custom C++ objects as UCLASS. UCLASS use UE4's Smart Pointers and memory management routines for allocation and deallocation according to Smart Pointer rules, can be loaded and read by the UE4 Editor, and can optionally be accessed from Blueprints.

Tip

Note that when you use the UCLASS macro, your UCLASS object's creation and destruction must be completely managed by UE4: you must use ConstructObject to create an instance of your object (not the C++ native keyword new), and call UObject::ConditionalBeginDestroy() to destroy the object (not the C++ native keyword delete). How to create and destroy your UObject-derivative classes is outlined in the Instantiating UObject-derived classes (ConstructObject <> and NewObject <>) and Destroying UObject-derived classes sections later in this chapter.

Getting ready

In this recipe, we will outline how to write a C++ class that uses the UCLASS macro to enable managed memory allocation and deallocation as well as to permit access from the UE4 Editor and Blueprints. You need a UE4 project into which you can add new code to use this recipe.

How to do it...

To create your own UObject derivative class, follow the steps below:

1. From your running project, select File | Add C++ Class inside the UE4 Editor.
2. In the Add C++ Class dialog that appears, go to the upper-right side of the window, and tick the Show All Classes checkbox:
   
3. Create a UCLASS by choosing to derive from the Object parent class. UObject is the root of the UE4 hierarchy. You must tick the Show All Classes checkbox in the upper-right corner of this dialog for the Object class to appear in the list view.
4. Select Object (top of the hierarchy) as the parent class to inherit from, and then click on Next.

   Tip

   Note that although Object will be written in the dialog box, in your C++ code, the C++ class you will deriving from is actually UObject with a leading uppercase U. This is the naming convention of UE4:

   UCLASS deriving from UObject (on a branch other than Actor) must be named with a leading U.

   UCLASS deriving from Actor must be named with a leading A (Chapter 4, Actors and Components).

   C++ classes (that are not UCLASS) deriving from nothing do not have a naming convention, but can be named with a leading F (for example, FAssetData), if preferred.

   Direct derivatives of UObject will not be level placeable, even if they contain visual representation elements such as UStaticMeshes. If you want to place your object inside a UE4 level, you must at least derive from the Actor class or beneath it in the inheritance hierarchy. See Chapter 4, Actors and Components for how to derive from the Actor class for a level-placeable object.

   This chapter's example code will not be placeable in the level, but you can create and use Blueprints based on the C++ classes that we write in this chapter in the UE4 Editor.

5. Name your new Object derivative something appropriate for the object type that you are creating. I call mine UserProfile. This comes off as UUserObject in the naming of the class in the C++ file that UE4 generates to ensure that the UE4 conventions are followed (C++ UCLASS preceded with a leading U).
6. Go to Visual Studio, and ensure your class file has the following form:

   #pragma once
   
   #include "Object.h" // For deriving from UObject
   #include "UserProfile.generated.h" // Generated code
   
   // UCLASS macro options sets this C++ class to be 
   // Blueprintable within the UE4 Editor
   UCLASS( Blueprintable )
   class CHAPTER2_API UUserProfile : public UObject
   {
     GENERATED_BODY()
   };

7. Compile and run your project. You can now use your custom UCLASS object inside Visual Studio, and inside the UE4 Editor. See the following recipes for more details on what you can do with it.

How it works…

UE4 generates and manages a significant amount of code for your custom UCLASS. This code is generated as a result of the use of the UE4 macros such as UPROPERTY, UFUNCTION, and the UCLASS macro itself. The generated code is put into UserProfile.generated.h. You must #include the UCLASSNAME.generated.h file with the UCLASSNAME.h file for compilation to succeed. Without including the UCLASSNAME.generated.h file, compilation would fail. The UCLASSNAME.generated.h file must be included as the last #include in the list of #include in UCLASSNAME.h:

The error that occurs when a UCLASSNAME.generated.h file is not included last in a list of includes is as follows:

>> #include found after .generated.h file - the .generated.h file should always be the last #include in a header

There's more…

There are a bunch of keywords that we want to discuss here, which modify the way a UCLASS behaves. A UCLASS can be marked as follows:

• Blueprintable: This means that you want to be able to construct a Blueprint from the Class Viewer inside the UE4 Editor (when you right-click, Create Blueprint Class… becomes available). Without the Blueprintable keyword, the Create Blueprint Class… option will not be available for your UCLASS, even if you can find it from within the Class Viewer and right-click on it:
  
• The Create Blueprint Class… option is only available if you specify Blueprintable in your UCLASS macro definition. If you do not specify Blueprintable, then the resultant UCLASS will not be Blueprintable.
• BlueprintType: Using this keyword implies that the UCLASS is usable as a variable from another Blueprint. You can create Blueprint variables from the Variables group in the left-hand panel of any Blueprint's EventGraph. If NotBlueprintType is specified, then you cannot use this Blueprint variable type as a variable in a Blueprints diagram. Right-clicking the UCLASS name in the Class Viewer will not show Create Blueprint Class… in its context menu:
  

Any UCLASS that have BlueprintType specified can be added as variables to your Blueprint class diagram's list of variables.

You may be unsure whether to declare your C++ class as a UCLASS or not. It is really up to you. If you like Smart Pointers, you may find that UCLASS not only make for safer code, but also make the entire code base more coherent and more consistent.

See also

• To add additional programmable UPROPERTY to the Blueprints diagrams, see the Creating a user-editable UPROPERTY section below. For details on referring to instances of your UCLASS using appropriate Smart Pointers, refer to Chapter 3, Memory Management and Smart Pointers.