DEV Community: GameDevToolLab

Practical UE5 File Loading Optimization: Beyond Parallel I/O and Raising the FPS Cap

GameDevToolLab — Mon, 24 Aug 2026 14:15:26 +0000

UE5 loading optimization is often reduced to two ideas: read more files in parallel, and raise the FPS cap during a loading screen. Both can help, but only when they target the real bottleneck.

A transition also includes dependency discovery, decompression, UObject creation, Serialize and PostLoad, activation, collision, texture/audio streaming, PSOs, and GC. If activation dominates the Game Thread, more parallel reads may only create a larger completion spike.

This article targets UE 5.8 as of August 2026. Use this order:

Measure I/O and post-load work separately.
Reduce hard-reference graphs and requested data.
Preload by player-experience phase.
Change loading budgets during controlled transitions instead of blindly unlocking FPS.
Tune containers, compression, streaming, and activation on target hardware.

Read by symptom

Slow startup: reference graphs, Asset Manager, IoStore.

Teleport hitch: World Partition sources, texture mips, PSOs.

Freeze after the loading screen: activation, overlap, PSOs.

Slow custom JSON or binary data: split Read, Decode, and Apply.

Decompose load time first

Treat loading as a pipeline:

Stage	Typical work	Common bottleneck
Discover	Asset Registry, Primary Assets, dependencies	Large search scope or graph
Read	Container or file reads	Random I/O, many small requests
Decode	Decryption, Oodle decompression	CPU saturation
Deserialize	UObject creation, `Serialize`, `PostLoad`	Custom work, nested sync loads
Activate	Actor spawn, Component registration, render setup	Game Thread, collision, PSOs

If Read takes 0.4 seconds and Activate takes 2.0 seconds, more I/O concurrency cannot remove most of the wait. It may make more packages finish together and worsen the activation spike.

Record median and p95 transition time, worst Game Thread frame, bytes and request count, decode CPU, activation time, and peak memory. Separate cold and warm-cache runs. Use cooked packaged builds on target devices for final decisions.

Separate loading from waiting with Unreal Insights

In UE 5.8, AssetLoadTime exposes timing around asset serialization, while LoadTime covers runtime loading from pak or IoStore paths:

-trace=default,AssetLoadTime,LoadTime

Use Editor or PIE for reference investigation, then compare a Shipping-equivalent packaged build with the same channels, device, and cache conditions. Add -statnamedevents only when Blueprint names are necessary, and place bookmarks around the transition.

Check for:

I/O or Async Loading Thread starvation.
PostLoad, Actor creation, or registration spikes.
Duplicate requests or urgent work buried under broad preloads.
Texture or PSO hitches after package loading completes.

Focused Zen Loader logging can help:

-LogCmds="LogStreaming veryverbose"

Do not keep VeryVerbose logging in normal profiling builds.

Avoid polling GetAsyncLoadPercentage every frame. Epic warns that it is slow and may block async loading. Prefer load groups, handle callbacks, and monotonic phase-based progress.

The largest optimization is not loading the asset

Hard references such as UTexture2D*, USkeletalMesh*, and Blueprint classes pull dependency graphs into memory. A persistent “all characters” registry can make the title screen load meshes, materials, animation, audio, and VFX. Inspect inclusive size, dependency direction, and cooked chunks with Reference Viewer, Size Map, and Asset Audit.

When owner and target lifetimes differ, use soft references:

UPROPERTY(EditDefaultsOnly)
TSoftObjectPtr<USkeletalMesh> CharacterMesh;

UPROPERTY(EditDefaultsOnly)
TSoftClassPtr<AActor> CharacterClass;

A soft reference does not load its target automatically. Request it through Streamable Manager or Asset Manager when its phase begins.

Changing the type does not guarantee cooking. The Cooker still needs a discoverable route through a serialized UPROPERTY, Asset Bundle, Primary Asset rule, PrimaryAssetLabel, explicit Cook Rule, or similar mechanism. Runtime-generated soft paths need separate cook registration. Verify final chunk membership in a packaged build.

Keep hard references when assets are always required together. Otherwise inspect ConstructorHelpers, Blueprint types and casts, class defaults, and distant World Partition Actor links. Interfaces, IDs, Gameplay Tags, events, or subsystem queries can avoid loading a concrete class.

Load by experience phase with Asset Manager

Individual soft references become difficult to own and release consistently. Centralize policy around Asset Manager and divide Secondary Assets into named Asset Bundles:

UCLASS(BlueprintType)
class UCharacterDefinition : public UPrimaryDataAsset
{
    GENERATED_BODY()
public:
    UPROPERTY(EditDefaultsOnly, meta=(AssetBundles="Menu"))
    TSoftObjectPtr<UTexture2D> Portrait;

    UPROPERTY(EditDefaultsOnly, meta=(AssetBundles="Gameplay"))
    TSoftObjectPtr<USkeletalMesh> Mesh;

    UPROPERTY(EditDefaultsOnly, meta=(AssetBundles="Gameplay"))
    TSoftClassPtr<AActor> CharacterClass;

    UPROPERTY(EditDefaultsOnly, meta=(AssetBundles="Voice"))
    TArray<TSoftObjectPtr<USoundBase>> VoiceAssets;
};

Load Menu during selection, Gameplay after confirmation, and Voice before dialogue. Bundle by player-experience phase, not only file type.

This UE 5.8 excerpt shows ownership and request replacement for one character. It omits declarations, logging, retries, and multi-consumer counting; older versions may use earlier overloads.

void UStageLoadSubsystem::LoadCharacter(const FPrimaryAssetId& Id)
{
    if (LoadedCharacterId == Id) return;

    ReleaseCharacter();
    LoadedCharacterId = Id;

    FAssetManagerLoadParams Params;
    Params.Priority = FStreamableManager::DefaultAsyncLoadPriority;
    Params.OnComplete = FStreamableDelegateWithHandle::CreateWeakLambda(
        this, [this, Id](TSharedPtr<FStreamableHandle>)
        {
            if (LoadedCharacterId != Id) return;
            if (UObject* Asset = UAssetManager::Get()
                    .GetPrimaryAssetObject(Id))
            {
                OnCharacterReady(Asset);
            }
        });

    const TArray<FName> Bundles{ FName(TEXT("Gameplay")) };
    CharacterHandle = UAssetManager::Get().LoadPrimaryAsset(
        Id, Bundles, MoveTemp(Params));
}

void UStageLoadSubsystem::ReleaseCharacter()
{
    if (CharacterHandle.IsValid() &&
        !CharacterHandle->HasLoadCompleted())
    {
        CharacterHandle->CancelHandle();
    }
    CharacterHandle.Reset();

    if (!LoadedCharacterId.IsValid()) return;
    UAssetManager::Get().UnloadPrimaryAsset(LoadedCharacterId);
    LoadedCharacterId = FPrimaryAssetId();
}

Production code still needs request generations, consumer counts, and separate failure and cancellation signals.

API	Lifetime model
`LoadPrimaryAsset(s)`	Retained until `UnloadPrimaryAsset(s)`. The handle controls progress, waiting, cancellation, and callbacks, not asset lifetime.
`PreloadPrimaryAssets`	Valid while its handle is retained; releasable afterward if unreferenced.
Direct Streamable Manager request	A retained handle or hard reference owns the useful lifetime.

LoadPrimaryAsset(s) may return a null handle when no new work is required while still invoking completion. Validate the object in OnComplete, keep failure/cancellation/replacement distinct, and put release under one owner.

Parallel loading is not “the more, the faster”

Unlimited concurrency can create small random reads, decode contention, registration bursts, high peak memory, and urgent-work starvation. Group requests by player need:

Minimum: map, player, required UI.
Immediate: nearby assets, first enemies, essential SFX.
Later: next area, additional enemies, dialogue voice.
Optional: distant high mips and cosmetics.

Only the minimum set should receive high priority. Share in-flight handles and track consumers to prevent duplicate requests and premature unloads.

Cancellation does not rewind completed work. Treat request cancellation, handle release, and UObject-reference removal as separate operations.

Do not represent readiness with one boolean

An async callback rarely means gameplay is safe to start. Track at least:

Requested
AssetsReady
WorldReady
RuntimeReady
PresentationReady
Interactive

After a handle completes, spawning, collision, UI, network synchronization, texture/audio readiness, and PSOs may remain. Aggregate completion from the owning subsystems.

Use measured phase weights for monotonic display progress:

AssetsReady       35%
WorldReady        25%
RuntimeReady      20%
PresentationReady 15%
Interactive        5%

Keep display progress separate from the internal state machine.

Can a higher FPS cap make loading faster?

Sometimes. Streaming and Actor/Component registration include per-frame budgeted work. Raising the FPS cap may apply those budgets more often per second.

It will not help when storage, decompression CPU, or one long Game Thread task is saturated. It may hurt when rendering, animation, UI, or unrelated Tick consumes the extra frames. Treat t.MaxFPS 0 as a diagnostic experiment, not a permanent strategy.

During gameplay, stable frame time matters. During a controlled transition, total completion time may matter more:

Example setting	Purpose
`s.AsyncLoadingTimeLimit`	Per-frame time for async loading
`s.PriorityAsyncLoadingExtraTime`	Extra time for priority loading
`s.LevelStreamingActorsUpdateTimeLimit`	Time for streamed Actor updates
`s.PriorityLevelStreamingActorsUpdateExtraTime`	Extra priority streaming time
`s.LevelStreamingComponentsRegistrationGranularity`	Registration batch size
`s.UnregisterComponentsTimeLimit`	Time for unregister work

Names and behavior vary by version and platform. Check VariableName ?, Engine Source, Device Profiles, and current values. Centralize changes and restore prior values on success, cancellation, error, or map transition. Use Gameplay, Transition, and Tail profiles; wait only for the mandatory remainder in Tail.

Keep the loading screen cheap: heavy 3D scenes, Niagara, blur, Scene Capture, animated UI, and unnecessary Tick compete with loading. Preserve required render preparation or the hitch moves to the first interactive frame.

Avoid routine synchronous flushes

Calling FlushAsyncLoading immediately after an async request recreates the Game Thread stall it was meant to avoid. It is easier to justify at startup, in a fully non-interactive transition, or in deterministic editor and automation workflows.

If a synchronous boundary is unavoidable, start early, keep the mandatory set small, and wait only for the remaining tail. LoadSynchronous is not safe merely because the directly referenced asset looks small; its hard-reference graph may be large.

Tune IoStore, Zen Loader, and Oodle together

Zen Loader uses cooked dependency data and retrieves chunks from .utoc and .ucas containers. IoStore is the normal UE 5.8 packaged path.

Use Asset Registry for packaged discovery. Place custom data deliberately as a UE asset, staged UFS file, Non-UFS file, or Save/Download data; packaged Content is not a loose-file directory.

Inspect final layout when chunk placement looks wrong:

UnrealPak.exe IoStore -Describe=<Global.ucas> -DumpToFile=Output.txt

Encrypted containers also need -CryptoKeys=<Crypto.json>.

Compression trades storage reads for decode CPU. Oodle Method changes the main size/decode-speed tradeoff; Level changes encoder effort and output size without selecting another runtime decoder. Smaller output can still reduce reads and patch size.

Method	General tendency
Kraken	Strong compression and good decode speed; useful baseline
Mermaid	Less compression, faster decode
Selkie	Favors decode speed further
Leviathan	Smaller data is possible, with slower decode

Compare total time, decode CPU, container size, bytes read, and peak memory on weak-CPU and weak-storage targets. No compression may remove decode work while increasing I/O, download, and patch size.

World Partition is not only Cell Size

Small cells increase request count; large cells include unnecessary Actors. Tune for movement speed, visibility, Actor density, and storage. Before adding Runtime Grids, use HLOD Layers, Data Layers, and spatial loading.

For teleports, create a World Partition Streaming Source at the destination before moving the player:

Configure grid, priority, and target state.
Load during a fade, door animation, or elevator ride.
Move after streaming completion.
Disable the temporary source and release the old area.

Direct references between distant Actors can couple their cells. Replace them with IDs, events, or subsystem queries where appropriate.

Increasing wp.Runtime.MaxLoadingLevelStreamingCells may shorten elapsed time while raising CPU, memory, and registration peaks. Measure gameplay and transitions separately. UE 5.8 includes World Partition Insights; use branch-appropriate tools on older versions.

Optimize activation and second-stage resources

A completed read can still be followed by expensive spawning, registration, collision, and overlap work.

Consider ISM/HISM for repeated static geometry.
Avoid excessive Actor counts for non-gameplay decoration.
Remove always-present Components that are rarely needed.
Avoid global Actor searches and synchronous loads in BeginPlay.
Delay nonessential initialization until later frames or proximity.

Initial overlap calculation can be expensive. Evaluate UpdateOverlapsMethodDuringLevelStreaming and “Generate Overlap Events During Level Streaming” per class: decoration may not need it, while triggers may depend on it.

A package can be loaded while presentation data is still missing:

Textures: prioritize critical UI and near-field mips; do not mark everything Never Stream.
Audio: stream long assets, but prepare the first chunk for sounds that must start immediately.
Shaders/PSOs: use PSO Precaching or Pipeline Cache for materials guaranteed to appear at startup.

Prepare mandatory presentation data and continue optional resources in the background.

Custom files need Read, Decode, and Apply stages

Many worker tasks using synchronous file APIs can still create competing small reads. Choose storage first, then the API:

Small text: FFileHelper::LoadFileToStringAsync.
Large sequential processing without one full allocation: FFileHelper::LoadFileInBlocks.
Async offset-and-size reads: IAsyncReadFileHandle::ReadRequest.
Custom cooked chunks: consider FIoDispatcher with Asset Registry and chunk rules.

LoadFileInBlocks calls a visitor for sequential blocks. It avoids retaining the whole file, but does not guarantee asynchronous I/O. Keep it off the Game Thread. Use IAsyncReadFileHandle::ReadRequest for true async range reads.

Validate size and read requests; a non-null OpenAsyncRead handle is not full success. Keep each IAsyncReadRequest alive until completion and define one owner for the handle, request, and buffer.

Use this pipeline:

Read: obtain bytes with async I/O.
Decode: decompress, validate, and parse on a worker.
Apply: create or update necessary UObjects on the Game Thread.

Keep parsed data in plain structures until Apply. Avoid retaining compressed input, decompressed output, and final objects simultaneously. For random access, index the format and read only required ranges.

Prefetch from player intent and control memory overlap

Distance-only prefetch is unreliable with fast movement and branching paths. Strong signals include a confirmed stage, destination, character selection, door sequence, matchmaking result, quest update, or server instruction.

Scale requests to confidence: hover may load a portrait, confirmation loads Gameplay, and an irreversible transition loads voice. Track hit rate, time hidden, wasted bytes, and residency because wrong predictions still consume work.

Preloading the next stage while retaining the old one can overlap working sets and trigger GC or OS pressure:

Prefetch the new minimum set while the old scene remains visible.
Stop expensive old-scene systems after the fade begins.
Release old handles and references.
Place necessary GC in a known non-interactive interval.
Activate the new scene and continue optional loading.

Use Memory Insights before adding more manual GC. Compare peak memory beside total time when tuning concurrency.

Fast Geometry Streaming is not the default answer

UE 5.8 improves the Experimental Fast Geometry Streaming plugin for static, non-gameplay assets. It may help very large static worlds, but does not replace reference cleanup, Asset Manager, World Partition, or gameplay Actor loading. Validate platform and workflow constraints before adoption.

A practical workflow

Fix device, build, storage, and starting state; record median, p95, worst hitch, and peak memory.
Classify Read, Decode, Deserialize, and Activate in Insights.
Remove unnecessary hard references and define mandatory/immediate/later/optional bundles.
Add intent-driven preloading and Gameplay, Transition, and Tail budgets.
Compare IoStore, Oodle, mips, audio, and PSOs under identical conditions.
Add regression limits for dependency size, transition time, hitch, and memory.

Conclusion

UE5 loading performance is not determined by one concurrency number.

The largest wins usually come from loading fewer dependencies and dividing assets by experience phase.
Parallel I/O and a higher FPS cap should follow measurement of I/O, CPU, Game Thread, and memory behavior.
IoStore, Oodle, World Partition, activation, texture residency, audio, PSOs, and GC all affect perceived loading.
Custom data needs explicit Read, Decode, Apply, cancellation, and ownership boundaries.

Find the slow stage in Unreal Insights and why each asset is reachable in Reference Viewer. Apply parallelism, prefetching, budgets, and compression only where measurements support them. The goal is to become interactive without a large hitch afterward.

References

Checked against UE 5.8 documentation on August 9, 2026. For another engine version, verify the matching documentation and Engine Source.

Editorial disclosure: this English edition was prepared with AI-assisted translation and editing from a technically reviewed Japanese draft. The technical claims and code excerpts were reviewed against the references above before publication.

Where Unity Burst and Jobs Actually Help: A Practical Guide for GameObject-Based Projects

GameDevToolLab — Sat, 22 Aug 2026 09:14:06 +0000

Introduction

Burst Compiler and the C# Job System can solve CPU bottlenecks, but they are not performance switches. Scheduling, copying, immediate Complete() calls, and unclear NativeContainer ownership can easily erase the gain.

In a GameObject-based project, performance depends on which calculation you isolate, which data crosses the managed boundary, and when the main thread waits. This article focuses on that boundary rather than a full ECS migration or Job syntax basics.

The baseline is Unity 6.3 LTS, Burst 1.8.30, Collections 2.6.8, and Mathematics 1.3.3 as of August 2026. Examples use IJobFor and ScheduleParallelByRef. ByRef avoids a large scheduling-time struct copy, although workers still use local copies. Older Unity versions may expose different overloads.

The code demonstrates design boundaries, not a compiled drop-in sample. Validate it with Safety Checks, a Development Build, and the Profiler on target hardware.

When Burst and Jobs are a good fit

Burst and Jobs fit workloads with many independent elements, substantial CPU work, contiguous value-type data, little Unity API access inside the kernel, and useful work available before the result is needed.

Good candidates include movement, projectiles, FOV tests, LOD or culling, AI scoring, procedural geometry, noise, grids, and bulk processing. Deterministic server or replay workloads need cross-platform reproducibility tests.

Poor candidates include small collections, Unity-API-heavy or immediate-result logic, managed-object-heavy processing, and cases where marshaling costs more than calculation. A compute shader may suit very large data-parallel work better.

Ask: can you isolate a large enough calculation kernel that is closed over value-type data?

Understand the four separate roles

Burst Compiler optimizes supported C# kernels into native code; it does not create multithreading.
C# Job System schedules work and tracks dependencies, with its own overhead.
NativeContainer exposes shared data under Unity's ownership and safety rules.
Unity.Mathematics provides Burst-friendly numerical types and functions.

Prepare data, schedule execution, and optimize the kernel as separate concerns.

Four questions before introducing Jobs

Is CPU computation really the bottleneck?

Profile first. Jobs do not fix frames dominated by rendering, physics, GC, asset loading, or synchronous I/O.

Is each element independent?

IJobFor.Execute(int index) has no guaranteed order. Shared accumulation should become per-index output followed by a reduction.

Can the managed boundary stay small?

Measure input collection and result application. A faster worker kernel can still make the frame slower.

Can waiting be delayed?

Immediate Complete() removes most overlap. Schedule early, consume next frame, or chain dependencies and wait only for the final handle.

Start with `IJobFor` and fixed-index output

For a new parallel loop, begin with input and output that use the same index.

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;
using Unity.Mathematics;

[BurstCompile]
public struct IntegratePositionJob : IJobFor
{
    [ReadOnly] public NativeArray<float3> Velocities;
    public NativeArray<float3> Positions;
    public float DeltaTime;

    public void Execute(int index)
    {
        float3 position = Positions[index];
        Positions[index] = position + Velocities[index] * DeltaTime;
    }
}

var job = new IntegratePositionJob
{
    Velocities = velocities,
    Positions = positions,
    DeltaTime = deltaTime
};

JobHandle handle = job.ScheduleParallelByRef(
    positions.Length,
    innerloopBatchCount: 64,
    dependency: default);

A NativeContainer indexer is not a ref return, so “read, modify, write back” is the clearest default for structures. The outer owner allocates and disposes the arrays and must call Complete() before reading or disposing data still owned by a job. [ReadOnly] and fixed-index output also make the access pattern explicit to the Safety System.

Practical example: target evaluation with one-frame latency

Consider a lock-on system that scores targets by distance, field of view, and threat. The main thread snapshots Transform data into persistent NativeArrays and consumes the job next frame. A version prevents stale results from reaching changed or removed targets.

Input, output, and the job

using Unity.Burst;
using Unity.Collections;
using Unity.Jobs;
using Unity.Mathematics;

public struct TargetInput
{
    public float3 Position;
    public float Threat;
    public byte IsActive;
}

public struct TargetEvaluation
{
    public float DistanceSq;
    public float Score;
    public byte IsCandidate;
}

[BurstCompile]
public struct EvaluateTargetsJob : IJobFor
{
    [ReadOnly] public NativeArray<TargetInput> Inputs;
    [WriteOnly] public NativeArray<TargetEvaluation> Outputs;

    public float3 ObserverPosition;
    public float3 ObserverForward;
    public float MaxDistanceSq;
    public float CosHalfFieldOfView;

    public void Execute(int index)
    {
        TargetInput input = Inputs[index];
        float3 toTarget = input.Position - ObserverPosition;
        float distanceSq = math.lengthsq(toTarget);
        bool isNearlySamePosition = distanceSq <= 0.0001f;
        float3 direction = math.normalizesafe(toTarget);
        float facing = isNearlySamePosition
            ? 1.0f
            : math.dot(ObserverForward, direction);

        bool candidate =
            input.IsActive != 0 &&
            distanceSq <= MaxDistanceSq &&
            facing >= CosHalfFieldOfView;

        float distanceSq01 = math.saturate(
            distanceSq / math.max(MaxDistanceSq, 0.0001f));

        Outputs[index] = new TargetEvaluation
        {
            DistanceSq = distanceSq,
            Score = candidate
                ? input.Threat * 2.0f + facing - distanceSq01
                : float.NegativeInfinity,
            IsCandidate = (byte)(candidate ? 1 : 0)
        };
    }
}

The job receives no managed references and writes only to matching output indices. Near-zero-distance targets pass the FOV test; tune the threshold for your scale. float.NegativeInfinity is an internal sentinel, so use Score only when IsCandidate != 0.

Define the target contract

public abstract class TargetAgent : MonoBehaviour
{
    public abstract float Threat { get; }
    public abstract int EvaluationVersion { get; }
    public abstract void ApplyEvaluation(float score, bool isCandidate);
}

Read Threat before scheduling, increment EvaluationVersion when relevant state changes, and call ApplyEvaluation only on the main thread.

This example allows one frame of stale _maxDistance or _fieldOfView. That may suit lock-on assistance, LOD, or visual filtering, but not damage, server validation, deterministic replays, or ranking logic. Those paths need a request ID or deterministic synchronization.

This is a design excerpt, not a drop-in sample. Registration APIs, capacity growth, the complete TargetAgent, and tests are omitted.

using System.Collections.Generic;
using Unity.Collections;
using Unity.Jobs;
using Unity.Mathematics;
using UnityEngine;

public sealed class TargetEvaluationSystem : MonoBehaviour
{
    [SerializeField] private Transform _observer;
    [SerializeField] private List<TargetAgent> _targets =
        new List<TargetAgent>();
    [SerializeField, Min(1)] private int _capacity = 1024;
    [SerializeField, Min(0f)] private float _maxDistance = 30f;
    [SerializeField, Range(1, 179)] private float _fieldOfView = 100f;

    private NativeArray<TargetInput> _inputs;
    private NativeArray<TargetEvaluation> _outputs;
    private TargetAgent[] _scheduledTargets;
    private int[] _scheduledVersions;
    private JobHandle _pending;
    private int _pendingCount;
    private bool _isDisposed;

    private void Awake()
    {
        int capacity = math.max(1, _capacity);
        _inputs = new NativeArray<TargetInput>(
            capacity, Allocator.Persistent,
            NativeArrayOptions.UninitializedMemory);
        _outputs = new NativeArray<TargetEvaluation>(
            capacity, Allocator.Persistent,
            NativeArrayOptions.UninitializedMemory);
        _scheduledTargets = new TargetAgent[capacity];
        _scheduledVersions = new int[capacity];
    }

    private void Update()
    {
        CompleteAndApply();
        if (_isDisposed || !isActiveAndEnabled || _observer == null)
            return;

        int targetCount = _targets.Count;
        Debug.Assert(
            targetCount <= _inputs.Length,
            "Target count exceeds NativeArray capacity.");
        int count = math.min(targetCount, _inputs.Length);
        for (int i = 0; i < count; i++)
        {
            TargetAgent target = _targets[i];
            _scheduledTargets[i] = target;
            _scheduledVersions[i] =
                target != null ? target.EvaluationVersion : 0;

            if (target == null || !target.isActiveAndEnabled)
            {
                _inputs[i] = default;
                continue;
            }

            Vector3 p = target.transform.position;
            _inputs[i] = new TargetInput
            {
                Position = new float3(p.x, p.y, p.z),
                Threat = target.Threat,
                IsActive = 1
            };
        }

        if (count == 0)
            return;

        Vector3 op = _observer.position;
        Vector3 forward = _observer.forward;
        float maxDistanceSq = _maxDistance * _maxDistance;

        var job = new EvaluateTargetsJob
        {
            Inputs = _inputs,
            Outputs = _outputs,
            ObserverPosition = new float3(op.x, op.y, op.z),
            ObserverForward = math.normalizesafe(
                new float3(forward.x, forward.y, forward.z)),
            MaxDistanceSq = maxDistanceSq,
            CosHalfFieldOfView = math.cos(
                math.radians(_fieldOfView * 0.5f))
        };

        _pending = job.ScheduleParallelByRef(count, 64, default);
        _pendingCount = count;
    }

    private void CompleteAndApply()
    {
        int count = _pendingCount;
        if (count == 0)
            return;

        _pending.Complete();
        _pendingCount = 0;

        try
        {
            for (int i = 0; i < count; i++)
            {
                TargetAgent target = _scheduledTargets[i];
                int version = _scheduledVersions[i];

                if (target == null ||
                    !target.isActiveAndEnabled ||
                    target.EvaluationVersion != version)
                {
                    continue;
                }

                TargetEvaluation value = _outputs[i];
                target.ApplyEvaluation(
                    value.Score, value.IsCandidate != 0);

                if (_isDisposed || !isActiveAndEnabled)
                    break;
            }
        }
        finally
        {
            ClearScheduledReferences(count);
        }
    }

    private void OnDisable() => CompleteWithoutApply();

    private void OnDestroy()
    {
        _isDisposed = true;
        CompleteWithoutApply();
        if (_inputs.IsCreated)
            _inputs.Dispose();
        if (_outputs.IsCreated)
            _outputs.Dispose();
    }

    private void CompleteWithoutApply()
    {
        int count = _pendingCount;
        if (count == 0)
            return;

        _pending.Complete();
        _pendingCount = 0;
        ClearScheduledReferences(count);
    }

    private void ClearScheduledReferences(int count)
    {
        System.Array.Clear(_scheduledTargets, 0, count);
        System.Array.Clear(_scheduledVersions, 0, count);
    }
}

The next Update completes the previous job before reusing the arrays. Removal code must also advance the target version.

finally clears managed references but does not swallow exceptions. This sample is fail-fast; a system that must continue should catch individual callbacks and define recovery.

Capacity overflow triggers Debug.Assert; production code should define a hard limit or resize only after the pending job completes.

Build pipelines instead of isolated jobs

Pass one job's handle into the next instead of completing between stages. Use JobHandle.CombineDependencies when several independent jobs feed one later stage. Keep data in NativeContainers through evaluation and reduction, then copy only the smallest required result back to GameObjects.

Do not let parallel iterations update one shared maximum. Write one score per index, then run a dependent single IJob reduction. A linear final pass is often cheap and gives deterministic tie-breaking.

Variable-length output and `ParallelWriter`

Use a container-specific writer when parallel iterations append results.

[ReadOnly] public NativeArray<TargetEvaluation> Evaluations;
public NativeList<int>.ParallelWriter CandidateIndices;

public void Execute(int index)
{
    if (Evaluations[index].IsCandidate != 0)
        CandidateIndices.AddNoResize(index);
}

AddNoResize requires enough Capacity before scheduling. When reusing the list, complete the previous writer, call Clear() on the main thread, verify Capacity, and schedule again.

Parallel append order is undefined. If order affects state, sort afterward, compact fixed flags in source order, or preserve source indices with an explicit tie rule.

NativeContainer lifetime and batch size

Use Temp for extremely short-lived data, TempJob for short jobs disposed within four frames, and Persistent for explicitly owned buffers. For every-frame work, allocate persistent capacity once and reuse it. One owner should control allocation, the outstanding handle, resizing, and disposal. Never resize or dispose while a job may access the memory; call Complete() even when IsCompleted is true. See the NativeContainer manual.

Batch size also needs measurement. Start around 64 for light work, 16 or 32 for medium work, and 1 for expensive iterations; compare average time, worst frames, and the wait at Complete().

GameObjects, Transforms, and data boundaries

A Burst job cannot directly access a normal GameObject or MonoBehaviour.

Snapshot values: copy Transform data into NativeArrays. This suits multi-stage numerical pipelines, but collection and application costs must be measured.

Use IJobParallelForTransform: process a TransformAccessArray. Use read-write scheduling when modifying Transforms and read-only scheduling when reading; read-only jobs may receive invalid entries, so check TransformAccess.isValid. Frequent additions and removals make maintenance and index mapping part of the cost. See IJobParallelForTransformExtensions.

Write kernels Burst can optimize

Keep managed references outside the kernel and copy only required values before scheduling. Prefer Unity.Mathematics and squared-distance comparisons for numerical work.

Do not enable FloatMode.Fast automatically. Approximate visuals may tolerate it; replay, server validation, and cross-device agreement require error and reproducibility tests.

Per-element FunctionPointer<T> calls retain overhead and can block wider vectorization. Prefer direct job code or batched calls; see Burst's Function Pointer guidance.

Treat Safety System errors as design feedback. Prefer fixed-index output, dependency chains, staged reductions, or supported writers before disabling restrictions. Pass mutable settings through the job struct, not mutable static state.

Invalidate results instead of canceling jobs

A scheduled job cannot be interrupted halfway through. When a result becomes obsolete, let the job finish and reject it with a generation or request ID. Split very long work into shorter jobs. This is usually safer than a cancellation flag because the main thread cannot freely mutate shared job memory after scheduling.

Measure the complete system

Compare a normal C# loop, RunByRef, ScheduleByRef, and ScheduleParallelByRef. Measure collection, scheduling, Complete() wait, result application, and the whole frame. Reject the design if the kernel improves but the full boundary becomes slower.

Profile after Burst warm-up and decide in a Development Build on target hardware. For WaitForJobGroup, inspect Timeline: completion timing, scheduling timing, dependency serialization, worker occupancy, and Burst compilation.

A practical adoption sequence

Extract numerical work from MonoBehaviour.Update
Express inputs and outputs as value-type arrays
Validate results, disposal, invalidation, and scene transitions with RunByRef or ScheduleByRef
Switch to ScheduleParallelByRef and measure batch size and independence
Schedule earlier and delay Complete()
Split work into dependent jobs only when profiling supports it

Common failures are per-frame allocation, immediate completion, many tiny jobs, excessive copying, suppressed safety errors, and assumed output order. Fix data and synchronization before adding more jobs.

Conclusion

With Burst and the Job System, data boundaries and synchronization matter more than syntax.

Keep Unity API access outside the kernel
Reuse NativeContainers and complete jobs before reading, resizing, or disposal
Chain work instead of waiting immediately
Validate stale results and variable output order explicitly
Measure the entire path on target hardware

Start with many similar elements and a result that can tolerate one frame of latency. Expand only where profiling proves a benefit.

References

This article was created with AI-assisted drafting. The author reviewed the technical content and makes the final publication decision.

Unity Mipmaps Beyond Smaller Textures: Temporal Stability, Streaming, and Semantic Mips

GameDevToolLab — Wed, 19 Aug 2026 07:31:55 +0000

Introduction

Mipmaps are usually introduced as smaller copies of a texture. That is correct, but it does not explain why a no-mipmap screenshot looks sharp while motion shimmers, why foliage disappears, why normal-mapped highlights flash, or why an atlas bleeds only in lower levels.

A more useful model treats a mip chain as three things:

A tool for temporal image stability.
A mechanism for allocating bandwidth and resident memory.
A hierarchy whose levels can preserve different kinds of meaning.

