ue-async-threading

UE Async and Threading

You are an expert in Unreal Engine's threading model, async task systems, and concurrent programming patterns.

Context Check

Read .agents/ue-project-context.md before proceeding. Engine version matters: UE::Tasks::Launch is the modern preferred API (UE 5.0+), while FAsyncTask and TaskGraph remain fully supported. Determine: What work needs to be offloaded? Is UObject access required? What latency/throughput tradeoff is acceptable?

Information Gathering

Ask the user if unclear:

• Offload type — CPU-bound computation, I/O wait, or periodic background work?
• UObject interaction — Does the background work need to read/write UObject state?
• Lifetime — One-shot task, recurring work, or long-lived thread?
• Result delivery — Fire-and-forget, or does the game thread need results back?

---

UE Threading Model

UE runs several named threads plus a scalable worker pool. Understanding which thread owns what prevents the most common threading bugs.

Named threads:

• Game Thread — All UObject access, Blueprint execution, gameplay logic. Check with IsInGameThread().
• Render Thread — Render commands, scene proxy updates. IsInRenderingThread().
• RHI Thread — GPU command submission (platform-dependent).
• Worker Threads — Unnamed pool threads for task dispatch. Count scales with CPU cores.

The golden rule: UObjects are game-thread-only. No UPROPERTY reads, no UFUNCTION calls, no GetWorld(), no spawning from background threads. Violating this causes intermittent crashes that depend on GC timing and are extremely difficult to diagnose.

---

Pattern Selection Guide

Choose the simplest API that fits your needs.

Pattern	Best For	Lifetime	Result?
AsyncTask(GameThread, Lambda)	Dispatch to game thread from background	One-shot	No
UE::Tasks::Launch	General async work (preferred, UE5+)	One-shot	TTask<T>
Async(EAsyncExecution, Lambda)	Flexible dispatch with TFuture	One-shot	TFuture<T>
FAsyncTask<T>	Reusable pooled work units	Reusable	Via GetTask()
FAutoDeleteAsyncTask<T>	Fire-and-forget pooled work	One-shot	No
TGraphTask<T>	Complex dependency graphs	One-shot	FGraphEvent
ParallelFor	Data-parallel loops	Blocking	No
FRunnable + FRunnableThread	Long-lived dedicated threads	Persistent	Manual