Reflection

The MCLASS, MSTRUCT, MPROPERTY, MFUNCTION, MENUM, MINTERFACE and MDELEGATE macros, their specifiers, and how the header tool turns them into generated code.

Last updated Nov 5, 2026Edit this pageVersion 1.0.0

Reflection is what lets a C++ field save into a level, show in the Details panel, keep its target alive in the garbage collector and replicate, and what lets a function be called by name from Visual Scripting. You opt in with macros in your headers. At build time MowoHeaderTool (MHT) reads them and generates the descriptor tables and glue code.

The macros themselves expand to nothing (Reflection/ReflectMacros.h). MHT reads the header text with its own parser and never runs a compiler, so a typo is reported as File.h(12): error: … before anything compiles. Engine/Source/Runtime/Reflection/Public/Reflection/ReflectMacros.h

Two rules for every reflected header

  1. Its last #include is its generated header, named after the file: DoorActor.h ends its includes with #include "DoorActor.generated.h". An include after it, or a missing one, is a build error.
  2. Every MCLASS and MINTERFACE body contains MGENERATED_BODY(). It may not sit inside an #if.

A header may declare any number of reflected types, enums and delegates.

Objects and actors

DoorActor.h
#pragma once

#include "Game/AActor.h"

#include "DoorActor.generated.h"

namespace Mowo {

MCLASS(meta = (Icon = "door"))
class ADoorActor : public AActor {
public:
	MGENERATED_BODY()

	MPROPERTY(EditAnywhere, Category = "Door")
	float m_OpenAngle = 90.0f;

	MPROPERTY()
	TObjectPtr<ADoorActor> m_LinkedDoor;

	MOWO_TOOLTIP("Swings the door open.")
	MFUNCTION()
	void Open();

	MFUNCTION()
	bool IsOpen() const;
};

} // namespace Mowo

From this MHT generates:

  • an MClass descriptor: name, super class, size, constructor, flags and metadata,
  • the garbage-collection trace function, from the MPROPERTY object references,
  • a property table and a function table, with a type-erased call thunk per MFUNCTION,
  • the expansion of MGENERATED_BODY(): StaticClass(), ThisClass, Super (the first base that is not an interface), and the friend declaration the trace function uses to read private fields.

On an MCLASS, only MPROPERTY fields are reflected, and they may be private. Object references must be TObjectPtr<T>; see Objects and garbage collection.

Class references

A field that names a class rather than an object is a TSubclassOf<T>:

ASpawner.h
MPROPERTY(EditAnywhere, Category="Spawning")
TSubclassOf<APickup> m_PickupClass;

It holds an MClass* (a class is not a garbage-collected object, so there is no TObjectPtr and no trace), converts to and from MClass*, and answers IsChildOf. In the Details panel it is a searchable class picker that lists only the registered classes deriving from T, Visual Scripting classes among them. The level stores the class name and resolves it again on load and after a hot reload. A class lives in its module's image, so unloading the module clears every reflected class field that points into it and remembers the name; the field is filled again when a class of that name registers. A name that no loaded module knows (the module is not loaded, the class was renamed, a Visual Scripting class is not registered yet) leaves the field at its default and logs a warning, but the name is kept beside the object: the next save writes it back unchanged, the Details picker shows it as Missing: Name, and the reference is restored as soon as the class appears. Only picking another class replaces it. A class that does not derive from T is refused. A class reference on a Visual Scripting class follows a hot reload by name only through the actor snapshot; a Visual Scripting class that is retired and replaced is not re-resolved in the fields that still point at the old one, so re-pick it if a field shows a stale class. Outside reflection (a local, a cache) keep the name and look the class up with MClassRegistry::FindByName when you use it. A plain MClass* field works the same way and accepts any class unless MetaClass=Name narrows it. Engine/Source/Runtime/Core/Public/Core/TSubclassOf.h

Class specifiers

SpecifierEffect
Abstract, Transient, NotPlaceable, DeprecatedClass flags
Config=GameMarks the class as configurable from INI; see Project files
DisplayName=, Category=, Tooltip=Describe the class in the editor
meta=(...)Open key-value metadata, read at run time with MClass::FindMeta

An unknown specifier is a build error that lists the known ones.

Property specifiers

