Objects and garbage collection

MObject, how the incremental garbage collector decides what lives, why every object MPROPERTY must be a TObjectPtr, and the other smart pointers.

Last updated Oct 26, 2026Edit this pageVersion 1.0.0

MObject is the garbage-collected base class, the equivalent of Unreal's UObject. Actors, components, worlds, subsystems and the engine itself are MObjects. The engine keeps every live object in one registry and frees the ones nothing reachable refers to. MObject

This page covers the rules C++ code has to follow. For actors, components and spawning, see Gameplay.

Creating objects

Create an object through the factory, not with a bare new, so it gets an outer and a name:

C++
#include "Core/NewObject.h"

MMyThing* thing = Mowo::FObjectFactory::NewObject<MMyThing>(outer, "MyThing");

FObjectFactory::NewObject In gameplay code you rarely call it directly: MWorld::SpawnActor<T>() creates actors, and AActor::CreateDefaultSubobject<T>() creates components inside an actor's constructor.

Warning

The outer does not keep an object alive. An inner keeps its outer alive, not the reverse. Store a new object in an MPROPERTY of something reachable, or root it, or the next collection deletes it.

What the collector keeps

The collector is mark-and-sweep. It starts from the roots and follows two kinds of edge:

  • The outer chain. Each reachable object keeps its outer alive.
  • Reflected references. Every MPROPERTY that refers to an MObject. The header tool generates the trace function for each class, so you never write one.

Roots are the objects added with FMObjectArray::AddRoot (counted: each AddRoot needs its own RemoveRoot), TStrongObjectPtr holders, and the objects FGCObject referencers report. The engine roots itself and its subsystems.

  1. Roots
  2. Outer chain
  3. MPROPERTY references
  4. Mark reachable
  5. Sweep the rest
A pointer member without MPROPERTY is invisible to the collector.

A property can hold an object reference as T* or TObjectPtr<T>, or inside std::vector, std::array, std::set, std::unordered_set, std::map or std::unordered_map, nested to any depth. A set element or map key must be the reference itself. Any other template that holds an object reference (std::optional, std::pair, std::list) is a compile error rather than an untraced field. Engine/Source/Runtime/Core/Public/Core/FReferenceCollector.h

The TObjectPtr rule

The collector is incremental: it marks in slices of a frame and sweeps a bounded number of objects per frame, so your code keeps running while a collection is half done. If you store a reference into an object the collector has already scanned, it could miss the new target and free a live object.

TObjectPtr<T> prevents that: every store through it runs a write barrier that tells the collector about the new target. When no collection is marking, the barrier costs one atomic load.

Danger

Every object MPROPERTY must be a TObjectPtr<T>, including elements of containers. A raw T* property written while the collector marks can hide its target, and nothing in the header tool or the build catches it.

C++
MCLASS()
class ADoor : public AActor {
	MGENERATED_BODY()

	MPROPERTY()
	TObjectPtr<ADoor> m_LinkedDoor;

	MPROPERTY()
	std::vector<TObjectPtr<AActor>> m_Watchers;
};

Inserting a TObjectPtr into a container copies it, which runs the barrier, so containers of TObjectPtr are safe. TObjectPtr has a std::hash, so it works as a set element or map key.

When collection runs

Console variableDefaultEffect
mowo.GC.IntervalSeconds5Seconds between collections; 0 disables periodic collection
mowo.GC.IncrementalonOff runs the whole collection in one frame
mowo.GC.StepBudgetMs1.0Marking budget per frame
mowo.GC.SweepBudget128Objects deleted per frame

FMObjectArray::CollectGarbage() runs a full synchronous collection when you need one. FCoreDelegates::OnPreGarbageCollect() and OnPostGarbageCollect() fire around each collection.

Destroying objects

To remove an actor, call MWorld::Destroy(actor). For other objects, MarkPendingKill() flags the object as destroyed; weak pointers to it read null at once, and the next collection frees it. MWorld::Destroy

When the collector frees a destroyed object, it clears every traced reference to it: a T* or TObjectPtr property, a vector element or a map value becomes null, and a set element or map key is erased. A destroyed object is freed even if it is rooted. Untraced pointers (locals, members without MPROPERTY) are not cleared; use TWeakObjectPtr for those.

Smart pointers

TypeUse it for
TObjectPtr<T>An object reference in an MPROPERTY; traced, with the write barrier
TWeakObjectPtr<T>A non-owning reference that reads null once the object dies, even if its slot is reused
TStrongObjectPtr<T>An owning root from code that is not an MObject; each copy holds its own root share
TSoftObjectPtr<T>An asset reference by path; LoadSynchronous() resolves it

TWeakObjectPtr MWorld::SpawnActor<T>() returns a TWeakObjectPtr<T>, so check IsValid() before using a spawned actor in a later frame.

The non-garbage-collected pointers are separate: Ref<T> (intrusive reference counting over RefCounted), WeakRef<T> and Scope<T> live in Core for assets, GPU resources and other plain C++ objects.

C++ owners of objects

A class that is not an MObject but holds MObjects (a manager, a tool, an editor preview) derives from FGCObject. It registers itself on construction and reports its references at the start of every mark: FGCObject

PreviewScene.h
#include "Core/FGCObject.h"
#include "Core/FReferenceCollector.h"
#include "Core/TObjectPtr.h"

#include <string>
#include <vector>

class FPreviewScene : public Mowo::FGCObject {
public:
	void AddReferencedObjects(Mowo::FReferenceCollector& collector) override {
		collector.AddReferencedObject(m_PreviewObject);
		collector.AddReferencedObjects(m_Extras);
	}

	std::string GetReferencerName() const override {
		return "FPreviewScene";
	}

private:
	Mowo::TObjectPtr<Mowo::MObject> m_PreviewObject;
	std::vector<Mowo::TObjectPtr<Mowo::MObject>> m_Extras;
};

Report the field itself, not a copy, so a reference to a destroyed object is cleared in place. AddReferencedObjects runs under the collector's lock in the middle of a mark: read and report, nothing else.

Classes and default objects

Every reflected class has an MClass descriptor: its name, super class, size, property table, function table and trace function. MClassRegistry finds one by C++ type or by name, and MClass::GetDefaultObject() returns the class default object, the instance that holds the class's default property values. MClassRegistry::FindByName

C++
Mowo::MClass* cls = Mowo::MClassRegistry::Get().FindByName("ADoor");
Mowo::MObject* defaults = cls->GetDefaultObject();

Spawning copies the default object's reflected values onto the new actor, and a saved level stores only the properties that differ from it, so raising a default reaches every instance that never overrode the field.

FName is the interned string used for object, class and property names: comparing two names compares indices.

Engine sources

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

  • Engine/Source/Runtime/Core/Public/Core/MObject.h
  • Engine/Source/Runtime/Core/Public/Core/NewObject.h
  • Engine/Source/Runtime/Core/Public/Core/TObjectPtr.h
  • Engine/Source/Runtime/Core/Public/Core/FMObjectArray.h
  • Engine/Source/Runtime/Core/Public/Core/FGCObject.h
  • Engine/Source/Runtime/Core/Public/Core/FReferenceCollector.h
  • Engine/Source/Runtime/Core/Public/Core/FCoreDelegates.h
  • Engine/Source/Runtime/Core/Public/Core/MClassRegistry.h
  • Engine/Source/Runtime/Game/Public/Game/MWorld.h

Page feedback

Was this page helpful?