Works in Unreal Engine 5. Tested on UE 5.8. Updated October 2026.
Quick answer: to run work on its own thread, make a class that inherits FRunnable, put the work in Run(), and start it with FRunnableThread::Create.
- Write a class with a
Run()function that does the work and aStop()function that tells it to finish. - Start it:
FRunnableThread::Create(Worker, TEXT("MyWorker")). - When you’re done (for example in EndPlay), call
Kill(true)on the thread, then delete the thread and then the worker.
Don’t touch actors, components or other UObjects from the thread. Do the heavy maths there and use the results on the game thread.
When to use FRunnable
Use it for long-running background work that would otherwise freeze the game: generating terrain, parsing big files, path or AI calculations. For small one-off jobs, the simpler options at the end of this page are easier.
Step 1: Write the worker
// PrimeCounterWorker.h
#pragma once
#include "CoreMinimal.h"
#include "HAL/Runnable.h"
#include
class FPrimeCounterWorker : public FRunnable
{
public:
std::atomic bStopRequested = false;
std::atomic PrimesFound = 0;
virtual uint32 Run() override;
virtual void Stop() override;
};
// PrimeCounterWorker.cpp
#include "PrimeCounterWorker.h"
uint32 FPrimeCounterWorker::Run()
{
for (int32 Number = 2; Number < 10000000; ++Number)
{
if (bStopRequested)
{
break;
}
bool bIsPrime = true;
for (int32 Divisor = 2; Divisor * Divisor <= Number; ++Divisor)
{
if (Number % Divisor == 0)
{
bIsPrime = false;
break;
}
}
if (bIsPrime)
{
PrimesFound++;
}
}
return 0;
}
void FPrimeCounterWorker::Stop()
{
bStopRequested = true;
}
Run() checks bStopRequested in its loop, so the thread can finish quickly when asked. std::atomic makes the two variables safe to read and write from different threads.
Step 2: Start and stop it from an actor
// In your actor's header (keep this order)
TUniquePtr Worker;
TUniquePtr WorkerThread;
// BeginPlay
Worker = MakeUnique();
WorkerThread.Reset(FRunnableThread::Create(Worker.Get(), TEXT("PrimeCounterWorker")));
// EndPlay
if (WorkerThread)
{
WorkerThread->Kill(true);
WorkerThread.Reset();
}
Worker.Reset();
Kill(true) calls your Stop() and waits until Run() has finished. Always delete the thread before the worker. Include HAL/RunnableThread.h in the actor’s .cpp.
To show progress, read Worker->PrimesFound in the actor’s Tick. That’s safe because it’s atomic.
Simpler options
| Option | Use it for |
|---|---|
FRunnable | Long-running background work you start and stop yourself |
AsyncTask | A short job on a background thread, fire and forget |
ParallelFor | Splitting a loop across all CPU cores |
UBlueprintAsyncActionBase | Async nodes for Blueprints (tutorial) |
FAQ
Can I spawn actors or change components from the thread?
No. UObjects are only safe on the game thread. Calculate on the thread and apply the results in Tick or on the game thread.
Why does my game freeze when I stop the thread?
Kill(true) waits for Run() to finish. If Run() never checks its stop flag, it waits forever. Check the flag inside your loops.
Does Kill force the thread to end immediately?
No. It asks the worker to stop by calling Stop(), then waits.