This article uses Unity 6.5 (6000.5) terminology. Inspector names can differ in Unity 2022/2023 LTS, other Unity 6 versions, and between URP and HDRP package versions.

Mipmaps Match Sampling Density, Not Distance

Imagine a 4096 x 4096 texture on a floor viewed at a shallow angle. One screen pixel may cover hundreds of texels. Sampling only mip 0 selects a tiny subset of that footprint, so a small camera movement selects a different subset and produces crawling detail, moire, and flicker.

A mipmap selects a texel density closer to the projected footprint. Distance matters, but it is not the rule. Projected size, UV scale, surface angle, texture resolution, projection, bias, and anisotropy all affect the result.

For ordinary implicit sampling, the GPU estimates UV change across neighboring fragments. In simplified form:

rho = max(length(ddx(texelPosition)), length(ddy(texelPosition)))
lod = log2(rho)

An LOD near 0 points to mip 0; near 1 points to mip 1. Hardware is more sophisticated, especially with anisotropy, but the key model is: screen-space UV derivatives drive mip selection.

Bilinear, trilinear, and anisotropic filtering solve different problems

Bilinear: blends texels inside one mip.
Trilinear: blends two adjacent mips.
Anisotropic: handles elongated footprints on oblique surfaces.

Trilinear filtering does not replace anisotropic filtering. A road may need anisotropic sampling even when mip transitions are smooth.

Ideal LOD and resident quality are separate

The sampler may want mip 0 while Streaming currently has only mip 2 and coarser levels resident. This explains why a surface can be blurry after a camera cut and sharpen later. Always separate the ideal sample LOD from the highest-resolution mip actually available in GPU memory.

The 33% Cost Hides a More Useful Fact

For a square texture, the complete chain is approximately:

Mip 0: 4096 x 4096
Mip 1: 2048 x 2048
Mip 2: 1024 x 1024
...
Mip 12: 1 x 1

Each level contains one quarter as many texels as the previous one:

1 + 1/4 + 1/16 + 1/64 + ... = 4/3

So a full mip chain adds about 33% more texels than mip 0 alone. The reverse view is more useful for budgeting:

Range	Approximate share of the full chain
Mip 0	75.00%
Mip 1	18.75%
Mip 2	4.69%
Mip 3	1.17%
Mip 4 and below combined	0.39%

Mip 0 alone is roughly three quarters of the chain. Dropping the maximum resolution by one level does not halve the texel count; it reduces the remaining chain to about one quarter. Two levels reduce it to about one sixteenth.

Compression blocks, minimum mip storage, alignment, and platform details change exact byte counts, but this approximation explains why Mipmap Limits and Mipmap Streaming can have such large effects.

Why “No Mipmaps” Can Win a Screenshot Comparison

Disabling mipmaps can sharpen one frame while making motion unstable. Test fine grids, gravel, leaves, thin text, and repeating patterns with a slow, repeatable camera pan. Temporarily disabling TAA can help isolate texture aliasing.

Watch for crawling patterns, distant moire, flashing highlights, oblique-surface noise, and discontinuities between render scales. Mipmaps are spatial prefilters, but in practice they are also temporal noise reduction. Judge negative mip bias the same way: in motion, not from one sharp frame.

Configure Import Settings by Meaning, Not File Extension

Two PNG files can require opposite settings. Decide from what the shader expects the texels to mean.

Texture meaning	sRGB	Mipmaps	Main concern
Base color / ordinary emissive color	Usually on	Usually on in 3D	Alpha coverage; HDR/data exceptions
Normal map	Import as Normal Map	Usually on	Average direction loses normal variance
Roughness / metallic / AO	Off	Often on	Numerical meaning after filtering
Material ID / category	Off	Use cautiously	Averaging can invent invalid IDs
Fixed-size UI	Usually on	Often unnecessary	Reconsider for scaling, rotation, world space
Pixel art	Pipeline-dependent	Usually off or custom	Point sampling and integer scaling
Lookup/data texture	Off	Usually off	Automatic averaging may corrupt data

sRGB is semantic

Base color is normally color. Roughness, metallic, AO, height, vectors, coefficients, LUT values, and masks are normally linear data. HDR textures and emissive maps that store numerical intensity are common exceptions. Because mip generation is filtering, the wrong color space changes the meaning of lower levels.

Box, Kaiser, and negative bias

Unity's Box filter is smoother; Kaiser retains more sharpness and potentially more shimmer. Negative bias also selects higher-resolution levels, increasing aliasing, bandwidth, cache pressure, and streaming demand. Before using it globally, check anisotropic filtering, UV density, source resolution, render scale, and the active upscaler.

Failure Case 1: Foliage and Fences Disappear

An alpha-tested shader may contain:

clip(alpha - 0.5);

A thin leaf may be alpha 1 against alpha 0. Downsampling creates boundary values such as 0.4, which fail a 0.5 cutoff. The average is not mathematically wrong; the area that survives the threshold, or coverage, changed between mip levels.

Unity's Preserve Coverage adjusts lower levels to keep coverage more stable. Match its cutoff to the shader and check the base pass, shadow-caster pass, Shader Graph threshold, LOD materials, and any Alpha To Coverage path. If the object remains visible but its shadow thins, inspect the shadow pass first.

Replicate Border is different: it preserves image-edge values for cases such as light cookies. It does not replace Preserve Coverage.

Failure Case 2: Normal Maps Still Produce Flashing Highlights

Mipmapping averages normal directions, but an average normal does not describe their distribution. Equal left- and right-facing normals may average forward; that does not make the region smooth. It means variance was discarded. Keeping the original smoothness can then create a sharp, unstable specular lobe around the average direction.

Treat normal filtering and specular stability separately:

import the normal map correctly and give it mipmaps;
keep roughness/smoothness linear;
feed lost normal variance into roughness when possible;
consider HDRP's Geometric Specular Anti-Aliasing;
in custom shaders, reduce smoothness from normal variation or LOD.

MSAA mainly addresses polygon edges. TAA can hide some instability, but unstable input often trades shimmer for blur or ghosting. Stabilize the material before temporal reconstruction.

Failure Case 3: Packed Masks Share One Mip Policy

Packing metallic, AO, roughness, and other masks into RGBA reduces samples and memory, but all channels still share mip generation, filtering, wrap mode, sRGB state, compression, Mipmap Limit Group, streaming priority, and bias.

Mip filtering operates on channel values, while compression error is not guaranteed to be independent per channel. More importantly, sampling and residency policy are selected at texture granularity. Pack values because they can share that policy, not merely because a channel is empty.

Data	Desired reduction behavior
AO	Smooth aggregation may be acceptable
Roughness	Specular energy matters, not only arithmetic mean
Binary mask	Preserve area, majority, or max depending on meaning
Material ID	Never invent an intermediate category
Signed direction	May require renormalization or reinterpretation

For IDs and categories, consider a separate non-mipmapped texture, point sampling, custom majority/max mips, or a buffer/spatial structure.

Failure Case 4: Atlas Bleeding Gets Worse at Lower Mips

Four pixels of mip-0 padding become two in mip 1, one in mip 2, and half a pixel in mip 3:

effective padding at mip L ~= mip 0 padding / 2^L

Design padding for the lowest level you expect to use. Dilate island colors, increase padding, keep UVs inside their islands, and distinguish texture-edge problems from neighbors inside the atlas.

A Texture2DArray isolates layers and avoids much atlas bleeding, but Unity's Mipmap Streaming does not support array textures. Balance visual stability, batching, streaming, and platform support.

Hand-authored lower mips can go further: detailed sign text can become a bold pictogram at distance. That is the basis of semantic mipmaps.

Mipmap Limits and Streaming as a Quality Scheduler

A Mipmap Limit caps allowed quality; Mipmap Streaming decides which allowed levels are resident. Group textures by visual importance, such as CharacterHero, CharacterCrowd, WorldNear, WorldFar, and Cinematic. One removed top level has a large effect because mip 0 was about 75% of the chain.

Priority is relative, not a reservation for mip 0. A budget shortage can prevent a requested level from loading, so never wait forever. This is a small cutscene-oriented example; a general preloader also needs ownership, cancellation, limit handling, camera-change handling, destruction safety, and budget monitoring.

using System.Collections;
using UnityEngine;

public sealed class MipmapPreloader : MonoBehaviour
{
    [SerializeField] private Texture2D[] textures = { };
    [SerializeField, Min(0)] private int requestedLevel;
    [SerializeField, Min(0.1f)] private float timeoutSeconds = 3f;

    public IEnumerator Preload()
    {
        foreach (Texture2D texture in textures)
            if (CanStream(texture))
                texture.requestedMipmapLevel = Mathf.Clamp(
                    requestedLevel, 0, texture.mipmapCount - 1);

        float deadline = Time.realtimeSinceStartup + timeoutSeconds;
        while (Time.realtimeSinceStartup < deadline)
        {
            bool complete = true;
            foreach (Texture2D texture in textures)
                if (CanStream(texture))
                    complete &= texture.IsRequestedMipmapLevelLoaded();

            if (complete)
                yield break;

            yield return null;
        }

        Debug.LogWarning("Mip preload timed out; continuing with fallback quality.");
    }

    public void Release()
    {
        foreach (Texture2D texture in textures)
            if (CanStream(texture))
                texture.ClearRequestedMipmapLevel();
    }

    private void OnDisable() => Release();

    private static bool CanStream(Texture2D texture) =>
        texture != null && texture.streamingMipmaps;
}

Define the timeout fallback: continue at lower quality, extend a fade, or reduce the request. Release control after the cutscene. Centralize ownership because one caller's ClearRequestedMipmapLevel can clear another caller's expectation.

Unity estimates required levels from meshes, UVs, cameras, and standard material conventions. Array textures, cubemap arrays, and 3D textures are unsupported by Mipmap Streaming; custom drawing and nonstandard UV transforms also need verification.

Success is not “Streaming is enabled.” It is that required-mip estimation and the memory budget remain valid during real camera motion on target hardware.

Visualize the Approximate Mip Level

Subjective reports such as “slightly blurry on one device” are easier to investigate when approximate LOD is visible.

float ApproximateMipLevel(float2 uv, float4 texelSize)
{
    // texelSize = (1/width, 1/height, width, height)
    float2 texelPosition = uv * texelSize.zw;
    float2 dx = ddx(texelPosition);
    float2 dy = ddy(texelPosition);
    float footprint2 = max(dot(dx, dx), dot(dy, dy));
    return max(0.5 * log2(max(footprint2, 1e-8)), 0.0);
}

Color floor(lod) bands to reveal UV-density discontinuities, material bias differences, oblique surfaces, dynamic-resolution changes, and the mip where an atlas starts bleeding.

This is diagnostic, not an exact sampler result. Real sampling also accounts for anisotropy, bias, and platform details. Calculate derivatives before divergent per-fragment branches whenever possible.

Technique 1: Semantic Mipmaps

A mip level can carry a representation designed for its scale rather than an automatic reduction. I will call this a semantic mipmap.

replace a shop name with its icon at distance;
remove minor roads from lower map levels;
thicken selection or emissive marks in coarse mips;
fade a detail normal toward neutral;
reduce a binary mask by majority or max instead of average.

This is texture LOD: the representation changes, not only its resolution.

Trilinear filtering blends adjacent levels. If mip 2 is text and mip 3 is an icon, the transition contains both. Design blendable levels, transition over several mips, use explicit LOD, or blend separate textures.

Filter and wrap modes are semantic too. A sign may use Trilinear and Clamp; an ID hierarchy may require Point or explicit LOD. Point filtering stops interpolation but cannot repair a mip generated with the wrong reduction rule.

Texture2D.SetPixelData can write every level. The critical detail is Apply(updateMipmaps: false); otherwise Unity regenerates the chain from mip 0.

using System;
using System.Collections.Generic;
using UnityEngine;

public static class SemanticMipTextureBuilder
{
    public static Texture2D Create(
        int width,
        int height,
        IReadOnlyList<Color32[]> mips,
        bool linear,
        FilterMode filterMode,
        TextureWrapMode wrapMode)
    {
        if (width <= 0)
            throw new ArgumentOutOfRangeException(nameof(width));
        if (height <= 0)
            throw new ArgumentOutOfRangeException(nameof(height));

        int expected = Mathf.FloorToInt(
            Mathf.Log(Mathf.Max(width, height), 2f)) + 1;

        if (mips == null || mips.Count != expected)
            throw new ArgumentException($"Exactly {expected} mip levels are required.");

        int mipWidth = width;
        int mipHeight = height;
        for (int level = 0; level < expected; level++)
        {
            if (mips[level] == null || mips[level].Length != mipWidth * mipHeight)
                throw new ArgumentException($"Mip {level} has an invalid pixel count.");

            mipWidth = Mathf.Max(1, mipWidth >> 1);
            mipHeight = Mathf.Max(1, mipHeight >> 1);
        }

        var texture = new Texture2D(
            width, height, TextureFormat.RGBA32,
            mipChain: true, linear: linear)
        {
            filterMode = filterMode,
            wrapMode = wrapMode
        };

        for (int level = 0; level < expected; level++)
            texture.SetPixelData(mips[level], level);

        texture.Apply(updateMipmaps: false, makeNoLongerReadable: false);
        return texture;
    }
}

For shipped assets, an editor or external pipeline that generates levels before platform compression is often easier to manage. Use makeNoLongerReadable: true when the CPU no longer needs the texture.

Technique 2: Use the Mip Chain as a Hierarchical Data Structure

A mip chain repeatedly aggregates each 2 x 2 region. The reduction need not be an average:

Average: luminance, exposure, bloom;
Min / Max: regional extrema;
Depth pyramid: occlusion and screen-space effects;
Occupancy: reject empty coarse regions before reading detail;
Variance: preserve mean and dispersion.

For custom reduction, create a mipmapped RenderTexture, disable autoGenerateMips, and dispatch a compute shader from level 0 to 1, then 1 to 2. GenerateMips performs ordinary generation; it does not express max, majority vote, or arbitrary aggregation.

This is only an outline. Enable enableRandomWrite before creation, verify GraphicsFormat random-write support, bind the destination mip with ComputeShader.SetTexture(..., mipLevel), define ordering and synchronization, and test every target graphics API.

Mip 0: source 16 x 16
  -> max over each 2 x 2 block
Mip 1: 8 x 8 -> Mip 2: 4 x 4 -> Mip 3: 2 x 2 -> Mip 4: 1 x 1

A coarse occupancy level can terminate a search before fine reads. For depth pyramids, min/max meaning reverses between conventional Z and reversed Z.

Technique 3: Automate Import Rules by Semantic Suffix

Many mip failures are configuration drift. Avoid an ambiguous _mask suffix and split conventions by reduction behavior:

_orm: continuous linear data with mipmaps;
_cutout: alpha-tested color with Preserve Coverage;
_coverage: linear coverage data with Preserve Coverage;
_binary / _id: discrete values, no automatic mipmaps, point filtering;
separate suffixes for majority, max, or authored semantic mips.

using UnityEditor;
using UnityEngine;

public sealed class TextureImportConvention : AssetPostprocessor
{
    public override uint GetVersion() => 2;

    private void OnPreprocessTexture()
    {
        var importer = (TextureImporter)assetImporter;
        string path = assetPath.Replace('\\', '/').ToLowerInvariant();

        if (path.Contains("/textures/world/"))
        {
            importer.mipmapEnabled = true;
            importer.filterMode = FilterMode.Trilinear;
            importer.streamingMipmaps = true;
        }

        if (HasSuffix(path, "_orm"))
        {
            importer.sRGBTexture = false;
            importer.mipmapEnabled = true;
            importer.filterMode = FilterMode.Trilinear;
        }

        if (HasSuffix(path, "_cutout") || HasSuffix(path, "_coverage"))
        {
            importer.mipmapEnabled = true;
            importer.filterMode = FilterMode.Trilinear;
            importer.mipMapsPreserveCoverage = true;
            importer.alphaTestReferenceValue = 0.5f;

            if (HasSuffix(path, "_coverage"))
                importer.sRGBTexture = false;
        }

        if (HasSuffix(path, "_binary") || HasSuffix(path, "_id"))
        {
            importer.sRGBTexture = false;
            importer.mipmapEnabled = false;
            importer.streamingMipmaps = false;
            importer.filterMode = FilterMode.Point;
        }
    }

    private static bool HasSuffix(string path, string suffix) =>
        path.EndsWith($"{suffix}.png") || path.EndsWith($"{suffix}.tga");
}

Place this in an Editor folder or editor-only assembly. Keep the cutoff synchronized with the shader. Separate mandatory rules, first-import defaults, and convention warnings. Increment GetVersion() when behavior changes.

Dynamic Resolution, Upscalers, and Mip Bias

Lower internal resolution changes UV derivatives and can select coarser mips. A strong global negative bias may sharpen a still image while increasing shimmer, bandwidth, and streaming pressure.

Check the active pipeline and upscaler first. HDRP provides Use Mip Bias for Dynamic Resolution, and its DLSS integration can apply automatic correction. URP/HDRP, DLSS/FSR/STP, package versions, and custom shaders do not apply bias in the same place, so avoid correcting it twice at pipeline, texture, and shader levels.

Compare stationary detail, slow-pan shimmer, GPU time, streaming-budget pressure, and render-scale transitions on one camera path. Output sharpening and sampler bias are different: one modifies the reconstructed image; the other introduces higher-frequency texture input.

A Practical Decision Flow

Will it shrink or rotate on screen? Use mipmaps for most 3D textures; reconsider UI that scales, rotates, or enters world space.
Color or data? Use sRGB for ordinary color, linear for numerical data, and the Normal Map importer for normals.
Alpha tested? Match Preserve Coverage with every shader pass that clips.
Viewed obliquely? Try anisotropic filtering before negative bias.
Atlased? Derive padding and dilation from the lowest required mip.
Memory constrained? Prefer Mipmap Limit Groups and Streaming over disabling mipmaps globally.
Does averaging preserve meaning? Use ordinary generation for color-like signals, Preserve Coverage for cutouts, custom min/max/majority reduction for special data, and semantic mips when the representation should change.

Common Mipmap Myths

Myth	Better model
Distance alone selects the mip	Screen-space UV derivatives select the ideal LOD
No mipmaps means higher quality	It may sharpen a still frame while increasing temporal aliasing
Trilinear fixes an oblique floor	Anisotropic footprints need anisotropic filtering
A mip chain nearly doubles memory	The theoretical increase is about 33%; mip 0 is about 75% of the chain
High priority guarantees mip 0	Requests can lose to the memory budget
Normal mipmaps guarantee stable highlights	Average direction does not preserve normal variance
Any empty packed channel is free	All channels share filtering, compression, and residency policy
Atlas padding is a mip-0 decision	Effective padding halves at every level
Mips must be automatic reductions	Levels can contain semantic replacements or custom aggregates

Conclusion

Mipmaps connect image stability, bandwidth, resident memory, material semantics, and scalable representation. The central question is:

When this texture becomes smaller on screen, what information must survive?

Color may need an average; foliage needs coverage; normals need variance; IDs need category integrity; signs need readability; hierarchical depth needs min or max. Treat every level as a deliberate representation, and mipmaps become a design tool rather than an import checkbox.

References

Is LitMotion the Best Tween Library for Unity in 2026? A Practical Guide

GameDevToolLab — Tue, 18 Aug 2026 10:19:47 +0000

DOTween has been the default answer for Unity tweening for years, and it is still a very strong library. But for a new code-driven project, I would no longer choose it automatically.

After using LitMotion recently, I found its API especially comfortable: Transform values, UI values, and custom values all follow the same Create -> With -> Bind pattern. LitMotion v2 also adds Sequence support, Inspector editing through LitMotion.Animation, debugging tools, and improved cancellation/control APIs.

This article compares LitMotion, PrimeTween, and DOTween, then shows the parts of LitMotion I consider important in production: setup, MotionHandle, object lifetime, Time.timeScale, Sequence, UniTask, Punch/Shake, TextMeshPro, and migration design.

The version information here was checked on July 28, 2026. Recheck release pages if you read this much later.

My recommendation

Situation	Recommendation
New project, animation logic mainly in C#	LitMotion
Very sensitive to tween CPU/GC cost	Benchmark LitMotion and PrimeTween in your real workload
Prefer `Tween.Position()`-style target APIs	PrimeTween
Want short Inspector-edited animations	Evaluate LitMotion.Animation, PrimeTween PRO, and DOTween Pro
Existing project already uses DOTween heavily	Usually keep DOTween
Third-party assets depend on DOTween	Keep DOTween, or strictly separate ownership

For a new code-first project, LitMotion is currently my first candidate.

It emphasizes low-allocation tween creation, uses the C# Job System and Burst, supports arbitrary values, and keeps a consistent API. It is MIT licensed and supports Unity 2021.3 or later.

That does not mean your whole animation path becomes allocation-free. Capturing lambdas, strings, LINQ, async code, Canvas rebuilds, and whatever you do in the binding still matter.

At the research date, LitMotion's latest release was v2.0.2. PrimeTween was also actively maintained, so I consider it a serious alternative rather than a secondary option.

LitMotion, PrimeTween, and DOTween

LitMotion

LitMotion is a data-oriented tween library built around LMotion.

LMotion.Create(0f, 1f, 0.3f)
    .WithEase(Ease.OutCubic)
    .Bind(x => alpha = x);

Create a value transition, add options, then bind it to a target. The same structure works for Transform, UI, TextMeshPro, and your own values.

LitMotion v2 adds LSequence, LitMotion.Animation, TryCancel() / TryComplete() style handle control, and LitMotion Debugger.

PrimeTween

PrimeTween is also designed around modern, low-allocation usage, but its API feels more target-oriented.

Tween.PositionY(
    transform,
    endValue: 10f,
    duration: 1f,
    ease: Ease.InOutSine);

Starting from Tween. is very discoverable in an IDE. If you prefer choosing a target operation first, PrimeTween may feel more natural than LitMotion.

DOTween

DOTween remains excellent when you already have production code and tools around it.

transform.DOMoveX(10f, 0.5f)
    .SetEase(DG.Tweening.Ease.OutCubic);

It has a mature ecosystem, many shortcuts, strong Sequence support, and DOTween Pro. If your project already depends on those strengths and profiling shows no problem, migration can easily cost more than it saves.

What about MagicTween?

MagicTween's repository was archived in 2025 and points users toward LitMotion. I would not choose MagicTween for a new project.

Do not choose from a benchmark alone

The author's public TweenPerformance project shows strong LitMotion results in its tested environment, including very low allocation during tween creation.

But benchmark versions differ from the current libraries, the environment is specific, and real games also pay for bindings, Canvas work, closures, strings, async state machines, materials, and game-specific logic.

Use benchmarks as a hint. Make the final decision from a Player build on your target hardware.

Installing LitMotion

For LitMotion v2.0.2, the package requirements are:

Unity 2021.3+
Burst 1.6.0+
Collections 1.5.1+
Mathematics 1.0.1+

Add the package through Unity Package Manager. In a team project, pin a tag or commit.

https://github.com/annulusgames/LitMotion.git?path=src/LitMotion/Assets/LitMotion#v2.0.2

The ?path=... part comes before #v2.0.2.

Typical namespaces are:

using LitMotion;
using LitMotion.Extensions;

UniTask integration requires com.cysharp.unitask. TextMeshPro integration requires TMP. If you use custom asmdefs, verify references to LitMotion, LitMotion.Extensions, UniTask, and Unity.TextMeshPro as needed.

The snippets in this article are based on LitMotion v2.0.2's public API and source. I would still compile representative examples in a minimal Unity project before adopting them as team standards.

The core pattern: Create, configure, Bind

LMotion.Create() returns a builder. The motion becomes useful when you configure it and finally bind it.

LMotion.Create(0f, 1f, 0.3f)
    .WithEase(Ease.OutCubic)
    .Bind(x => alpha = x);

For a Transform:

LMotion.Create(target.position, destination, 0.4f)
    .WithEase(Ease.OutCubic)
    .BindToPosition(target)
    .AddTo(target.gameObject);

For an arbitrary value:

LMotion.Create(volume, 1f, 0.5f)
    .WithEase(Ease.Linear)
    .Bind(x => volume = x)
    .AddTo(gameObject);

A capturing lambda can allocate. If this is a hot path, use a state-passing overload instead:

LMotion.Create(volume, 1f, 0.5f)
    .Bind(this, (x, self) => self.volume = x)
    .AddTo(gameObject);

For built-in properties, dedicated BindTo...() helpers are usually clearer.

Ease, delay, and loops

Builder options compose naturally:

LMotion.Create(0f, 1f, 0.25f)
    .WithDelay(0.1f)
    .WithEase(Ease.OutBack)
    .Bind(x => value = x);

List entrance effects are easy to stagger:

for (var i = 0; i < items.Length; i++)
{
    var item = items[i];

    LMotion.Create(0f, 1f, 0.25f)
        .WithDelay(i * 0.04f)
        .WithEase(Ease.OutCubic)
        .BindToLocalScaleXYZ(item)
        .AddTo(item.gameObject);
}

For infinite loops:

LMotion.Create(0.95f, 1.05f, 0.5f)
    .WithLoops(-1, LoopType.Yoyo)
    .BindToLocalScaleXYZ(transform)
    .AddTo(gameObject);

-1 means the motion does not end by itself, so always provide a lifetime through object destruction, a stored handle, or cancellation.

`MotionHandle`: stop old animations before starting new ones

Bindings return a MotionHandle.

public void Replay()
{
    handle.TryCancel();

    handle = LMotion.Create(0f, 1f, 0.4f)
        .WithEase(Ease.OutCubic)
        .Bind(x => value = x);
}

Use TryComplete() when you want to apply the final value instead of stopping at the current one.

The bigger design issue is property ownership. If open/close, hover, selection, and click feedback all write the same Scale or Alpha, they can fight each other even if every individual tween is valid.

private MotionHandle fadeHandle;

public void SetVisible(bool visible)
{
    fadeHandle.TryCancel();

    fadeHandle = LMotion.Create(
            canvasGroup.alpha,
            visible ? 1f : 0f,
            0.2f)
        .WithEase(Ease.OutCubic)
        .BindToAlpha(canvasGroup)
        .AddTo(gameObject);
}

Starting from the current value also avoids a jump when the animation reverses halfway through.

`AddTo(gameObject)` and CancellationToken are different tools

For UI and temporary objects, I normally tie a motion to its owner:

LMotion.Create(0f, 1f, 1f)
    .Bind(x => value = x)
    .AddTo(gameObject);

AddTo(gameObject) cancels the motion when the GameObject is destroyed. It is lifetime ownership, not async-flow control.

LitMotion v2.0.2's ToUniTask(token) uses CancelBehavior.Cancel with cancelAwaitOnMotionCanceled: true. If you want the intent visible in code, write it explicitly:

await handle.ToUniTask(
    CancelBehavior.Cancel,
    cancelAwaitOnMotionCanceled: true,
    cancellationToken: token);

If token cancellation should move the motion to its end value, use CancelBehavior.Complete.

Decide whether a screen token, GameObject lifetime, explicit handle, or caller token owns the animation. Do not add all of them blindly and assume they mean the same thing.

UI animation while `Time.timeScale == 0`

Pause menus often still need animation after gameplay time is stopped.

LMotion.Create(0f, 1f, 0.2f)
    .WithScheduler(MotionScheduler.UpdateIgnoreTimeScale)
    .WithEase(Ease.OutCubic)
    .BindToAlpha(canvasGroup)
    .AddTo(gameObject);

Useful schedulers include normal Update, UpdateIgnoreTimeScale, FixedUpdate, and the PreLateUpdate / PostLateUpdate families.

The scheduler also changes ordering relative to other scripts, so verify camera, layout, and physics interactions instead of treating this as only a time-scale switch.

Sequence for fixed timelines

LitMotion v2 provides LSequence:

var sequenceHandle = LSequence.Create()
    .Append(
        LMotion.Create(0f, 1f, 0.25f)
            .WithEase(Ease.OutCubic)
            .BindToAlpha(canvasGroup))
    .Join(
        LMotion.Create(0.9f, 1f, 0.25f)
            .WithEase(Ease.OutBack)
            .BindToLocalScaleXYZ(panel))
    .AppendInterval(0.15f)
    .Append(
        LMotion.Create(
                panel.localPosition.y,
                panel.localPosition.y + 20f,
                0.2f)
            .WithLoops(2, LoopType.Yoyo)
            .BindToLocalPositionY(panel))
    .Run()
    .AddTo(gameObject);

Append() is sequential, Join() is parallel, Insert() places a motion at a specific time, and AppendInterval() adds a wait. Run() starts the sequence.

If initial values are being applied too early while assembling a sequence, consider WithImmediateBind(false).

Sequence is best for a fixed timeline. Input waits, network waits, branching, and complex cancellation are usually clearer in async code or a state machine.

UniTask: `await handle` and `ToUniTask()` do not cancel the same way

LitMotion supports directly awaiting a MotionHandle, but in v2.0.2 await handle; resumes on either completion or cancellation, and MotionAwaiter.GetResult() does not throw.

If you need CancellationToken integration or want motion cancellation to propagate as async cancellation, use ToUniTask().

A UI animation that can be triggered repeatedly can share one linked CTS so the next play request cancels the previous one:

private CancellationTokenSource playCts;

public async UniTask PlayAsync(CancellationToken cancellationToken)
{
    playCts?.Cancel();

    var currentCts = CancellationTokenSource
        .CreateLinkedTokenSource(cancellationToken);
    playCts = currentCts;
    var token = currentCts.Token;

    try
    {
        var fade = LMotion.Create(canvasGroup.alpha, 1f, 0.25f)
            .BindToAlpha(canvasGroup)
            .AddTo(gameObject);

        var scale = LMotion.Create(panel.localScale.x, 1f, 0.3f)
            .WithEase(Ease.OutBack)
            .BindToLocalScaleXYZ(panel)
            .AddTo(gameObject);

        await UniTask.WhenAll(
            ToCancelableUniTask(fade, token),
            ToCancelableUniTask(scale, token));
    }
    finally
    {
        if (ReferenceEquals(playCts, currentCts))
            playCts = null;

        currentCts.Dispose();
    }
}

private static UniTask ToCancelableUniTask(
    MotionHandle handle,
    CancellationToken token)
{
    return handle.ToUniTask(
        CancelBehavior.Cancel,
        cancelAwaitOnMotionCanceled: true,
        cancellationToken: token);
}

When a new call cancels the previous PlayAsync(), the previous caller observes cancellation. If that is normal UI control flow, handle it at a clear boundary:

try
{
    await resultPanelAnimation.PlayAsync(token);
}
catch (System.OperationCanceledException)
{
    // Re-entry, screen transition, or destruction is normal here.
}

The important point is not to hide cancellation semantics. Decide where cancellation becomes a normal result.

Punch and Shake

Punch is useful for button feedback:

var baseScale = buttonTransform.localScale;

LMotion.Punch.Create(baseScale, Vector3.one * 0.15f, 0.3f)
    .WithFrequency(8)
    .WithDampingRatio(1f)
    .BindToLocalScale(buttonTransform)
    .AddTo(buttonTransform.gameObject);

The second argument is strength, not an end value. Do not pass Vector3.zero as the start value unless you intentionally want to oscillate around zero scale.

Shake works similarly:

var basePosition = cameraRoot.localPosition;

LMotion.Shake.Create(basePosition, new Vector3(8f, 8f, 0f), 0.35f)
    .WithFrequency(20)
    .WithDampingRatio(1f)
    .WithRandomSeed(123)
    .BindToLocalPosition(cameraRoot)
    .AddTo(cameraRoot.gameObject);

For cameras, a dedicated shake-offset transform is often safer than letting Cinemachine, follow code, recoil, and shake all write the same transform.

TextMeshPro integration

LitMotion can animate fixed-size strings:

LMotion.String.Create128Bytes(
        "",
        "<color=#FFD54F>MISSION COMPLETE</color>",
        1.2f)
    .WithRichText()
    .WithScrambleChars(ScrambleMode.Uppercase)
    .BindToText(messageText)
    .AddTo(messageText.gameObject);

128 is a byte capacity, not a character count. Localized Japanese text, emoji, and RichText tags can consume more space than a short English sample. Choose capacity from the longest production string.

Numeric binding is also convenient:

LMotion.Create(0, 9999, 0.8f)
    .WithEase(Ease.OutCubic)
    .BindToText(scoreText)
    .AddTo(scoreText.gameObject);

Formatted binding is supported too:

LMotion.Create(0f, 100000f, 1f)
    .BindToText(scoreText, "{0:N2}")
    .AddTo(scoreText.gameObject);

The standard formatted path uses string.Format(), so it can allocate. If this is a hot path, consider the documented ZString integration and profile the full UI update cost.

LitMotion.Animation for Inspector workflows