SpecifierEffect
EditAnywhere, VisibleAnywhereEditable or read-only in the Details panel
Category=Groups the field
ConfigSettable from the class's INI section
SaveGameSaved in the world-state save
TransientSame as RuntimeOnly: neither saved nor shown
Replicated, ReplicatedUsing=Fn, RepCondition=, NetQuantize=Property replication; see Multiplayer
AssetRef, AssetType=A std::string that holds an asset path, saved as a typed asset reference
Key=, DisplayName=, Tooltip=, Range=, ClampMin=, ClampMax=, Step=, Units=, Color, LayerMask, EditCondition=, Hidden, ReadOnly, RuntimeOnly, Custom=, Nested=The same meanings as the field markers below
MetaClass=NameOn an MClass* field: the class a picked value must derive from. A TSubclassOf<Name> field already says so in its type
meta=(...)Anything else, carried into the module's JSON export

Function specifiers

MFUNCTION reflects a public method's name, return type and parameters. MFUNCTION(Server), (Client) and (Multicast) make it an RPC; Reliable or Unreliable picks the channel. Naming two directions is a build error, and so is an MFUNCTION that is not public. Category=, DisplayName=, Tooltip= and Description= describe the node Visual Scripting shows.

Write MOWO_TOOLTIP("...") before MFUNCTION (or MFUNCTION(Tooltip="...")) to describe what a call does; the Visual Scripting node shows it on hover. Every MFUNCTION is exposed to Visual Scripting automatically.

A reflected call can carry bool, the fixed-width integers, float, double, Vec2, Vec3, Vec4, Quat, std::string, any MObject-derived pointer, enums, FName, FGameplayTag, FRotator, TSoftObjectPtr and MClass*. Anything else is marked as a custom type and refused by the Visual Scripting VM.

Components and value structs

ECS components and plain value structs use MOWO_REFLECTED_NAMED("Name") (or MSTRUCT()), and fields carry markers instead of MPROPERTY. A struct whose body contains MOWO_COMPONENT(Self) registers as a component; without it, it is a value struct, described wherever a component field uses it.

HealthComponent.h
#pragma once

#include "ECS/Component.h"
#include "Reflection/Reflect.h"

#include "HealthComponent.generated.h"

struct MOWO_REFLECTED_NAMED("Health") MCATEGORY("Gameplay") MOWO_TOOLTIP("Hit points and regeneration.") HealthComponent {
	MOWO_COMPONENT(HealthComponent)

	MOWO_KEY("max_health") MOWO_RANGE(1, 1000)
	float maxHealth = 100.0f;

	MOWO_UNITS("s")
	float regenDelay = 3.0f;

	MOWO_RUNTIME_ONLY
	float current = 0.0f;
};

MHT turns this into a type descriptor with a property table and registers the component with the ECS, so level loading and saving, the editor's Add Component menu, duplication and prefabs all pick it up. Adding a component or a field needs no serializer or editor change.

Field markers

MarkerEffect
MOWO_KEY("name")The key the field saves under
MOWO_DISPLAY("Label")The Details label
MOWO_TOOLTIP("...")Hover text; on the struct itself, the description the Add Component menu shows
MOWO_RANGE(lo, hi)A slider
MOWO_STEP(s)Drag and step granularity
MOWO_UNITS("m")The unit the stored number means; rad is stored in radians and edited in degrees
MOWO_COLORA colour picker for a Vec3 or Vec4
MOWO_ASSET_REF, MOWO_ASSET_TYPE("Mesh")An asset picker for a string path, optionally filtered to one type
MOWO_LAYER_MASKA named-layer multi-select for a uint32_t
MOWO_EDIT_CONDITION("flag")Disables the row unless the named field is true ("!flag" inverts)
MOWO_READ_ONLY, MOWO_HIDDENDisabled row, or no row
MOWO_RUNTIME_ONLYNeither saved nor shown
MOWO_CUSTOM("key")Hands the field to a registered property-type handler
MOWO_NESTED(...)Shows one member of a value-type field as its own row
MCATEGORY("...")On the struct, the Add Component menu group; on a field, its category

std::vector<T> fields become arrays, std::map, std::unordered_map and TMap become maps, std::set, std::unordered_set and TSet become sets, and a field typed as another reflected struct becomes a nested struct. Map keys and set elements are int32_t, uint32_t, UUID or std::string. Shapes MHT does not support (a vector of vectors, a vector of enums) are skipped with a build warning; mark them MOWO_RUNTIME_ONLY or give them a custom handler.

