UE5Coro Documentation

Aggregate awaiters allow you to combine multiple awaitables or TCoroutine objects into a single co_await operation. They support expedited cancellation and are designed so that once the first await completes, subsequent awaits of the same result return the value synchronously on the calling thread.

Threading Behavior

• Standard Awaiters (WhenAny, WhenAll, Race): The coroutine resumes on a thread corresponding to one of the input parameters or the thread that canceled the coroutine. If all inputs resume on the game thread and no cross-thread cancellation occurs, the aggregate is guaranteed to resume on the game thread.
• Latent Awaiters (Latent::WhenAny, Latent::WhenAll): These always resume on the game thread.

Completion

Completion includes unsuccessful completions (e.g., failures or cancellations).

FAwaitableSemaphore is a coroutine-friendly replacement for std::counting_semaphore. It does not use an acquire() method; instead, it is directly awaitable, which acquires exactly 1 count.

Key Behaviors:

• Thread Safety: All operations are thread-safe.
• Immovability: Objects are immovable. Use smart pointers if you need to move or copy them.
• Cancellation: Supports expedited cancellation, processed on the same thread that calls Cancel().
• Limitations: Does not support interprocess usage (unlike some Unreal FSemaphore types).

// Example conceptual usage
FAwaitableSemaphore MySemaphore(1, 1); // Capacity 1, Initial 1

// In a coroutine (acquires 1 count)
co_await MySemaphore;

// In another thread (releases 1 count)
MySemaphore.Unlock();

UE5Coro includes a custom K2Node to improve the visual experience of calling Coroutine UFUNCTIONs in Blueprints.

Key behaviors:

• Visual Cleanup: It removes unnecessary pins from the node to keep the graph clean.
• Automatic Patching: It performs runtime patching on UFunctions so you do not need to manually mark them with BlueprintInternalUseOnly.
• Editor Tooltip: The node is labeled with the tooltip "Call Coroutine" to distinguish it from standard function calls.
• Performance: There is no performance penalty in Shipping builds because K2Nodes are editor-only.

Note on Removal: If you decide to remove UE5Coro from your project later, you can simply delete this class. However, if you do, you must implement a core redirect back to K2Node_CallFunction to maintain Blueprint compatibility.

The UE5Coro::Anim namespace provides awaitable functions to interact with Unreal Engine montages and notifies from the game thread. These are useful for gameplay logic that needs to react to animation state changes or specific notifies without implementing boilerplate UFUNCTION callbacks.

Important Usage Constraints:

• The return values of these functions may be copied, but only one copy may be awaited at a time.
• Do not reuse returned values; subsequent awaits are not guaranteed to return a valid value.
• For functions returning pointers (like PlayMontageNotifyBegin), the pointer points to engine-managed memory and has a limited lifetime. It is only valid until the next co_await or co_return.

The FLatentPromise bridges latent TCoroutines and their backing latent actions.

Key Behaviors:

• Initial Suspend: Mimics Blueprint behavior; it will NOT start execution if a similar latent action is already running. If clear, it creates an FPendingLatentCoroutine registered with the world.
• Detaching: To allow seamless multithreading, FLatentPromise can "detach" from the game thread. This ensures the coroutine can reach its next co_await safely even if the latent action manager attempts to delete the pending action on the game thread.
• Resumption: Any awaiter that detaches a FLatentPromise must guarantee that FPromise::Resume is called. This call determines if ownership returns to the game thread/latent action manager or remains detached.
• Final Suspend: Reaching final_suspend always re-attaches the promise to the game thread.

UE5Coro uses aggressive assertions to catch memory and asynchronous execution bugs early. When debugging, pay attention to the following macro types:

• ensureMsgf: Indicates a likely error that the plugin has handled. It will not crash the engine but should be investigated.
• checkf: Indicates a definite error that will likely cause a crash.
• checkf(..., "Internal error: ..."): Indicates a bug within the UE5Coro plugin itself.

UE5Coro implements a simplified, cooperative cancellation model. To avoid the massive overhead of a universal cancellation system, cancellation processing only occurs during co_await when the coroutine is in a known, safe state.

Key Characteristics:

• Cooperative: Cancellation is checked when a coroutine resumes.
• Expedited Cancellation: Awaiters that can handle faster cancellation can register themselves by calling FPromise::RegisterCancelableAwaiter.

Returning TGenerator<T> from a function allows it to yield an arbitrary number of values (including infinite) using co_yield. The caller controls when and how many values to fetch. This is more memory-efficient than allocating a TArray because values are generated on demand.

Note on Deprecation: TGenerator is deprecated when targeting C++23 or later. It is recommended to use std::generator instead. To suppress deprecation warnings, define the macro UE5CORO_DISABLE_GENERATOR_DEPRECATION.

Lifecycle Behaviors:

• A default-constructed TGenerator yields no elements.
• Moving a generator transfers the execution state to the new object; the moved-from object becomes identical to a default-constructed one.

using namespace UE5Coro;

TGenerator<int> Example()
{
    co_yield 1;
    co_yield 2;
    co_yield 3;
}