DEV Community: GameDevToolLab

R3 Operation Rules for Unity 6: SubscribeAwait, EveryUpdate, and Patterns to Avoid

GameDevToolLab — Wed, 08 Jul 2026 06:52:48 +0000

Introduction

In the previous article, I covered the basic design rules for using R3 in Unity 6 projects: how to expose ReactiveProperty<T> and Subject<T>, how to manage subscription lifetimes, and how to separate R3 from async/await.

This article continues from there and focuses on operation rules after introducing R3.

The target reader is a Unity team with around 10 programmers, where multiple people touch UI, networking, loading, presentation, and game flow. In solo development or short-lived prototypes, you may not need to be this strict. This article intentionally takes a conservative approach that prioritizes maintainability in long-running projects.

This is not an article about Unity 6-specific APIs. It is about how to operate R3 safely in Unity 6-era projects. Most of the ideas also apply to other Unity versions supported by R3.

The code samples omit common using declarations such as using R3;, using UnityEngine;, TextMeshPro, R3.Unity uGUI extensions, and CancellationToken. Methods such as OnClickAsObservable() and OnValueChangedAsObservable() assume R3.Unity uGUI extensions. In Unity projects, you need both the R3 core package and R3.Unity, and their versions should be aligned.

This article assumes R3 1.2.0 or later. In R3 1.2.0, the default value of cancelOnCompleted for SubscribeAwait, SelectAwait, WhereAwait, and ReactiveCommand was changed to false. When combining Take(1), disposal, completion, and async work, distinguish between stopping further input and canceling the currently running operation.

The three rules to take away are:

SubscribeAwait(Drop) prevents duplicate execution while an operation is running; it is not the same as simultaneous-input protection or one-shot control.
PlayerLoop/time-based streams such as EveryUpdate and Timer should make purpose, lifetime, and provider explicit.
Use R3 for notification and wiring; keep domain logic and important mutual exclusion readable as ordinary C#.

Use SubscribeAwait for repeated-click protection

A common UI problem is repeated clicks during a network request or loading operation.

R3 provides SubscribeAwait and SelectAwait. They let you specify how to handle the next event while an async operation is still running by using AwaitOperation.

If you want to ignore clicks while a request is running, use Drop.

_loginButton.OnClickAsObservable()
    .SubscribeAwait(
        async (_, ct) =>
        {
            await LoginAsync(ct);
        },
        AwaitOperation.Drop)
    .AddTo(this);

Drop discards subsequent events that arrive while the async operation is running. It is useful for login buttons, purchase buttons, gacha buttons, and confirm buttons where duplicate execution during processing must be avoided.

However, Drop does not mean "execute only once forever." If the operation finishes quickly, the next click will be processed normally. If the dialog stays open after the operation, input can still be accepted again. If you want to accept only the first input for the whole screen or dialog session, use a separate mechanism such as Take(1), a confirmed flag, explicit disposal, or closing the screen.

For a search box where you want to cancel the previous request and process only the latest text, Switch is usually a better fit.

_searchInput.OnValueChangedAsObservable()
    .Skip(1) // Use this when initial-value search is not needed.
    .Debounce(TimeSpan.FromMilliseconds(300), UnityTimeProvider.Update)
    .SubscribeAwait(
        async (text, ct) =>
        {
            await SearchAsync(text, ct);
        },
        AwaitOperation.Switch)
    .AddTo(this);

In R3.Unity, OnValueChangedAsObservable() emits the latest value at the time of subscription. If initial-value search is part of the specification, that is fine. If you do not want to call an API with an empty string or initial value during screen initialization, add Skip(1) or an explicit filter. The Debounce provider also matters: should it run while the game is paused, or should it follow Time.timeScale? In this example, UnityTimeProvider.Update is specified explicitly.

A simple team rule can start like this:

Use case	Recommended operation
Login, purchase, confirm, gacha	`Drop`
Search, preview update	`Switch`
Must process in order	`Sequential`
Safe to run in parallel	`Parallel`

For ordinary game UI, avoid using Parallel casually. It is not common for multiple purchases, transitions, or network operations to be safe when executed at the same time.

Repeated-click protection and simultaneous-input protection are different

Repeated-click protection and simultaneous-input protection are not the same thing.

Repeated-click protection handles pressing the same button many times in a short period. Simultaneous-input protection handles multiple buttons, back keys, shortcuts, gamepad inputs, or other input paths firing at nearly the same time.

If each button has its own SubscribeAwait(Drop), different buttons are not mutually exclusive.

_okButton.OnClickAsObservable()
    .SubscribeAwait(async (_, ct) => await DecideAsync(ct), AwaitOperation.Drop)
    .AddTo(this);

_cancelButton.OnClickAsObservable()
    .SubscribeAwait(async (_, ct) => await CancelAsync(ct), AwaitOperation.Drop)
    .AddTo(this);

In this form, pressing OK and Cancel almost simultaneously can still run both operations. Drop is applied per Observable stream.

If operations should be mutually exclusive, first merge them into one event stream.

private enum DialogAction
{
    Ok,
    Cancel
}

Observable.Merge(
        _okButton.OnClickAsObservable().Select(_ => DialogAction.Ok),
        _cancelButton.OnClickAsObservable().Select(_ => DialogAction.Cancel))
    .SubscribeAwait(
        async (action, ct) =>
        {
            await ExecuteDialogActionAsync(action, ct);
        },
        AwaitOperation.Drop)
    .AddTo(this);

Now OK and Cancel belong to the same mutual-exclusion group. If another event arrives while the operation is running, it will be dropped.

Still, this is only duplicate-execution prevention while the operation is running. If a confirmation dialog must accept exactly one action and never accept another one afterward, use session-level one-shot control.

Observable.Merge(
        _okButton.OnClickAsObservable().Select(_ => DialogAction.Ok),
        _cancelButton.OnClickAsObservable().Select(_ => DialogAction.Cancel))
    .Take(1)
    .SubscribeAwait(
        async (action, ct) =>
        {
            await ExecuteDialogActionAsync(action, ct);
        },
        AwaitOperation.Drop,
        cancelOnCompleted: false)
    .AddTo(this);

Take(1) stops input after the first event. That is separate from whether the async operation already in progress should be canceled or allowed to finish. For purchases, payments, server state changes, and gacha confirmation, you must also design cancellation, partial success, retry behavior, and idempotency.

Another common pattern is to keep an explicit confirmed/closed flag.

private bool _closed;

private async ValueTask ExecuteDialogActionAsync(DialogAction action, CancellationToken ct)
{
    if (_closed)
    {
        return;
    }

    _closed = true;
    SetButtonsInteractable(false);

    await ExecuteAsync(action, ct);
}

It is also safer to put a shared gate on the processing side, not only in the UI stream. Input paths tend to grow over time: shortcuts, gamepads, keyboard back, test hooks, or direct method calls.

private bool _isProcessing;

private async ValueTask ExecuteDialogActionAsync(DialogAction action, CancellationToken ct)
{
    if (_isProcessing)
    {
        return;
    }

    _isProcessing = true; // Set this at the very beginning of the entry point.

    try
    {
        SetButtonsInteractable(false);

        switch (action)
        {
            case DialogAction.Ok:
                await DecideAsync(ct);
                break;
            case DialogAction.Cancel:
                await CancelAsync(ct);
                break;
        }
    }
    finally
    {
        _isProcessing = false;

        if (this != null && gameObject.activeInHierarchy)
        {
            SetButtonsInteractable(true);
        }
    }
}

This bool gate is a simple example for UI / Presenter code running on the Unity main thread. If the operation can be called from a service layer, background thread, SDK callback, or multiple threads, use an appropriate synchronization method such as SemaphoreSlim, Interlocked, lock, or a dedicated job queue.

Also be careful with finally. Re-enabling buttons unconditionally can be wrong if the view was destroyed, the screen was closed, or the button was disabled for another reason. In production code, choose a policy such as restoring the previous interactable state, binding a processing state from the ViewModel, or not re-enabling UI when the screen closes.

A useful way to separate responsibilities is this:

Layer	Responsibility
View	Merge multiple input paths into one entry point
Observable stream	Drop later events while processing
Presenter / ViewModel	Hold shared gates and confirmed states
Service / Server	Provide idempotency and duplicate-execution protection for important operations

A good team rule is:

UI operations that must not run together should not be handled by independent per-button subscriptions. Merge them as one mutual-exclusion group and pass them through one SubscribeAwait(Drop) or one shared gate.

Do not overuse EveryUpdate

R3 provides Observable.EveryUpdate(). It is convenient because it creates a stream that emits every frame. But if everything becomes EveryUpdate, the code can become harder to follow than a normal Update method.

A bad example:

Observable.EveryUpdate()
    .Subscribe(_ =>
    {
        Move();
        Rotate();
        CheckGround();
        UpdateAnimation();
    })
    .AddTo(this);

There is little benefit in writing this with R3. A normal Update is clearer.

void Update()
{
    Move();
    Rotate();
    CheckGround();
    UpdateAnimation();
}

EveryUpdate is useful when you want to treat frame updates as an event stream and compose it.

Observable.EveryUpdate()
    .Where(_ => _player.IsGrounded)
    .Take(1)
    .Subscribe(_ => OnLanded())
    .AddTo(this);

Or when you want to observe something for a fixed number of frames:

Observable.EveryUpdate()
    .Take(60)
    .Subscribe(_ => UpdatePreview())
    .AddTo(this);

However, if UpdatePreview() performs heavy work such as rebuilding UI or generating meshes, running it for 60 consecutive frames may still be too expensive. This is not an R3-specific issue; be careful with the actual work performed every frame.

A practical rule:

Use normal Update for ordinary game-loop logic.
Use EveryUpdate only when frame events need stream composition.
Long-lived EveryUpdate subscriptions should have a clear reason.
EveryUpdate().Subscribe(...) with no meaningful composition should be questioned in review.

If you need FixedUpdate-like timing, R3 can use UnityFrameProvider.FixedUpdate.

Observable.EveryUpdate(UnityFrameProvider.FixedUpdate)
    .Subscribe(_ => CheckFixedFrameEvent())
    .AddTo(this);

Even so, physics logic itself is often clearer in a normal FixedUpdate(). Use R3 here only when you need to compose events that happen on the FixedUpdate timing.

Be explicit about TimeProvider and FrameProvider

R3 can specify providers for time-based and frame-based operations. In Unity, the defaults are the Update-based providers: UnityTimeProvider.Update and UnityFrameProvider.Update.

Use Timer or Interval when waiting by time.

Observable.Timer(TimeSpan.FromSeconds(1), UnityTimeProvider.Update)
    .Subscribe(_ => ShowMessage())
    .AddTo(this);

If the operation should ignore Time.timeScale, use UpdateIgnoreTimeScale explicitly.

Observable.Timer(TimeSpan.FromSeconds(1), UnityTimeProvider.UpdateIgnoreTimeScale)
    .Subscribe(_ => ShowMessage())
    .AddTo(this);

If you want to wait for a number of frames, use frame-based APIs instead of seconds.

Observable.TimerFrame(60, UnityFrameProvider.Update)
    .Subscribe(_ => ShowAfter60Frames())
    .AddTo(this);

Omitting the provider is not always wrong. But in games, whether a timer should stop during pause, ignore timeScale, or be frame-based is part of the specification. For important code, specifying the provider makes review easier.

Use Observable Tracker for review and investigation

R3 has Observable Tracker, a debugging aid for inspecting Observable and subscription state.

When a team first introduces R3, common problems include:

Subscriptions remain after closing a screen.
Opening the same view increases the subscription count.
EveryUpdate keeps running longer than intended.
Nobody knows which Observable is still alive.

Observable Tracker is useful for investigating these problems.

That said, it should not replace code review. The basic rule is to decide lifetimes in code first, then use Observable Tracker for suspicious areas or during the initial adoption phase.

Do not let R3 leak too deeply into domain logic

Once R3 is introduced, it can be tempting to turn everything into Observable streams. But if the core domain logic also becomes reactive, people who are not comfortable with R3 may struggle to read or modify it.

For example, damage calculation is often just ordinary C#.

public void Damage(int damage)
{
    if (damage <= 0)
    {
        return;
    }

    Hp = Mathf.Max(0, Hp - damage);
}

There is no need to express this calculation itself as an Observable chain.

Use R3 to notify the result.

private readonly Subject<Unit> _dead = new();
public Observable<Unit> Dead => _dead;

public void Damage(int damage)
{
    if (damage <= 0)
    {
        return;
    }

    Hp = Mathf.Max(0, Hp - damage);

    if (Hp == 0)
    {
        _dead.OnNext(Unit.Default);
    }
}

In real code, the class that owns the Subject should also dispose it.

The basic policy is:

Keep calculations, decisions, and state transitions as ordinary C#.
Use R3 for state-change notifications, UI updates, and event wiring.
Do not bury important specifications deep inside Observable chains.

This matters a lot in team development. If only the R3 expert can safely change the code, maintainability has already gone down.

Split complex chains

Short R3 chains can be readable. Long ones become hard to review quickly.

_model.Items
    .Where(items => items != null)
    .Select(items => items.Where(x => x.IsVisible))
    .Select(items => items.OrderBy(x => x.SortOrder))
    .Select(items => items.Take(10))
    .Subscribe(items => UpdateList(items))
    .AddTo(this);

This is still understandable, but real projects often add more conditions.

When a chain grows, split it into named intermediate Observables or ordinary methods.

var visibleItems = _model.Items
    .Where(items => items != null)
    .Select(FilterVisibleItems);

var sortedItems = visibleItems
    .Select(SortItems);

sortedItems
    .Subscribe(UpdateList)
    .AddTo(this);

private IEnumerable<Item> FilterVisibleItems(IEnumerable<Item> items)
{
    return items.Where(x => x.IsVisible);
}

private IEnumerable<Item> SortItems(IEnumerable<Item> items)
{
    return items.OrderBy(x => x.SortOrder).Take(10);
}

Named methods are easier to review than business rules hidden inside a long chain.

Use ToReadOnlyReactiveProperty() when the result should be stored as state. Remember that the generated ReadOnlyReactiveProperty also owns upstream subscriptions, so it needs a lifetime too.

Do not overuse ToObservable

ToObservable() is useful, but not everything should become an Observable.

If you only need to calculate a total, LINQ is enough.

var total = items.Sum(x => x.Price);

There is no need to write this as an Observable chain.

items.ToObservable()
    .Select(x => x.Price)
    .Sum()
    .Subscribe(total => Debug.Log(total));

R3 is strong when values flow over time. If you are just aggregating an in-memory collection right now, LINQ or a normal foreach is usually clearer.

Do not rely on AddTo(this) for every lifetime

AddTo(this) is the basic way to tie a subscription to the lifetime of a MonoBehaviour or GameObject.

_model.Hp
    .Subscribe(UpdateHp)
    .AddTo(this);

But AddTo(this) usually means lifetime until Destroy. It does not automatically mean disabled, hidden, tab-switched, popup-closed, or re-bound.

If a tab creates subscriptions every time it is selected, use a separate DisposableBag for that tab binding.

private DisposableBag _tabDisposables;

public void BindTab(TabModel tab)
{
    _tabDisposables.Dispose();
    _tabDisposables = default;

    tab.Items
        .Subscribe(UpdateItems)
        .AddTo(ref _tabDisposables);
}

private void OnDestroy()
{
    _tabDisposables.Dispose();
}

If a disposed DisposableBag receives a new disposable, the new one is disposed immediately. Reset it with = default before reusing the field.

The same applies to Views whose Initialize() method may be called multiple times.

private DisposableBag _bindDisposables;

public void Initialize(PlayerStatus status)
{
    _bindDisposables.Dispose();
    _bindDisposables = default;

    status.Hp
        .Subscribe(UpdateHp)
        .AddTo(ref _bindDisposables);
}

If a prefab is reused, dependency injection runs again, or a tab is rebound, AddTo(this) alone can leave the previous subscription alive. Distinguish between GameObject lifetime, display lifetime, and binding lifetime.

How to think about OnErrorResume

R3 does not use the traditional Rx model where OnError stops the subscription. Instead, errors are handled through OnErrorResume.

For UI events, this is often convenient: a failed click should not necessarily kill the button subscription forever. But it also does not mean exceptions can be swallowed silently.

_loginButton.OnClickAsObservable()
    .SubscribeAwait(
        async (_, ct) =>
        {
            await LoginAsync(ct);
        },
        ex =>
        {
            if (ex is OperationCanceledException)
            {
                return;
            }

            Debug.LogException(ex);

            if (this != null && gameObject.activeInHierarchy)
            {
                _dialog.Show("Login failed.");
            }
        },
        _ => { },
        AwaitOperation.Drop)
    .AddTo(this);

The second argument is R3's OnErrorResume handler, not the old Rx OnError. The subscription does not stop.

In production code, decide these rules:

Send logs to Debug.LogException or the project's standard logger.
Separate user-facing failure messages from developer logs.
Decide whether OperationCanceledException should be shown to users.
Do not touch a destroyed View after screen transition.
For important operations, consider representing success/failure as a return value instead of relying only on Observable error handling.

Patterns to avoid

These are the patterns I would explicitly ban in team development.

Pattern to avoid	Problem	Alternative
`public ReactiveProperty<T>`	Anyone can write to it	Keep it private and expose `ReadOnlyReactiveProperty<T>`
`public Subject<T>`	Anyone can call `OnNext`	Keep it private and expose `Observable<T>`
static/global `Subject`	Publisher, subscriber, and lifetime become unclear	Keep events within a feature or screen scope
`Subscribe` without lifetime	Leaks and duplicate execution	Use `AddTo` / `DisposableBag`
Adding subscriptions every `Initialize()`	Re-initialization creates duplicates	Dispose binding disposables before rebinding
Per-button `Drop` for exclusive actions	Does not prevent simultaneous input	Merge by mutual-exclusion group
Using `EveryUpdate` as `Update`	Intent becomes harder to follow	Use normal `Update` for ordinary loops
Making everything `ToObservable()`	Harder than LINQ or `foreach`	Use Observable only where time flow matters
Very long chains	Hard to review	Split into intermediate Observables or methods
Swallowing errors in `OnErrorResume`	Failures disappear from monitoring	Define logging and display rules

Even when exposing ReadOnlyReactiveProperty<T> or Observable<T>, a caller who knows the concrete object could force an unsafe cast. The point is not to make abuse impossible through types alone. The point is to hide write access from the public API and make unsafe casts a team-rule violation.

Team operation rules

Based on the table above, code review can focus on four questions:

Is the write entry point hidden?
Is the subscription lifetime clear, including re-initialization?
Are repeated clicks, simultaneous input, and one-shot control treated as separate problems?
Is the code using Observable where ordinary C#, LINQ, Update, or async/await would be clearer?

Do not start by creating too many detailed rules. It is safer to first establish private write access, lifetime management, input exclusivity, and limited EveryUpdate usage.

Adoption scope

R3 is safer to introduce gradually, not all at once across the entire project.

A practical adoption order is:

UI events and repeated-click protection
ViewModel-to-View state notification
Loading progress and busy flags
Composition of multiple inputs
Game events only where needed

If you try to convert every Model, Service, and event to R3 at once, review cost will rise quickly. In a team with R3 beginners, starting from UI and ViewModel code usually leads to smoother adoption.

Notes for migrating from UniRx

If your team has UniRx experience, people may treat R3 as just a newer UniRx. But several design details are different.

Important points include:

Use Debounce, not Throttle.
Do not assume OnError stops the subscription.
Use SubscribeAwait and AwaitOperation for async UI events.
Follow R3's disposable patterns such as DisposableBag.
Be explicit about Unity providers where timing matters.

Migration is not only API replacement. Revisit error handling, async behavior, and subscription lifetime design.

Recommended practical structure

A typical maintainable structure is to separate Model, Presenter/ViewModel, and View responsibilities.

Model

The Model owns state and publishes change notifications. It does not expose write access.

public sealed class PlayerStatus : IDisposable
{
    private readonly ReactiveProperty<int> _hp = new(100);
    public ReadOnlyReactiveProperty<int> Hp => _hp;

    public void Damage(int damage)
    {
        if (damage <= 0)
        {
            return;
        }

        _hp.Value = Mathf.Max(0, _hp.Value - damage);
    }

    public void Dispose()
    {
        _hp.Dispose();
    }
}

ViewModel / Presenter

The ViewModel or Presenter converts Model state into UI-friendly state. Any generated ReadOnlyReactiveProperty must also have a lifetime.

private DisposableBag _disposables;
private ReadOnlyReactiveProperty<bool> _canDecide;

public ReadOnlyReactiveProperty<bool> CanDecide => _canDecide;

public void Initialize(PlayerStatus status, Wallet wallet)
{
    _disposables.Dispose();
    _disposables = default;

    _canDecide = Observable.CombineLatest(
            status.Hp,
            wallet.Gold,
            (hp, gold) => hp > 0 && gold >= 100)
        .ToReadOnlyReactiveProperty();

    _canDecide.AddTo(ref _disposables);
}

public void Dispose()
{
    _disposables.Dispose();
}

If Initialize() may be called more than once, rebuild subscriptions after disposing the previous ones. If the class is single-initialization only, make that assumption explicit in the design.

View

The View sends UI events to the Presenter and reflects Presenter state into UI.

private DisposableBag _bindDisposables;

public void Initialize(PlayerPresenter presenter)
{
    _bindDisposables.Dispose();
    _bindDisposables = default;

    presenter.CanDecide
        .Subscribe(canDecide => _decideButton.interactable = canDecide)
        .AddTo(ref _bindDisposables);

    _decideButton.OnClickAsObservable()
        .SubscribeAwait(
            async (_, ct) => await presenter.DecideAsync(ct),
            AwaitOperation.Drop)
        .AddTo(ref _bindDisposables);
}

private void OnDestroy()
{
    _bindDisposables.Dispose();
}

If Initialize() is guaranteed to be called only once, AddTo(this) can be enough. If the View can be rebound or re-initialized, explicitly dispose the previous binding subscriptions.

Choosing not to use R3 is also important

R3 is useful, but not every piece of code needs it.

Examples where R3 is often unnecessary:

Simple sequential logic
One-time loading
Complex damage calculation
AI decision-making core
Core physics update logic
One-off collection aggregation

These are often clearer with ordinary C#, async/await, Update, or LINQ.

Use R3 where you need to compose events or value flows:

UI events
State-change notifications
Composition of multiple inputs
Repeated-click and simultaneous-input protection
Loading progress
ViewModel-to-View notification

The purpose of R3 is not to make code look advanced. It is to make event flow and lifetime explicit enough for the team to maintain.

Conclusion

R3 is very effective when its usage is constrained. It works well for UI events, ViewModel-to-View notifications, loading progress, busy flags, and input composition. In those areas, it can express intent more clearly than hand-written event management.

But if the team uses it freely everywhere, Subject, EveryUpdate, long chains, and subscriptions with unclear lifetimes will multiply.

The most important point in this article is to separate repeated clicks, simultaneous input, one-shot control, subscription lifetime, and time providers. For a 10-person Unity team that needs to maintain a project over time, R3 should not be introduced as a tool for making everything Observable. It should be introduced as a restricted set of rules for writing notification and wiring code safely.

R3 Design Rules for Unity 6: Keeping Reactive Code Maintainable in a 10-Person Team

GameDevToolLab — Mon, 06 Jul 2026 16:09:43 +0000

Introduction

There are many ways to handle events and state changes in Unity.

Update
UnityEvent
C# events
Action
async/await
UniTask
UniRx
R3
custom event buses
ScriptableObject-based events

For a small prototype, almost any of these can work.

The situation changes when a project has around ten programmers and multiple people touch the same UI, game flow, networking, effects, and loading code. Event handling quickly becomes one of the easiest places to lose control.

Typical problems look like this:

Nobody knows where a subscription is created.
Nobody knows when a subscription is disposed.
Events are delivered to destroyed GameObjects.
Subject turns into a global event bus.
UI updates are scattered across many classes.
async code and input-spam prevention are mixed together.
leaked subscriptions cause memory leaks or duplicated execution.
only the people who already know Rx can read the code.

R3 is a modern Reactive Extensions implementation developed by Cysharp.

The Cysharp/R3 README describes R3 as a new future for dotnet/reactive and UniRx, with support for multiple platforms including Unity. The author also introduces R3 as a modern reimplementation of Reactive Extensions for C# in this article.

For Unity projects, you usually install both the core R3 package and R3.Unity. Unity support starts from Unity 2021.3.

In production, keep the versions of R3 and R3.Unity aligned. Updating only one side, or leaving one side behind, can cause API mismatches or dependency trouble. It is better to define the installation and update procedure as part of the project rules.

In Unity, UnityTimeProvider.Update and UnityFrameProvider.Update are set as defaults, so R3 fits naturally into Unity 6-era projects.

This article focuses on how to use R3 in a maintainable way in Unity 6 projects, and which patterns should be avoided in team development.

The target environment is roughly this:

Unity 6 series
around ten programmers
long-term operation and maintenance
UI, loading, networking, game flow, and effects touched by multiple people
a mix of UniRx users and people new to reactive programming
a need to care about GC, subscription leaks, and operational stability

This is not a full introduction to every R3 feature.