LitMotion.Animation is a separate package:

https://github.com/annulusgames/LitMotion.git?path=src/LitMotion/Assets/LitMotion.Animation#v2.0.2

When using Git URL dependencies, I prefer pinning both core and animation packages to the same tag explicitly:

{
  "dependencies": {
    "com.annulusgames.lit-motion": "https://github.com/annulusgames/LitMotion.git?path=src/LitMotion/Assets/LitMotion#v2.0.2",
    "com.annulusgames.lit-motion.animation": "https://github.com/annulusgames/LitMotion.git?path=src/LitMotion/Assets/LitMotion.Animation#v2.0.2"
  }
}

It supports Edit Mode and Play Mode previews and is useful for short Prefab-specific animation tuning.

I would still define a team boundary: keep shared duration, ease, and cancellation conventions in code or configuration, and leave only local presentation tuning to the Inspector.

Common production mistakes

A few problems matter more than the exact tween API:

Forgetting to bind: LMotion.Create(...).WithEase(...) is only a builder until you call Bind() / BindTo...().
Multiple motions write one property: separate ownership or cancel the previous handle.
Infinite loops have no shutdown: combine them with object lifetime, a handle, or cancellation.
Pause UI stops: use an ignore-time-scale scheduler only where appropriate.
"Zero allocation" is interpreted too broadly: closures, strings, async code, and Unity systems still allocate or consume CPU.
Everything goes into Sequence: use async/state machines for branching and external waits.

LitMotion Debugger (Window > LitMotion Debugger) is useful for finding duplicate motions and missing cancellation. Use it in Editor Play Mode; profile final CPU/GC with the debugger disabled in a Player build.

Migrating from DOTween

Simple cases are easy to rewrite:

// DOTween
transform.DOMove(targetPosition, 0.5f)
    .SetEase(DG.Tweening.Ease.OutCubic);

// LitMotion
LMotion.Create(transform.position, targetPosition, 0.5f)
    .WithEase(LitMotion.Ease.OutCubic)
    .BindToPosition(transform)
    .AddTo(gameObject);

The real migration risk is behavior around the one-liner. Review:

Kill vs cancel behavior;
whether cancellation keeps the current value or applies the final value;
Sequence behavior;
update timing and Time.timeScale;
relative tweens;
DOTween Pro data;
third-party integrations and internal wrappers.

Migrate feature by feature, not library-wide, and never let two tween systems own the same property at the same time.

Adoption checklist

Before standardizing LitMotion in a team, I would verify:

Unity/Burst/Collections/Mathematics requirements;
custom asmdef references for LitMotion, extensions, UniTask, and TMP;
Git dependencies pinned to a tag or commit;
current LitMotion Releases and PrimeTween Changelog;
representative snippets compiled in a minimal Unity project;
third-party assets and internal tooling dependencies;
cancellation rules for destruction, reopening, and repeated input;
which animations ignore Time.timeScale;
Sequence vs async/await conventions;
Player-build CPU and GC on target hardware.

Also test cancellation halfway through, object destruction, rapid reversal, and repeated clicks—not only normal completion.

Conclusion

For a new Unity project in 2026 where tween logic is mainly written in C#, LitMotion is the first library I would evaluate.

Its Create -> With -> Bind model is consistent across Transform values, arbitrary data, TextMeshPro, Punch/Shake, Sequence, and UniTask integration. LitMotion v2 also addresses many of the practical features that once made mature alternatives easier to justify by default.

PrimeTween remains a strong alternative, especially if target-oriented APIs fit your team better. DOTween is still the pragmatic choice for projects that already have a working DOTween ecosystem.

Whichever library you choose, the production problems are usually property ownership, re-entry, cancellation, object lifetime, time scale, and the code around the tween—not the number of characters in the tween call.

References

Official docs and source

Releases and benchmarks

WAV Is Not Automatically High Quality in Unity: PCM, ADPCM, Vorbis, and Load Types

GameDevToolLab — Fri, 14 Aug 2026 11:52:56 +0000

Scope

This article is based mainly on the Unity 6.5 documentation available on August 4, 2026. I did not run device benchmarks or controlled listening tests. Treat every recommendation as a starting point, then verify it in a Player build on the target device with the actual maximum voice count, the Audio Profiler, and representative speakers or headphones.

WAV is only the source

Importing a high-quality WAV file does not guarantee that the shipped game plays the same uncompressed waveform.

WAV is an input container. Unity can convert it to PCM, ADPCM, Vorbis, MP3, or another platform-supported format. Load Type then decides whether Unity keeps decoded samples in memory, keeps compressed data in memory and decodes during playback, or reads the clip progressively from storage.

The runtime result depends on the combination:

source file
× Compression Format
× Quality / Sample Rate / channels
× Load Type
× Preload Audio Data / Load In Background
× simultaneous playback
× target platform

This is why “WAV means high quality,” “Vorbis always saves memory,” and “Streaming is always lighter” are unreliable rules.

In this article, BGM means background music and SFX means sound effects.

Practical starting points

Use case	Format	Load Type	Channels	Why
Long BGM	Vorbis	Streaming	Stereo	The start is predictable, and full decoded residency is avoided
Short jingle	Vorbis or PCM	Compressed In Memory or Decompress On Load	Stereo	Streaming overhead may not be worthwhile for a few seconds
UI click	PCM	Decompress On Load	Depends	It should follow an unpredictable input without runtime I/O
Footstep, weapon, impact	ADPCM or PCM	Start with Decompress On Load	Mono	It should follow gameplay events without playback-time decoding
Medium SFX	Vorbis	Compressed In Memory	Depends	A middle ground between decoded memory and CPU
Typical dialogue	Vorbis	Compressed In Memory	Mono candidate	The next line can be prefetched
Long narration	Vorbis	Streaming	Mono candidate	Several minutes do not need to be fully decoded
Battle bark	PCM or ADPCM	Decompress On Load	Mono candidate	Combat feedback should start immediately

These are baselines for native builds, not final presets. Web builds require a separate policy.

Keep three decisions separate

Source file

The file under Assets: WAV, AIFF, MP3, Ogg Vorbis, FLAC, and so on. Prefer an uncompressed or lossless production master. Converting MP3 to WAV does not restore discarded information, and encoding that WAV to Vorbis adds another lossy generation.

Compression Format

PCM, ADPCM, and Vorbis affect build size, compression artifacts, compressed-data size, and decoding cost.

Load Type

Decompress On Load, Compressed In Memory, and Streaming decide where data lives and when decoding and storage access occur.

Compression Format and Load Type are independent. A Vorbis clip using Decompress On Load is decoded during loading, so “Vorbis” alone does not imply low runtime memory.

PCM, ADPCM, and Vorbis

PCM

PCM is uncompressed. It avoids lossy artifacts and playback-time decompression, making it a simple choice for tiny, timing-critical sounds.

A rough payload estimate is:

bytes per second
= sample rate × bytes per sample × channel count

A 44.1 kHz, 16-bit stereo clip lasting 60 seconds is about 10.1 MiB before Unity-specific buffers. PCM is easy to justify for a click, but expensive as a blanket policy for music.

ADPCM

ADPCM is smaller than PCM and generally cheaper to decode than Vorbis. Unity documents roughly 3.5:1 compression compared with PCM and suggests footsteps, impacts, and weapon sounds as examples.

It can expose artifacts in tonal or smooth content. Also, ADPCM + Decompress On Load still needs decoded sample memory after loading; the compression ratio does not produce the same reduction in runtime memory.

Vorbis

Vorbis offers a quality setting that trades size against audible loss. It is a common candidate for BGM, dialogue, narration, ambience, and medium-to-long effects.

With Compressed In Memory, decoding contributes to mixer work. With Streaming, work moves to the streaming path. Test difficult material such as cymbals, sibilance, reverb tails, quiet ambience, and high-frequency synthetic sounds.

Property	PCM	ADPCM	Vorbis
Compression	None	Lightweight fixed compression	High-ratio lossy compression
Build size	Large	About one third of PCM as a guideline	Often smaller than ADPCM
Playback CPU	Low	Moderate	Higher decoding cost
Good starting use	Tiny critical SFX	Footsteps, impacts, weapons	BGM, voice, medium/long SFX
Main risk	Long clips consume space and memory	Artifacts in tonal content	Many decoders can raise CPU

The three Load Types

Decompress On Load

Unity decodes the clip while loading it and keeps decoded samples available. It suits short clips where the decoded total is small and playback-time work or startup uncertainty matters more than memory.

Unity 6.5 gives rough warnings that decoded Vorbis can require about ten times the compressed size and ADPCM about 3.5 times. These are planning guidelines, not fixed measurements.

Compressed In Memory

Unity keeps compressed data in memory and decodes it during playback. This often fits medium SFX and dialogue libraries that are too large to keep fully decoded but too short to stream individually.

The trade-off is mixer-side CPU. Test the real worst case with effects, spatialization, pitch changes, and overlapping voices.

Streaming

Unity reads compressed data progressively from storage and decodes through the streaming path. It is a natural baseline for long BGM, narration, and ambience.

Streaming is not free. Unity 6.5 lists approximately 200 KB of overhead per streaming clip. Hundreds of short streams can therefore be worse than a few long ones. Profile Streaming CPU, Streaming File Memory, and Streaming Decode Memory in a Player build.

Load Type	Memory behavior	Playback work	Typical use
Decompress On Load	Holds decoded samples	Low decoding work during playback	Short, timing-critical SFX
Compressed In Memory	Holds compressed data	Decodes on the mixer path	Medium SFX and dialogue
Streaming	Avoids full decoded residency	Progressive I/O and decoding	BGM and long voice

Choose by playback timing, not only duration

Unpredictable gameplay sounds

A UI click, attack, perfect dodge, landing, hit confirmation, or Animation Event cannot always be scheduled ahead. Its timing is part of the control feedback.

Streaming introduces storage access, stream initialization, and buffering. This does not mean every streamed sound is always audibly late. It means there is little reason to add that I/O risk to a tiny sound whose main job is immediate response.

Start with:

Decompress On Load
+ Preload Audio Data enabled

If Preload is disabled, call LoadAudioData() early and verify loadState before gameplay. Decompress On Load alone does not guarantee that the first Play() call performs no loading work.

Predictable audio

BGM, narration, cutscene audio, and the next dialogue line normally have preparation time. Long clips can stream; shorter voice lines can stay compressed in memory and be prefetched.

For music and synchronized stems, use AudioSettings.dspTime and PlayScheduled() rather than frame timing. loadState == Loaded is only a minimum precondition: it does not guarantee that storage and decoding remain safe during scene loading, AssetBundle work, crossfades, or long playback.

BGM

For music lasting several minutes, start with Vorbis + Streaming + Stereo. Begin loading before the transition, check readiness, and schedule precise starts or crossfades. Test loop boundaries, two-track overlap, scene loading, slower storage, long playback, and suspend/resume.

Do not apply the same rule to a three-second logo sound. Compare Vorbis + Compressed In Memory with PCM/Vorbis + Decompress On Load; per-stream overhead may cost more than the clip justifies.

Adaptive music must be measured at the maximum stem count. Four outgoing stems overlapping four incoming stems can briefly create eight streams. Synchronized assets should share the intended sample rate, duration, and loop boundaries and be ready before the same DSP-time start is scheduled.

Addressables and AssetBundles are a separate I/O layer

Load Type = Streaming describes the AudioClip. It does not complete the distribution design.

Bundle grouping, bundle compression, local or remote placement, caching, pre-download, custom encryption, and concurrent loading all affect startup and I/O contention. AudioClip Vorbis compression and AssetBundle LZ4/LZMA compression are separate layers.

A remote BGM flow may look like this:

Download required dependencies
→ LoadAssetAsync<AudioClip>() and keep the handle
→ wait for the required audio-data preparation
→ schedule or start playback

Pre-downloading a bundle does not by itself mean that the AudioClip asset and its audio data are ready.

SFX

UI and action feedback

Use PCM + Decompress On Load as the baseline for tiny clicks, confirm/cancel sounds, attack starts, perfect-input feedback, and hit confirmation. Ensure the audio data is loaded before the player can trigger them.

If hundreds are resident, inspect the decoded total. Mono is a candidate when stereo carries no information, but do not automatically collapse deliberately stereo UI sounds.

Footsteps, impacts, and weapons

Short, noisy, frequently repeated sounds are good ADPCM candidates. Start with ADPCM + Decompress On Load + Mono, then evaluate the worst-case soundscape rather than one isolated clip: maximum enemies, surface variations, BGM, voice, effects, and the minimum-spec device.

Medium effects

Mechanical loops and cinematic effects lasting several to tens of seconds often justify testing Vorbis + Compressed In Memory. It reduces decoded residency but spends DSP CPU, so maximum concurrency decides whether it works.

Voice

Typical dialogue is usually a mono candidate unless stereo carries real information such as binaural recording or intentional movement. Listen for phase and normalization changes when using Force To Mono.

For lines lasting a few to several seconds, start with Mono + Vorbis + Compressed In Memory. If Preload is off, call LoadAudioData() while the current line plays and check loadState before advancing.

With Addressables, release responsibility should belong to the layer that owns the AudioClip. Keep the handle while an AudioSource, pool, scheduled playback, Timeline/Playable, or next-line queue still references it.

optionally pre-download the bundle
→ LoadAssetAsync<AudioClip>() and keep the handle
→ LoadAudioData() if required, then verify loadState
→ play the clip
→ finish playback and clear references or schedules
→ UnloadAudioData() if appropriate
→ release the handle

For several minutes of narration, use Mono + Vorbis + Streaming as the baseline and test interruption, seeking, suspend/resume, and long-session stability.

Battle barks behave more like SFX. Combat shouts and damage reactions should usually be prepared as PCM/ADPCM + Decompress On Load because delayed playback weakens feedback.

When runtime code needs AudioClip.GetData(), Unity 6.5 requires compressed audio to use Decompress On Load, and Streaming clips are unavailable through that path. For long streamed voice, generate visemes, amplitude envelopes, or subtitle timing offline and read that lightweight data at runtime.

Channels, sample rate, preload, and background loading

Converting stereo to mono roughly halves the sample count. Point-source 3D effects and typical dialogue are common candidates; music, wide ambience, and binaural content should normally remain stereo.

Begin with Preserve Sample Rate or Optimize Sample Rate. Override only after a category creates a meaningful size problem, then listen carefully to sibilance, metallic transients, high electronic tones, airy ambience, and clips pitched upward.

Preload Audio Data prepares audio data with the asset according to the import configuration. When disabled, the first Play() or PlayOneShot() can start loading unless runtime code explicitly loads it first. Disabling Preload is not an optimization by itself; it moves responsibility into code.

Load In Background can reduce main-thread blocking, but it does not guarantee immediate playback. A request made before completion can wait. Prefetch sounds with a required start time and use DSP scheduling for synchronization.

Practical presets

Preset	Format	Load Type	Preload	Mono	Main use
BGM_Long	Vorbis	Streaming	Usually Off	Off	Long-form BGM
BGM_Short	Vorbis	Compressed In Memory	Project-dependent	Off	Jingles
SFX_UI	PCM	Decompress On Load	On	Depends	UI feedback
SFX_Frequent	ADPCM	Decompress On Load	On	Candidate	Footsteps and impacts
SFX_Medium	Vorbis	Compressed In Memory	Project-dependent	Depends	Medium effects
Voice_Dialogue	Vorbis	Compressed In Memory	Usually Off with prefetch	Candidate	Dialogue
Voice_Bark	PCM/ADPCM	Decompress On Load	On	Candidate	Combat voice
Voice_Long	Vorbis	Streaming	Usually Off	Candidate	Narration

“Project-dependent” means the loading and distribution design decides. “Candidate” means a reasonable first comparison, not a rule.

Import automation: unverified template

Manual settings drift in a large project. AssetPostprocessor.OnPreprocessAudio() can encode a folder policy.

Important: This follows the public Unity 6.5 API shape but was not compiled or reimport-tested for this article. Validate compilation, target and non-target folders, reimport behavior, and Inspector results in a test project before adoption.

using System;
using UnityEditor;
using UnityEngine;

public sealed class ProjectAudioImportPolicy : AssetPostprocessor
{
    private const uint PolicyVersion = 1;
    public override uint GetVersion() => PolicyVersion;

    private void OnPreprocessAudio()
    {
        var importer = (AudioImporter)assetImporter;
        var settings = importer.defaultSampleSettings;
        settings.sampleRateSetting = AudioSampleRateSetting.PreserveSampleRate;

        if (IsUnder("Assets/Audio/BGM/Long/"))
        {
            importer.forceToMono = false;
            importer.loadInBackground = true;
            settings.preloadAudioData = false;
            settings.loadType = AudioClipLoadType.Streaming;
            settings.compressionFormat = AudioCompressionFormat.Vorbis;
            settings.quality = 0.8f;
        }
        else if (IsUnder("Assets/Audio/SFX/UI/"))
        {
            importer.forceToMono = false;
            importer.loadInBackground = false;
            settings.preloadAudioData = true;
            settings.loadType = AudioClipLoadType.DecompressOnLoad;
            settings.compressionFormat = AudioCompressionFormat.PCM;
        }
        else if (IsUnder("Assets/Audio/Voice/Dialogue/"))
        {
            // This template does not enforce a Normalize policy.
            importer.forceToMono = true;
            importer.loadInBackground = true;
            settings.preloadAudioData = false;
            settings.loadType = AudioClipLoadType.CompressedInMemory;
            settings.compressionFormat = AudioCompressionFormat.Vorbis;
            settings.quality = 0.7f;
        }
        else
        {
            return;
        }

        importer.defaultSampleSettings = settings;
    }

    private bool IsUnder(string folder) =>
        assetPath.StartsWith(folder, StringComparison.Ordinal);
}

The quality values are comparison starting points, not universal recommendations. Perform level-matched A/B listening and adjust per platform.

The template changes only three folders. Platform overrides can use SetOverrideSampleSettings(), but its return value should be checked because unsupported combinations can fail. It also does not force Normalize; verify that policy through Presets, the Inspector, or version-tested automation.

Automation does not replace judgment. It consistently applies a decision the team has already validated.

Platform overrides and Web

Windows, Android, iOS, and Web have different decoding performance, memory budgets, storage behavior, and implementation constraints. Use Default as a baseline, then override platforms that need a different policy.

For Web, Unity 6.5 documentation directs developers toward Compressed In Memory and Decompress On Load; do not blindly copy the native long BGM = Streaming rule. Browser and Unity behavior can change, so recheck the exact Unity version and supported browsers.

Browsers also generally require a click, tap, or key input before playback can begin. Initialize or resume audio after a user gesture, and test output latency and background-tab recovery separately. Load Type alone cannot solve these constraints.

Unity also documents a possible Web loop glitch caused by AAC encoding and a workaround involving at least 1,024 silent samples at the beginning of a WAV plus loop information in the smpl chunk. Verify it on the browsers you support.

Profile the built game

Connect the Audio Profiler to a Player build and reproduce the maximum realistic overlap.

Metric	What it helps explain
DSP CPU	Mixer, effects, and Compressed In Memory decoding
Streaming CPU	Streaming work
Total Audio Memory	Overall audio-engine allocation
Sample Sound Memory	Decoded sample residency
Streaming File / Decode Memory	Streaming buffers
Playing Audio Sources / Audio Voices	Playback and voice count
Virtual / Plays	Virtualization and unexpected repeats

more Decompress On Load   → watch Sample Sound Memory
more Compressed In Memory → watch DSP CPU
more Streaming            → watch Streaming CPU and memory

Memory can retain a high-water mark for reuse, so it may not return to the startup value immediately. Compare clean startup, maximum combat, repeated scene transitions, large dialogue sessions, and long play sessions.

Change one axis at a time. When comparing Load Types, keep format, quality, channels, sample rate, and simultaneous count fixed. Record the Unity version, platform, device, importer settings, clip count, total duration, CPU, memory, startup delay, underruns, loop problems, and audible differences.

Common mistakes

Mistake	Better interpretation
WAV means the shipped game is uncompressed	Unity re-encodes for the target platform
Everything should be PCM	Long clips inflate build size and decoded memory
ADPCM makes runtime memory 3.5 times smaller	Decompress On Load still needs decoded samples
Vorbis is always optimal	Many simultaneous decoders can raise CPU
Every short voice line should stream	Per-stream overhead accumulates
Turning Preload off fixes memory	It can move loading to the first playback request
Background loading means instant playback	Playback can wait for completion
BGM, SFX, and Voice are enough categories	Duration, concurrency, trigger timing, and platform matter

Production decision flow

Keep an uncompressed or lossless source master.
Classify clips by behavior: long/short BGM, UI/frequent/medium SFX, dialogue/bark/long voice.
Use PCM for tiny timing-critical sounds, test ADPCM for repeated noisy SFX, and use Vorbis as the default candidate for medium and long content.
Use Decompress On Load when the decoded total is small, Compressed In Memory when compressed residency is preferable, and Streaming for genuinely long predictable audio.
Preload input-, hit-, physics-, and animation-driven sounds instead of streaming them.
Review mono and sample-rate options by content, not folder name alone.
Prefetch dialogue and music; align synchronized assets and use PlayScheduled() for DSP-timeline starts.
Measure and listen on the minimum-spec device at maximum realistic load.

Conclusion

The runtime quality and cost of Unity audio are not decided when a WAV enters the Assets folder. Platform conversion, Compression Format, quality, sample rate, channel count, Load Type, preload policy, distribution pipeline, and concurrency determine the shipped result.

A reasonable first pass is:

long BGM: Vorbis + Streaming;
UI and action feedback: PCM + Decompress On Load + preloading;
footsteps, impacts, and weapons: test ADPCM and preload event-driven clips;
medium SFX: Vorbis + Compressed In Memory;
dialogue: Mono + Vorbis + Compressed In Memory with prefetching;
long narration: Mono + Vorbis + Streaming;
battle barks: PCM/ADPCM + Decompress On Load.

The final choice belongs to the real clip duration, loaded and playing counts, trigger timing, target device, profiler data, and listening result.

References

Where Unity Audio Reaches Its Limits: CRI ADX vs Wwise vs FMOD Studio

GameDevToolLab — Wed, 12 Aug 2026 03:54:52 +0000

Introduction

Unity can play, mix, stream, spatialize, schedule, and profile audio without third-party middleware. Many small and medium projects can ship with AudioSource, Audio Mixer, Audio Random Container, and modest supporting code.

Larger productions still adopt CRI ADX, Wwise, or FMOD Studio. The reason is usually not lower sound quality or automatically better performance. The practical boundary is this:

Can the game keep treating audio as clips triggered by code, or must audio behavior become independently authored data that sound designers can edit, package, profile, and validate?

Beyond that boundary, Unity can reproduce many features, but the team must maintain event definitions, parameter mapping, voice policy, content delivery, live tuning, validation, and diagnostics.

This article compares Unity 6.5 built-in audio, CRI ADX including ADX LE, Wwise 2025.1.9, and FMOD Studio 2.03. The fixed Wwise 2025.1.9 Public Library is used because Wwise 2026.1 was still beta on the research date. Version and licensing notes are based on official information checked on July 29, 2026; recheck current terms before release.

The conclusion first: operational complexity matters more than sound count

Option	Best fit	Main reason to choose it
Unity built-in audio	Small to medium, comparatively simple, programmer-led projects	Keep dependencies and tooling small
CRI ADX	Mobile or console titles with many voices and streams	Manage cues, compression, voice control, and delivery together
Wwise	Large projects with complex states, music, profiling, and several audio contributors	Formalize a scalable audio pipeline
FMOD Studio	Projects that value DAW-like authoring and fast device iteration	Build parameter-driven events quickly

Middleware deserves evaluation when several of these are firm requirements:

Sound designers must change layers, randomization, transitions, and mix behavior without a programmer.
One playback request represents an event rather than one clip.
Continuous game values such as RPM, health, or combat intensity affect sound.
Voice limits need category-specific survival rules.
Voice data must be delivered by language, chapter, event, or DLC.
Sound designers must tune and profile a running device build.
Codec, memory, and streaming policy must stay consistent across platforms.

As a screening rule rather than an official threshold, three or more clear requirements justify a vertical-slice comparison. One or two may still be simpler with a thin layer over Unity Audio.

What Unity's built-in audio already covers

Unity 6.5 already provides 2D/3D playback, attenuation, priority, Audio Mixer routing and effects, snapshots, exposed parameters, Audio Random Container, and scheduled playback. It also provides three load types, platform-specific compression, real and virtual voice limits, the Audio Profiler, spatializer plug-ins, and the Scriptable Audio Pipeline.

A random footstep, pause snapshot, streamed BGM, or voice virtualization does not by itself require middleware. Audio Random Container handles simple variation, but compound conditions still need a separate data model.

Use the Audio Mixer first

At minimum, separate major categories:

Master
├─ Music
├─ SFX
│  ├─ Player
│  ├─ Enemy
│  ├─ Environment
│  └─ UI
└─ Voice

This supports user volume, pause states, ducking, and category-specific processing. Once a Mixer parameter is set from script, snapshots no longer control that value until the override is cleared. Give exposed parameters explicit ownership: do not stack user volume, cinematic modifiers, pause or mute state, and accessibility adjustments onto one ambiguous value.

Choose load type by use case

Decompress On Load: short, frequent effects; higher memory, lower repeated decode work
Compressed In Memory: lower memory, more playback-time decode work
Streaming: long music and ambience

Unity documents useful scale estimates: decompressed Vorbis may use roughly ten times its compressed size, ADPCM roughly 3.5 times, and each streaming clip has about 200 KB of overhead. Decide from duration, concurrency, latency, memory, and target-device performance.

PlayScheduled can implement bar-aligned transitions and synchronized stems. The growing cost is ownership of BPM data, transition points, cancellation, preview, and debugging. Likewise, the Scriptable Audio Pipeline enables custom processing but does not provide event authoring, bank generation, localization packaging, live tuning, or a dedicated sound-design profiler; it also does not support Web platforms.

Where Unity Audio reaches its practical limit

There is no universal clip or voice count where Unity stops working. The practical limit is reached when maintaining the custom workflow costs more than integrating middleware.

1. A playback request becomes an event

_audioSource.PlayOneShot(hitClip);

This is enough until one hit requires non-repeating variations, weapon and surface selection, near and far layers, a critical layer, random pitch, an instance cap, and player-over-enemy priority.

The game now wants to post PlayerAttackHit with values such as Material=Metal and Critical=true. Middleware keeps selection, layers, randomization, voice limits, and mix behavior in authored data. Unity can do the same with ScriptableObjects and custom inspectors, but the team is then building a small middleware layer.

2. Every adjustment requires a programmer

If changing footstep variation or a music transition requires C#, Prefabs, Timeline, or scene-level sources, every adjustment becomes a designer-to-programmer handoff followed by another build and review. A few minutes saved once is trivial; the same loop repeated hundreds of times is not. Dedicated authoring and live connection move routine iteration to the sound designer.

3. Several states and values affect one sound

Vehicles may combine RPM, throttle, speed, surface, camera perspective, and damage. Action games combine combat intensity, enemy count, health, area, and weather. Custom implementations tend to scatter mappings, curves, and exceptions across scripts.

Wwise States, Switches, and RTPCs; FMOD parameters; and CRI ADX AISACs and selectors make the mapping from game state to audio behavior explicit and editable.

4. The hard problem is which voices survive

Unity has real and virtual voice limits plus AudioSource.priority. Middleware does not remove hardware limits. The difference appears when policy becomes specific: UI must survive, player voice outranks enemy chatter, one enemy may have one growl, distant footsteps virtualize, and over-limit events steal the oldest, quietest, or farthest instance. Event-, bus-, cue-, or pool-level rules are easier to author and inspect than one global priority value.

5. Audio becomes delivered content

Live games may split voices by language, chapter, or event; stream music; delete completed story data; and select codecs per platform. Unity plus Addressables can do this, but the team must connect groups to event definitions, languages, references, and lifetime.

CRI ACB/AWB files, Wwise SoundBanks, and FMOD Banks connect authoring to delivery units. Addressables does not make middleware lifetime automatic. For example, FMOD Banks still require explicit loading and unloading, required Master and Strings Banks, and awareness that releasing an AssetBundle does not unload a Bank.

6. You must explain why a sound is missing

Unity's Audio Profiler is useful for voice count, CPU, memory, and audibility. Complex projects may also need the posting object, selected parameter branch, virtualization or stealing reason, loaded localized waveform, Bank memory, and the effect of a live mix edit. Dedicated audio profiling lets the sound team investigate this directly instead of requesting new programmer logs.

CRI ADX: resource control and a workflow aligned with Japanese game production

CRI ADX uses CRI Atom Craft for authoring and generally exposes cues to the game. Its production toolkit includes AISACs for continuous control, selectors for discrete states, REACT for category interactions, ACB/AWB delivery units, HCA/HCA-MX codecs, voice pools, profiling, in-game preview, and Atom Craft Robot automation.

It is a strong candidate for mobile, console, live-service, and voice-heavy projects where compression, streaming, voice limits, and delivery must be designed together. Paid ADX plans include support; ADX LE does not include individual support.

Treat the Atom Craft project, generated files, Unity plug-in, and Cue Sheet lifetime as one pipeline. Define naming, generation ownership, and preview integration early.

As of July 29, 2026, ADX LE distribution required previous-year revenue and cumulative content revenue to remain at or below JPY 10 million. It also required self-publishing plus specified copyright and end-user license notices. The logo was recommended rather than mandatory. Projects outside those conditions, including publisher-distributed titles, need a paid agreement.

CRI's FAQ also states that paid ADX and ADX LE output data are not mutually compatible. A commercial project likely to exceed LE should discuss an evaluation license early.

Wwise: formalizing complex systems and scaling large pipelines

Wwise combines event authoring, game states, interactive music, spatial audio, SoundBanks, profiling, and automation.

Its State, Switch, and RTPC distinction is particularly useful:

State: a broad condition such as paused, underwater, or low health
Switch: an object-specific selection such as dirt, stone, or metal
RTPC: a continuous value such as RPM, health, or combat intensity

Music Segments, containers, transition rules, and stingers support beat-aware behavior. The authoring tool can connect to builds to inspect game objects, voices, memory, streaming, and SoundBanks. WAAPI enables bulk registration, object creation, and validation from external tools.

Wwise fits projects with several audio contributors, many states, complex music or spatial audio, deep runtime analysis, and automation. The trade-off is organizational weight. Define Game Object lifetime, naming, SoundBank split and lifetime, Work Unit source control, build configuration, and the Wwise/Unity Integration update procedure at the start.

Licensing varies across non-commercial, limited-commercial, commercial core, support, and optional features. Confirm budget, platforms, plug-ins, and support before production costs are locked.

FMOD Studio: authoring speed with an approachable structure

FMOD Studio builds events through a timeline and parameter sheets, then packages them into Banks. Its DAW-like presentation often gives composers and sound designers a direct route into implementation.

Parameters can be Continuous, Discrete, or Labeled; built-in values include distance, direction, and elevation. Events can switch and layer sources while automating gain, pitch, filters, and effects. Live Update connects Studio to a running game for immediate inspection and tuning.

Transition Markers and Regions, Magnet Regions, Loop Regions, and Tempo Markers support conditional, beat-aware music. Instance limits can steal the oldest, quietest, or farthest instance, or virtualize it.

FMOD fits teams that value fast parameter and music iteration. Establish naming for events, Banks, parameters, buses, and snapshots before content grows, and keep Studio and Unity Integration versions aligned. FMOD generally recommends disabling Unity's built-in audio system, so staged migration needs a defined coexistence period.

As of July 29, 2026, game licensing listed:

Indie: below a USD 600,000 development budget, free or USD 2,000
Basic: USD 600,000 to USD 1.8 million, USD 6,000
Premium: above USD 1.8 million, USD 18,000

The Free Indie License also required annual revenue below USD 200,000. Commercial projects require registration, and plan conditions include logo requirements. Verify the current EULA and budget definitions before contracting.

Production-oriented comparison

This is a practical assessment, not an official ranking. Team experience, outsourcing partners, genre, and existing pipeline can reverse several rows.

Requirement	Unity built-in	CRI ADX	Wwise	FMOD Studio
Low initial integration cost	Excellent	Fair	Fair	Good
Work entirely inside Unity	Excellent	Fair	Fair	Fair
Independent sound-designer iteration	Limited	Excellent	Excellent	Excellent
Randomization, layers, and branching	Good	Excellent	Excellent	Excellent
Continuous parameter-driven audio	Limited	Excellent	Excellent	Excellent
Complex interactive music	Limited	Good–Excellent	Excellent	Excellent
Voice limiting and virtualization	Good	Excellent	Excellent	Excellent
Compression, streaming, and delivery units	Good	Excellent	Excellent	Excellent
Live tuning and dedicated profiling	Limited–Good	Excellent	Excellent	Excellent
Large-scale automation	Limited	Good–Excellent	Excellent	Good–Excellent
Low learning and operating cost	Excellent	Good	Limited	Good
Japanese-language onboarding	Good	Excellent	Good	Limited–Good
Predictable external license cost	Excellent	Limited	Limited	Good

