Calling C++ from Visual Scripting and back
Expose C++ functions as nodes with MFUNCTION, learn how the VM resolves and marshals a call, and spawn and drive visual classes from C++.
Visual Scripting and C++ meet through reflection. Mark a C++ function with MFUNCTION and it becomes a node; nothing else is needed. In the other direction, C++ can spawn a visual class by name, call its functions, fire its input pins and read its variables.
How a C++ function becomes a node
- MCLASS + MFUNCTION in a header
- MowoHeaderTool generates the thunks
- MClass with FMFunctionInfo
- Node catalogue lists it
- VM calls the thunk
- You annotate a class with
MCLASS()and its methods withMFUNCTION(). - During the build, MowoHeaderTool (MHT) reads the header and generates a descriptor with a thunk per function. The Reflection guide covers the macros, specifiers and header rules.
- The descriptor lists each function's name, parameter names and types, return type, flags and an invoke pointer FMFunctionInfo.
- The node catalogue walks every registered class and flattens its functions VisualScriptNodeCatalog.
- At run time the VM resolves the node's function name, converts each argument to the parameter type, and calls the thunk.
Expose a function
- Turn on the header tool in the module
Your game module's
.Build.cssetsbUseHeaderTool = trueand lists its reflected header folder inHeaderToolDirectories. The project templates already do Templates/TP_FirstPerson/Source/TP_FirstPerson/TP_FirstPerson.Build.cs. - Mark it up
Add
MCLASS()before the class,MGENERATED_BODY()inside it, andMFUNCTION()before each method a graph should see. End the header's includes with its generated header. An optionalTooltipspecifier becomes the node's description. - Build and use it
Build the module and open the Visual Scripting editor. A function on your actor class can be called on a target of that class with Call On Target. A class whose name ends in
Staticsgets its own palette category:MScoreStaticsshows up as Score Library.
#pragma once
#include "Game/AActor.h"
#include <cstdint>
#include <string>
#include "AScoreBoard.generated.h"
namespace Mowo {
MCLASS()
class AScoreBoard : public AActor {
MGENERATED_BODY()
public:
MFUNCTION(Tooltip="Adds points to the running score.")
void AddScore(int32_t points) { m_Score += points; }
MFUNCTION(Tooltip="The current score. Const, so it is a pure node.")
int32_t GetScore() const { return m_Score; }
MFUNCTION()
bool HasReached(int32_t target, int32_t& outMissing) const;
MFUNCTION(Server, Reliable)
void RequestReset() { m_Score = 0; }
private:
int32_t m_Score = 0;
};
} // namespace MowoWhat a graph sees for this class:
| Function | Node shape |
|---|---|
AddScore | Exec node with an Int input labeled points |
GetScore | Pure node, because it is const |
HasReached | Pure node with a Bool return on pin 0 and the out-parameter outMissing on pin 1 |
RequestReset | Exec node that routes to the server as a reliable RPC |
How the VM resolves a call
A Call Function node stores a function name. The VM resolves it like this:
- Qualified name. If the name has the form
Class::Function, the VM finds that class and calls the function on its default object, or with no instance if the function is static. This is how the Library nodes such asMGameplayStatics::SpawnActorByClasswork from any graph. - The running class. Otherwise it walks the running instance's native class chain and takes the first match.
AActorexposes functions such asGetActorLocation,SetActorLocation,GetActorNameandGetComponentByClassthis way AActor. A Character class reachesACharacter's functions the same way. - Call On Target. A Call On Target node resolves on the target object's class instead. If the target has no reflected function of that name but is a visual class, the VM runs the target's visual function in the target's own context, with the target's variables. A reflected method always wins over a visual function of the same name.
A non-static function with no instance to call on logs "without a target instance" and does nothing. Answers are cached per thread and dropped whenever a class registers, unregisters or a module unloads.
What marshals
| C++ parameter or return | Pin |
|---|---|
bool | Bool |
int32_t, uint32_t, int64_t, uint64_t, narrow integers, enums | Int family |
float, double | Float family |
Vec2, Vec3, Vec4, Quat | Vector pins |
std::string, FName, gameplay tags | String |
FRotator | Vec3 of pitch, yaw and roll in degrees |
TSoftObjectPtr<T> | String asset path |
MClass* | String class name |
MObject* and subclasses, such as AActor* | Object |
A registered MSTRUCT, FTransform | Struct (Custom) |
| An unregistered struct, any container | Refused: the call is skipped with an error |
A non-const reference parameter, such as Vec3& outLocation, is an out-parameter. The node shows it as an output pin: pin 0 is the return value and pin k is the k-th out-parameter, in declaration order. A type that marshals through another pin (an enum, FName, FRotator and so on) cannot be an out-parameter; the header tool fails the build on one.
The VM checks the argument count strictly: a node that supplies the wrong number of inputs is refused. Spawn functions are the exception, because Expose on Spawn pins follow the declared parameters.
RPC specifiers
MFUNCTION(Server), MFUNCTION(Client) and MFUNCTION(Multicast), optionally with Reliable, declare a network RPC. A call to one routes over the session instead of running locally. An RPC must be a non-static, non-const method that returns void; the VM refuses anything else at the call, and the editor flags it as a compile error. The receiving side re-checks the direction against where the packet came from, so a peer cannot run a non-RPC or wrong-direction function by naming it.
Call a visual class from C++
Every backing class implements IVisualScriptHost, and its FVisualScriptRuntime is the visual side of the object. Through AVisualScriptActor (or FVisualScriptRuntime::Of for any backing class), C++ can AVisualScriptActor:
- spawn a class by name, with
MWorld::SpawnActorByClassorMGameplayStatics::SpawnActorByClass; - run one of the class's functions with
CallVisualScriptFunction; - run any event graph as an input pin with
ReceivePin, passing a payload that lands inPinPayload; - read and write the instance's variables with
FindVarandSetVar.
#include "Core/MClassRegistry.h"
#include "Game/AVisualScriptActor.h"
#include "Game/MWorld.h"
#include "VisualScripting/VisualScriptValue.h"
#include <vector>
static bool OpenDoorFromCpp(Mowo::MWorld* world)
{
Mowo::MClass* doorClass = Mowo::MClassRegistry::Get().FindByName(Mowo::FName("BP_Door"));
if (!world || !doorClass) {
return false;
}
auto* door = dynamic_cast<Mowo::AVisualScriptActor*>(world->SpawnActorByClass(doorClass));
if (!door) {
return false;
}
std::vector<Mowo::VisualScriptValue> args = { Mowo::VisualScriptValue::MakeFloat(2.0f) };
door->CallVisualScriptFunction("OpenDoor", args, nullptr);
door->ReceivePin("OnInteract", Mowo::VisualScriptValue::FromObject(door));
const Mowo::VisualScriptValue* isOpen = door->FindVar("IsOpen");
return isOpen && isOpen->AsBoolean();
}BP_Door, OpenDoor, OnInteract and IsOpen come from the sample class shown on The .vscript file format.
Timers and level wiring
MTimerStatics::SetTimerByPin schedules an instance's input pin on the world's timer manager and returns an int handle. Unlike Delay, the graph keeps running, the timer can repeat, and it can be paused or cleared MTimerStatics.
MWorld also keeps a table of pin wires: firing an output pin on one actor runs a named input pin on another MWorld::AddPinWire. A graph fires one with the FirePin node. C++ adds wires with AddPinWire and fires them with MWorld::FirePin.
Choose where logic lives
| Put it in a visual class when | Put it in C++ when |
|---|---|
| It is per-actor behavior: a door, a pickup, a trap. | It is a reusable system other code calls. |
| Designers need to tune and rewire it. | It runs on a hot path. |
| It wires existing functions together. | It needs containers across the call boundary. |
Expose the heavy lifting from C++ as MFUNCTIONs, then compose it in a graph.
Next
- Node libraries: the shipped
Staticsclasses. - Debugging: watch these calls fire.
- Programming and the Game API.
Engine sources
This page describes behavior implemented in these files of the engine repository, checked against commit c1d08db53.
- Engine/Source/Runtime/Reflection/Public/Reflection/ReflectMacros.h
- Engine/Source/Runtime/Core/Public/Core/MObject.h
- Engine/Source/Runtime/Core/Public/Core/MClassRegistry.h
- Engine/Source/Runtime/VisualScripting/Public/VisualScripting/VisualScriptNodeCatalog.h
- Engine/Source/Runtime/VisualScripting/Public/VisualScripting/VisualScriptValue.h
- Engine/Source/Runtime/Game/Public/Game/AActor.h
- Engine/Source/Runtime/Game/Public/Game/AVisualScriptActor.h
- Engine/Source/Runtime/Game/Public/Game/VisualScriptRuntime.h
- Engine/Source/Runtime/Game/Public/Game/MWorld.h
- Engine/Source/Runtime/Game/Public/Game/MGameplayStatics.h
- Engine/Source/Runtime/Game/Public/Game/MTimerStatics.h
- Templates/TP_FirstPerson/Source/TP_FirstPerson/TP_FirstPerson.Build.cs