Exposing Gameplay Elements to Blueprints

As a programmer, working with Blueprints offers you many benefits by making your code extremely flexible. For example, a gameplay designer might want a new type of weapon implemented in the game. As the programmer, you code the weapon as you traditionally would except that you expose some important functionality, such as the fire rate and the Fire() function. After play testing, the designer decides that they need to change the fire rate of the gun to work on a curve. Rather than having to recode the fire rate of the gun and recompile the game, the designer can simply go into the Blueprint and change the fire rate directly, saving both the designer and the programmer time.

For more details about optimizing the C++/Blueprints distribution in your project, or tips to keep in mind when creating an API exposed to Blueprints, see the Guidelines for Programming for Blueprints.

Making Classes Blueprintable

In order to create Blueprints that extend from a class, that class must be defined as Blueprintable; which involves adding this keyword inside the UCLASS() macro preceding the class definition. This keyword makes the Blueprint system aware of the class so that it shows in the class list of the New Blueprint dialog and can be selected as the parent for the Blueprint being created.

The simplest form of declaration for a Blueprintable class is similar to the following:

UCLASS(Blueprintable)
class AMyBlueprintableClass : AActor
{
    GENERATED_BODY()
}

Readable and Writable Properties

In order to expose a variable defined in a C++ class to a Blueprint extending from that class, that variable must be defined using one of the keywords listed below inside the UPROPERTY() macro preceding the variable definition. These keywords makes the Blueprint system aware of the variable so that it shows in the My Blueprint panel and its value can be set or accessed.

//Character's Health
UPROPERTY(EditAnywhere, BlueprintReadWrite, Category="Character")
float health;

Executable and Overridable Functions

In order to call a native function from a Blueprint, that function must be defined using one of the keywords listed below inside the UFUNCTION() macro preceding the function definition. These keywords make the Blueprint system aware of the function so that it shows in the context menu or Palette and can be added to a graph and executed - or, in the case of events, so that they can be overridden and executed.

The simplest form of declaration for a BlueprintCallable Function is similar to the following:

//Fire a Weapon
UFUNCTION(BlueprintCallable, Category="Weapon")
void Fire();

When creating your function's signature, note that making a parameter pass by reference will make it an output pin on the Blueprint node. To make a parameter pass by reference and still display as an input, use the UPARAM() macro.

UFUNCTION(BlueprintCallable, Category = "Example Nodes")
static void HandleTargets(UPARAM(ref) TArray<FVector>& InputLocations, TArray<FVector>& OutputLocations);

You can also use UPARAM() to change the display name of a pin. For example, the MakeRotator function in KismetMathLibrary uses UPARAM() and the DisplayName keyword to change how the Roll, Pitch, and Yaw parameters appear in Blueprints.

/** Makes a rotator {Roll, Pitch, Yaw} from rotation values supplied in degrees */
UFUNCTION(BlueprintPure, Category="Math|Rotator", meta=(Keywords="construct build rotation rotate rotator makerotator", NativeMakeFunc))
static FRotator MakeRotator(
UPARAM(DisplayName="X (Roll)") float Roll,  
UPARAM(DisplayName="Y (Pitch)") float Pitch,
UPARAM(DisplayName="Z (Yaw)") float Yaw);