Note: This blog post is based on Unreal Engine version 4.25.3<\/h4>\n\n\n\nWhat are Interfaces?<\/h2>\n\n\n\n
Interfaces are great in any language. They let you define a set of functionality that anything can implement, and not be tied to a rigid class hierarchy. My favourite implementation of this is actually in Go<\/a>, where you don\u2019t even have to declare that you\u2019re implementing an interface – if you happen to have the right combination of functions on your type, you just are<\/em>. Lovely.<\/p>\n\n\n\n C++ technically doesn\u2019t have interfaces, but it does have multiple inheritance, which can be made to emulate it. This is what UE4 does, with a bunch of boilerplate tacked on to make it a bit more explicit, and to support the reflection system.<\/p>\n\n\n\n There are<\/em> a bunch of blog posts out there teaching you how to use UE4 C++ interfaces, and I used them to get up to speed (I\u2019m not an expert, I only started using them recently).<\/p>\n\n\n\n But I found pretty quickly that they skip over a few things that I needed almost immediately. For example they generally assume you\u2019re working entirely within C++, when I think a lot of us are working in mixed C++ \/ Blueprint environments. They also didn\u2019t talk about what you need to do when you want interface variables. So I felt I could add something from what I\u2019ve learned in the last few weeks.<\/p>\n\n\n\n I could just refer to the other tutorials for the basics, but I decided to make this post self-contained and cover C++ interfaces from the ground up as well.<\/p>\n\n\n\n So this post will cover:<\/p>\n\n\n\n I like to declare my interfaces in C++ and not as Blueprint Interfaces<\/a>, because it gives me more options; C++ interfaces can be used in both C++ and Blueprints, while Blueprint Interfaces can only be used in Blueprints.<\/p>\n\n\n\n Let\u2019s say we\u2019re creating an interface called As you can see, you have a So next, you\u2019ll want to add some methods to the interface, which you always do inside the There\u2019s a couple of things to note there:<\/p>\n\n\n\n Usually when you declare However<\/strong>: I\u2019ve discovered that this doesn\u2019t mean you must<\/em> have a C++ implementation. In my testing you can totally implement this interface directly in Blueprints with no C++ intermediate class if you want, the As such I don\u2019t see why you\u2019d use any other specifier; the documentation<\/a> says the other options are: no specifier (can\u2019t be implemented in BP), or Here\u2019s a minimal C++ implementation of the interface on an Actor called SomeThingsActor:<\/p>\n\n\n\n Easy, right? The only interesting thing is that because the interface definition was set to As I mentioned earlier, You can also subclass a Blueprint class from a C++ implementation like Here\u2019s how you\u2019d implement it directly. On your Blueprint class:<\/p>\n\n\n\n A lot of information online will tell you that you can just use It\u2019s true that this works if<\/strong> If, however, you implement this interface directly<\/em> on a Blueprint, To detect interfaces reliably, whether they\u2019ve been implemented as C++ or Blueprints, you need avoid using First, detecting if the interface is implemented:<\/p>\n\n\n\n Once you\u2019ve detected if the interface is present, you must call it via the interface wrappers, not directly on the instance:<\/p>\n\n\n\n This will work universally, whether the interface has been implemented in C++ or Blueprints, so it seems best to always<\/em> use this method. It\u2019s probably less efficient, but personally I tend to use interfaces at a fairly high level so am not particularly concerned.<\/p>\n\n\n\n This is a little simpler because there\u2019s really only one way to do it; you can call any<\/strong> interface on any<\/strong> object:<\/p>\n\n\n\n Notice the envelope icon which shows that this is a \u201cMessage\u201d to the receiving object, which is silently ignored if that interface is not implemented. It works whether the interface was implemented in C++ or Blueprints. When you pick the function from the list, it displays like this:<\/p>\n\n\n\n If you specifically need to know whether an object implements an interface, you can test with the \u201cDoes Implement Interface\u201d node:<\/p>\n\n\n\n Sometimes you want to hold on to a reference to an interface, as the general type.<\/p>\n\n\n\n In Blueprints this is pretty easy. You need to make sure your \u201cU\u201d interface class has the Once you\u2019ve done that, you can just create variables with this type inside your Blueprints like any other variable:<\/p>\n\n\n\n I usually prefer to define my variables in C++, because then I can use them in C++ code or Blueprints.<\/p>\n\n\n\n In C++ things are slightly more tricky, because you can\u2019t store a Spoiler: You might wonder in a minute why I talk about TScriptInterface only to tell you in the end not to use it. Well, it\u2019s because it\u2019s actually suggested by the compiler if you try to use an interface pointer as a UPROPERTY. That\u2019s how I found it, only to discover its problems later.<\/p><\/blockquote>\n\n\n\n Unreal provides a The simplest way to assign an object which implements the interface to this property is to use the assignment operator:<\/p>\n\n\n\n When you want to use this stored reference, you call it using the overloaded Simple in theory, but there\u2019s one major<\/strong> problem with this, and that\u2019s that The thing is, you can still make This is because the UObject pointer in the TScriptInterface is fine, but the interface pointer is null.<\/p>\n\n\n\n Also, calls in Blueprints will work fine<\/em> with this I\u2019ve now chosen to skip This way you can just assign the \u201craw\u201d object pointer to this variable and use the standard \u201csafe\u201d way to call it, avoiding So, that\u2019s what I\u2019ve learned about interfaces in Unreal in a mixed C++ \/ Blueprint environment in the last couple of weeks. I\u2019d written it all down in my personal notes but came to the conclusion my usage must be pretty common, and those little gotchas seemed worth putting down somewhere public for others to potentially benefit from.<\/p>\n\n\n\n I\u2019ve done my best but I\u2019m not an expert, if I\u2019ve misunderstood anything in this blog post, please do let me know on Twitter<\/a>. \ud83d\ude09<\/p>\n","protected":false},"excerpt":{"rendered":" Introduction I wrote this blog post to fill a few gaps in the documentation I\u2019d found for C++ interfaces in Unreal. Specifically I have a few tips for what I think are common usage scenarios that no blog post I found talked about. Note: This blog post is based on Unreal Engine version 4.25.3 What are Interfaces?…<\/p>\nWhy another blog post about this?<\/h2>\n\n\n\n
Declaring the C++ Interface<\/h2>\n\n\n\n
DoSomeThings<\/code> which, well, does some things. First we need a header file:<\/p>\n\n\n\n#pragma<\/strong> once\n#include<\/strong> \"CoreMinimal.h\"\n#include<\/strong> \"DoSomeThings.generated.h\"\n\nUINTERFACE(MinimalAPI)\nclass<\/strong> UDoSomeThings : public<\/strong> UInterface\n{\n GENERATED_BODY()\n \/\/ This will always be empty!\n};\n\n\nclass<\/strong> YOURPROJECT_API IDoSomeThings\n{\n GENERATED_BODY()\npublic<\/strong>:\n \/\/ ... Here is where we will define UFUNCTION interface methods\n};\n\n<\/code><\/pre>\n\n\n\nUDoSomeThings<\/code> and IDoSomeThings<\/code> – there doesn\u2019t seem to be any link between them, but the naming convention actually does this automatically thanks to UE header magic.<\/p>\n\n\n\nAdding methods<\/h2>\n\n\n\n
IDoSomeThings<\/code> class. Lets start with something simple:<\/p>\n\n\n\nclass<\/strong> YOURPROJECT_API IDoSomeThings\n{\n GENERATED_BODY()\npublic<\/strong>:\n \/\/\/ Get the number of things\n UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category=\"Things\")\n int<\/strong> GetNumberOfThings<\/strong>();\n};\n<\/code><\/pre>\n\n\n\nBlueprintCallable<\/code>, because I want to be able to use it in Blueprints<\/li>BlueprintNativeEvent<\/code> because I want to give C++ classes the option of implementing it<\/li><\/ol>\n\n\n\nWhy BlueprintNativeEvent?<\/h2>\n\n\n\n
BlueprintNativeEvent<\/code> it means you immediately want to add a C++ implementation, named in this case GetNumberOfThings_Implementation<\/code>. But, since this is just the interface definition, you don\u2019t have to do that yet. You wait until you actually implement this interface on a C++ class to do that.<\/p>\n\n\n\nBlueprintNativeEvent<\/code> just allows you to have C++ implementors as well.<\/p>\n\n\n\nBlueprintImplementableEvent<\/code> (must be implemented in BP, can\u2019t be implemented in C++). Since BNE seems to let you do anything<\/em> I can\u2019t see why the others are useful, in interfaces specifically. \ud83e\udd37\u200d\u2642\ufe0f<\/p>\n\n\n\nImplementing the Interface in C++<\/h2>\n\n\n\n
#pragma<\/strong> once\n\n#include<\/strong> \"CoreMinimal.h\"\n#include<\/strong> \"DoSomeThings.h\"\n#include<\/strong> \"SomeThingsActor.generated.h\"\n\nUCLASS(Blueprintable)\nclass<\/strong> YOURPROJECT_API ASomeThingsActor : public<\/strong> AActor, public<\/strong> IDoSomeThings\n{\n GENERATED_BODY()\npublic<\/strong>:\n virtual<\/strong> int<\/strong> GetNumberOfThings_Implementation<\/strong>() override;\n};\n<\/code><\/pre>\n\n\n\n#include<\/strong> \"SomeThingsActor.h\"\n\nint<\/strong> ASomeThingsActor::GetNumberOfThings_Implementation()\n{\n return<\/strong> 1;\n}\n<\/code><\/pre>\n\n\n\nBlueprintNativeEvent<\/code>, we implement GetNumberOfThings_Implementation<\/code> rather than GetNumberOfThings<\/code>.<\/p>\n\n\n\nImplementing the Interface in Blueprints<\/h2>\n\n\n\n
BlueprintNativeEvent<\/code> doesn\u2019t stop you implementing this interface directly<\/strong> in Blueprints if you want – at least in my experience. I don\u2019t know if this is by accident or by design. It\u2019s specific to interfaces, if you use BlueprintNativeEvent<\/code> on a regular UCLASS<\/code> you must have a C++ implementation, but it\u2019s in the same class in that case.<\/p>\n\n\n\nASomeThingsActor<\/code> above, and override the method. But you don\u2019t have<\/em> to, with interfaces.<\/p>\n\n\n\n![\"Implementing](\"https:\/\/merserver.com\/wp-content\/uploads\/2022\/10\/ue-cpp-interface-impl.png\")
<\/li>![\"Implementing](\"https:\/\/merserver.com\/wp-content\/uploads\/2022\/10\/ue-cpp-interface2.png\")
<\/li>![\"Implementing](\"https:\/\/merserver.com\/wp-content\/uploads\/2022\/10\/ue-cpp-interface3.png\")
<\/li><\/ul>\n\n\n\nDetecting & Calling the Interface<\/h2>\n\n\n\n
Calling in C++<\/h3>\n\n\n\n
Cast<><\/code> to both detect and access an interface in C++:<\/p>\n\n\n\nauto<\/strong> I = Cast<IDoSomeThings>(Actor);\nif<\/strong> (I)\n{\n int<\/strong> Num = I->GetNumberOfThings();\n}\n<\/code><\/pre>\n\n\n\nActor<\/code> is a C++ implementation of IDoSomeThings<\/code>, or a Blueprint subclass of a C++ implementor.<\/p>\n\n\n\nCast<IDoSomeThings><\/code> will always return nullptr<\/strong>. Always. This is because the C++ side has no idea the actor implements this. This is particularly nefarious because nothing will look wrong until you happen to use a trivial direct BP implementation and suddenly a bunch of things will start to fail silently.<\/p>\n\n\n\nCast<><\/code><\/em> and use UE4\u2019s explicit interface utilities which use the full reflection system and can therefore detect Blueprints.<\/p>\n\n\n\n\/\/\/ Either of these 2 are valid\n\n\/\/\/ Option 1 does more sanity checks, is null-safe on Actor\nbImpl = UKismetSystemLibrary::DoesImplementInterface(Actor, UDoSomeThings::StaticClass())\n\n\/\/\/ Option 2 skips some checks, you must ensure Actor is non-null\nbImpl = Actor->GetClass()->ImplementsInterface(UDoSomeThings::StaticClass())\n<\/code><\/pre>\n\n\n\nif<\/strong> (bImpl)\n{\n int<\/strong> Num = IDoSomeThings::Execute_GetNumberOfThings(Actor);\n}\n<\/code><\/pre>\n\n\n\nCalling in Blueprints<\/h3>\n\n\n\n
![\"Calling](\"https:\/\/merserver.com\/wp-content\/uploads\/2022\/10\/ue-cpp-interface4.png\")
<\/figure>\n\n\n\n![\"Calling](\"https:\/\/merserver.com\/wp-content\/uploads\/2022\/10\/ue-cpp-interface5.png\")
<\/figure>\n\n\n\n![\"Calling](\"https:\/\/merserver.com\/wp-content\/uploads\/2022\/10\/ue-cpp-interface6.png\")
<\/figure>\n\n\n\nStoring Interfaces As Variables<\/h2>\n\n\n\n
Blueprint Variables<\/h3>\n\n\n\n
BlueprintType<\/code> specifier, which allows it to be stored in Blueprint variables:<\/p>\n\n\n\nUINTERFACE(MinimalAPI, BlueprintType)\nclass<\/strong> UDoSomeThings : public<\/strong> UInterface\n<\/code><\/pre>\n\n\n\n![\"BP](\"https:\/\/merserver.com\/wp-content\/uploads\/2022\/10\/ue-cpp-interface7.png\")
<\/figure>\n\n\n\nC++ variables<\/h3>\n\n\n\n
IDoSomeThings<\/code> pointer as a UPROPERTY()<\/code>, because they don\u2019t play nice with the garbage collector. We need something that holds on to the UObject.<\/p>\n\n\n\nTScriptInterface (Prone to error!)<\/h4>\n\n\n\n
TScriptInterface<><\/code> type which is designed to wrap an object as a specific interface. It\u2019s the official suggested way to hold on to both the object reference safely and the interface it\u2019s supposed to be presenting. You can use it like this:<\/p>\n\n\n\nUPROPERTY(BlueprintReadWrite)\nTScriptInterface<IDoSomeThings> SomethingInstance;\n<\/code><\/pre>\n\n\n\nTScriptInterface<><\/code> is used as a value type, so rather than null when not initialised, the default state is an empty wrapper. To test whether it\u2019s empty or not, use the bool()<\/code> overloaded operator:<\/p>\n\n\n\nif<\/strong> (SomethingInstance)\n{\n \/\/ OK this points to something useful\n}\n<\/code><\/pre>\n\n\n\nif<\/strong> (UKismetSystemLibrary::DoesImplementInterface(Actor, UDoSomeThings::StaticClass()))\n{\n SomethingInstance = Actor;\n}\n<\/code><\/pre>\n\n\n\n-><\/code> operator, i.e.:<\/p>\n\n\n\nint<\/strong> Num = SomethingInstance->GetNumberOfThings();\n<\/code><\/pre>\n\n\n\nTScriptInterface<><\/code> derives the interface pointer using Cast<><\/code>. And as we established earlier, Cast<><\/code> will always return nullptr<\/strong> if the instance in question is only implementing the interface at the Blueprint level, and none of its superclasses implement it in C++.<\/p>\n\n\n\nTScriptInterface<><\/code> work in this scenario, by instead calling:<\/p>\n\n\n\nint<\/strong> Num = IDoSomeThings::Execute_GetNumberOfThings(SomethingInstance.GetObject());\n<\/code><\/pre>\n\n\n\nTScriptInterface<><\/code> variable, which can hide the problem. Various methods of TScriptInterface<><\/code> will fail in C++ if your class only implements at a Blueprint level, so I consider it unsafe to use.<\/p>\n\n\n\nUObject: the more reliable way<\/h4>\n\n\n\n
TScriptInterface<\/code> and instead just hold a UObject*<\/code>, because the object reference is the only bit of TScriptInterface<\/code> which is reliable in cases where the interface is only implemented in Blueprints anyway.<\/p>\n\n\n\nUPROPERTY(BlueprintReadWrite)\nUObject* SomethingInstance;\n<\/code><\/pre>\n\n\n\nCast<><\/code> as we previously discussed:<\/p>\n\n\n\n\/\/ I'm assuming here that we checked the object supported the interface before saving\n\/\/ it to the variable; if not we should check for that as well as nulls\nif<\/strong> (SomethingInstance)\n{\n int<\/strong> Num = IDoSomeThings::Execute_GetNumberOfThings(SomethingInstance);\n}\n<\/code><\/pre>\n\n\n\nThe End<\/h2>\n\n\n\n