Skip to content

Latest commit

 

History

History
254 lines (166 loc) · 8.74 KB

the-ufunction-macro.md

File metadata and controls

254 lines (166 loc) · 8.74 KB
Raw
description
A quick reference around Unreal's UFUNCTION macro in C++ and available keywords.

The UFUNCTION Macro

Keywords

These keywords are also valid for the UDELEGATE macro.

BlueprintAuthorityOnly

This function will only execute from Blueprint code if running on a machine with network authority (a server, dedicated server, or single-player game).

  • Useful for visually marking methods in Blueprint for designers.
  • Will still execute on non-network authority clients when called from C++.
UFUNCTION(BlueprintCallable, BlueprintAuthorityOnly)
void SpawnProjectile();

BlueprintCallable

This function can be executed in a Blueprint and will appear in Blueprint tooling.

  • Using the const C++ keyword on the related method will remove the execution pin, making this a pure Blueprint function node.
UFUNCTION(BlueprintCallable)
void SetValue(float InValue);

BlueprintCosmetic

This function is cosmetic and will not run on dedicated servers.

  • Will still execute on network authority servers when called from C++.
UFUNCTION(BlueprintImplementableEvent, BlueprintCosmetic)
void PlayHitEffects();

BlueprintGetter

This function will be used as the accessor for a Blueprint-exposed property. This specifier implies BlueprintPure and BlueprintCallable.

More information needed about this keyword.

BlueprintInternalUseOnly

Indicates that the function should not be exposed to the end user.

More information needed about this keyword.

BlueprintImplementableEvent

This function is designed to be overridden (implemented) in Blueprint.

  • Do not provide a body for this function; the auto-generated code will include a thunk that calls ProcessEvent to execute the overridden body.
  • You'll need to add the BlueprintCallable keyword if you want to call this function from Blueprint, otherwise it's only callable via C++.
UFUNCTION(BlueprintImplementableEvent)
void OnSomethingHappened();

BlueprintNativeEvent

This function is designed to be overridden in Blueprint, but also has a native (C++) implementation.

  • To create a native implementation of the function, you'll need to define a method named [FunctionName]_Implementation instead of just the function name. This is due to how the auto-generated code will include a thunk that calls the implementation method when necessary.
  • You'll need to add the BlueprintCallable keyword if you want to call this function from Blueprint, otherwise it's only callable via C++.
// Example.h
UFUNCTION(BlueprintNativeEvent)
void DoSomething();

// Example.cpp
void Example::DoSomething_Implementation() {
    // Your code here
}

BlueprintPure

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

  • It's effectively the same as marking a method as BlueprintCallable with the const C++ keyword.
  • These functions must have a return type.
  • It is not required, but generally recommended that the function be marked const.
UFUNCTION(BlueprintPure)
float GetValue() const;

BlueprintSetter

This function will be used as the mutator for a Blueprint-exposed property. This specifier implies BlueprintCallable.

More information needed about this keyword.

CallInEditor

This function can be called in the editor on selected instances via a button in the Details panel.

More information needed about this keyword.

Category

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

  • You can define nested categories using the | operator.
  • Quotes are only required when adding spaces or the | operator.
UFUNCTION(BlueprintCallable, Category="Weapon|Gun")
void Fire();

Client

The function is only executed on the client that owns the Object on which the function is called. See Unreal's documentation on RPCs for more information.

  • Declares an additional function named the same as the main function, but with _Implementation added to the end. The auto-generated code will call the _Implementation method when necessary.
  • Owning client is the object with ENetRole of AutonomousProxy.
  • RPC functions should not have a return value.
  • RPC functions are unreliable by default.
UFUNCTION(Client)
void ReportHit(float Damage, FVector Direction);

Custom Thunk

The UnrealHeaderTool code generator will not produce a thunk for this function; it is up to the user to provide one.

More information needed about this keyword.

Exec

This function is executable from the command line. For more information, check out this wiki article about the Exec Functions.

UFUNCTION(Exec)
void GodMode(bool bEnabled);

NetMulticast

The function is executed both locally on the server, and replicated to all clients, regardless of the Actor's NetOwner. See Unreal's documentation on RPCs for more information.

  • Declares an additional function named the same as the main function, but with _Implementation added to the end. The auto-generated code will call the _Implementation method when necessary.
  • Multicast RPCs behave differently when called by the network authority (server) or client:
    • If they are called from the server, the server will execute them locally as well as execute them on all currently connected clients.
    • If they are called from clients, they will only execute locally, and will not execute on the server.
  • Multicast functions are throttled and will not replicate more than twice in a given Actor's network update period.
  • RPC functions should not have a return value.
  • RPC functions are unreliable by default.
UFUNCTION(NetMulticast)
void BroadcastGameplayEvent(EGameplayEventType EventType);

Reliable

The function is replicated over the network, and is guaranteed to arrive regardless of bandwidth or network errors. Only valid when used in conjunction with the Client or Server keywords.

UFUNCTION(Client, Reliable)
void SendPrivateMessage(FString Text);

SealedEvent

This function cannot be overridden in sub-classes. The SealedEvent keyword can only be used for events. For non-event functions, declare them as static or final to seal them.

UFUNCTION(BlueprintNativeEvent, SealedEvent)
void DoSomething();

ServiceRequest

This function is an RPC (Remote Procedure Call) service request**.**

More information needed about this keyword.

ServiceResponse

This function is an RPC service response.

More information needed about this keyword.

Server

The function is only executed on the server. See Unreal's documentation on RPCs for more information.

  • Declares an additional function named the same as the main function, but with _Implementation added to the end, which is where code should be written. The auto-generated code will call the _Implementation method when necessary.
  • The WithValidation keyword must be used with the Server keyword.
  • RPC functions should not have a return value.
  • RPC functions are unreliable by default.
UFUNCTION(Server, WithValidation)
void ServerSendInputValue(float Value);

Unreliable

The function is replicated over the network but can fail due to bandwidth limitations or network errors.

  • Only valid when used in conjunction with Client or Server.
UFUNCTION(Client, Unreliable)
void SendObjectLocation(FVector Location);

WithValidation

Declares an additional function named the same as the main function, but with _Validate added to the end. This function takes the same parameters, and returns a bool to indicate whether or not the call to the main function should proceed.

  • Required for the Server keyword. This was done to encourage secure server RPC functions, and to make it as easy as possible for someone to add code to check each and every parameter to be valid against all the known input constraints.
// MyCharacter.h
UFUNCTION(Server, Reliable, WithValidation)
void ServerSetSprint(bool bSprinting);

// MyCharacter.cpp
void AMyCharacter::ServerSetSprint_Implementation(bool bSprinting) {
  SetSprint(bSprinting);
}

bool AMyCharacter::ServerSetSprint_Validate(bool bSprinting) {
  return true;
}

****

Additional Resources