A field typed FGameplayTag or FGameplayTagContainer goes to a built-in handler without any marker: it saves as the tag name (a container as a list of names), and the Details panel shows a picker over the project's declared tags instead of a text box. An explicit MOWO_CUSTOM("key") or Custom= still wins.

MOWO_CUSTOM_SERIALIZE(fn) and MOWO_CUSTOM_DESERIALIZE(fn) on the struct add hooks that run beside the reflected fields. Define them in the component's own module: the generated code that references them compiles into that module.

Enums

An enum used by a reflected field gets a descriptor automatically, so it saves by name and shows as a drop-down. MENUM() registers one that nothing reflected uses yet:

DoorState.h
#include "Reflection/ReflectMacros.h"

#include <cstdint>

enum class MENUM() EDoorState : uint8_t {
	Closed,
	Opening MMETA(DisplayName = "Opening..."),
	Open,
	Retired MMETA(Hidden),
	Count
};
  • MMETA(DisplayName="...") relabels an enumerator; the saved string is always the identifier, so relabelling never breaks a saved level.
  • MMETA(Hidden) keeps an enumerator out of the drop-down. A trailing Count, MAX or Num sentinel is hidden automatically.
  • A header that only marks enums can include Reflection/ReflectMacros.h instead of Reflect.h.

Interfaces

C++
MINTERFACE()
class IDamageable {
public:
	MGENERATED_BODY()

	virtual ~IDamageable() = default;
	virtual float TakeDamage(float amount, AActor* instigator) = 0;
};

MHT registers a class named MDamageable for the interface, and every MCLASS deriving from IDamageable lists it, so GetClass()->ImplementsInterface(FName("IDamageable")) answers without the C++ type. IDamageable::StaticInterfaceClass() returns the descriptor. MIMPLEMENTS("IFoo") declares an interface a class implements without inheriting it in C++.

Delegates

C++
MDELEGATE(Tooltip = "Health changed: new value, old value.")
using FOnHealthChanged = TMulticastDelegate<float, float>;

MDELEGATE in front of a Delegate<R(Args...)> or TMulticastDelegate<Args...> alias exports its signature for the editor and Visual Scripting. It generates no run-time code.

Conditional members

A member inside #if WITH_EDITOR (or any condition MHT cannot decide) is reflected under the same condition: its generated row is wrapped in the same #if, so one generated file is right for every configuration. Conditions MHT can decide (#if 0, include guards, macros the header defines) are applied as the preprocessor would.

MHT never expands macros, so a reflected type or member that a macro produces is not seen.

Turning it on

MHT runs inside the build tool, between reading the rules and compiling, for every module whose .Build.cs sets bUseHeaderTool = true. It scans the folders in HeaderToolDirectories (or Public/) and writes, per header:

FileContents
<Header>.generated.hWhat each MGENERATED_BODY() expands to
<Header>.refl.cppDescriptors, registrations, trace functions and call thunks, compiled into the module
<Module>.reflection.jsonThe module's markup: types, properties, functions, enums, delegates, metadata

The output folder, Reflection/ under the module's generated directory, is a public include path of the module. Generated sources include stdafx.h, so every scanned module needs one in its Private/ folder or on its forced includes (the game-module scaffold handles this). A pass with an error writes nothing, and an unchanged output keeps its timestamp.

Warning

A reflected component in a module without bUseHeaderTool = true gets no descriptor: it does not appear in the editor and does not save. New modules that declare reflected types must opt in.

Engine sources

This page describes behavior implemented in these files of the engine repository, checked against commit 38224a3a8.

  • Engine/Source/Runtime/Reflection/Public/Reflection/ReflectMacros.h
  • Engine/Source/Runtime/Reflection/Public/Reflection/Reflect.h
  • Engine/Source/Runtime/ECS/Public/ECS/Component.h
  • Engine/Source/Runtime/Core/Public/Core/MObject.h
  • Engine/Source/Runtime/Core/Public/Core/TSubclassOf.h
  • Engine/Source/Runtime/Core/Public/Core/ClassRefUtils.h
  • Engine/Source/Runtime/Game/Public/Gameplay/GameplayDelegates.h

Page feedback

Was this page helpful?