Do not count “Excellent” cells. In a small project, breadth becomes training, build, and version-management cost. Unity's smaller feature set is valuable when it keeps ownership simple. Support experience also varies by region, reseller, contract, outsourcing company, and internal expertise.

Compare lifetime ownership, not free versus paid

A custom Unity Audio layer may begin at a few hundred lines, but its real cost includes custom editors, Unity-version maintenance, validation, voice policy, Addressables lifetime, profiling views, documentation, staff turnover, and platform investigation.

Middleware adds SDK and native plug-in updates, tool training, generated-content management, platform integration, licenses, and compatibility among runtime, authoring tool, Unity integration, and Banks.

In either case, separate editable sources from generated output, assign loading ownership, pin compatible versions, define rollback, remove profiling connections from release builds, and divide programmer, sound designer, and build-owner responsibilities. Compare total cost across the title's lifetime.

Choosing by project type

Small premium 2D game: start with Unity Audio and a small logical-event layer.
Voice-heavy mobile live service: evaluate CRI ADX and design Cue Sheets by language, chapter, and event early.
Mid-sized PC or console title with dedicated audio staff: FMOD Studio is a practical vertical-slice candidate.
Large action RPG with complex music and spatial audio: evaluate Wwise and assign a technical audio owner.

For contract work, the client's or publisher's existing standard often matters more than a feature-table advantage. Naming, content split, contracts, handoff procedure, and internal expertise are production assets.

Abstract audio before `AudioSource` calls spread everywhere

If middleware may be introduced later, avoid calling AudioSource or product-specific APIs throughout gameplay code.

using UnityEngine;

public readonly struct AudioEventId
{
    public string Value { get; }
    public AudioEventId(string value) => Value = value;
}

public readonly struct AudioHandle
{
    public int Value { get; }
    public AudioHandle(int value) => Value = value;
}

public interface IGameAudio
{
    AudioHandle Play(
        AudioEventId eventId,
        Vector3 position,
        GameObject emitter = null);

    void Stop(AudioHandle handle, float fadeSeconds = 0f);
    void SetParameter(AudioHandle handle, string name, float value);
    void SetGlobalParameter(string name, float value);
    void SetState(string group, string state);
}

This is only a boundary example. Production code also needs asynchronous Bank or Cue Sheet loading, failures, cancellation, handle validity, playback completion, emitter lifetime, and unloading during scene transitions.

Gameplay posts a logical event such as SFX/Player/SwordHit. A Unity implementation maps it to a container or clip; ADX to a cue; Wwise to an Event; FMOD to an Event Reference.

Centralize unregistered-event detection, playback-before-load errors, emitter lifetime, 3D position policy, content state, parameter validation, and diagnostics. Prefer generated code, typed IDs, GUID references, or validated assets over raw strings spread across gameplay code.

Run a three-day vertical-slice evaluation

First eliminate candidates that fail platform, contract, distribution, team-experience, outsourcing, or CI requirements. Then implement the same small scene with the two strongest options:

Footsteps across surfaces and speeds.
Exploration, alert, and combat music transitions.
Voice-driven ducking.
One hundred to two hundred simultaneous requests with priority rules.
3D ambience.
Two voice languages.
Bank or Cue Sheet load and unload.
Live profiling plus CI generation or validation.

Measure integration hours, independent sound-designer changes, edit-to-device steps, time to diagnose a missing sound, runtime visibility, Git clarity, new-machine setup, and removal of debug connections from release builds.

Define scoring weights before seeing results, and test minimum-spec hardware with production-like data. Choose the product that removes your bottleneck, not the one with the longest feature list.

Common misconceptions

“Unity Audio has lower sound quality.” Quality depends on source material, compression, sample rate, mix, and output hardware. Unity's internal use of FMOD technology is not FMOD Studio.
“Middleware is always faster.” It also has runtime, decode, DSP, and management costs. Its advantage is systematic control, which still requires target-hardware measurement.
“The sound team no longer needs programmers.” Events, objects, parameters, states, and content lifetime still cross the game-audio boundary. Middleware reduces routine blocking; it does not remove integration.
“We can add it near the end.” Late migration replaces scattered sources, Timeline tracks, clip references, Addressables groups, settings, and tests while introducing new event and delivery models.
“A free license means zero cost.” Training, integration, CI, updates, and incident response still consume engineering time.

Final recommendation

Keep Unity's built-in audio when a small or medium project can meet its requirements without building a large custom workflow.

The limit is not reached when Unity can no longer play a sound.

It is reached when audio behavior is scattered through game code and the team must continuously maintain its own tools for authoring, delivery, voice policy, live iteration, and investigation.

Beyond that point:

Choose CRI ADX for voice-heavy, streaming-heavy, resource-conscious production and strong alignment with Japanese game development.
Choose Wwise for complex states, music, spatial audio, large teams, profiling depth, and automation.
Choose FMOD Studio for fast timeline- and parameter-oriented iteration.
Keep Unity Audio when minimizing dependencies and keeping the system small matters most.

Prioritize production experience, client or publisher standards, and the team's ability to investigate failures. A controlled vertical slice reveals more than counting check marks in a feature table.

References

Specifications and licensing terms change. Check current documentation before adoption or release.

Unity

CRI ADX

Wwise

FMOD Studio

ASTC Isn't Automatically the Right Answer: Mobile Texture Formats for Unity on iOS and Android

GameDevToolLab — Mon, 10 Aug 2026 13:05:38 +0000

When targeting modern iOS and Android devices in Unity, ASTC is often the first texture format people reach for. It supports RGB and RGBA, offers block sizes from 4x4 through 12x12, and gives you a practical way to trade image quality for memory and bandwidth.

But "use ASTC" is not a complete production strategy.

You still need answers to questions such as:

Which iPhones and Android devices can actually use ASTC?
Does Android support depend on the OS version, OpenGL ES, Vulkan, or the GPU?
Is ASTC 6x6 unfriendly to GPUs because 6 is not a power of two?
Is it reasonable to use 6x6 for every texture?
What happens when Unity loads ASTC on unsupported hardware?
How is a PNG or JPEG file size related to runtime texture memory?

This article focuses on those production decisions rather than treating ASTC as simply "the newer mobile compression format." The terminology and Unity settings are based mainly on Unity 6.4 documentation as of July 2026. If a later Unity version changes the UI or delivery behavior, use the documentation for that version.

The short version is:

On Apple hardware, A8 is the hardware boundary for LDR ASTC, but that is not the same thing as the minimum device you can ship to with a current Unity project.
For Android phones and tablets distributed through Google Play, a robust default is an AAB with ETC2 as the default texture format and ASTC as an additional format through Texture Compression Targeting.
ASTC 6x6 is not a problem just because 6 is not a power of two. It is a standard hardware texture format with 128-bit blocks.
Do not force every texture to 6x6. A useful starting point is 6x6 for general albedo/sprites, 4x4-5x5 for text, SDFs, important normals and high-detail UI, and 8x8 for low-frequency backgrounds when visual testing allows it.

If you only want the actionable settings, skip to A practical project policy near the end. If you are specifically interested in why 6x6 works well on GPUs, read Is ASTC 6x6 a problem because it is not power-of-two?

First, separate three different meanings of "image format"

Texture discussions often mix three layers:

Source files: PNG, JPEG, PSD, TIFF, EXR. Their file size does not directly determine GPU memory. A 1024x1024 texture expanded to RGBA32 is about 4 MiB without mipmaps even if its PNG is tiny.
Build/delivery containers: APK, AAB, AssetBundle, Addressables bundles, LZ4, LZMA. These affect download size, storage, and loading, but do not change the GPU footprint of a texture once uploaded.
GPU texture formats: ASTC, ETC2, PVRTC, BCn, RGBA32. These are designed for random-access sampling by the texture hardware and are the focus of this article.

Keeping the layers separate prevents mistakes such as "a smaller PNG means less VRAM" or "LZ4-compressing an AssetBundle reduces texture memory."

What ASTC changes

ASTC (Adaptive Scalable Texture Compression) covers RGB/RGBA, linear/sRGB, multiple bit rates, LDR and supported HDR paths, and a range of square and non-square block footprints.

The important point is that ASTC 4x4, 6x6, and 8x8 are not encoder quality presets. They specify how many texels are represented by one 128-bit compressed block.

ASTC block size and bit rate

Every 2D ASTC block is 128 bits, or 16 bytes. Increasing the number of texels represented by that block lowers the amount of information available per texel and therefore lowers the memory footprint.

The theoretical bit rate is:

bits per pixel = 128 / (block width * block height)

A useful subset of Unity's options looks like this:

ASTC	Texels per block	Bit rate	1024x1024, no mips	Typical starting use
4x4	16	8.00 bpp	1.00 MiB	High-quality UI, text, visible detail
5x5	25	5.12 bpp	~657 KiB	High-quality general textures
6x6	36	3.56 bpp	~457 KiB	General quality/memory balance
8x8	64	2.00 bpp	256 KiB	Backgrounds and low-frequency imagery
10x10	100	1.28 bpp	~166 KiB	Aggressive size reduction
12x12	144	0.89 bpp	~116 KiB	Very aggressive, specialized use

Because dimensions such as 1024 are not divisible by every ASTC block size, the real base-level size uses rounded-up block counts:

ceil(width / blockWidth)
* ceil(height / blockHeight)
* 16 bytes

For a sufficiently large 2D texture, a complete mip chain is often roughly 4/3 the base level. Small mip levels introduce extra rounding because every level still needs at least one compression block.

In this article, MipMap refers to the Unity setting, Mip to an individual level, and "mip chain" to the whole sequence.

Is ASTC 6x6 a problem because it is not power-of-two?

No. The fact that 6 is not a power of two is not, by itself, a disadvantage.

ASTC deliberately defines many non-power-of-two footprints: 5x4, 5x5, 6x5, 6x6, 8x5, 8x6, 10x5, 10x6, 10x8, 12x10, and others.

The old advice that "GPUs prefer powers of two" contains historical truth, but it refers to a different level of the problem.

Texture dimensions and compression block dimensions are different things

Older GPUs and APIs often restricted the width and height of the whole texture to power-of-two values such as 256, 512, or 1024. NPOT textures sometimes had restrictions around mipmaps or repeat modes.

The 6 in ASTC 6x6 is not the texture width. It is the texel footprint represented by one compressed block.

If a GPU exposes ASTC 6x6 support, its texture hardware is designed to address and decode that footprint. You do not need to avoid it because you imagine a general-purpose integer divide-by-six happening in shader code.

Conceptually, a texel at (x, y) belongs to a block like this:

blockX = floor(x / 6)
blockY = floor(y / 6)
localX = x mod 6
localY = y mod 6

That pseudocode describes the mapping, not the internal circuit implementation. The key layout property is that the compressed block itself is always 16 bytes. Once the block index is known, the storage address is a fixed-stride calculation:

blockAddress = baseAddress
             + (blockY * blocksPerRow + blockX) * 16

So ASTC 6x6 is not a raw 6x6 pixel array with an awkward six-byte alignment. Thirty-six texels are encoded into a 16-byte block. In memory, the compressed data is still a grid of fixed-size blocks.

Does 4x4 have exactly the same performance as 6x6?

That is a different question, and the answer is not guaranteed to be yes.

Different GPU generations can have different texture-unit throughput, cache behavior, anisotropic filtering costs, and decoder implementations. You should not assume every ASTC footprint has identical throughput on every GPU.

But in production, the more important trade-off is usually:

6x6 uses substantially less texture memory than 4x4.
Less compressed data can reduce external memory bandwidth pressure.
The same cache capacity can cover more texels.
Image quality is lower because the same 128 bits describe more texels.

So choose between 4x4 and 6x6 based on quality, memory, bandwidth, and measurements, not because one block width happens to be a power of two.

Can a device support ASTC 4x4 but not 6x6?

That is not the normal way ASTC LDR capability is modeled. For example, when Vulkan's textureCompressionASTC_LDR feature is enabled, the standard LDR ASTC block formats are part of the supported feature set; 6x6 is not a separate optional extension.

Unity still lets you query specific formats such as TextureFormat.ASTC_6x6, which is useful for diagnostics, custom compressed data, and driver investigation. Think of the hardware capability as ASTC LDR support, while Unity's diagnostic API can inspect individual formats.

What about texture edges and NPOT sizes?

A 1024x1024 texture does not divide evenly into 6x6 blocks. It needs 171 blocks in each dimension, with the edge blocks covering a partially valid area.

That is expected behavior. Block compression rounds block counts up.

The overhead matters more for tiny textures. A 7x7 texture compressed as ASTC 6x6 needs 2x2 blocks, or 64 bytes. Its effective bit rate is about 10.45 bpp, far above the 3.56 bpp headline number for large images.

For many tiny textures, consider:

Sprite Atlas or Texture Atlas packing
R8, RG16, or even RGBA32 for very small data where appropriate
grouping by loading and batching behavior, not just per-texture format
disabling mipmaps for UI that does not need them

ASTC supporting NPOT textures does not mean every tiny texture is storage-efficient on its own.

ASTC support on iOS

Apple hardware is easier to reason about than the Android ecosystem. The hardware boundary for LDR ASTC is the A8 generation.

A8 is the hardware boundary for LDR ASTC. It is not the minimum shippable device list for a Unity 6.4 project.

Unity 6.4's Player requirements specify iOS/iPadOS 15 or newer and A8 SoC or newer, and the project must also satisfy its Deployment Target, Xcode version, SDK dependencies, and current App Store requirements.

A rough hardware view is:

Apple GPU generation	Example SoC	LDR ASTC	Note
Apple1	A7	No	Early Metal generation
Apple2+	A8+	Yes	LDR ASTC available
Apple6+	A13+	HDR ASTC	Treat separately from LDR

The iPhone 6 and 6 Plus used A8, while the iPhone 5s used A7. Those are SoC-generation examples, not current Unity 6.4 deployment examples. The iPhone 6 family cannot satisfy an iOS 15+ requirement.

The practical rule is to separate:

hardware capability — whether the SoC can sample ASTC, and
shipping eligibility — whether the OS, Unity, Xcode, SDKs, and App Store rules still allow that device into your supported set.

If every device you actually ship to supports LDR ASTC, using ASTC as the standard iOS texture format is a natural choice.

ASTC support on Android

Android cannot be summarized as "Android version X or newer supports ASTC." The actual capability depends primarily on the GPU and driver.

The Android Developers documentation gives rough Google Play ecosystem support figures of more than 80% for ASTC and more than 95% for ETC2. Those numbers do not predict your own audience, but they illustrate the important point: ASTC is mainstream, yet an ASTC-only Android strategy can still exclude a meaningful device segment.

Unity 6.4 documentation lists examples of GPU generations commonly associated with ASTC support, including:

Qualcomm Adreno 4xx and later / Snapdragon 415 and later
Arm Mali T624 and later
NVIDIA Tegra K1 and later
PowerVR GX6250 and later

Treat those as useful guidance, not a substitute for the actual API and driver capability on the device.

OpenGL ES 3.0 does not imply ASTC

ETC2 is a standard requirement in OpenGL ES 3.0. ASTC LDR under OpenGL ES 3.0/3.1 is typically exposed through extensions such as GL_KHR_texture_compression_astc_ldr, so the API version alone is insufficient.

OpenGL ES 3.2 is different: the specification includes the 2D LDR ASTC formats in its required compressed texture formats. That still does not imply HDR ASTC, and it does not tell you what Unity imported, which graphics API Unity actually selected, or which asset slice Google Play delivered.

A safer summary is:

OpenGL ES 3.0 -> ETC2 can be expected.
OpenGL ES 3.0 -> ASTC is not guaranteed.
OpenGL ES 3.1 -> many modern devices support ASTC, but do not infer it from the version alone.
OpenGL ES 3.2 -> 2D LDR ASTC is required by the specification.
In Unity -> verify the active graphics environment and the relevant format support on real devices.

Vulkan support does not imply ASTC either

Vulkan exposes a textureCompressionASTC_LDR feature. A device being able to run Vulkan does not mean that feature must be enabled.

The correct mental model is "Vulkan device plus ASTC feature," not "Vulkan equals ASTC."

What happens when Unity hits unsupported ASTC?

Unity can fall back by decompressing an unsupported texture into an uncompressed format. Unity 6.4's Android documentation describes ASTC falling back to RGBA32 on unsupported hardware.

That can keep the app running, but it is not free:

CPU work during loading
longer first-use or scene-transition stalls
transient memory pressure
much higher texture memory usage
higher memory bandwidth
increased risk of out-of-memory termination on constrained devices

ASTC 6x6 is about 3.56 bpp. RGBA32 is 32 bpp: roughly nine times as much data.

For a 2048x2048 texture with no mipmaps, ASTC 6x6 is roughly 1.78 MiB after block rounding, while RGBA32 is 16 MiB. With a full mip chain, you are roughly around 2.4 MiB versus 21.3 MiB.

One texture may be survivable. Dozens of characters, backgrounds, UI atlases, and effects can turn that fallback into a serious memory problem.

Treat runtime fallback as a last safety net, not a normal production path.

Use Texture Compression Targeting on Google Play

This section is about Android phones and tablets. If you also target Google Play Games for PC from the same delivery setup, review S3TC requirements separately instead of assuming ASTC + ETC2 covers that environment.

With an Android App Bundle, Google Play can deliver different texture compression variants to different devices. In Unity 6.4, you configure multiple entries in Texture Compression Formats.

A robust order for broad mobile distribution is:

1. ETC2  // default
2. ASTC  // additional optimized format

Why put ETC2 first if you prefer ASTC? The first entry is the default fallback, not the universally preferred delivery format. Google Play can still deliver the ASTC variant to ASTC-capable devices while ETC2 covers the safer fallback path. Each device downloads one matching variant, reducing the need for RGBA32 runtime expansion.

ETC2 is not visually equivalent to ASTC 6x6, so QA the ETC2 slice independently for alpha-heavy sprites, gradients, normals, and packed masks. Multiple variants also increase import/build time and CI storage, and per-texture Platform Overrides should be audited because they can defeat the global policy.

Remote Addressables and custom AssetBundles are a separate problem

Google Play's Texture Compression Targeting does not automatically rewrite arbitrary bundles hosted on your own CDN.

If you maintain ASTC and ETC2 variants for remote Addressables or custom AssetBundles, treat them as separate content lines. Include the format in identifiers such as:

Addressables Profile
RemoteLoadPath
catalog
bundle name
URL
cache key

Do not publish different binary contents behind the same URL and hope the cache sorts it out. Keep Content Update flows format-specific as well.

Direct APK distribution

Texture Compression Targeting assumes AAB delivery. Without AAB, Unity 6.4 uses only the first entry in Texture Compression Formats for the APK. If ETC2 is first and ASTC second, the APK is ETC2; an ASTC APK needs ASTC first in a separate build.

For enterprise distribution, alternative stores, MDM, or testing APKs, choose a common ETC2 build, separate ASTC/ETC2 APKs, format-specific bundles, or an explicitly ASTC-only hardware requirement. ASTC-only APKs are reasonable in controlled device fleets but risky for broad consumer distribution.

Is ASTC 6x6 a good default?

Often, yes—as a starting point, not as a rule.

ASTC 6x6 is about 3.56 bpp, roughly 44% of ASTC 4x4's bit rate and around one ninth of RGBA32. That makes it a practical baseline for many game textures.

Consider 4x4 or 5x5 for

small text embedded in UI
thin-line icons
high-contrast edges
faces, eyes, and other highly scrutinized character areas
complex gradients mixed with fine detail
important normal maps
packed masks whose numeric precision matters
SDF/font atlases
low-resolution textures shown very large on screen

6x6 is often a good starting point for

general character and environment albedo
typical sprites
VFX color textures
UI backgrounds and panels
general RGBA sprites

ASTC does not double in size because a texture has alpha; RGB and RGBA use the same block footprint. But complex color plus complex alpha still has to fit into the same 128 bits, so artifacts can become more visible.

Consider 8x8 or larger for

blurred backgrounds
skies, clouds, smoke, and other low-frequency imagery
distant assets shown small on screen
particles where some loss of noise/detail is acceptable
downloadable content where size pressure is severe

At 8x8, 10x10, and 12x12, inspect edge smearing, block artifacts, gradients, and alpha transitions carefully. "Background" is not enough justification by itself if the camera can zoom in.

Starting presets by texture role

Role	Starting point	What to inspect
General albedo / sprite	ASTC 6x6	Faces, silhouettes, alpha edges
Hero character / high-quality UI	ASTC 4x4-5x5	Thin lines, eyes, text, gradients
UI background / large panel	ASTC 6x6-8x8	Banding, rounded corners, translucency
Distant or blurred background	ASTC 8x8	Block artifacts when camera approaches
Normal map	ASTC 4x4-6x6	Lighting distortion; ensure sRGB is off
Packed ORM-like mask	ASTC 4x4-6x6	Channel errors and threshold behavior
Font / SDF	ASTC 4x4 or compare uncompressed	Small-size readability and edges
Very small texture	Prefer atlasing	Block rounding and wasted mips

These are comparison starting points, not universal answers.

Treat normal maps and packed masks more carefully than color

Compression errors in color textures can be visually hidden. Errors in normals and masks can turn into lighting artifacts or threshold changes.

For normal maps, disable sRGB and use Unity's normal-map import path. Prefer 4x4 or 5x5 when close-up lighting, specular response, or fine normal detail matters; 6x6 can still be sufficient for distant or low-detail surfaces.

For packed metallic/occlusion/roughness/smoothness masks, remember that channels carry numeric meaning. If a shader branches around a threshold such as 0.5, compression error can change behavior even when the packed image still looks acceptable. Visualize important channels independently during QA.

Do not confuse ASTC LDR and ASTC HDR

The ASTC used for normal PNG/JPEG-derived game textures is primarily LDR ASTC. HDR ASTC has separate hardware requirements.

On Apple hardware, LDR ASTC starts with the A8-era Apple2 GPU family, while HDR ASTC starts later with the A13-era Apple6 family. On Android, HDR support likewise needs its own OpenGL ES extension or Vulkan capability.

This implication is unsafe:

The device supports ASTC 6x6
therefore
it must support HDR ASTC 6x6

Check LDR and HDR separately. HDR fallback can be even more expensive if Unity has to expand into a format such as RGBA Half.

Texture compression can affect runtime performance

ASTC is not only about package size. On mobile GPUs, external DRAM traffic is expensive in performance and power. Sampling compressed textures can reduce resident texture memory, memory traffic, and cache pressure.

Moving from ASTC 4x4 (8 bpp) to 6x6 (~3.56 bpp) cuts the compressed data footprint to about 44%, but that does not imply a similar FPS gain. If the frame is CPU-, shader-, fill-rate-, or synchronization-bound, texture compression may barely change frame time.

Measure texture memory, bandwidth when available, loading hitches, sustained thermals, and download/install size—not only FPS.

Encoder time is different from runtime decode

Higher-quality ASTC encoding can increase import and build time because the encoder searches harder for a good 128-bit representation. Runtime devices are not recompressing textures every frame; the GPU samples already-compressed blocks.

A useful split is:

Block size -> memory footprint and quality
Encoder quality -> build time and final compression quality
Runtime sampling -> GPU texture hardware
Unsupported fallback -> possible CPU work and uncompressed memory growth

Using faster encoding during development and higher-quality encoding for release is reasonable, but final visual QA should use release-equivalent settings.

Runtime diagnostics in Unity

SystemInfo.SupportsTextureFormat can tell you whether the current device/graphics environment supports a specific TextureFormat.

using UnityEngine;

public static class TextureFormatDiagnostics
{
#if UNITY_EDITOR || DEVELOPMENT_BUILD
    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.AfterAssembliesLoaded)]
    private static void LogSupport()
    {
        bool astc4x4 = SystemInfo.SupportsTextureFormat(TextureFormat.ASTC_4x4);
        bool astc6x6 = SystemInfo.SupportsTextureFormat(TextureFormat.ASTC_6x6);
        bool astc8x8 = SystemInfo.SupportsTextureFormat(TextureFormat.ASTC_8x8);
        bool etc2Rgba = SystemInfo.SupportsTextureFormat(TextureFormat.ETC2_RGBA8);

        Debug.Log(
            $"GPU={SystemInfo.graphicsDeviceName}, " +
            $"API={SystemInfo.graphicsDeviceType}, " +
            $"ASTC4x4={astc4x4}, " +
            $"ASTC6x6={astc6x6}, " +
            $"ASTC8x8={astc8x8}, " +
            $"ETC2_RGBA8={etc2Rgba}");
    }
#endif
}

Keep this as development/QA diagnostics rather than permanent release logging.

Also understand what it proves. It tells you about device capability; it does not prove that a specific loaded asset is currently resident as ASTC.

For actual asset verification, combine it with:

the delivered Google Play slice
Texture2D.format
texture.graphicsFormat
Unity Profiler / Memory Profiler

When you need to distinguish sRGB vs linear, LDR vs HDR, or specific usages, use SystemInfo.IsFormatSupported(GraphicsFormat, GraphicsFormatUsage) as the more precise API.

And note that decoding a PNG at runtime with something like LoadImage does not magically create an ASTC-resident texture. If you need GPU-compressed runtime content, you must ship platform-appropriate compressed data and load it using the correct format.

What to verify on real devices

Do not finish ASTC validation in the Editor preview. Test representative iOS hardware, an ASTC Android path, and an ETC2/fallback Android path.

Delivered variant: for AABs, confirm which slice reached the device with bundletool, Play Console testing, logs, or distinguishable test assets.
Runtime memory: use Unity Profiler/Memory Profiler and platform tools. If a texture expected to be ASTC 6x6 occupies RGBA32-like memory, investigate fallback or import settings.
Loading hitches: compare controlled builds so format expansion, bundle loading, shader warm-up, and image decoding are not confused with one another.
Image quality: test at real resolution, render scale, mip settings, camera distance, UI scale, and post-processing. Validate the ETC2 slice separately from the ASTC slice.

A practical project policy

iOS

Treat A8 as the LDR ASTC hardware boundary, not the current minimum shipping device.
In Unity 6.4, also account for iOS/iPadOS 15+, Deployment Target, Xcode/SDK, and App Store requirements.
If the actual device set supports ASTC, start general textures at 6x6, important UI/hero assets at 4x4-5x5, and compare 8x8 for low-frequency backgrounds.
Treat HDR ASTC as a separate capability.

Android / Google Play

For phones/tablets, prefer AAB + Texture Compression Targeting with ETC2 as default and ASTC as an additional format.
Verify both ASTC and ETC2 slices and QA their image quality separately.
If Google Play Games for PC is also in scope, investigate S3TC separately.
Do not rely on RGBA32 runtime expansion as a normal shipping path.

Content production

Use 6x6 as an initial preset, not a rule. Manage role-based settings with presets or an AssetPostprocessor, treat normals/masks/SDFs/tiny textures separately, and perform final QA with release-equivalent encoding while checking memory, loading, and image quality together.

Conclusion

ASTC is one of the most practical standard texture formats for modern mobile GPUs, but the production answer is not "set everything to ASTC 6x6."

On iOS, A8 is the LDR ASTC hardware boundary, while the actual shipping device set is determined by the intersection of Unity's Player requirements, your Deployment Target, Xcode/SDK constraints, and App Store requirements. On Android, support is fundamentally a GPU/driver capability question, and a portion of the Google Play ecosystem still needs a non-ASTC path.

That is why ETC2 as the safe default plus ASTC as an additional Google Play Texture Compression Targeting format is a strong general Android policy.

And ASTC 6x6 being non-power-of-two is not something to fear. Six-by-six describes the texel footprint represented by a 128-bit fixed-size compressed block. The real decision is the trade-off between quality, GPU memory, bandwidth, supported devices, and fallback cost.

Start with 6x6 for general textures, move important assets toward 4x4-5x5, test 8x8 on low-frequency content, and validate both the delivered format and the real memory/quality result on devices. That gives you the benefits of ASTC without turning format support or aggressive compression into a hidden production risk.

References

Using External C# DLLs Safely in Unity: Newer C#, IL2CPP, Builds, and Debugging

GameDevToolLab — Fri, 07 Aug 2026 12:50:12 +0000

Introduction

Part 1 covered the adoption decision: the difference between an external DLL and an asmdef, sharing code with a C# game server, reducing Unity's daily compilation scope, running standard .NET tests, and keeping Unity dependencies out of the core domain.

This second part focuses on implementation and operations. It shows how to build a managed DLL with an external .NET SDK and integrate it safely into Unity.

The main topics are:

When a DLL can use newer C# syntax than Unity compiles directly.
The different roles of netstandard2.1 and LangVersion.
Pinning the .NET SDK with global.json.
Building a public API that still passes warnings-as-errors and XML documentation checks.
Referencing the same DLL from Unity and a C# server.
Managing Plugin Importer settings and .meta files.
IL2CPP, AOT, managed stripping, reflection, and generic-code restrictions.
Portable PDB, Source Link, commit hashes, and reproducible debugging.
Treating the DLL, PDB, XML documentation, .meta, license, and linker configuration as one deliverable.

The examples are based on Unity 6.5 as of July 2026. The goal is not to bypass Unity's runtime restrictions. The goal is to use an external build toolchain while staying inside the runtime and API surface Unity can actually execute.

The Main Rule: A Newer Compiler Does Not Give Unity a Newer .NET Runtime

Building a DLL with an external .NET SDK can let you use C# syntax that the Unity Editor does not accept as project source. Three separate layers must still be considered:

The C# compiler that understands the source syntax.
The Unity runtime that executes the generated IL.
The Base Class Library APIs called by the DLL.

Setting LangVersion to C# 12 does not turn Unity into a .NET 10 runtime. The DLL imported into Unity must still target a compatible API surface, typically netstandard2.1 for the Unity version considered in this article.

A safe design also keeps newer syntax inside the implementation and exposes conservative public types: ordinary classes, structs, interfaces, arrays, and other APIs that Unity-side source can consume without depending on the new syntax.

You Can Use Newer C# Syntax Inside the DLL

The important distinction is straightforward:

If an external compiler can compile the source and the resulting assembly stays within Unity's runtime and API compatibility limits, Unity can often use the DLL even when the Editor could not compile that source directly.

Unity 6.5 documents C# 9.0 as the language version used for project scripts, with some feature restrictions. The exact status by Unity version is documented in Unity's C# compiler and language version reference.

The source of an imported DLL is not parsed by Unity's C# compiler. For example, a recent Roslyn compiler can compile a C# 12 primary constructor into IL:

namespace Shared.GameRules;

// Keep the C# 12 primary constructor inside the DLL implementation.
internal sealed class StaminaRuleCore(int maxValue, int recoverySeconds)
{
    public int MaxValue => maxValue;
    public int RecoverySeconds => recoverySeconds;

    public int Clamp(int value) => Math.Clamp(value, 0, maxValue);
}

Unity loads the compiled assembly rather than parsing this source file.

There is no need to make this type public. The implementation later in this article keeps the primary-constructor type internal and exposes a conventional StaminaRule facade to Unity and the server. That keeps the architectural rule consistent: newer syntax is an implementation detail, while the public boundary remains conservative.

This does not mean that every new C# or .NET feature works automatically.

Three Compatibility Layers

At minimum, verify these three layers:

Compiler compatibility: Does the selected Roslyn compiler understand the source syntax?
Runtime compatibility: Can Unity's scripting backend execute the resulting IL and metadata?
API compatibility: Are all referenced framework APIs available in Unity's supported profile and on every target platform?

Some language features, such as file-scoped namespaces and raw string literals, mostly compile down to forms that older runtimes already understand.

Other features require new runtime capabilities, metadata, attributes, or library types. Microsoft also notes that some language features introduced from C# 8 onward depend on CLR capabilities or types associated with newer .NET implementations.

Unity 6.5 supports managed plug-ins targeting compatible .NET Standard or .NET Framework profiles. Unity's API compatibility documentation states that assemblies targeting .NET Core are not the intended input for this workflow.

Therefore, this is not an appropriate Unity plug-in target:

<TargetFramework>net10.0</TargetFramework>

Do not expect to import that server-targeted assembly directly into Unity.

Use a compatibility target for the shared library instead:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.1</TargetFramework>
    <LangVersion>12.0</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>disable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <Deterministic>true</Deterministic>
  </PropertyGroup>

</Project>