The goal is simpler: define practical rules that prevent R3 from breaking maintainability in team development.

Code samples omit common using directives such as using R3;, using UnityEngine;, R3.Unity uGUI extensions, TextMeshPro namespaces, and CancellationToken. Adjust them to match your UI package, DI container, and project structure.

The short version

If you use R3 in Unity, start with these rules:

Use R3 for event wiring and state-change notification.
Leave one-shot async operations to async/await.
Expose Observable<T> or ReadOnlyReactiveProperty<T>.
Keep Subject<T> and writable ReactiveProperty<T> private.
Always tie subscriptions to a GameObject, Component, ViewModel, or another explicit owner.
Use SubscribeAwait and AwaitOperation for UI input control in the operational layer.
Use frame-based operators such as IntervalFrame, DelayFrame, and EveryUpdate only when the frame semantics matter.
Limit the R3 patterns allowed in the team.
Do not turn everything into an Observable.

The most important point is this:

Do not turn R3 into a magical application-wide event system.

R3 is powerful. If everyone uses it freely, the project can quickly become a codebase where nobody knows where events come from or who reacts to them.

For maintainability, use R3 as a strong tool, but keep its scope controlled.

Where R3 works well

R3 is a good fit when you want to compose a stream of values or events.

For example:

button clicks
Toggle and Slider changes
input events
HP, stamina, currency, and other state-change notifications
ViewModel-to-View updates
loading progress
busy/loading flags
input-spam prevention
delayed-by-frame behavior
combining multiple events
updating UI only when a value changes

On the other hand, not everything should be pushed into R3.

These are usually better left outside R3:

simple sequential processing
one-shot loading
complex domain logic
cutscene or effect sequences that are easier to read procedurally
large amounts of per-frame logic
the core of physics updates
AI decision-making logic
battle calculation logic

R3 is for observing, transforming, combining, and subscribing to value streams.

You do not need to convert every piece of code into an Observable.

Separate R3 from async/await

The first rule to decide is how R3 and async/await should share responsibility.

The Cysharp/R3 README follows the idea that one-shot asynchronous operations should generally be represented by ***Async methods returning Task<T>.

In Unity projects, I recommend this split.

Use async/await for these

loading master data once
loading one prefab through Addressables
calling one API endpoint
saving data once
running initialization steps in order
showing one dialog and waiting for its result

When using Addressables, waiting with async/await and releasing resources are separate responsibilities. The owner of the loaded resource still needs to own Addressables.Release, Addressables.ReleaseInstance, or the equivalent cleanup. This is similar to R3 subscription lifetime management: do not make ownership vague.

Use R3 for these

handling repeated button clicks
reflecting value changes into the UI
deriving button interactability from multiple states
showing and hiding loading UI from a busy flag
controlling repeated input with Drop or Switch
handling events based on frames, timers, or repeated intervals

For example, a loading operation itself can be plain async/await:

public async Task<PlayerMaster> LoadPlayerMasterAsync(CancellationToken ct)
{
    var json = await _storage.LoadTextAsync("player_master.json", ct);
    return JsonUtility.FromJson<PlayerMaster>(json);
}

This short example uses JsonUtility only to keep the sample simple. In real projects, choose a JSON library or custom loader based on your data format. JsonUtility has limitations such as dictionaries, top-level arrays, and null handling.

If you want to expose loading progress to the UI, R3 becomes useful:

public sealed class LoadingModel : IDisposable
{
    private readonly ReactiveProperty<float> _progress = new(0f);
    public ReadOnlyReactiveProperty<float> Progress => _progress;

    public void SetProgress(float value)
    {
        _progress.Value = Mathf.Clamp01(value);
    }

    public void Dispose()
    {
        _progress.Dispose();
    }
}

A class like LoadingModel implements IDisposable, so whoever creates it must also define when it is disposed. That owner might be a DI container, a LifetimeScope, a screen Presenter, or a MonoBehaviour.

The operation itself is async/await.

The state notification is R3.

This separation makes the code much easier to read in a team.

Publish R3 events on the Unity main thread by default

In Unity projects, it is safest to make this a team rule:

Subject.OnNext and ReactiveProperty<T>.Value updates should normally happen on the Unity main thread.

The Cysharp/R3 README explains that operator composition is designed to be thread-safe, but the values flowing through OnNext are expected to be published from a single thread. If Subject.OnNext is called from multiple threads, synchronization such as lock is required. ReactiveProperty also does not make simultaneous OnNext, Value updates, and Subscribe operations thread-safe.

A practical Unity rule looks like this:

// Example team policy
// - Update ReactiveProperty.Value on the Unity main thread.
// - Do not call Subject.OnNext directly from external SDK callbacks or background threads.
// - If a result comes from Task.Run, a custom thread, or an SDK callback,
//   return to the main thread before notifying the UI or game layer when needed.
// - If multi-threaded publication is truly required, consider lock,
//   Synchronize, SynchronizedReactiveProperty, or a dedicated queue.

Network callbacks and external SDK events do not always return on Unity's main thread.

This is not only about "UI must be updated on the main thread." It is also about keeping the R3 event stream itself on a predictable thread.

Keep ReactiveProperty private

ReactiveProperty<T> is one of the most useful R3 types for state.

It is also easy to misuse.

If you expose it directly as public, any caller can write to it.

Bad example:

public sealed class PlayerStatus
{
    public ReactiveProperty<int> Hp { get; } = new(100);
}

Now any caller can do this:

playerStatus.Hp.Value = 999;

This is convenient in the short term, but once the game is in operation, it becomes hard to answer a basic question: "Who changed HP?"

For maintainability, keep writable ReactiveProperty<T> fields private and expose them as read-only properties.

public sealed class PlayerStatus : IDisposable
{
    private readonly ReactiveProperty<int> _hp = new(100);

    public ReadOnlyReactiveProperty<int> Hp => _hp;

    public void Damage(int value)
    {
        if (value <= 0)
        {
            return;
        }

        _hp.Value = Mathf.Max(0, _hp.Value - value);
    }

    public void Heal(int value)
    {
        if (value <= 0)
        {
            return;
        }

        _hp.Value = Mathf.Min(100, _hp.Value + value);
    }

    public void Dispose()
    {
        _hp.Dispose();
    }
}

This PlayerStatus also implements IDisposable, so the creator must dispose it. Tie it to the owner lifetime: screen, battle, scene, DI scope, or another explicit lifetime.

External code can subscribe to HP changes, but normal API usage cannot modify the value directly.

This is not perfect type-level security. Since the actual object is still a ReactiveProperty<T>, an abusive downcast can still mutate it. Make it part of the team rule that ReadOnlyReactiveProperty<T> must not be cast back to ReactiveProperty<T> for mutation.

_playerStatus.Hp
    .Subscribe(hp => _hpText.text = hp.ToString())
    .AddTo(this);

The basic pattern is this:

private readonly ReactiveProperty<T> _value = new(initialValue);
public ReadOnlyReactiveProperty<T> Value => _value;

This is especially important in Models and ViewModels.

R3 should make state flow easier to observe. It should not make state writable from anywhere.

Be even more careful with Subject

Subject<T> is convenient, but it is also one of the most dangerous R3 types.

A Subject<T> is an event publication endpoint. If it is public, anyone can call OnNext.

Bad example:

public sealed class BattleEvents
{
    public Subject<int> OnDamage { get; } = new();
}

Now unrelated code can publish damage:

battleEvents.OnDamage.OnNext(999);

That breaks the meaning of the event source.

A more maintainable shape is to keep Subject<T> private and expose it as Observable<T>.

public sealed class BattleEvents : IDisposable
{
    private readonly Subject<int> _damaged = new();

    public Observable<int> Damaged => _damaged;

    public void PublishDamage(int damage)
    {
        if (damage <= 0)
        {
            return;
        }

        _damaged.OnNext(damage);
    }

    public void Dispose()
    {
        _damaged.Dispose();
    }
}

From the public API, other classes can treat it as subscription-only. Again, a type alone cannot prevent every abusive cast or rule violation. The important part is that the normal path does not expose the publication endpoint, and the team rule forbids casting it back to Subject to publish events.

_battleEvents.Damaged
    .Subscribe(damage => ShowDamageEffect(damage))
    .AddTo(this);

Now event publication is limited to the code path that can call PublishDamage.

That alone makes the event flow much easier to trace.

Do not create a global Subject-based event bus

A common failure after introducing R3 is a global event bus.

For example:

public static class GlobalEventBus
{
    public static readonly Subject<object> Event = new();
}

Or even with separate event types:

public static class GameEvents
{
    public static readonly Subject<PlayerDeadEvent> PlayerDead = new();
    public static readonly Subject<ItemGotEvent> ItemGot = new();
    public static readonly Subject<QuestCompletedEvent> QuestCompleted = new();
}

This can look useful in a small project.

As the team grows, the problems appear quickly:

publishers are hard to trace
subscribers are hard to trace
event lifetime is vague
subscriptions survive across scenes
tests become harder
event names keep increasing
execution order becomes implicit
the impact of specification changes becomes hard to predict

In a live game, someone may add an event later without noticing an existing subscriber, causing unexpected side effects.

If you use R3, keep events scoped as much as possible.

only inside Battle
only inside one UI screen
only inside a ViewModel
only inside one Feature
only inside a Scene or LifetimeScope

If an event truly needs to be application-wide, design it as an explicit application service or event aggregation layer. Do not just place an R3 Subject globally and call it a day.

Every Subscribe must have a lifetime

The most important part of R3 usage is subscription disposal.

Subscribe creates a subscription.

If that subscription is never disposed, references can remain, events can be delivered to destroyed Views, and the same logic can run two or three times.

The Cysharp/R3 README also emphasizes that subscription management is a core Rx concern, and poor management can lead to memory leaks.

In Unity, the basic pattern is to tie subscriptions to a Component or GameObject.

OnClickAsObservable() and OnValueChangedAsObservable() in these samples are R3.Unity uGUI extension methods.

_button.OnClickAsObservable()
    .Subscribe(_ => OnClick())
    .AddTo(this);

This disposes the subscription according to the lifetime of this MonoBehaviour.

You can also tie it to a GameObject:

_observable
    .Subscribe(x => Debug.Log(x))
    .AddTo(gameObject);

The review rule is simple:

If you call Subscribe, decide the lifetime on the same line or nearby.

Bad example:

void Start()
{
    _playerStatus.Hp.Subscribe(hp =>
    {
        _hpText.text = hp.ToString();
    });
}

This code does not show when the subscription is disposed.

It is also easy to miss in code review.

Better:

void Start()
{
    _playerStatus.Hp
        .Subscribe(hp =>
        {
            _hpText.text = hp.ToString();
        })
        .AddTo(this);
}

R3.Unity's AddTo(Component / GameObject) is designed to handle Unity-specific destruction issues by using ObservableDestroyTrigger, including cases where inactive GameObjects can make destruction handling awkward.

However, the lifetime here is basically destruction lifetime.

Do not assume AddTo(this) means the subscription stops when the UI is hidden, disabled, or switched to another tab.

SetActive(false), OnDisable, tab changes, and internal screen state changes are different lifetimes. Decide per screen whether hidden UI should keep receiving model updates. If you need subscriptions to stop on disable or rebinding, manage that separately with another DisposableBag, explicit re-subscription, TakeUntil, CancellationToken, or another lifecycle mechanism.

How to choose disposable containers

R3 gives you several ways to manage subscriptions.

For maintainability, keep the team rule simple.

AddTo(this)

Use this for the normal MonoBehaviour lifetime.

_observable
    .Subscribe(OnValueChanged)
    .AddTo(this);

This should be the default in Unity Views and Presenters.

DisposableBag

Use this when a normal C# class owns multiple subscriptions.

private DisposableBag _disposables;

public void Initialize()
{
    _model.Hp
        .Subscribe(UpdateHp)
        .AddTo(ref _disposables);

    _model.Mp
        .Subscribe(UpdateMp)
        .AddTo(ref _disposables);
}

public void Dispose()
{
    _disposables.Dispose();
}

DisposableBag is a struct, so avoid accidental copies.

Hold it as a field and pass it by ref.

Disposable.Combine / Builder

When the number of subscriptions is fixed and small, you can build one disposable.

private IDisposable _disposable;

public void Initialize()
{
    var builder = Disposable.CreateBuilder();

    _model.Hp.Subscribe(UpdateHp).AddTo(ref builder);
    _model.Mp.Subscribe(UpdateMp).AddTo(ref builder);

    _disposable = builder.Build();
}

public void Dispose()
{
    _disposable?.Dispose();
}

If the number of subscriptions is static, this keeps the code simple and avoids unnecessary dynamic management.

CompositeDisposable

Use this only when you need dynamic add/remove behavior.

private readonly CompositeDisposable _disposables = new();

public void Add(IDisposable disposable)
{
    disposable.AddTo(_disposables);
}

public void Dispose()
{
    _disposables.Dispose();
}

CompositeDisposable has more features, but that does not make it the default choice.

A practical team rule is:

AddTo(this) for MonoBehaviours.
DisposableBag for normal classes.
Disposable.CreateBuilder() or Disposable.Combine for a fixed small set.
CompositeDisposable only when removal or dynamic management is needed.

R3 is especially useful for UI

UI is one of the best places to use R3 in Unity.

UI often needs to update when state changes.

Here is a simple HP display:

public sealed class PlayerStatusView : MonoBehaviour
{
    [SerializeField] private TextMeshProUGUI _hpText;
    [SerializeField] private Slider _hpSlider;

    private PlayerStatus _status;

    public void Initialize(PlayerStatus status)
    {
        _status = status;

        _status.Hp
            .Subscribe(UpdateHp)
            .AddTo(this);
    }

    private void UpdateHp(int hp)
    {
        _hpText.text = hp.ToString();
        _hpSlider.value = hp;
    }
}

This much can also be done with a normal event.

In this sample, _hpSlider.value = hp assumes Slider.maxValue matches the max HP. If your project uses normalized 0-1 slider values, convert the value in the View, such as hp / maxHp.

Also, this example assumes Initialize() is called only once. If prefabs are reused, screens are re-initialized, DI injection happens again, or tabs are rebound, dispose the previous subscriptions before subscribing again. AddTo(this) keeps subscriptions until the GameObject is destroyed, so it does not automatically remove subscriptions created by repeated initialization.

R3 becomes more useful when UI state depends on multiple values.

_canDecide = Observable
    .CombineLatest(
        _model.SelectedItem,
        _model.HasEnoughGold,
        _model.IsBusy,
        (item, hasGold, isBusy) => item != null && hasGold && !isBusy)
    .ToReadOnlyReactiveProperty();

// If this MonoBehaviour owns it:
_canDecide.AddTo(this);

// If a normal Presenter / ViewModel owns it:
// _canDecide.AddTo(ref _disposables);

ToReadOnlyReactiveProperty() creates an object that owns an upstream subscription. That generated ReadOnlyReactiveProperty also needs its lifetime managed.

In this sample, the MonoBehaviour owns _canDecide, so it uses AddTo(this). If a Presenter or ViewModel owns it, tie it to that class's DisposableBag instead.

The button can subscribe to it:

_canDecide
    .Subscribe(canDecide => _decideButton.interactable = canDecide)
    .AddTo(this);

This is where R3 shines: deriving UI state from multiple model states.

If the expression grows too long, move the logic into a named method:

private bool CanDecide(Item item, bool hasGold, bool isBusy)
{
    return item != null && hasGold && !isBusy;
}

_canDecide = Observable
    .CombineLatest(
        _model.SelectedItem,
        _model.HasEnoughGold,
        _model.IsBusy,
        CanDecide)
    .ToReadOnlyReactiveProperty();

// If this MonoBehaviour owns it:
_canDecide.AddTo(this);

// If a normal Presenter / ViewModel owns it:
// _canDecide.AddTo(ref _disposables);

R3 chains are easy to read when they are short. When they become long, split them. The follow-up article covers more detailed rules for splitting complex chains.

Do not put heavy logic inside Subscribe

A common R3 mistake is putting too much logic inside Subscribe.

Bad example:

_button.OnClickAsObservable()
    .Subscribe(_ =>
    {
        if (_model.SelectedItem == null)
        {
            _dialog.Show("Please select an item.");
            return;
        }

        if (!_wallet.HasEnoughGold(_model.SelectedItem.Price))
        {
            _dialog.Show("Not enough gold.");
            return;
        }

        _wallet.Consume(_model.SelectedItem.Price);
        _inventory.Add(_model.SelectedItem);
        _sound.Play(SE.Decide);
        _analytics.Send("buy_item");
        _screen.Close();
    })
    .AddTo(this);

This is easy to write at first, but it does not age well.

Use the R3 chain as the event entry point.

Move the actual logic to methods.

_button.OnClickAsObservable()
    .Subscribe(_ => TryBuySelectedItem())
    .AddTo(this);

private void TryBuySelectedItem()
{
    if (_model.SelectedItem == null)
    {
        _dialog.Show("Please select an item.");
        return;
    }

    if (!_wallet.HasEnoughGold(_model.SelectedItem.Price))
    {
        _dialog.Show("Not enough gold.");
        return;
    }

    Buy(_model.SelectedItem);
}

private void Buy(Item item)
{
    _wallet.Consume(item.Price);
    _inventory.Add(item);
    _sound.Play(SE.Decide);
    _analytics.Send("buy_item");
    _screen.Close();
}

R3 should express when something is called.

Game logic should remain in ordinary methods.

That separation makes code review much easier.

Summary

This article covered the basic design rules for using R3 in Unity 6-era team development.

The key idea is not to spread R3 everywhere just because it is convenient.

Use R3 for event wiring and state-change notification.
Leave one-shot async operations to async/await.
Keep ReactiveProperty<T> and Subject<T> private.
Expose ReadOnlyReactiveProperty<T> or Observable<T>.
Always decide the lifetime when you call Subscribe.
Remember that AddTo(this) is destruction lifetime, not hidden/disabled lifetime.
If Initialize() can run multiple times, dispose previous subscriptions before subscribing again.
Do not put heavy logic directly inside Subscribe.

The next article will cover the operational side: SubscribeAwait, AwaitOperation, EveryUpdate, providers, Observable Tracker, forbidden patterns, and code review points.

LINQ and ZLinq in the Unity 6 Era: Avoiding GC Allocations in Large-Scale Projects

GameDevToolLab — Fri, 03 Jul 2026 03:05:24 +0000

Introduction

In large-scale Unity development, GC Alloc can quietly become a real problem.

At first, nothing looks wrong. But as the project grows and you add more enemies, UI, master data, events, states, notifications, logs, and other systems, small allocations that happen every frame begin to pile up.

LINQ is especially convenient.

var aliveEnemies = enemies
    .Where(x => x.IsAlive)
    .OrderBy(x => x.DistanceToPlayer)
    .ToList();

It is readable.
But if this kind of code runs every frame, it can become a source of both GC Alloc and CPU overhead.

Unity's official documentation also recommends reducing frequent managed heap allocations as much as possible, ideally getting close to 0 bytes per frame.

https://docs.unity3d.com/2022.3/Documentation/Manual/performance-garbage-collection-best-practices.html

For general GC Alloc best practices, this article refers to the Unity 2022.3 documentation, because the general guidance still applies. Unity 6-specific GC behavior is covered later using the Unity 6.0 documentation.

This article assumes Unity 6.0 as the minimum Unity version and explains how to choose between regular LINQ and ZLinq in production code.

Unity 6.0 uses the Roslyn C# compiler, and its C# language version is C# 9.0. However, some C# 9 features, such as init-only setters, are not supported.

https://docs.unity3d.com/6000.0/Documentation/Manual/csharp-compiler.html

The short version

The point of this article is not to ban LINQ completely.

Do not use LINQ in hot paths just because it is readable.

Do not assume ZLinq solves everything just because you introduced it.

Those are the two main ideas.

A rough guideline looks like this:

Area	Guideline
Editor extensions, build scripts, debug code	Regular LINQ is usually fine
Startup, loading, initialization	LINQ can be fine, but measure when data size is large
Update / LateUpdate / FixedUpdate	Avoid LINQ by default
Code that is not per-frame but still called frequently	Consider ZLinq
Code that materializes results into List or Array	Prefer reusing a preallocated List over LINQ/ZLinq
Burst / Job / NativeArray-heavy code	This article does not go deep into this area; prefer for loops and Native Collections

Unity 6 GC assumptions

In Unity 6, Incremental GC is enabled by default.
Unity uses the Boehm-Demers-Weiser garbage collector. With Incremental GC, garbage collection work is split across multiple frames to reduce GC spikes.

https://docs.unity3d.com/6000.0/Documentation/Manual/performance-incremental-garbage-collection.html

However, Incremental GC does not make garbage collection itself faster.
It spreads the workload across multiple frames.

Unity's GC is also non-compacting. Older Unity documentation explains that Unity's GC is non-generational, which means it is not good at efficiently handling small and frequent temporary allocations, such as those caused by boxing.

https://docs.unity3d.com/2022.3/Documentation/Manual/performance-garbage-collection-best-practices.html

You also need to be careful about platform-specific differences.
Unity 6.0's Web platform documentation explains that GC on Web platforms does not run incrementally over multiple frames like it does on other platforms. Instead, it runs once at the end of every frame.

https://docs.unity3d.com/6000.0/Documentation/Manual/webgl-technical-overview.html

Incremental GC also uses write barriers to track reference changes. In code that changes a very large number of references, the overhead of those write barriers may matter.
This article focuses on reducing GC Alloc, but the final decision should always be based on profiling a Player build on the target platform.

In other words, even in Unity 6, the basic policy does not change:

Reduce per-frame GC Alloc as much as possible
Do not underestimate small allocations
Avoid allocations in hot paths before GC spikes become a problem
Confirm the result with the Profiler

Where LINQ tends to become a problem

LINQ is especially risky in code like this:

void Update()
{
    var target = _enemies
        .Where(x => x.IsAlive)
        .OrderBy(x => x.DistanceToPlayer)
        .FirstOrDefault();

    if (target != null)
    {
        Attack(target);
    }
}

This is easy to write, but if it runs every frame, it can become problematic.

The issue is not only GC Alloc.

Enumeration cost from Where and Select
Sorting cost from OrderBy
Allocations from ToList() and ToArray()
Closures created by lambdas
Enumeration through IEnumerable<T>
Accumulation of small allocations

In a large project, one instance may not matter. The problem is that similar code can appear in dozens of places.

The result is often not "someone wrote terrible code".
It is more like "everyone used a convenient pattern a little bit, and GC Alloc slowly grew everywhere".

A case where a for loop is better

The previous code is safer as a simple for loop if it runs in a hot path.

private Enemy FindNearestAliveEnemy(IReadOnlyList<Enemy> enemies)
{
    Enemy nearest = null;
    float nearestDistance = float.MaxValue;

    for (int i = 0; i < enemies.Count; i++)
    {
        Enemy enemy = enemies[i];

        if (!enemy.IsAlive)
        {
            continue;
        }

        float distance = enemy.DistanceToPlayer;
        if (distance < nearestDistance)
        {
            nearest = enemy;
            nearestDistance = distance;
        }
    }

    return nearest;
}

It is longer than LINQ.
But what it does is explicit.

It does not create intermediate enumerables
It does not sort
It does not create a List
It only searches for the minimum value that matches the condition

This kind of small difference matters in code that runs every frame during gameplay.

However, this applies when you only need the nearest single item.
If you need a fully sorted result, such as a ranking display or a list that must be processed in nearest-first order later, OrderBy itself is not wrong.

Also, if DistanceToPlayer calculates Vector3.Distance or magnitude every time in real code, the distance calculation itself may be expensive before LINQ or ZLinq even enters the picture.
For nearest-neighbor checks, you may also want to compare squared distance and cache the player's position before the loop.
In this article's examples, DistanceToPlayer is treated as a lightweight value to keep the code simple.

What is ZLinq?

ZLinq is a zero-allocation-oriented LINQ library by Cysharp.

It lets you write code that resembles regular LINQ, while using AsValueEnumerable() to convert the source into a value-type-based enumerable. The goal is to reduce allocations caused by method chains.
The ZLinq README explains that, unlike regular LINQ, adding more method chains does not easily increase allocations, that it is implemented with struct-based ValueEnumerable, and that it generally has better base performance than regular LINQ.

https://github.com/Cysharp/ZLinq

The basic form looks like this:

using ZLinq;

private void UpdateEnemies(List<Enemy> enemies)
{
    foreach (Enemy enemy in enemies
        .AsValueEnumerable()
        .Where(static x => x.IsAlive))
    {
        enemy.Tick();
    }
}

Compared with regular LINQ, AsValueEnumerable() is added.

// Regular LINQ
foreach (Enemy enemy in enemies.Where(static x => x.IsAlive))
{
    enemy.Tick();
}

// ZLinq
foreach (Enemy enemy in enemies.AsValueEnumerable().Where(static x => x.IsAlive))
{
    enemy.Tick();
}

The code looks similar, but the enumeration mechanism is different.

However, the important point is that adding AsValueEnumerable() does not magically make everything zero-allocation.
If you call ToList(), a List is still created. If a lambda captures an external variable, allocations related to closures can still occur.

Where ZLinq is easy to use

