UE4 UFUNCTION Keywords Explained

In this post I will be covering the common keywords used with the UFUNCTION macro in Unreal Engine 4. Each of the keywords covered include a practical code sample and a look at how it compiles into Blueprint nodes.  I left out the networking specific keywords as they deserve a separate post on networking in Unreal Engine 4 and instead I focus on the different keywords used for exposing your C++ to Blueprint.

Exposing C++ to Blueprint

The following keywords help expose your code to Blueprints for designers to build, modify and extend the game. If you’re not familiar with UFUNCTION, then consider reading the official docs first.

BlueprintCallable

The function can be executed in a Blueprint or Level Blueprint graph.

Exposes the function as a node to Blueprint. Must be combined with the Category keyword.

	UFUNCTION(BlueprintCallable, Category = "Character")
	void RespawnCharacter();

const (C++ keyword)

When using the “const” keyword on your function (see code sample), the Blueprint node will not have an execution line. ‘const’ promises the function will not change any data a thus the node will look like the GetMaxHealth node below. It’s great for getter functions for example where you only want to get a value from C++.

	UFUNCTION(BlueprintCallable, Category = "Character")
	float GetMaxHealth() const;

BlueprintImplementableEvent

The function can be overridden in a Blueprint or Level Blueprint graph.

Used when Blueprint implements the logic of this function instead of C++. Can be combined with BlueprintCallable so it can be called from Blueprint, otherwise only C++ can call this function.

	UFUNCTION(BlueprintCallable, BlueprintImplementableEvent, Category = "Character")
	void SetupInventory();

An important note here is the difference between specifying ‘void’ or a return type (eg. bool) on the function. The above code sample is of type void, and therefore results in a Event node, where the sample below (with a bool as return type) will be overridable as a Function instead. This difference is not exclusive to this keyword.

	UFUNCTION(BlueprintCallable, BlueprintImplementableEvent, Category = "Character")
	bool SetupInventory();

BlueprintNativeEvent

This function is designed to be overridden by a Blueprint, but also has a native implementation. Provide a body named [FunctionName]_Implementation instead of [FunctionName]; the autogenerated code will include a thunk that calls the implementation method when necessary.

Useful when the code provides a basic implementation and Blueprint extends the logic. The function body looks a little different with a _Implementation suffix (see code below) you still call [FunctionName] without the suffix in code as usual. As with the other keywords, use BlueprintCallable to expose to Blueprint.

	UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category = "Character")
	void OnEnterInventory();

Code below is the body in the .cpp file

void AMyGameCharacter::OnEnterInventory_Implementation()
{
    // base implementation to be extended by Blueprint...
}

The same logic applies as explained in BlueprintImplementableEvent. Specifying a return value compiles to a Function, and using ‘void’ compiles to an Event node as seen above.

BlueprintPure

The function does not affect the owning object in any way and can be executed in a Blueprint or Level Blueprint graph.

Similar to using the ‘const’ keyword as explained at BlueprintCallable above. Nodes with this keyword have no execution line pin and cannot alter any data of the object. Great for math nodes or “get” functions to retrieve variables from the object. This keyword also implies BlueprintCallable. These functions must have a return value.

	UFUNCTION(BlueprintPure, Category = "Character")
	float GetMaxHealth();

Metadata Specifiers

Meta keywords have a slightly different syntax via UFUNCTION(… , meta = (Keyword1, Keyword2));

BlueprintProtected

This function can only be called on ‘this’ in a Blueprint. It cannot be called on another instance.

This meta keyword limits the use of the function it’s applied to, meaning that only the Blueprint instance itself can call the function, any other Blueprint classes do not have access to this function. This access limitation does not affect C++.

	UFUNCTION(BlueprintCallable, meta = (BlueprintProtected), Category = "Character")
	bool SetupInventory();

DeprecatedFunction

This function is deprecated, any blueprint references to it cause a compilation warning. You can customize the deprecation message using the DeprecationMessage metadata specifier.

Deprecation is an important part of a healthy pipeline. Customize the message using DeprecationMessage.

	UFUNCTION(BlueprintCallable, meta = (DeprecatedFunction, DeprecationMessage = "Hello Designers! Please use RespawnPlayer instead!"), Category = "Character")
	void RespawnCharacter();

DeprecationMessage

Supplies the custom message to use for deprecation. Must be combined with the DeprecatedFunction metadata specifier.

Customize the message with helpful information for the designers. Such as which nodes to use instead or the reason for deprecating the node in the first place.

Misc.

Category

Specifies the category of the function when displayed in Blueprint editing tools.

The category keyword is cosmetic only and is used to group functions (and properties) in the editor. See BlueprintCallable for usage example.

As you can see our functions show up under “Character” which we specified as the category in all above code samples.

Exec

The function can be executed from the in-game console. Exec commands only function when declared within certain class.

Using Exec on functions is great for (debug) commands such as giving health to a player or enabling god mode. You can provide one or multiple parameters which will be displayed via the in-game console (~ Tilde-key) as seen below.

	UFUNCTION(Exec)
	void GiveHealth(float BonusHealth);

If you found this useful, please consider sharing this page with your fellow Unreal Engine 4 Developers!

References

• Function definitions (Official Docs)
• Extending Blueprints