TargetFramework defines the available API surface and runtime compatibility. LangVersion defines the source syntax accepted by the compiler. Treating them as separate decisions is essential.

Confirm Unity's API Compatibility Level

Successfully compiling for netstandard2.1 does not prove that every Unity target will behave identically.

Pin and test the following assumptions for each artifact:

The supported Unity version or version range.
The Player Settings API Compatibility Level.
The actual platforms: Android, iOS, WebGL, desktop, consoles, and others.
Every Base Class Library API used inside the DLL.
The scripting backend, AOT restrictions, and managed stripping configuration.

An API can exist in the chosen target framework and still require validation on the actual Unity backend or platform. If the SDK must support several Unity versions, consider targeting the oldest supported API surface, publishing different artifacts per compatibility group, or using multiple target frameworks where that genuinely helps.

Use Unity's API compatibility levels for .NET as the reference for the project setting and supported profiles.

Avoid this in a shared library:

<LangVersion>latest</LangVersion>

latest can change behavior merely because a developer machine or CI image installs a newer SDK. Use an explicit version such as 12.0, and pin the SDK itself with global.json.

Features That Are Usually Easier, and Features That Need More Care

Features that often compile into existing IL and metadata patterns include:

File-scoped namespaces.
Global using directives.
Raw string literals.
Newer pattern matching syntax.
Primary constructors.
Lambda and type-inference syntax improvements.
Compile-time code generation helpers.

Features and libraries that deserve more careful validation include:

required members.
init accessors.
Features that require newer attribute types.
Default interface methods and other runtime-dependent features.
System.Reflection.Emit.
APIs specific to a newer .NET runtime.
Libraries that assume CoreCLR or NativeAOT behavior.
Reflection-heavy serializers and DI containers.
Runtime proxy or code generation.

The risk increases when the public API exposes metadata or construction requirements that Unity-side code must understand.

A practical rule is:

Use newer C# syntax inside the DLL, but keep the types, parameters, return values, and attributes exposed to Unity conservative.

For example, the internal code may use a primary constructor and new pattern syntax, while the public API uses ordinary classes, structs, interfaces, Task, arrays, and IReadOnlyList<T>.

Be cautious about exposing required, init, or new attribute-dependent initialization patterns on public DTOs that Unity code must construct or serialize. Also distinguish between types used as a callable API and types expected to participate in Unity serialization.

global using is usually compatible at the IL level, but excessive use can make source dependencies less visible. Keep its use consistent through team conventions and analyzers.

Do Not Make New Syntax the Only Reason for DLL Packaging

If the sole goal is to use a C# 12 syntax feature, the operational cost can exceed the benefit:

Navigating between Unity source and external library source.
Running a separate build.
Keeping DLL and PDB files synchronized.
Maintaining CI compatibility tests.
Verifying IL2CPP and real devices.

Treat newer syntax as an additional benefit of a library that already has stronger reasons to exist: server sharing, independent tests, strict architecture, or binary distribution.

Use the Standard .NET SDK Toolchain

An SDK-style project outside Unity can use the normal .NET development toolchain:

Shared settings through Directory.Build.props.
Warnings as errors.
Nullable Reference Types.
Roslyn analyzers.
Source Generators.
dotnet test.
dotnet format.
dotnet pack.
NuGet dependency management.
Deterministic builds.
Source Link.
Multiple target frameworks.
CI caching.

Unity can also use analyzers and additional compiler arguments, but its exact behavior depends on the Unity version and generated project setup. A separate library can follow the same rules used by the server or platform team.

Pin the SDK with `global.json`

Once the compiler is external, prevent developers and CI from silently using different Roslyn versions.

Place a global.json near the repository root:

{
  "sdk": {
    "version": "10.0.301",
    "rollForward": "latestPatch",
    "allowPrerelease": false
  }
}

10.0.301 is an example for this article. It is not a required SDK for Unity DLL development. Replace it with an SDK version installed and supported by your team and CI.

latestPatch permits patch updates within the same feature band while avoiding an unintended feature-band or major-version jump.

Print the environment at the start of CI:

dotnet --version
dotnet --info

Add the commit hash to InformationalVersion so that both build logs and the produced assembly identify the compiler environment and source revision.

If the library should treat all warnings as errors, use:

<PropertyGroup>
  <Nullable>enable</Nullable>
  <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
</PropertyGroup>

If only nullable warnings should fail the build, remove TreatWarningsAsErrors and configure WarningsAsErrors for the desired warning IDs or categories. Avoid showing both approaches without explaining which policy is intended.

Source Generators can also run entirely in the external build, with Unity receiving only the resulting DLL. This can be easier to reproduce than installing the generator into Unity's compiler pipeline.

Generated code is still subject to Unity's runtime, API compatibility, and IL2CPP restrictions. External generation controls the toolchain; it does not bypass the platform.

Implementation: One DLL Used by Unity and a .NET Server

The following is a small but complete layout.

Directory Structure

GameRepository/
├── global.json
├── Shared/
│   ├── Shared.GameRules/
│   │   ├── Shared.GameRules.csproj
│   │   └── StaminaRule.cs
│   └── Shared.GameRules.Tests/
├── Server/
│   └── Game.Server/
└── UnityClient/
    └── Assets/
        └── Plugins/
            └── Company/
                ├── Shared.GameRules.dll
                ├── Shared.GameRules.dll.meta
                └── Shared.GameRules.pdb

Treat more than the DLL itself as the artifact. A production package may include the DLL, PDB, XML documentation, license, version metadata, and, where necessary, a link.xml file.

Shared Library `csproj`

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>netstandard2.1</TargetFramework>
    <LangVersion>12.0</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>disable</ImplicitUsings>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
    <Deterministic>true</Deterministic>
  </PropertyGroup>

</Project>

With GenerateDocumentationFile and TreatWarningsAsErrors enabled together, missing XML documentation for public types and members can make CS1591 fail the build. Add documentation to the public API rather than suppressing the warning in a reusable SDK.

A short tutorial could disable CS1591, but an internal shared library or distributed SDK benefits from shipping API documentation with the artifact.

Keep C# 12 in the Internal Implementation

using System;

namespace Shared.GameRules;

/// <summary>
/// Defines the maximum stamina and time-based recovery rule.
/// </summary>
public sealed class StaminaRule
{
    private readonly StaminaRuleCore _core;

    /// <summary>
    /// Initializes a stamina rule.
    /// </summary>
    /// <param name="maxValue">The maximum stamina value.</param>
    /// <param name="recoverySeconds">
    /// The number of seconds required to recover one point.
    /// </param>
    public StaminaRule(int maxValue, int recoverySeconds)
    {
        _core = new StaminaRuleCore(maxValue, recoverySeconds);
    }

    /// <summary>
    /// Gets the maximum stamina value.
    /// </summary>
    public int MaxValue => _core.MaxValue;

    /// <summary>
    /// Gets the seconds required to recover one point.
    /// </summary>
    public int RecoverySeconds => _core.RecoverySeconds;

    /// <summary>
    /// Clamps a value to the inclusive range from zero to the maximum.
    /// </summary>
    /// <param name="value">The value to clamp.</param>
    /// <returns>The clamped value.</returns>
    public int Clamp(int value)
    {
        return _core.Clamp(value);
    }

    /// <summary>
    /// Applies a non-negative recovery amount without exceeding the maximum.
    /// </summary>
    /// <param name="currentValue">The stamina value before recovery.</param>
    /// <param name="recoveredAmount">The non-negative amount to apply.</param>
    /// <returns>The stamina value after recovery.</returns>
    public int ApplyRecovery(int currentValue, int recoveredAmount)
    {
        return _core.ApplyRecovery(currentValue, recoveredAmount);
    }

    /// <summary>
    /// Calculates the stamina recovered during the specified UTC interval.
    /// </summary>
    /// <param name="previous">The previous confirmed recovery time in UTC.</param>
    /// <param name="current">The current calculation time in UTC.</param>
    /// <returns>The amount recovered during the interval.</returns>
    public int CalculateRecoveredAmount(
        DateTimeOffset previous,
        DateTimeOffset current)
    {
        return _core.CalculateRecoveredAmount(previous, current);
    }
}

// The primary constructor is an internal implementation detail.
internal sealed class StaminaRuleCore(
    int maxValue,
    int recoverySeconds)
{
    public int MaxValue { get; } =
        ValidatePositive(maxValue, nameof(maxValue));

    public int RecoverySeconds { get; } =
        ValidatePositive(recoverySeconds, nameof(recoverySeconds));

    public int Clamp(int value)
    {
        return Math.Clamp(value, 0, MaxValue);
    }

    public int ApplyRecovery(int currentValue, int recoveredAmount)
    {
        if (recoveredAmount < 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(recoveredAmount),
                recoveredAmount,
                "The recovered amount must be zero or greater.");
        }

        var normalizedCurrent = Clamp(currentValue);
        var finalValue = (long)normalizedCurrent + recoveredAmount;

        return finalValue >= MaxValue
            ? MaxValue
            : (int)finalValue;
    }

    public int CalculateRecoveredAmount(
        DateTimeOffset previous,
        DateTimeOffset current)
    {
        if (current <= previous)
        {
            return 0;
        }

        var elapsed = current - previous;
        var elapsedSeconds =
            elapsed.Ticks / TimeSpan.TicksPerSecond;
        var recoveredAmount =
            elapsedSeconds / RecoverySeconds;

        return recoveredAmount >= int.MaxValue
            ? int.MaxValue
            : (int)recoveredAmount;
    }

    private static int ValidatePositive(
        int value,
        string parameterName)
    {
        return value > 0
            ? value
            : throw new ArgumentOutOfRangeException(
                parameterName,
                value,
                "The value must be greater than zero.");
    }
}

The public StaminaRule uses a normal constructor and ordinary methods. Unity-side C# source does not need to understand the C# 12 primary constructor.

The method is named CalculateRecoveredAmount because it returns the amount recovered during an interval, not the final stamina value. Apply the result through the separate public API:

var finalValue = rule.ApplyRecovery(
    currentValue,
    recoveredAmount);

ApplyRecovery normalizes the current value, widens the addition to long, and saturates at MaxValue. It avoids overflowing an int before calling Clamp.

The time calculation also avoids TimeSpan.TotalSeconds and its double representation. It converts ticks to whole seconds explicitly, making the rounding policy consistent across consumers.

Server Side

During development, reference the project directly from the server instead of manually copying the DLL:

<ItemGroup>
  <ProjectReference Include="..\..\Shared\Shared.GameRules\Shared.GameRules.csproj" />
</ItemGroup>

The server can still target net10.0; only the shared project targets netstandard2.1.

Do not scatter direct clock reads across domain code. Inject a clock:

using System;
using Shared.GameRules;

internal interface IClock
{
    DateTimeOffset UtcNow { get; }
}

internal sealed class SystemClock : IClock
{
    public DateTimeOffset UtcNow => DateTimeOffset.UtcNow;
}

internal sealed class StaminaRecoveryService
{
    private readonly IClock _clock;
    private readonly StaminaRule _rule;

    public StaminaRecoveryService(IClock clock)
    {
        _clock = clock;
        _rule = new StaminaRule(
            maxValue: 100,
            recoverySeconds: 300);
    }

    public int Calculate(DateTimeOffset lastRecoveredAt)
    {
        return _rule.CalculateRecoveredAmount(
            lastRecoveredAt,
            _clock.UtcNow);
    }
}

Even in a short sample, a clock abstraction makes fixed-time tests possible. The server uses UTC as the authoritative source and does not trust the client device clock for the final decision.

Unity Side

Place the built assembly under a stable path such as Assets/Plugins/Company:

using Shared.GameRules;
using UnityEngine;

public sealed class StaminaPresenter : MonoBehaviour
{
    [SerializeField] private int maxValue = 100;
    [SerializeField] private int recoverySeconds = 300;

    private StaminaRule _rule = null!;

    private void Awake()
    {
        _rule = new StaminaRule(maxValue, recoverySeconds);
    }

    public int Normalize(int value)
    {
        return _rule.Clamp(value);
    }
}

Unity lifecycle and Inspector values remain in a thin adapter; the calculation lives in the shared DLL.

The field uses null! because Unity initializes it in Awake, while a nullable-enabled compiler cannot infer that lifecycle guarantee. If the design permits access before Awake, use a nullable field, a defensive exception, or another initialization pattern consistent with the team's Unity conventions.

Automate DLL, PDB, and XML Copying

Manual copying makes it easy to commit an old DLL with a new source revision. Automate at least the basic flow.

PowerShell example:

$ErrorActionPreference = "Stop"

dotnet --version

dotnet build `
  ".\Shared\Shared.GameRules\Shared.GameRules.csproj" `
  -c Release

dotnet test `
  ".\Shared\Shared.GameRules.Tests\Shared.GameRules.Tests.csproj" `
  -c Release

$source = ".\Shared\Shared.GameRules\bin\Release\netstandard2.1"
$destination = ".\UnityClient\Assets\Plugins\Company"

New-Item -ItemType Directory -Force -Path $destination | Out-Null

Copy-Item "$source\Shared.GameRules.dll" $destination -Force
Copy-Item "$source\Shared.GameRules.pdb" $destination -Force
Copy-Item "$source\Shared.GameRules.xml" $destination -Force

This script intentionally does not overwrite the .meta file. Commit or package the configured Shared.GameRules.dll.meta, and replace only the DLL at the same path.

A CI pipeline can use this order:

dotnet --version / dotnet --info
dotnet restore
dotnet build
dotnet test
Copy DLL, PDB, and XML documentation into a Unity Package
Run Unity EditMode tests
Build the target Player
Run an IL2CPP smoke test on the target platform

A successful external build proves only that the .NET project compiles. It does not prove that Unity import, IL2CPP, managed stripping, or the final device works.

Unity Plugin Importer Settings

Unity treats a managed DLL as a plug-in asset. The main settings are managed through the Plugin Inspector.

Store Importer Settings in `.meta`

Auto Referenced, target platforms, CPU, editor-only settings, and other Plugin Importer state are stored in Unity's .meta file, not inside the DLL.

If CI copies a DLL to a new path and lets Unity generate a fresh .meta every time, the import configuration is no longer reproducible.

A safer workflow is:

Configure the Plugin Importer once in Unity.
Commit or package the resulting Shared.GameRules.dll.meta.
Replace only the DLL at the same path during updates.
Include the configured .meta when distributing the package to a new project.
Review the platform settings for every platform-specific DLL.

The importer configuration is part of the deliverable, not local editor state.

Auto Referenced

When enabled, Unity assemblies can reference the DLL automatically. This is convenient for initial integration but broadens the dependency graph.

For a small project with one foundational DLL, leaving it enabled may be reasonable. As the number of libraries grows, disabling it and referencing the DLL only from selected asmdef files makes dependencies clearer.

A predefined assembly such as Assembly-CSharp cannot configure an explicit reference to a precompiled DLL. Code that needs a DLL with Auto Referenced disabled must live under an asmdef that references the DLL. If existing code remains in Assembly-CSharp, the DLL must remain auto-referenced.

Platform Settings

Select the platforms that should include the DLL: Editor, Windows, macOS, Android, iOS, WebGL, and others.

A pure netstandard2.1 library is often usable on all managed targets, but a DLL calling OS-specific APIs must be restricted.

If several platform-specific files share the same assembly name, ensure that only one is active for a given build target.

Override References on asmdef Files

For an asmdef that consumes a DLL whose Auto Referenced setting is disabled, enable Override References and add the DLL under Assembly References.

Once Override References is enabled, the asmdef explicitly lists the precompiled DLLs it references. Forgetting another dependency can therefore produce compilation errors.

Adopt the setting gradually on assemblies where narrowing the dependency graph has a real benefit.

IL2CPP and AOT Restrictions

A DLL that works in the Mono Editor is not guaranteed to work on iOS, consoles, WebGL, or IL2CPP Android.

Unity documents AOT restrictions, the lack of System.Reflection.Emit, stripping risks for code referenced only through reflection, and special considerations for serializers and generic code. See Unity's IL2CPP limitations.

Reflection and Managed Stripping

A string-based type lookup is difficult for static analysis to follow:

// Simplified example showing a stripping risk.
var type = Type.GetType(typeName)
    ?? throw new InvalidOperationException(
        $"Type was not found: {typeName}");

var instance = Activator.CreateInstance(type);

This is a minimal illustration of the risk, not a complete production factory. It may work in the Editor while the type or constructor is removed from an IL2CPP Player. See Unity's Managed code stripping documentation.

Use Preserve or link.xml where necessary. There is an architectural detail, however: applying UnityEngine.Scripting.Preserve directly inside a Unity-independent Core DLL introduces a reference to UnityEngine.

If the Core DLL must remain a pure .NET library, prefer one of these approaches:

Put the preservation rule in the Unity project's link.xml.
Put Unity-specific preservation declarations in a Unity adapter assembly.
Replace reflection with explicit static registration or generated code.

Example link.xml:

<linker>
  <assembly fullname="Shared.GameRules">
    <type fullname="Shared.GameRules.GeneratedRuleRegistry" preserve="all" />
  </assembly>
</linker>

Do not preserve an entire large assembly without a reason. It can increase build size and IL2CPP build time. Reduce reflection and preserve the smallest necessary surface.

Runtime Code Generation

Be careful with libraries that depend on:

System.Reflection.Emit.
DynamicMethod.
Runtime proxy generation.
JIT-based serializers.
Runtime compilation of expression trees.
Dynamically generated DI interceptors.

They may work in the Mono Editor and fail in an AOT environment. Prefer libraries that provide an AOT mode, source generation, pre-registration, or static resolvers.

Generic Code

AOT compilation must know which concrete generic combinations are required.

Generic methods or types reached only through reflection are easy to miss. Possible mitigations include explicit references to representative combinations, generated registration code, or linker configuration.

Test the Final Target

A useful validation order is:

Normal .NET tests.
Unity Editor EditMode tests.
Mono Development Build.
IL2CPP Development Build.
The real Android, iOS, WebGL, console, or desktop target.
A Release Build using the production Managed Stripping Level.

"It compiles in Unity" is only the first checkpoint.

Preserve Debuggability

A common complaint about external DLLs is that exception stack traces no longer navigate to source lines.

Place the Portable PDB produced by the same build next to the DLL, and make the corresponding source revision available to developers.

Portable PDB mainly improves managed-code debugging and mapping managed exception stack traces to source. An IL2CPP Player's native crash analysis is a different pipeline. It can require Development Build or Script Debugging settings during investigation, IL2CPP-generated native symbols, and platform-specific symbol storage or upload. A managed PDB alone does not solve every Player crash.

Assets/Plugins/Company/
├── Shared.GameRules.dll
└── Shared.GameRules.pdb

Never update the DLL while leaving an old PDB, and do not combine artifacts from separate builds. Publish them together under one CI build number.

Useful practices for an internal library include:

Configure Source Link so compatible IDEs and debuggers can retrieve the matching source.
Put the commit hash in InformationalVersion.
Log the library version during application startup.
Prevent accidental mixing of Debug and Release artifacts.
Define how NuGet/package versions, assembly versions, and file versions relate.

An exception report containing Shared.GameRules 2.3.1+abc1234 immediately identifies the source revision to inspect.

DLL packaging does not inherently make debugging impossible. Debugging becomes difficult when binary, symbol, source, and version relationships are not automated.

Final Validation Before Adoption or Release

Before using the article's configuration in a production project, verify at least the following in a minimal repository:

dotnet build -c Release for the shared library.
dotnet test -c Release for the shared tests.
A server sample with the ProjectReference.
Unity import after copying the DLL, PDB, and XML documentation.
Compilation with DLL Auto Referenced disabled and asmdef Override References configured.
Unity EditMode tests.
An IL2CPP Development Build for the target platform.
A Release Build using a production-like Managed Stripping Level.
Device smoke tests for reflection, serialization, and generic-code paths.

A successful external build does not validate Unity import, IL2CPP, stripping, or platform APIs. Automate as much of the full path as practical.

Implementation and Operations Decision Table

Goal or situation	Decision
Use C# syntax newer than Unity compiles directly	Possible in an external DLL, but it should be a secondary benefit
Import a `net8.0` or `net10.0` server DLL directly into Unity	Do not; separate a Unity-compatible target
Use `LangVersion latest`	Prefer an explicit numeric version for reproducibility
Expose new-language features throughout the public API	Keep them internal and use a conservative public surface
Use a Reflection.Emit-based library on iOS	Avoid it or find an AOT-compatible mode
Distribute the same DLL to several games	A versioned UPM package is a strong option
Ship Asset Store implementation as a binary	A DLL can work, but it remains decompilable
Share Unity-heavy code with a server	Split Core and Unity Adapter assemblies
Make Plugin Importer settings reproducible	Version the `.meta` file with the artifact

Conclusion

The key practices for operating external C# DLLs safely in Unity are:

Treat LangVersion and TargetFramework as separate compatibility decisions.
Keep newer C# syntax inside the implementation and expose a conservative API.
Target a Unity-compatible surface such as netstandard2.1 for the shared DLL.
Pin the .NET SDK with global.json and avoid LangVersion latest.
If XML documentation and warnings-as-errors are enabled, document every public API.
Package the DLL, PDB, XML documentation, .meta, license, and linker settings together.
Control the Plugin Importer reference graph with asmdef files and Override References.
Test the production IL2CPP backend, stripping level, and real platform instead of stopping at the Editor.
Preserve debuggability with InformationalVersion, commit hashes, Source Link, and synchronized symbols.
Never place secrets in a managed DLL because it can be decompiled.

External compilation gives you a newer C# compiler, not a newer Unity .NET runtime. Once that distinction is clear, you can bring newer syntax, normal .NET SDK tooling, analyzers, Source Generators, and CI practices into Unity library development without assuming that Unity's execution restrictions have disappeared.

A practical package structure is:

Company.Product.Core.dll
  └ netstandard2.1, no Unity dependency,
     newer syntax used internally.

Company.Product.Unity.dll
  └ UnityEngine conversions, Components,
     and Unity-specific behavior.

Company.Product.Editor.dll
  └ Inspectors, importers, MenuItem commands,
     and editor-only tooling.

The benefits outweigh the operational cost when the full path is automated: external build, test, Unity import, IL2CPP Player build, device verification, and versioned artifact publication.

References

Why Use Precompiled C# DLLs in Unity? asmdef, Shared Server Code, and Practical Trade-offs

GameDevToolLab — Wed, 05 Aug 2026 07:39:29 +0000

Introduction

In a typical Unity project, C# source files live under Assets, and the Unity Editor compiles them for you. For a small project, this is usually the simplest and most productive workflow.

As a project grows, however, different requirements begin to appear:

Share calculations and validation rules between a Unity client and a game server written in C#.
Test game logic quickly without starting Unity.
Remove mature, rarely changed infrastructure code from Unity's everyday recompilation loop.
Use newer C# syntax than the Unity Editor can compile directly.
Distribute the same library to multiple games.
Deliver a versioned binary internally or externally instead of distributing source code.

One possible answer is to compile selected C# code outside Unity and import the result as a managed DLL.

Unity's documentation describes managed plug-ins as .NET assemblies produced outside Unity with tools such as Visual Studio, MSBuild, or the .NET SDK. Normal scripts in the Unity project are recompiled by Unity when their source changes, while an imported DLL is treated as a precompiled asset.

This does not mean that moving every C# file into a DLL automatically makes a project faster, safer, or easier to maintain. DLLs are most valuable for code that changes relatively infrequently, has little or no dependency on Unity APIs, and is reused in more than one runtime or product.

This is Part 1 of a two-part series. It focuses on the benefits, architecture, and adoption criteria for external C# DLLs in Unity. In particular, it covers shared client/server code, compilation boundaries, standard .NET tests, dependency control, versioned distribution, and the trade-offs compared with Assembly Definition files.

Part 2 covers the implementation details: newer C# syntax, global.json, csproj, netstandard2.1, copying DLLs into Unity, Plugin Importer settings, .meta files, IL2CPP/AOT restrictions, and debugging symbols.

The examples are based on Unity 6.5 as of July 2026.

What This Part Covers

DLL-based workflows combine several different topics: architecture, compilation, language versions, Unity's Plugin Importer, IL2CPP, packaging, and deployment. Mixing all of them into one article makes it difficult to separate the adoption decision from the implementation details, so this guide is split into two parts.

This first part covers:

The difference between an external DLL and an asmdef.
Sharing code between a Unity client and a C# server.
The effect on Unity compilation time.
Running unit tests without launching Unity.
Using project boundaries to keep Unity dependencies out of core logic.
Designing a small public API.
Distributing a versioned library across multiple projects.
The disadvantages and operational costs of DLLs.

The Main Recommendation: Put Stable Core Code in a DLL

The best candidates for an external DLL are usually the following:

Damage, reward, stamina, and experience calculations.
Input and request validation.
IDs, enums, value objects, and protocol-level types.
State transitions and game progression logic that do not depend on Unity APIs.
General-purpose encryption, compression, transformation, and diff logic.
SDKs used by multiple games, servers, live-ops tools, or batch processes.
Mature infrastructure code that is no longer edited every day.

The following code is usually easier to keep as source inside the Unity project:

Gameplay code built around frequently edited MonoBehaviour classes.
Components tuned repeatedly through the Inspector.
Logic tightly coupled to scenes, prefabs, animations, or Timeline.
Code that changes several times a day while a feature is still being designed.
Editor extensions that must track Unity API changes closely.

A practical architecture is often a three-layer split rather than an attempt to move everything into a DLL:

Game.Shared.Core
  └ Shared logic with no UnityEngine dependency.
     Built as an external DLL.

Game.Unity
  └ MonoBehaviour, ScriptableObject, UI, input, and presentation.
     Calls Shared.Core.

Game.Server
  └ ASP.NET Core, Worker Service, or another server runtime.
     References Shared.Core.

The value does not come from changing a file extension to .dll. It comes from establishing a Unity-independent core and reusing exactly the same rules across multiple execution environments.

DLLs and asmdef Files Solve Related but Different Problems

When Unity compilation time becomes a problem, the first tool to consider is usually an Assembly Definition file, or .asmdef.

An asmdef divides source code inside the Unity project into multiple assemblies. Unity can then recompile the changed assembly and the assemblies that depend on it, rather than rebuilding one enormous Assembly-CSharp.dll every time.

An external DLL also creates an assembly boundary, but its development workflow is different.

Area	asmdef	External DLL
Source location	Inside the Unity project	In an external .NET project
Compiler	Unity's bundled Roslyn	A selected .NET SDK/Roslyn version
Applying changes	Unity recompiles automatically	Rebuild the DLL, then update it in Unity
Referencing Unity APIs	Straightforward	Requires references to Unity assemblies
Newer C# syntax	Limited by Unity's support	Limited by the selected compiler, runtime, and API compatibility
Sharing with a server	Possible, but requires extra structure	Straightforward for a pure .NET library
Debugging	Same as normal Unity scripts	Requires symbol and source-version management
Frequently edited code	Well suited	Additional build/copy steps become costly
Binary distribution	Not its main purpose	Well suited

If compilation time is the only concern, start with asmdef files. They usually provide most of the benefit with less operational overhead.

External DLLs become more attractive when you also need one or more of the following:

A shared implementation for client, server, and tools.
A separately maintained build pipeline.
A compiler newer than the one Unity uses for project source.
Versioned binary distribution.
Strict separation from Unity APIs.

Updating a DLL still causes Unity assemblies that reference it to be recompiled. DLLs do not eliminate Unity compilation entirely. They are effective when a large, stable body of code is precompiled and Unity sees only a relatively small, stable public API.

Benefit 1: Share the Same Rules Between Unity and a C# Server

The most obvious benefit is sharing code with .NET applications outside Unity.

Suppose both the client and server contain this calculation:

public static int CalculateRequiredGold(int currentLevel)
{
    return 100 + currentLevel * currentLevel * 25;
}

Copying it into both projects works initially, but sooner or later only one copy changes:

The server changes the coefficient after level 20.
The Unity client's prediction still uses the old formula.
The UI shows that an upgrade costs 1,000 gold.
The server API rejects the request because the real cost is 1,200 gold.

This type of inconsistency can be harder to discover than a networking failure. The API is returning a valid error, and the client may not throw an exception. The two sides simply disagree about the rules.

A shared library lets the Unity client, the server, internal tools, and tests reference the same implementation:

Shared.GameRules.dll
├── LevelRule
├── DamageFormula
├── RewardCalculator
├── ItemUseValidator
└── ProtocolConstants

The server itself can still target a modern runtime such as .NET 10. Only the shared library needs to target a compatibility surface such as netstandard2.1, allowing both Unity and the server to reference it.

Code That Is Easy to Share

The best shared code has explicit inputs and outputs and does not access global engine state.

public readonly struct BattleParameter
{
    public BattleParameter(int attack, int defense, int skillPower)
    {
        Attack = attack;
        Defense = defense;
        SkillPower = skillPower;
    }

    public int Attack { get; }
    public int Defense { get; }
    public int SkillPower { get; }
}

public static class DamageFormula
{
    public static int Calculate(BattleParameter value)
    {
        var raw =
            (long)value.Attack * value.SkillPower / 100L
            - value.Defense;

        if (raw <= 1)
        {
            return 1;
        }

        return raw >= int.MaxValue
            ? int.MaxValue
            : (int)raw;
    }
}

Using ordinary classes and readonly struct values at the public boundary tends to reduce friction with Unity's compiler and serializers. The important point is not the exact syntax. The important point is that the calculation does not depend on UnityEngine.Object, GameObject, Transform, Time, or any other engine-owned state.

The calculation also widens intermediate multiplication to long. The final value saturates to the range from 1 to int.MaxValue. In production code, the overflow policy should be part of the game specification: reject the input with checked, saturate, wrap intentionally, or use a larger numeric type.

Once the policy is implemented in the shared library, the Unity client, server, and tests all observe the same behavior.

Code That Should Not Be Shared

Using C# on both sides does not mean that every implementation belongs in a common DLL.

The following concerns are usually safer as server-only code:

Hidden loot probabilities and anti-cheat rules.
Database transactions.
Authentication, authorization, and signature verification.
Server-side inventory and billing decisions.
Secret keys and server-only configuration.
Logic whose authoritative input is the server clock or server-owned state.

The following concerns are usually Unity-specific:

Frame updates.
Object lifetime and scene ownership.
Presentation state.
Animation and VFX timing.
Inspector-driven authoring.

A shared ItemUseValidator on the client can reject an obviously invalid input before sending a request. This improves feedback and reduces unnecessary traffic. The server must still execute the authoritative validation again.

A client-side managed DLL can be decompiled. Never place secret values or security-sensitive server decisions in a shared client DLL.

The Same DLL Does Not Guarantee the Same Result

Sharing the implementation is only one part of deterministic behavior. Different inputs or execution assumptions still produce different results.

For client/server rules, define at least the following:

The rounding mode and when rounding occurs.
Whether a value uses float, double, decimal, or an integer/fixed-point representation.
Whether time is UTC and which clock is authoritative.
Whether only a random seed is shared or the random algorithm is also fixed.
Whether parsing and formatting may depend on CultureInfo.
Whether overflow throws, saturates, or wraps.

For currencies and rewards that must match exactly, storing the smallest unit as an integer is usually safer than using float. If decimal values are required, the Math.Round mode and the order of operations should also be specified.

Do not treat the device clock as authoritative. A client may use the shared library to display an estimate, but the server should recalculate the final result from server-managed UTC time.

Randomness has the same issue. UnityEngine.Random on the client and System.Random on the server are not guaranteed to produce the same sequence from the same seed. If results must match, either pass the random value into the rule, fix the algorithm inside the shared library, or let the server produce and return the final result.

A DLL gives you one implementation of the rule. Production consistency additionally requires the same inputs, rounding, time base, and random policy.

Sharing DTOs Requires Versioning Discipline

Sharing request and response DTOs can reduce mismatched names and types. It can also couple the release cadence of the client and server too tightly.

Long-running products should decide how contract evolution works:

Use separate DTOs per API version.
Treat additions as compatible and removals or type changes as breaking changes.
Make a schema such as Protobuf the source of truth and generate code for both sides.
Share domain values in the common DLL, but map them to HTTP DTOs separately in the client and server.

"We can share the type" is not the same as "we should use this exact type forever." The boundary should match the deployment and compatibility model.

Benefit 2: Reduce the Source Unity Must Compile in the Daily Loop

Unity compiles normal C# scripts when they change, while imported managed DLLs are treated as precompiled assemblies.

Consider a project with the following layout:

Assets/Scripts
├── GamePlay          800 files
├── UI                500 files
├── Network           300 files
├── Data              400 files
└── StableFramework  1200 files

If StableFramework is mature and changes only once every few weeks, recompiling and reanalyzing all of its source during ordinary gameplay work may not provide much value.