ZLinq works well in cases like this:

foreach (Enemy enemy in _enemies
    .AsValueEnumerable()
    .Where(static x => x.IsAlive)
    .Where(static x => x.IsVisible))
{
    enemy.UpdateMarker();
}

This kind of code is a good fit when you want to:

Filter
Transform
Enumerate
Use the result immediately
Avoid ToList()

In large projects, API boundaries often use types such as IEnumerable<T> or IReadOnlyList<T>.
Abstract types give callers more flexibility, but in hot paths, the fact that the static type is abstract can make profiling and optimization harder.

private void ApplyDamage(IEnumerable<Enemy> enemies)
{
    foreach (Enemy enemy in enemies)
    {
        enemy.Damage(10);
    }
}

Enumeration through an abstract type like this can cause extra allocations depending on the implementation and how the code is written.

ZLinq explains that even when AsValueEnumerable() is used on IEnumerable<T>, it may be able to reduce allocations if the actual object is an array or List<T>.

https://github.com/Cysharp/ZLinq#unity

private void ApplyDamage(IEnumerable<Enemy> enemies)
{
    foreach (Enemy enemy in enemies.AsValueEnumerable())
    {
        enemy.Damage(10);
    }
}

However, this is not universal.
The optimizations explicitly described in the README generally assume that the actual object is an array, List<T>, or a similar supported collection.
When going through an abstract type such as IReadOnlyList<T>, the behavior can depend on the static type, the actual object, and the ZLinq version.
In hot paths, either make the concrete type clear, such as List<T>, an array, or a Native Collection, or always confirm GC Alloc in a Player build.

Things to avoid even with ZLinq

Even when using ZLinq, code like this still needs care:

var list = _enemies
    .AsValueEnumerable()
    .Where(static x => x.IsAlive)
    .ToList();

The Where chain may avoid allocations, but ToList() still creates a List.

In other words, ZLinq is:

A way to make LINQ-like processing closer to zero-allocation

It is not:

A way to erase all collection creation from the result

ZLinq's ValueEnumerable also cannot be passed everywhere in the same way as a regular IEnumerable<T>.
If an existing API requires IEnumerable<T>, if you want to store the query result in a field, or if you need to use it across await or yield, you will eventually need to choose something like ToArray(), ToList(), or ToArrayPool().
At that point, allocation and lifetime management become relevant again.

If you need a List result every frame, it is often safer to allocate the List ahead of time and reuse it.

private readonly List<Enemy> _aliveEnemies = new();

private void CollectAliveEnemies(IReadOnlyList<Enemy> enemies)
{
    _aliveEnemies.Clear();

    for (int i = 0; i < enemies.Count; i++)
    {
        Enemy enemy = enemies[i];

        if (enemy.IsAlive)
        {
            _aliveEnemies.Add(enemy);
        }
    }
}

This is not fancy, but it is very strong in large-scale Unity development.

Unity's official documentation also introduces the pattern of keeping and reusing a List instead of creating a new one every frame.

https://docs.unity3d.com/2022.3/Documentation/Manual/performance-garbage-collection-best-practices.html

ZLinq also provides APIs such as CopyTo(List<T>) for copying results into an existing destination.
CopyTo(List<T>) clears the destination List before filling it, so be careful if you want to preserve the existing contents.

https://github.com/Cysharp/ZLinq#additional-operators

That said, until everyone on the team understands the behavior, Clear() + Add() is often easier to review for hot-path result collection.

Reusable Lists are effective for reducing GC Alloc, but Clear() usually keeps the internal array capacity.
If a List grows extremely large only at peak moments, consider destroying or shrinking it at scene transitions or loading boundaries.
Also, if you let another system keep a reference to a reusable List, the next Clear() will change its contents.
When passing such Lists to events, async code, or UI binding, define ownership and lifetime clearly.

Watch out for closures

With both LINQ and ZLinq, lambdas can create closures when they capture variables from outside the lambda.

private void UpdateTargets(float range)
{
    foreach (Enemy enemy in _enemies
        .AsValueEnumerable()
        .Where(x => x.DistanceToPlayer < range))
    {
        enemy.SetTarget();
    }
}

Here, range is a variable outside the lambda.
Even when using ZLinq, this kind of capture may cause the compiler to generate a closure object or delegate.
In other words, even if the ZLinq enumeration itself is close to zero-allocation, the lambda can still cause GC Alloc.

Unity's documentation also recommends minimizing closures and anonymous methods in performance-sensitive code, especially in code that runs every frame.

https://docs.unity3d.com/2022.3/Documentation/Manual/performance-garbage-collection-best-practices.html

When no capture is needed, use a static lambda.

foreach (Enemy enemy in _enemies
    .AsValueEnumerable()
    .Where(static x => x.IsAlive))
{
    enemy.Tick();
}

Adding static prevents the lambda from capturing variables outside itself.

float range = 10;

// This captures range, so it cannot be static.
// .Where(static x => x.DistanceToPlayer < range)

In hot paths, either shape the code so that static lambdas can be used, or just write a for loop.

Be careful with Drop-in Generator

ZLinq also has a Drop-in Generator that redirects regular LINQ calls toward ZLinq.

It is convenient, but in large projects, applying it broadly from the beginning is risky.

The ZLinq README explains that Drop-in Generator uses a Source Generator to generate extension methods for each type, and that these extension methods take priority over regular LINQ.
It also explains that, when using Drop-in Generator in Unity, the minimum Unity version is 2022.3.12f1 because of C# Incremental Source Generator support.

https://github.com/Cysharp/ZLinq#drop-in-replacement

https://github.com/Cysharp/ZLinq#unity

Since this article assumes Unity 6.0, the version requirement is usually not a problem. But if you apply it to the whole project at once, the following issues can happen:

It becomes harder to understand the difference from regular LINQ
It becomes harder to tell where ZLinq is being used
It spreads before the whole team understands the behavior
API boundaries that take IEnumerable<T> become harder to reason about
The impact of dependency updates becomes broader

At first, I prefer writing AsValueEnumerable() explicitly.
That way, code review makes it clear that the code is intentionally using ZLinq.

When installing ZLinq through tools such as NuGetForUnity, it is safer to pin the versions of ZLinq itself and Drop-in Generator.
In team development, if dependency versions differ between developers, the assumptions used during review and benchmarking can also differ.

If you use Drop-in Generator, asmdef and namespace boundaries should also be part of the team rules.
Make it clear in which assemblies ZLinq should take priority over regular LINQ, and avoid accidentally applying it to third-party code or shared libraries.
Some places may also change return types or available APIs compared with System.Linq, so keep migration PRs small and check both profiler results and code diffs step by step.

Installing ZLinq in Unity

When using ZLinq in Unity, the README describes a flow where the main ZLinq package is installed through NuGetForUnity or a similar tool, while Unity-specific features are referenced through the ZLinq.Unity package via a Git URL.
The Unity package adds support for GameObject and Transform hierarchy traversal, among other things.

https://github.com/Cysharp/ZLinq#unity

When referencing a package through a Git URL, specify a tag or commit hash when possible, and manage both Packages/manifest.json and packages-lock.json as a team.
If only the NuGet-side ZLinq package is pinned while ZLinq.Unity or ZLinq.DropInGenerator is floating, behavior may differ subtly between developers or CI environments.

For example, you can traverse a Transform hierarchy.
The following code is intended as a startup or verification example. It is not meant to be moved directly into Update().

using UnityEngine;
using ZLinq;

public sealed class TransformSearchSample : MonoBehaviour
{
    [SerializeField] private Transform _root;

    private void Start()
    {
        foreach (Transform child in _root
            .Descendants()
            .Where(static x => x.gameObject.activeSelf))
        {
            Debug.Log(child.name);
        }
    }
}

Transform hierarchy traversal is convenient, but if you run it every frame against a deep hierarchy, the traversal cost itself can become a problem.

ZLinq does not make repeated hierarchy searches free.
If the search target is large, consider caching or updating by differences.
Also, Debug.Log itself is expensive at runtime, so do not put it in hot paths.

Treat NativeArray / Job / Burst as a separate topic

ZLinq supports Unity types such as NativeArray and NativeSlice.
The README also explains that with Unity Collections 2.1.1 or later, more Native Collections are supported.

https://github.com/Cysharp/ZLinq#unity

However, in truly low-level hot paths that use Jobs or Burst, data layout, Native Collections, and Burst compilation constraints often matter more than preserving a LINQ-like style.

So this article focuses on how to handle LINQ and ZLinq in ordinary Unity runtime code, rather than on whether ZLinq can be used with NativeArray.

Do not expect too much from SIMD in Unity

ZLinq has SIMD-related features, but the README explains that SIMD is not used in Unity because Unity references .NET Standard 2.1.

https://github.com/Cysharp/ZLinq#unity

For Unity articles, it is less misleading to describe ZLinq as:

A way to keep a LINQ-like style while reducing GC Alloc and often improving runtime performance compared with regular LINQ

rather than:

A magic SIMD-based speedup tool

However, if you are aiming for maximum performance, that is a different discussion.
The ZLinq README also explains that if you want the best possible performance, you should write the code inline.
For hot paths, measure ZLinq and for loops with real data.

Be careful about code size with IL2CPP / AOT

In large production titles, you need to check not only Mono execution in the Editor, but also IL2CPP builds.

ZLinq uses structs and generics heavily.
This can be beneficial for reducing GC Alloc and improving runtime performance, but depending on how it is used, it may affect generated IL2CPP code size, build time, and binary size.

Unity's IL2CPP has generic sharing to reduce code size, but value-type generics may be less shareable in some cases.

https://unity.com/blog/engine-platform/il2cpp-internals-generic-sharing-implementation

So when introducing ZLinq, it is safer to first apply it explicitly to the code that actually has a problem, instead of immediately applying Drop-in Generator to the whole project.
Check the following:

GC Alloc in the Editor
Profiler results in a Development Build
IL2CPP build time
Player size
Runtime performance on the target platform

ZLinq is useful, but the wider the introduction scope becomes, the more you need to check its impact on the build output.

Minimum profiling conditions

This article repeatedly says "check it with the Profiler", but it is important not to decide based only on Editor results.
Especially in production titles that use IL2CPP, GC Alloc and CPU time in the Mono Editor are not enough for the final decision.

At minimum, separate the following checks:

Use the Editor Profiler first to find where GC Alloc occurs
Check the target platform Player with a Development Build
If using IL2CPP, check CPU time, GC Alloc, Player size, and build time in an IL2CPP build
Deep Profile is useful, but it has large overhead, so do not use it blindly for final numeric judgment
Compare regular LINQ, ZLinq, and for loops with the same data size and call count
When introducing Drop-in Generator, compare profiler results, Player size, and build time before and after the change, ideally per PR

Also, even when GC Alloc becomes 0, CPU cost does not disappear.
Sorting with OrderBy, Transform hierarchy traversal, distance calculation, virtual calls, cache misses, and other costs remain.
ZLinq is a powerful option for reducing GC Alloc, but in hot paths, CPU time must be checked as well.

Suggested team rules

In large-scale development, rules matter more than individual discipline.

For example, the following rules are easy to review.

Places where LINQ is acceptable

Editor extensions
Importers
Build scripts
Debug code
Test code
One-time conversion at startup
Temporary processing during loading

Runtime areas that require confirmation

Update
LateUpdate
FixedUpdate
Per-frame UI updates
Updates for many enemies, bullets, effects, and similar objects
Scroll list rebuilding
Input handling
Camera control
State machines that run every frame

If LINQ or ZLinq is used in these areas, the author should be able to explain during review why it is acceptable.

Places where ZLinq is worth considering

Code that is not per-frame but is still called frequently
Code where filtering or transformation should remain readable
Code that enumerates results immediately without materializing a List
Existing codebases full of LINQ that need gradual GC reduction
Search code shared between Editor and Runtime

Places where for loops should be preferred

Truly hot code
Code called thousands of times per frame
Code that needs early break
Code that only needs the minimum, maximum, or first matching item
Code that reuses result Lists
Code strongly tied to Job / Burst / Native Collections

Code review checklist

In code review, it is more practical to ask the following questions than to reject every use of LINQ mechanically.

var result = source.Where(...).Select(...).ToList();

When you see code like this, check:

Is it called every frame?
Is the number of items large?
Is ToList() or ToArray() really necessary?
Is a closure being created?
Is OrderBy really necessary?
Is it sorting only to call FirstOrDefault?
Can the result List be reused?
Can ZLinq preserve readability while reducing allocations?
Would a for loop be clearer?
Is the ownership and lifetime of a reused List clear?
Do we need to check the impact on IL2CPP builds?

OrderBy().FirstOrDefault() deserves particular attention.

var target = enemies
    .Where(static x => x.IsAlive)
    .OrderBy(static x => x.DistanceToPlayer)
    .FirstOrDefault();

If you only need the minimum value, you do not need to sort.

Enemy target = null;
float minDistance = float.MaxValue;

for (int i = 0; i < enemies.Count; i++)
{
    Enemy enemy = enemies[i];

    if (!enemy.IsAlive)
    {
        continue;
    }

    float distance = enemy.DistanceToPlayer;
    if (distance < minDistance)
    {
        target = enemy;
        minDistance = distance;
    }
}

In this kind of case, changing the algorithm is more effective than replacing LINQ with ZLinq.

Summary

LINQ and ZLinq are both useful.
But in large-scale Unity development, if you do not decide where they are allowed, convenient code can directly turn into runtime performance problems.

The policy in this article is simple:

Avoid LINQ in hot paths
Consider ZLinq for frequently called code where readability still matters
Be suspicious of ToList(), ToArray(), closures, and unnecessary OrderBy
Keep the ZLinq introduction scope controlled, and verify with the Profiler and IL2CPP builds

ZLinq is not a free pass to use LINQ carelessly.

It is best treated as:

An option for keeping LINQ readability while still thinking seriously about GC

A Deep Dive into C# Dispose: GC, Finalizers, and UnityEngine.Object Destruction

GameDevToolLab — Wed, 01 Jul 2026 03:00:23 +0000

Assumptions

This article assumes Unity 6.2 or later. However, the GC-related explanations are based on the official Unity 6.2 documentation available at the time of writing. Future Unity versions may change implementation details or documentation wording.

The goal of this article is to avoid mixing up the lifetime-management mechanisms used by C# and Unity:

C# Dispose
GC
finalizers
UnityEngine.Object
Addressables
NativeContainer

In Unity 6.2, Incremental GC is enabled by default. On the other hand, System.GC.Collect() is treated as a full blocking collection, while UnityEngine.Scripting.GarbageCollector.CollectIncremental() is the Unity-side API for incremental collection.

In this article, we will separate the following concepts:

the C# managed heap
external resources closed by IDisposable
native Unity engine objects
GPU resources
Addressables reference counts
native memory allocated by NativeContainer types

If you think of all of these as “the GC will clean them up eventually,” Unity will hurt you. Possibly with a chair.

Introduction

When writing C#, you often hear statements like these:

C# has GC, so I do not need to free memory manually.

But I still need to call IDisposable.

Unity Texture and Material instances should be closed with Object.Destroy, not Dispose, if I created and own those runtime instances.

C# also has ~ClassName(), so can I just clean things up there?

With the right assumptions, each of these statements is true.

The confusing part is that several different lifetime-management systems are being discussed at once.

This article looks at Dispose not as a generic “cleanup method,” but as a way to express ownership. We will also cover why finalizers are not enough, why UnityEngine.Object uses Destroy, and why GC.Collect() is not a magic memory-cleanup button.

The short version is this:

Dispose is not magic for deleting memory.

Dispose is a contract for explicitly closing a lifetime that the GC cannot understand on its own.

Unity’s Destroy is a different mechanism. It tells the Unity engine to destroy an object managed by the engine-side object system.

“When references disappear, the object is destroyed” is not quite right

A common explanation of C# GC is:

Objects with no references are collected by the GC.

As a rough explanation, that is fine.

But C# GC is not reference counting. It does not count the number of references to each object and immediately destroy the object when the count reaches zero.

Roughly speaking, the GC checks whether an object is reachable from GC Roots.

GC Roots include references on the stacks of running threads, static fields, CPU register references, GC handles, and runtime-internal references related to finalization. These are representative examples, and the exact details depend on the runtime environment.

The GC traces the object graph from those roots. Objects that can be reached are considered alive. Objects that cannot be reached are candidates for collection.

For example, consider this cyclic reference:

public sealed class Node
{
    public Node Other;
}

void CreateCycle()
{
    var a = new Node();
    var b = new Node();

    a.Other = b;
    b.Other = a;
}

a and b refer to each other.

In a reference-counting system, this kind of cycle can be a problem because the reference count never reaches zero.

But if neither a nor b is reachable from GC Roots, the GC can consider both objects collectible.

In C#, what matters is not “how many references exist,” but “whether the object is reachable from the live world.”

Do not explain Unity GC exactly like CoreCLR GC

If you search for C# or .NET GC, you will often find explanations about generational GC, Gen0 / Gen1 / Gen2, compaction, and LOH. Those topics are important for CoreCLR, but importing that model directly into Unity can be misleading.

Unity documentation explains that both Mono and IL2CPP use Boehm GC. In this article, terms like finalizer queue and finalizer thread are used as a general C#/.NET mental model. The exact implementation in Unity depends on the backend.

In real Unity projects, managed heap behavior is only one part of the picture. You also need to think about Unity engine native memory, assets, GPU resources, Addressables reference counts, and NativeContainer allocations.

C# finalizers are not called when references disappear

C# has this syntax:

public sealed class Sample
{
    ~Sample()
    {
        // finalizer
        // In real code, do not call Unity APIs or access other managed objects here.
    }
}

This ~Sample() is a finalizer.

It may look like a cleanup method that runs as soon as the object becomes unnecessary, but that is not how it works.

The rough flow is:

1. Normal references to the object disappear.
2. Nothing happens immediately.
3. A GC occurs.
4. The GC determines that the object is unreachable.
5. The object becomes a finalization target.
6. The finalizer runs later.
7. The object memory may be reclaimed by a later GC.

More precisely, objects with finalizers are registered for finalization when they are created. When the GC later finds them unreachable, they become eligible for finalizer execution.

The important point is:

A finalizer is not called at the moment references disappear.

Also, even when a GC happens, the finalizer body is not necessarily executed right there inside that GC.

You cannot control when a finalizer runs. It is also generally unsafe to touch other managed objects or Unity APIs from a finalizer. Having a finalizer can also make GC handling more expensive, and the actual memory for the object may only be reclaimed by a later GC.

A finalizer is not normal cleanup logic.

It is a last-resort safety net.

Files and sockets should be closed with Dispose. NativeContainers should be closed with Dispose. Runtime Texture and Material instances that you own should be closed with Destroy. These should not be left to finalizers.

Why Dispose exists

This is where Dispose comes in.

IDisposable is a very small interface:

public interface IDisposable
{
    void Dispose();
}

There is no magic here.

Implementing IDisposable does not make the GC call it immediately. It also does not automatically dispose every field.

Dispose is just a method.

It matters because it expresses this contract:

This object owns a resource that the GC cannot fully handle.

Please explicitly close it when you are done.

For example, here is a simple logger class:

public sealed class FileLogger : IDisposable
{
    private readonly StreamWriter _writer;

    public FileLogger(string path)
    {
        _writer = new StreamWriter(path);
    }

    public void Log(string message)
    {
        _writer.WriteLine(message);
    }

    public void Dispose()
    {
        _writer.Dispose();
    }
}

FileLogger does not directly call an OS file handle API, but it owns a StreamWriter, and StreamWriter is IDisposable. So it is natural for FileLogger to be IDisposable too.

using (var logger = new FileLogger("log.txt"))
{
    logger.Log("start");
}

With using, Dispose is called when the scope exits. Conceptually, it is close to a try/finally.

In C# 8 or later, you can also write:

using var logger = new FileLogger("log.txt");
logger.Log("start");

But using var does not dispose the object immediately after the declaration line. It disposes the object when the variable goes out of scope. If you use it at the beginning of a long method, the lifetime may be longer than you expect. If you want a narrower lifetime, use the traditional using (...) { } block.

The key point is this:

using is not GC.

using does not make the GC run earlier. It is syntax for reliably calling Dispose.

GC checks reachability. Dispose closes a semantic lifetime. They are not the same thing.

Dispose means ending ownership, not deleting memory

You typically need Dispose in the following cases.

Owning an unmanaged resource directly

For example, you might hold a pointer or handle allocated through a native API.

The following code is a minimal example for explanation. If Dispose() is not called, this code leaks native memory. In production code, it is safer to wrap direct IntPtr ownership with something like SafeHandle whenever possible.

public sealed class NativeBuffer : IDisposable
{
    private IntPtr _ptr;

    public NativeBuffer(int size)
    {
        _ptr = Marshal.AllocHGlobal(size);
    }

    public void Dispose()
    {
        if (_ptr == IntPtr.Zero)
            return;

        Marshal.FreeHGlobal(_ptr);
        _ptr = IntPtr.Zero;
    }
}

The memory pointed to by _ptr is not on the C# managed heap.

The GC can track the lifetime of the NativeBuffer object itself. But it does not know how to free the memory behind _ptr.

Should it call Marshal.FreeHGlobal? Should it call some custom Release function from a native library? The GC cannot infer that.

That is why Dispose is needed.

Owning fields that are IDisposable

Even if your class does not directly own native resources, if it owns an IDisposable object internally, it is usually natural for your class to be IDisposable too.

public sealed class SaveDataWriter : IDisposable
{
    private readonly BinaryWriter _writer;

    public SaveDataWriter(string path)
    {
        var stream = File.Create(path);
        _writer = new BinaryWriter(stream);
    }

    public void Write(int value)
    {
        _writer.Write(value);
    }

    public void Dispose()
    {
        _writer.Dispose();
    }
}

In this example, BinaryWriter owns and closes the internal Stream, so Dispose() only calls _writer.Dispose().

If you create the BinaryWriter with leaveOpen: true, then the ownership of the Stream is separated, and you need to dispose the Stream elsewhere.

The point is not “dispose every field you have.”

The point is deciding who owns what.

Preventing use after disposal

Dispose does not delete the C# object itself. The reference can still remain after disposal.

writer.Dispose();
writer.Write("after dispose");

To prevent this kind of misuse, classes often keep a _disposed flag and throw ObjectDisposedException when methods are called after disposal.

This is not about deleting memory. It is about marking the object as no longer usable after its owned resources have been closed.

You do not always need the full Dispose Pattern

C# samples often show the full Dispose Pattern with a finalizer, GC.SuppressFinalize(this), and protected virtual Dispose(bool disposing).

That pattern is meaningful, but it is not a ritual you need to write every time.

If you have a sealed class that only disposes owned IDisposable fields, a simple Dispose() is often enough. You do not need a finalizer.

If you directly own an IntPtr or other unmanaged resource, you need to think more carefully. Prefer SafeHandle where possible. If you directly own an unmanaged resource without SafeHandle, you need some finalizer-like safety net for missed disposal. If the class is intended to be inherited, consider the protected virtual Dispose(bool disposing) shape.

The Dispose Pattern is a design choice based on what you own.

GC.Collect is not a magic “free memory now” button

When memory usage grows, it is tempting to write:

GC.Collect();

As a .NET API, GC.Collect() forces garbage collection. In Unity 6.2 documentation, System.GC.Collect() is described as a full blocking collection.

But the practical point is this:

Calling it does not guarantee that the amount of memory you expect will immediately go down.

First, objects still reachable from GC Roots are not collected.

private static byte[] _cache;

void Create()
{
    _cache = new byte[1024 * 1024 * 100];
    GC.Collect();
}

Here, _cache is still referenced from a static field, so the GC considers it alive.

Objects with finalizers may also not be fully cleaned up by a single GC.

Most importantly, GC.Collect() primarily targets the managed heap.

The following are not fixed by GC.Collect() alone:

deterministically closing files or sockets that were not disposed
disposing NativeArray<T> or other NativeContainers
destroying Texture2D or Material instances that you created and own
Unity engine native memory
GPU resources
Addressables reference counts

Depending on implementation, files and sockets may eventually be closed through finalizers or SafeHandle, but that timing is not deterministic. The owner should close them with using / Dispose.

Also, Unity’s normal automatic GC may split work across multiple frames through Incremental GC, but that is not the same thing as System.GC.Collect(). If you want to advance incremental collection explicitly, that is the Unity-side GarbageCollector.CollectIncremental() API.

If GarbageCollector.GCMode is set to Disabled, Unity documentation says that calling System.GC.Collect() does not start a collection.

So GC.Collect() is not a fix for lifetime-management bugs. Before calling it, check whether references remain, whether Dispose was missed, and whether Destroy was missed.

Why Unity makes this more complicated

In Unity, C# code often operates on native Unity engine objects.

Texture2D texture = new Texture2D(1024, 1024);

Texture2D looks like a C# object. But it inherits from UnityEngine.Object.

Objects like this are not just ordinary C# managed objects. Roughly speaking, they involve:

a C# wrapper
a native Unity engine object
sometimes GPU-side resources

The C# GC can basically track the C# managed object. Unity engine native memory and GPU resources are outside its direct responsibility.

So you should not expect the following code to free the native memory behind the texture:

Texture2D texture = new Texture2D(1024, 1024);
texture = null;
GC.Collect();

This removes one C# reference and tries to run GC on the managed heap. But the native Unity object and GPU resources behind Texture2D are not directly released by the GC.

If you created and own a runtime UnityEngine.Object instance, such as a new Texture2D, you usually close that lifetime with Object.Destroy.

Texture2D texture = new Texture2D(1024, 1024);

// When you are done with it
UnityEngine.Object.Destroy(texture);

But the important word here is ownership.

You should not destroy every UnityEngine.Object just because it inherits from UnityEngine.Object. Imported assets, shared assets loaded through Resources.Load, renderer.sharedMaterial, and Addressables asset results may be shared by other systems.

In Unity, destruction is not decided only by type.

It is decided by who created the object and who owns it.

UnityEngine.Object can become “kind of null”

If you have used Unity for a while, you have probably seen behavior like this:

UnityEngine.Object.Destroy(texture);

if (texture == null)
{
    UnityEngine.Debug.Log("null?");
}

Unity’s Object has special == behavior that is different from normal C# objects.

The C# reference can still exist, but the native Unity object behind it may already be destroyed, or scheduled for destruction and treated as invalid by Unity.

Unity can make that state appear as == null.

In plain C#, if a reference remains, it is not null. But with Unity, the C# wrapper points to a native object whose lifetime must also be considered.

It is often useful to think of UnityEngine.Object as:

a C# wrapper with a handle to a native Unity engine object.

Also note that Unity’s special null behavior depends on the overloaded == null. ReferenceEquals, is null, null-conditional operators, and comparisons under generic constraints may not behave like Unity’s == null check.

Why UnityEngine.Object uses Destroy instead of Dispose

A natural question is:

If Texture owns native resources, why is it not IDisposable? Why not use Dispose?

The reason is that Unity’s Object.Destroy is not just resource cleanup.

Destroying a GameObject affects Components, Transform hierarchy, scene management, events, lifecycle callbacks, and more. Destroying a Component removes it from a GameObject. For MonoBehaviour, OnDisable and OnDestroy may be involved.

Unity destruction is not just “close the external resource owned by this object.”

It is an operation that removes an object from Unity’s engine-side object graph.

Also, Destroy usually does not immediately destroy the object on the spot. In the normal case, the object is actually destroyed after the current Update loop and before rendering.

This is useful for maintaining engine consistency during game-loop processing.

Destroy is not C# resource cleanup.

It is a destruction request to the Unity engine.

In Unity, choose the cleanup method by ownership, not just type

It is dangerous to remember cleanup rules only by type.

“UnityEngine.Object means Destroy” is a helpful starting point, but in production code you need to ask:

Do I own this object?

Target	Basic policy
Plain C# object	Let GC handle it
C# object implementing `IDisposable`	`Dispose()`
`NativeArray<T>` and other NativeContainers	`Dispose()` or `Dispose(JobHandle)`
Runtime instance created with `new Texture2D`, `new Material`, or `new GameObject`	Owner calls `Object.Destroy()`
Material implicitly cloned by `renderer.material`	Usually tied to the Renderer lifetime. If you need to release it earlier than the Renderer, replace it, or keep ownership yourself, consider `Destroy()`
`renderer.sharedMaterial`, imported assets, shared asset references	Do not destroy casually
Shared asset loaded through `Resources.Load`	Do not destroy casually from the user side. Remove references and let it become a candidate for `Resources.UnloadUnusedAssets()` when appropriate
Asset from Addressables `LoadAssetAsync`	Release the corresponding handle or result with `Addressables.Release()`
Instance created by Addressables `InstantiateAsync`	Use `Addressables.ReleaseInstance(gameObject)` or `Addressables.ReleaseInstance(handle)`
Instance created by manually instantiating a Prefab loaded through Addressables	Treat instance `Destroy()` and load-handle `Release()` separately. Keep the load handle alive until all instances are destroyed
Temporary RenderTexture from `RenderTexture.GetTemporary`	`RenderTexture.ReleaseTemporary()`

Destroy, Dispose, and Release all close lifetimes, but they close different kinds of lifetimes.

Mixing them up is how memory bugs get their villain origin story.

Disposing NativeArray used by Jobs

Unity.Collections NativeContainer types such as NativeArray<T> implement IDisposable.

For synchronous code that does not involve Jobs, the owner disposes it:

var array = new Unity.Collections.NativeArray<int>(
    1024,
    Unity.Collections.Allocator.Persistent);

try
{
    // Synchronous usage
}
finally
{
    if (array.IsCreated)
        array.Dispose();
}

If a Job is using the NativeArray, do not call Dispose() while the Job may still be accessing it. Either dispose it after handle.Complete(), or if the NativeContainer supports it, use Dispose(JobHandle) to make disposal depend on Job completion.

var handle = job.Schedule();
var disposeHandle = array.Dispose(handle);
disposeHandle.Complete();

This example uses Allocator.Persistent because the point is to show that ownership must be explicitly closed.

How Resources.UnloadUnusedAssets fits in

Unity also has Resources.UnloadUnusedAssets().

It is a heavy operation for unloading unused assets and their corresponding Unity-side resources. It can be useful at large loading boundaries or scene transitions.

But it should not be used as a substitute for normal ownership management.

First, if unwanted references remain, the asset may not be considered unused. Static fields, event subscriptions, caches, and ScriptableObject references can keep assets alive.

At the same time, Resources.UnloadUnusedAssets() does not use exactly the same reachability rules as the C# GC. Unity 6.2 API documentation explains that Unity checks things like the GameObject hierarchy and static variables, but not the script execution stack.

So an asset referenced only by a temporary local variable is not something you should assume is always protected from UnloadUnusedAssets().

A safer mental model is:

Dynamically created UnityEngine.Object: decide the owner and call Destroy
Addressables result: use Release / ReleaseInstance depending on how it was acquired
NativeContainer: Dispose
Temporary RenderTexture: ReleaseTemporary
Large loading boundary: consider UnloadUnusedAssets if needed
Managed heap issue: inspect references and GC allocations

Common misconceptions in real Unity projects

Setting a variable to null destroys the object

_texture = null;

This only removes one C# reference. If other references remain, the object is not collectible by GC.

For UnityEngine.Object types, removing the C# reference does not destroy the native Unity object. If you dynamically created and own a Texture or Material, decide the owner and call Destroy.

Dispose deletes the C# object

Dispose closes owned external resources. It does not delete the C# object immediately.

The reference still exists after Dispose, so use a _disposed flag or throw ObjectDisposedException if you need to prevent reuse.

Destroy means instant total disappearance

Destroy tells Unity to destroy the object, but in many cases destruction is not completed immediately on the spot.

If you keep touching the object in the same frame after calling Destroy, you may access an object that has already been scheduled for destruction. It is safer to treat a destroyed object as unusable immediately after calling Destroy.

GC.Collect also cleans up native memory

GC.Collect() primarily works on the managed heap.

Unity native memory, GPU resources, Addressables reference counts, and NativeContainer allocations have their own lifetime-management mechanisms.

When memory does not go down in Unity, first ask:

Who owns this thing, and where is that ownership closed?

Summary

The most important thing about Dispose is not to mix it up with GC.

GC checks whether managed objects are reachable from GC Roots. C# ~ClassName() is not deterministic destruction; it is a finalizer. Dispose is a contract for explicitly closing a lifetime the GC cannot understand.

Unity adds another layer with UnityEngine.Object. But you should not memorize “all UnityEngine.Object types must be destroyed.” Instead, ask whether you created and own the runtime instance. Shared assets, Addressables asset results, and renderer.sharedMaterial should not be casually destroyed by user code.

In practice:

Plain C# object: let GC handle it
IDisposable: close it with Dispose / using
NativeContainer: Dispose, or after Job completion / with Dispose(JobHandle)
Runtime UnityEngine.Object instance you created and own: Object.Destroy
Addressables: LoadAssetAsync uses Release, InstantiateAsync uses ReleaseInstance
Temporary RenderTexture: ReleaseTemporary
Large loading boundary: consider Resources.UnloadUnusedAssets() when appropriate

GC.Collect() does not fix lifetime-management bugs. GC manages the managed heap. Unity native memory, GPU resources, Addressables reference counts, and NativeContainer allocations each have their own lifetime rules.

Also, UnloadUnusedAssets() does not use the exact same reachability model as the C# GC. Assets reachable from Unity-side structures such as scene hierarchy or static variables are not treated as unused, but references that only exist on the script execution stack are not necessarily protected.

Dispose is a contract for closing ownership.

Destroy is a request to destroy Unity engine objects.

Keep those two separate, and a lot of Unity memory-management weirdness becomes much easier to reason about.

References

Token-Saving Techniques for Using AI Efficiently in Unity Projects

GameDevToolLab — Tue, 30 Jun 2026 08:13:21 +0000

Introduction

Using AI coding agents in a Unity project that is under development or already in production can significantly speed up investigation, implementation, and review.

At the same time, the larger the project gets, the more likely you are to run into problems like these:

The agent reads unrelated directories.
It tries to inspect generated files such as Library/ or Temp/.
It reads huge Scene / Prefab / ScriptableObject YAML files in full.
It consumes tokens by reading Addressables outputs or large logs.
You have to repeat the same project explanation in every chat.
You write too much in AGENTS.md / CLAUDE.md, and the agent starts following it less reliably.

The important part of using AI effectively is not just choosing a powerful model.

It is designing what the AI should read, and what it should not read.

This article focuses on Unity projects and summarizes practical ways to reduce token usage when using AI agents. At the end, I also include copy-paste friendly AGENTS.md and CLAUDE.md templates that can be adapted for both Unity and UE5 projects.

I Recommend Writing AGENTS.md / CLAUDE.md in English

The samples in this article write AGENTS.md and CLAUDE.md in English.

There are four main reasons.

First, most codebases are already centered around English. Class names, method names, file names, API names, error messages, and CLI commands are usually English. When instructions are also written in English, they naturally map to the names in the code.

Second, English rules are easier to reuse across multiple AI agents such as Codex, Claude Code, Gemini CLI, and Cursor. Japanese instructions also work, but English is usually safer for machine-facing team rules.

Third, English instructions are often easier to keep short. A rule like Do not edit generated files. is short and clear compared to a polite sentence in Japanese.

Fourth, it may slightly reduce context size in some cases. This does not mean English always produces dramatically fewer tokens than Japanese. It depends on the model, tokenizer, and how the text is written. Still, for short machine-facing rules, English tends to be compact and makes it easier to remove unnecessary explanation.

That said, switching to English alone will not magically reduce token usage. The bigger wins come from reducing duplication, clearly excluding directories, and avoiding full reads of large files.

So you do not need to write everything in English. Human-facing notes, internal terms, and background context can be written in Japanese or whatever language your team uses.

My recommendation is:

Write short rules that the AI must follow in English, and write supplemental explanation for humans in your team's preferred language.

However, if the team cannot confidently review English rules, forcing everything into English is risky. In practice, it is often best to keep AI-facing rules short and English, while adding human-facing background and exceptions in the language the team can maintain.

First Principle: Instruction Files Are Not Enforcement

AGENTS.md and CLAUDE.md are useful, but there is one misunderstanding to clear up first.

These files are context for AI agents.
They are not hard enforcement settings.

For example, even if you write:

Do not inspect Library/

there is no guarantee that the AI will never read Library/.

Of course, writing it is still much better than not writing it. It guides the agent's first moves and reduces unnecessary reads. But it is closer to a request or working policy than a hard rule.

If you need stronger guarantees, do not rely on instruction files alone. Combine them with layers such as:

.gitignore
.sembleignore
Claude Code's claudeMdExcludes
Claude Code hooks
Codex sandbox / approval / config
CI / lint / tests
Keeping generated files out of Git in the first place

The first line of defense for token saving is .gitignore.
Unity's Library/ and Temp/, and Unreal's Intermediate/ and Saved/, should usually not be tracked by Git.

AI agents may still be able to read untracked files on the local disk, so .gitignore is not a complete blocker. But it is still very important because it keeps generated files out of search targets, indexes, and diffs.

Do Not Let AI Read Everything

The worst thing you can do in a large project is to ask the agent something vague like this:

Please look at this Unity project and fix the problem.

That is like asking a human, "Read every file in this company and improve something."
The AI will try to be diligent and search broadly, which often means reading unrelated files.

A better request narrows the search scope from the beginning:

Investigate only the input validation in the login screen.
First, use Semble to find related files, then report the candidate files and why they matter.
After that, read only the minimum necessary files.

The key is to specify the investigation target and search process upfront.

Clarify things like:

Which feature is involved?
Which directories should be inspected?
Which directories should not be inspected?
What search method should be used first?
Is it allowed to modify files immediately?
Should the agent report its findings before making changes?

Just making these explicit can greatly reduce unnecessary reading.

Files That Consume Tokens Easily in Unity Projects

Unity projects contain many things that are heavy for AI agents to inspect.

Common examples include:

Target	Problem
`Library/`	Contains a huge amount of generated data.
`Temp/`	Temporary files with low investigation value.
`obj/`	C# build outputs.
`Logs/`	Can be large and repetitive.
`.csproj` / `.sln`	Usually generated by Unity. Read only when needed; do not edit directly.
Scenes / Prefabs	YAML can become very large.
ScriptableObjects	Can become large depending on data size.
Addressables catalogs / bundles	Heavy as investigation targets.
Generated files under StreamingAssets	Often contains binaries or generated data.
Large CSV / JSON / YAML files	Full reads quickly consume tokens.

On the other hand, the places the agent should usually inspect first are often predictable.

Target	Reason
`Assets/Scripts/`	Main gameplay/runtime logic.
`Assets/Editor/`	Custom Unity Editor extensions.
`Assets/Plugins/<CompanyName>/`	Company-owned runtime/editor code.
`Packages/manifest.json`	Package dependencies.
`ProjectSettings/`	Unity project settings. Useful to read, but changes must be handled carefully.
`*.asmdef`	Assembly boundaries and dependencies.
`Assets/AddressableAssetsData/`	Addressables settings.

Depending on Unity and Addressables versions, AddressableAssetsData can also contain generated files. Avoid full reads of large .bin files or catalogs; prefer extraction.

Start with Semble Search

In a large codebase, even using grep or rg and then reading several files can consume a lot of tokens.

Local semantic code search can help. In this article, I use Semble as the example.

More information about Semble and related case studies is included in the References section at the end. If Semble is new to you, you may want to skim those links first.

Semble is a code search library for AI agents. It can search code snippets using natural language queries and return relevant snippets instead of entire files. It can be used through MCP, CLI, or instructions in AGENTS.md.

Its official documentation shows token reduction compared with grep + read. There is also a Japanese Zenn article that measures token usage reduction when using semble with Claude Code.

These numbers depend heavily on the repository, index targets, search queries, and how the AI agent reads results. In this article, I treat Semble as one practical way to implement search-first workflows, not as a guarantee of a fixed reduction rate.

Also, Semble is not magic. If .gitignore or .sembleignore is not configured and generated files are indexed, the search results themselves can become noisy.

Semble also has limitations:

Bad queries return irrelevant results.
Generated files and huge data files can pollute the index.
You still need to inspect source files for final confirmation.
For exact API names or identifiers, rg may be faster and more accurate.

A practical split is:

Search by meaning: Semble
Search exact strings: rg / grep
Inspect huge files: extraction scripts
Final confirmation: read only the necessary original files

A useful AGENTS.md rule is:

## Search policy

Use Semble first for semantic code search when available and suitable.
Use rg/grep only when exact string matching is needed or Semble results are insufficient.
Do not scan the entire repository without explaining why.

Write the Folder Structure in Advance

Letting the AI infer the project structure every time is wasteful.

Write a minimal folder map in AGENTS.md.

## Project layout

- `Assets/Scripts/`
  - Runtime gameplay code.
- `Assets/Editor/`
  - Unity Editor extensions.
- `Assets/Plugins/CompanyName/`
  - Company-owned runtime/editor packages.
- `Assets/Scripts/Generated/`
  - Generated code. Do not edit directly.
- `Assets/AddressableAssetsData/`
  - Addressables settings. Avoid generated binary files.
- `Packages/`
  - Unity package manifest and local packages.
- `ProjectSettings/`
  - Unity project settings.

This is enough in many cases.
You do not need to document every directory.

The important part is that the AI can quickly tell where to start and what to avoid.

What to Put in AGENTS.md / CLAUDE.md

AGENTS.md and CLAUDE.md are not full specifications.
They are work guides for AI agents.

The useful scope is roughly:

Project overview
Technologies used
Important directories
Directories to avoid
Search policy
Generated file policy
Coding rules
Work process
Verification methods
Things not to change

Be careful not to overfill them with:

General explanations of the tech stack
Long design philosophy
Outdated specifications
Rarely used procedures
Detailed rules for one specific feature
Large explanations duplicated from README

Files that the AI reads in every session should stay short.

Claude Code documentation also explains that long CLAUDE.md files consume context and may reduce instruction-following reliability. Codex also has a limit on the combined size of AGENTS.md instructions.

As a rough guide, keep the root AGENTS.md around 100 to 200 lines, and move detailed procedures to separate files.

## Playbooks

Read these only when relevant:

- `docs/ai/playbooks/addressables.md`
  - Addressables investigation workflow.
- `docs/ai/playbooks/prefab-audit.md`
  - Scene/Prefab extraction workflow.
- `docs/ai/playbooks/release-check.md`
  - Release verification checklist.

However, Claude Code's @path import expands the imported content into context when it is loaded.

Splitting files does not automatically reduce tokens.

The purpose of splitting is to improve maintainability and create a path for the agent to read details only when they are relevant.

Differences Between Codex and Claude Code

Codex primarily uses AGENTS.md.
You can combine global instructions in ~/.codex/AGENTS.md with repository-local AGENTS.md files.

Claude Code's standard file name is CLAUDE.md.
If you already use AGENTS.md, you can import it from CLAUDE.md.

@AGENTS.md

## Claude Code specific rules

Use plan mode before large refactors.
Do not run Unity Editor unless explicitly requested.

This lets you centralize shared rules in AGENTS.md and keep only Claude Code-specific rules in CLAUDE.md.

One important caveat: Codex does not have a standard local file equivalent to CLAUDE.local.md.
A file named .codex-local.md is not automatically read.

Codex instruction discovery basically loads at most one instruction file per directory. The search order is AGENTS.override.md, then AGENTS.md, then names registered in project_doc_fallback_filenames. If AGENTS.md exists in the same directory, adding .codex-local.md as a fallback name does not make it behave like CLAUDE.local.md.

Also, as its name implies, AGENTS.override.md is an override. If you place it at the repository root, it may replace the team-shared AGENTS.md at the same level rather than supplementing it.

If you want personal rules for Codex, consider this order:

Write cross-repository personal rules in ~/.codex/AGENTS.md.
Use CODEX_HOME if you want to separate working profiles.
Use repository-local AGENTS.override.md only when the team has agreed on its meaning.
For temporary personal notes, manually ask the agent to read them at the start of the session.

It is safer to separate team-shared rules from personal notes. In Claude Code, CLAUDE.local.md is suitable for that purpose.

# personal AI agent notes
CLAUDE.local.md

If you use a custom name with Codex, treat it as a fallback candidate for directories without AGENTS.md, not as an append-only supplement to an existing AGENTS.md.

Extract Large Data Instead of Reading It Directly

If you let the AI read full Scenes, Prefabs, ScriptableObjects, logs, CSV, JSON, or YAML files, tokens disappear fast.

In these cases, it is often more efficient to make the AI write an extraction script instead of reading the file directly.

For example, when investigating Prefabs, do not read the entire YAML. Use an Editor script to output only the needed information.

Target	Extracted information
Prefab / Scene	GameObject hierarchy, component list, missing references.
ScriptableObject	Type name, key fields, referenced GUIDs.
Addressables	Address, label, group, path.
Logs	Error lines, N surrounding lines, duplicate counts.
CSV / JSON	Row count, keys, problematic entries, a few samples.

A useful AGENTS.md rule is:

## Large file policy

Do not read large YAML, JSON, CSV, log, scene, prefab, or ScriptableObject files directly.

For large files:
1. Write a small read-only script to extract only relevant fields.
2. Show the script before running it when it may touch Unity/Unreal assets.
3. Do not call SaveAssets, ForceReserializeAssets, asset delete/move APIs, or import-triggering operations unless explicitly requested.
4. Write extraction output to a dedicated gitignored report directory such as `.ai-tmp/ai-extract/`.
5. Show the extraction summary.
6. Read the original file only if the summary is insufficient.

The point is to avoid saying "read everything" from the start.

Make the AI narrow the data first. For logs, that means error types and a few surrounding lines. For Prefabs, that means GameObject paths, component names, and missing references.

For extraction output, avoid Unity's Temp/. Use a project-controlled gitignored directory such as .ai-tmp/ai-extract/. Temp/ is managed by the Unity Editor and is not a stable workspace for AI-generated reports.

When running Unity Editor scripts, assume read-only by default. Investigation scripts should generally not call AssetDatabase.SaveAssets(), ForceReserializeAssets(), asset delete/move APIs, or anything that triggers reimport. It is also useful to confirm that the Git working tree is clean before running such scripts.

Do Not Edit Generated Code Directly

API clients, master data definitions, localization definitions, Protocol Buffers, and C# outputs from internal tools are overwritten the next time they are generated.

## Generated files

Do not edit generated files directly.

Examples:
- `Assets/Scripts/Generated/`
- `Assets/Plugins/CompanyName/Generated/`
- `*.g.cs`
- `*.generated.cs`

If a generated file has a bug, fix the generator or template instead.

Just stating "fix the source generator instead" prevents many accidents.

Ask for Findings Before Changes

If you let the AI immediately modify files, it may touch unrelated code.

For larger tasks, make the process explicit:

## Work process

For non-trivial tasks:

1. Search relevant files first.
2. Report the files you plan to inspect.
3. Summarize the current behavior.
4. Propose the smallest safe change.
5. Modify only the necessary files.
6. Run the relevant verification command if available.

This allows a human to check the search scope.

In Unity, one feature can involve Runtime code, Editor tools, Addressables, ScriptableObjects, and Prefabs at the same time.
Asking the agent to report where it will look first reduces both unnecessary reading and incorrect edits.

Keep Changes Small

AI agents sometimes try to clean up extra things while solving a task.
That can be a problem in production projects.

Unrequested refactoring increases review cost.

## Change policy

Keep changes minimal.
Do not perform broad refactors unless explicitly requested.
Do not change public APIs unless required.
Do not reformat unrelated files.

Making "minimal changes" a rule keeps reviews manageable.

Write Verification Commands

If you ask the AI to "verify it" without defining how, the result will be vague.

Write project-specific verification methods.

## Verification

Prefer the smallest relevant verification.

Examples:
- Run EditMode tests from Unity Test Runner.
- Run PlayMode tests only when the change affects runtime behavior.
- Run Unity batchmode tests when available.
- Run .NET tool tests with `dotnet test` only for standalone tool projects.

If verification cannot be run, explain what should be checked manually.

If your project runs Unity Test Runner from the command line, include the actual command.

Unity batchmode example:

`Unity.exe -runTests -batchmode -projectPath . -testPlatform EditMode -testResults TestResults.xml`

Unity Test Framework examples for -runTests do not include -quit. -quit is often used in normal batchmode build commands, but it is safer not to mix it into test execution examples.

Unity CLI execution differs by environment. Use your team's actual command rather than treating article snippets as universal. Unity.exe is a Windows example; real commands depend on Unity Hub installation paths, OS, CI image, licensing, and -logFile handling.

Keep Personal Notes Out of Git

Separate team-shared AGENTS.md / CLAUDE.md files from machine-local personal notes.

In Claude Code, you can use CLAUDE.local.md and add it to .gitignore. It is a good place for local paths, personal commands, and temporary investigation notes.

Codex does not have a standard local supplement equivalent to CLAUDE.local.md. For personal Codex rules, prefer ~/.codex/AGENTS.md. Use AGENTS.override.md only when the team agrees on its meaning, because it may replace the same-level AGENTS.md rather than supplement it.

CLAUDE.local.md

Unreal Engine Notes

The same idea applies to UE5.
Separate what the AI should inspect from what it should avoid.

Prefer reading:

Source/
Config/
Plugins/*/Source/
*.Build.cs
*.Target.cs
*.uproject
*.uplugin

Avoid by default:

Intermediate/
Saved/
DerivedDataCache/
Binaries/

.uasset and .umap files under Content/ are not useful as raw text.
For Blueprint or Map investigation, extract the necessary information through Asset Registry, Editor Utility, Python scripts, or C++ helper commands before giving it to the AI.

UE contains even more binary assets than Unity, so it is especially important to think in terms of extracting information through the editor rather than asking the AI to read files.

The Chat Prompt Still Matters

Even with a good AGENTS.md, vague chat instructions reduce the effect.

Investigate the NullReferenceException that appears during Unity startup.
First, use Semble to find likely initialization code.
Do not read the full log. Check only the error and 5 surrounding lines.
Before changing anything, report possible causes and the files you plan to modify.

Good requests include the target feature, first search method, things not to read, and a request to report before modifying.
The important part is not prompt elegance. It is scoping the investigation.

Minimum Checklist

Before publishing or introducing this workflow to a project, check at least:

.gitignore
directories to read and avoid
generated file policy
large-file extraction policy
verification methods
separation of personal notes

Even this alone can greatly reduce wasteful AI reads.

Summary

Reducing token usage in AI agents is not just about choosing the right model.

The important part is designing what information the AI reads.

Keep generated files out of version control with .gitignore.
Write search policies in AGENTS.md / CLAUDE.md.
Understand that instruction files are context, not enforcement.
Use search tools such as Semble first.
Extract summaries from huge files instead of reading them directly.
Ask for findings before changes.
Keep changes small.
Define verification methods.

Unity projects contain many files that are expensive for AI agents to read.
That is exactly why not letting the AI read everything is so effective.

Finally, here are general-purpose templates for Unity and UE5.

The following section intentionally repeats some of the article in a copy-paste friendly form. It is kept as an independent template so it can be pasted into real projects.

Do not use everything blindly. Delete what you do not need. Unity-specific and Unreal-specific sections are placed at the bottom of AGENTS.md; for a Unity-only project, delete the Unreal section, and for an Unreal-only project, delete the Unity section.

Copy-Paste AGENTS.md

# AGENTS.md

## Language
- Prefer short English for machine-facing rules.
- Use a language the team can review and maintain.
- Reply to users in the language they use.

## Project overview
- This is a game development project using Unity and/or Unreal Engine.
- Prioritize small, safe, reviewable changes.
- Do not perform broad refactors unless explicitly requested.

## Core rules
- Do not read the entire repository by default.
- Search first, inspect only relevant files, then propose the smallest safe change.
- Instruction files are guidance, not enforcement.
- Use `.gitignore`, tool settings, hooks, tests, and CI for hard guarantees.

## Search policy
- Use Semble first for semantic code search when available and suitable.
- Use `rg` / `grep` for exact symbols, APIs, errors, and paths.
- Do not scan the entire repository without explaining why.

## Workflow for non-trivial changes
1. Search for relevant files.
2. Report candidate files and why they matter.
3. Inspect only necessary files.
4. Summarize current behavior.
5. Propose the smallest safe change.

## Avoid by default
Do not inspect these unless explicitly requested:
- `.git/`, `.vs/`, `.idea/`, `.gradle/`
- `node_modules/`, `dist/`, `build/`, `Build/`, `Builds/`
- `logs/`, `MemoryCaptures/`
- `.ai-tmp/`, except report files created for the current task

## Large files
Do not read large YAML, JSON, CSV, logs, scenes, prefabs, ScriptableObjects, `.uasset`, or `.umap` files directly.
- Create a small read-only extraction script or command first.
- Show the script before running it when it may touch assets.
- Do not save, reserialize, delete, move, reimport, or modify assets unless explicitly requested.
- Write reports to `.ai-tmp/ai-extract/`.
- Read only the generated summary first.
- Read raw files only if the summary is insufficient.

## Generated files
- Do not edit generated files directly.
- Examples: `**/Generated/**`, `*.g.cs`, `*.generated.cs`, generated API clients, data loaders, localization files, protobuf/message files.
- If generated output has a bug, fix the generator, template, or source data instead.

## Coding policy
- Follow existing style.
- Keep changes minimal.
- Do not reformat unrelated files.
- Do not change public APIs unless required.
- Do not introduce new packages without approval.
- Prefer readable code over clever code.

## Verification
- Run the smallest relevant verification when possible.
- Use the project's actual commands rather than generic examples.
- If verification cannot be run, explain why and what should be checked manually.

## Reporting
When making changes, report:
- files inspected
- files changed
- reason for each change
- verification performed
- verification not performed
- remaining risks

## Platform-specific sections
Unity and Unreal Engine rules are intentionally placed at the end.
Delete the section that does not apply to your project.

## Unity policy
Prefer reading:
- `Assets/Scripts/`
- `Assets/Editor/`
- `Assets/Plugins/<CompanyName>/`
  - Treat third-party plugins and purchased assets as read-only unless explicitly requested.
- `Packages/manifest.json`, `Packages/packages-lock.json`
- `ProjectSettings/`
  - Read when relevant, but change only with explicit intent and explain the diff.
- `Assets/**/*.asmdef`

Avoid unless explicitly requested:
- `Library/`, `Temp/`, `temp/`, `obj/`, `Obj/`, `Logs/`, `UserSettings/`
- `*.csproj`, `*.sln`
  - Usually generated by Unity. Read only when needed; do not edit directly.
- `Assets/StreamingAssets/aa/`
- large generated Addressables files, bundles, catalogs, and binary outputs

For serialized assets, extract path, GUID, GameObject path, component type, serialized fields, missing references, and Addressables address/group/labels.
Verification examples: EditMode tests, PlayMode tests, Unity batchmode tests without adding `-quit` to `-runTests`, project-specific validation scripts.

## Unreal Engine policy
Prefer reading:
- `Source/`
- `Config/`
- `Plugins/*/Source/`
- `*.Build.cs`, `*.Target.cs`, `*.uproject`, `*.uplugin`

Avoid unless explicitly requested:
- `Binaries/`, `Intermediate/`, `Saved/`, `DerivedDataCache/`

Do not treat `.uasset` or `.umap` files as readable source.
For Blueprint, Map, Asset, or Content analysis, extract metadata through Unreal Editor, Asset Registry, Editor Utility, Python, or C++ helper scripts.
Verification examples: build the affected target, run relevant automation tests, run project-specific validation scripts.

Copy-Paste CLAUDE.md

@AGENTS.md

# CLAUDE.md

## Claude Code specific rules
- Use plan mode before large refactors or multi-file changes.
- Do not run Unity Editor or Unreal Editor unless explicitly requested.
- If an editor command is necessary, explain the command and expected impact first.
- Prefer Semble or narrow searches over broad Read/Grep/Glob operations.
- For large files or asset investigation, use read-only extraction and read the summary first.

## Context management
- Keep this file short.
- Put long task-specific procedures in separate files and read them only when relevant.
- `@path` imports help maintainability, but imported content is still loaded into context.
- Do not import large files unless they are needed in every session.

## Personal notes
- Use `CLAUDE.local.md` for personal, machine-specific notes.
- Do not commit `CLAUDE.local.md`.

References

OpenAI Codex: Custom instructions with AGENTS.md https://developers.openai.com/codex/guides/agents-md
Claude Code: Memory / CLAUDE.md https://code.claude.com/docs/en/memory
Claude Code: Hooks reference https://code.claude.com/docs/en/hooks
Unity Docs: Recommended ignore configuration for Unity projects https://docs.unity.com/unity-version-control/ignore-files
Unity Docs: Running tests from the command line https://docs.unity.cn/Packages/com.unity.test-framework%401.4/manual/reference-command-line.html
Unreal Engine Documentation: Directory Structure https://dev.epicgames.com/documentation/en-us/unreal-engine/unreal-engine-directory-structure
Semble official documentation https://minish.ai/packages/semble/introduction/
Semble GitHub https://github.com/MinishLab/semble
Zenn: Claude Code のトークン削減を実測した — semble 93%・cacheRead 1800倍の内訳 https://zenn.dev/pepabo/articles/claude-code-token-reduction-measured

Creating a Small Helper Class to Safely Handle CancellationTokenSource Cancel and Dispose

GameDevToolLab — Fri, 26 Jun 2026 02:21:58 +0000

Introduction

When writing async code in Unity, you often end up working with CancellationToken for loading, networking, Addressables, screen transitions, timeouts, and so on.

The object you usually create for that is CancellationTokenSource, but it is surprisingly easy to handle it incorrectly.

For example:

private CancellationTokenSource? _cts;

private void CancelAndDispose()
{
    _cts?.Cancel();
    _cts?.Dispose();
}

At first glance, this looks fine. However, the disposed CancellationTokenSource remains in the field.

If CancelAndDispose() is called again, the second Cancel() may throw an ObjectDisposedException.

Also, when using CancelAfter() or CreateLinkedTokenSource(), disposing the CTS after use becomes even more important.

This article explains the difference between Cancel() and Dispose(), then introduces a small helper class that safely handles CancelAfter() and CreateLinkedTokenSource() as well.

Cancel and Dispose Are Different Things

First, Cancel() and Dispose() do different jobs.

Cancel() sends a cancellation request to code that has received a CancellationToken.

var cts = new CancellationTokenSource();

var task = LoadAsync(cts.Token);

cts.Cancel();

This is only a cancellation request.

Calling Cancel() does not forcibly stop a running operation. The callee must either check the CancellationToken or pass it to an API that supports cancellation.

On the other hand, Dispose() is not a cancellation request.

cts.Dispose();

Dispose() releases resources held internally by CancellationTokenSource.

In short:

Cancel()
    Sends a cancellation request

Dispose()
    Releases resources

Calling Cancel() does not automatically call Dispose(). Depending on the situation, you may need both.

cts.Cancel();
cts.Dispose();

However, that does not mean you should blindly write those two lines everywhere.

Disposed Does Not Mean Null

Let's look at this code again.

private CancellationTokenSource? _cts;

private void CancelAndDispose()
{
    _cts?.Cancel();
    _cts?.Dispose();
}

Dispose() does not set _cts to null.

That means the following call order can be dangerous:

CancelAndDispose();
CancelAndDispose();

Even after _cts.Dispose() is called the first time, _cts is still not null.

So the second call still executes _cts?.Cancel().

CancellationTokenSource.Cancel() may throw ObjectDisposedException if the target CTS has already been disposed.

In Unity, cleanup code can be called through multiple paths.

public void Close()
{
    CancelAndDispose();
}

private void OnDestroy()
{
    CancelAndDispose();
}

You could catch and ignore ObjectDisposedException, but that is not the real fix.

The real problem is that a disposed CTS remains in the field.

Instead of hiding the exception, it is safer to structure the code so that a disposed CTS is never touched again.

Dispose Is Important with CancelAfter and CreateLinkedTokenSource

CancelAfter() schedules a cancellation request after a specified delay.

using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(10));

await LoadAsync(cts.Token);

This is commonly used for timeouts.

CancelAfter() is convenient, but the CTS needs internal machinery to cancel itself later. Because of that, it is important to dispose the CTS when you are done with it.

The same applies to CreateLinkedTokenSource().

For example, you may want to combine multiple cancellation conditions, such as "the MonoBehaviour was destroyed" and "the operation timed out".

using var timeoutCts = new CancellationTokenSource();
timeoutCts.CancelAfter(TimeSpan.FromSeconds(10));

using var linkedCts = CancellationTokenSource.CreateLinkedTokenSource(
    destroyCancellationToken,
    timeoutCts.Token);

await LoadAsync(linkedCts.Token);

In this example, both timeoutCts and linkedCts should be disposed.

CreateLinkedTokenSource() creates a new CancellationTokenSource that becomes canceled when any of the provided tokens is canceled.

So this newly created CTS is also something you should dispose after use.

If you leave a CTS created with CancelAfter() or CreateLinkedTokenSource() undisposed, the release of internal resources and registrations may be delayed.

Instead of saying this always causes an immediate memory leak, it is more accurate to say that resources owned by the finished CTS may remain alive longer than necessary.

Managing CTS Fields Directly Gets Messy

If everything is contained inside a single method, using is often enough.

using var cts = new CancellationTokenSource();
cts.CancelAfter(TimeSpan.FromSeconds(10));

await LoadAsync(cts.Token);

However, in game code, you often want to keep a CTS in a field.

For example, when restarting a load operation, you may want to cancel the previous load first.

private CancellationTokenSource? _loadCts;

public async void Reload()
{
    _loadCts?.Cancel();
    _loadCts?.Dispose();

    _loadCts = new CancellationTokenSource();
    var token = _loadCts.Token;

    try
    {
        await LoadAsync(token);
    }
    catch (OperationCanceledException) when (token.IsCancellationRequested)
    {
        // Cancellation is treated as a normal flow.
    }
}

This code mixes together cancellation of the previous CTS, disposal, creation of a new CTS, timeout setup, linked token creation, and protection against double cleanup.

Writing that every time is annoying.

And annoying code tends to get copied incorrectly sooner or later.

So instead, we can put ownership of the CancellationTokenSource into a dedicated helper class.

Creating a Helper Class

The policy for this class is:

- Return only CancellationToken to the caller
- Let the helper class create, replace, cancel, and dispose CTS instances
- Do not leave a disposed CTS in the field
- End the old CTS when Renew / RenewOwned is called
- Dispose CTS instances created by CancelAfter and CreateLinkedTokenSource
- By default, do not throw ObjectDisposedException / AggregateException from Cancel()
- If onCancelException is specified, report the exception there before swallowing it
- Allow a strict mode that propagates Cancel exceptions when needed

Cancel() may throw AggregateException if a registered cancellation callback throws.

If an old CTS throws during Cancel() inside RenewOwned(), the caller sees RenewOwned() as failed.

However, depending on the implementation order, the new CTS may already have become active internally.

For this reason, this helper class does not propagate exceptions caused by Cancel() by default. If onCancelException is specified, it reports the exception there.

If onCancelException is not specified, the exception is simply swallowed. In a real project, it is recommended to pass a logging function such as Debug.LogException.

Implementation

#nullable enable

using System;
using System.Threading;

public sealed class CancellationTokenSourceOwner : IDisposable
{
    private readonly object _gate = new();
    private readonly bool _throwOnCancelException;
    private readonly Action<Exception>? _onCancelException;

    private CancellationTokenSource? _cts;
    private bool _disposed;

    public CancellationTokenSourceOwner(
        bool throwOnCancelException = false,
        Action<Exception>? onCancelException = null)
    {
        _throwOnCancelException = throwOnCancelException;
        _onCancelException = onCancelException;
    }

    public CancellationToken Renew()
    {
        return RenewOwned(new CancellationTokenSource());
    }

    public CancellationToken RenewAfter(TimeSpan delay)
    {
        var next = new CancellationTokenSource();

        try
        {
            next.CancelAfter(delay);
        }
        catch
        {
            next.Dispose();
            throw;
        }

        return RenewOwned(next);
    }

    public CancellationToken RenewLinked(params CancellationToken[] tokens)
    {
        var next = CancellationTokenSource.CreateLinkedTokenSource(tokens);
        return RenewOwned(next);
    }

    public CancellationToken RenewLinkedAfter(
        TimeSpan delay,
        params CancellationToken[] tokens)
    {
        var next = CancellationTokenSource.CreateLinkedTokenSource(tokens);

        try
        {
            next.CancelAfter(delay);
        }
        catch
        {
            next.Dispose();
            throw;
        }

        return RenewOwned(next);
    }

    /// <summary>
    /// Takes ownership of next.
    /// After calling this method, the caller must not dispose next.
    /// </summary>
    public CancellationToken RenewOwned(CancellationTokenSource next)
    {
        if (next == null)
            throw new ArgumentNullException(nameof(next));

        CancellationTokenSource? old;
        CancellationToken token;

        lock (_gate)
        {
            if (_disposed)
            {
                next.Dispose();
                throw new ObjectDisposedException(nameof(CancellationTokenSourceOwner));
            }

            token = next.Token;
            old = _cts;
            _cts = next;
        }

        CancelAndDisposeCore(old);

        return token;
    }

    public void CancelAndDispose()
    {
        CancellationTokenSource? old;

        lock (_gate)
        {
            old = _cts;
            _cts = null;
        }

        CancelAndDisposeCore(old);
    }

    public void Dispose()
    {
        CancellationTokenSource? old;

        lock (_gate)
        {
            if (_disposed)
                return;

            _disposed = true;
            old = _cts;
            _cts = null;
        }

        CancelAndDisposeCore(old);
    }

    private void CancelAndDisposeCore(CancellationTokenSource? cts)
    {
        if (cts == null)
            return;

        try
        {
            try
            {
                cts.Cancel();
            }
            catch (Exception ex) when (ShouldHandleCancelException(ex))
            {
                ReportCancelException(ex);
            }
        }
        finally
        {
            cts.Dispose();
        }
    }

    private bool ShouldHandleCancelException(Exception ex)
    {
        if (_throwOnCancelException)
            return false;

        return ex is ObjectDisposedException || ex is AggregateException;
    }

    private void ReportCancelException(Exception ex)
    {
        var handler = _onCancelException;
        if (handler == null)
            return;

        try
        {
            handler(ex);
        }
        catch
        {
            // Do not let logging failures break cleanup.
        }
    }
}

Implementation Notes

RenewOwned Transfers Ownership

The actual CTS replacement logic is centralized in RenewOwned().

Renew(), RenewAfter(), RenewLinked(), and RenewLinkedAfter() are convenience methods for different use cases, and they all call RenewOwned() internally.

var next = new CancellationTokenSource();
next.CancelAfter(TimeSpan.FromSeconds(5));

var token = _owner.RenewOwned(next);

At this point, ownership of next moves to _owner.

The caller must not call next.Dispose() after passing it to RenewOwned().

Change State Inside the Lock, Cancel Outside the Lock

In RenewOwned(), the class removes the old CTS and activates the new CTS inside the lock.

However, Cancel() itself is called outside the lock.

The reason is that Cancel() may execute registered cancellation callbacks synchronously.

If the owner lock is held while calling Cancel(), the design can become complicated depending on what those callbacks do.

The order is:

RenewOwned:
    Activate the new CTS inside the lock
    Exit the lock
    Cancel and dispose the old CTS

CancelAndDispose / Dispose:
    Remove the active CTS inside the lock
    Exit the lock
    Cancel and dispose the removed CTS

There is one important caveat.

RenewOwned() activates the new CTS before canceling the old CTS.

That means this class does not support reentrant usage where a cancellation callback from the old token calls Renew(), CancelAndDispose(), or Dispose() on the same owner.

Cancellation callbacks should avoid manipulating the owner itself and should be kept to minimal notifications or logging.

Cancel Exceptions Are Not Propagated by Default

CancelAndDisposeCore() always calls Dispose() even if Cancel() throws.

try
{
    try
    {
        cts.Cancel();
    }
    catch (Exception ex) when (ShouldHandleCancelException(ex))
    {
        ReportCancelException(ex);
    }
}
finally
{
    cts.Dispose();
}

By default, ObjectDisposedException and AggregateException caused by Cancel() are not propagated.

If onCancelException is specified, the exception is reported there and then swallowed.

In Unity, this lets you avoid throwing from cleanup code while still keeping a log.

private readonly CancellationTokenSourceOwner _loadToken = new CancellationTokenSourceOwner(
    onCancelException: ex => Debug.LogException(ex));

If ObjectDisposedException is reported, check whether the CTS passed to RenewOwned(next) was disposed by the caller, or whether the same CTS is being shared outside the owner.

If you want to treat cancellation callback exceptions as bugs, enable strict mode.

private readonly CancellationTokenSourceOwner _loadToken = new CancellationTokenSourceOwner(
    throwOnCancelException: true);

In strict mode, RenewOwned() may throw even though the new CTS has already become active internally.

For Unity loading and screen transition code, passing a logging function to onCancelException and using the non-throwing default is usually easier to handle.

Usage

The basic method is Renew().

private readonly CancellationTokenSourceOwner _loadToken = new CancellationTokenSourceOwner(
    onCancelException: ex => Debug.LogException(ex));

public async void Reload()
{
    var token = _loadToken.Renew();

    try
    {
        await LoadAsync(token);
    }
    catch (OperationCanceledException) when (token.IsCancellationRequested)
    {
        // Cancellation is treated as a normal flow.
    }
    catch (Exception ex)
    {
        Debug.LogException(ex);
    }
}

Calling Renew() creates a new CTS. If an old CTS exists, it is canceled and then disposed.

Use RenewAfter() when you need a timeout.

var token = _loadToken.RenewAfter(TimeSpan.FromSeconds(10));

Use RenewLinked() when you need to link with an external token.

var token = _loadToken.RenewLinked(destroyCancellationToken);

Use RenewLinkedAfter() when you need both a timeout and an external token.

var token = _loadToken.RenewLinkedAfter(
    TimeSpan.FromSeconds(10),
    destroyCancellationToken);

This cancels when either the MonoBehaviour is destroyed or 10 seconds pass.

Internally, this uses both CreateLinkedTokenSource() and CancelAfter(), but disposal of the CTS remains inside CancellationTokenSourceOwner.

For cleanup:

public void Close()
{
    _loadToken.CancelAndDispose();
}

private void OnDestroy()
{
    _loadToken.Dispose();
}

CancelAndDispose() removes the active CTS first, then calls Cancel() and Dispose().

So even if it is called multiple times, the second and later calls have no active CTS to touch.

Dispose() ends the lifetime of the owner itself. Calling Renew() after Dispose() throws ObjectDisposedException.

Use CancelAndDispose() when you want to stop the current operation but keep the owner reusable. Use Dispose() when the owner itself is done.

Combining with destroyCancellationToken

Unity 2022.2 and later provides MonoBehaviour.destroyCancellationToken.

destroyCancellationToken is managed by Unity, so you do not dispose it yourself.

However, a linked CTS created by CreateLinkedTokenSource() is created by your code, so it must be disposed.

When using this helper class, the mental model becomes:

destroyCancellationToken
    Token managed by Unity
    Do not dispose it yourself

RenewLinked(destroyCancellationToken)
    Owner creates a linked CTS
    Owner disposes it

RenewLinkedAfter(timeout, destroyCancellationToken)
    Owner creates a linked CTS
    Owner sets CancelAfter
    Owner disposes it

Caveats

CancellationTokenSourceOwner is not a universal cancellation management system.

Use it with the following assumptions in mind.

Do Not Reenter the Owner from Cancellation Callbacks

This class does not support calling Renew(), CancelAndDispose(), or Dispose() on the same owner from a cancellation callback of the old token.

RenewOwned() activates the new CTS before canceling the old CTS.

If a callback from the old token manipulates the owner, it may affect the new CTS.

Renew / CancelAndDispose May Be Synchronously Expensive

Cancel() may run cancellation callbacks synchronously.

That means Renew(), CancelAndDispose(), and Dispose() may not return until callbacks of the old CTS have finished.

If you call these methods on the Unity main thread, heavy cancellation callbacks can cause frame drops.

The Old CTS Is Disposed Immediately After Cancel

This class disposes the old CTS immediately after calling Cancel().

For normal async / await code and APIs that accept CancellationToken, this is usually convenient.

However, it does not work well with code that touches token.WaitHandle after cancellation.

var token = _loadToken.Renew();

_loadToken.CancelAndDispose();

// Not recommended:
// The old CTS has already been disposed, so this design does not work well with WaitHandle.
var handle = token.WaitHandle;

If you pass tokens to old APIs or custom implementations that use WaitHandle, consider a design where the CTS is disposed only after the operation has fully completed.

Always Handle Exceptions from async void

Unity event handlers sometimes use async void.

However, exceptions escaping from async void are hard to handle, so it is safer to explicitly catch both OperationCanceledException and normal exceptions.

try
{
    await LoadAsync(token);
}
catch (OperationCanceledException) when (token.IsCancellationRequested)
{
    // Cancellation is normal flow.
}
catch (Exception ex)
{
    Debug.LogException(ex);
}

Outside Unity event handlers, prefer async Task when possible so the caller can await the operation.

Summary

CancellationTokenSource is not finished just because you called Cancel().

Cancel()
    Sends a cancellation request

Dispose()
    Releases resources

These are separate responsibilities.

Especially when using CancelAfter() or CreateLinkedTokenSource(), failing to dispose the CTS after use may delay the release of internal resources and registrations.

Also, when keeping CTS directly in fields, it is easy to leave a disposed CTS behind, call Cancel() on an already disposed CTS, or forget to dispose CTS instances created for timeouts or linked tokens.

Putting ownership of the CTS into a dedicated class makes the code easier to reason about.

The caller receives only a CancellationToken, while creation, cancellation, disposal, renewal, linked tokens, and timeouts are handled by the owner class.

If you create a CancellationTokenSource yourself, you are responsible for disposing it.
But instead of repeating that logic in every class, put ownership in one place.

With this structure, Unity loading and networking code becomes easier to handle safely.

Do We Still Need UniTask in the Unity 6 Era? Choosing Between Awaitable and UniTask

GameDevToolLab — Wed, 24 Jun 2026 17:00:32 +0000

Introduction

When writing asynchronous code in Unity, Coroutine and UniTask have long been the practical choices.

A major reason is that many Unity APIs must be called from the main thread.

If you simply use .NET Task and move work to a background thread, you can run into problems the moment you touch objects such as GameObject, Transform, or SceneManager.

UniTask has been a very convenient solution to this constraint.

await UniTask.SwitchToThreadPool();

// Heavy computation, JSON parsing, binary parsing, etc.
var result = HeavyWork();

await UniTask.SwitchToMainThread();

// Touch Unity APIs
gameObject.name = result.Name;

However, starting with Unity 2023.1, Unity introduced the standard Awaitable API.

In Unity 6, APIs such as Awaitable.NextFrameAsync(), Awaitable.WaitForSecondsAsync(), Awaitable.BackgroundThreadAsync(), and Awaitable.MainThreadAsync() are available.

In other words, Unity now provides a standard way to write a certain amount of async/await code.

So, in the Unity 6 era, do we still need UniTask?

This article is not a basic UniTask tutorial. Instead, it focuses on what changed with the arrival of Awaitable, and where UniTask still remains valuable.

Conclusion

Here is the conclusion first.

With the arrival of Awaitable, Unity is no longer in a world where "UniTask is the only realistic way to use async/await."

However, if you want to operate asynchronous workflows properly in an actual game application, UniTask is still very useful.

A rough breakdown looks like this:

Use case	Recommended choice
Waiting until the next frame	Awaitable is often enough
Waiting for a few seconds	Awaitable is often enough
Lightweight coroutine replacement	Awaitable is often enough
Library code where you want to avoid external dependencies	Returning Awaitable can be a good fit
Waiting for multiple async operations together	UniTask is stronger
Large-scale loading, networking, Addressables control	UniTask is stronger
Practical cancellation handling	UniTask is stronger
Fine-grained PlayerLoopTiming control	UniTask is stronger
Tracking leaked or forgotten async operations	UniTask is stronger

Very roughly:

Small async code: Awaitable
Application-wide async infrastructure: UniTask

That is the mental model I use.

What changed with Awaitable?

The biggest change is that Unity now supports code like this as a standard feature:

await Awaitable.BackgroundThreadAsync();

// Now on a ThreadPool thread
var result = HeavyWork();

await Awaitable.MainThreadAsync();

// Back on the Unity main thread
gameObject.name = result.Name;

This is a big deal.

Previously, even if you wanted to use async/await in Unity, using .NET Task directly often did not fit well with Unity's main-thread restrictions.

You can move work to a background thread with Task.Run.

var result = await Task.Run(() =>
{
    return HeavyWork();
});

However, touching Unity APIs inside that code is dangerous.

var result = await Task.Run(() =>
{
    // NG
    return transform.position;
});

Many Unity APIs are designed to be used from the main thread.

Because of that, you need a design that explicitly returns to the main thread before touching Unity APIs.

UniTask made this very natural.

await UniTask.SwitchToThreadPool();

var result = HeavyWork();

await UniTask.SwitchToMainThread();

ApplyResultToUnityObject(result);

Today, Unity's standard Awaitable API can express the same basic idea.

await Awaitable.BackgroundThreadAsync();

var result = HeavyWork();

await Awaitable.MainThreadAsync();

ApplyResultToUnityObject(result);

This means that introducing UniTask only to switch back to the main thread is less necessary than it used to be.

Task and Awaitable also differ in continuation timing

The arrival of Awaitable did not just add more APIs that can be used with async/await.

.NET Task and Unity's Awaitable also differ in how continuations are handled.

In Unity, a continuation from a Task called on the main thread can be posted to UnitySynchronizationContext, and may resume on the next Update tick.

On the other hand, Unity's Awaitable is designed to run continuations synchronously when the operation completes.

That means that when dealing with Unity-provided asynchronous operations, Awaitable is designed to avoid unnecessary one-frame delays more easily.

This does not mean "Awaitable is always faster."

But it does mean that Awaitable is designed around Unity's frame loop, while Task is a general-purpose .NET abstraction.

That distinction is worth keeping in mind.

await is not magic that automatically moves work to another thread

This is an easy misunderstanding.

Writing await does not automatically move the entire operation to a background thread.

await Awaitable.BackgroundThreadAsync();

This means that the following continuation resumes on a background thread.

Conversely:

await Awaitable.MainThreadAsync();

This means that the following continuation resumes on the Unity main thread.

So the following code is dangerous:

await Awaitable.BackgroundThreadAsync();

// NG: touching Unity APIs from a background thread
gameObject.name = "Loaded";

The correct pattern is to return to the main thread before touching Unity APIs.

await Awaitable.BackgroundThreadAsync();

var result = HeavyWork();

await Awaitable.MainThreadAsync();

gameObject.name = result.Name;

The same idea applies to UniTask.

await UniTask.SwitchToThreadPool();

var result = HeavyWork();

await UniTask.SwitchToMainThread();

gameObject.name = result.Name;

Awaitable does not remove Unity's main-thread restriction.

What changed is that Unity now provides standard APIs to work with that restriction.

Awaitable is very convenient as a coroutine replacement

Awaitable can replace many common coroutine patterns quite naturally.

Waiting until the next frame:

await Awaitable.NextFrameAsync();

Waiting for a fixed amount of time:

await Awaitable.WaitForSecondsAsync(1.0f);

Waiting for the FixedUpdate timing:

await Awaitable.FixedUpdateAsync();

Waiting until the end of the frame:

await Awaitable.EndOfFrameAsync();

For lightweight use cases, this is often enough.

For example, UI effects, simple waits, short samples, and small libraries that want to avoid external dependencies can often use Awaitable without bringing in UniTask.

private async Awaitable ShowMessageAsync(string message)
{
    label.text = message;
    await Awaitable.WaitForSecondsAsync(1.0f);
    label.text = "";
}

For this level of code, UniTask is not mandatory.

What Awaitable replaced, and what it did not

Awaitable did not erase all of UniTask's value.

However, some of UniTask's previous value became less unique.

For example:

Writing next-frame waits with async/await
Writing WaitForSeconds-like waits with async/await
Writing EndOfFrame-like waits with async/await
Returning to the main thread using Unity-standard APIs
Moving to a background thread using Unity-standard APIs

These can now be written fairly naturally with Awaitable.

On the other hand, UniTask still has strong value in areas such as:

WhenAll / WhenAny / WhenEach
Fine-grained PlayerLoopTiming control
Frame-based APIs such as DelayFrame
Unity-oriented CancellationToken workflows
UniTaskTracker
Integration with Addressables, DOTween, uGUI, and other surrounding libraries

So the value that became less unique is:

Making async/await usable in Unity at all

The value that remains is:

Making asynchronous workflows easier to operate across a full application

Once you separate these two ideas, the decision becomes much clearer.

So where is UniTask still strong?

If Awaitable can switch threads, does that mean UniTask lost its value?

Personally, I see it less as "UniTask lost value" and more as "UniTask's role shifted."

Previously, UniTask often served as:

The practical foundation for using async/await in Unity

After Awaitable, its role is closer to:

A practical foundation for operating larger asynchronous workflows in Unity

The difference becomes clear in the following areas.

UniTask strength 1: WhenAll / WhenAny / WhenEach are practical

In real loading code, a single async operation is rarely the whole story.

You often want to start multiple operations, such as loading master data, Addressables assets, textures, or network responses, and then wait for all of them.

var playerTask = LoadPlayerAsync();
var itemTask = LoadItemAsync();
var questTask = LoadQuestAsync();

await UniTask.WhenAll(playerTask, itemTask, questTask);

Receiving multiple results is also clean.

var (player, item, quest) = await UniTask.WhenAll(
    LoadPlayerAsync(),
    LoadItemAsync(),
    LoadQuestAsync()
);

This is very useful in practice.

If you await each operation one by one, they become sequential.

var player = await LoadPlayerAsync();
var item = await LoadItemAsync();
var quest = await LoadQuestAsync();

In this form, LoadItemAsync does not start until LoadPlayerAsync has finished.

If you start all operations first and then wait for them together, operations that can run concurrently will proceed concurrently.

var playerTask = LoadPlayerAsync();
var itemTask = LoadItemAsync();
var questTask = LoadQuestAsync();

var (player, item, quest) = await UniTask.WhenAll(
    playerTask,
    itemTask,
    questTask
);

In game loading code, this can directly affect loading time.

If you want to process results as they complete, WhenEach is also useful.

var tasks = new[]
{
    LoadMasterAsync("player"),
    LoadMasterAsync("item"),
    LoadMasterAsync("quest"),
};

await foreach (var result in UniTask.WhenEach(tasks))
{
    var master = result.GetResult();
    ApplyMaster(master);
}

WhenEach is useful when you want to apply results in completion order instead of waiting for everything first.

If you want to handle errors individually, you can inspect each result.

await foreach (var result in UniTask.WhenEach(tasks))
{
    if (result.IsFaulted)
    {
        Debug.LogException(result.Exception);
        continue;
    }

    ApplyMaster(result.GetResult());
}

This is where Awaitable's characteristics matter.

Awaitable instances are pooled internally, and you should not await the same Awaitable instance more than once.

Awaiting the same instance multiple times can lead to exceptions, deadlocks, or behavior close to undefined behavior.

Also, standard Awaitable does not provide the same level of composition APIs as UniTask's WhenAll, WhenAny, and WhenEach.

So Awaitable is convenient for lightweight coroutine replacement, but UniTask is more practical when you need to manage many loading operations or network requests together.

UniTask strength 2: Fine-grained PlayerLoopTiming control

In Unity async code, simply returning to the main thread is not always enough.

Sometimes you need to care about where in the PlayerLoop you resume.

For example:

Resume before Update
Resume after LateUpdate
Run at FixedUpdate timing
Run at an EndOfFrame-like timing

UniTask lets you specify PlayerLoopTiming.

await UniTask.Yield(PlayerLoopTiming.Update);
await UniTask.Yield(PlayerLoopTiming.LastPostLateUpdate);

You can also specify timing when switching back to the main thread.

await UniTask.SwitchToMainThread(PlayerLoopTiming.PreLateUpdate);

This can matter for code such as:

UI updates
Camera post-processing
Code that depends on Transform updates
Loading progress display
Screenshots at the end of the frame
Post-processing after Addressables or AsyncOperation completion

Awaitable has NextFrameAsync, FixedUpdateAsync, and EndOfFrameAsync.

However, it does not expose PlayerLoopTiming as finely as UniTask.

UniTask's PlayerLoopTiming includes many phases such as Initialization, EarlyUpdate, FixedUpdate, PreUpdate, Update, PreLateUpdate, PostLateUpdate, and LastPostLateUpdate.

So the practical distinction is:

If returning to the main thread is enough: Awaitable can be enough
If the exact PlayerLoop timing matters: UniTask is stronger

UniTask strength 3: Yield and NextFrame can be used intentionally

A subtle but important UniTask detail is the difference between Yield and NextFrame.

await UniTask.Yield();

and:

await UniTask.NextFrame();

do not mean exactly the same thing.

If your intent is "wait until the next frame" in the same sense as yield return null, then UniTask.NextFrame() usually expresses that intent more clearly.

await UniTask.NextFrame();

On the other hand, UniTask.Yield() resumes at the specified PlayerLoopTiming.

Depending on when it is called, it may resume within the same frame.

So if you casually use Yield as a replacement for yield return null, it can cause bugs in code that depends on frame boundaries.

This is easy to miss in basic tutorials.

In asynchronous code, it is not enough to say "wait."

Sometimes it matters when the continuation resumes.

UniTask strength 4: Cancellation is easier to operate in practice

In games, an async operation often outlives the object that started it.

For example:

The scene changed
The screen was closed
The prefab was destroyed
A network request was canceled
The player returned to the title screen during loading

If the async operation keeps running, it may later try to touch an object that has already been destroyed.

UniTask makes common Unity cancellation patterns easy to write.

private async UniTaskVoid Start()
{
    var token = this.GetCancellationTokenOnDestroy();

    try
    {
        await LoadAsync(token);
    }
    catch (OperationCanceledException)
    {
        // Cancellation caused by Destroy, screen transition, etc.
    }
}

private async UniTask LoadAsync(CancellationToken cancellationToken)
{
    await UniTask.Delay(1000, cancellationToken: cancellationToken);

    cancellationToken.ThrowIfCancellationRequested();

    // Touch Unity APIs
    label.text = "Loaded";
}

Awaitable APIs can also accept CancellationToken.

However, UniTask provides many practical patterns that fit Unity development very well.

In particular, GetCancellationTokenOnDestroy() makes it easy to tie the lifetime of an async operation to the lifetime of a MonoBehaviour.

UniTask strength 5: UniTaskTracker helps find forgotten operations

Asynchronous operations are easy to leave behind invisibly.

For example:

SomeAsync().Forget();

Forget() is convenient, but if used carelessly, the operation may continue running even after the screen has closed.

Loading, networking, polling, and UI effects can keep running and produce mysterious logs or exceptions later.

UniTask includes UniTaskTracker.

This is very useful in practice.

Async problems are not always about the speed of a single operation.

Often the real issue is:

An operation that should have ended is still running
An operation that should have been canceled is still active
The same async operation was started multiple times

Awaitable does not have an equivalent tracker.

This is another reason UniTask remains strong as an application-wide async foundation.

A common allocation trap around Progress

Even if you use UniTask, surrounding code can still allocate.

A typical example is Progress<T>.

var progress = new Progress<float>(x =>
{
    progressBar.value = x;
});

This is convenient, but if created frequently, it can become a source of allocations.

UniTask provides Progress.Create.

var progress = Progress.Create<float>(x =>
{
    progressBar.value = x;
});

For very high-frequency progress reporting, you can also implement IProgress<T> yourself and reuse the instance.

public sealed class ProgressBarReporter : IProgress<float>
{
    private readonly UnityEngine.UI.Slider slider;

    public ProgressBarReporter(UnityEngine.UI.Slider slider)
    {
        this.slider = slider;
    }

    public void Report(float value)
    {
        slider.value = value;
    }
}

var progress = new ProgressBarReporter(progressBar);
await LoadAsync(progress, cancellationToken);

When you see allocations while using UniTask, the cause may not be UniTask itself.

It may be Progress, lambdas, closures, LINQ, array allocations, or other surrounding code.

So it is important to look at the whole implementation, not just whether UniTask is being used.

Moving to the ThreadPool does not automatically make loading faster

This is another common misunderstanding.

await Awaitable.BackgroundThreadAsync();

or:

await UniTask.SwitchToThreadPool();

can move heavy work to a background thread.

However, Unity loading itself does not necessarily become fully background-threaded just because you moved your continuation.

For example, Addressables, AssetBundle loading, scene loading, texture creation, and mesh creation may still include main-thread work internally.

So you should not assume:

I moved to BackgroundThread, so all Unity loading no longer blocks the main thread.

Moving to a background thread is most effective for work that does not depend on Unity APIs.

For example:

JSON parsing
MessagePack parsing
Custom binary parsing
Encryption / decryption
Compression / decompression
Hash calculation
Large array processing
Pure computation such as pathfinding or scoring

On the other hand, creating UnityEngine.Object, touching Transform, or loading scenes still requires main-thread work at some point.

This boundary matters.

Also, if you target WebGL or web builds, be careful with designs that depend on ThreadPool.

The UniTask README explains that APIs such as UniTask.SwitchToThreadPool() and UniTask.RunOnThreadPool() do not work on WebGL and similar environments.

If web builds are part of your target, avoid depending too heavily on ThreadPool-based designs. Instead, consider splitting work across frames, using coroutine or PlayerLoop-based distribution, or checking the current state of Job System support for your target.

A safer pattern for using ThreadPool with Awaitable

When using Awaitable for background work, pay attention to which thread the method completes on.

For example, the following code needs caution:

private async Awaitable<ParsedData> ParseAsync(byte[] bytes)
{
    await Awaitable.BackgroundThreadAsync();

    var parsed = ParseBytes(bytes);

    return parsed;
}

This method does its work on a background thread and then completes there.

If the caller immediately touches Unity APIs after awaiting it, that can be dangerous.

var data = await ParseAsync(bytes);

// If ParseAsync completes on a background thread,
// touching Unity APIs here is dangerous.
gameObject.name = data.Name;

If the caller may touch Unity APIs after this method returns, a safer default is to return to the main thread before completing the method.

private async Awaitable<ParsedData> ParseAsync(
    byte[] bytes,
    bool continueOnMainThread = true)
{
    await Awaitable.BackgroundThreadAsync();

    var parsed = ParseBytes(bytes);

    if (continueOnMainThread)
    {
        await Awaitable.MainThreadAsync();
    }

    return parsed;
}

With this pattern, normal calls complete after returning to the main thread.

var data = await ParseAsync(bytes);

// ParseAsync has returned to the main thread before completion,
// so touching Unity APIs is easier to reason about.
gameObject.name = data.Name;

If you want to chain multiple heavy operations on a background thread, you can opt out explicitly.

var data = await ParseAsync(bytes, continueOnMainThread: false);

// If you want to touch Unity APIs here,
// explicitly return to the main thread.
await Awaitable.MainThreadAsync();

gameObject.name = data.Name;

The important point is to make the contract clear:

Which thread does this async method complete on?
Is it safe to touch Unity APIs after awaiting it?
How far does cancellation propagate?

Also, Unity does not necessarily stop background operations automatically when exiting Play Mode.

When using background work in the Editor, consider using Application.exitCancellationToken so the operation can be canceled when Play Mode ends.

Using RunOnThreadPool with UniTask

With UniTask, you can also write background execution that returns a result like this:

var parsed = await UniTask.RunOnThreadPool(() =>
{
    return ParseBytes(bytes);
});

ApplyToUnityObject(parsed);

The same warning applies here.

Do not touch Unity APIs inside ParseBytes.

var parsed = await UniTask.RunOnThreadPool(() =>
{
    // NG
    var position = transform.position;

    return ParseBytes(bytes);
});

Code running on the ThreadPool should be limited to pure work that does not depend on Unity APIs.

For library development, returning Awaitable can make sense

For application code, UniTask is still very useful.

However, for libraries or Unity Asset Store packages, you may want to avoid adding external dependencies.

If you can target Unity 6 or later, returning Awaitable can be a realistic choice.

public async Awaitable LoadAsync(CancellationToken cancellationToken)
{
    await Awaitable.NextFrameAsync(cancellationToken);

    // Work
}

If the application uses UniTask, it can adapt Awaitable as needed.

Library side: return Awaitable
Application side: convert or wrap it for UniTask-based operation

This keeps the library dependency-light while still allowing the application to use UniTask's operational features.

UniTask can handle Awaitable with AsUniTask(), so the two do not need to be treated as mutually exclusive.

Practical guideline

Here is a practical rule of thumb.

Case	Awaitable	UniTask
Small waiting logic	Good fit	Also possible
Lightweight coroutine replacement	Good fit	Also possible
Standard Unity-only implementation	Good fit	Adds external dependency
Library return type	Good fit	Requires users to depend on UniTask
Waiting for multiple loads together	Weak	Good fit
Managing many async operations	Weak	Good fit
Designing cancellation across systems	Possible	Good fit
Fine-grained PlayerLoopTiming control	Weak	Good fit
Finding forgotten async operations	Weak	Good fit
Considering WebGL / ThreadPool limitations	Be careful	Be careful

The important point is that Awaitable and UniTask are not enemies.

Awaitable is Unity's lightweight standard async API.

UniTask is a practical tool for managing larger async workflows in Unity applications.

Summary

Awaitable made asynchronous programming in Unity much more practical.

The biggest changes are that Unity now provides standard APIs for:

Waiting until the next frame
Waiting for seconds
Waiting for FixedUpdate
Waiting until EndOfFrame
Awaiting AsyncOperation
Switching to the main thread
Switching to a background thread

Because of this, simple coroutine replacements and small async workflows can often be written with Awaitable alone.

However, real game development rarely stops at single async operations.

You often need to handle:

Large-scale loading
Networking
Addressables
Cancellation
Screen transitions
Destroy-linked lifetimes
Exception handling
Progress reporting
PlayerLoopTiming control
Tracking forgotten operations

Once you consider these operational concerns, UniTask still has a strong reason to exist.

The conclusion is:

Awaitable made Unity-standard async/await much more realistic.
But if you need to operate asynchronous workflows in a real application, UniTask is still powerful.

In the Unity 6 era, UniTask is no longer just a coroutine replacement.

It is better understood as a foundation for organizing asynchronous workflows across an application.

References

Unity Manual: Introduction to asynchronous programming with Awaitable

https://docs.unity3d.com/6000.1/Documentation/Manual/async-awaitable-introduction.html
Unity Manual: Awaitable completion and continuation

https://docs.unity3d.com/6000.1/Documentation/Manual/async-awaitable-continuations.html
Unity Manual: Awaitable completion and continuation (Unity 6000.0)

https://docs.unity3d.com/6000.0/Documentation/Manual/async-awaitable-continuations.html
Unity Scripting API: Awaitable

https://docs.unity3d.com/6000.2/Documentation/ScriptReference/Awaitable.html
UniTask GitHub README

https://github.com/Cysharp/UniTask

Fixing Addressables Downloads That Keep Running After Cancellation

GameDevToolLab — Mon, 22 Jun 2026 13:16:20 +0000

Overview

When downloading a large number of remote assets with Unity Addressables, you can limit the number of concurrent network requests by setting MaxConcurrentWebRequests.

However, this only controls the number of concurrent requests.

For example, suppose you download 500 AssetBundles at once. Even if the number of concurrent requests is limited to 3, the remaining 497 requests are still added to Addressables' internal request queue.

If the user presses a cancel button in this state, the queued requests inside Addressables are not automatically removed.

Depending on your implementation, the flow can look like this:

Start downloading 500 files
↓
3 requests start immediately
497 requests are queued in Addressables' internal WebRequestQueue
↓
The user cancels
↓
The app-side await / CancellationToken is treated as canceled
↓
However, the internal Addressables queue remains
↓
Every time a request slot becomes available, the next queued request starts
↓
Even after canceling, the app still waits for a large number of failed requests

Even if you limit the number of concurrent downloads with MaxConcurrentWebRequests, canceling can still take a very long time when the total number of downloads is large.

This article introduces an approach where we directly modify the internal Addressables code so that both queued requests and active requests can be canceled.

Assumptions

This article uses Addressables 2.9.1 as the example.

However, the internal implementation of Addressables can change depending on the version.

So rather than copying the code in this article as-is, you should first check the following points in the version used by your project:

Where the queued web requests are stored
Where UnityWebRequest is started
Where completion is reported back to AssetBundleProvider

Then adjust the implementation to match the Addressables version used in your project.

Why submit all requests first?

If you only care about cancellation, the safest approach is to create your own queue on the app side and submit only a few requests to Addressables at a time.

Start only 3 downloads
↓
When one finishes, start the next one
↓
If canceled, do not submit the remaining requests

With this approach, cancellation is simple.

However, in an actual game, you often want to display UI like this:

Total download size: 1.2 GB
Remaining download size: 850 MB
Progress: 29%

By using AsyncOperationHandle.GetDownloadStatus() in Addressables, you can obtain the downloaded byte count and the total byte count.

Because of that, there are cases where you want to pass the entire download target set to Addressables at the beginning, so that the progress UI can be calculated accurately.

In other words, the desired behavior is:

Pass the full download target set to Addressables for progress UI
Limit concurrent downloads with MaxConcurrentWebRequests
Immediately discard queued requests when canceled
Stop active requests as well if possible

Why modify Addressables directly instead of using a custom provider?

Addressables also allows you to create custom providers.

However, based on my experience, the internal implementation of Addressables has changed significantly several times across version updates.

Because of that, when modifying behavior that deeply depends on Addressables internals, it can sometimes be easier to manage the change by embedding the Addressables package into the project and directly modifying the relevant code, rather than trying to wrap everything with a custom provider.

Of course, this is more of a practical workaround than an officially recommended extension method.

Directly modifying the package has several downsides:

You must check diffs whenever Addressables is updated
The modified package is more likely to be outside official support
The team needs to understand and share the modification details
Unity / Addressables updates may require reapplying or rewriting the changes

Even so, if canceling a large download causes the app to wait for hundreds of failed network requests, directly modifying the package can be worth it.

Making Addressables editable

Addressables installed through Package Manager is normally placed under Library/PackageCache.

Packages in this state are not meant to be edited directly.

If you want to edit Addressables, embed it into the project's Packages folder.

The official Unity workflow mainly has two options:

1. Use the Package Manager Scripting API Client.Embed
2. Manually copy the package from Library/PackageCache to the Packages folder

Method 1: Use Client.Embed

Unity provides the Client.Embed API to embed an installed package into the project.

By creating an Editor script like the following, you can embed Addressables from a menu item.

#if UNITY_EDITOR
using UnityEditor;
using UnityEditor.PackageManager;
using UnityEditor.PackageManager.Requests;
using UnityEngine;

public static class EmbedAddressablesPackageMenu
{
    private static EmbedRequest _request;

    [MenuItem("Tools/Addressables/Embed Addressables Package")]
    private static void EmbedAddressables()
    {
        if (_request != null && !_request.IsCompleted)
        {
            Debug.LogWarning("Addressables package embed is already running.");
            return;
        }

        _request = Client.Embed("com.unity.addressables");
        EditorApplication.update += WaitForEmbedRequest;
    }

    private static void WaitForEmbedRequest()
    {
        if (_request == null || !_request.IsCompleted)
            return;

        EditorApplication.update -= WaitForEmbedRequest;

        if (_request.Status == StatusCode.Success)
        {
            Debug.Log($"Embedded package: {_request.Result.packageId}");
        }
        else
        {
            Debug.LogError($"Failed to embed Addressables package: {_request.Error.message}");
        }

        _request = null;
    }
}
#endif

Client.Embed copies the target package into the Packages folder and makes it editable.

Method 2: Manually copy the package

If you want to do it manually, first install Addressables normally from Package Manager.

Then copy the Addressables folder under Library/PackageCache into the Packages folder.

Example:

Library/PackageCache/com.unity.addressables@8460f1c9c927
↓
Packages/com.unity.addressables

The important point is that the destination folder name should usually be com.unity.addressables.

Embedded packages under the Packages folder take precedence in Unity.

Because of that, even if Packages/manifest.json remains unchanged, the embedded package is used first.

{
  "dependencies": {
    "com.unity.addressables": "2.9.1"
  }
}

If you want to explicitly reference it as a local package, you can also write it like this:

{
  "dependencies": {
    "com.unity.addressables": "file:com.unity.addressables"
  }
}

However, if you simply want it to be treated as an embedded package, placing it at Packages/com.unity.addressables is usually enough.

Modification policy

In Addressables 2.9.1, WebRequestQueue.cs has the following management structure:

internal static int s_MaxRequest = 3;
internal static Queue<WebRequestQueueOperation> s_QueuedOperations = new Queue<WebRequestQueueOperation>();
internal static List<UnityWebRequestAsyncOperation> s_ActiveRequests = new List<UnityWebRequestAsyncOperation>();

Roughly speaking, they mean:

s_QueuedOperations = requests waiting in the queue that have not called SendWebRequest yet
s_ActiveRequests   = requests that have already called SendWebRequest and are currently running

What we want to do is:

Queued requests:
  Do not start communication, and notify AssetBundleProvider that they were canceled

Active requests:
  Stop them with UnityWebRequest.Abort()

To do that, we add the following changes:

1. Add OnCancel to WebRequestQueueOperation
2. Add AbortRequest() to WebRequestQueue
3. Register cancellation handling in AssetBundleProvider through OnCancel

Modifying WebRequestQueue.cs

First, add OnCancel to WebRequestQueueOperation.

public class WebRequestQueueOperation
{
    private bool m_Completed = false;

    /// <summary>
    /// Stores the async operation object returned from sending the web request.
    /// </summary>
    public UnityWebRequestAsyncOperation Result;

    /// <summary>
    /// Event that is invoked when the async operation is complete.
    /// </summary>
    public Action<UnityWebRequestAsyncOperation> OnComplete;

    /// <summary>
    /// Event that is invoked when the queued request is canceled before sending.
    /// </summary>
    public Action OnCancel { get; set; }

    /// <summary>
    /// Indicates that the async operation is complete.
    /// </summary>
    public bool IsDone
    {
        get { return m_Completed || Result != null; }
    }

    internal UnityWebRequest m_WebRequest;

    /// <summary>
    /// The web request.
    /// </summary>
    public UnityWebRequest WebRequest
    {
        get { return m_WebRequest; }
        internal set { m_WebRequest = value; }
    }

    public WebRequestQueueOperation(UnityWebRequest request)
    {
        m_WebRequest = request;
    }

    internal void Complete(UnityWebRequestAsyncOperation asyncOp)
    {
        m_Completed = true;
        Result = asyncOp;
        OnComplete?.Invoke(Result);
    }
}

Next, add AbortRequest() to WebRequestQueue.

public static class WebRequestQueue
{
    internal static int s_MaxRequest = 3;
    internal static Queue<WebRequestQueueOperation> s_QueuedOperations = new Queue<WebRequestQueueOperation>();
    internal static List<UnityWebRequestAsyncOperation> s_ActiveRequests = new List<UnityWebRequestAsyncOperation>();

    /// <summary>
    /// Cancels queued requests and aborts active requests.
    /// </summary>
    public static void AbortRequest()
    {
        // Cancel requests that are waiting in the queue and have not started communication yet.
        var queuedOperations = s_QueuedOperations.ToArray();
        s_QueuedOperations.Clear();

        foreach (var operation in queuedOperations)
        {
            operation.OnCancel?.Invoke();
        }

        // Abort requests that have already started communication.
        foreach (var operation in s_ActiveRequests.ToArray())
        {
            operation.completed -= OnWebAsyncOpComplete;
            operation.webRequest.Abort();

            // Remove it from the active request list.
            // Since the queued operations have already been cleared,
            // this won't start the next queued request.
            OnWebAsyncOpComplete(operation);
        }
    }
}

queuedOperations is copied with ToArray() before calling Clear().

This avoids modifying the queue while it is being enumerated, because Addressables-side completion handling may run inside OnCancel.

For active requests, Abort() is called.

At that point, operation.completed -= OnWebAsyncOpComplete; removes the completion callback from WebRequestQueue, and then OnWebAsyncOpComplete(operation) is called manually.

The purpose is to remove the request from s_ActiveRequests.

Because s_QueuedOperations.Clear() has already been called, this does not start the next queued request.

Modifying AssetBundleProvider.cs

Next, register cancellation handling in AssetBundleProvider through OnCancel.

In 2.9.1, there is a place where WebRequestQueueOperation is received and BeginWebRequestOperation is registered to OnComplete.

Add the cancellation handling there.

internal void AddBeginWebRequestHandler(WebRequestQueueOperation webRequestQueueOperation)
{
    if (webRequestQueueOperation.IsDone)
    {
        BeginWebRequestOperation(webRequestQueueOperation.Result);
    }
    else
    {
#if ENABLE_PROFILER
        AddBundleToProfiler(Profiling.ContentStatus.Queue, m_Source);
#endif
        webRequestQueueOperation.OnComplete += asyncOp => BeginWebRequestOperation(asyncOp);

        // Register cancellation handling for queued requests.
        webRequestQueueOperation.OnCancel += () =>
        {
            // Do not call the normal web request completion path.
            // This request was canceled before SendWebRequest was called.
            webRequestQueueOperation.OnComplete = null;

            // Notify Addressables that the provide operation has failed.
            m_ProvideHandle.Complete<AssetBundleResource>(null, false, null);

#if ENABLE_CACHING
            if (!string.IsNullOrEmpty(m_Options.Hash))
            {
#if ENABLE_PROFILER
                if (m_Source == BundleSource.Cache)
#endif
                {
                    // Even when the operation fails, a null-like cache state can remain.
                    // If the same address is loaded or downloaded again, that cached null can be returned immediately.
                    // Clear the cached version to avoid that state.
                    var locHash = Hash128.Parse(m_Options.Hash);

                    if (!locHash.isValid ||
                        !Caching.IsVersionCached(new CachedAssetBundle(m_Options.BundleName, locHash)))
                    {
                        Caching.ClearCachedVersion(m_Options.BundleName, locHash);
                    }
                }
            }
#endif
        };
    }
}

The important point is that the normal OnComplete path must not be called when canceled.

Requests waiting in the communication queue have not called SendWebRequest() yet.

Therefore, instead of sending them to the normal request completion path, we notify Addressables of failure by calling m_ProvideHandle.Complete<AssetBundleResource>(null, false, null).

Usage

After this change, call WebRequestQueue.AbortRequest() when the user wants to cancel communication.

using UnityEngine.ResourceManagement;

public sealed class DownloadCancelButton
{
    public void CancelDownload()
    {
        WebRequestQueue.AbortRequest();
    }
}

This allows both of the following to be canceled:

Queued requests:
  Call OnCancel and notify Addressables that the operation failed

Active requests:
  Stop communication with UnityWebRequest.Abort()

Note: This implementation is a global cancellation

The AbortRequest() implementation above cancels all requests currently stored in WebRequestQueue.

This is simple when you want to stop all Addressables communication, but it is not suitable if multiple download processes are running at the same time and you only want to cancel one of them.

If you want partial cancellation, extend the method so that it can filter requests by URL or internal ID.

For example, you can add a Predicate<UnityWebRequest> parameter like this:

public static void AbortRequest(Predicate<UnityWebRequest> predicate)
{
    var queuedOperations = s_QueuedOperations.ToArray();
    s_QueuedOperations.Clear();

    foreach (var operation in queuedOperations)
    {
        if (predicate == null || predicate(operation.WebRequest))
        {
            operation.OnCancel?.Invoke();
        }
        else
        {
            s_QueuedOperations.Enqueue(operation);
        }
    }

    foreach (var operation in s_ActiveRequests.ToArray())
    {
        if (predicate != null && !predicate(operation.webRequest))
            continue;

        operation.completed -= OnWebAsyncOpComplete;
        operation.webRequest.Abort();
        OnWebAsyncOpComplete(operation);
    }
}

Usage example:

WebRequestQueue.AbortRequest(request =>
{
    return request != null &&
           request.url.Contains("/addressables/");
});

Filtering by your project's CDN path or version path can reduce the risk of stopping unintended requests.

Note: Retry behavior for active requests

Queued requests are explicitly completed as failed through OnCancel.

On the other hand, requests that are already active are interrupted with UnityWebRequest.Abort().

In that case, they may still flow into the normal communication failure handling path inside Addressables.

Depending on the AssetBundleProvider settings or the Addressables version, they may be retried if retry settings are enabled.

If you also want active requests to be treated as a true "user cancellation", add a separate cancellation flag and branch inside WebRequestOperationCompleted so that it does not enter the normal retry path.

The general idea is:

Set a cancellation flag when WebRequestQueue.AbortRequest() is executed
↓
Check whether cancellation is active inside AssetBundleProvider's request completion handling
↓
If canceled, do not treat it as a normal network error or retry target.
Complete it as failed instead

This part differs depending on the Addressables version, so it is safest to check the AssetBundleProvider.cs used by your project and adjust accordingly.

Note: Clearing the cache

Even when a request is canceled or fails, a partially invalid state can remain on the cache side.

If the same address is loaded or downloaded again in that state, the invalid cache state may be returned immediately.

Because of that, this example clears the target Bundle cache with Caching.ClearCachedVersion when canceled.

var locHash = Hash128.Parse(m_Options.Hash);

if (!locHash.isValid ||
    !Caching.IsVersionCached(new CachedAssetBundle(m_Options.BundleName, locHash)))
{
    Caching.ClearCachedVersion(m_Options.BundleName, locHash);
}

Depending on the project, this may not be necessary.

However, if the same data may be downloaded again after canceling a large download, it is worth checking how the cache behaves.

Summary

When downloading a large number of remote assets with Addressables, queued requests are stored inside Addressables even if MaxConcurrentWebRequests is set.

Because of that, if you submit 500 downloads at once and then cancel them, the remaining requests may still be processed one by one, causing cancellation to take a long time.

If you want to pass all targets to Addressables for progress UI, app-side queue control alone may not be enough.

In this approach, we directly modify WebRequestQueue and AssetBundleProvider in Addressables 2.9.1 and add the following behavior:

Queued requests:
  Call OnCancel and complete them as failed before communication starts

Active requests:
  Stop communication with UnityWebRequest.Abort()

With this change, both queued requests and active requests can be stopped when the user cancels.

However, the internal implementation of Addressables differs depending on the version.

Treat the code in this article as one example for 2.9.1, and adjust it to match the Addressables version used by your project.

References

Unity Manual: Embedded dependencies https://docs.unity3d.com/ja/2023.2/Manual/upm-embed.html
Unity Scripting API: PackageManager.Client.Embed https://docs.unity3d.com/2023.2/Documentation/ScriptReference/PackageManager.Client.Embed.html
Unity Manual: Local folder or tarball paths https://docs.unity.cn/Components/upm-localpath.html
Addressables: Asynchronous operation handles https://docs.unity.cn/Packages/com.unity.addressables@2.2/manual/AddressableAssetsAsyncOperationHandle.html

A Practical Guide to Unity Addressables Bundle Splitting and LZ4/LZMA Compression

GameDevToolLab — Fri, 19 Jun 2026 11:31:12 +0000

Overview

In the previous article, we looked at Addressables download concurrency, label design, and batch downloads using labels.

One important point there was this:

Labels are only the entry point for specifying what you want to download. The actual files downloaded are AssetBundles.

In other words, even if your label design looks clean, a rough Bundle layout can still cause unexpected assets to be downloaded together.

This time, we will look at how to split AssetBundles and how to choose compression settings.

In particular, this article covers:

Whether Bundles should be split into smaller units or grouped together
How to handle many small files, such as VN / adventure game scenario text files
How to split assets that will keep increasing over time, such as character 3D models
How to think about Pack Together, Pack Separately, and Pack Together By Label
How to choose between LZ4 and LZMA

This is not an introduction to the official features. The focus is on practical decision-making for real projects.

Label design and Bundle splitting must be considered together

In Addressables, you can use Addresses and Labels to specify which assets to load or download.

However, the actual files downloaded are AssetBundles.

For example, suppose you define labels like this:

Label	Purpose
`chapter_01`	Assets used in Chapter 1
`chapter_02`	Assets used in Chapter 2
`character_alice`	Assets related to Alice
`character_bob`	Assets related to Bob

If you only look at the labels, it may seem like the assets are managed in a fine-grained way.

But if the actual Bundle is packed as one large Bundle, downloading only chapter_01 may still download other assets included in the same Bundle.

So, in Addressables, these two concepts need to be considered separately:

Item	Role
Address / Label	Specifies which assets are requested
AssetBundle	The actual unit downloaded, cached, and loaded

Label design alone does not determine the download unit.

Label design and Bundle splitting must be designed together.

What does Bundle splitting affect?

Bundle splitting is not just a way to organize things in the Editor.

In practice, it affects the following:

Affected area	Description
Download unit	Which files are downloaded together
Cache unit	Which units are stored on the device
Update unit	Which Bundles become update targets during content updates
Load unit	Which Bundles are required at load time
Number of files	Affects download requests and file open operations
Management cost	Catalogs, dependencies, and operation rules become more complex

Splitting Bundles into smaller units makes it easier to download only what is needed and reduce update size.

On the other hand, if the number of Bundles increases too much, download requests, cached files, file open operations, catalog complexity, and dependency management cost all increase.

So with Addressables, “smaller is always better” is not the right answer.

The basic approach is:

Group what should be grouped, and split what should be split, based on how the assets are actually used.

Bundle Mode options

In Addressables Group settings, you can choose a Bundle Mode.

The main options are:

Bundle Mode	Description	Suitable cases
`Pack Together`	Packs assets in the group into Bundles together	Small files, or data used together
`Pack Separately`	Packs each Addressable entry in the group into a separate Bundle	Characters, stages, costumes, and other assets with clear update units
`Pack Together By Label`	Packs assets with the same label set together	Cases where you want to manage or download by label

One important detail is that Pack Separately does not mean “one asset per Bundle.”

It means one Bundle per Addressable entry.

If a folder is marked as an Addressable entry, the contents under that folder may be packed into one Bundle.

Also, scene assets are handled as separate Bundles from normal assets. Even with Pack Together, everything is not necessarily packed into a single file.

Avoid casually saying “one address, one file”

In real projects, people sometimes describe Pack Separately as “one address, one file.”

That may be fine for a rough conversation, but it is better to be careful when writing design documents or articles.

As an Addressables setting, the accurate term is Pack Separately.

Pack Separately creates a separate Bundle for each Addressable entry in the group.

So the following cases are not as simple as “one asset = one Bundle”:

A folder is registered as an Addressable entry
Sprite Atlases or Sub Assets are involved
Scenes and normal assets are mixed
Dependencies are moved into separate Bundles

For a rough explanation, “one address, one file” may be understandable.

But for actual design, it is safer to think in terms of Pack Separately.

Cases where grouping Bundles is acceptable

First, let’s look at cases where grouping assets into Bundles is reasonable.

Asset characteristic	How to think about it
Each file is small	Creating individual Bundles may make the file count a bigger problem
There are many files	Download requests and file open operations can increase
They are used together	Splitting does not change the actual load unit much
Individual updates are rare	Fine-grained update units provide little benefit
The management unit is clear	Easy to group by chapter, event, language, and so on

Typical examples include:

VN / adventure game scenario text
Dialogue text
Small .txt files
Small configuration files
Master data
Localization text
Lightweight ScriptableObject assets

For this kind of data, creating one Bundle per file may not be the easiest approach to operate.

Especially when each file is only a few KB to a few dozen KB, and there are hundreds or thousands of them, the downside of increasing the number of files can become more noticeable than the benefit of fine-grained Bundles.

Many small files, such as VN scenario text

VN / adventure game scenario text is an easy example where grouping often makes sense.

For example, suppose you have a structure like this:

Scenario/
  Chapter01/
    scene_001.txt
    scene_002.txt
    scene_003.txt
    ...
  Chapter02/
    scene_001.txt
    scene_002.txt
    scene_003.txt
    ...

If every .txt file is packed into its own Bundle, the number of files increases quickly.

When the file count increases, the following costs also increase:

More download requests
More cached files
More file open operations
More file lookup and management cost
Catalog and dependency checks become more tedious

Of course, if you need to update each scenario file independently, or if you absolutely do not want to download a scenario until the user is about to read it, splitting into smaller units may be valid.

But in many cases, grouping like this is easier to operate:

Grouping unit	Example
Chapter	`scenario_chapter_01`
Event	`scenario_event_summer`
Language	`scenario_ja`, `scenario_en`
Delivery unit	`scenario_initial`, `scenario_update_001`

For scenario text, users often play by chapter or event.

So grouping Bundles by those units usually makes operation easier.

Cases where Bundles should be split

On the other hand, there are also cases where splitting Bundles is better.

Asset characteristic	How to think about it
Each asset is large	Downloading unnecessary data becomes costly
The addition unit is clear	Easy to update by character, costume, or stage
Individual updates are frequent	Update diffs can be kept smaller
The asset may not be used	It can be downloaded only when needed
There is a sales or unlock unit	Works well with DLC, gacha, event rewards, etc.

Typical examples include:

Character 3D models
Character-specific Meshes
Character-specific Textures
Character-specific Materials
Character-specific Animations
Costumes
Weapons
Stages
Large Prefabs
VFX
Voice assets

If you group these too aggressively, operation can become painful.

In particular, assets such as characters and stages often increase over time. Splitting Bundles by the unit in which they are added makes them easier to manage.

Assets that keep increasing, such as character 3D models

Character 3D models are an easy example where splitting Bundles often makes sense.

Suppose all characters are packed into one Bundle:

character_all.bundle
  Alice
  Bob
  Carol
  Dave
  Eve

With this layout, adding just one new character can make the entire character_all.bundle an update target.

Even if a user only needs Alice, they may still download Bob and the other characters because they are in the same Bundle.

On the other hand, if you split Bundles by character, the update and download units become clearer:

character_alice.bundle
character_bob.bundle
character_carol.bundle
character_dave.bundle
character_eve.bundle

With this layout, if only Alice is needed, only Alice’s Bundle can be downloaded.

When adding a new character, you can add a new Bundle and avoid updating existing character Bundles as much as possible.

A character Bundle may contain assets like this:

character_alice.bundle
  Alice.prefab
  Alice.mesh
  Alice.material
  Alice_texture_base
  Alice_texture_normal
  Alice_animation_idle
  Alice_animation_run

This kind of layout is practical because larger assets that are used together are grouped by their addition and update unit.

`Pack Together By Label` is useful, but depends on label design

Pack Together By Label packs assets with the same label set into Bundles.

If your label design is clean, this can make it easier to create Bundles by label.

For example:

Asset	Labels
Alice-related assets	`character_alice`, `initial_download`
Bob-related assets	`character_bob`, `event_001`
Chapter 1 scenario	`scenario_chapter_01`, `initial_download`
Chapter 2 scenario	`scenario_chapter_02`, `update_001`

However, if labels are messy, relying on Pack Together By Label can easily produce an unintended Bundle layout.

For example, if management labels, download labels, event labels, and search labels are mixed together, the number of label combinations increases and the Bundle layout becomes hard to read.

When using Pack Together By Label, it is safer to separate label responsibilities:

Label type	Example	Notes
Download labels	`initial_download`, `chapter_01`	These may affect Bundle splitting
Classification labels	`character`, `scenario`	Decide whether they should affect Bundle splitting
Management labels	`deprecated`, `debug`	Avoid mixing them with runtime labels
Event labels	`event_001`	Also consider what happens after the event ends

Increasing the number of labels is not bad by itself.

But when using Pack Together By Label, the label set directly affects the Bundle layout, so you need operation rules.

How to decide whether to group or split

As a rough guide:

Asset characteristic	Recommendation
Many small files	Group them
Used together by chapter or event	Group them
Little need for individual updates	Group them
Too many files are being created	Group them
Each asset is large	Split them
Addition unit is clear	Split them
Added by character, costume, or stage	Split them
You do not want to download unused assets	Split them
You want to keep update diffs small	Split them

In more practical terms:

Group many small files
Split large assets with clear addition units
Group assets that are used together
Split assets that may not be used
Split assets with different update units

These are the basic rules for Bundle splitting.

Difference between LZ4 and LZMA

Next, let’s look at compression settings.

In Addressables Group settings, you can choose the compression format for Bundles.

The common choices are LZ4 and LZMA.

Compression	Characteristics
LZMA	High compression ratio, useful for reducing download size
LZ4	Chunk-based and easier to handle at load time
Uncompressed	No decompression cost, but file size tends to be larger

LZMA treats the entire Bundle as one compressed stream.

This usually gives a higher compression ratio, but the decompression cost during loading can become larger.

LZ4 compresses data in chunks.

Its compression ratio is usually lower than LZMA, but it is easier to read only the needed parts, and it tends to be lighter to handle at load time.

Cases where LZMA is easy to recommend

LZMA is useful when you want to reduce download size.

However, in real projects, it is safer to decide based on what is inside the Bundle.

As a rule of thumb:

If 1 Bundle is close to 1 asset, LZMA is easy to recommend.
If 1 Bundle contains multiple assets, LZ4 should be the default.

Here, “1 Bundle = 1 asset” means cases like:

One large binary file
One large TextAsset
One video file
One audio file
One Prefab packed into its own Bundle
One Texture packed into its own Bundle

These Bundles are likely to be loaded almost entirely when used.

That makes it easier to benefit from LZMA’s high compression ratio.

On the other hand, be careful with a Bundle like this:

character_alice.bundle
  Alice.prefab
  Alice.mesh
  Alice.material
  Alice_texture_base
  Alice_texture_normal
  Alice_animation_idle
  Alice_animation_run

This is a “one character, one Bundle” layout, but the Bundle still contains multiple assets.

Even if it looks like one unit called Alice at the application level, the Bundle itself is a collection of multiple assets.

So it is safer not to casually decide “one character Bundle means LZMA.”

LZMA is easy to recommend only when the layout is close to 1 Bundle = 1 asset.

Use LZ4 as the default for Bundles containing multiple assets

LZMA treats the entire Bundle as one compressed stream.

So even if you only want to read part of the Bundle, the decompression cost of the whole Bundle can become an issue at load time.

When multiple independent assets are grouped into one Bundle, LZ4 is usually easier to operate.

Bundle layout where LZ4 should be the default	Reason
Bundle containing multiple Addressable entries	You may only read part of it
Bundle containing many small files	The purpose is reducing file count, so partial access matters
Chapter-level scenario Bundle	You may not read every file in the chapter at once
Master data Bundle	Only some data may be referenced
Localization Bundle	Data may be read by language or screen
Character-related asset Bundle	Often contains Prefab, Mesh, Texture, Animation, etc.
Bundle where stable load time and memory behavior matter	Avoiding full-stream decompression is safer

The important point is:

“One character, one Bundle” and “one Bundle, one asset” are different things.

Even if a character has its own Bundle, if that Bundle contains a Prefab, Meshes, Textures, Materials, and Animations, it is still a multi-asset Bundle.

In that case, using LZ4 as the default usually makes load-time behavior more stable.

Cases where LZ4 should be the default

LZ4 is suitable when you care about load-time handling.

In Addressables, it is common to group multiple assets into one Bundle. In practice, LZ4 is usually the default choice for multi-asset Bundles.

Bundle layout	Reason
Bundle containing many small files	You may only read part of it
Chapter-level scenario Bundle	Files are often read in sequence
Master data Bundle	Only some data may be referenced
Localization Bundle	Data may be read by language or screen
Bundle containing multiple Addressable entries	LZMA is more affected by whole-Bundle decompression
Character-related asset Bundle	Often contains multiple assets
Bundle where stable load time matters	Chunk-based compression is easier to operate

For Bundles that group multiple files, such as VN scenario text, LZ4 is often easier to handle.

Group the Bundle to reduce the number of files.

But use LZ4 because you may only read part of the Bundle.

This combination is very practical.

Practical recommended settings

As a starting point, the following rules are easy to work with:

Asset type	Bundle split	Compression
One large TextAsset	1 asset per Bundle	LZMA recommended
One large binary file	1 asset per Bundle	LZMA recommended
One video file	1 asset per Bundle	LZMA recommended, but also consider compression of the video format itself
One audio file	1 asset per Bundle	LZMA recommended, but also consider compression of the audio format itself
One Texture	1 asset per Bundle	LZMA recommended, but judge based on the size after texture compression
VN scenario text	Group by chapter or event	LZ4
Dialogue text	Group by chapter, event, or language	LZ4
Master data	Group by type or update unit	LZ4
Localization	Group by language	LZ4
Character 3D models	Consider one Bundle per character	LZ4 if the Bundle contains multiple assets
Costumes	Consider one Bundle per costume	LZ4 if the Bundle contains multiple assets
Stages	Consider one Bundle per stage	LZ4 if the Bundle contains multiple assets
Large VFX	Split by usage unit	LZ4 if the Bundle contains multiple assets
Voice assets	Split by character, chapter, or event	LZ4 if multiple files are grouped together

The key point is to think about Bundle granularity and compression format separately.

Splitting Bundles, such as one Bundle per character, is useful for reducing download and update units.

However, if that Bundle contains multiple assets, LZ4 should be the default compression choice.

Conversely, if a Bundle contains only one asset, LZMA is easy to recommend.

Condition	Recommendation
1 Bundle is close to 1 asset	LZMA recommended
The whole Bundle is always read	LZMA is easier to recommend
You strongly want to reduce initial download size	LZMA is easier to recommend
Multiple Addressable entries are included	LZ4 by default
You may only read part of the Bundle	LZ4 by default
Many small files are grouped together	LZ4 by default
You want stable load time	LZ4 by default
Web delivery is involved	Start with LZ4 in mind

Of course, the final decision should be based on real device measurements.

Even with “1 asset per Bundle,” the perceived behavior changes depending on asset type, size, device performance, and load timing.

Measure download size, load time, and memory usage on real devices before making the final decision.

Notes on Bundle splitting

There are a few additional things to keep in mind when splitting Bundles.

Duplicate dependencies

When Bundles are split into smaller units, shared dependencies become important.

For example, if multiple characters reference the same Material or Texture, the dependency layout can become complicated depending on how you split the Bundles.

You need operation rules for whether shared assets should be moved into a shared Bundle or kept with each character.

Do not look only at update diffs

Splitting Bundles into smaller units makes update diffs easier to reduce.

But the trade-off is an increased number of Bundles.

If you only look at update size, you may want to split everything. But download requests, cache count, and load-time management cost should be considered together.

Think about initial downloads and additional downloads separately

Assets needed for the initial download and assets downloaded later should not be judged by the same rule.

Type	How to think about it
Initial download	Group assets needed immediately after launch and reduce the number of downloads
Additional download	Download only what is needed by character, stage, or event
Optional download	Download voices, high-resolution textures, etc. only when needed

For initial downloads, grouping more aggressively can be easier.

For additional downloads, making the unit clear is usually easier to operate.

Do not mix the responsibilities of labels and Bundle Mode too much

Labels are useful, but trying to solve everything with labels can break the design.

Labels for specifying download targets
Labels for search or classification
Labels for management
Labels for events
Labels for debugging

If all of these are mixed together and you use Pack Together By Label, the Bundle layout becomes difficult to understand.

When adding labels, consider whether each label is allowed to affect Bundle splitting.

Practical checklist

Finally, here is a checklist for deciding Bundle layout.

Group or split

[ ] Are these assets used together?
[ ] Do you want to download them individually?
[ ] Do you want to update them individually?
[ ] Is each file large?
[ ] Is the number of files getting too high?
[ ] Is there a clear unit such as character, chapter, stage, or event?
[ ] Is this part of the initial download or an additional download?
[ ] Are unnecessary assets being downloaded?

Compression settings

[ ] Is download size the priority?
[ ] Is load time the priority?
[ ] Is the layout close to 1 Bundle = 1 asset?
[ ] Does the Bundle contain multiple assets?
[ ] Is there a chance that only part of the Bundle will be read?
[ ] Did you measure download size on a real device?
[ ] Did you measure load time on a real device?
[ ] Did you measure memory usage on a real device?

Operation

[ ] Does the label design match the Bundle layout?
[ ] Are you relying too much on Pack Together By Label?
[ ] Have you decided how to handle shared dependencies?
[ ] Are you balancing update size and file count?
[ ] Will the design still work after more assets are added post-release?

Summary

With Addressables Bundle splitting, neither “split everything” nor “group everything” is always correct.

The important thing is to decide based on how the assets are used, update units, download units, file count, and load-time cost.

For data such as VN scenario text, where each file is small but there are many files, grouping by chapter or event can be easier to operate.

This is because increasing the number of files also increases download requests, cached files, file open operations, file lookup cost, and management cost.

On the other hand, for assets such as character 3D models, where each asset is large and new assets are likely to be added over time, splitting by character can be easier to manage.

For compression, the rule of thumb is:

If 1 Bundle is close to 1 asset, LZMA is recommended. If the Bundle contains multiple assets, use LZ4 by default.

LZMA is useful when compression ratio is the priority, but because whole-Bundle decompression can become an issue, it is safer to avoid it when multiple independent load targets are grouped into one Bundle.

On the other hand, if the Bundle effectively contains one asset, such as one large TextAsset, one binary file, or one Texture, LZMA is easy to recommend.

In the end, always measure download size, load time, and memory usage on real devices before making the final decision.

Addressables can look complicated if you only look at the settings.

But in practice, the basic idea is simple:

Group small files. Split large assets with clear addition units. For compression, use LZMA when 1 Bundle is close to 1 asset, and use LZ4 by default for multi-asset Bundles.

Starting from this policy makes it easier to build a Bundle layout that does not break down over time.

Practical Tips for Unity Addressables: Concurrent Downloads and Label Design

GameDevToolLab — Fri, 19 Jun 2026 11:29:54 +0000

Overview

Unity Addressables makes it much easier to handle remote asset downloads and cache management.

However, when you use it in a real project, you may run into issues like these:

Calling DownloadDependenciesAsync does not make downloads as fast as expected
Downloading by label pulls in assets you did not expect
Manually managing Address and Label settings becomes painful

This article focuses on the points that are easy to overlook when designing downloads with Addressables:

Configuring the number of concurrent downloads
How to think about concurrent downloads on iOS and Android
Why you should start downloading larger files first
Bulk downloads using labels
The difference between labels and AssetBundle download units
Automating management with Smart Addresser

Bundle splitting and LZ4/LZMA compression will be covered in a separate article, so this article only touches on them where necessary.

Addressables download speed is not determined by a single API call

When pre-downloading assets with Addressables, the API you will often use is:

Addressables.DownloadDependenciesAsync(label);

This is useful because it allows you to download the dependencies associated with a label or address ahead of time.

That makes the user experience more stable than suddenly downloading assets right before a loading sequence.

However, download speed is not determined just by calling this API.

In practice, it depends on factors such as:

The number of concurrent downloads
CDN or server response speed
The user's network condition
AssetBundle size
The number of AssetBundles
Device performance
Decompression and loading cost after download

Especially in mobile games, the number of concurrent downloads and the order in which downloads are started are very important.

Configure the number of concurrent downloads properly

Addressables allows you to control how many web requests run at the same time.

At runtime, you can configure it with the following API:

WebRequestQueue.SetMaxConcurrentRequests(maxRequests);

If the number of concurrent downloads is too low, you may not fully utilize the available network or CDN performance.

On the other hand, if it is too high, you may run into problems such as:

Increased load on low-end devices
Lower frame rate during downloads
More heat generation
Bottlenecks during decompression or loading after downloads
Instability depending on the network condition

In other words, more concurrent downloads do not always mean faster downloads.

You need to tune this based on your target devices, Bundle size, network environment, and loading screen design.

Use 10 on iOS, and switch between 3 and 10 on Android based on device performance

In my projects, I use the following policy based on real-device testing.

Platform	Concurrent downloads
iOS	10
High-end Android devices	10
Low- to mid-range Android devices	3

The important point is that this is not an official fixed recommendation from Unity.

It is a practical policy adopted after testing within a specific project.

:::message
In this article, I use 10 concurrent downloads on iOS and either 3 or 10 on Android depending on device performance, as a practical policy based on real-device testing.

The optimal value depends on your CDN, network condition, Bundle size, and device performance, so make sure to measure it on actual devices.
:::

iOS devices tend to have less variation in performance, so it is easier to use a relatively aggressive setting.

Android devices vary much more, so it is safer to switch the value based on device performance instead of using 10 for every device.

Configure concurrent downloads at runtime

If you want to change the number of concurrent downloads per device, call WebRequestQueue.SetMaxConcurrentRequests() when the app starts.

using UnityEngine;
using UnityEngine.ResourceManagement;

public static class AddressablesDownloadTuning
{
    public static void Apply()
    {
        int maxRequests = GetMaxConcurrentRequests();

        WebRequestQueue.SetMaxConcurrentRequests(maxRequests);

        Debug.Log($"Addressables max concurrent requests: {maxRequests}");
    }

    private static int GetMaxConcurrentRequests()
    {
#if UNITY_IOS
        return 10;
#elif UNITY_ANDROID
        return GetAndroidDeviceScore() >= 3 ? 10 : 3;
#else
        return 10;
#endif
    }

#if UNITY_ANDROID
    private static int GetAndroidDeviceScore()
    {
        int score = 0;

        if (SystemInfo.systemMemorySize >= 6000)
            score += 2;
        else if (SystemInfo.systemMemorySize >= 4000)
            score += 1;

        if (SystemInfo.processorCount >= 8)
            score += 1;

        if (SystemInfo.graphicsMemorySize >= 2048)
            score += 1;

        return score;
    }
#endif
}

Call it during app initialization.

using UnityEngine;

public class AppInitializer : MonoBehaviour
{
    private void Awake()
    {
        AddressablesDownloadTuning.Apply();
    }
}

The key is to configure this before Addressables downloads begin.

It is easier to manage if you call it at a fixed timing, such as during initial app setup or around Addressables initialization.

Adjust Android scoring for your project

In the sample above, the Android device score is calculated using:

System memory
CPU core count
GPU memory

However, this scoring method is only an example.

In practice, the best criteria will differ depending on your project's target devices, Bundle sizes, download-time load, and loading screen design.

For example, you may want to tune it while checking:

Minimum target device specs
FPS during downloads
Memory usage during downloads
Decompression and loading time after downloads
Heat generation
Network conditions
Whether other loading tasks also run during downloads

Android devices vary widely, so you cannot simply say, "This device has a lot of memory, so 10 is fine."

Even if the memory and CPU specs look good, storage performance or network conditions can still make download behavior unstable.

For that reason, device scoring should not be treated as a fixed answer.

It should be adjusted per project based on real-device testing.

Personally, I first decide a safe value for low-end devices, then increase the number of concurrent downloads only for higher-end devices.

Start downloading larger files first when downloading multiple files

When configuring concurrent downloads, there is one more thing to consider: the order in which downloads are started.

If you manage your own queue of multiple Bundles or labels, it is generally better to start with the largest files first.

The reason is that you want to avoid leaving one huge file until the very end.

For example, suppose the maximum number of concurrent downloads is 3 and you have the following download targets.

File	Size
A	300MB
B	20MB
C	10MB
D	8MB
E	5MB

If you start from the smallest files, the download may look smooth at first.

However, if the 300MB file is left until the end, the progress can appear to stall near the end of the loading screen.

Starting from smaller files

[ 5MB ] [ 8MB ] [ 10MB ]
[ 20MB ]
[ 300MB ] <- Only the largest file remains at the end

On the other hand, if you start downloading the larger file first, the 300MB file can progress in the background while smaller files are processed in the remaining request slots.

Starting from larger files

[ 300MB ] [ 20MB ] [ 10MB ]
[ 8MB ] [ 5MB ] <- Smaller files are processed while the larger one is already running

Even with the same number of concurrent downloads, the perceived waiting time can change depending on the order.

This is especially useful when you download multiple additional assets together on a loading screen.

In that case, it is usually better to enqueue larger Bundles first.

However, when you call Addressables.DownloadDependenciesAsync(label) for a single label, it is difficult to precisely control which Bundle is downloaded first internally.

If you want explicit control over the download order, split your download targets by label or key, get their sizes in advance, and then start downloads in descending order of size.

using System.Collections;
using System.Collections.Generic;
using System.Linq;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AddressablesPreloadQueue : MonoBehaviour
{
    [SerializeField]
    private List<string> preloadLabels = new()
    {
        "scenario_chapter_01",
        "voice_jp_chapter_01",
        "character_hero_001",
    };

    private IEnumerator Start()
    {
        yield return PreloadBySize(preloadLabels);
    }

    private IEnumerator PreloadBySize(IReadOnlyList<string> labels)
    {
        var targets = new List<DownloadTarget>();

        foreach (string label in labels)
        {
            var sizeHandle = Addressables.GetDownloadSizeAsync(label);
            yield return sizeHandle;

            if (sizeHandle.Status == AsyncOperationStatus.Succeeded &&
                sizeHandle.Result > 0)
            {
                targets.Add(new DownloadTarget(label, sizeHandle.Result));
            }

            Addressables.Release(sizeHandle);
        }

        targets.Sort((a, b) => b.Size.CompareTo(a.Size));

        var handles = new List<AsyncOperationHandle>();

        foreach (var target in targets)
        {
            Debug.Log($"Download start: {target.Label}, size: {target.Size} bytes");

            var handle = Addressables.DownloadDependenciesAsync(target.Label, false);
            handles.Add(handle);
        }

        while (handles.Any(x => !x.IsDone))
        {
            yield return null;
        }

        foreach (var handle in handles)
        {
            if (handle.Status != AsyncOperationStatus.Succeeded)
            {
                Debug.LogError("Download failed.");
            }

            Addressables.Release(handle);
        }
    }

    private readonly struct DownloadTarget
    {
        public readonly string Label;
        public readonly long Size;

        public DownloadTarget(string label, long size)
        {
            Label = label;
            Size = size;
        }
    }
}

The important point is that WebRequestQueue.SetMaxConcurrentRequests() controls the number of concurrent downloads, while your own queue controls the order in which downloads are started.

For example, if the concurrent request limit is 3, even if you start downloads in descending order of size, only up to 3 web requests will run at the same time.

In short, Addressables bulk downloads become more stable when you think about these three points together:

Match the number of concurrent downloads to device performance
Enqueue download targets from largest to smallest
Design labels and Bundle splitting together

Bulk downloads using labels

Addressables allows you to use labels to handle multiple assets as a group.

For example, if you want to download all assets with the preload label, you can write:

Addressables.DownloadDependenciesAsync("preload");

However, in production, it is usually better to check the download size before starting the download.

Addressables.GetDownloadSizeAsync("preload");

If the assets are already cached, the download size will be 0.

This allows you to implement behavior such as:

Check whether a download is required
Show the download size to the user
Show a Wi-Fi recommendation
Skip the process if the assets are already downloaded

Sample code for DownloadDependenciesAsync

The following sample checks the download size for a label, then downloads it if necessary.

using System.Collections;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;

public class AddressablesPreloader : MonoBehaviour
{
    [SerializeField]
    private string preloadLabel = "preload";

    private IEnumerator Start()
    {
        yield return Preload(preloadLabel);
    }

    private IEnumerator Preload(string label)
    {
        var sizeHandle = Addressables.GetDownloadSizeAsync(label);
        yield return sizeHandle;

        if (sizeHandle.Status != AsyncOperationStatus.Succeeded)
        {
            Debug.LogError($"Failed to get download size: {label}");
            Addressables.Release(sizeHandle);
            yield break;
        }

        long downloadSize = sizeHandle.Result;
        Addressables.Release(sizeHandle);

        if (downloadSize <= 0)
        {
            Debug.Log($"Already downloaded: {label}");
            yield break;
        }

        Debug.Log($"Download size: {downloadSize} bytes");

        var downloadHandle = Addressables.DownloadDependenciesAsync(label, false);

        while (!downloadHandle.IsDone)
        {
            var status = downloadHandle.GetDownloadStatus();
            Debug.Log($"Download progress: {status.Percent:P0}");
            yield return null;
        }

        if (downloadHandle.Status == AsyncOperationStatus.Succeeded)
        {
            Debug.Log($"Download completed: {label}");
        }
        else
        {
            Debug.LogError($"Download failed: {label}");
        }

        Addressables.Release(downloadHandle);
    }
}

In this sample, DownloadDependenciesAsync(label, false) is used, and Addressables.Release(downloadHandle) is called manually after completion.

If you want to display progress or check the result, it is easier to manage the lifetime of the handle yourself.

How to design labels

A label should be designed as a key that represents which group of assets you want to handle together at runtime.

For example, you might use labels like these:

Label	Purpose
`preload`	Minimum assets required on first launch
`scenario_chapter_01`	Scenario text, backgrounds, and character sprites used in chapter 1
`event_2026_summer`	Assets for a limited-time summer event
`character_hero_001`	Assets for a specific character
`voice_jp_chapter_01`	Japanese voice assets for chapter 1

The important point is to design labels based on the actual loading flow.

For example, in an ADV or visual-novel-style game, you might use groups such as:

Common UI required on first launch
Title screen
Tutorial
Scenario assets per chapter
Backgrounds per chapter
Character sprites per chapter
Voice assets per language
Limited-time events

For a game where characters are added over time, labels like these may also work well:

character_hero_001
character_hero_002
skin_hero_001_summer
voice_hero_001_jp

Label design becomes much easier if you work backward from when the user needs each group of assets.

Labels are assigned to assets, but downloads happen per Bundle

This is an easy point to misunderstand.

Addressables labels are assigned to Addressable assets.

However, what actually gets downloaded is the AssetBundle.

:::message alert
A label is a key used to specify which group of assets should be downloaded.

However, the actual download unit is the AssetBundle.

So even if you assign a label to an asset, it does not necessarily mean only that specific asset will be downloaded in isolation.
:::

For example, suppose you have the following setup:

A.prefab has the preload label
B.prefab does not have the preload label
But A.prefab and B.prefab are included in the same AssetBundle

In this case, even if you download using the preload label, the AssetBundle that contains A.prefab will be downloaded.

If B.prefab is also included in that same AssetBundle, B.prefab will effectively be downloaded as well.

In other words, labels are the entry point for selecting download targets, but the actual file unit that gets downloaded is the AssetBundle.

Design labels and Bundle splitting together

Even if your labels are finely designed, the download unit remains large if your Bundles are grouped too broadly.

On the other hand, if you split Bundles too aggressively, the number of files increases.

An increased file count can lead to issues such as:

More requests
More complex catalog and dependency resolution
A large number of tiny Bundles
Higher file lookup and management cost

For this reason, label design and Bundle splitting should always be considered together.

For example, assets like ADV or visual-novel-style scenario files often have many small files.

In that case, splitting every scenario text file, small JSON file, or small configuration file into its own Bundle can create too many files and directly increase download or loading overhead.

For this kind of data, it is often more stable in practice to group assets by chapter or event.

On the other hand, assets like character 3D models are often added over time.

For those, a design close to one Bundle per character may be more suitable.

If characters are added, updated, or removed on a per-character basis, it is easier to operate when they can be downloaded in that same unit.

I will cover this in more detail in the next article.

Manual label management is error-prone

For small projects, manually managing Addressables from the Addressables Groups window is usually fine.

However, as the number of assets grows, manual management becomes painful.

Common problems include:

Forgetting to assign labels
Inconsistent label naming
Old labels remaining unintentionally
Address naming rules becoming inconsistent
Assets being placed in unintended Groups
Forgetting to clean up assets after an event ends

This becomes especially problematic in live-service games, where assets increase with each event or new character.

If every Address and Label is managed manually in that situation, mistakes are almost guaranteed to happen eventually.

Addressables is powerful, but it can become hard to maintain if your operational rules are unclear.

Use Smart Addresser

If you want to manage Address and Label settings through rules, a tool like Smart Addresser can help a lot.

Smart Addresser is an Addressables support tool published by CyberAgentGameEntertainment.

It is not an official Addressables feature, but it can automate management through rules, including:

Automatic Address assignment
Automatic Label assignment
Version management
Rule validation
CLI-based application

Manual management is enough for small projects.

However, once the number of assets grows, it is safer to generate Address and Label settings from rules instead of assigning them by hand.

In team development, it is especially important to make sure the same Address and Label settings are generated no matter who works on the assets.

Recommended practical setup

In practice, the following setup is easy to operate.

Configure concurrent downloads at startup

Call WebRequestQueue.SetMaxConcurrentRequests() when the app starts.

Use a fixed value for iOS, and switch based on device performance for Android, depending on your project.

Assign the `preload` label only to the minimum required assets

Include only the assets required for first launch or the title screen in preload.

If you put too many assets into this label, the initial download becomes heavy.

It is better to keep preload limited to assets that are absolutely required at the beginning.

Split labels by chapter, event, or character

Design labels based on the loading flow.

scenario_chapter_01
scenario_chapter_02
event_2026_summer
character_hero_001
voice_jp_chapter_01

Labels are easier to manage when they match the actual game progression.

Check the download size before downloading

Before a bulk download, use GetDownloadSizeAsync() to check the size.

If the size is large, you can show a confirmation dialog or recommend Wi-Fi.

If the assets are already cached, the size will be 0, so you can skip unnecessary download processing.

Start larger downloads first when downloading multiple targets

If you manage your own download queue for multiple labels or Bundles, start from the largest one.

This helps avoid the situation where only a huge Bundle remains at the end, reducing the feeling that progress has stalled near the end of the loading screen.

Design labels and Bundle splitting together

Even if your labels are cleanly separated, the actual download unit stays large if the Bundle is large.

On the other hand, splitting Bundles too finely increases the number of files.

That is why labels and Bundle splitting should be designed together.

Summary

When designing downloads with Addressables, the number of concurrent downloads and label design are important.

Simply calling DownloadDependenciesAsync does not determine download speed or operational stability.

The number of concurrent downloads should not be increased blindly.

It needs to be tuned based on device performance, network conditions, and Bundle size.

In my projects, I use 10 on iOS and either 3 or 10 on Android depending on device performance, based on real-device testing.

Also, when you manage your own queue for multiple download targets, starting from larger Bundles first helps avoid leaving one huge file until the end.

Labels make bulk downloads easy.

However, labels are only keys used to select download targets.

The actual download unit is the AssetBundle.

For that reason, label design and Bundle splitting should be considered together.

As the number of assets grows, manual Address and Label management becomes more error-prone.

In that case, using a rule-based management tool such as Smart Addresser can make operations much easier.

Next: Bundle splitting and LZ4/LZMA

In the next article, I will cover Addressables Bundle splitting and compression settings.

In particular, I plan to cover topics such as:

Whether many small files, such as ADV scenario files, should be grouped together
Whether character 3D models that will increase over time should use one Bundle per character
Download and lookup overhead caused by increasing the number of files
The downsides of splitting Bundles too finely
How to choose between LZ4 and LZMA

Bundle splitting is one of the areas where practical Addressables operation differs greatly between projects.

Next time, I will organize more concrete decision criteria.

Fast File Loading Techniques in Unity

GameDevToolLab — Fri, 19 Jun 2026 11:26:02 +0000

Temporarily Switch to 60 FPS During Loading and Load Multiple Files in Parallel

Even if your main gameplay runs at 30 FPS or another frame rate lower than 60 FPS, temporarily switching to 60 FPS during loading can improve loading times when reading multiple files.

Also, when loading multiple files, it is more efficient to start all load operations first and then wait for all of them to finish, rather than waiting for each one sequentially.

using System.Threading.Tasks;
using UnityEngine;
using UnityEngine.AddressableAssets;

public class LoadSample : MonoBehaviour
{
    async void Start()
    {
        int prevFps = Application.targetFrameRate;
        int prevVSync = QualitySettings.vSyncCount;

        // Switch to 60 FPS only during loading
        QualitySettings.vSyncCount = 0;
        Application.targetFrameRate = 60;

        // Start multiple load operations at the same time
        var playerTask = Addressables.LoadAssetAsync<GameObject>("Player").Task;
        var enemyTask  = Addressables.LoadAssetAsync<GameObject>("Enemy").Task;
        var uiTask     = Addressables.LoadAssetAsync<GameObject>("BattleUI").Task;

        // Wait until all load operations are complete
        await Task.WhenAll(playerTask, enemyTask, uiTask);

        var playerPrefab = playerTask.Result;
        var enemyPrefab  = enemyTask.Result;
        var uiPrefab     = uiTask.Result;

        // Restore the FPS settings after loading is complete
        Application.targetFrameRate = prevFps;
        QualitySettings.vSyncCount = prevVSync;

        Instantiate(playerPrefab);
        Instantiate(enemyPrefab);
        Instantiate(uiPrefab);
    }
}

There are two key points.

// Start everything first
var taskA = LoadA();
var taskB = LoadB();
var taskC = LoadC();

// Then wait for all of them at the end
await Task.WhenAll(taskA, taskB, taskC);

If you load them sequentially, like this:

await LoadA();
await LoadB();
await LoadC();

the waiting time accumulates.

On the other hand, if the load operations do not depend on each other, starting them at the same time and waiting for all of them together may reduce the total loading time.

However, loading many large assets at the same time can increase memory usage or cause spikes during asset expansion, so it is better to group them reasonably by screen or use case.

Run Network Requests and File Loading at the Same Time

When transitioning to a specific screen, you may need both of the following:

Fetch data from a network API
Load the prefab used to build the screen

If you load the prefab only after the network request finishes, the waiting time is added together.

var apiResult = await CallApi();
var prefab = await LoadPrefab();

If the network request and the loading process do not depend on each other, it is more efficient to start them at the same time.

var apiTask = CallApi();
var prefabTask = LoadPrefab();

await Task.WhenAll(apiTask, prefabTask);

var apiResult = apiTask.Result;
var prefab = prefabTask.Result;

Because the waiting time for the network request and the file loading overlaps, you can reduce the amount of time the user has to wait.