Moving it to an external DLL means that Unity normally handles only its public API and compiled IL. Changes in the game project do not rebuild the library itself.

There are three configurations worth comparing:

Put everything in Assembly-CSharp.
Split Unity source into multiple assemblies with asmdef files.
Move stable code into an external DLL.

For many projects, moving from the first configuration to the second produces most of the improvement. The third adds value when the library can genuinely operate on a release cycle independent of the Unity project.

What Time Can Be Reduced

An external DLL can reduce:

Unity compilation of the moved source set.
Unity-side Roslyn Analyzer execution for that source.
Source enumeration during Unity project generation.
IDE analysis of a very large Unity-generated project.
Recompiling the same library independently in several Unity games.

The following costs remain:

Building the external .NET project.
Copying and importing the DLL into Unity.
Recompiling Unity assemblies that depend on the updated DLL.
Assembly reload and static initialization.
Converting the managed DLL during an IL2CPP Player build.

Moving code that changes every few minutes into a DLL can make iteration slower because it adds dotnet build, copy, and Unity import steps.

The optimization is not "remove compilation." It is "remove stable code from the ordinary Unity edit-and-play loop."

Limit the Reference Graph or the Benefit Shrinks

By default, a custom asmdef can implicitly reference precompiled DLLs whose Plugin Importer setting Auto Referenced is enabled. Updating such a DLL may therefore recompile assemblies that do not actually use it.

To reduce the affected graph, disable Auto Referenced for the DLL and enable Override References only on asmdef files that need it.

Shared.GameRules.dll
        ↑
Game.Domain.asmdef
        ↑
Game.Presentation.asmdef

Do not implicitly reference the library from unrelated UI, editor, or test assemblies.

The DLL boundary becomes valuable only when the reference graph is also kept small.

Common Misconception: A DLL Does Not Automatically Make Runtime Code Faster

"Precompiled DLL" can sound as if it executes faster than C# source stored in the Unity project. In practice, the main benefit is the development-time build boundary and reusability, not game runtime speed.

Unity project source is eventually compiled into managed assemblies as well. With IL2CPP, Unity performs managed stripping across project assemblies and external DLLs, converts IL to C++, and produces native code. If the logic is the same, its origin as project source or a prebuilt DLL does not by itself create a meaningful runtime performance difference.

Overengineering the boundary can even add costs:

Allocations when copying data into public DTOs.
Conversion between Unity-specific and shared types.
Extra virtual calls introduced only for abstraction.
Copies across DLL boundaries that exist only because of packaging.
Reflection-based registration.

These costs are not automatically serious, but they are a reason not to treat DLL packaging as a runtime optimization.

For runtime performance, use the Unity Profiler and optimize the actual bottleneck: allocations, algorithms, data layout, Burst, Jobs, rendering, loading, or networking.

The "speed" a DLL most commonly improves is:

The time from editing code to returning to Play Mode.
The speed of pure .NET tests that do not launch Unity.

Keeping these two definitions separate makes the result easier to measure.

Benefit 3: Run Unit Tests Without Starting Unity

A Unity-independent DLL can be referenced by a normal .NET test project.

src/
├── Shared.GameRules/
│   └── Shared.GameRules.csproj
└── Shared.GameRules.Tests/
    └── Shared.GameRules.Tests.csproj

The test project can use xUnit, NUnit, MSTest, or any other compatible framework.

public sealed class DamageFormulaTests
{
    [Theory]
    [InlineData(100, 20, 150, 130)]
    [InlineData(10, 999, 100, 1)]
    public void Calculate_ReturnsExpectedValue(
        int attack,
        int defense,
        int skillPower,
        int expected)
    {
        var parameter = new BattleParameter(
            attack,
            defense,
            skillPower);

        var actual = DamageFormula.Calculate(parameter);

        Assert.Equal(expected, actual);
    }
}

This enables a different development loop:

Run tests in seconds without opening the Unity Editor.
Use a lightweight Linux CI runner.
Run the library in the same pipeline as server tests.
Avoid Unity licenses and Library cache setup for pure logic tests.
Use the IDE's standard test runner.
Add coverage, mutation testing, and benchmarks.

Unity Test Framework can also run EditMode tests. The point is not that Unity tests are bad; it is that Unity-independent logic does not need to pay the cost of Unity import, compilation, and the Unity test runner.

Fast tests make it practical to cover more edge cases: zero, negative values, maximum values, overflow, rounding, level caps, time boundaries, and invalid inputs.

Keep Unity Integration Tests in Unity

External .NET tests cannot detect every problem. They do not validate:

MonoBehaviour lifecycle behavior.
Unity serialization.
Mapping to ScriptableObject data.
IL2CPP stripping.
Main-thread restrictions.
Platform-specific file or network behavior.

Use a two-level strategy:

Normal .NET tests
  └ Fast, broad verification of shared logic.

Unity EditMode / PlayMode / device tests
  └ Unity integration, AOT, serialization, and platform behavior.

DLLs do not eliminate Unity tests. They let pure logic run in a more appropriate environment.

Benefit 4: Enforce Dependency Direction at Compile Time

When all source is inside one Unity project, developers can often reference engine state simply because it is available.

Examples include calling a persistence service directly from UI code or using GameObject.Find inside domain logic.

A separate netstandard2.1 project does not reference UnityEngine by default:

// Does not compile in Shared.GameRules.
var player = GameObject.Find("Player");

The limitation becomes architectural protection:

Domain logic cannot search scenes.
Time is passed in or provided through a clock abstraction rather than read from DateTime.Now everywhere.
Randomness is abstracted instead of hardcoded to UnityEngine.Random.
Logging does not depend directly on Debug.Log.
Core file operations do not hardcode Application.persistentDataPath.

For example, a time-dependent rule can receive a clock:

using System;

public interface IClock
{
    DateTimeOffset UtcNow { get; }
}

public sealed class EnergyRecoveryService
{
    private readonly IClock _clock;

    public EnergyRecoveryService(IClock clock)
    {
        _clock = clock;
    }

    public int Calculate(
        DateTimeOffset lastRecoveredAt,
        int recoverySeconds)
    {
        if (recoverySeconds <= 0)
        {
            throw new ArgumentOutOfRangeException(
                nameof(recoverySeconds),
                recoverySeconds,
                "Recovery seconds must be greater than zero.");
        }

        var elapsed = _clock.UtcNow - lastRecoveredAt;
        if (elapsed <= TimeSpan.Zero)
        {
            return 0;
        }

        var elapsedSeconds =
            elapsed.Ticks / TimeSpan.TicksPerSecond;
        var recoveredAmount =
            elapsedSeconds / recoverySeconds;

        return recoveredAmount >= int.MaxValue
            ? int.MaxValue
            : (int)recoveredAmount;
    }
}

Unity can provide a Unity-facing implementation, the server can provide a server implementation, and tests can provide a fixed clock. Configuration such as recoverySeconds is validated at the boundary, preventing zero division and invalid behavior from entering the shared rule.

The calculation uses integer ticks instead of going through TimeSpan.TotalSeconds as a double. Negative elapsed time becomes zero, and very large values saturate to int.MaxValue. This makes the rounding and upper-bound policy explicit and easier to keep identical on the client and server.

You can create the same architecture with asmdef files and strict conventions, but a separate project makes a Unity dependency a compilation error rather than a code-review preference.

Keep the Public API Small

Every public type in a DLL becomes a contract for Unity, the server, tests, and tools. If every internal class is public, consumers will depend on implementation details that become difficult to change.

Expose inputs and final results rather than every intermediate state:

public readonly struct DamageResult
{
    public DamageResult(int value, bool isCritical)
    {
        Value = value;
        IsCritical = isCritical;
    }

    public int Value { get; }
    public bool IsCritical { get; }
}

public interface IDamageCalculator
{
    DamageResult Calculate(
        BattleParameter parameter,
        int randomValue);
}

Passing a random value into the calculation makes the rule deterministic for a given input. If exact client/server agreement is required, specify whether you share the random value, a seed plus a fixed algorithm, or only the server-produced result.

Public API guidelines that help preserve compatibility include:

Do not expose UnityEngine types from the Core DLL.
Choose arrays or IReadOnlyList<T> based on the caller's real needs.
Avoid unrestricted setters.
Assign explicit numeric values to enums used in protocols or persisted data.
Treat optional parameter defaults as part of the contract.
Remember that renaming a public parameter can affect callers using named arguments.
Do not use exceptions as an ordinary branch result.
Default to internal and make only intentional entry points public.

The library's value is not the number of classes it contains. It is the stability of the boundary.

Split DLLs by Reasons to Change

Dividing DLLs by file count usually causes all of them to be released together anyway. A better boundary reflects who changes the code, why it changes, and how often it changes.

Company.Protocol
  └ Network contracts.
     Updated with client/server agreement.

Company.GameRules
  └ Calculations and validation.
     Updated with game-design rules.

Company.Foundation
  └ Logging, IDs, and shared data structures.
     Updated infrequently by a platform team.

Company.UnityAdapter
  └ Unity API integration.
     Updated for engine and presentation changes.

If protocol contracts and Unity adapters live in the same DLL, a Unity-only update can unnecessarily force a server-side package update. On the other hand, splitting too aggressively increases the number of packages, references, and version combinations.

A useful rule is to split code that needs a separate release reason, has different consumers, or needs a one-way dependency boundary. A namespace difference alone does not justify another DLL.

Benefit 5: Distribute the Same Version to Multiple Projects

Copying source into each Unity repository makes it difficult to know which project contains which revision:

ProjectA/Assets/Common/...
ProjectB/Assets/Common/...
ProjectC/Assets/Common/...

A built and versioned DLL makes the dependency explicit:

Shared.GameRules 2.3.1
Shared.Networking 4.0.0
Company.Logging 1.8.2

Possible distribution methods include:

Commit the DLL directly to the consumer repository.
Put the DLL in a Unity Package.
Publish a UPM package through a scoped registry.
Publish the .NET package to an internal NuGet feed and copy its DLL into a generated Unity package.
Synchronize a CI artifact into the Unity project.

For companies maintaining several games, knowing the exact version in use is often more important than always running the latest version.

Automatic updates can break all projects at once. Pin each consumer to a known version, test the upgrade, and then update deliberately.

DLLs Fit Semantic Versioning Well

A public DLL API maps naturally to Semantic Versioning:

Patch: compatible bug fixes.
Minor: backward-compatible additions.
Major: removed or renamed types, changed parameters, and other breaking changes.

Deleting or renaming an assembly, moving a public type, or changing public method signatures should be treated as a breaking change.

A physical binary boundary encourages teams to distinguish between freely changeable internal implementation and public compatibility commitments.

Benefit 6: Deliver Functionality Without Shipping Source

A Unity Asset Store tool, external SDK, or partner library may need to be distributed as a DLL instead of source code.

Unity's documentation lists supplying code without source as one use case for managed plug-ins.

Benefits include:

Consumers are less likely to modify internal implementation accidentally.
The deliverable can be smaller and more controlled.
The public API becomes an explicit product surface.
Implementation details are less visible during ordinary use.
The same binary can be delivered to multiple consumers.

However, managed DLLs can be decompiled. Obfuscation can increase the cost of analysis, but it does not make the code secret.

DLL packaging is not a substitute for security:

Do not embed API keys.
Do not ship server private keys.
Do not put the final billing, reward, or entitlement decision in the client.
Do not rely on the DLL format for copy protection.
Keep license terms and technical enforcement as separate concerns.

A DLL is useful for preventing casual edits and keeping implementation out of the normal source view. It cannot guarantee that nobody will inspect the code.

Should the DLL Reference UnityEngine?

A Unity-specific SDK may legitimately need to call Unity APIs from inside a DLL.

Technically, you can build such an assembly by referencing Unity modules such as UnityEngine.CoreModule.dll. For code shared with a server, however, this creates an unnecessary dependency.

A better package layout is:

Company.Product.Core.dll
  └ netstandard2.1, no Unity dependency.

Company.Product.Unity.dll
  └ UnityEngine-dependent adapters.

Company.Product.Editor.dll
  └ UnityEditor-dependent editor tooling.

Core can be used by servers, CLIs, and tests. Unity converts between Unity types and the core model and contains Components. Editor contains importers, inspectors, and menu commands.

If you do build a Unity-dependent DLL, manage at least the following:

The Unity version whose assemblies are referenced.
Separation of runtime and editor assemblies.
Plugin Importer platform settings.
Rebuilding when Unity APIs change.
Preventing UnityEditor references from entering Player builds.
Changes that Unity's API Updater cannot rewrite inside the precompiled binary.

The thinner the Unity-specific layer is, the easier it is to support multiple Unity LTS versions.

Disadvantages of External DLLs

The benefits come with operational costs.

More Steps Before a Change Appears in Unity

A source file in Unity is recompiled after saving. An external DLL must be built and copied or packaged.

File watching, IDE tasks, automatic builds, and CI artifacts can reduce the friction. The most effective solution is still to avoid placing frequently edited code in the DLL.

Weaker Inspector and Source Navigation Workflows

A DLL can contain MonoBehaviour types, but the source is not a normal script asset in the project. Navigation, script assets, serialization compatibility, and class renames require more care.

Game-specific Components are usually easier to maintain in Unity source, with the DLL focused on logic.

Transitive Dependencies Must Be Shipped

If the .NET project references a NuGet package, Unity also needs the compatible dependent assemblies. Unity does not resolve .deps.json in the same way as a normal .NET application.

Different Unity packages may also ship conflicting versions of the same assembly.

Prefer few external dependencies. When one is necessary, verify:

A netstandard2.1 asset exists.
IL2CPP support is documented.
Native binaries are not required, or are available for every target.
Transitive dependencies are known and packaged.
Same-name assembly conflicts can be managed.
Redistribution is permitted by the license.

Public API Changes Become More Expensive

Internal implementation remains flexible, but a public API change can affect Unity, the server, and every tool at once.

This is a cost, but it also creates useful pressure to keep dependencies clean. Avoid a single enormous interface. Prefer small types and purpose-specific services.

DLLs Are Not a Security Boundary

Managed assemblies remain inspectable. DLLs are a packaging and architecture choice, not a secret-storage mechanism.

A Gradual Migration Plan

A large Unity project does not need to move thousands of files at once.

Step 1: Find Unity-Independent Code

Good candidates usually have these properties:

No using UnityEngine;.
Static or input/output-oriented calculations.
DTOs and value objects.
Validation rules.
String, time, and numeric conversion.
Pure data processing before or after networking.
Testable without scenes or editor state.

Step 2: Create a Boundary with asmdef First

Before moving code to another repository or project, create something such as Game.Domain.asmdef inside Unity and correct the dependency direction.

If the assembly still references large parts of Unity, the architecture needs separation before it needs packaging.

Step 3: Move the Assembly to an External .NET Project

Replace Unity-specific parameters with standard or domain-specific values where appropriate:

// Avoid in a cross-runtime core library.
int Calculate(Vector3 position);

// Easier to share.
int Calculate(Position3 position);

Do not create custom replacements for every Unity type without a real reason. If vector math does not need to be shared, leaving it in the Unity layer may be the better choice.

Step 4: Add Normal .NET Tests

Before and after the move, create characterization tests that prove behavior remains the same. Lock down calculations, rounding, caps, random input, and date boundaries.

Step 5: Import the DLL into Unity

Part 2 covers global.json, csproj, Plugin Importer, and .meta management.

It is acceptable to begin with Auto Referenced enabled. After the integration works, restrict the reference graph with asmdef files and Override References.

Step 6: Verify IL2CPP

Pay special attention to reflection, serialization, generics, async code, and threading. Editor success is not the final validation.

Step 7: Automate Distribution and Version Updates

Replace manual copying with a pipeline that produces the DLL, PDB, XML documentation, license, and linker configuration as one artifact.

Decision Table

Goal or situation	Recommended first choice
Improve Unity compilation time only	Start with asmdef
Remove mature, large code from the daily edit loop	Consider an external DLL
Share calculations between Unity and a C# server	A Unity-independent DLL is a strong option
Share code with a CLI or data-processing tool	A DLL is a strong option
Edit `MonoBehaviour` classes every day	Unity source plus asmdef
Test Unity-independent logic quickly	External DLL or independent .NET project
Make code impossible to inspect	DLLs do not solve this
Distribute one foundation library to several games	DLL plus UPM package

The central criteria are not file count. They are change frequency and number of consumers. Stable code used outside Unity and tested independently gains the most from an external DLL.

Conclusion

The practical benefits of turning selected Unity code into an external managed DLL are:

Share calculations and validation between a Unity client and a C# server.
Remove mature code from Unity's normal source recompilation loop.
Run fast, standard .NET tests without starting Unity.
Prevent Unity dependencies through compile-time project boundaries.
Distribute a versioned artifact to multiple games.
Treat the public API as an explicit compatibility contract.
Use asmdef first when compilation time is the only goal.
Do not expect packaging alone to improve runtime performance.

The most valuable combination is usually the ability to use the same game rules on the client and server and to test those rules extensively without Unity.

At the same time, sharing one DLL is not enough to guarantee identical behavior. Inputs, rounding, time, randomness, culture, and overflow policies must also be aligned, while the server remains authoritative.

A useful final architecture is:

Stable pure logic
  └ Unity-independent external DLL.

Frequently changing gameplay code
  └ Unity source divided with asmdef files.

Unity integration
  └ Thin MonoBehaviour and ScriptableObject adapters.

Server-specific behavior
  └ Modern .NET server projects.

Part 2 shows how to implement this structure with a fixed .NET SDK, a netstandard2.1 project, newer C# syntax inside the DLL, Plugin Importer settings, IL2CPP/AOT testing, reproducible artifacts, and debugging symbols.

References

Does Unity Really Need DI? Keeping Zenject, Choosing Reflex, and Comparing VContainer

GameDevToolLab — Mon, 03 Aug 2026 11:33:13 +0000

Introduction

As a Unity project grows, dependencies become harder to see and replace. Typical signs are more GameManager.Instance calls, repeated scene lookups, and input, networking, save, analytics, or billing code that cannot be swapped without changing its callers.

Dependency injection, or DI, addresses these problems by moving construction and lifetime management to explicit composition boundaries.

Zenject and its fork Extenject were the best-known Unity DI containers for years. As of July 26, 2026, the latest Zenject release is 9.2.0 from May 2020, while Extenject has been quiet since its 9.3.1 prerelease in July 2022.

Reflex 14.3.1 was released in June 2026 and VContainer 1.19.0 in July 2026. This article uses Unity 6-era APIs and describes the libraries as they existed on July 26, 2026.

Keep Zenject or Extenject in an existing project if it is stable.

For a new project, evaluate Reflex first.

Compare VContainer when you need its broader lifecycle features; use manual DI when the project is small.

Zenject is not suddenly unusable. The concern is that a DI container affects scene startup, prefab creation, lifetimes, editor tooling, generated code, and IL2CPP builds. For a new multi-year project, maintenance matters as much as convenience.

DI is not the same as using interfaces

DI means that an object receives dependencies instead of constructing them internally.

public sealed class PlayerMoveService
{
    private readonly IPlayerInput _input;

    public PlayerMoveService(IPlayerInput input)
    {
        _input = input;
    }
}

The composition root can create IPlayerInput and pass it to PlayerMoveService. This is already DI; a container is optional.

Manual construction is often clearer for a small graph. A container becomes useful when the project needs consistent registration, scopes, disposal, and scene-aware object creation. DI should expose dependencies, not hide them behind a global resolver.

Why Unity makes DI more complicated

Plain C# objects can use constructor injection. Unity adds MonoBehaviour, scenes, prefabs, Inspector references, and callback order.

A practical split is:

Plain C# classes: constructor injection
Scene MonoBehaviour components: method or field injection
References local to one prefab: SerializeField
Runtime-created prefabs: a project-owned factory plus explicit injection

Do not move every reference into DI. Buttons, labels, and child transforms are usually clearer in the Inspector. DI is most useful for networking, save data, input, time, randomness, purchases, logging, and analytics.

`Awake` and dynamic prefabs

For ordinary scene objects, Reflex intends to inject before Awake and OnEnable when a ContainerScope exists. Do not assume the same behavior for altered script execution order, additive or asynchronous loading, or manually instantiated prefabs.

An active prefab runs Awake and OnEnable during Instantiate; later injection cannot change that. A safe project-wide rule is to keep Awake self-contained and begin DI-dependent work from Initialize or StartAsync.

Model lifetimes explicitly

Singleton: one shared instance
Scoped: one instance per container
Transient: one instance per resolution

API clients may belong in the root scope. Battle score, waves, and enemy collections usually belong to a scene scope. DI is valuable because it makes lifetime and disposal boundaries explicit, not because it creates more singletons.

Why Zenject became popular

Zenject addressed Unity-specific problems through contexts, installers, initialization and tick interfaces, factories, pools, SignalBus, validation, subcontainers, and prefab injection. Its feature set and documentation made it a natural default.

The cost appears when application code directly depends on DiContainer, PlaceholderFactory<T>, SignalBus, ITickable, or IInitializable. Replacing the container then requires redesigning factories, events, update loops, and startup order.

Keep container-specific conveniences near the composition boundary.

Is Zenject still usable?

Yes, especially in an existing project.

Existing projects

Do not rewrite a stable foundation only because upstream development is quiet. Migration can affect scene startup, prefab ownership, factories, pools, signals, tests, Addressables, and IL2CPP stripping.

Keeping Zenject is reasonable when current builds are continuously tested, the team can patch or fork it, and the project already relies on Zenject-specific features. “Unmaintained” should trigger risk assessment, not an automatic rewrite.

New projects

The justification is weaker. Unity has continued to change editor APIs, IL2CPP, code generation, and Unity 6 internals since the last main Zenject release. Reflex and VContainer have shipped recent compatibility updates.

A DI package touches scenes, generated code, reflection, editor tools, and build pipelines. Choosing Zenject for a new multi-year project means accepting that your team may become its effective maintainer.

Is Zenject too slow?

The Reflex README publishes a benchmark that resolves a transient object with a four-level dependency chain 10,000 times.

Environment	Reflex	Zenject	VContainer
Android / Mono	4.9 ms / 54.7 KB	34.4 ms / 503.9 KB	20.3 ms / 70.3 KB
Android / IL2CPP	4.0 ms / 140.6 KB	15.8 ms / 1,000 KB	4.2 ms / 140.6 KB
Windows / Mono	0.7 ms / 140.6 KB	5.6 ms / 1,000 KB	1.9 ms / 140.6 KB
Windows / IL2CPP	1.4 ms / 140.6 KB	6.2 ms / 1,000 KB	3.0 ms / 140.6 KB

Each cell is time / GC allocation. See the current Reflex performance table.

This is a Reflex-published benchmark, not an independent test. It measures resolution throughput, not scene scanning, initial container construction, player size, or a complete startup path.

Within this workload, Reflex is faster and allocates less than Zenject. That may matter when resolving many transient objects at startup, but it does not make Zenject unusable. DI should normally resolve at composition boundaries, while gameplay uses already-injected references.

If a project resolves thousands of dependencies every frame, redesigning that path matters more than replacing the container.

Why Reflex is a strong default for new projects

Reflex provides a relatively small Unity-focused DI surface instead of reproducing every Zenject feature. As of July 2026 it includes root and scene containers, three lifetimes, lazy and eager resolution, multiple injection styles, factories, manual scopes, runtime GameObject injection, a debugger, and a Roslyn Source Generator.

It does not depend on runtime code emission and targets IL2CPP and WebGL. Version 14.3.1 also continued Unity 6 compatibility work.

Recent releases do not guarantee future health. Inspect issue response, contributor concentration, community knowledge, and whether your team can diagnose failures without upstream help.

Keep application-facing factories and events behind project-owned abstractions:

public interface IEnemyFactory
{
    EnemyView Create(EnemySpawnParameter parameter);
}

Only the composition root should know about Reflex's Container or RegisterFactory. The DI package should assemble the architecture, not become it.

Installing Reflex

This article uses the Reflex 14.x API. Older examples may use AddSingleton, AddScoped, or AddTransient, so check the package version.

In Unity Package Manager, select Add package from git URL:

https://github.com/gustavopsantos/reflex.git?path=/Assets/Reflex/#14.3.1

Pin a release tag and check Reflex Releases before adoption.

Create ReflexSettings directly under Assets/Resources with Create > Reflex > Settings. For application-wide registrations, create a RootScope prefab and add it to those settings. For each DI-enabled scene, create GameObject > Reflex > SceneScope, which adds a ContainerScope component.

Registering plain C# classes

using UnityEngine;

public interface IPlayerInput
{
    Vector2 ReadMove();
}

public sealed class UnityPlayerInput : IPlayerInput
{
    public Vector2 ReadMove()
    {
        return new Vector2(
            Input.GetAxisRaw("Horizontal"),
            Input.GetAxisRaw("Vertical"));
    }
}

public sealed class PlayerMoveService
{
    private readonly IPlayerInput _input;

    public PlayerMoveService(IPlayerInput input)
    {
        _input = input;
    }

    public Vector3 CalculateVelocity(float speed)
    {
        Vector2 move = _input.ReadMove().normalized;
        return new Vector3(move.x, 0f, move.y) * speed;
    }
}

The service does not know the Unity input API and can use a test implementation of IPlayerInput. The sample uses the legacy Input Manager only to stay small.

using Reflex.Core;
using Reflex.Enums;
using UnityEngine;

public sealed class GameplayInstaller : MonoBehaviour, IInstaller
{
    public void InstallBindings(ContainerBuilder builder)
    {
        builder.RegisterType(
            typeof(UnityPlayerInput),
            new[] { typeof(IPlayerInput) },
            Lifetime.Singleton,
            Resolution.Lazy);

        builder.RegisterType(
            typeof(PlayerMoveService),
            new[] { typeof(PlayerMoveService) },
            Lifetime.Scoped,
            Resolution.Lazy);
    }
}

Lifetime.Singleton: one instance shared by the registering container and its children
Lifetime.Scoped: one instance per container
Lifetime.Transient: a new instance per resolution
Resolution.Lazy: create on first use
Resolution.Eager: create while building the container

Injecting a `MonoBehaviour`

using Reflex.Attributes;
using UnityEngine;

public sealed class PlayerView : MonoBehaviour
{
    [SerializeField] private CharacterController _controller;
    [SerializeField] private float _speed = 5f;

    private PlayerMoveService _moveService;

    [Inject]
    private void Construct(PlayerMoveService moveService)
    {
        _moveService = moveService;
    }

    private void Update()
    {
        Vector3 velocity = _moveService.CalculateVelocity(_speed);
        _controller.Move(velocity * Time.deltaTime);
    }
}

The controller and speed are prefab-local configuration, so they stay in the Inspector. The input-dependent service is injected.

If Construct is not called, check that the scene contains a SceneScope or ContainerScope, the scene was loaded through the expected path, and PlayerMoveService is registered in that scene or a parent scope.

For production code, validate injection during explicit initialization before the view joins the update loop.

Registering a `ScriptableObject` or existing instance

Use RegisterValue for an existing settings asset:

[CreateAssetMenu(menuName = "Game/Player Move Settings")]
public sealed class PlayerMoveSettings : ScriptableObject
{
    public float Speed = 5f;
}

public sealed class GameplayInstaller : MonoBehaviour, IInstaller
{
    [SerializeField] private PlayerMoveSettings _settings;

    public void InstallBindings(ContainerBuilder builder)
    {
        builder.RegisterValue(
            _settings,
            new[] { typeof(PlayerMoveSettings) });
    }
}

RegisterValue creates a singleton registration. If the value implements IDisposable, Reflex disposes it with the container, so avoid duplicate ownership by another SDK or scope.

Dispose is not UnityEngine.Object.Destroy; Unity objects still follow scene, prefab, and explicit Unity ownership rules.

Avoid many raw string or numeric registrations. Reflex has no direct WithId equivalent, so use small types such as ApiBaseUrl and AssetBaseUrl to prevent accidental wiring.

Do not turn `Resolve` into a Service Locator

Passing Container through application code and calling Resolve<T> hides the class's real dependencies and forces tests to construct a container.

Inject the services directly:

public sealed class BattleService
{
    private readonly ISaveDataRepository _saveData;
    private readonly IAnalytics _analytics;

    public BattleService(
        ISaveDataRepository saveData,
        IAnalytics analytics)
    {
        _saveData = saveData;
        _analytics = analytics;
    }
}

Limit container access to composition roots, installers, DI-aware factories, and framework boundaries. Microsoft's DI guidelines recommend the same approach.

When explicit resolution is necessary, Single<T> detects duplicate registrations. Resolve<T> returns the last valid registration. Use IEnumerable<T> or distinct contracts when multiple implementations are intentional.

Source Generator and IL2CPP

Reflex supports IL2CPP without runtime code emission and provides a Roslyn Source Generator.

For generated field, property, or method injection, add SourceGeneratorInjectable and make the type public partial:

[SourceGeneratorInjectable]
public partial class PlayerView : MonoBehaviour
{
    [Inject]
    private void Construct(PlayerMoveService moveService)
    {
        _moveService = moveService;
    }
}

For nested types, every containing type must also be public partial.

Source generation does not remove every AOT limitation. The Reflex README notes a possible ExecutionEngineException for constructor-injected IEnumerable<T> when required IL2CPP code is missing.

Test early with desktop and Android IL2CPP, production stripping settings, iOS Xcode generation when relevant, and Addressables-created scenes and prefabs.

Creating dynamic prefabs safely

Scene objects can be injected by SceneScope. Runtime prefabs should go through one project-owned factory. Reflex provides GameObjectSelfInjector and the GameObjectInjector APIs.

The exact implementation changes with Addressables and pooling, so this is conceptual code:

public sealed class EnemyViewFactory : IEnemyViewFactory
{
    private readonly EnemyView _prefab;
    private readonly Transform _parent;

    public EnemyViewFactory(EnemyView prefab, Transform parent)
    {
        _prefab = prefab;
        _parent = parent;
    }

    public EnemyView Create(Vector3 position)
    {
        EnemyView view = Object.Instantiate(
            _prefab, position, Quaternion.identity, _parent);

        Container container =
            _parent.gameObject.scene.GetSceneContainer();

        GameObjectInjector.InjectRecursive(
            view.gameObject, container);

        view.Initialize();
        return view;
    }
}

Keep container-specific types inside the factory and choose the container that represents the object's actual scene or child scope.

Recommended rules:

do not use DI dependencies in Awake or OnEnable,
keep create -> inject -> initialize -> join gameplay,
inject pooled instances once and reset them on reuse,
reconsider pool sharing when the parent scope changes,
keep Addressables handles and release responsibility in the factory or pool.

SetActive(false) after creation cannot undo callbacks that already ran, and GameObjectSelfInjector cannot guarantee every component's relative Awake order.

VContainer is the main alternative

VContainer 1.19.0 remains actively maintained. It provides LifetimeScope, source generation, PlayerLoop integration, pure C# entry points, UniTask and ECS integration, diagnostics, async-scene child scopes, and keyed registration.

These features matter when DI should coordinate async startup, Entities, or a pure C# update loop. They are not requirements for every GameObject project.

Decision point	Reflex	VContainer
Direction	Small Unity-focused DI surface	DI plus lifecycle and entry-point integration
Scene injection	SceneScope injects the scene	Explicit component registration is central
Pure C# entry points	Project-owned when needed	Interfaces such as `IStartable`
UniTask integration	Separate from DI core	Official integration
Keyed registration	Use distinct types	Supported

In the Reflex-published Android IL2CPP benchmark, Reflex records 4.0 ms and VContainer 4.2 ms. The difference is too small to choose by ranking alone.

Compare registration style, PlayerLoop requirements, lifetime design, team experience, and debugging needs in a small prototype.

Manual DI is also valid

For a small game or isolated feature, direct construction may be safer than adding a container:

private void Awake()
{
    var input = new UnityPlayerInput();
    var moveService = new PlayerMoveService(input);
    _playerView.Initialize(moveService);
}

This is only a minimal composition example. A real project can place async startup in a separate bootstrap flow.

Manual DI is easy to inspect, has no container-specific AOT behavior, and is unaffected by third-party maintenance. Add a container when the dependency graph, scopes, or disposal requirements justify it.

Mapping Zenject concepts to Reflex

Zenject / Extenject	Reflex or project-owned replacement
`ProjectContext`	RootScope
`SceneContext`	Scene `ContainerScope`
`MonoInstaller`	`MonoBehaviour, IInstaller`
`BindInstance`	`RegisterValue`
`AsSingle` / `AsTransient`	Singleton / Transient lifetime
`AsCached`	Re-evaluate as scoped or singleton
`NonLazy`	`Resolution.Eager`
`PlaceholderFactory`	Project factory plus `RegisterFactory`
`SignalBus`	C# events, R3, or a project EventBus
`MemoryPool`	`UnityEngine.Pool` or a project pool
`IInitializable` / `ITickable`	Explicit bootstrap and project update loop
SubContainer	Child scopes or scene hierarchy

Do not mechanically rename APIs. Lifetimes, subscription disposal, and update order must be reconsidered.

A safer migration order is:

Stop adding new Zenject-specific types.
Wrap factories and events in project-owned interfaces.
Remove Zenject references from plain C# domain code.
Separate composition roots by scene or feature.
Add startup and disposal tests.
Replace installers and contexts last.

Avoid long-term coexistence and never let both containers create the same singleton.

Common DI failures in Unity

Creating an interface for everything

Not every value object or calculation class needs an IFoo. Prioritize external I/O, time, randomness, input, networking, storage, purchases, and analytics.

Using the container as a global variable

Calling Container.Resolve<T>() everywhere hides dependencies and makes tests require a configured container.

Resolving every frame

private void Update()
{
    var input = _container.Resolve<IPlayerInput>();
}

Inject once and keep the reference. Fixing this design usually matters more than choosing a faster container.

Storing scene state in root singletons

Root scope suits APIs, authentication, master data, logging, and analytics. Battle state and screen-specific presenters normally belong to a scene scope.

Expecting DI to define async startup order

DI resolves dependencies; it does not define the correct order for loading master data, save files, and scenes. Use an explicit bootstrap flow.

Conclusion

DI is not about eliminating every singleton or creating an interface for every class. It exposes dependencies, centralizes composition, and makes root, scene, and prefab lifetimes explicit.

Zenject can remain a reasonable foundation for a stable existing project. Its latest main release dates from 2020, however, and Extenject has also been quiet since 2022. For a new project that must follow future Unity versions, it is difficult to justify Zenject as the default.

Reflex remains actively maintained and provides Unity-focused scopes, source generation, debugging, and runtime prefab injection. VContainer offers a broader lifecycle and entry-point model when a project needs it.

Keep an existing Zenject project when migration cost is not justified.

Evaluate Reflex first for a new Unity project.

Compare VContainer when PlayerLoop integration, pure C# entry points, UniTask, ECS, or broader lifecycle management are real requirements.

Start with manual DI when the project is small.

A DI container automates construction and lifetime management; it does not design the software. Keep it near composition boundaries and preserve the option to replace it later.

References

Testing in Unreal Engine 5: CQTest, Automation Spec, Functional Tests, and CI

GameDevToolLab — Fri, 31 Jul 2026 05:21:19 +0000

Introduction

The hardest part of writing tests in Unreal Engine 5 is often not the assertion syntax. It is deciding which testing system to use.

UE provides several overlapping options:

IMPLEMENT_SIMPLE_AUTOMATION_TEST
Complex Automation Tests
Automation Spec
CQTest
Functional Tests
Python Automation Tests
Automation Driver
Gauntlet
Low-Level Tests

Games also require very different execution environments. Some rules can be tested as ordinary C++ functions. Others require UObject, UWorld, Actors, PIE, level streaming, UI input, rendering, network sessions, or a packaged build.

Trying to force all of those cases into one framework usually creates a slow and fragile test suite.

This article uses Unreal Engine 5.8 documentation as its baseline and explains how to divide responsibilities across C++ tests, CQTest, Automation Spec, asynchronous waits, Functional Tests, command-line execution, and CI.

Code sample scope: The snippets reference UE 5.8 APIs, but they are explanatory fragments rather than a complete sample project. Project-specific types, includes, .Build.cs dependencies, module API macros, and some setup code must be adapted to your project. The examples were not fully compiled in a UE 5.8 project while preparing this article.

The practical rule is simple:

Use the lightest execution environment that can prove the behavior you care about.

Which UE Test System Should You Use?

Target	Good first choice	Typical environment
Math, rules, and data conversion	CQTest, Automation Spec, or Simple Automation Test	Editor / command line
Behavior expressed as readable scenarios	Automation Spec	Editor / command line
The same logic with many inputs	Complex Automation Test	Editor / command line
Actors, Components, Blueprints, and level wiring	Functional Test	Editor / PIE
Asset and content-production rules	Python Automation Test	Editor
Mouse, keyboard, scrolling, and UI flows	Automation Driver	Editor / Client
Packaged builds, devices, clients, and servers	Gauntlet	Build machine / device
Fast tests in a dedicated executable	Low-Level Tests	Dedicated test target

Do not introduce everything at once. Keep most rule verification in fast C++ tests, add a small number of Functional Tests for critical gameplay wiring, and introduce Gauntlet only when the packaged runtime or multi-process environment is part of the requirement.

Separate Game Rules from Actors and Widgets

The most effective preparation for testing is to move deterministic rules out of Actors and Widgets.

// DamageCalculator.h
#pragma once

#include "CoreMinimal.h"

class FDamageCalculator
{
public:
    static int32 CalculateFinalDamage(
        const int32 BaseDamage,
        const int32 Defense)
    {
        if (BaseDamage <= 0)
        {
            return 0;
        }

        return FMath::Max(1, BaseDamage - FMath::Max(0, Defense));
    }
};

This function can be checked without creating a World or spawning an Actor. The gameplay Actor can read input values and apply the result, while a much smaller Functional Test verifies that the Unreal-side wiring is correct.

The goal is not to remove every Unreal type from the codebase. The goal is to separate:

Logic that benefits from many fast boundary-value tests
Engine integration that requires a World, Actor, Component, Blueprint, or level

Where to Put Test Code

Epic's documentation shows Automation Tests near the related module, commonly under Private/Tests.

Source/MyGame/
├─ Public/Combat/DamageCalculator.h
└─ Private/
   ├─ Combat/DamageCalculator.cpp
   └─ Tests/DamageCalculatorTest.cpp

This is a reasonable starting point for small tests that only depend on modules such as Core and Engine.

However, wrapping registration code with WITH_DEV_AUTOMATION_TESTS does not remove .Build.cs dependencies. When tests begin to require CQTest, editor-only modules, or Functional Testing support, move them into a dedicated module such as Source/MyGameTests or a Tests plugin.

Source/MyGameTests/
├─ MyGameTests.Build.cs
└─ Private/
   ├─ Unit/
   └─ Functional/

The examples below omit repeated guards for readability. In real files, guard C++ test registration code—Automation Tests, Specs, and CQTest tests—with the appropriate development-test configuration. Keep test-only classes and dependencies out of Shipping targets according to your project's build policy.

The sample names FInventoryService, FProfileService, APickupActor, and UInventoryComponent represent project-specific types. Replace them with your own implementations and dependencies.

Simple Automation Tests

A traditional Automation Test derives from FAutomationTestBase. A single test can be registered with IMPLEMENT_SIMPLE_AUTOMATION_TEST.

#include "Misc/AutomationTest.h"
#include "Combat/DamageCalculator.h"

#if WITH_DEV_AUTOMATION_TESTS

IMPLEMENT_SIMPLE_AUTOMATION_TEST(
    FDamageCalculatorMinimumDamageTest,
    "MyGame.Unit.Combat.DamageCalculator.MinimumDamage",
    EAutomationTestFlags::EditorContext |
    EAutomationTestFlags::ProductFilter)

bool FDamageCalculatorMinimumDamageTest::RunTest(const FString& Parameters)
{
    const int32 Actual = FDamageCalculator::CalculateFinalDamage(10, 100);

    TestEqual(
        TEXT("Positive attacks return at least one damage"),
        Actual,
        1);

    return true;
}

#endif

RunTest can use helpers such as TestEqual, TestTrue, TestFalse, and TestNotNull. Stop early when a missing prerequisite would make later code unsafe.

UObject* Object = CreateObjectUnderTest();
if (!TestNotNull(TEXT("The object under test was created"), Object))
{
    return false;
}

Treat Test Names as a CI Hierarchy

The test name is both a display name and a command-line filter.

MyGame.Unit.Combat.DamageCalculator.MinimumDamage
MyGame.Integration.Save.LoadRoundTrip
MyGame.Functional.Gameplay.Pickup

A pattern such as Project.Layer.Feature.Subject.Condition makes it easy to run MyGame.Unit before submission and reserve MyGame.Functional for a heavier job.

Common flags include:

EditorContext: Run in the Editor
ClientContext / ServerContext: Run in a client or server context
SmokeFilter: Extremely short checks
ProductFilter: Project or product functionality
PerfFilter / StressFilter: Performance or stress testing
NonNullRHI: Requires a rendering environment

ProductFilter is normally appropriate for game-project tests, while EngineFilter is intended for engine functionality. Epic's guidance treats Smoke Tests as checks that should complete in roughly one second or less.

CQTest for Fixture-Style C++ Tests

CQTest extends the Automation Test infrastructure with fixtures, setup and teardown, assertions, and latent actions.

Add CQTest to the module that builds the tests—not automatically to the product Runtime module.

PrivateDependencyModuleNames.AddRange(
    new string[] { "Core", "CoreUObject", "Engine", "CQTest" }
);

A minimal test is concise:

#include "CQTest.h"
#include "Combat/DamageCalculator.h"

TEST(DamageCalculator_StandardReduction, "MyGame.Unit.Combat")
{
    const int32 Actual = FDamageCalculator::CalculateFinalDamage(100, 30);
    ASSERT_THAT(AreEqual(70, Actual));
}

Use TEST_CLASS when several tests share a fixture.

TEST_CLASS(InventoryServiceTest, "MyGame.Unit.Inventory")
{
    TUniquePtr<FInventoryService> Inventory;

    BEFORE_EACH()
    {
        Inventory = MakeUnique<FInventoryService>(10);
    }

    AFTER_EACH()
    {
        Inventory.Reset();
    }

    TEST_METHOD(AddItem_IncreasesCount)
    {
        ASSERT_THAT(IsTrue(Inventory->AddItem(TEXT("Potion"), 3)));
        ASSERT_THAT(AreEqual(
            3,
            Inventory->GetItemCount(TEXT("Potion"))));
    }

    TEST_METHOD(AddItem_RejectsCapacityOverflow)
    {
        Inventory->AddItem(TEXT("Potion"), 10);
        ASSERT_THAT(IsFalse(Inventory->AddItem(TEXT("Ether"), 1)));
    }
};

Rebuilding the state before each method reduces order dependence. CQTest is a strong default for new fixture-style C++ tests, but an existing project that already uses Automation Spec consistently does not need to replace it only for stylistic reasons.

Automation Spec for Readable Behavior Scenarios

Automation Spec uses a BDD-style structure with Describe, BeforeEach, and It.

BEGIN_DEFINE_SPEC(
    FInventoryServiceSpec,
    "MyGame.Unit.Inventory.InventoryService",
    EAutomationTestFlags::EditorContext |
    EAutomationTestFlags::ProductFilter)

    TUniquePtr<FInventoryService> Inventory;

END_DEFINE_SPEC(FInventoryServiceSpec)

void FInventoryServiceSpec::Define()
{
    BeforeEach([this]()
    {
        Inventory = MakeUnique<FInventoryService>(10);
    });

    Describe("when adding an item to an empty inventory", [this]()
    {
        It("increases the count by the added amount", [this]()
        {
            Inventory->AddItem(TEXT("Potion"), 3);
            TestEqual(
                TEXT("Potion count"),
                Inventory->GetItemCount(TEXT("Potion")),
                3);
        });
    });
}

Specs work well when the scenarios themselves should read like documentation. Epic recommends the .spec.cpp suffix.

Avoid deeply nested Describe blocks. Two or three levels are usually enough; beyond that, the active setup becomes difficult to understand.

Complex Automation Tests for Parameter Sets

A Complex Automation Test uses GetTests to expose multiple cases and passes each command string to RunTest.

#include "Misc/LexFromString.h"

IMPLEMENT_COMPLEX_AUTOMATION_TEST(
    FDamageCalculatorCasesTest,
    "MyGame.Unit.Combat.DamageCalculator.Cases",
    EAutomationTestFlags::EditorContext |
    EAutomationTestFlags::ProductFilter)

void FDamageCalculatorCasesTest::GetTests(
    TArray<FString>& Names,
    TArray<FString>& Commands) const
{
    Names.Add(TEXT("Standard"));
    Commands.Add(TEXT("100,30,70"));

    Names.Add(TEXT("MinimumDamage"));
    Commands.Add(TEXT("10,100,1"));
}

bool FDamageCalculatorCasesTest::RunTest(const FString& Parameters)
{
    TArray<FString> Values;
    Parameters.ParseIntoArray(Values, TEXT(","));

    if (!TestEqual(TEXT("Parameter count"), Values.Num(), 3))
    {
        return false;
    }

    int32 BaseDamage = 0;
    int32 Defense = 0;
    int32 Expected = 0;

    if (!LexTryParseString(BaseDamage, *Values[0]) ||
        !LexTryParseString(Defense, *Values[1]) ||
        !LexTryParseString(Expected, *Values[2]))
    {
        AddError(FString::Printf(
            TEXT("Could not parse numeric parameters: %s"),
            *Parameters));
        return false;
    }

    TestEqual(
        TEXT("Final damage"),
        FDamageCalculator::CalculateFinalDamage(BaseDamage, Defense),
        Expected);

    return true;
}

FCString::Atoi turns invalid text into zero, which can hide broken test data. LexTryParseString lets the test fail explicitly.

For only a few scenarios, separate CQTest or Spec cases may be more readable. Complex Tests become especially useful when enumerating every map, Data Table row, or asset in a folder because each input appears as a separate test result.

Testing Work That Spans Multiple Frames

Asset loading, level transitions, HTTP, async tasks, PIE startup, and similar work cannot finish in one frame. Do not block the Game Thread with Sleep; wait for an observable completion condition.

CQTest provides TestCommandBuilder. The following assumes that the same TEST_CLASS owns a TUniquePtr<FProfileService> initialized in BEFORE_EACH.

TEST_METHOD(LoadProfile_CompletesWithSavedName)
{
    TestCommandBuilder
        .Do([this]()
        {
            ProfileService->BeginLoad(TEXT("Player01"));
        })
        .Until(
            TEXT("Wait for profile loading to complete or fail"),
            [this]()
            {
                return ProfileService->IsLoadCompleted() ||
                    ProfileService->HasFailed();
            },
            FTimespan::FromSeconds(10))
        .Then([this]()
        {
            ASSERT_THAT(IsFalse(ProfileService->HasFailed()));
            ASSERT_THAT(AreEqual(
                FString(TEXT("Alice")),
                ProfileService->GetLoadedProfile().PlayerName));
        })
        .OnTearDown([this]()
        {
            ProfileService->Cancel();
        });
}

Prefer Until over a fixed WaitDelay. A timeout must still exist: otherwise, a condition that never becomes true is one of the hardest CI failures to investigate. Include the operation, target ID, last observed state, and error code in diagnostics.

Traditional Simple Automation Tests can use DEFINE_LATENT_AUTOMATION_COMMAND and ADD_LATENT_AUTOMATION_COMMAND. For new code, CQTest or Spec latent features often keep the sequence easier to read.

Expected Warnings and Errors

The Automation Framework records warnings and errors emitted during a test. Register an error first when the error is the expected behavior.

AddExpectedError(
    TEXT("Inventory capacity exceeded"),
    EAutomationExpectedErrorFlags::Contains,
    1);

The count is checked as well. Keep the matching text narrow: a broad Contains pattern can accidentally absorb an unrelated error. Prefer a stable identifier and an exact occurrence count.

Routine invalid input is often easier to test through return values or result types instead of Error logs. Reserve Error logging for genuinely abnormal states.

Functional Tests for Actors and Levels

Use Functional Tests for behavior that depends on Actors, Components, Blueprints, or level wiring—for example, collecting a pickup, opening a door through a trigger, AI movement, or startup spawning.

Enable the Functional Testing plugin and place a Functional Test Actor in a small dedicated test map. A C++ module that derives from AFunctionalTest needs the FunctionalTesting dependency.

The lifecycle is:

Start preparation in PrepareTest
Wait in IsReady when preparation spans frames
Perform assertions in StartTest
Call FinishTest for both success and failure
Restore state during cleanup

Forgetting FinishTest leaves the test running until timeout.

The following example expects an APickupFunctionalTest instance in a dedicated map, with PickupClass and Inventory configured in Details. It is intentionally simplified. A production test should usually own a test Pawn or Fixture Actor and obtain the Component from that fixture instead of depending on ordinary gameplay state.

// PickupFunctionalTest.h
#pragma once

#include "FunctionalTest.h"
#include "PickupFunctionalTest.generated.h"

class APickupActor;
class UInventoryComponent;

UCLASS()
class MYGAMETESTS_API APickupFunctionalTest : public AFunctionalTest
{
    GENERATED_BODY()

protected:
    virtual void PrepareTest() override;
    virtual bool IsReady_Implementation() override;
    virtual void StartTest() override;
    virtual void CleanUp() override;

private:
    UPROPERTY(EditAnywhere, Category = "Test")
    TSubclassOf<APickupActor> PickupClass;

    UPROPERTY(EditInstanceOnly, Category = "Test")
    TObjectPtr<UInventoryComponent> Inventory;

    TWeakObjectPtr<APickupActor> SpawnedPickup;
    bool bPreparationFinished = false;
};

void APickupFunctionalTest::PrepareTest()
{
    Super::PrepareTest();
    bPreparationFinished = false;

    if (PickupClass && Inventory && GetWorld())
    {
        APickupActor* Pickup = GetWorld()->SpawnActor<APickupActor>(
            PickupClass,
            GetActorLocation(),
            GetActorRotation());

        if (Pickup)
        {
            SpawnedPickup = Pickup;
            RegisterAutoDestroyActor(Pickup);
        }
    }

    bPreparationFinished = true;
}

bool APickupFunctionalTest::IsReady_Implementation()
{
    // Wait only for preparation to finish so StartTest can report failures.
    return bPreparationFinished;
}

void APickupFunctionalTest::StartTest()
{
    Super::StartTest();

    if (!PickupClass)
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("PickupClass is not configured"));
        return;
    }

    if (!Inventory)
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("Inventory is not configured"));
        return;
    }

    if (!GetWorld())
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("GetWorld() returned nullptr"));
        return;
    }

    if (!SpawnedPickup.IsValid())
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("Failed to spawn APickupActor"));
        return;
    }

    const int32 Before = Inventory->GetItemCount(TEXT("Potion"));
    SpawnedPickup->Collect(Inventory);
    const int32 After = Inventory->GetItemCount(TEXT("Potion"));

    const bool bSucceeded = AssertEqual_Int(
        After,
        Before + 1,
        TEXT("Collecting the pickup adds one Potion"),
        this);

    FinishTest(
        bSucceeded
            ? EFunctionalTestResult::Succeeded
            : EFunctionalTestResult::Failed,
        bSucceeded ? TEXT("Succeeded") : TEXT("Item count did not increase"));
}

void APickupFunctionalTest::CleanUp()
{
    SpawnedPickup.Reset();
    bPreparationFinished = false;
    Super::CleanUp();
}

RegisterAutoDestroyActor removes the spawned Actor when the test ends. Do not wait forever in IsReady when a class reference is missing or spawning failed. Complete preparation and report a specific failure in StartTest.

Prefer several small test maps over one giant functional-test map. Smaller maps reduce startup cost, hidden dependencies, and interference between tests.

Running Tests in the Editor

In UE 5.8, open the automation interface from Tools > Test Automation. Depending on the version, enabled plugins, and layout, it may also be available through Tools > Session Frontend and its Automation tab.

A typical workflow is:

Enable the required testing plugins
Compile C++ and restart the Editor
Open Test Automation
Select tests under MyGame
Start the tests
Inspect the result events for failures

When a test is missing, verify the module is loaded, the context flags match, dependencies such as CQTest are present, required plugins are enabled, and the Editor has been fully restarted. New registrations may not appear reliably after Live Coding alone.

Running Tests from the Command Line

Use Automation RunTest through -ExecCmds.

"C:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" ^
  "D:\Projects\MyGame\MyGame.uproject" ^
  -Unattended ^
  -NoSplash ^
  -NullRHI ^
  -ExecCmds="Automation RunTest MyGame.Unit;Quit" ^
  -ReportExportPath="D:\Projects\MyGame\Saved\AutomationReports\Unit"

-Unattended suppresses blocking dialogs. -ReportExportPath writes report data, including JSON and HTML-related files. Preserve both the report directory and Saved/Logs as CI artifacts.

Do Not Trust Only the Process Exit Code

Use the process result to detect startup failures, crashes, and job timeouts, but also parse the Automation Report JSON.

Fail the CI job when:

A test failed or timed out
A required test unexpectedly remained NotRun or incomplete
The expected report JSON was not generated

Decide explicitly whether reasoned exclusions reported as Skipped are allowed. Preserve reports even on success, and upload HTML-related output plus logs on failure.

Functional Tests also need the map containing the test Actor.

"C:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" ^
  "D:\Projects\MyGame\MyGame.uproject" ^
  "/Game/Tests/Maps/L_PickupFunctionalTest" ^
  -Unattended ^
  -NoSplash ^
  -ExecCmds="Automation RunTest MyGame.Functional.Gameplay.Pickup;Quit" ^
  -ReportExportPath="D:\Projects\MyGame\Saved\AutomationReports\Pickup"

-NullRHI reduces cost when rendering is unnecessary. Remove it for screenshots, Slate, Viewports, Materials, GPU-specific checks, and tests marked NonNullRHI. Separate rendering and non-rendering jobs instead of assuming every Functional Test can run headlessly.

Groups can be defined in DefaultEngine.ini.

[/Script/AutomationController.AutomationControllerSettings]
+Groups=(Name="PreSubmit", Filters=((Contains="MyGame.Unit.", MatchFromStart=true)))
+Groups=(Name="Nightly", Filters=((Contains="MyGame.Functional.", MatchFromStart=true)))

-ExecCmds="Automation RunTest Group:PreSubmit;Quit"

Temporarily exclude a flaky test through configuration instead of commenting it out, and include both a reason and a removal condition.

+ExcludeTest=(Test="MyGame.Functional.Gameplay.Pickup",Reason="UE-12345: Remove after fixing spawn wait",Warn=False)

A Practical CI Split

Running every test on every change makes feedback too slow. Running everything only at night allows several unrelated changes to accumulate before a failure appears.

Pull Request or Pre-Submit

Keep this within a few minutes:

CQTest and Simple Automation Tests for deterministic C++
Important serialization round trips
Critical data validation
Smoke Tests that finish in roughly one second

Use -NullRHI when rendering is not required.

After Updating the Main Branch

Add moderately expensive integration checks:

Small Functional Tests
Important map loads
Blueprint compilation
Save/load with real files
Asset Registry reference validation

Nightly or Scheduled Jobs

Reserve expensive environments for:

Loading all maps and major assets
Screenshot comparisons
Multiple clients and a Dedicated Server
Packaged builds
Long-running memory or stress tests
Target-device execution

This is where Gauntlet becomes useful. It can launch and coordinate multiple Unreal sessions, clients, and servers. Do not move ordinary rule tests into Gauntlet; use it when the packaged runtime or process topology is part of what must be proven.

Python Automation Tests for Content Workflows

Python tests are useful for naming rules, folder structure, import settings, and forbidden references. With the Python Automation Test support enabled, scripts under Content/Python named test_*.py can be discovered.

The following sample uses EditorAssetLibrary, so it assumes an Editor environment with the required Python and Editor Scripting plugins. Confirm API and plugin names for your exact engine version.

import unreal

assets = unreal.EditorAssetLibrary.list_assets(
    "/Game/Characters",
    recursive=True,
    include_folder=False,
)

invalid_assets = [
    path for path in assets
    if not path.rsplit("/", 1)[-1].startswith(("SK_", "SM_", "T_", "MI_"))
]

max_reported = 20
preview = "\n".join(f"- {path}" for path in invalid_assets[:max_reported])
omitted = max(0, len(invalid_assets) - max_reported)
omitted_note = f"\n...and {omitted} more" if omitted else ""

if invalid_assets:
    raise AssertionError(
        f"Naming violations: {len(invalid_assets)}\n"
        f"{preview}{omitted_note}\n"
        "Rename assets to use SK_, SM_, T_, or MI_."
    )

Do not dump thousands of paths into CI logs. Report the count, a limited preview, and the correction rule. When combining several checks, log each summary and raise an exception at the end; logging errors without failing can leave the CI job green.

Python execution does not automatically advance Editor ticks during asynchronous work. Split such operations with unreal.AutomationScheduler.add_latent_command.

Automation Driver for UI Input

Automation Driver simulates mouse input, clicks, keys, scrolling, and drag-and-drop. Give UI elements stable driver IDs instead of locating them only by visible text or hierarchy.

SNew(STextBlock)
    .Text(ViewModel, &FViewModel::GetPlayerName)
    .AddMetaData(FDriverMetaData::Id("PlayerNameLabel"));

The driver is disabled by default. Enable it at test start and always disable it during cleanup.

Synchronous Driver APIs block until completion. Calling them on the Game Thread can deadlock. Keep input operations outside the Game Thread, but do not move Slate or UObject validation indiscriminately to a worker thread. Slate TSharedPtr instances are not thread-safe by default and should not be copied into worker-thread lambdas.

A safe conceptual split is:

BeforeEach [Game Thread]
  Create the Widget, Window, ViewModel, and Driver; enable the Driver
        ↓
Input phase [outside Game Thread]
  Perform clicks, typing, scrolling, and other synchronous Driver actions
        ↓
Validation phase [Game Thread]
  Inspect UObject, Slate, and ViewModel state
        ↓
AfterEach [Game Thread]
  Destroy the Driver, close the Window, and disable the Driver

Use Spec async blocks or latent commands to return to the Game Thread after input completes. Ensure failure paths still reach Disable().

UI tests are slower and more fragile than service-layer tests. Limit them to representative flows such as starting from the title screen, saving settings, or selecting a save slot. Test detailed branches in C++ beneath the UI.

When to Use Low-Level Tests

UE5 Low-Level Tests use Catch2 and run through a dedicated test executable with their own .Build.cs and .Target.cs. Avoiding full Editor startup can make a large low-level suite much faster.

They are not limited strictly to pure C++; with the right target and modules, they can exercise UObject, assets, and Engine Components. However, they require dedicated build and CI setup, and World- or Editor-workflow-heavy tests may remain easier in Automation or Functional Tests.

Consider Low-Level Tests when you already have hundreds of small tests, Editor startup dominates execution time, or BuildGraph should run them as an independent job. For the first test in a project, CQTest or a Simple Automation Test is usually the shorter path.

Common Failure Modes

Waiting with Sleep

FPlatformProcess::Sleep can stop the Game Thread from ticking. Use latent actions and observable completion conditions.

Depending on Test Order

Each test must create its own state and restore it during teardown. A test that assumes a previous test already logged in will fail in isolation or parallel execution.

Leaving Files or Actors Behind

Register generated Actors with RegisterAutoDestroyActor. Write files under a test-only temporary directory and remove them in teardown. Clean stale artifacts before startup as well, and make cleanup run after failures.

Comparing Floating-Point Values Exactly

Use an explicit tolerance for physics, timing, and coordinates.

TestTrue(
    TEXT("X is within tolerance"),
    FMath::IsNearlyEqual(Actual.X, Expected.X, 0.1f));

Creating Unreproducible Random Tests

Fix the seed and print both the seed and generated input on failure. Randomized testing should supplement deterministic boundary cases, not replace them.

Writing Vague Failure Messages

Include the condition, expected value, actual value, and target ID. A developer should be able to begin investigation from the CI log alone.

Expecting Live Coding to Register Everything

When a new test is missing from the list, close the Editor, run a normal build, and restart it. Registration depends on module loading.

Starting with Coverage Percentage

Begin with failures that matter: save compatibility, currency rules, combat boundaries, data references, or a level that cannot start. Frequently changed rules and QA flows that are checked manually every time are also strong candidates.

The first objective is not a percentage. It is preventing one important regression from returning.

A Gradual Adoption Plan

Add one World-independent rule test with CQTest or a Simple Automation Test.
Add a regression test before fixing the next reproducible bug.
Automate save/load compatibility and static-data validation.
Stabilize one representative Functional Test in a small dedicated map.
Commit the command-line scripts so local and CI execution use the same commands.
Track duration, retry success rate, and timeout locations, then remove flakiness instead of normalizing reruns.

Conclusion

Unreal Engine testing works best as a layered system:

CQTest, Automation Spec, and Simple or Complex Automation Tests for fast C++ behavior
Functional Tests for Actors, Components, Blueprints, and level wiring
Python Automation Tests for content-production rules
Automation Driver for a small number of representative UI flows
Gauntlet for packaged builds and multi-process environments
Low-Level Tests when dedicated execution speed justifies the extra build setup

For multi-frame work, wait for explicit completion or failure conditions with a clear timeout. In CI, parse Automation Reports instead of trusting only the Editor process exit code.

Do not start by building an end-to-end test for the whole game. Start with deterministic tests that run quickly and fail with enough information to diagnose the problem.

The useful milestone is not “we reached a coverage target.” It is:

When an important old bug returns, the build stops automatically.

References

A Practical Guide to Testing in Unity: EditMode, PlayMode, Async, and CI

GameDevToolLab — Thu, 30 Jul 2026 13:03:01 +0000

Introduction

Testing in Unity is more complicated than testing ordinary C# code.

A damage formula can be covered with a normal NUnit [Test], but a real game also contains MonoBehaviour, ScriptableObject, frame updates, coroutines, scenes, prefabs, physics, and asynchronous asset loading.

The practical questions are where to split EditMode and PlayMode, when [UnityTest] is necessary, how to handle lifecycle and asynchronous code, and which tests belong in CI.

This article uses Unity 6 and Unity Test Framework 1.6 as its baseline. It is written for programmers introducing automated tests or adding them incrementally to an existing project. The samples are intentionally small, so adjust omitted namespaces and project-specific types to your own assemblies.

The basic strategy is to keep game rules in fast pure-C# EditMode tests, test thin Unity adapters only where needed, reserve PlayMode for PlayerLoop or lifecycle behavior, and leave visual quality or device-specific performance to QA and device tests.

Tests do not prove that a game has no bugs. They provide a fast safety net when you refactor code, change specifications, or fix a regression.

What Unity Test Framework provides

Unity Test Framework is Unity's built-in testing system. It is based on NUnit and adds support for Unity-specific concepts such as frames, the application loop, domain reloads, and player execution.

The common ways to run tests are:

Test Runner inside the Unity Editor
Unity command-line execution for CI
TestRunnerApi for custom tooling

Use Test Runner during development, command-line execution in CI, and TestRunnerApi only when you need a custom test workflow.

Unity ships its own NUnit-compatible environment, so APIs from the latest standalone NUnit may not all be available or behave identically. Check the documentation for the Test Framework version bundled with your Editor, especially for asynchronous assertions.

EditMode and PlayMode tests

Unity tests are broadly divided into EditMode and PlayMode tests.

EditMode tests

EditMode tests run in the Editor without normal Play Mode. They suit calculations, save migration, probability rules, data validation, ScriptableObject logic, editor tooling, serialization, and static prefab or scene checks. Pure C# EditMode tests are usually fast enough to run continuously.

PlayMode tests

PlayMode tests execute in Unity's runtime environment. Use them for lifecycle callbacks, frame updates, coroutines, scene loading, runtime prefab wiring, animation transitions, physics, and behavior that appears only in a Player. They are slower and more sensitive to global state, so an all-PlayMode suite becomes expensive to diagnose.

A practical decision process

Ask these questions in order:

Does the behavior work without Unity APIs?
Does it need Unity objects but not frame progression?
Does it depend on the PlayerLoop, lifecycle events, scenes, or physics?
Does it require an actual target device?

Use pure EditMode tests for case 1, Unity-aware EditMode tests for case 2, PlayMode tests for case 3, and Player/device testing for case 4.

Create test assemblies first

Tests should live in assemblies that reference NUnit and the production assemblies they test.

A practical folder structure is:

Assets/
├── Game/
│   ├── Runtime/
│   │   ├── Game.Runtime.asmdef
│   │   ├── Battle/
│   │   └── Save/
│   └── Editor/
│       ├── Game.Editor.asmdef
│       └── Validation/
└── Tests/
    ├── EditMode/
    │   ├── Game.EditModeTests.asmdef
    │   ├── Battle/
    │   └── Save/
    └── PlayMode/
        ├── Game.PlayModeTests.asmdef
        ├── Battle/
        └── Scene/

An EditMode test assembly conceptually looks like this:

{
  "name": "Game.EditModeTests",
  "references": [
    "Game.Runtime"
  ],
  "includePlatforms": [
    "Editor"
  ],
  "optionalUnityReferences": [
    "TestAssemblies"
  ]
}

A PlayMode test assembly can target runtime platforms:

{
  "name": "Game.PlayModeTests",
  "references": [
    "Game.Runtime"
  ],
  "includePlatforms": [],
  "optionalUnityReferences": [
    "TestAssemblies"
  ]
}

Treat these JSON blocks as conceptual examples. Unity versions can generate different fields, so verify the settings in the Inspector instead of blindly replacing an .asmdef file.

A common obstacle in older projects is that production code still belongs to Assembly-CSharp.dll, which a test assembly cannot directly reference. Move one independent class into Game.Runtime.asmdef, reference it from the test assembly, and expand gradually. Keep UnityEditor APIs in a separate editor assembly and preserve a one-way dependency from presentation code toward lower-level logic.

Write the first pure C# test

Start with a class that has no Unity dependency.

namespace Game.Battle
{
    public sealed class DamageCalculator
    {
        public int Calculate(int attack, int defense)
        {
            var damage = attack - defense;
            return damage < 1 ? 1 : damage;
        }
    }
}

The test is ordinary NUnit code:

using Game.Battle;
using NUnit.Framework;

namespace Game.Tests.EditMode.Battle
{
    public sealed class DamageCalculatorTests
    {
        [Test]
        public void Calculate_AttackIsGreaterThanDefense_ReturnsDifference()
        {
            // Arrange
            var calculator = new DamageCalculator();

            // Act
            var actual = calculator.Calculate(attack: 100, defense: 30);

            // Assert
            Assert.That(actual, Is.EqualTo(70));
        }

        [Test]
        public void Calculate_DefenseIsGreaterThanAttack_ReturnsMinimumDamage()
        {
            var calculator = new DamageCalculator();

            var actual = calculator.Calculate(attack: 30, defense: 100);

            Assert.That(actual, Is.EqualTo(1));
        }
    }
}

Arrange, Act, and Assert are useful as a mental model:

Arrange the subject and inputs.
Act by executing one behavior.
Assert the result.

Comments are not mandatory in every short test. Clear spacing is often enough.

Test names should explain a failure. A useful convention is:

Method_Condition_ExpectedResult

For example:

Calculate_DefenseIsGreaterThanAttack_ReturnsMinimumDamage

The exact convention matters less than being able to infer what broke from the failed test name in CI.

Parameterize boundary cases

Use [TestCase] when the same rule must be checked with multiple inputs.

[TestCase(100, 30, 70)]
[TestCase(30, 100, 1)]
[TestCase(50, 50, 1)]
[TestCase(1, 0, 1)]
public void Calculate_WithVariousParameters_ReturnsExpectedDamage(
    int attack,
    int defense,
    int expected)
{
    var calculator = new DamageCalculator();

    var actual = calculator.Calculate(attack, defense);

    Assert.That(actual, Is.EqualTo(expected));
}

Parameterization is especially useful for:

minimum and maximum values
zero, one, and negative values
just below, exactly at, and just above a threshold
level and inventory caps
date boundaries
probability-table edges
rounding rules

For more complex cases, use [TestCaseSource]. TestCaseData allows readable names in CI output.

private static readonly TestCaseData[] Cases =
{
    new TestCaseData(100, 30, 70)
        .SetName("AttackGreaterThanDefense"),
    new TestCaseData(30, 100, 1)
        .SetName("DefenseGreaterThanAttack"),
};

[TestCaseSource(nameof(Cases))]
public void Calculate_WithCases_ReturnsExpected(
    int attack,
    int defense,
    int expected)
{
    var calculator = new DamageCalculator();

    Assert.That(calculator.Calculate(attack, defense), Is.EqualTo(expected));
}

Do not combine unrelated rules merely because the inputs fit into one parameter list. Parameterize data variations of the same behavior.

Assert behavior, not every field

A test becomes difficult to understand when it verifies many unrelated values. The goal is not "one assertion per test" but "one behavior per test."

Multiple assertions are appropriate when they describe one atomic result:

[Test]
public void ConsumePotion_WhenStockExists_HealsAndDecreasesStock()
{
    var inventory = new Inventory(potionCount: 2);
    var player = new Player(currentHp: 50, maxHp: 100);

    inventory.ConsumePotion(player);

    Assert.That(player.CurrentHp, Is.EqualTo(80));
    Assert.That(inventory.PotionCount, Is.EqualTo(1));
}

Healing the player and consuming one item are two parts of the same operation. Splitting them would duplicate setup without improving clarity.

Test ScriptableObject rules in EditMode

A ScriptableObject can be created without saving an asset.

using NUnit.Framework;
using UnityEngine;

public sealed class EnemyParameterTests
{
    private EnemyParameter _parameter;

    [SetUp]
    public void SetUp()
    {
        _parameter = ScriptableObject.CreateInstance<EnemyParameter>();
    }

    [TearDown]
    public void TearDown()
    {
        Object.DestroyImmediate(_parameter);
    }

    [Test]
    public void IsBoss_HpIsAtLeast10000_ReturnsTrue()
    {
        _parameter.Hp = 10000;

        Assert.That(_parameter.IsBoss, Is.True);
    }
}

The production type might be:

using UnityEngine;

[CreateAssetMenu(menuName = "Game/Enemy Parameter")]
public sealed class EnemyParameter : ScriptableObject
{
    [field: SerializeField]
    public int Hp { get; set; }

    public bool IsBoss => Hp >= 10000;
}

Destroy temporary EditMode objects with DestroyImmediate when appropriate. Put cleanup in [TearDown] so it still runs after an assertion failure.

Separate two concerns:

Test class rules with temporary instances.
Validate all real project assets in a dedicated project-validation test.

Tests that depend on exact asset paths or GUIDs are more fragile than tests against temporary instances.

Validate prefabs and assets

Automated tests are also effective at finding authoring mistakes.

Suppose every enemy prefab under Assets/Game/Enemies must have an EnemyController on its root:

using System.Linq;
using NUnit.Framework;
using UnityEditor;
using UnityEngine;

public sealed class EnemyPrefabValidationTests
{
    [Test]
    public void EnemyPrefabs_AllHaveEnemyController()
    {
        var guids = AssetDatabase.FindAssets(
            "t:Prefab",
            new[] { "Assets/Game/Enemies" });

        var invalidPaths = guids
            .Select(AssetDatabase.GUIDToAssetPath)
            .OrderBy(path => path)
            .Where(path =>
            {
                var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(path);
                return prefab == null ||
                       prefab.GetComponent<EnemyController>() == null;
            })
            .ToArray();

        Assert.That(
            invalidPaths,
            Is.Empty,
            $"Prefabs without EnemyController:\n{string.Join("\n", invalidPaths)}");
    }
}

This is closer to project validation than a unit test, but it is highly valuable. The same approach can detect missing components or scripts, broken references, duplicate IDs, invalid Addressables labels, missing localization keys, incorrect Layers or Tags, and assets that violate project rules.

The sample above only checks for EnemyController. Missing scripts require a separate validation, for example with GameObjectUtility.GetMonoBehavioursWithMissingScriptCount while traversing the prefab hierarchy.

A full project scan may be slow. Categorize it separately and run it in CI or at night instead of blocking every local edit.

[Category("AssetValidation")]
[Test]
public void EnemyPrefabs_AllHaveEnemyController()
{
    // Validation logic
}

Test MonoBehaviour correctly

Never instantiate a MonoBehaviour with new. Create a GameObject and use AddComponent<T>().

A method that does not require frame progression can still be tested in EditMode:

using NUnit.Framework;
using UnityEngine;

public sealed class HealthViewTests
{
    private GameObject _gameObject;

    [SetUp]
    public void SetUp()
    {
        _gameObject = new GameObject("HealthViewTest");
    }

    [TearDown]
    public void TearDown()
    {
        Object.DestroyImmediate(_gameObject);
    }

    [Test]
    public void SetHealth_WithHalfValue_StoresRatio()
    {
        var view = _gameObject.AddComponent<HealthView>();

        view.SetHealth(current: 50, max: 100);

        Assert.That(view.Ratio, Is.EqualTo(0.5f).Within(0.0001f));
    }
}

This does not test Awake or Start. It only verifies a public method on a component. Move to PlayMode when Unity lifecycle behavior is part of the specification.

Cross frames with UnityTest

When a PlayMode test must cross frames, use [UnityTest] and return IEnumerator. The attribute is also available in EditMode, but this example focuses on runtime lifecycle behavior.

using UnityEngine;

public sealed class PlayerInitializer : MonoBehaviour
{
    public bool IsInitialized { get; private set; }

    private void Start()
    {
        IsInitialized = true;
    }
}

The PlayMode test waits one frame before checking the result:

using System.Collections;
using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;

public sealed class PlayerInitializerTests
{
    [UnityTest]
    public IEnumerator Start_AfterOneFrame_InitializesPlayer()
    {
        var gameObject = new GameObject("Player");

        try
        {
            var initializer = gameObject.AddComponent<PlayerInitializer>();

            yield return null;

            Assert.That(initializer.IsInitialized, Is.True);
        }
        finally
        {
            Object.Destroy(gameObject);
        }
    }
}

yield return null waits until the next frame.

Object.Destroy is delayed until the end of the frame. try/finally ensures that destruction is requested even when an assertion fails. For fixtures that create multiple objects, or when destruction must complete before the next test, centralize cleanup in [UnityTearDown] and wait one frame.

Avoid arbitrary frame waits:

// Avoid this when there is no reason for exactly ten frames.
for (var i = 0; i < 10; i++)
{
    yield return null;
}

Prefer a completion condition with an upper bound:

[UnityTest]
public IEnumerator Load_WhenStarted_CompletesWithinFrames()
{
    var gameObject = new GameObject("Loader");

    try
    {
        var loader = gameObject.AddComponent<TestLoader>();
        loader.Begin();

        const int maxFrames = 120;
        for (var frame = 0; frame < maxFrames && !loader.IsCompleted; frame++)
        {
            yield return null;
        }

        Assert.That(
            loader.IsCompleted,
            Is.True,
            "Loading did not complete within 120 frames.");
    }
    finally
    {
        Object.Destroy(gameObject);
    }
}

Do not use a frame limit for work whose duration depends heavily on machine performance or real I/O. For those cases, inject the dependency or expose an explicit completion signal.

Choose Test or UnityTest by behavior

Use [Test] when the operation is synchronous and does not need frame progression:

[Test]
public void Calculate_WhenCalled_ReturnsExpected()
{
    // Synchronous behavior
}

Use [UnityTest] when you need:

yield return null
coroutine progression
WaitForFixedUpdate
lifecycle changes across frames
Unity-specific yield instructions

A test in a PlayMode assembly does not automatically require [UnityTest]. A normal [Test] is valid there when it completes synchronously.

Keep physics tests broad and deterministic

A physics test may wait for fixed updates:

[UnityTest]
public IEnumerator Rigidbody_AfterFixedUpdate_FallsDown()
{
    var gameObject = GameObject.CreatePrimitive(PrimitiveType.Cube);

    try
    {
        gameObject.AddComponent<Rigidbody>();
        var initialY = gameObject.transform.position.y;

        yield return new WaitForFixedUpdate();
        yield return new WaitForFixedUpdate();

        Assert.That(
            gameObject.transform.position.y,
            Is.LessThan(initialY));
    }
    finally
    {
        Object.Destroy(gameObject);
    }
}

This verifies only the broad behavior: gravity moves the object downward. Exact coordinates after a fixed number of frames are fragile because they depend on Unity version, physics settings, fixed delta time, and floating-point behavior.

Prefer these strategies:

use tolerances instead of exact floating-point equality
verify direction or range rather than a precise final coordinate
extract your own decision logic into pure C# tests
set and restore physics settings explicitly
isolate high-precision simulation in a dedicated suite

You do not need to retest Unity's physics engine. Test that your code configures it correctly and interprets its results correctly.

Test asynchronous code without real waiting

Unity Test Framework supports tests that return .NET Task.

using System.Threading.Tasks;
using NUnit.Framework;

public sealed class UserRepositoryTests
{
    [Test]
    public async Task LoadAsync_ExistingUser_ReturnsUser()
    {
        var repository = new FakeUserRepository();
        repository.Add(new User(id: 10, name: "Alice"));

        var user = await repository.LoadAsync(10);

        Assert.That(user.Name, Is.EqualTo("Alice"));
    }
}

Avoid real delays:

// Avoid this in an ordinary unit test.
await Task.Delay(5000);

Twenty five-second tests already add 100 seconds. Real network access also makes results depend on authentication, server data, and connectivity.

Most asynchronous tests should verify the result, error conversion, cancellation, state update, and duplicate-execution rules rather than elapsed time.

Inject external work behind an interface:

public interface IUserApi
{
    Task<UserDto> GetAsync(int userId);
}

public sealed class UserService
{
    private readonly IUserApi _api;

    public UserService(IUserApi api)
    {
        _api = api;
    }

    public async Task<User> LoadAsync(int userId)
    {
        var dto = await _api.GetAsync(userId);
        return new User(dto.Id, dto.Name);
    }
}

Use a fake that completes immediately:

public sealed class FakeUserApi : IUserApi
{
    private readonly UserDto _response;

    public FakeUserApi(UserDto response)
    {
        _response = response;
    }

    public Task<UserDto> GetAsync(int userId)
    {
        return Task.FromResult(_response);
    }
}

Then test conversion without network access:

[Test]
public async Task LoadAsync_ApiSucceeds_ConvertsDto()
{
    var api = new FakeUserApi(new UserDto(10, "Alice"));
    var service = new UserService(api);

    var user = await service.LoadAsync(10);

    Assert.That(user.Id, Is.EqualTo(10));
    Assert.That(user.Name, Is.EqualTo("Alice"));
}

Keep real connectivity checks in a small integration suite with controlled credentials and environments.

Awaitable and UniTask require extra care

Unity 6 projects increasingly use Awaitable, while many existing projects use UniTask.

Separate two questions:

What return type does the test method use?
What asynchronous type does production code return?

For Unity Test Framework 1.6, prefer supported async Task test methods. Use [UnityTest] and IEnumerator for coroutine-style frame tests. Production code may return Awaitable or UniTask, but tests must be able to observe completion.

Being awaitable does not mean a workflow is safe in an EditMode test. Pure C# transformations and cancellation rules belong in EditMode. Operations based on Awaitable.NextFrameAsync, UniTask Yield or DelayFrame, scene loading, Addressables, and Unity object lifecycles should be tested in PlayMode or in a built Player.

Important constraints are that Unity Awaitable instances are pooled and must not be awaited twice; UniTask should also be treated as single-consumption unless its documented preservation mechanisms are used. PlayerLoop-dependent APIs can differ across EditMode, PlayMode, Player, and BatchMode. Return to the main thread before touching Unity APIs, avoid async void, UniTaskVoid, and .Forget() in testable inner APIs, and provide cancellation for operations that may not complete.

A production event handler may need fire-and-forget behavior. Keep the inner operation awaitable and test that inner method directly. Otherwise an exception or state change can occur after the test has already finished and leak into another test.

Also run PlayerLoop-dependent asynchronous tests in CI with -batchmode. Do not terminate the Editor before the test result XML and exit code are produced.

Inject time and randomness

Current time and randomness are common sources of flaky tests.

Avoid reading local time inside business logic:

public bool CanReceiveDailyBonus()
{
    return DateTime.Now.Date > _lastReceivedAt.Date;
}

The result changes at a date boundary and may differ across CI time zones.

Make the clock explicit:

public interface IClock
{
    DateTimeOffset UtcNow { get; }
}

public sealed class DailyBonusService
{
    private readonly IClock _clock;

    public DailyBonusService(IClock clock)
    {
        _clock = clock;
    }

    public bool CanReceive(DateTimeOffset lastReceivedAt)
    {
        return _clock.UtcNow.Date >
               lastReceivedAt.ToUniversalTime().Date;
    }
}

Use a fixed clock in tests:

public sealed class FixedClock : IClock
{
    public FixedClock(DateTimeOffset utcNow)
    {
        UtcNow = utcNow.ToUniversalTime();
    }

    public DateTimeOffset UtcNow { get; }
}

[Test]
public void CanReceive_WhenUtcDateChanged_ReturnsTrue()
{
    var clock = new FixedClock(
        new DateTimeOffset(2026, 7, 26, 0, 0, 0, TimeSpan.Zero));
    var service = new DailyBonusService(clock);

    var result = service.CanReceive(
        new DateTimeOffset(2026, 7, 25, 23, 59, 59, TimeSpan.Zero));

    Assert.That(result, Is.True);
}

The actual product specification must also define whether the source of truth is UTC, server time, or a region-specific reset time.

Randomness should be injected in the same way:

public interface IRandom
{
    int Range(int minInclusive, int maxExclusive);
}

A fake can return a chosen value so rare drops and critical-hit branches are deterministic. This also helps replay systems, debugging, and synchronization with a server.

A mock library is optional

Do not introduce a mocking framework merely because an article about testing mentions mocks. A handwritten fake is often clearer in Unity projects.

public sealed class RecordingAnalytics : IAnalytics
{
    public List<string> Events { get; } = new();

    public void Send(string eventName)
    {
        Events.Add(eventName);
    }
}

[Test]
public void Purchase_WhenSucceeded_SendsAnalyticsEvent()
{
    var analytics = new RecordingAnalytics();
    var service = new PurchaseService(analytics);

    service.Complete();

    Assert.That(analytics.Events, Does.Contain("purchase_completed"));
}

Handwritten fakes are easy to inspect, debug, and keep compatible across Unity and .NET versions. A mocking library becomes useful when many dependencies require extensive call and argument verification.

If mock setup dominates the test, the production class may have too many responsibilities.

Test exceptions and logs

For synchronous exceptions, use Assert.Throws:

[Test]
public void Constructor_MaxHpIsZero_ThrowsArgumentOutOfRangeException()
{
    Assert.Throws<ArgumentOutOfRangeException>(
        () => new Player(maxHp: 0));
}

Be careful with Assert.ThrowsAsync in Unity. Unity's documentation warns that blocking the caller while an operation needs the main thread can freeze the Editor. A safe pattern is to await in an async Task test and inspect the exception with try/catch:

[Test]
public async Task LoadAsync_WhenApiFails_ThrowsUserLoadException()
{
    try
    {
        await _service.LoadAsync(userId: 10);
        Assert.Fail("UserLoadException was not thrown.");
    }
    catch (UserLoadException exception)
    {
        Assert.That(exception.ErrorCode, Is.EqualTo("network_error"));
    }
}

For failures that are part of normal control flow, a result type can be clearer than exceptions.

Unity normally fails a test when an unexpected error or exception is logged. Register expected logs explicitly:

using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;

[Test]
public void Load_InvalidId_LogsError()
{
    LogAssert.Expect(LogType.Error, "Invalid user id: -1");

    var loader = new UserLoader();
    loader.Load(-1);
}

Use a regular expression for dynamic values:

using System.Text.RegularExpressions;

LogAssert.Expect(
    LogType.Error,
    new Regex(@"Invalid user id: -?\d+"));

Do not use logs as the only failure signal when callers must react. Return a result, throw a meaningful exception, or expose a state that can be asserted.

Isolate state with SetUp and TearDown

Every test must behave the same alone and as part of the full suite.

public sealed class PlayerControllerTests
{
    private GameObject _gameObject;
    private PlayerController _controller;

    [SetUp]
    public void SetUp()
    {
        _gameObject = new GameObject("Player");
        _controller = _gameObject.AddComponent<PlayerController>();
    }

    [TearDown]
    public void TearDown()
    {
        Object.DestroyImmediate(_gameObject);
    }

    [Test]
    public void SetSpeed_PositiveValue_UpdatesSpeed()
    {
        _controller.SetSpeed(5f);

        Assert.That(_controller.Speed, Is.EqualTo(5f));
    }
}

In PlayMode, destruction is delayed. Use [UnityTearDown] when you must destroy multiple objects and wait for completion:

private readonly List<GameObject> _createdObjects = new();

[UnityTearDown]
public IEnumerator TearDown()
{
    foreach (var gameObject in _createdObjects)
    {
        if (gameObject != null)
        {
            Object.Destroy(gameObject);
        }
    }

    _createdObjects.Clear();

    yield return null;
}

Record each created object immediately after creation so cleanup still occurs after an assertion failure.

Common leaks include static fields, singletons, PlayerPrefs, time and physics settings, Random.state, scenes, temporary assets, event subscriptions, cancellation sources, Addressables handles, and DontDestroyOnLoad objects.

Save global settings before changing them and restore them in teardown:

private float _originalTimeScale;

[SetUp]
public void SetUp()
{
    _originalTimeScale = Time.timeScale;
    Time.timeScale = 2f;
}

[TearDown]
public void TearDown()
{
    Time.timeScale = _originalTimeScale;
}

Never depend on test order

A suite that assumes this order is fragile:

1. CreateUser
2. UpdateUser
3. DeleteUser

UpdateUser fails when run by itself. Each test should create and remove its own state:

[Test]
public void UpdateUser_ExistingUser_ChangesName()
{
    var repository = new InMemoryUserRepository();
    repository.Add(new User(10, "Before"));

    repository.Update(new User(10, "After"));

    Assert.That(repository.Find(10).Name, Is.EqualTo("After"));
}

Long end-to-end flows can be useful, but treat them as a separate scenario layer rather than chaining unit tests.

Write tests that survive refactoring

Test observable behavior instead of implementation details.

Private methods are implementation details; extract a separate responsibility when it deserves direct testing. Call counts alone do not prove player-visible behavior, so combine interactions with output or state assertions. Avoid hard-coding Transform hierarchy details: a UI test tied to a path such as this breaks during harmless cleanup:

Canvas/Root/Window/Content/Panel/Buttons/Button_01

Assert identifiers, components, and visible states that are part of the specification, not child indices that exist only for implementation convenience.

Wait for completion, not elapsed time

Prefer a completion flag, event, or task over:

yield return new WaitForSeconds(3f);

Keep whole-scene tests rare

Scene tests are valuable but expensive to prepare and diagnose. Build a pyramid of pure logic tests, prefab-level tests, and a small number of scene-level scenarios.

Testable design does not mean removing MonoBehaviour

MonoBehaviour is the correct place to receive Unity events, hold Inspector references, and control GameObjects. The problem is placing game rules, storage, networking, time, randomness, and presentation logic in the same component.

A useful division is:

PlayerPresenter : MonoBehaviour
├── receives input and lifecycle events
├── updates the View
└── calls PlayerUseCase

PlayerUseCase : Pure C#
├── damage and item rules
├── state transitions
└── calls repositories

Cover PlayerUseCase with many fast EditMode tests. Give PlayerPresenter a small number of tests that verify wiring between Unity events, the use case, and the view.

A dependency-injection container is not required. Constructors, initialization methods, serialized references, or factories are sufficient when they make dependencies explicit.

Introduce tests into an existing project incrementally

Do not begin by redesigning the entire codebase.

1. Select frequently changed, high-impact rules

Good first targets include:

paid-item grants
save-data migration
daily reset logic
stamina recovery
damage formulas
reward selection
API response conversion
master-data validation

2. Add characterization tests

When the intended specification is unclear, record the current input and output before refactoring. A characterization test does not claim that the existing implementation is ideal. It prevents accidental behavior changes while you improve it.

3. Cut one Unity-dependent boundary

Extract the dependency that blocks testing most: time, randomness, networking, or file I/O. There is no need to convert the entire project to a new architecture at once.

4. Add a regression test with each bug fix

When possible:

reproduce the bug with a failing test
fix the code
confirm that the test passes

5. Standardize new and modified code first

A rule that new features and changed high-risk code receive tests is more sustainable than trying to cover every legacy class immediately.

Decide what not to test

More tests do not automatically mean higher quality.

Do not retest Unity's own APIs or trivial properties without custom rules. Pixel-perfect visuals, animation appeal, input feel, thermal behavior, and device memory need QA, screenshots, performance tests, or device runs. Avoid detailed tests for short-lived prototypes, but still cover complex calculations. Derive expectations from specification examples rather than copying the production formula into the test.

Run tests in CI

Once tests matter, manual execution is not enough.

A conceptual Windows command for EditMode tests is shown below. The example assumes that CI provides the path to the project-pinned Unity Editor through an environment variable named UNITY_EDITOR_PATH.

$UnityPath = $env:UNITY_EDITOR_PATH

if ([string]::IsNullOrWhiteSpace($UnityPath) -or
    -not (Test-Path $UnityPath))
{
    throw "UNITY_EDITOR_PATH is not configured correctly."
}

& $UnityPath `
  -runTests `
  -batchmode `
  -projectPath "D:\Projects\MyGame" `
  -testPlatform EditMode `
  -testResults "D:\TestResults\editmode-results.xml" `
  -logFile "D:\TestResults\editmode-editor.log"

Run PlayMode separately:

& $UnityPath `
  -runTests `
  -batchmode `
  -projectPath "D:\Projects\MyGame" `
  -testPlatform PlayMode `
  -testResults "D:\TestResults\playmode-results.xml" `
  -logFile "D:\TestResults\playmode-editor.log"

UNITY_EDITOR_PATH is not a Unity-reserved name. It is only an example of how to provide the exact Editor executable chosen by your project.

At minimum, retain:

test-result XML
Editor log
Unity process exit code
Unity Editor version
branch and commit hash

Layer the pipeline: pull requests run compilation, fast EditMode tests, critical validation, and a small PlayMode smoke suite; main-branch builds run the full Editor suite and asset checks; nightly or release jobs run built-Player, target-platform, long-scenario, and performance tests. Do not put every slow test on every pull request.

Also avoid adding -nographics blindly when tests require rendering or a GPU-dependent path.

Use categories as CI execution units

Categories are useful only when they are connected to actual workflows.

[Category("Fast")]
[Test]
public void Calculate_ReturnsExpected()
{
}

[Category("AssetValidation")]
[Test]
public void ValidateAllAssets()
{
}

[Category("Integration")]
[UnityTest]
public IEnumerator LoginFlow_Completes()
{
    yield return null;
}

Run the Fast EditMode category in CI:

& $UnityPath `
  -runTests `
  -batchmode `
  -projectPath "D:\Projects\MyGame" `
  -testPlatform EditMode `
  -testCategory "Fast" `
  -testResults "D:\TestResults\fast-editmode-results.xml" `
  -logFile "D:\TestResults\fast-editmode-editor.log"

Unity Test Framework also supports filtering by test assembly with -assemblyNames. Check the command-line reference for the exact syntax supported by your Unity version, including multiple categories and exclusions.

Keep the category list small and aligned with pipeline stages. Examples include Fast, Integration, Scene, AssetValidation, RequiresGraphics, RequiresDevice, and Performance.

Do not leave [Ignore] without a reason. Record the issue, reason, and condition for re-enabling the test.

Do not optimize for 100% coverage

Coverage shows which lines ran, not whether important behavior was asserted. Prioritize rules such as preventing duplicate paid-item grants, preserving save data during migration, enforcing daily-reward and currency caps, and avoiding duplicate requests during retries. Use coverage to find suspicious gaps, not as the sole performance target.

Monitor test duration

Developers stop running slow suites. Watch for EditMode tests that take seconds, repeated full AssetDatabase scans, unnecessary scene loads, real services, arbitrary waits, and expensive setup. Separate fast and slow suites, record duration in CI, and never improve speed by sharing mutable state between tests.

Common failure patterns

Avoid five recurring mistakes:

Do not write every test in PlayMode; keep game rules in pure C# where possible.
Do not add test-only branches to production code; inject alternate dependencies instead.
Do not depend on the scene that happened to be open when Test Runner started.
Do not hide unexpected errors with broad LogAssert.ignoreFailingMessages or retries.
Review test code for weak assertions, arbitrary waits, and cleanup leaks.

A minimal team policy

A small rule set is enough to begin:

Prefer EditMode for game rules and use [UnityTest] only for frame progression.
Make tests independent and clean up objects, assets, events, and global state.
Replace real time, real networks, current time, and uncontrolled randomness with explicit dependencies.
Add regression tests for important bug fixes.
Run a fast suite on pull requests and record why any test is ignored.
Explicitly decide which concerns remain in QA, device, or performance testing.

Measure whether tests reduce regression risk and verification time, not merely how many tests exist.

Recommended adoption priority

Start with save migration, paid-item grants, response conversion, date rules, reward and currency calculations, caps, duplicate IDs, and recurring bugs. Next, add prefab, scene, Addressables, localization, presenter, state-machine, and analytics validation. Visual appeal, input feel, GPU behavior, device heat, memory pressure, long sessions, and multi-device communication need QA, performance, screenshot, or scenario testing rather than ordinary unit tests.

Unreal Engine uses a different stack—Automation Framework, Automation Spec, Functional Testing, and Gauntlet—so it is better treated in a separate article.

Conclusion

Unity testing is not about reproducing the entire game in every test. Cover game rules and data transformations with fast EditMode tests, validate assets with focused editor checks, and use PlayMode only where lifecycle events, frames, scenes, or physics are part of the behavior.

For asynchronous work, inject external services, clocks, randomness, storage, and cancellation so tests can observe completion without real waiting. Existing projects can start with high-impact rules, recurring bugs, save migration, and static asset validation instead of an immediate rewrite.

The useful metric is whether the team can change the game and verify critical behavior quickly. Unity Test Framework is a programmer's safety net, not a replacement for QA.

DEV Community: GameDevToolLab

Practical UE5 File Loading Optimization: Beyond Parallel I/O and Raising the FPS Cap

Decompose load time first

Separate loading from waiting with Unreal Insights

The largest optimization is not loading the asset

Load by experience phase with Asset Manager

Parallel loading is not “the more, the faster”

Do not represent readiness with one boolean

Can a higher FPS cap make loading faster?

Avoid routine synchronous flushes

Tune IoStore, Zen Loader, and Oodle together

World Partition is not only Cell Size

Optimize activation and second-stage resources

Custom files need Read, Decode, and Apply stages

Prefetch from player intent and control memory overlap

Fast Geometry Streaming is not the default answer

A practical workflow

Conclusion

References

Where Unity Burst and Jobs Actually Help: A Practical Guide for GameObject-Based Projects

Introduction

When Burst and Jobs are a good fit

Understand the four separate roles

Four questions before introducing Jobs

Is CPU computation really the bottleneck?

Is each element independent?

Can the managed boundary stay small?

Can waiting be delayed?

Start with IJobFor and fixed-index output

Practical example: target evaluation with one-frame latency

Input, output, and the job

Define the target contract

Build pipelines instead of isolated jobs

Variable-length output and ParallelWriter

NativeContainer lifetime and batch size

GameObjects, Transforms, and data boundaries

Write kernels Burst can optimize

Invalidate results instead of canceling jobs

Measure the complete system

A practical adoption sequence

Conclusion

References

Unity Mipmaps Beyond Smaller Textures: Temporal Stability, Streaming, and Semantic Mips

Introduction

Mipmaps Match Sampling Density, Not Distance

Bilinear, trilinear, and anisotropic filtering solve different problems

Ideal LOD and resident quality are separate

The 33% Cost Hides a More Useful Fact

Why “No Mipmaps” Can Win a Screenshot Comparison

Configure Import Settings by Meaning, Not File Extension

sRGB is semantic

Box, Kaiser, and negative bias

Failure Case 1: Foliage and Fences Disappear

Failure Case 2: Normal Maps Still Produce Flashing Highlights

Failure Case 3: Packed Masks Share One Mip Policy

Failure Case 4: Atlas Bleeding Gets Worse at Lower Mips

Mipmap Limits and Streaming as a Quality Scheduler

Visualize the Approximate Mip Level

Technique 1: Semantic Mipmaps

Technique 2: Use the Mip Chain as a Hierarchical Data Structure

Technique 3: Automate Import Rules by Semantic Suffix

Dynamic Resolution, Upscalers, and Mip Bias

A Practical Decision Flow

Common Mipmap Myths

Conclusion

References

Is LitMotion the Best Tween Library for Unity in 2026? A Practical Guide

My recommendation

LitMotion, PrimeTween, and DOTween

LitMotion

PrimeTween

DOTween

What about MagicTween?

Do not choose from a benchmark alone

Installing LitMotion

The core pattern: Create, configure, Bind

Ease, delay, and loops

MotionHandle: stop old animations before starting new ones

AddTo(gameObject) and CancellationToken are different tools

UI animation while Time.timeScale == 0

Start with `IJobFor` and fixed-index output

Variable-length output and `ParallelWriter`

`MotionHandle`: stop old animations before starting new ones

`AddTo(gameObject)` and CancellationToken are different tools

UI animation while `Time.timeScale == 0`

UniTask: `await handle` and `ToUniTask()` do not cancel the same way

Abstract audio before `AudioSource` calls spread everywhere