DEV Community: GameDevToolLab

Unity 6.3 Memory Management: When to Use GC, Destroy, and Dispose

GameDevToolLab — Fri, 02 Oct 2026 05:34:32 +0000

Introduction

Should you assign null, call Destroy, or use Dispose? What about Resources.UnloadUnusedAssets and GC.Collect?

The confusion starts when dropping a C# reference, destroying a Unity object, and releasing an acquired asset reference are treated as the same operation. Unity uses several kinds of memory; garbage collection does not manage them all.¹

This guide starts with how a resource was acquired, who owns it, and how long it remains in use. The goal is to prevent both leaks and premature cleanup of resources that someone still needs.

Scope and validation: This article targets Unity 6.3 LTS (6000.3) and conventional GameObject/MonoBehaviour development. The Japanese source records a documentation review dated September 15, 2026, using Addressables 2.10, Collections 2.6, and Memory Profiler 1.1 documentation. Package versions are separate from the Editor version. Entities-specific lifecycles and native plugin internals are outside this article's scope.

An independent review of the Japanese version reported successful compilation of the four complete C# examples in Unity 6000.3.22f1, Addressables 2.10.3, and Collections 2.6.3. That report is not a runtime test. This English edition has not been recompiled, run in a Player, or measured on a target device; comments and diagnostic messages have been translated.

1. Choose the cleanup method by acquisition, not just type

Unity distinguishes managed memory, C# unmanaged memory, and native memory. Allocations accessed through NativeArray and similar APIs may appear under native memory in the Profiler. C# garbage collection cannot reclaim every kind of Unity or GPU resource. IL2CPP still uses garbage collection for managed memory.¹

How the resource was acquired	Normal cleanup	Common mistake
Ordinary C# object, array, or `List<T>`	Remove unnecessary references; let GC reclaim it	Expecting `null` to free memory immediately
GameObject from `Object.Instantiate`	`Destroy` the instance you own	Treating deactivation as destruction
Material, Mesh, Texture2D, or ScriptableObject you created	The owner calls `Destroy`	Destroying a shared asset you only reference
`Addressables.LoadAssetAsync`	`Addressables.Release` the acquired handle	Calling `Destroy` on the asset instead
Instance from `Addressables.InstantiateAsync`	Use `Addressables.ReleaseInstance` for manual cleanup	Confusing it with an ordinary `Instantiate` clone
`NativeArray` or similar allocation you own	`Dispose`, respecting allocator lifetime and Job dependencies	Disposing borrowed views or copies twice
Owned object from `new RenderTexture`	Stop using it; `Destroy` for final cleanup, `Release` for GPU resources only	Assuming `Release` destroys the object
`RenderTexture.GetTemporary`	`RenderTexture.ReleaseTemporary`	Destroying a borrowed resource
`GraphicsBuffer` or `ComputeBuffer` you created	`Dispose` or the corresponding `Release`	Only dropping the C# reference
Owned file, network, or other `IDisposable` resource	`using` or `Dispose`	Assuming the interface executes cleanup automatically

The following sections provide the API references. The rule is: pair acquisition with the matching cleanup, at the end of the agreed lifetime. When passing a resource elsewhere, distinguish ownership transfer from borrowing.

A generated Texture2D and one loaded through Addressables have the same type but different cleanup requirements. Avoid a generic ReleaseEverything(UnityEngine.Object obj) that decides solely from the type.

2. Why memory remains even with garbage collection

Assigning `null` removes one reference

An ordinary C# object becomes eligible for collection when it is no longer reachable. Setting one variable to null does not help while another reference keeps it alive.²

var data = new byte[1024 * 1024];
var anotherReference = data;

data = null;

// anotherReference still refers to the same array.
// Setting data to null does not remove that other reference.
Debug.Log(anotherReference.Length);

Common retention paths include static collections and persistent services holding scene objects. Closing a screen does not remove references from those longer-lived owners, which can also retain the objects' associated data.

Ask what still keeps the object reachable, not whether you wrote null. Memory Profiler identifies unintended references and missing cleanup as common causes of leaks.³

`List<T>.Clear()` does not discard capacity

Clear() sets the count to zero and removes references held by the elements, but retains Capacity. Consider TrimExcess() or changing Capacity separately when reducing the backing storage is appropriate.⁴

// Assume items is a List<ItemData> held by this class.
items.Clear();

// Consider this only at a boundary where large capacity is no longer needed.
items.TrimExcess();

Shrinking every frame only to grow again adds unnecessary work. Keep capacity for reusable working buffers; consider shrinking after unusually large temporary workloads at a screen or session boundary.

Also, List<GameObject>.Clear() does not destroy its GameObjects, and List<IDisposable>.Clear() does not dispose its elements. Cleaning up each resource and removing collection references are separate steps.

`Dispose` is not another name for GC

IDisposable defines explicit resource cleanup. GC does not discover the interface and automatically call Dispose(). The caller must arrange it through using or try/finally.⁵

Implementing IDisposable on a MonoBehaviour likewise does not make Destroy call it. Connect disposal to your component's cleanup path explicitly.

3. What `Destroy` does—and does not—destroy

GameObject destruction is separate from asset cleanup

Destroy(gameObject) destroys that GameObject, its components, and its Transform children. It does not recursively destroy every Material or Texture referenced by those components.⁶⁷

Ten character instances may share one Material and Texture. Destroying those assets when one character dies would break the other nine. Keep instance lifetime separate from shared asset lifetime.

Actual destruction is deferred until after the current Update loop. Do not diagnose a leak from a measurement immediately after calling Destroy, or replace it with DestroyImmediate in runtime code. Account for deferred destruction in the lifecycle instead.⁶

Unity's `== null` does not only mean “no C# reference”

A UnityEngine.Object has a managed object and a corresponding native object. After native destruction, the managed object can remain: Unity's == null may be true while ReferenceEquals(obj, null) is false.⁸

A destroyed component retained in a static field can still keep its large managed arrays alive. Memory Profiler exposes this kind of state as a Leaked Managed Shell.⁹

Use Unity's operator when testing a Unity object's lifetime:

if (target != null)
{
    target.DoSomething();
}

The ?. and ?? operators do not perform Unity's destroyed-object check. target?.DoSomething() is not a safe guard against a destroyed component. This does not prohibit those operators on ordinary C# objects.⁸

Putting everything in `OnDestroy` is not enough

Choose cleanup points according to the required lifetime.

Required lifetime	Acquisition and cleanup
Only while enabled	Start in `OnEnable`; end in `OnDisable`
While the component exists	Acquire during initialization; use explicit cleanup / `OnDestroy`
One operation	`using` or `try/finally`
Across multiple screens or scenes	An explicit, longer-lived owner

OnDestroy is only called for GameObjects that were previously active. If another system injects resources into an object that remains inactive, that system needs an explicit cleanup path rather than relying only on OnDestroy.¹⁰

The examples below are ordinary runtime components. ExecuteAlways and Editor extensions require cleanup paths beyond normal Play Mode lifecycles.

4. Track the Materials, Meshes, and Textures you create

Some getters can create instances

renderer.material can instantiate a Material. The first access to MeshFilter.mesh can duplicate an existing Mesh or create a new one. Cleanup of the generated objects is your responsibility.⁷¹¹

This does not mean every read of the same Renderer's material creates another Material. The risk is overlooking the initial instantiation or later replacement and recreation.

For reference-only access, consider sharedMaterial and sharedMesh. Changes to shared objects affect other users; sharing is not permission to modify them indiscriminately.

Example: destroy only the Material you explicitly cloned

Save this as RuntimeMaterialOwner.cs and attach it to a MeshRenderer with one Material. This component assumes exclusive control of the Renderer's first Material slot.

using UnityEngine;

[RequireComponent(typeof(MeshRenderer))]
public sealed class RuntimeMaterialOwner : MonoBehaviour
{
    private MeshRenderer _renderer;
    private Material _originalMaterial;
    private Material _ownedMaterial;

    private void Awake()
    {
        _renderer = GetComponent<MeshRenderer>();
        _originalMaterial = _renderer.sharedMaterial;

        if (_originalMaterial == null)
        {
            Debug.LogError("Assign a source Material to clone.", this);
            return;
        }

        // Create the owned Material explicitly instead of relying on an implicit clone.
        _ownedMaterial = new Material(_originalMaterial)
        {
            name = _originalMaterial.name + " (Owned Runtime)"
        };
        _renderer.sharedMaterial = _ownedMaterial;
    }

    public void ReleaseOwnedMaterial()
    {
        Material owned = _ownedMaterial;
        _ownedMaterial = null;

        if (_renderer != null &&
            _renderer.sharedMaterial == owned && owned != null)
        {
            _renderer.sharedMaterial = _originalMaterial;
        }

        _originalMaterial = null;

        if (owned != null)
        {
            Destroy(owned);
        }
    }

    private void OnDestroy()
    {
        ReleaseOwnedMaterial();
    }
}

Cleanup destroys the Material recorded when it was created, without accessing renderer.material again. Calling ReleaseOwnedMaterial() before OnDestroy leaves the ownership field empty, so the later call does not destroy it again.

Do not share this owned Material with other objects. To share it, move ownership to something that outlives every user. Cloning a Material does not give you ownership of its Textures. Retain any Addressables handles needed while the source assets are used.

Apply the same pattern to new Mesh, new Texture2D, and ScriptableObject.CreateInstance. Do not include Inspector-assigned shared assets in this cleanup indiscriminately.

5. Match Addressables acquisitions with releases

`Release` relinquishes an acquired reference

Addressables tracks assets and AssetBundles with its own reference counts. Explicit loads need corresponding releases; assigning a C# variable to null does not decrement those counts.¹²

Retain a handle while using its result. Copying the handle does not acquire an independent reference. An additional owner needs an explicit acquisition, such as a separate load or the documented Acquire operation, and a matching release.¹³

IsValid() is not an ownership flag telling you whether your caller still owes a release. Another user can retain the same underlying operation. Track your own ownership and released state separately.

Example: release a screen's acquisition even during loading

Save this as AddressableRawImage.cs and attach it to a UGUI RawImage. Install UGUI and Addressables, mark a Texture as Addressable, and set its address. This component alone writes the RawImage's texture, retaining the asset only while the component is active and enabled.

using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.ResourceManagement.AsyncOperations;
using UnityEngine.UI;

[RequireComponent(typeof(RawImage))]
public sealed class AddressableRawImage : MonoBehaviour
{
    [SerializeField] private string _address;

    private RawImage _image;
    private AsyncOperationHandle<Texture2D> _handle;
    private bool _ownsHandle;

    private void Awake()
    {
        _image = GetComponent<RawImage>();
    }

    private void OnEnable()
    {
        if (string.IsNullOrWhiteSpace(_address))
        {
            Debug.LogError("Set the Texture address.", this);
            return;
        }

        _handle = Addressables.LoadAssetAsync<Texture2D>(_address);
        _ownsHandle = true;
        _handle.Completed += OnCompleted;
    }

    private void OnCompleted(AsyncOperationHandle<Texture2D> handle)
    {
        if (!_ownsHandle || !handle.Equals(_handle))
        {
            return;
        }

        if (handle.Status != AsyncOperationStatus.Succeeded)
        {
            string error = handle.OperationException?.Message
                ?? "Unknown loading error";
            ReleaseLoad();
            Debug.LogError($"Failed to load Texture: {error}", this);
            return;
        }

        if (_image == null)
        {
            ReleaseLoad();
            return;
        }

        _image.texture = handle.Result;
    }

    private void ReleaseLoad()
    {
        if (!_ownsHandle)
        {
            return;
        }

        var handle = _handle;
        _ownsHandle = false;
        _handle = default;

        // Stop using the asset before releasing the handle.
        if (_image != null)
        {
            _image.texture = null;
        }

        if (handle.IsValid())
        {
            handle.Completed -= OnCompleted;
            Addressables.Release(handle);
        }
    }

    private void OnDisable() => ReleaseLoad();
    private void OnDestroy() => ReleaseLoad();
}

The example releases failed operations as well as successful ones: failed handles still have operation instance data to release.¹³

Releasing before completion does not immediately cancel the underlying load. Addressables allows a pending acquisition to be released, with cleanup occurring after completion. The example also removes the callback so it cannot update a closed screen.¹⁴

Do not confuse ordinary `Instantiate` with `InstantiateAsync`

Cloning a Prefab loaded through LoadAssetAsync<GameObject> with ordinary Object.Instantiate does not automatically increment Addressables' reference count for that clone. Releasing the load handle while clones remain can invalidate the lifetimes of their dependent Materials and Textures.¹⁵

Keep the Prefab load handle until all owned clones have finished being destroyed. Because Destroy is deferred, do not release the final handle immediately after requesting destruction. Inactive instances waiting in a pool still count as users.

For manual cleanup of Addressables.InstantiateAsync instances, use ReleaseInstance. With the default trackHandle: true, you can pass the instance; with false, retain the operation handle and pass it to ReleaseInstance(handle) instead. Do not release twice through different cleanup paths.¹⁶¹⁷

Scene unloading can automatically release instances created with trackHandle: true. That does not mean every asset separately acquired through LoadAssetAsync is automatically released too.¹⁸

A zero reference count does not guarantee an immediate memory drop

An asset whose reference count reaches zero may remain in memory while another asset in the same AssetBundle is still used. Inspect asset and Bundle dependencies, not only individual counts.¹²

Packing persistent assets and large screen-specific assets together makes their lifetimes harder to separate. Once acquisitions and releases balance, consider grouping Bundle contents by lifetime.

6. Unloading a scene is not the same as unloading unused assets

`UnloadSceneAsync` does not unload every asset

SceneManager.UnloadSceneAsync destroys the GameObjects belonging to the scene and removes it from SceneManager. The API explicitly states that assets are not unloaded by this operation alone.¹⁹

For ordinary scene management, consider waiting for scene unloading, removing unnecessary references, then waiting for Resources.UnloadUnusedAssets() at a suitable loading-screen boundary.

// Excerpt from a coroutine.
// sceneToUnload is a loaded Scene managed by ordinary SceneManager APIs.
// Run this outside the scene being unloaded, with another scene kept loaded.
var unload = UnityEngine.SceneManagement.SceneManager
    .UnloadSceneAsync(sceneToUnload);

if (unload != null)
{
    yield return unload;
}

// By this point, owners must have cleared unnecessary caches and references.
yield return Resources.UnloadUnusedAssets();

For Addressables-loaded scenes, use Addressables' scene-unloading API and handle management instead. This snippet is not a replacement for that cleanup.¹⁸

`UnloadUnusedAssets` is not a universal “free everything” button

Resources.UnloadUnusedAssets examines references through the GameObject hierarchy, script components, and static variables to identify unused assets. A long-lived cache may keep an otherwise unnecessary asset referenced.²⁰

The script execution stack is not examined. Do not equate this with C# GC reachability and assume a local variable protects the asset. Keep required assets in references Unity tracks, such as fields on an appropriate owner; preserve the corresponding Addressables acquisition too.²⁰

Do not make this a per-frame cleanup operation. Measure its necessity and cost at suitable transitions. Following it with GC.Collect() still does not reclaim every category of memory.

Direct asset and AssetBundle unloading also requires ownership

Resources.UnloadAsset targets assets stored on disk and invalidates the specified asset. Ensure no other user still needs it. It is not a general cleanup API for arbitrary runtime-created objects.²¹

For manually managed AssetBundles, Unload(false) leaves loaded assets alive; Unload(true) destroys them and can break active users. Unloading with false and reloading can also produce duplicate assets. Do not manually unload Bundles owned by Addressables.²²

7. Manage `NativeArray` ownership alongside its final Job dependency

Respect the allocator's lifetime

Using an unmanaged allocation from C# does not make GC responsible for it. Collections allocators have different lifetime requirements.²³

Allocator	Lifetime and constraints
`Temp`	Use within the allocating thread and scope. Main-thread allocations are reclaimed at the end of the frame; Job-local allocations at the end of that Job. Do not pass main-thread Temp allocations into Jobs.
`TempJob`	Dispose within four frames of allocation. The deadline is not a promise of automatic, safe cleanup.
`Persistent`	Retain as long as needed, then dispose explicitly.

Avoid keeping Temp allocations across network waits or await. A short-lived allocation must not depend on an unpredictable delay.

Example: dispose only after the Job completes

Save this as NativeJobOwner.cs and attach it to a GameObject. It owns an array while enabled and waits for the array's Job before disposing on disable.

using Unity.Collections;
using Unity.Jobs;
using UnityEngine;

public sealed class NativeJobOwner : MonoBehaviour
{
    private NativeArray<int> _values;
    private JobHandle _lastUse;

    private struct FillJob : IJobParallelFor
    {
        public NativeArray<int> Values;

        public void Execute(int index)
        {
            Values[index] = index * 2;
        }
    }

    private void OnEnable()
    {
        _values = new NativeArray<int>(256, Allocator.Persistent);

        try
        {
            _lastUse = new FillJob { Values = _values }
                .Schedule(_values.Length, 64);
        }
        catch
        {
            ReleaseOwnedData();
            throw;
        }
    }

    private void ReleaseOwnedData()
    {
        if (!_values.IsCreated)
        {
            return;
        }

        // Wait for the last Job using the array before disposing it.
        _lastUse.Complete();
        _values.Dispose();
        _values = default;
        _lastUse = default;
    }

    private void OnDisable() => ReleaseOwnedData();
    private void OnDestroy() => ReleaseOwnedData();
}

Complete() blocks the caller when necessary. This example prioritizes safe cleanup. When several Jobs use the allocation, combine their dependencies so _lastUse really represents every outstanding user.²⁴

To defer waiting, Dispose(JobHandle) can schedule a disposal Job. After scheduling disposal, do not pass the array to new work, and track the returned handle. Complete the disposal Job at the appropriate shutdown or synchronization boundary.²⁵

// values is an owned NativeArray; lastUse includes all Jobs that use it.
JobHandle disposal = values.Dispose(lastUse);
values = default;

// Do not use values or any aliases after scheduling disposal.
// To avoid waiting here, retain disposal in the owner and Complete it later.
disposal.Complete();

Copying the struct does not duplicate the allocation

Here, a and b do not own separate array storage:

var a = new NativeArray<int>(16, Allocator.Persistent);
var b = a;

a.Dispose();

// Invalid: b.Dispose();  This tries to dispose the same allocation through a copy.
// Invalid: Debug.Log(b[0]);  This tries to access memory already disposed.
b = default;

Disposal updates IsCreated on the struct being disposed, not every copy. Another copy may still report true. An IsCreated check does not make disposal through arbitrary copies safe.²³

Similarly, Texture2D.GetRawTextureData<T>() returns a direct NativeArray view of the Texture's data. Do not dispose it as an owned allocation, and respect invalidation caused by modifying or destroying the Texture. The non-generic GetRawTextureData() overload instead returns a byte[] copy; the shared name does not imply shared ownership rules.²⁶

8. GPU resources need more than dropping C# references

RenderTexture `Release` and `Destroy` have different roles

RenderTexture.Release() frees hardware resources but does not destroy the RenderTexture object. Using it again can recreate those GPU resources.²⁷

For a RenderTexture you created with new RenderTexture, final cleanup might look like this:

// Cleanup excerpt. This owner created _ownedRt with new RenderTexture.
// This example assumes the Camera is the only consumer.
if (_ownedRt != null)
{
    if (_camera != null && _camera.targetTexture == _ownedRt)
    {
        _camera.targetTexture = null;
    }

    if (RenderTexture.active == _ownedRt)
    {
        RenderTexture.active = null;
    }

    _ownedRt.Release();
    Destroy(_ownedRt);
    _ownedRt = null;
}

This explicitly releases GPU storage before destroying the object. It does not mean every final Destroy requires a preceding Release. Distinguish releasing GPU storage for later reuse from ending the object's lifetime.

Also stop use through RawImage, Materials, global Shader properties, or other consumers. Do not apply this cleanup to a RenderTexture owned by someone else.

Return `GetTemporary` resources with `ReleaseTemporary`

RenderTexture.GetTemporary borrows from Unity's internal pool. Return it with ReleaseTemporary, including on exceptions or early returns.²⁸

// Synchronous temporary-work excerpt, not a rendering pipeline RenderPass.
RenderTexture previous = RenderTexture.active;
RenderTexture temporary = RenderTexture.GetTemporary(256, 256, 0);

try
{
    RenderTexture.active = temporary;
    GL.Clear(true, true, Color.clear);
    // Perform temporary work that finishes within this scope.
}
finally
{
    RenderTexture.active = previous;
    RenderTexture.ReleaseTemporary(temporary);
}

Do not keep using a cached reference after returning it, or destroy the borrowed RenderTexture yourself. Another operation may reuse it after return.

Explicitly clean up GraphicsBuffer and ComputeBuffer

Call Dispose or the corresponding Release on buffers you created when they are no longer used. Dropping C# references is not sufficient GPU resource management.²⁹³⁰

First stop scheduling rendering or compute work that uses the buffer. Async GPU readback and other outstanding operations can extend its required lifetime beyond the screen that requested it.

URP Render Graph also distinguishes resources created inside the graph from imported external resources. Do not independently destroy graph-managed resources, or assume importing a resource transfers ownership of a custom RTHandle to the graph.³¹

Discard CPU copies only when you no longer need CPU access

Runtime-generated Textures and Meshes may retain CPU copies alongside GPU data. Once CPU reads and edits are finished, these APIs can discard that storage:³²³³

// Only after creation and editing are finished, with no further CPU reads or writes.
texture.Apply(updateMipmaps: true, makeNoLongerReadable: true);
mesh.UploadMeshData(markNoLongerReadable: true);

This does not end the Texture or Mesh's lifetime. GPU data remains available for rendering, and final object cleanup is still separate. Do not apply this when later code needs to read pixels or edit vertices.

For Textures, discarding the CPU copy also fixes the uploaded resolution: subsequent mipmap-limit changes no longer affect it. Do not apply the option indiscriminately just to reduce memory.³²

9. Events, async operations, and pools can retain resources

A long-lived event publisher can retain its subscribers

An event publisher retains subscribers through registered delegates. If the publisher survives, a forgotten subscription can keep an unnecessary subscriber reachable.³⁴

The problem is not “events always leak,” but a long-lived publisher retaining a shorter-lived subscriber. For notifications needed only while a screen is enabled, pair subscription and unsubscription as follows.

Save this as ScoreObserver.cs:

using System;
using UnityEngine;

public static class ScoreEvents
{
    public static event Action<int> Changed;

    public static void Publish(int score) => Changed?.Invoke(score);

    [RuntimeInitializeOnLoadMethod(
        RuntimeInitializeLoadType.SubsystemRegistration)]
    private static void ResetForPlayMode()
    {
        Changed = null;
    }
}

public sealed class ScoreObserver : MonoBehaviour
{
    private void OnEnable()
    {
        ScoreEvents.Changed += OnScoreChanged;
    }

    private void OnDisable()
    {
        ScoreEvents.Changed -= OnScoreChanged;
    }

    private void OnScoreChanged(int score)
    {
        Debug.Log($"Score: {score}", this);
    }
}

If notifications are needed while disabled, this lifetime is wrong: use the component's full lifetime or an explicit session instead.

Do not assume that writing a similar anonymous lambda during unsubscription removes the original registration. Use a named method or retain the registered delegate when unsubscription is required.³⁴

With Domain Reload disabled, static variables and events survive between Play Mode sessions. The reset above clears the event between sessions, but resetting a static field does not release native resources. Clean up owned buffers or load handles before discarding their references.³⁵

Cancellation and resource cleanup are separate operations

MonoBehaviour.destroyCancellationToken corresponds to destruction of that component. Retrieve and retain it before destruction, then pass it to async APIs that accept cancellation. Disabling is not destruction: a UI that merely closes also needs a screen-session lifetime.³⁶

For an owned CancellationTokenSource, Cancel() and Dispose() are separate. Dispose() does not request cancellation. Request cancellation, confirm users have finished, and dispose when it no longer races with other operations.³⁷

Work that cannot be canceled, or that completes late, still needs cleanup for unused results and handles. The Addressables example separates “do not update the screen” from “release the acquisition.”

Coroutines stop when their GameObject becomes inactive or their MonoBehaviour is destroyed, but not merely because MonoBehaviour.enabled = false. Cleanup placed after a yield is not guaranteed to run on every exit path.³⁸

Dispose owned UnityWebRequest instances on success, failure, interruption, and screen destruction. The request and resources obtained from its result, such as a Texture, can have separate lifetimes.³⁹

Pools retain objects for reuse; returning is not final cleanup

Object pools reduce repeated creation and destruction by keeping objects available. Returning an object is therefore different from finally releasing its resources.⁴⁰

On return, reset references to previous users, event subscriptions, and running operations. Whether large buffers should remain allocated depends on reuse frequency and the memory budget.

ObjectPool<T>.maxSize limits how many returned objects the pool retains, not the total number that can be checked out simultaneously. Enforce a separate checkout limit when you need a total memory cap.⁴¹

Clear() acts on pooled objects and invokes a configured actionOnDestroy. Storing GameObjects does not automatically make the pool destroy them without that callback. Checked-out objects need separate tracking and cleanup.⁴⁰

10. Verify cleanup by returning to the same state

GC Alloc and leaks measure different problems

High per-frame GC Alloc indicates allocation churn and potential GC work. Near-zero GC Alloc does not prove that previously allocated Textures, native arrays, or caches have been released.

Unity 6.3's incremental GC spreads collection work across frames to reduce long pauses. It does not collect reachable objects or fix missing Addressables releases. The Web platform does not support incremental GC.⁴²

Before adding periodic GC.Collect(), investigate retained references, unreleased handles, and native resources that lack cleanup.

Distinguish used, reserved, and OS-reported memory

Unity reserves memory for reuse. Used and reserved memory differ, and managed heap space is not guaranteed to return to the OS at a particular time.⁴³²

A process memory number that does not immediately fall is not proof of a leak. Conversely, spare capacity in reserved memory can temporarily hide a growing leak from that same metric.

Inspect unwanted object counts, sizes, reference paths, and loaded assets and handles first. Unity cannot fully track all driver and platform allocations, so combine these observations with target-platform measurements.⁴³

A repeatable measurement procedure

Use Memory Profiler snapshot comparisons taken after returning to the same screen and state.³

Stage	Procedure
Warm-up	Open and close the target screen or scene once to exercise initial loads and caches.
Snapshot A	Return to the baseline screen and wait for normal cleanup to finish.
Repeat	Perform the same open/close or scene-transition sequence, for example ten times.
Snapshot B	Return to A's state and wait for the same completion conditions.
More repetitions and C	Repeat again to distinguish a plateau from continued accumulation.
Investigate	Trace growing types and instances to owners, references, cleanup paths, and Addressables dependencies.

Ten repetitions are an example, not a universal pass threshold. Choose counts and tolerances based on usage, device budgets, and intended caching.

Do not compare snapshots with pending destruction, unloading, async loading, or disposal Jobs against snapshots where all cleanup has completed. If normal cleanup includes UnloadUnusedAssets, wait for it every time.

Keep ordinary behavior tests separate from diagnostic tests that force GC or additional unloading. Extra cleanup used only in a test does not prove the normal lifecycle releases resources correctly.

Editor snapshots include the Editor's own memory. Use them for quick investigation, but perform final checks against a Player, such as a Development Build, on the target device and scripting backend.⁴⁴

Narrow the investigation by symptom

Symptom	First places to investigate
Material/Mesh counts grow after every screen closure	Implicit `material`/`mesh` clones, ownership fields, missing destruction
GameObjects disappear but large managed arrays remain	Statics, events, persistent services, `Leaked Managed Shell`
Textures remain after Addressables releases	Unreleased handles, other assets in the same Bundle, dependencies
Native memory keeps growing	Owned native containers, disposal Job dependencies, buffer cleanup
Rendering breaks after adding cleanup	Destroyed shared assets, early final handle release, cleanup during borrowing
Memory rises and then plateaus	Intended pools, caches, or reservation—or unnecessary retention

These are starting points, not diagnoses. Identify who owns the remaining resource and why it is still retained.

Conclusion: decide ownership before choosing a cleanup API

Unity memory management cannot be reduced to “set everything to null,” “destroy everything,” or “run GC at the end.” Ask three questions:

Who acquired it, and how? Distinguish creation, loading, and borrowing; match the cleanup method.
Who still needs it? Include shared users, pooled instances, Jobs, and async work—not just the screen that created it.
Does every exit path release exactly what it owns? Cover success, failure, cancellation, disabling, and destruction.

Then verify repeated transitions back to the same state.

Preventing leaks and preventing premature cleanup both begin with explicit ownership and lifetimes.

References

These are the primary sources cited by the Japanese edition. Unity URLs generally target 6000.3; package URLs retain their documented version series. They are preserved here rather than silently updated to newer releases.

Unity 6.3 Manual, Memory in Unity introduction. ↩
Unity 6.3 Manual, Managed memory introduction. ↩
Memory Profiler 1.1, Find memory leaks. ↩
Microsoft Learn, List<T>.Clear. The cited contract concerns element references, Count, and Capacity; this does not equate Unity's runtime with .NET 10. ↩
Microsoft Learn, Using objects that implement IDisposable. ↩
Unity 6.3 Scripting API, Object.Destroy, Object.DestroyImmediate. ↩
Unity 6.3 Scripting API, Renderer.material. ↩
Unity 6.3 Scripting API, Object. ↩
Memory Profiler 1.1, Analyze managed shell objects. ↩
Unity 6.3 Scripting API, MonoBehaviour.OnDestroy. ↩
Unity 6.3 Scripting API, MeshFilter.mesh. ↩
Addressables 2.10, Managing Addressable asset memory. ↩
Addressables 2.10, Wait for asynchronous loads to complete, ResourceManager.Acquire. ↩
Addressables 2.10, Wait for asynchronous loads with coroutines. ↩
Addressables 2.10, Load assets. For an explicit explanation of reference counting, also see the official Addressables 1.18 section Instantiating objects from Addressables. Its older sample code is not reproduced as the implementation for this article. ↩
Addressables 2.10 API, Addressables.InstantiateAsync. ↩
Addressables 2.10 API, Addressables.ReleaseInstance. ↩
Addressables 2.10, Unload Addressable assets. ↩
Unity 6.3 Scripting API, SceneManager.UnloadSceneAsync. ↩
Unity 6.3 Scripting API, Resources.UnloadUnusedAssets. ↩
Unity 6.3 Scripting API, Resources.UnloadAsset. ↩
Unity 6.3 Scripting API, AssetBundle.Unload. ↩
Collections 2.6, Allocator overview. ↩
Unity 6.3 Scripting API, JobHandle.Complete. ↩
Unity 6.3 Scripting API, NativeArray<T>.Dispose. ↩
Unity 6.3 Scripting API, Texture2D.GetRawTextureData. ↩
Unity 6.3 Scripting API, RenderTexture.Release. ↩
Unity 6.3 Scripting API, RenderTexture.GetTemporary. ↩
Unity 6.3 Scripting API, GraphicsBuffer. ↩
Unity 6.3 Scripting API, ComputeBuffer.Release. ↩
Unity 6.3 URP Manual, Create a texture in the Render Graph system, Import a texture into the Render Graph system. ↩
Unity 6.3 Scripting API, Texture2D.Apply. ↩
Unity 6.3 Scripting API, Mesh.UploadMeshData. ↩
Microsoft Learn, How to subscribe to and unsubscribe from events. ↩
Unity 6.3 Manual, Domain reloading. ↩
Unity 6.3 Scripting API, MonoBehaviour.destroyCancellationToken. ↩
Microsoft Learn, CancellationTokenSource.Dispose. ↩
Unity 6.3 Scripting API, MonoBehaviour.StopCoroutine. ↩
Unity 6.3 Scripting API, UnityWebRequest.Dispose. ↩
Unity 6.3 Scripting API, ObjectPool<T>. ↩
Unity 6.3 Scripting API, ObjectPool<T> constructor. ↩
Unity 6.3 Manual, Garbage collection modes. ↩
Unity 6.3 Manual, Memory Profiler module reference. ↩
Memory Profiler 1.1, Capture and import snapshots. ↩

UE5 Shader Optimization: Materials, Custom HLSL, and Global Shaders with RDG

GameDevToolLab — Wed, 30 Sep 2026 06:24:27 +0000

When a material graph grows in Unreal Engine 5, it is tempting to ask: would writing HLSL directly make it faster? Would implementing the shader in C++ make optimization easier?

Moving a shader into code is not, by itself, an optimization. Material Editor nodes already become HLSL. Epic also warns that a Custom expression can prevent Unreal's material-level constant folding and produce more instructions than an equivalent graph built with standard nodes. Material concepts · Custom expressions

This guide separates five questions that are often mixed together: GPU execution time, shader permutation costs, first-use pipeline hitches, choosing an authoring layer, and adding a compute shader with C++ and HLSL.

The engine baseline is Unreal Engine 5.8.2, as in the Japanese edition dated August 31, 2026. Version-sensitive references were rechecked for this English edition on September 30, 2026. This is a documentation baseline, not a compilation or execution result for UE 5.8.2. Epic's 5.8.2 hotfix announcement is dated August 25, 2026. Release announcement

The examples primarily target Windows, DirectX 12, and Shader Model 6. Mobile, consoles, and VR have different compiler, precision, bandwidth, and GPU constraints. Make the final decision on the actual target hardware.

Substrate: New projects use Substrate by default from UE 5.7 onward, but Epic's UE 5.8 documentation still labels it Beta. Existing projects upgraded to UE 5.7 or later retain the non-Substrate path unless they explicitly opt in. The principles below apply to both paths; the code does not depend on a particular Substrate Slab. Substrate status · Substrate overview

Start with the simplest layer that meets your needs

Do not begin by moving everything to HLSL or C++. Choose the layer that solves the actual problem.

Goal	Start with	When to move lower
Ordinary surface shading	Material nodes and Material Functions	An operation is unavailable, or repeated logic is becoming difficult to maintain
Many parameter variations	Material Instances	Split the parent when static-switch combinations become unmanageable
A small custom formula	Custom Material Expression	Built-in nodes are insufficient, and generated HLSL plus measurements justify it
Full-screen color processing	Post Process Material	You need arbitrary UAVs or buffers, custom pass ordering, or compute dispatch
A compute shader	Global Shader and RDG	You need reads, writes, or dispatch control outside the material model
Drawing meshes in a custom pass	Mesh Material Shader or a custom mesh pass	Renderer integration is necessary and its maintenance cost is acceptable
Something is simply “slow”	Profiling	Change the implementation after identifying the bottleneck and affected pass

Material nodes are not a simplified substitute for “real” shaders. Expressions visually represent shader operations, and the graph is translated into HLSL. In the Material Editor, Window > Shader Code > HLSL Code opens a read-only view of the generated source. It is not the final GPU-native instruction stream. Material concepts · Material Editor UI

The useful comparison is therefore not nodes versus code. It is the shader compiled for the target platform, multiplied by the pixels, layers, and passes that execute it. Use generated HLSL to investigate the implementation, then use target-platform statistics and GPU timings to evaluate performance.

Separate three kinds of shader cost

1. Runtime GPU work

Instruction count is only one part of GPU cost. Screen coverage, overdraw, texture access and cache behavior, arithmetic, special functions, loops, branch coherence, render-target traffic, and vertex work all matter. A material can also participate in several passes: depth, shadows, base pass, velocity, and representations used by Lumen. Rendering optimization · Shader development

A hypothetical 100-instruction shader applied once to a small prop is not equivalent to the same shader running across several full-screen translucent layers. The arithmetic is similar; the amount of work is not.

Before changing a formula, ask where it runs, how often it runs, and what it reads and writes.

2. Compilation and shader permutations

An Unreal material does not correspond to one shader binary. Rendering passes, vertex factories, feature levels, material quality, static parameters, and target platforms produce different variants. Shader development

A Static Switch can remove its unused branch at compile time, which is useful for runtime performance. The trade-off is a separate compiled variation for each required static-parameter combination. Ten independent Boolean switches allow up to 2^10 = 1,024 combinations before other permutation dimensions are considered. This is a theoretical combination count, not a claim that every project compiles all 1,024. Material parameters

A parent material that includes every possible feature can increase cooking time, Derived Data Cache (DDC) work, continuous-integration costs, shader storage, and loading overhead. Audit the combinations actually used rather than counting only parent assets. Material Analyzer

3. First-use PSO hitches

Having shader binaries available does not mean every Pipeline State Object (PSO) is ready. Creating a required pipeline on first use can still cause driver-side work and a visible hitch. Removing a few pixel-shader instructions does not directly solve that problem. PSO precaching

UE's PSO Precaching system collects candidate pipelines and compiles them asynchronously. Epic's UE 5.8 documentation includes eligible Global Compute Shader permutations in precaching. You still need to verify platform support, wait for important outstanding requests during loading, and watch for missed or late PSOs during gameplay. PSO precaching

These are different optimization objectives. Decide whether the goal is less GPU time per frame, less compilation and storage, or fewer first-use hitches before choosing a technique.

Profile outside the Material Editor

1. Establish whether the GPU is the bottleneck

Start with stat unit and compare Game, Draw, GPU, and Frame times. When another stage dominates, reducing material instructions may not improve the overall frame time. The largest reported GPU value is a clue rather than a complete diagnosis: timing can include waits. Rendering optimization

Use stat gpu and ProfileGPU to identify the expensive passes, such as Base Pass, Translucency, Post Processing, Lumen, or shadows. Timing Insights in Unreal Insights can show CPU and GPU work on a shared timeline. Rendering optimization · Timing Insights

Keep the comparison conditions fixed: resolution and screen percentage; dynamic resolution; VSync and frame limits; camera, visible objects, lights, and effects; scalability and material quality; RHI and shader model; and shader/PSO warm-up state.

Save a reproducible scene and camera. Editor-only work and additional viewports can distort a comparison, so repeat the final test in an appropriate Development or Test build on the target platform, with the required profiling tools available.

2. Read Material Stats and Platform Stats

Material Stats provide a quick starting point for instruction-count comparisons. Platform Stats show results for the selected rendering targets. Compare the same rendering API and shader model. An SM5 count and an SM6 count are not automatically comparable because the compilation path and reported metrics can differ. Material Editor UI

Treat these statistics as diagnostic evidence, not as a stopwatch. They do not capture screen coverage, all overdraw, memory-bandwidth pressure, or the effect on the rest of the frame.

3. Use Shader Complexity and Quad Overdraw as clues

Shader Complexity helps locate expensive regions, particularly translucent effects. Epic explicitly notes that instruction counts do not assign equivalent execution cost to every operation: texture fetches and simple arithmetic can have very different costs. Loops that are not unrolled can also be poorly represented by the visualization. Viewport modes

A useful sequence is to find candidates with Shader Complexity, inspect overlap with Quad Overdraw, measure the affected pass with ProfileGPU, and A/B test the material under identical conditions. Use a GPU debugger such as RenderDoc or PIX when you need to inspect individual events or shader behavior more closely. Viewport modes · Rendering optimization · Shader debugging

A red region is a reason to investigate, not an instruction to rewrite the material in HLSL.

Material optimizations worth investigating first

Check blend mode, screen coverage, and overdraw

Opaque rendering can often use depth rejection effectively. Translucency processes overlapping layers, and masked materials still need to evaluate their cutout. Several layers of foliage, fences, or large particle cards can therefore become expensive even when each individual material looks modest. Rendering optimization · Viewport modes

Before changing the math, ask whether the effect needs translucency, whether its polygon covers large transparent areas, whether too many particles overlap, whether distant LODs can drop layers, and whether several full-screen effects could be reduced or combined.

Reducing the number of shaded pixels or overlapping layers can matter more than removing a few arithmetic instructions. Measure both options instead of assuming that the shorter formula wins.

Evaluate texture access and arithmetic separately

Neither “replace textures with math” nor “bake all math into textures” is a universal rule.

Complex, static, multi-octave noise evaluated per pixel is a candidate for baking. A simple gradient may not justify adding a large texture, streaming requirements, and another sample. Consider sample count, mip selection, resolution, compression, locality, memory traffic, and whether the target workload is limited by arithmetic or bandwidth. Rendering optimization

Channel packing can reduce separate texture accesses when channels are used together, but the grouping matters. Do not assume that Base Color and scalar masks such as roughness, metallic, and ambient occlusion can share arbitrary compression and color-space settings. Preserve the intended data interpretation, and check whether unrelated channels are being fetched unnecessarily. Texture masks

The decision belongs to the measured workload, not to the appearance of the material graph.

Move suitable UV calculations to the vertex stage

Customized UVs let you evaluate UV operations in the vertex shader and interpolate the results for the pixel shader. This can help when there are substantially fewer vertices than shaded pixels. Customized UVs

An affine operation is a typical candidate:

UV * Tiling + Offset

Nonlinear operations such as sin, cos, length, or squaring generally do not survive interpolation unchanged. Moving them to the vertex stage can make the result depend on mesh density. The cost of extra interpolants also matters. Customized UVs

Do not assume that the vertex stage is always cheaper, particularly for dense geometry or a Nanite rendering path. Compare the actual target path, both visually and in GPU time.

Material Instances do not automatically remove instructions

Changing Scalar, Vector, or Texture Parameters through a Material Instance or Material Instance Dynamic (MID) normally retains the parent's shader logic. The advantage is reuse and controlled variation, not automatic removal of GPU work. Static Switch Parameters are different: they select compiled variations that can omit unused branches. Material instances · Material parameters

As a design rule, use runtime parameters for colors, strengths, thresholds, and animation speeds. Consider a static switch when removing an entire feature branch is valuable. Separate genuinely different material families instead of building one universal parent, and inspect real static-override combinations with Material Analyzer. Material Analyzer

Also review project-level rendering features. Settings for features such as stationary skylights, low-quality lightmaps, whole-scene point-light shadows, or path tracing can affect which material shaders must be compiled. Disable support only after establishing that the project does not need it. Fewer permutations primarily reduce compilation and storage; they do not guarantee a cheaper visible pixel shader. Rendering settings

Use Material Functions to improve maintainability

Material Functions organize and reuse graph logic. They are not a promise that the GPU executes a shared computation once for every caller. Evaluate the resulting compiled material. Material Functions

A practical boundary is to separate responsibilities with Material Functions, then introduce Custom HLSL only where standard nodes are insufficient or the equivalent graph becomes difficult to maintain. This keeps more of the workflow accessible to artists and preserves graph previews and material integration.

Inspect Substrate statistics and the GBuffer format

Substrate represents materials using Slabs and can simplify their composition to fit project and platform budgets. Use the Material Editor's Substrate statistics to inspect topology, enabled features, and simplification. Substrate overview

Blendable GBuffer is the default for most new Substrate-enabled projects and prioritizes predictable performance. Some templates, including Automotive and Architectural, choose Adaptive GBuffer instead. Adaptive supports richer materials but increases cost and cooking work. Compare the same GBuffer format and closure configuration, not merely whether Substrate is enabled. Substrate overview

What “writing a shader in code” means in UE5

1. Custom Material Expression

A Custom expression replaces part of a material graph with HLSL. Unreal still handles material integration, parameters, lighting, and the relevant rendering passes. It is usually the smallest step beyond ordinary graph authoring. Custom expressions

Typical reasons to use it include a missing formula, a readable fixed-count loop, bit operations, or a calculation that becomes unwieldy as nodes.

Keep the boundaries clear. Unreal cannot perform all of its material-level constant folding inside a Custom expression. Inputs are function-local because the code is wrapped in a generated function. Valid HLSL can still encounter backend-specific limitations. None of this means that the downstream shader compiler performs no optimization. Custom expressions

World-space calculations also need care. UE5's Large World Coordinates (LWC) rendering types and translated world space exist to manage precision. Blindly reducing large coordinates to float3 can introduce errors far from the origin. LWC rendering

A Custom expression remains part of a material. It does not give you arbitrary render-pass scheduling or unrestricted UAV access. Choose it for a concrete functionality, readability, or reuse benefit—not because code looks inherently faster.

2. `.ush`, `.usf`, and Global Shaders

For a Global Shader, you place HLSL in shader files and register a shader type from C++. Global Shaders are not tied to a particular material or mesh and are used for tasks such as full-screen processing, compute work, and clears. Adding Global Shaders · Shader development

The division of responsibility is important:

Layer	Responsibility
HLSL	Vertex, pixel, or compute operations executed by the GPU
C++	Shader registration, compile conditions, parameters, resources, passes, and dispatch
Render Dependency Graph (RDG)	Resource dependencies and lifetimes, transitions, scheduling, and unused-pass culling

C++ configures the GPU work; it does not become the per-pixel GPU program. RDG manages work whose resource usage is declared to the graph. Render Dependency Graph

3. Mesh Material Shaders and custom mesh passes

Rendering meshes in a custom pass while using their materials, consuming vertex-factory data, or integrating closely with the base pass requires more than a stand-alone Global Shader. This territory includes Mesh Material Shaders, mesh pass processors, renderer integration, and suitable extension points such as Scene View Extensions. Shader development · Mesh drawing pipeline

The integration has a larger maintenance cost across engine upgrades. For an ordinary screen effect, first consider a Post Process Material. For independent compute work, first consider a Global Shader with RDG.

Custom HLSL example: a rounded-rectangle mask

This example creates a rounded rectangle centered at UV = (0.5, 0.5). All dimensions use ordinary UV units, not a coordinate system scaled to -1..1.

Configure the Custom expression inputs as follows:

Input	Type	Meaning	Example
`UV`	`float2`	Coordinates in the `0..1` UV domain	TextureCoordinate
`HalfSize`	`float2`	Half-width and half-height from the center	`(0.40, 0.25)`
`Radius`	`float`	Corner radius, in the same UV units	`0.08`
`Feather`	`float`	Minimum edge-transition width, in UV units	`0.002`

Set Output Type to CMOT Float 1. Custom expression setup

float2 safeHalfSize = clamp(
    abs(HalfSize),
    float2(1e-5, 1e-5),
    float2(0.5, 0.5));

float safeRadius = clamp(
    Radius,
    0.0,
    min(safeHalfSize.x, safeHalfSize.y));

float2 p = abs(UV - 0.5);
float2 q = p - safeHalfSize + safeRadius;

float distanceToEdge =
    length(max(q, 0.0)) +
    min(max(q.x, q.y), 0.0) -
    safeRadius;

float aa = max(
    max(abs(Feather), 1e-5),
    fwidth(distanceToEdge));

return saturate(0.5 - distanceToEdge / aa);

With HalfSize = (0.40, 0.25), the rectangle has a width of 0.80 and a height of 0.50. Those dimensions describe the zero-distance contour, where the returned mask is 0.5; the feathered transition extends to either side of that contour.

The accepted inputs are finite numbers. Each half-extent is converted to its absolute value and clamped to 1e-5..0.5. The radius is clamped to 0..min(safeHalfSize.x, safeHalfSize.y), so a negative radius becomes zero and an oversized radius cannot exceed the smaller sanitized half-extent. A negative Feather uses its magnitude, with a numerical floor and screen-space derivatives determining the final transition width.

Use this example in the pixel-shader path because it uses fwidth. Connect the result to an appropriate blend factor or Opacity Mask. A masked material still applies its clipping threshold; producing a smooth scalar does not by itself make masked rendering behave like alpha blending. Apply aspect correction when a circular corner in UV space would otherwise appear stretched on screen.

This example is not a speed claim. An equivalent graph can be built from standard nodes. Compare the graph version and Custom HLSL version using the same Platform Stats target, generated HLSL, and GPU profiling conditions. The Custom version may be useful because it is easier to maintain, even when it is not faster.

For shared code, Custom expressions expose Include File Paths and Additional Defines. Mapping a plugin shader directory to a virtual path lets you keep reusable functions in a .ush file. Avoid putting unrelated code into one universal include: changes to a widely included file can trigger a much broader recompile. Custom expressions · Shader development

Add a Global Compute Shader through a plugin

The following example shows the minimal pass implementation for writing a UV gradient into an RDG texture. In a game, add it from a render-thread integration point that already receives an FRDGBuilder, such as an appropriate Scene View Extension callback or another renderer extension. It is not a game-thread RHI example. Adding Global Shaders · Render Dependency Graph

Validation and integration limits: These snippets illustrate shader registration, RDG resources, and dispatch. They do not form a complete screen effect. You must supply the rendering callback and a downstream consumer that composites the texture or transfers the result to an appropriate external render target. The C++ and HLSL have not been compiled or executed on UE 5.8.2 in this authoring environment. Compilation on your engine branch and execution on each target RHI remain required checks.

Folder layout

Plugins/ShaderLab/
├─ ShaderLab.uplugin
├─ Shaders/
│  └─ Private/
│     └─ WriteGradient.usf
└─ Source/
   └─ ShaderLab/
      ├─ ShaderLab.Build.cs
      ├─ Public/
      │  └─ WriteGradientShader.h
      └─ Private/
         ├─ ShaderLabModule.cpp
         └─ WriteGradientShader.cpp

Load the module at PostConfigInit so shader registration and the virtual shader-path mapping are available early enough. Adding Global Shaders

{
  "FileVersion": 3,
  "Version": 1,
  "VersionName": "1.0.0",
  "FriendlyName": "ShaderLab",
  "CanContainContent": false,
  "Modules": [
    {
      "Name": "ShaderLab",
      "Type": "Runtime",
      "LoadingPhase": "PostConfigInit"
    }
  ]
}

Build.cs

The public pass header exposes RDG types, so RenderCore is a public dependency. The other dependencies below support the plugin implementation. Public include visibility and exported binary symbols are separate concerns; both will matter when another module calls the pass function. Unreal modules · Module API specifiers

using UnrealBuildTool;

public class ShaderLab : ModuleRules
{
    public ShaderLab(ReadOnlyTargetRules Target) : base(Target)
    {
        PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

        PublicDependencyModuleNames.AddRange(
            new[]
            {
                "Core",
                "RenderCore"
            });

        PrivateDependencyModuleNames.AddRange(
            new[]
            {
                "CoreUObject",
                "Engine",
                "Projects",
                "Renderer",
                "RHI"
            });
    }
}

Map the shader directory

// ShaderLabModule.cpp

#include "Interfaces/IPluginManager.h"
#include "Misc/Paths.h"
#include "Modules/ModuleManager.h"
#include "ShaderCore.h"

class FShaderLabModule final : public IModuleInterface
{
public:
    virtual void StartupModule() override
    {
        const TSharedPtr<IPlugin> Plugin =
            IPluginManager::Get().FindPlugin(TEXT("ShaderLab"));

        check(Plugin.IsValid());

        const FString ShaderDirectory =
            FPaths::Combine(Plugin->GetBaseDir(), TEXT("Shaders"));

        AddShaderSourceDirectoryMapping(
            TEXT("/ShaderLab"),
            ShaderDirectory);
    }

    virtual void ShutdownModule() override
    {
    }
};

IMPLEMENT_MODULE(FShaderLabModule, ShaderLab)

The physical directory Plugins/ShaderLab/Shaders can now be addressed through the virtual shader path /ShaderLab. The registration below uses that virtual path, not a machine-specific filesystem path. Shaders in plugins

Write the HLSL

// Shaders/Private/WriteGradient.usf

RWTexture2D<float4> OutputTexture;
int2 OutputSize;

[numthreads(8, 8, 1)]
void MainCS(uint3 DispatchThreadId : SV_DispatchThreadID)
{
    if (DispatchThreadId.x >= (uint)OutputSize.x ||
        DispatchThreadId.y >= (uint)OutputSize.y)
    {
        return;
    }

    float2 uv =
        (float2(DispatchThreadId.xy) + 0.5) /
        float2(OutputSize);

    OutputTexture[DispatchThreadId.xy] =
        float4(uv, 0.0, 1.0);
}

Each thread writes one texel. The half-texel offset evaluates the gradient at texel centers. The bounds check protects the final thread groups when the texture dimensions are not multiples of eight. The caller must supply a texture with positive dimensions.

Register the Global Shader and add the RDG pass

A public function called from another module needs the export macro SHADERLAB_API. Putting a header in Public makes it available for inclusion; that alone does not export the function across a modular-build DLL boundary. Module API specifiers

// Public/WriteGradientShader.h

#pragma once

#include "RenderGraphFwd.h"

SHADERLAB_API void AddWriteGradientPass(
    FRDGBuilder& GraphBuilder,
    FRDGTextureRef OutputTexture);

When a consumer calls the function only from its .cpp implementation, add the dependency in that consumer module's Build.cs:

PrivateDependencyModuleNames.Add("ShaderLab");

Use PublicDependencyModuleNames instead when the consumer's public interface itself requires the ShaderLab header. Likewise, expose the appropriate owning-module dependencies for any engine types used by that public interface. Unreal modules

The implementation registers the shader and schedules its work:

// WriteGradientShader.cpp

#include "WriteGradientShader.h"

#include "DataDrivenShaderPlatformInfo.h"
#include "GlobalShader.h"
#include "RenderGraphBuilder.h"
#include "RenderGraphUtils.h"
#include "ShaderParameterStruct.h"

class FWriteGradientCS final : public FGlobalShader
{
public:
    DECLARE_GLOBAL_SHADER(FWriteGradientCS);
    SHADER_USE_PARAMETER_STRUCT(FWriteGradientCS, FGlobalShader);

    BEGIN_SHADER_PARAMETER_STRUCT(FParameters, )
        SHADER_PARAMETER(FIntPoint, OutputSize)
        SHADER_PARAMETER_RDG_TEXTURE_UAV(
            RWTexture2D<float4>,
            OutputTexture)
    END_SHADER_PARAMETER_STRUCT()

    static bool ShouldCompilePermutation(
        const FGlobalShaderPermutationParameters& Parameters)
    {
        return IsFeatureLevelSupported(
            Parameters.Platform,
            ERHIFeatureLevel::SM5);
    }
};

IMPLEMENT_GLOBAL_SHADER(
    FWriteGradientCS,
    "/ShaderLab/Private/WriteGradient.usf",
    "MainCS",
    SF_Compute);

void AddWriteGradientPass(
    FRDGBuilder& GraphBuilder,
    FRDGTextureRef OutputTexture)
{
    check(OutputTexture);

    const FIntPoint OutputSize = OutputTexture->Desc.Extent;

    FWriteGradientCS::FParameters* Parameters =
        GraphBuilder.AllocParameters<
            FWriteGradientCS::FParameters>();

    Parameters->OutputSize = OutputSize;
    Parameters->OutputTexture =
        GraphBuilder.CreateUAV(
            FRDGTextureUAVDesc(OutputTexture));

    TShaderMapRef<FWriteGradientCS> ComputeShader(
        GetGlobalShaderMap(GMaxRHIFeatureLevel));

    FComputeShaderUtils::AddPass(
        GraphBuilder,
        RDG_EVENT_NAME("ShaderLab.WriteGradient"),
        ComputeShader,
        Parameters,
        FComputeShaderUtils::GetGroupCount(
            OutputSize,
            FIntPoint(8, 8)));
}

The SM5 feature-level check is a compile filter, not a claim that every admitted platform has been tested. The intended DX12/SM6 target is not made SM5-only by this minimum-feature-level check. Keep the shader map and compile policy consistent with the rendering path used by your integration. Shader development

The output texture must be created by, or registered with, the same FRDGBuilder and support the required UAV usage. This example expects a non-multisampled 2D texture at mip zero, with a format compatible with its float4 UAV. It does not handle texture arrays or arbitrary mip views. The following caller-side fragment assumes an existing graph and a positive FIntPoint OutputSize; it is not a complete rendering callback:

const FRDGTextureDesc OutputDesc =
    FRDGTextureDesc::Create2D(
        OutputSize,
        PF_FloatRGBA,
        FClearValueBinding::Black,
        TexCreate_ShaderResource | TexCreate_UAV);

FRDGTextureRef OutputTexture =
    GraphBuilder.CreateTexture(
        OutputDesc,
        TEXT("ShaderLab.GradientOutput"));

AddWriteGradientPass(GraphBuilder, OutputTexture);

Within the graph, another pass can read the result as an SRV and composite it. Alternatively, use the appropriate RDG extraction or external-resource path, such as QueueTextureExtraction, to retain the underlying resource after graph execution. Do not retain the FRDGTextureRef itself beyond its graph lifetime. A pass with no live output consumer may be culled; allocating a texture is not the same as displaying it. Render Dependency Graph

Splitting the caller into another class or module does not change those lifetime rules. Keep the builder and RDG handles within the graph's lifetime. Do not capture game-thread UObject state or raw pointers without a valid render-thread ownership and synchronization design. Render Dependency Graph

What to optimize in this example

The five-argument FComputeShaderUtils::AddPass above schedules an ordinary compute pass on the graphics pipe. Writing a compute shader does not automatically run it on the Async Compute pipe or overlap it with graphics work. The pass-flag overload is separate, and ERDGPassFlags::Compute and ERDGPassFlags::AsyncCompute describe different execution pipes. AddPass API · Pass flags

For this pass, investigate group size, texture format, UAV traffic, unnecessary dispatch area, graph dependencies and lifetimes, permitted shader permutations, and first-use PSO behavior. An 8 x 8 group is a starting point, not a universal optimum. Register use, shared memory, wave size, and access patterns can change the result. Render Dependency Graph · Shader development

Only when testing Async Compute as an optional A/B variant, replace the shown call with the overload that accepts pass flags and specify ERDGPassFlags::AsyncCompute. That is a candidate to measure, not a default improvement. AddPass API

An async flag does not guarantee useful overlap. Resource dependencies, queue synchronization, RHI and hardware support, and competition for compute or memory bandwidth can eliminate the benefit or make the frame slower. Inspect the actual schedule and overlap with RDG Insights and GPU profiling tools. Render Dependency Graph

Decide between a Custom expression and a Global Shader

Stay with a Custom expression when the material model fits

A Custom expression is a good fit when you want to compute material inputs such as Base Color, Normal, Roughness, or Opacity Mask; keep Unreal's normal material and mesh-pass integration; express a formula more clearly; and continue controlling values through Material Instances. Custom expressions · Material parameters

You do not need a custom rendering pass merely because a material contains HLSL.

Use a Global Shader when you need independent GPU work

Move to a Global Shader when the operation needs writes to resources such as RWTexture2D or RWBuffer, arbitrary compute dispatch dimensions, a material-independent full-screen operation, or explicit RDG dependencies between intermediate textures and buffers. Adding Global Shaders · Render Dependency Graph

The benefit is control over GPU work and resources, not an automatic reduction in execution time.

Extend the renderer when the mesh pipeline itself must change

Custom mesh drawing, vertex-factory-specific data, deep base-pass or shadow integration, Nanite integration, new shading models, and new GBuffer representations belong to a more tightly coupled layer. Some changes require engine modifications rather than a self-contained plugin. Mesh drawing pipeline · Shader development

Budget for engine-upgrade maintenance, validation on every target RHI, and pipeline-cache coverage. Do not choose this layer merely to make an ordinary material graph look shorter.

Design permutations and PSOs deliberately

The same permutation discipline applies to code-authored shaders and materials.

Use ShouldCompilePermutation to exclude unsupported or unnecessary platforms. When using a permutation domain, avoid generating combinations that runtime code cannot reach. A runtime parameter can be preferable to another compile-time define when the variation does not justify a separate shader. Conversely, a small, controlled set of permutations may be worthwhile when it removes substantial runtime work. Shader development

On the material side, Material Analyzer groups instances with matching static overrides and helps identify candidates for a shared intermediate parent. Review the interaction of project features, Static Switches, material quality, and feature levels rather than treating each setting in isolation. Material Analyzer · Rendering settings

For PSOs, verify distinct milestones: the shader was cooked; the pipeline is covered by precaching; important requests finish before gameplay needs them; actual play does not reveal missed or late pipelines; and any fallback material or delayed draw behavior is acceptable. PSO precaching

A smooth editor session is not proof of a smooth first launch. Test the packaged target with an appropriately clean cache state. Shader compilation and DDC behavior, pipeline precaching, and the graphics driver's cache are related but are not the same cache or the same test.

Recompile and debug during development

For work on .usf and .ush files, enable shader development diagnostics in ConsoleVariables.ini:

r.ShaderDevelopmentMode=1

This enables shader-development logging and support for retrying compilation after errors. After saving, recompileshaders changed or Ctrl+Shift+. recompiles changed shaders. A change to a widely included file can invalidate a large set of dependent shaders, so keep shared includes focused. Shader development

For GPU debugging, use the platform-appropriate symbol settings, including r.Shaders.Symbols and r.Shaders.WriteSymbols where supported by your workflow. Symbol generation affects cooking time and storage. Enable it deliberately for the platforms and investigations that need it rather than assuming it is free. Shader debugging workflows

A practical optimization checklist

Before changing anything

[ ] Fix the target hardware, RHI, shader model, and resolution.
[ ] Express the frame-rate target as a time budget in milliseconds.
[ ] Use stat unit and GPU profiling to establish the bottleneck.
[ ] Identify the affected pass with ProfileGPU.
[ ] Save the comparison scene, camera, quality settings, and warm-up conditions.

When changing a material

[ ] Check blend mode, screen coverage, and overdraw before editing the formula.
[ ] Measure GPU time; do not rely on Shader Complexity alone.
[ ] Evaluate texture samples, arithmetic, and affected pixel count separately.
[ ] Test whether suitable UV calculations can move to Customized UVs without changing the image.
[ ] Estimate permutation growth before adding a Static Switch.
[ ] Use Material Instances and Material Functions for controlled reuse and maintainability.
[ ] Compare Custom HLSL against equivalent standard nodes on the same target.
[ ] For Substrate, compare statistics, simplification, and GBuffer format.

When adding a Global Shader

[ ] Explain why a Material or Post Process Material cannot meet the requirement.
[ ] Load shader registration and virtual-path mapping early enough.
[ ] Match C++ parameter names and types with the HLSL declarations.
[ ] Export cross-module functions or types with the correct MODULENAME_API macro.
[ ] Declare consumer module dependencies at the correct public/private boundary.
[ ] Keep RDG textures and buffers within the lifetime of their graph.
[ ] Match resource usage and format to the required UAV, SRV, or render-target access.
[ ] Check dispatch bounds and use positive resource dimensions.
[ ] Restrict shader compilation with ShouldCompilePermutation.
[ ] Name GPU events so the pass can be identified in profiling tools.
[ ] Distinguish ordinary compute from Async Compute and measure actual overlap for the async variant.
[ ] Verify PSO coverage and first use with clean caches.
[ ] Compile, inspect the output, and measure performance on every target RHI and device.

Conclusion

A useful order of investigation is:

Measure → reduce shaded area and overdraw → simplify material structure → use Custom HLSL where justified → add Global Shaders or renderer extensions when the requirements demand them.

Material graphs already become HLSL. Moving work into HLSL or C++ does not automatically make it faster. Start with screen coverage, translucency, texture access, unused features, and unnecessary static variations. Material concepts · Rendering optimization

Use Custom expressions for material-local formulas that benefit from code. Use Global Shaders and RDG for independent resources and dispatch. Use mesh-pipeline integration when the rendering architecture actually needs to change.

The right layer is not the lowest-level one. It is the simplest layer that meets the requirement, can be measured on the target platform, and remains maintainable by the team.

References

The following links point to Epic's primary documentation and release announcement. Version-dependent behavior should be checked against the engine branch used by the project.

Choosing UI Tools in Unreal Engine 5: UMG, CommonUI, Slate, Blueprint, and C++

GameDevToolLab — Fri, 25 Sep 2026 03:37:43 +0000

Designing a UI in Unreal Engine 5 is not a binary choice between Widget Blueprints and C++. The more useful starting point is to separate four responsibilities:

State ownership: Characters, Actor Components, PlayerStates, or Subsystems hold gameplay state.
Presentation: A thin adapter forwards simple values; a Presenter or Viewmodel handles more complex display transformations.
Widget ownership: A PlayerController, HUD, or ULocalPlayerSubsystem-based UI manager creates and retains screens.
Input routing: The PlayerController, CommonUI Action Router, or UI manager coordinates input, focus, and mouse capture.

This guide uses Unreal Engine 5.8 as its technical baseline. It covers UMG, CommonUI, Slate, Widget Components, and UMG Viewmodel, then connects those choices to both Blueprint-first and C++-first implementations.

The default approach is straightforward: start with UMG, keep layout and visual iteration in Widget Blueprints, and place state, ownership, and subscription contracts in Blueprint or C++ according to the project's needs. The important boundary is the responsibility—not the language.

Start with the use case and maturity level

The following table describes the UE5.8 baseline. Standard means the source documentation does not explicitly label the feature Beta or Experimental; it is not a promise that a project needs no testing.

Use case	Main option	Maturity and constraints	Adoption guidance
HUDs, menus, and dialogs	UMG	Standard	The default choice. Keep gameplay state and lifetime management outside the Widget Blueprint.
Layered menus, Back navigation, and gamepad support	UMG + CommonUI	The release notes describe Common UI itself as production-ready; the Enhanced Input how-to retains older warnings.	Distinguish the current integration path from the legacy path and test the one you use.
Many displayed fields or state shared across screens	Manual events / Presenter; MVVM when needed	UMG Viewmodel is Beta.	Do not introduce MVVM merely because a small screen has a few values. Add regression tests when adopting it.
Overhead health bars, terminals, and VR panels	Widget Component + UMG	Standard; requires world rendering and pointer design.	Measure widget count, `Draw Size`, update frequency, occlusion, and interaction.
Editor production tools	Editor Utility Widget	Beta	Move heavy asset processing into a C++ editor module.
Editor plugins and low-level UI components	Slate	Standard	C++-oriented. Do not rebuild every ordinary game screen in Slate.
Crosshairs and immediate-mode diagnostic drawing	`AHUD` Canvas	Standard	Suitable for simple drawing and debugging, not a general menu framework.
Research and diagnostic UI	UIFramework / SlateIM	Experimental	Not the default choice for a shipping product.

The maturity labels are documented in Epic's references for Editor Utility Widgets, UMG Viewmodel, UIFramework, and SlateIM. The CommonUI documentation discrepancy is discussed below with links to both sources.

When the choice is unclear, start with UMG. Add CommonUI for screen stacks and focus, a Presenter or MVVM for complex presentation, and Slate only for low-level components that are otherwise missing.

Separate the data path from the control path

A Presenter or Viewmodel produces display data. A ULocalPlayerSubsystem-based UI manager owns screens and coordinates stacks and input. These are different responsibilities, not interchangeable names for the same layer.

Data, simple:
  State owner --event--> Screen owner / thin adapter --> Widget

Data, complex:
  State owner --event--> Presenter / Viewmodel --> Widget

Control:
  PlayerController / HUD / LocalPlayer UI manager
    --create, retain, push, pop--> Widget
  CommonUI Action Router / PlayerController
    --input policy, Back, focus, mouse capture--> Widget

In the ammunition example later in this article, the PlayerController also acts as a minimal presentation adapter: it forwards values to the widget. Extract a dedicated Presenter or Viewmodel when formatting, multiple data sources, asynchronous state, shared presentation, or isolated tests make that forwarding layer more complex.

Choose an owner by lifetime and player scope

Owner	Lifetime and scope	Main responsibility and when to choose it
`APlayerController`	Represents one controlling player and generally outlives a Pawn. Behavior across map travel depends on the travel mechanism.	A few HUD widgets, the Owning Player relationship, and reconnection after Pawn changes. Appropriate while the responsibility remains small.
`AHUD`	Tied to the PlayerController/world-side lifetime; can span Pawn changes.	HUD coordination and Canvas drawing, especially when the existing architecture already uses the HUD as its entry point.
`ULocalPlayerSubsystem`-based UI manager	Shares the LocalPlayer's lifetime, outlives individual Pawns, and follows that LocalPlayer across world changes.	Layers, stacks, and input coordination. Useful for multiple screens and split-screen play.
GameInstance / GameViewport-level owner	Application-wide or scoped to a GameInstance rather than one local player.	Loading screens, global notifications, and player-independent overlays.
Actor + Widget Component	Follows the Actor/world lifetime.	Overhead indicators, in-world terminals, and VR panels.

ULocalPlayerSubsystem shares its lifetime with ULocalPlayer and exposes PlayerControllerChanged. See the ULocalPlayerSubsystem API. A persistent manager does not make a widget's references to an old world safe to retain: recreate and reconnect world-dependent widgets when the map changes.

Create player-specific UI with a valid Owning Player and add it with UUserWidget::AddToPlayerScreen. Decide who owns the screen separately from who owns the gameplay data shown on it.

Choosing among the UI features

UMG: the default for game screens

UMG is the starting point for HUDs, title screens, pause menus, inventories, shops, and conversations.

A Widget Blueprint should not become the owner of saving, networking, purchases, game progression, or a per-frame search for gameplay state. Keep that state elsewhere and pass the widget the data it needs to display.

CommonUI: layered interaction on top of UMG

CommonUI adds input routing, Activatable Widgets, styling, and input glyphs to UMG. It is useful for switching input devices, managing menu layers, handling Back, and restoring focus. See the Common UI Overview. Use Activatable Widgets for screens that participate in the interaction flow, rather than making every decorative widget activatable.

UCommonActivatableWidget can activate and deactivate, but it does not automatically activate or register as a Back handler by default. Enable Auto Activate or activate it explicitly, configure Back Handler where appropriate, and provide a Desired Focus Target. RequestRefreshFocus restores focus only when the widget is the leaf-most active node. See the Activatable Widget API and RequestRefreshFocus API.

UE5.8 CommonUI and Enhanced Input: the documentation is inconsistent

The UE5.8 release notes describe the integration of Enhanced Input with Common Input/UI, a reduction in duplicated Data Assets, reliability and debugging improvements, and Common UI itself becoming production-ready.

Meanwhile, the Enhanced Input integration how-to retains Experimental and limited support wording, together with a shipping warning originating from UE5.2. Do not use either page alone to make an unconditional claim about stability or shipping suitability.

Keep the two configuration paths distinct:

Current path: Input Actions, Player Mappable Key Settings, metadata implementing ICommonMappingContextMetadataInterface, and Input Mapping Contexts (IMCs). The standard metadata class is UCommonMappingContextMetadata.
Legacy path: A DataTable using CommonInputActionDataBase as its row structure, together with row handles.
Shared asset does not mean legacy: CommonUIInputData can also reference the current Accept/Back Input Actions. Its presence alone does not identify which path a project uses.
Migration rule: Choose one authoritative registration path for each action. Do not register the same action through both paths.

When Is Generic Input Action is enabled, CommonUI does not fire the ordinary Enhanced Input event for that action. Also check for duplicate registration between the CommonUI layer and gameplay input. See the CommonUI Input Technical Guide.

Slate, Canvas, and Widget Components

Slate is appropriate for editor plugins and low-level components that UMG does not provide. It is not a requirement merely because a project uses C++. See the Slate UI Framework.

AHUD Canvas is useful for crosshairs and diagnostic drawing. It is not a replacement for a menu architecture.

UWidgetComponent requires explicit decisions about draw size, redraw policy, distance, occlusion, and how many widgets update. See Widget Components. For UWidgetInteractionComponent, allocate Virtual User and Pointer indices deliberately so independent players or VR hands do not collide. See Widget Interaction Components.

Beta and Experimental features

Editor Utility Widgets and UMG Viewmodel are Beta. UIFramework and SlateIM are Experimental. Keep those labels visible in the adoption decision, not just in a footnote. For editor tooling, move heavy processing into a C++ editor module; treat Experimental UI features as research or diagnostic options rather than the default production foundation. The corresponding feature references are linked in the opening table.

Prerequisites for a new UE5.8 project

Adding modules to Build.cs does not enable plugins. Enable the plugins through the Plugins window or the project's .uproject file.

The following is a Plugins fragment to merge into an existing .uproject file, not a complete project file. Enable only the features the project actually uses: plain UMG does not require CommonUI or MVVM.

{"Plugins":[
  {"Name":"CommonUI","Enabled":true},
  {"Name":"EnhancedInput","Enabled":true},
  {"Name":"ModelViewViewModel","Enabled":true}
]}

CommonUI setup order

Enable CommonUI and, when required, EnhancedInput.
Set Game Viewport Client Class to CommonGameViewportClient or a subclass.
Assign Input Data and platform-specific Controller Data in Common Input Settings.
For the current integration path, enable Enhanced Input Support, configure the Input Action metadata, and register the actions in an IMC.
Reference the current Accept/Back Input Actions from CommonUIInputData.
When retaining legacy configuration, avoid registering the same action through both the DataTable and current paths.
Test keyboard/mouse, gamepad, device switching, and the complete pause → modal → gameplay sequence on the target hardware.

The viewport client forwards input into the CommonUI router and lets unhandled input continue toward gameplay. Keeping an unconditional duplicate action handler in the PlayerController can cause the same action to fire twice. See the CommonUI Input Technical Guide.

MVVM creation types

Enable the UMG Viewmodel plugin, then choose how the Viewmodel is supplied in the Widget Designer's Viewmodels panel. See UMG Viewmodel.

Creation type	Purpose
Create Instance	Automatically create a Viewmodel for each widget.
Manual	Inject an existing instance created by the owner or Presenter.
Global Viewmodel Collection	Retrieve an instance from the MVVM Subsystem's shared collection.
Property Path	Resolve an instance through a property/function path.
Resolver	Delegate acquisition or creation to a resolver object.
Context	Obtain the Viewmodel from a local context provider. A parent widget binding or external Context Extension can supply it; manual assignment is also possible.

The UE5.8 enum includes Resolver and Context, not just the four older options. See the Creation Type API and UE5.8 release notes. Shared context resolution is defined through UMVVMViewModelContextResolver. These remain part of the Beta MVVM feature and need regression coverage.

`Build.cs` dependencies

Merge these lines into the existing module rules constructor; they are not a complete Build.cs file.

PublicDependencyModuleNames.AddRange(new[] { "Core", "CoreUObject", "Engine", "UMG" });

// Add only when UMyUIManager.cpp directly uses FSlateApplication / FSlateUser.
PrivateDependencyModuleNames.AddRange(new[] { "Slate", "SlateCore" });

Add only the modules whose C++ types the project actually uses. CommonUI classes require CommonUI; Common Input types require CommonInput; Enhanced Input types require EnhancedInput; and MVVM APIs require ModelViewViewModel.

FKey and related input types require InputCore. Direct Slate usage, such as SWidget, FReply, or the focus APIs used below, requires the appropriate Slate / SlateCore dependencies. Dependencies exposed through public headers belong in PublicDependencyModuleNames; implementation-only dependencies belong in PrivateDependencyModuleNames.

The split-screen-aware RestoreGameplayInput() example directly uses FSlateApplication and FSlateUser in a .cpp file, so that example requires Slate and SlateCore as private dependencies. They are not blanket prerequisites for every plain UMG project.

Use the same responsibility model in Blueprint and C++

Responsibility	Blueprint-first project	C++-first project
State ownership	Actor Component, PlayerState, or Subsystem	Native class, service, or Gameplay Ability
Presentation	Blueprint Presenter or Viewmodel; the owner for a simple screen	UObject Presenter or native Viewmodel; the owner for a simple screen
Widget ownership	BP_PlayerController, BP_HUD, or a UI manager exposed to Blueprint through C++ when needed	PlayerController, HUD, or a `ULocalPlayerSubsystem` subclass
Input routing	Enhanced Input, CommonUI, and BP_UIManager	CommonUI Action Router, PlayerController, and UI manager

A Blueprint-first ammunition HUD

The same architecture can be implemented without moving every responsibility into native code:

Expose the source contract. BP_AmmoComponent provides getters, a RequestReload command, and an OnAmmoChanged Event Dispatcher.
Create and retain the widget. BP_PlayerController or BP_UIManager creates WBP_AmmoHUD with an Owning Player, stores it in a variable, and calls Add to Player Screen.
Track Pawn changes. The owner binds once to On Possessed Pawn Changed, immediately synchronizes with Get Controlled Pawn, and calls WBP_AmmoHUD.InitializeAmmoHUD(AmmoComponent) whenever the Pawn changes—including None and spectator transitions.
Reconnect explicitly. InitializeAmmoHUD unbinds the same Custom Event from the previously retained component, stores the new component, binds again, and immediately reads the getters. With None, reset the display rather than keeping the previous Pawn's ammunition.
Close symmetrically. CloseAmmoHUD unbinds that same Custom Event. Do not use Unbind All and accidentally remove other listeners.
Send commands instead of setting state. The reload button calls the retained component, or uses BPI_AmmoCommands to reach a Subsystem command. It does not directly overwrite ammunition values.

Choose the binding pair that matches the screen's lifetime: Construct/Destruct for removal and re-addition, Activated/Deactivated for CommonUI interaction, or explicit Open/Close for a screen that only changes visibility. Reopening must reconnect and immediately synchronize the current values.

A Blueprint Interface defines a command/getter boundary; it does not replace an Event Dispatcher. In a networked game, connect the command to the appropriate Server RPC or Gameplay Ability rather than assuming that a UI call has gameplay authority.

When to move a responsibility into C++

Move code when there is a concrete benefit: shared native type contracts, reuse, reviewable text diffs, automated tests, asynchronous or networking boundaries, or a measured processing bottleneck. This is not a claim that Blueprint lacks type checking.

“Blueprint is slow” is not a sufficient reason by itself. Layout, styles, animations, and hover/focus feedback can remain in Widget Blueprints while state and lifecycle contracts move into C++ incrementally.

C++ example: connect creation, ownership, initial state, and cleanup

The ammunition HUD has three parts:

UAmmoSourceComponent owns the state-facing contract.
UAmmoWidget renders the values and emits a reload request.
AMyPlayerController owns the widget and acts as the thin presentation adapter.

Replace MYGAME_API with your module's API macro. The source component below defines the public contract used by the controller; it is not a complete replicated weapon system.

1. Define the source component contract

The component declares the native delegate type, a reference-returning delegate getter, value getters, a state-change broadcast, and RequestReload().

Weapon calculations, replication, and server validation are deliberately outside this minimal example. A BlueprintNativeEvent places its default C++ implementation in _Implementation; see UFunctions. Here, reloading intentionally does nothing until a Blueprint override or C++ subclass forwards the request to a Server RPC, Ability, or weapon system.

// AmmoSourceComponent.h
#pragma once
#include "CoreMinimal.h"
#include "Components/ActorComponent.h"
#include "AmmoSourceComponent.generated.h"

DECLARE_MULTICAST_DELEGATE_TwoParams(FOnAmmoChangedNative, int32, int32);

UCLASS(ClassGroup=(Combat), meta=(BlueprintSpawnableComponent))
class MYGAME_API UAmmoSourceComponent : public UActorComponent
{
    GENERATED_BODY()
public:
    FOnAmmoChangedNative& OnAmmoChanged() { return AmmoChanged; }
    UFUNCTION(BlueprintPure, Category="Ammo") int32 GetCurrentAmmo() const
    { return FMath::Clamp(CurrentAmmo, 0, GetMagazineSize()); }
    UFUNCTION(BlueprintPure, Category="Ammo") int32 GetMagazineSize() const
    { return FMath::Max(MagazineSize, 1); }
    UFUNCTION(BlueprintCallable, BlueprintNativeEvent, Category="Ammo")
    void RequestReload();
    virtual void RequestReload_Implementation();
    void ApplyAmmoStateFromGameplay(int32 NewCurrent, int32 NewMagazine);

private:
    UPROPERTY(Transient) int32 CurrentAmmo = 30;
    UPROPERTY(EditDefaultsOnly, Category="Ammo", meta=(ClampMin="1"))
    int32 MagazineSize = 30;
    FOnAmmoChangedNative AmmoChanged;
};

// AmmoSourceComponent.cpp
#include "AmmoSourceComponent.h"

void UAmmoSourceComponent::RequestReload_Implementation()
{
    // In production, forward to a Server RPC, Ability, or weapon system.
}

void UAmmoSourceComponent::ApplyAmmoStateFromGameplay(
    int32 NewCurrent, int32 NewMagazine)
{
    const int32 Magazine = FMath::Max(NewMagazine, 1);
    const int32 Current = FMath::Clamp(NewCurrent, 0, Magazine);
    if (CurrentAmmo == Current && MagazineSize == Magazine) return;
    CurrentAmmo = Current;
    MagazineSize = Magazine;
    AmmoChanged.Broadcast(CurrentAmmo, MagazineSize);
}

This native delegate is not a UPROPERTY. A subscriber retains its FDelegateHandle and removes it from the same delegate instance when disconnecting. Read the getters for the initial display; do not wait for the next change notification.

2. Define the display widget

In the derived Widget Blueprint, connect the button's OnClicked event to the widget's RequestReload function. The widget emits an intent; the controller forwards it to the current source.

// AmmoWidget.h
#pragma once
#include "CoreMinimal.h"
#include "Blueprint/UserWidget.h"
#include "Components/TextBlock.h"
#include "AmmoWidget.generated.h"

DECLARE_DYNAMIC_MULTICAST_DELEGATE(FOnAmmoReloadClicked);

UCLASS(Abstract)
class MYGAME_API UAmmoWidget : public UUserWidget
{
    GENERATED_BODY()
public:
    UFUNCTION(BlueprintCallable, Category="HUD")
    void SetAmmo(int32 Current, int32 Magazine)
    {
        if (!ensure(AmmoText)) return;
        const int32 SafeMagazine = FMath::Max(Magazine, 1);
        Current = FMath::Clamp(Current, 0, SafeMagazine);
        AmmoText->SetText(FText::Format(
            NSLOCTEXT("AmmoWidget", "AmmoFormat", "{0} / {1}"),
            FText::AsNumber(Current), FText::AsNumber(SafeMagazine)));
    }
    UFUNCTION(BlueprintCallable, Category="HUD")
    void RequestReload() { OnReloadClicked.Broadcast(); }
    UPROPERTY(BlueprintAssignable, Category="HUD")
    FOnAmmoReloadClicked OnReloadClicked;

protected:
    UPROPERTY(meta=(BindWidget)) TObjectPtr<UTextBlock> AmmoText;
};

Add the required Text Block named AmmoText to the derived Widget Blueprint. Its name and type must satisfy the BindWidget declaration. See BindWidget metadata.

3. Own the HUD in the PlayerController and use one Pawn-change path

Do not use separate OnPossess, AcknowledgePossession, and OnUnPossess overrides just to reconnect the HUD. OnPossessedPawnChanged is notified on both authority and client, and either the old or new Pawn can be nullptr. See the AController API and FOnPossessedPawnChanged API.

// MyPlayerController.h
#pragma once
#include "CoreMinimal.h"
#include "GameFramework/PlayerController.h"
#include "MyPlayerController.generated.h"

class APawn;
class UAmmoSourceComponent;
class UAmmoWidget;

UCLASS()
class MYGAME_API AMyPlayerController : public APlayerController
{
    GENERATED_BODY()
protected:
    virtual void BeginPlay() override;
    virtual void EndPlay(const EEndPlayReason::Type Reason) override;
private:
    UPROPERTY(EditDefaultsOnly, Category="UI")
    TSubclassOf<UAmmoWidget> AmmoWidgetClass;
    UPROPERTY(Transient) TObjectPtr<UAmmoWidget> AmmoWidget;
    TWeakObjectPtr<UAmmoSourceComponent> AmmoSource;
    FDelegateHandle AmmoChangedHandle;
    UFUNCTION() void HandlePawnChanged(APawn* OldPawn, APawn* NewPawn);
    UFUNCTION() void HandleReload();
    void BindAmmoHudToPawn(APawn* NewPawn);
    void UnbindAmmoSource();
    void HandleAmmoChanged(int32 Current, int32 Magazine);
};

// MyPlayerController.cpp
#include "MyPlayerController.h"
#include "AmmoSourceComponent.h"
#include "AmmoWidget.h"
#include "GameFramework/Pawn.h"

void AMyPlayerController::BeginPlay()
{
    Super::BeginPlay();
    if (!IsLocalController() || !ensure(AmmoWidgetClass)) return;
    AmmoWidget = CreateWidget<UAmmoWidget>(this, AmmoWidgetClass);
    if (!ensure(AmmoWidget)) return;

    AmmoWidget->OnReloadClicked.AddUniqueDynamic(
        this, &AMyPlayerController::HandleReload);
    AmmoWidget->AddToPlayerScreen();
    OnPossessedPawnChanged.AddUniqueDynamic(
        this, &AMyPlayerController::HandlePawnChanged);
    BindAmmoHudToPawn(GetPawn());
}

void AMyPlayerController::HandlePawnChanged(APawn* OldPawn, APawn* NewPawn)
{
    (void)OldPawn;
    BindAmmoHudToPawn(NewPawn);
}

void AMyPlayerController::BindAmmoHudToPawn(APawn* NewPawn)
{
    UnbindAmmoSource();
    UAmmoSourceComponent* Source = NewPawn
        ? NewPawn->FindComponentByClass<UAmmoSourceComponent>() : nullptr;
    AmmoSource = Source;
    if (!Source) { HandleAmmoChanged(0, 1); return; }

    AmmoChangedHandle = Source->OnAmmoChanged().AddUObject(
        this, &AMyPlayerController::HandleAmmoChanged);
    HandleAmmoChanged(Source->GetCurrentAmmo(), Source->GetMagazineSize());
}

void AMyPlayerController::UnbindAmmoSource()
{
    if (UAmmoSourceComponent* Source = AmmoSource.Get();
        Source && AmmoChangedHandle.IsValid())
        Source->OnAmmoChanged().Remove(AmmoChangedHandle);
    AmmoChangedHandle.Reset();
    AmmoSource.Reset();
}

void AMyPlayerController::HandleAmmoChanged(int32 Current, int32 Magazine)
{
    if (AmmoWidget) AmmoWidget->SetAmmo(Current, Magazine);
}

void AMyPlayerController::HandleReload()
{
    if (UAmmoSourceComponent* Source = AmmoSource.Get()) Source->RequestReload();
}

void AMyPlayerController::EndPlay(const EEndPlayReason::Type Reason)
{
    OnPossessedPawnChanged.RemoveDynamic(
        this, &AMyPlayerController::HandlePawnChanged);
    UnbindAmmoSource();
    if (AmmoWidget)
    {
        AmmoWidget->OnReloadClicked.RemoveDynamic(
            this, &AMyPlayerController::HandleReload);
        AmmoWidget->RemoveFromParent();
        AmmoWidget = nullptr;
    }
    Super::EndPlay(Reason);
}

Configure a concrete Widget Blueprint derived from UAmmoWidget as AmmoWidgetClass, use the controller class in the game configuration, and give the relevant Pawn a UAmmoSourceComponent or subclass. Gameplay must feed state changes into the source; the example does not add replication for you.

BeginPlay binds once to the Pawn-change notification and immediately synchronizes using GetPawn(). Every reconnection first unsubscribes from the old source. A null Pawn—or a Pawn without the source component—resets the HUD to 0 / 1, the example's explicit no-source display.

Environment	Transition	Acceptance condition
Listen server's local player	Pawn A → `nullptr` / spectator → Pawn B	Pawn A notifications stop immediately; the no-source state resets the HUD; each Pawn B event produces exactly one update.
Remote owning client	Pawn A → `nullptr` / spectator → Pawn B	No old subscription or stale Pawn A display remains on the client; each Pawn B event produces exactly one update.

The controller owns this HUD until EndPlay. A design that temporarily closes the HUD needs its own matching disconnect/reconnect contract; the lifecycle choices in the next section explain how to define one.

Extract a dedicated class such as UAmmoHudPresenter when the adapter must combine multiple sources, share formatted text, handle asynchronous loading or replays, or support tests without a live gameplay source.

Delegate subscriptions need four distinct lifetime contracts

Binding in OnInitialized and unbinding in Destruct is an unsafe pairing for a reusable widget instance. After removal and re-addition, OnInitialized does not run again to restore that subscription.

OnInitialized normally runs once per instance; Construct and Destruct can run multiple times as the underlying widget hierarchy is constructed and destroyed. See OnInitialized, Construct, and Destruct.

Lifetime contract	Bind / unbind pair	Typical use
Entire widget instance	Bind once in `NativeOnInitialized`; normally do not remove it in `NativeDestruct`.	A callback from a child button within the same widget.
Presence in the widget hierarchy	`NativeConstruct` / `NativeDestruct`	External gameplay delegates, timers, or message-bus subscriptions tied to that presence.
Active CommonUI interaction	`NativeOnActivated` / `NativeOnDeactivated`	Subscriptions and input needed only while the screen is active.
Explicit visibility-based open period	Explicit `Open()` / `Close()`	A panel that becomes Hidden or Collapsed without being removed.

NativePreConstruct also runs for Designer previews, so do not access world state there unconditionally.

Test all four transitions: first display, remove → re-add, deactivate → reactivate, and hide → show. In each case, reconnecting should synchronize immediately, necessary notifications should not disappear, and each event should be delivered exactly once.

Restore input after closing the last CommonUI screen

FUIInputConfig controls input mode, mouse capture/lock, bHideCursorDuringViewportCapture, and whether move/look input is ignored. That cursor flag means hide the cursor while the viewport has capture. General visibility policy through APlayerController::bShowMouseCursor is a separate responsibility. See the FUIInputConfig API.

When no desired configuration is supplied, CommonUI can fall back to the last valid input configuration. Deactivating every Activatable Widget does not necessarily restore gameplay input. See Input Fundamentals for CommonUI.

Use one of two explicit policies:

Keep a persistent gameplay Activatable Widget at the root. It returns ECommonInputMode::Game, the intended mouse-capture policy, and enabled move/look input.
When removing all UI, let the LocalPlayer UI manager restore gameplay input configuration, bShowMouseCursor, and viewport focus after the final pop completes.

The following is a method excerpt for a UGameplayRoot class derived from UCommonActivatableWidget; declare the matching override in that class.

TOptional<FUIInputConfig> UGameplayRoot::GetDesiredInputConfig() const
{
    FUIInputConfig C(ECommonInputMode::Game,
        EMouseCaptureMode::CapturePermanently_IncludingInitialMouseDown,
        true); // Hide the cursor while the viewport has capture.
    C.bIgnoreMoveInput = false;
    C.bIgnoreLookInput = false;
    return C;
}

The next excerpt belongs to a UMyUIManager derived from ULocalPlayerSubsystem, with RestoreGameplayInput() declared in its class. It restores viewport focus only for the Slate User associated with that LocalPlayer. Include the CommonUI module and the private Slate dependencies described earlier.

#include "Engine/LocalPlayer.h"
#include "Framework/Application/SlateApplication.h"
#include "Framework/Application/SlateUser.h"
#include "GameFramework/PlayerController.h"
#include "Input/CommonUIActionRouterBase.h"
#include "Input/UIActionBindingHandle.h"

void UMyUIManager::RestoreGameplayInput()
{
    ULocalPlayer* LocalPlayer = GetLocalPlayer();
    if (!LocalPlayer) return;

    UCommonUIActionRouterBase* Router =
        LocalPlayer->GetSubsystem<UCommonUIActionRouterBase>();
    if (!Router) return;

    FUIInputConfig C(ECommonInputMode::Game,
        EMouseCaptureMode::CapturePermanently_IncludingInitialMouseDown, true);
    C.bIgnoreMoveInput = C.bIgnoreLookInput = false;
    Router->SetActiveUIInputConfig(C, this);

    if (APlayerController* PC = LocalPlayer->GetPlayerController(GetWorld()))
    {
        PC->bShowMouseCursor = false;
    }

    if (TSharedPtr<FSlateUser> SlateUser = LocalPlayer->GetSlateUser())
    {
        FSlateApplication::Get().SetUserFocusToGameViewport(
            SlateUser->GetUserIndex(),
            EFocusCause::SetDirectly);
    }
}

ULocalPlayer::GetSlateUser() returns the Slate User associated with that LocalPlayer. FSlateApplication exposes separate APIs for all users, SetAllUserFocusToGameViewport, and for one specified user, SetUserFocusToGameViewport. See the FSlateApplication API.

Do not replace the user-specific call with UWidgetBlueprintLibrary::SetFocusToGameViewport() in a split-screen UI manager. That Blueprint utility has no LocalPlayer parameter; the UE5.8 source behavior identified during review delegates to SetAllUserFocusToGameViewport(). Restrict it to projects that guarantee exactly one LocalPlayer. See the UWidgetBlueprintLibrary API. In a Blueprint-first split-screen project, expose the user-specific operation through a BlueprintCallable C++ wrapper.

UCommonUIActionRouterBase itself derives from ULocalPlayerSubsystem and provides SetActiveUIInputConfig; see its API reference. Use RequestRefreshFocus only with the leaf-most active node, as required by its API contract.

Step	Keyboard / mouse	Gamepad
Open pause	Move/look stop; cursor and capture match the menu policy.	The initial button receives focus and is usable.
Open a modal	Only the modal can be operated.	Back closes exactly one layer.
Close the modal	Control returns to the pause menu.	Focus returns inside the pause menu.
Close pause	Viewport focus, capture, and move/look are restored.	No stale UI focus consumes gameplay input; each input reaches its intended gameplay target once.

The split-screen acceptance test is stronger than “input works for both players.” Close Player 0's pause screen while Player 1 keeps a menu open: only Player 0 returns to the viewport, and Player 1 retains the menu and its focus. Repeat with the players reversed. Both directions must preserve one delivery per input to the correct target.

Manual events, MVVM, and performance

When there are few screens and ownership is clear, manual delegates or Event Dispatchers are enough. Consider a Presenter or MVVM when many widgets share the same state, display transformations need reuse, or Designer bindings and two-way binding provide a concrete benefit.

The following is a Viewmodel method excerpt, not a complete Viewmodel class. It assumes a CurrentHealth field and GetHealthText function configured for FieldNotify, as described in the UMG Viewmodel documentation.

void UPlayerStatusViewModel::SetCurrentHealth(int32 NewValue)
{
    if (UE_MVVM_SET_PROPERTY_VALUE(CurrentHealth, FMath::Max(NewValue, 0)))
        UE_MVVM_BROADCAST_FIELD_VALUE_CHANGED(GetHealthText);
}

A Viewmodel mediates display state and commands. It should not become the owner of damage calculations, persistent inventory storage, or server validation.

For UI performance, update frequency is often a more useful first question than whether a function was written in Blueprint or C++. Avoid per-frame casts, raw property bindings, repeated SetText calls with unchanged values, and unnecessary subscriptions for hidden screens. Prefer change events, List View entry reuse, invalidation, and reduced update frequency where appropriate. Apply a Retainer Box after measurement, not as a universal fix. See Optimization Guidelines for UMG and Invalidation in Slate and UMG.

A reproducible UI test matrix

Record aspect ratio, resolution, input device, world/VR interaction, and accessibility as separate dimensions. The values below are representative test conditions; replace the minimums with the actual supported minimums for your product and record the target platform for each run.

Dimension	Representative conditions	Acceptance condition
16:9	Minimum 1280×720; also 1920×1080 and 3840×2160	No clipping, overlap, or inaccessible controls.
16:10 / 21:9 / 32:9	1280×800, 3440×1440, and 5120×1440 when supported	Anchors, Safe Zones, and maximum widths remain within the design specification.
DPI and language	Minimum/maximum scaling, English/Japanese, longest translation, maximum digit count	No clipping, overlap, focus loss, or unstable layout.
Keyboard / mouse	Click, Tab, Escape, and pause → modal → gameplay	Focus, capture, cursor visibility, and gameplay input are correct; no double firing.
Gamepad	D-pad/stick, Accept, Back, and device switching	Initial/restored focus is correct; Back closes one layer.
Touch	Tap, scroll, software keyboard, and safe areas	Touch targets remain usable; scrolling does not conflict with other controls; the keyboard does not obscure required interaction.
Split-screen	Two LocalPlayers. Player 0 closes pause while Player 1 keeps a menu open; repeat in reverse.	Only the closing player's focus returns to the viewport. The other player's menu and focus remain unchanged. Each user's input reaches the correct target exactly once.
Pawn transitions	Pawn A → null / spectator → Pawn B	Unsubscribe from A, reset with no source, and update once per B event.
Widget lifetime	First display, remove/re-add, deactivate/reactivate, and hide/show	No missing or duplicated notifications.
World UI / VR	Occlusion, distance, left/right hands, and ray hit/miss	Unnecessary updates stop; Virtual User / Pointer assignments do not collide.
Accessibility	Keyboard navigation, contrast, and screen readers on supported platforms	Reading order, labels, and control reachability match the accessibility specification.

Automation Driver primarily targets desktop keyboard/mouse-style interaction. Test gamepads, touch, and motion controllers on hardware or with a separate harness rather than assuming Automation Driver covers them. See Automation Driver.

Screen Reader support is Experimental. The documented platform scope includes third-party screen readers on Windows and VoiceOver on iOS; do not assume universal platform coverage. See Supporting Screen Readers. Use Widget Reflector and Slate Insights to inspect focus, hit testing, invalidation, and updates.

Final recommendations

Use UMG for ordinary screens, CommonUI for screen stacks, Back navigation, and focus, a Presenter or Beta MVVM for complex presentation, and Widget Components for world-space UI.

Editor Utility Widgets and UMG Viewmodel are Beta; UIFramework and SlateIM are Experimental. The release notes describe Common UI itself as production-ready, but the Enhanced Input how-to retains older warnings. Keep the current and legacy integration paths separate, and validate the configuration used by the project against the linked documentation and target build.

Whether the project is Blueprint-first or C++-first, make the same four responsibilities explicit: state ownership, presentation, widget ownership, and input routing. Once those boundaries are clear, the Blueprint/C++ split can evolve without rewriting the whole UI architecture.

References

Version-sensitive and API-specific claims link directly to the relevant Epic documentation throughout the article. This English adaptation retains the UE5.8 scope of the reviewed Japanese edition. That edition records August 31, 2026 as its technical reference date; the translation is not a new engine build or runtime validation.

HDR in Unity URP: Bloom, Tone Mapping, and HDR Display Output

GameDevToolLab — Fri, 25 Sep 2026 03:36:48 +0000

Introduction

HDR, Emission, Bloom, Exposure, and Tonemapping are related but different features. Player Settings adds another: HDR Display Output.

Separate brightness during rendering from HDR display output, using an SDR-monitor experiment, diagnostics, and custom-rendering examples.

Sections 1–5 cover internal HDR; 6–8 cover output. Skip advanced sections 9–10 for troubleshooting in section 11 as needed.

Scope: Unity 6.3 LTS (6000.3), URP 17.3, English UI. Documentation review date recorded in the Japanese source: September 15, 2026. This translation does not revalidate every reference.¹

Untested examples: Unity compilation, scene execution, Player builds, HDR-display testing, and benchmarking have not been performed for this article. Observation prompts are not measured results.

1. Two meanings of HDR

HDR means High Dynamic Range. In Unity, distinguish these two uses:²

	HDR rendering	HDR display output
Purpose	Preserve brightness during rendering	Use an HDR display path
Controls	Camera, shader, buffer, post-processing	Player, OS, GPU, display
HDR monitor?	Not for internal processing	Yes, with compatible output

HDR rendering can end in SDR output. Games for SDR monitors can preserve HDR internally and map it to the display range afterward.²

High Definition Render Pipeline (HDRP) is not required for HDR. URP supports it, and HDRP also needs output configuration.³⁴

2. Why values above 1 matter

A white wall is not an emissive sign

These grayscale shader outputs illustrate scene values, not measured luminance:

White surface:     ( 1,  1,  1)
Emissive surface:  ( 4,  4,  4)
Strong emission:   (16, 16, 16)

Clamping them to 0–1 makes all three (1, 1, 1). Later processing cannot recover the difference.

An HDR buffer preserves differences for Bloom and later output conversion. HDR retains information; it does not simply brighten the image.²

Tone mapping is not clipping

Tone mapping remaps brightness to the output range. For example:

y = x / (1 + x)

Input x	Clamped to 0–1	Result of the formula
1	1	0.500
4	1	0.800
16	1	0.941

This preserves differences within 0–1. It is not Unity's Neutral or ACES formula. Choose URP's operator in the Tonemapping Volume Override.⁵

3. Linear, HDR, gamut, and bit depth

Concept	What it describes
Linear / Gamma	How lighting and color values relate numerically
HDR / SDR	Brightness range
Color gamut	Represented/encoded color range
Bit depth / format	Precision and numerical range

Linear does not enable HDR output. 10-bit storage need not be HDR, and HDR does not make assets wide-gamut.⁶⁷

Set Project Settings > Player > Other Settings > Rendering > Color Space to Linear. This changes lighting and blending in existing Gamma projects; compare and readjust their appearance.⁸⁹

Do not disable sRGB (Color Texture) everywhere. Color textures and data masks differ. Disabling it skips sRGB-to-Linear sampling conversion; choose according to the data.¹⁰

4. Compare HDR on an SDR monitor

Disable HDR display output initially to isolate internal HDR from OS/display settings.

4.1 Check the active URP Asset

An asset assigned to the current Quality level overrides the default. Identify the active asset with GraphicsSettings.currentRenderPipeline.¹¹

Enable its HDR setting and set Post-processing > Grading Mode to High Dynamic Range. Grading Mode controls grading, not display output.¹²

4.2 Configure the camera and Volume

Use one Base Camera without a target RenderTexture. Enable Output > HDR Rendering and Rendering > Post Processing in its Inspector.¹³

Create GameObject > Volume > Global Volume with a new Profile and Weight 1. Include its Layer in the camera's Volume Mask. Disable other Volumes and custom Renderer Features.¹⁴¹³

Add Bloom and Tonemapping. Enable each edited setting's override checkbox:

Override	Setting	Comparison value
Bloom	Threshold	2.0
Bloom	Intensity	0.5
Bloom	Scatter	0.7
Tonemapping	Mode	None initially

These are examples, not defaults or universal recommendations. Leave other color/exposure adjustments off.

Bloom Threshold uses gamma-space brightness. Threshold 2 does not directly select Linear shader values above 2.¹⁵

URP includes Volume-based post-processing; do not mix in Post Processing Stack v2.¹⁶

4.3 Build an HDR Unlit Shader Graph

Create a Universal Unlit Shader Graph to avoid lighting effects. Expose a Color property named HDR Color, Mode HDR, connected to Fragment Base Color. Keep Surface Type Opaque.¹⁷¹⁸

HDR Color property
    Mode: HDR
        |
        +-- Fragment / Base Color

Create three materials, with Alpha 1. Enter RGB using the HDR picker's float display:

Material	RGB	Intensity from white
A	(1, 1, 1)	0
B	(4, 4, 4)	+2
C	(16, 16, 16)	+4

Each Intensity step doubles RGB: +2 means ×4, +4 means ×16—not ×4. Reopening the picker can change its color/intensity decomposition without changing stored RGB.¹⁹

Assign A, B, C to Cubes at (-1.5, 0, 0), (0, 0, 0), (1.5, 0, 0). Use camera position (0, 0, -6), rotation (0, 0, 0), Orthographic Size 2, a dark solid background, and 16:9 Game View.

4.4 Change one variable at a time

These are observation prompts, not results recorded in Unity:

Configuration (Bloom values are Intensity)	What to examine
HDR on, Bloom 0, Tonemapping None	Does SDR hide differences in the white surfaces?
HDR on, Bloom 0.5, Tonemapping None	Do similar whites produce different glow?
HDR on, Bloom on, Neutral	How do highlights and surroundings change?
Same setup, HDR Rendering off	How does losing HDR differences affect Bloom?

Look for different values behind apparently identical whites, not just glow.

Bloom also works on 0–1 images with a low Threshold. HDR distinguishes brighter-than-white values.¹⁵

5. Separate Emission, Bloom, exposure, and tone mapping

This conceptual flow is not an exact render-pass schedule:²²⁰²¹

Shaders and lighting
    -> HDR scene color
    -> Image effects such as Bloom
    -> Post Exposure and color adjustments
    -> Tone mapping
    -> SDR or HDR display output

Emission is not Bloom

Emission represents a Lit material's self-emission; Bloom spreads bright image regions. Increasing Emission does not enable Bloom.²²¹⁵

Emission does not guarantee nearby illumination; check the GI setup and method. An additional Light can illuminate an emissive sign's surroundings.²²

This class-field declaration enables an HDR color picker, not camera HDR:²³

[SerializeField, ColorUsage(false, true)]
private Color emissionColor = Color.white;

Post Exposure comes after HDR effects

Post Exposure in Color Adjustments runs after HDR effects, before tone mapping. Raising it is not equivalent to raising Bloom's input.²⁰

Choose the emitter, Bloom extraction, or processed-image exposure control according to your goal.

Compare Neutral and ACES by appearance

Neutral minimizes hue/saturation changes. ACES approximates the reference ACES tone mapper, with stronger contrast and hue/saturation changes.⁵

For stylized emission, compare Neutral with ACES. Choose the intended look; ACES is not automatically better.

6. Enable HDR display output

URP HDR output requires Linear, an HDR-capable environment, and HDR in the active URP Asset. Check Player Other Settings:²¹³

Setting	Purpose
Allow HDR Display Output	Permit HDR output
Use HDR Display Output	Use HDR on the main display

A monitor alone is insufficient: check OS HDR settings, GPU, driver, and Graphics API.⁷

Start Windows testing with a D3D12 Player. Unity 6.3 URP also lists D3D11 and Vulkan. D3D11 HDR is Player-only, not available in the Editor or exclusive fullscreen. Use borderless fullscreen.²¹

HDR output still maps to the display range rather than sending scene values unchanged.²¹

7. Inspect HDR output in code

7.1 Read output and request status

Read HDROutputSettings.main: available includes the main display and project settings; active reports current HDR output. Availability is not a monitor-hardware-only test.²⁴²⁵

HDRModeChangeRequested reports a pending request, not current output. This diagnostic blocks further requests while one is pending; the caller checks completion later.²⁶²⁷

Save HdrOutputProbe.cs and attach it to a GameObject. It uses UnityEngine only. The source revision checked Unity 6.3 API/C# declarations, not compilation or execution. HDRModeChangeRequested is a property, without ().²⁸²⁹

using UnityEngine;

[DisallowMultipleComponent]
public sealed class HdrOutputProbe : MonoBehaviour
{
    private void Start()
    {
        LogStatus();
    }

    [ContextMenu("HDR/Log Status")]
    public void LogStatus()
    {
        var hdr = HDROutputSettings.main;
        if (hdr == null)
        {
            Debug.LogWarning("Could not retrieve HDR output settings.", this);
            return;
        }

        bool available = hdr.available;
        bool active = hdr.active;
        Debug.Log(
            $"ColorSpace={QualitySettings.activeColorSpace}, " +
            $"HDR available={available}, active={active}",
            this);

        // Do not read request status or luminance data when HDR is unavailable.
        if (!available)
        {
            Debug.Log("Skipped HDR details because HDR is unavailable.", this);
            return;
        }

        Debug.Log(
            $"API automaticHDRTonemapping={hdr.automaticHDRTonemapping}, " +
            $"HDRModeChangeRequested={hdr.HDRModeChangeRequested}",
            this);

        if (!active)
        {
            Debug.Log("HDR output is inactive. Skipped luminance data.", this);
            return;
        }

        // These are API values, not the effective settings of the URP Volume.
        Debug.Log(
            $"API paperWhiteNits={hdr.paperWhiteNits:F1} nits, " +
            $"minToneMapLuminance={hdr.minToneMapLuminance} nits, " +
            $"maxToneMapLuminance(10%)={hdr.maxToneMapLuminance} nits, " +
            $"maxFullFrameToneMapLuminance(100%)=" +
            $"{hdr.maxFullFrameToneMapLuminance} nits",
            this);
    }

    [ContextMenu("HDR/Request On")]
    public void RequestOn() => RequestMode(true);

    [ContextMenu("HDR/Request Off")]
    public void RequestOff() => RequestMode(false);

    private void RequestMode(bool enable)
    {
        if (!Application.isPlaying)
        {
            Debug.LogWarning("Call this method while the application is playing.", this);
            return;
        }

        var hdr = HDROutputSettings.main;
        // Check availability for both enabling and disabling HDR.
        if (hdr == null || !hdr.available)
        {
            Debug.LogWarning(
                "Cannot request an HDR output mode change in this environment.",
                this);
            return;
        }

        // Do not send another request, including a reversal, while one is pending.
        if (hdr.HDRModeChangeRequested)
        {
            Debug.LogWarning("An HDR output mode change request is still pending.", this);
            return;
        }

        if (hdr.active == enable)
        {
            Debug.Log($"HDR output is already in the requested state: {enable}", this);
            return;
        }

        hdr.RequestHDRModeChange(enable);
        Debug.Log(
            $"Requested HDR output change: {enable}. " +
            "Call LogStatus later to check the pending state and active output.",
            this);
    }
}

It logs at startup. Use its context menu in Play Mode, or public methods from Player UI Buttons. Install only one HdrOutputProbe.cs, not both pasted and supplied copies.

7.2 Guard both on and off requests

RequestHDRModeChange is documented to throw when HDR is unavailable. false is not exempt. Both directions use hdr == null || !hdr.available.²⁶

HDRModeChangeRequested and paperWhiteNits also document unavailable-environment exceptions. Read details after checking available, and luminance only when active.²⁷³⁰

Pending-request blocking and same-state skipping are sample policies, not mandatory Unity rules. Checking pending status first avoids treating an unfinished transition as complete.

available=true does not guarantee runtime switching everywhere. Returning from a request does not prove completion; call LogStatus() later to check pending status and active.²⁶²⁵

The sample lacks polling, timeouts, and disconnection recovery. Production UI needs availability rechecks, pending-state input restrictions, and completion updates. Save settings after confirming output, not logging a request.

7.3 Interpret API values correctly

API identifies HDR output settings, not photometer measurements or effective camera-Volume settings.²⁸³¹

Log field	Meaning or limitation
`available`	Availability for the main display and project
`active`	Current HDR state; compare against the request
`HDRModeChangeRequested`	Pending change; read only when available
`automaticHDRTonemapping`	Common API automatic tone-mapping state
`paperWhiteNits`	Reference white for automatic mapping with active HDR
`minToneMapLuminance`	Minimum input luminance retaining detail
`maxToneMapLuminance(10%)`	Maximum input luminance retaining detail: 10% bright area
`maxFullFrameToneMapLuminance(100%)`	Maximum input luminance retaining detail: entire screen bright

maxToneMapLuminance is not an unconditional display peak. (10%) and (100%) are log labels, not API names.²⁸

paperWhiteNits is documented for automatic HDR tone mapping with active HDR output; reading it does not prove URP uses it. automaticHDRTonemapping=false does not imply that the URP Tonemapping Volume is disabled.³⁰³²³¹

URP Volumes can override Paper White and luminance limits. Check output status in logs and artistic settings in the camera's Volumes. The probe does not change automatic tone mapping or Paper White.³¹⁵

available=true, active=false means available but inactive. available=false proves neither hardware failure nor an SDR-only monitor. These examples are not captured logs.²⁴²⁵

8. Paper White and highlight limits

1 nit = 1 cd/m² is a luminance unit, not a relative shader color value.²⁸

Paper White controls reference white, including UI white—not the display's maximum brightness.²¹

For illustration, ordinary white might be 200 nits and highlights reach 1000 nits; UI need not reach the maximum. These are not universal recommendations. Shader 1.0 is not inherently 1 or 200 nits; conversion and settings determine that relationship.³¹

HDR Tonemapping adds these controls. Both Neutral and ACES support Paper White.⁵

Setting	Neutral	ACES
Automatic white	`Detect Paper White`	`Detect Paper White`
Manual white	`Paper White`	`Paper White`
Brightness range	`Detect Brightness Limits`, `Min Nits`, `Max Nits`	`ACES Preset`: 1000, 2000, or 4000 nits

Disable Detect Paper White for manual white in either mode. Neutral exposes Min Nits/Max Nits when Detect Brightness Limits is off; ACES uses a preset. White controls overlap, but range controls differ.⁵

An ACES 1000-nit preset does not make UI white 1000 nits. Compare UI and emission, checking Inspector overrides rather than preset names.⁵²¹

Display reports can be inaccurate. Consider user calibration across highlights, menus, subtitles, and loading screens.⁵

9. Advanced: preserve HDR data

9.1 Avoid saturating HDR color

saturate in HLSL and Shader Graph clamps to 0–1: useful for masks, destructive for HDR color before tone mapping.³³

// Expressions inside a shader, not a complete Shader file.
float3 hdrColor = baseColor * intensity;

// Outputting this as scene color loses differences above 1.
float3 clippedColor = saturate(hdrColor);

Treat masks and interpolation weights separately from colors that need an HDR range.

9.2 Avoid duplicate color conversions

New Shader Graph HDR Color Nodes use Linear; old graphs may retain compatibility behavior. Unlike color textures, they may not need conversion. Check the input space before adding .linear or pow.³⁴

9.3 Choose an appropriate RenderTexture

Intermediate RenderTexture clipping is irreversible. These formats describe raw scene-linear color before display encoding, not final HDR signals:³⁵

GraphicsFormat	Bits/pixel	Raw values above 1	Alpha
`R8G8B8A8_UNorm`	32	No	Yes
`B10G11R11_UFloatPack32`	32	Yes, positive values	No
`R16G16B16A16_SFloat`	64	Yes	Yes

UNorm is not always SDR: HDR10 can use PQ-encoded 10-bit UNorm. Storage format and signal encoding both matter.⁷

URP's 64-bit HDR Precision increases precision and bandwidth cost. HDR Alpha Processing requires 64-bit; 32-bit HDR does not necessarily include alpha.¹²

A target RenderTexture hides some camera HDR controls and determines target settings. Camera HDR alone does not guarantee a suitable format.¹³

9.4 Match the custom-pass stage

Post-processed HDR output may not mean scene-linear color. At or after AfterRenderingPostProcessing, account for gamut and luminance conversion.³¹

For post-processing overlays or custom UI, check white levels and duplicate conversion. A float RenderTexture cannot prevent a doubled output transform.³⁶

9.5 EXR cannot recover discarded values

Unity can encode EXR, but the source must retain HDR data. EXR cannot restore values already lost to tone mapping or clamping.³⁷

10. Advanced: memory and performance

HDR need not double color-buffer storage: 32-bit HDR exists. At fixed resolution, 32 to 64 bits doubles an uncompressed buffer's raw size.³⁵

At 3840 × 2160:

32 bits/pixel:
3840 × 2160 × 4 bytes / 1024² ≈ 31.64 MiB

64 bits/pixel:
3840 × 2160 × 8 bytes / 1024² ≈ 63.28 MiB

These theoretical sizes cover one color buffer, not depth, MSAA, copies, history, or alignment. They are not measured application memory.

Compare HDR, precision, resolution, and Bloom separately, including high-quality Bloom filtering's added cost and benefit.¹⁵

On the same hardware and resolution, toggle HDR, 32/64-bit precision, and Bloom individually. Record GPU time and appearance.

11. Troubleshooting

These are starting points, not diagnoses:

Symptom	Check first
No visible HDR difference	Above-1 values and effects that reveal them
Emission without glow	Post Processing, Volume Mask, Bloom override/Intensity
Ordinary whites glow	Emitter values and Bloom Threshold
HDR display receives SDR	OS/Player, Linear, Graphics API, `available`/`active`
UI too bright	Paper White, composition stage, output conversion
HDR lost after a custom effect	`saturate`, buffer formats, repeated tone mapping
Intermediate alpha lost	Target format, HDR Precision, Alpha Processing
Editor/Player mismatch	Quality pipeline asset and Graphics API constraints

Use Window > Analysis > Render Pipeline Debugger > Lighting > HDR Debug Mode to inspect gamut and regions above Paper White, rather than relying only on the final image.³⁸

Conclusion

Track where brightness is created, preserved, and converted for display. Compare 1, 4, and 16 with internal HDR, Bloom, and tone mapping; then inspect display output and Paper White.

Separate rendering from display-path problems, ordinary white from highlights, and always check SDR too.

Unity Manual, Universal RP package — Unity 6.3. ↩
Unity Manual, Introduction to high dynamic range (HDR). ↩
Unity Manual, Enable HDR Output in URP. ↩
Unity HDRP 17.3 documentation, HDR Output. ↩
Unity Manual, Tonemapping Volume Override reference for URP. ↩
Unity Manual, Color spaces. ↩
Microsoft Learn, Use DirectX with Advanced Color on high/standard dynamic range displays. See the distinctions between storage formats and encoding, and between bit depth, gamut, and dynamic range. ↩
Unity Manual, Set the project color space. ↩
Unity Manual, Differences between linear and gamma color spaces. ↩
Unity Manual, Disable sRGB sampling for a texture. ↩
Unity Scripting API, QualitySettings.renderPipeline, GraphicsSettings.currentRenderPipeline. ↩
Unity Manual, URP Asset reference. ↩
Unity Manual, Camera component reference for URP. ↩
Unity Manual, Add post-processing in URP. ↩
Unity Manual, Bloom Volume Override reference for URP. ↩
Unity Manual, Post-processing in URP. ↩
Unity Shader Graph 17.3 documentation, Property Types. ↩
Unity Shader Graph 17.3 documentation, Your first Shader Graph. ↩
Unity Manual, HDR color picker reference. ↩
Unity Manual, Color Adjustments Volume Override reference for URP. ↩
Unity Manual, HDR Output in URP. ↩
Unity Manual, Lit shader reference for URP. ↩
Unity Scripting API, ColorUsageAttribute. ↩
Unity Scripting API, HDROutputSettings.available. ↩
Unity Scripting API, HDROutputSettings.active. ↩
Unity Scripting API, HDROutputSettings.RequestHDRModeChange — Unity 6.0. The Japanese revision used the Unity 6.0 member page for exception conditions and request behavior, and checked the declaration against the Unity 6.3 class reference and C# reference source. It could not retrieve the 6.3 member page. Behavior in a Unity 6.3 runtime remains untested; this adaptation has not revalidated it. ↩
Unity Scripting API, HDROutputSettings.HDRModeChangeRequested — Unity 6.0. The Japanese revision used the Unity 6.0 member page for exception conditions and checked the property declaration against the Unity 6.3 class reference and C# reference source. This is not a Unity 6.3 runtime test. ↩
Unity Scripting API, HDROutputSettings. ↩
Unity Technologies, UnityCsReference / 6000.3 / Graphics.bindings.cs. Used in the Japanese revision to check public property and method declarations in HDROutputSettings, not native implementation details or runtime behavior. ↩
Unity Scripting API, HDROutputSettings.paperWhiteNits — Unity 6.3. ↩
Unity Manual, Troubleshoot custom render passes with HDR output in URP. ↩
Unity Scripting API, HDROutputSettings.automaticHDRTonemapping — Unity 6.3. ↩
Unity Shader Graph 17.3 documentation, Saturate Node. ↩
Unity Shader Graph 17.3 documentation, Color Node. ↩
Unity Scripting API, GraphicsFormat. ↩
Unity Manual, Implement a custom HDR overlay in URP. ↩
Unity Scripting API, ImageConversion.EncodeToEXR. ↩
Unity Manual, HDR Output debug views in URP. ↩

6 Shader Graph Effects in Unity 6.3 You'll Want in Your Game

GameDevToolLab — Wed, 16 Sep 2026 06:36:06 +0000

Introduction

An enemy burns away. The edge where a shield meets the ground lights up. The scenery behind a heat source shimmers.

Effects like these start less with complex textures and more with deciding which input drives the effect, and which part of the object it changes.

In this article, we'll build six visually and technically different effects using URP and Shader Graph in Unity 6.3. The sample project is public and includes editable graphs and reusable prefabs. Here's a video showing all six effects:

Effect	What it looks like	Core idea
01 Emissive dissolve	An object disappears in patches, leaving a glowing edge	Threshold a noise pattern
02 Intersection shield	A glowing band appears where a shield intersects the ground or an obstacle	Use screen-space depth differences
03 Heat haze	The background behind a heat source shimmers	Offset the coordinates used to sample the background
04 Triplanar snow	Texture a rock without UV unwrapping and cover its upward-facing surfaces with snow	Use projection coordinates and surface orientation
05 Interactive grass	Grass bends in the wind and around an approaching character while its roots stay fixed	Displace vertices according to their height
06 Scan pulse	A glowing band travels continuously across floors, walls, and buildings	Use distance in world space

The graphs, materials, required meshes and textures, and control scripts are grouped under Runtime. Each effect has also been tested when imported into a separate project.

Open the sample project

Public repository / latest version · Pinned commit used for this article · Gallery scene · Validation record

Use Unity Hub to open the repository folder with Unity 6000.3.22f1. After package resolution and compilation finish, open Assets/ShaderGraphTechniques/Demo/Scenes/00_Gallery.unity and enter Play mode. Implementation links throughout this article point to the pinned commit.

The graphs, materials, prefabs, and control scripts for all six effects are under Assets/ShaderGraphTechniques/Runtime/. Each effect's GETTING_STARTED_JA.md lists its dependencies and setup requirements. Open the included .shadergraph in the Graph Editor to inspect the actual connections.

The video-selection and publication-status notes in the pinned commit are outdated. For the video, use the link at the beginning of this article.

Shared setup

Target environment

Unity 6.3 belongs to the 6000.3 release family. Its official manual links to the Shader Graph 17.3 package documentation for this generation of features. This article targets the tested combination of 6000.3.22f1 and URP / Shader Graph 17.3.0. This does not mean that all six effects became possible for the first time in Unity 6.3.¹

Setting	Assumption in this article
Editor	Unity 6.3 LTS / `6000.3.22f1`
Render pipeline	URP `17.3.0` / Shader Graph `17.3.0`
Renderer	Universal Renderer / Forward / standard Render Graph path
Color space	Linear
Camera	A single Base Camera; start with Perspective
Graph precision	Single as the baseline
Target renderer	A regular MeshRenderer; HDRP, Built-in, and the 2D Renderer are outside this article's scope
Capture environment	Windows 64-bit, NVIDIA GeForce RTX 3060 Laptop GPU, Direct3D 12

The sample includes ProjectSettings/ProjectVersion.txt, Packages/manifest.json, and Packages/packages-lock.json. Open it with this combination first rather than swapping in a different generation of URP or Shader Graph. When moving an effect into your own project, check the versions resolved by Package Manager there as well.

Distances and displacements in the sample scenes are tuned for 1 Unity unit = 1 m. Adjust distance-related properties when moving an effect into a game with a different scale.

These examples do not require a custom Renderer Feature or a hand-written shader implementation. Shader Graph handles the visuals; the runtime C# code handles parameter control, material ownership, and grass bounds.

Depth Texture and Opaque Texture are different settings

In the URP Asset, Depth Texture enables depth sampling, while Opaque Texture provides the background color after opaque objects have been rendered. The camera can override these settings.²

Effect	Depth Texture	Opaque Texture
Intersection shield	Required	Not required
Heat haze	Not required for the basic version	Required
Other effects	Not required for the effect's calculations	Not required

The sample enables both, but its project settings are not included in the exported packages. Enable only the settings needed by the effect in the destination project. Check not just Graphics settings, but also which URP Asset and Renderer the active Quality level and camera actually use.

For the heat-haze comparison, start with Opaque Downsampling = None. A downsampled background texture changes sharpness independently of the distortion itself.²

Adjust bright colors and Bloom separately

To create an emissive-looking area, feed bright values into Emission in a Lit Graph or Base Color in an Unlit Graph. Bloom is what makes that brightness spread into the surrounding image.³⁴⁵

When using Bloom, check the URP and camera HDR settings, the camera's Post Processing setting, the Global Volume and its Bloom override, and the relationship between the camera's Volume Mask and the Volume's Layer. Simply adding a Volume is not enough.⁶⁷

Make each effect readable without Bloom first, then add a subtle amount. The minimal comparison scenes use no Fog and do not require TAA, motion blur, or dynamic resolution.

Read the formulas as node connections

The text blocks below are compact descriptions of node connections, not HLSL you can paste and execute.

Saturate clamps a value to the 0–1 range. Step(edge, x) returns 0 when x < edge, and 1 otherwise. Smoothstep(a, b, x) smoothly transitions from 0 to 1 as x moves from a to b. Throughout this article, we keep a < b.⁸⁹

Pws means Position / World, and PosOS means Position / Object. Notation such as .xz means extracting the required components with Split and Combine, or with Swizzle. We use a consistent world-space coordinate system within URP.¹⁰¹¹

For each public property, set a clear display name and a Reference name matching the identifier used here, such as _Progress. In Shader Graph 17.3, the setting that exposes a property in the material Inspector is named Show In Inspector.¹²

In effects 01–04 and 06 at the pinned commit, Position / Object → Vertex / Position is explicitly connected even though those graphs do not deform vertices. The Windows StrictMode build passed with that connection in place, so use the same connection when building the graphs manually. The validation record explains the Motion Vector pass fix behind it.

Give animated effects a time input you can pause

In effects 03 and 05, t normally comes from the Time output of the Time node. The sample puts the following expression in Runtime/Common/ManualTime.shadersubgraph, allowing an effect to be frozen at a chosen time for capture or comparison.¹³

t = Lerp(Time.Time, _ManualTime, Saturate(_UseManualTime))

_UseManualTime is a Float in the 0–1 range, with a default of 0. _ManualTime is a Float measured in seconds, also defaulting to 0. The shared Sub Graph has explicit inputs and does not depend on a capture-only global variable. The property tables below are starting values for building the graphs manually; they are not values held constant throughout every frame of the video.

01 — Dissolve with a glowing edge

Watch this effect (0:03) · Implementation folder at the pinned commit

The graph is SG_01_Dissolve.shadergraph. Pass a value from 0 to 1 to the prefab's DissolveController.SetProgress(value) to control it. To use it on your own MeshRenderer with UV0, add MaterialInstanceOwner and DissolveController to the same GameObject.

This works well for enemy deaths, summoning, and item appearances. Instead of lowering the opacity of the entire object, it removes parts of the surface according to a noise pattern.

Graph settings and properties

Create a URP Lit Graph with Surface Type = Opaque and Alpha Clipping = On. Alpha Clipping discards pixels whose Alpha is below a threshold.³

Reference	Type and starting value	Purpose
`_Progress`	Float, 0–1; default 0	Fully visible at 0, fully removed at 1
`_NoiseScale`	Float, 8	Noise pattern density
`_EdgeWidth`	Float, 0.06	Width of the glowing band
`_BaseColor`	Color; your choice of surface color	Normal surface color
`_EdgeColor`	HDR Color; orange	Glow color
`_EdgeIntensity`	Float, 3	Glow intensity

Start with a Sphere or Capsule that has UV0. Because this version uses UVs, a mesh without UVs—or with heavily overlapping UVs—will not produce the intended pattern.

Core connections

Feed UV0's XY components and _NoiseScale into Simple Noise. Pass its output through Saturate and call the result m.¹⁴

p       = Saturate(_Progress)
w       = Max(_EdgeWidth, 0.0001)
m       = Saturate(SimpleNoise(UV0.xy, _NoiseScale))

cut     = Lerp(-w - 0.0001, 1.0001, p)
visible = Step(cut, m)
edge    = visible * (1 - Smoothstep(cut, cut + w, m))

Connect cut to the Edge input of Step, and m to In. The glowing band occupies a width of w on the surviving side of the boundary.

Simple Noise ── Saturate ──┬─ Step ─────────────── Alpha
                          │
                          └─ Smoothstep → One Minus
                                      × visible
                                      × HDR Color
                                      × Intensity ── Emission

Connect the Fragment outputs as follows:

Base Color           = _BaseColor.rgb
Emission             = _EdgeColor.rgb * _EdgeIntensity * edge
Alpha                = visible
Alpha Clip Threshold = 0.5
Metallic             = 0
Smoothness           = 0.35

Why extend the threshold slightly beyond the endpoints?

Using only Step(_Progress, m) leaves awkward endpoint behavior. In particular, a point where m = 1 can remain visible even at _Progress = 1.

Here, the threshold starts at -w - ε and ends at 1 + ε. With m constrained to 0–1, this guarantees no clipping or glowing edge at the start, and complete removal at the end. Those endpoints follow directly from the formula above. Progress is not, however, the percentage of surface area that has disappeared.

Integration notes

Clipping in this graph is a visual operation. Control Colliders and gameplay state separately. Check shadows with your actual lights and a Player build so that the object's shadow does not remain after its surface has disappeared.

If the glow clips to white, lower _EdgeIntensity first rather than changing Bloom, and inspect the shape of the boundary. This example is intended to work with Opaque + Alpha Clipping, not by switching to transparent blending to hide problems.

02 — A shield that glows where it intersects the environment

Watch this effect (0:13) · Implementation folder at the pinned commit

The graph is SG_02_IntersectionShield.shadergraph. It needs no dedicated runtime controller; adjust its exposed material properties. The video hides the two static blue comparison objects and shows the shield and moving pillar. Those comparison objects remain in the technical test scene, so its visible object count differs from the video's.

Place a transparent sphere so that the floor or a pillar intersects it. A glowing band around that intersection makes it look more like an energy field than a plain transparent sphere.

Graph settings and properties

Use a URP Unlit Graph with the following settings. Transparent blending, rendered faces, and depth writing are configured in the Graph Inspector.⁴

Surface Type  = Transparent
Blending Mode = Alpha
Render Face   = Front
Depth Write   = Force Disabled
Depth Test    = L Equal
Cast Shadows  = Off

Start with the camera outside the sphere. The basic version avoids double-sided rendering because it adds overlapping transparent front and back surfaces.

Reference	Type and starting value	Purpose
`_ContactWidth`	Float, 0.15	Depth-difference range that produces the glow
`_RimPower`	Float, 4	Rim sharpness
`_RimIntensity`	Float, 2	Rim brightness
`_ContactIntensity`	Float, 5	Intersection-band brightness
`_ShieldColor`	HDR Color; blue-green	Shield color
`_Opacity`	Float, 0–1; default 1	Visibility

Use the dedicated depth-difference node

Add Scene Depth Difference and set its Sampling Mode to Eye. Connect Screen Position / Default to Scene UV, and Position / World to Position WS.

This node returns the difference between the sampled scene depth and the depth of the supplied world-space position. Eye mode uses meters, and the result is negative when the sampled surface is closer to the camera.¹⁵

d       = SceneDepthDifference(Eye)
w       = Max(_ContactWidth, 0.0001)
contact = Step(0, d) * (1 - Saturate(d / w))

contact approaches 1 as the depths get closer and falls to 0 as they separate. This measures depth along the camera's viewing direction: it is not the shortest distance between objects or a Collider contact test. Changing the view changes the appearance of the band.

Add a Fresnel Effect node as well. Keep Normal and View Direction in the same World space, and pass _RimPower to Power. Call the output rim. Fresnel Effect emphasizes surfaces seen at a grazing angle.¹⁶

Base Color = _ShieldColor.rgb
             * (0.2 + rim * _RimIntensity
                    + contact * _ContactIntensity)

Alpha = Saturate((0.04 + 0.25 * rim + 0.8 * contact) * _Opacity)

What to check when the intersection does not glow

First, make sure Depth Texture is enabled for the active URP Asset and camera. Then give the intersecting floor or pillar an ordinary opaque material, such as URP/Lit.

This technique can only read surfaces present in the depth texture at that point in rendering. It does not detect intersections with every transparent object. Do not treat enabling Depth Write on the shield itself as a fix.

Also place an opaque box in front of the camera and check that it hides the shield behind it as usual. Changing the depth test to Always would turn this into a different, see-through effect.

03 — Heat haze that distorts the background

Watch this effect (0:23) · Implementation folder at the pinned commit

The graph is SG_03_HeatHaze.shadergraph. The prefab's HeatHazeController provides SetManualTime(seconds), UseRealtime(), and SetOpacity(0) for a frozen comparison, normal time, and hiding the effect.

This heat shimmer can be used above flames, exhaust vents, magic circles, or hot ground.

Rather than overlaying a semitransparent color, it resamples the background image at slightly offset coordinates to make the air appear to shimmer.

Graph settings and properties

Use a URP Unlit Graph with Transparent / Alpha, Depth Write = Force Disabled, Depth Test = L Equal, and Cast Shadows = Off. Start by applying it to a Quad whose front face points toward the camera.

Reference	Type and starting value	Purpose
`_NoiseScale`	Float, 6	Distortion pattern density
`_Distortion`	Float, 0.01	Distortion amount in normalized screen UVs
`_Opacity`	Float, 0–1; default 1	Blend amount for the distorted background
`_FlowA`	Vector2, (0.12, 0.20)	Motion of the first noise pattern
`_FlowB`	Vector2, (-0.18, 0.10)	Motion of the second noise pattern
`_ScreenEdgeFade`	Float, 0.04	Width over which distortion fades near screen edges

Also add the shared _UseManualTime and _ManualTime properties.

Use the Quad's UVs and screen UVs for different jobs

Build the distortion pattern from the Quad's UV0, but use the XY components of Screen Position / Default to sample the background. Default provides normalized 0–1 screen coordinates; it is not the same as Raw.¹⁷

u = UV0.xy
s = ScreenPosition(Default).xy

n1 = SimpleNoise(u * _NoiseScale + t * _FlowA, Scale = 1)
n2 = SimpleNoise(u * _NoiseScale + t * _FlowB + (19.7, 3.1), Scale = 1)
v  = 2 * Vector2(n1, n2) - Vector2(1, 1)

The two noise values form v, which supplies the two components of the background sampling offset.

Next, build a mask that softens the Quad's perimeter:

r        = Length(u * 2 - 1)
shape    = 1 - Smoothstep(0.65, 1, r)
edgeDist = Min(Min(s.x, 1 - s.x), Min(s.y, 1 - s.y))
screen   = Smoothstep(0, Max(_ScreenEdgeFade, 0.0001), edgeDist)

sampleUV = Clamp(s + v * _Distortion * shape * screen,
                 (0.001, 0.001), (0.999, 0.999))

shape hides the Quad's square boundary, and screen reduces distortion near the screen edges. The Clamp limits are fixed margins for this basic version, not an exact half-texel correction.

Pass sampleUV into the XY components of the Scene Color UV input, and use the output directly as the color. If you construct a Vector4, set the unused ZW components to 0.

Base Color = SceneColor(sampleUV)
Alpha      = shape * Saturate(_Opacity)

Do not multiply RGB by Alpha beforehand; let Alpha blending perform the compositing. This example also does not multiply Scene Color by an HDR intensity to make it glow.

There are limits to the background this method can read

In URP, Scene Color reads the Opaque Texture copied before transparent objects are rendered. Use it in the Fragment stage. It is not a way to freely distort the entire rendered frame, including glass and particles.¹⁸

As a result, overlapping transparent objects or multiple heat-haze surfaces can look as though they overwrite transparent effects drawn earlier. Changing draw order cannot recover information absent from the background copy.

Because this only offsets screen-space sample positions, it can also pull in colors from other objects near foreground silhouettes. Screen-edge fading and Clamp do not solve every silhouette artifact.

Evaluate the basic version without Fog, against an opaque background, using a single Quad. To compare with the effect disabled, use _Opacity = 0 or disable the Renderer. Setting distortion to 0 does not stop the shader from drawing the background copy.

04 — Triplanar rocks with snow on upward-facing surfaces

Watch this effect (0:33) · Implementation folder at the pinned commit

The graph is SG_04_TriplanarSnow.shadergraph. It needs no dedicated runtime controller. Adjust _SnowAmount on the material, and try replacing the included rock texture with your own.

This effect textures rocks and cliffs without well-organized UVs, then spreads snow across them. Changing the snow color to green or dark brown also makes it useful for moss or dirt coverage.

Graph settings and properties

Use a URP Lit Graph with Surface Type = Opaque and Alpha Clipping = Off.

Reference	Type and starting value	Purpose
`_BaseMap`	Texture2D	A tileable rock color texture
`_BaseTint`	Color; white	Rock color tint
`_TextureScale`	Float, 1	Texture density in world space
`_SnowAmount`	Float, 0–1; default 0.5	Snow coverage
`_SnowColor`	Color; slightly blue-tinted white	Snow color
`_SnowNoiseScale`	Float, 1.5	Coverage pattern density
`_SnowSoftness`	Float, 0.12	Softness of the snow boundary

Import _BaseMap as a color texture with sRGB enabled, Wrap Mode set to Repeat, and Mip Maps enabled.¹⁹ The sample includes a custom, pre-generated texture named TEX_SeamlessRock.png.

Texture the rock with Triplanar

Set the Triplanar node's Type to Default and Input Space to World. Connect _BaseMap to Texture and _TextureScale to Tile, and start with Blend at 4. Keep Position and Normal in World space as well.

Triplanar projects a texture from three directions and blends the results according to surface orientation. It samples the input texture three times, so its cost is not the same as a single ordinary texture lookup. Use this node in the Fragment stage.²⁰

rock = Triplanar(_BaseMap,
                 Position = Pws,
                 Normal   = Normalize(NormalVector(World)),
                 Tile     = _TextureScale,
                 Blend    = 4).rgb * _BaseTint.rgb

Multiply upward-facing slope by coverage

Use Normal Vector / World for surface orientation. Take its Dot Product with (0, 1, 0) to measure how much it faces upward.²¹

up    = Dot(Normalize(NormalVector(World)), (0, 1, 0))
slope = Smoothstep(0.35, 0.85, up)

n     = Saturate(SimpleNoise(Pws.xz, _SnowNoiseScale))
a     = Saturate(_SnowAmount)
s     = Max(_SnowSoftness, 0.0001)
cut   = Lerp(1 + s + 0.0001, -s - 0.0001, a)
cover = Smoothstep(cut - s, cut + s, n)
snow  = slope * cover

slope limits which surfaces can receive snow, and the noise-based cover fills those surfaces. With this formula, Snow Amount 0 means no snow; at 1, coverage reaches the limit allowed by slope. Even at 1, vertical walls do not turn completely white.

Base Color = Lerp(rock, _SnowColor.rgb, snow)
Smoothness = Lerp(0.2, 0.35, snow)
Metallic   = 0

This is the appearance of snow, not a volume simulation

The basic version changes color and surface appearance only. It does not thicken the silhouette with snow or detect areas sheltered by a roof. An upward-facing surface can receive snow even indoors.

Because the projection is in world space, moving the object changes its position relative to the pattern. This makes the setup suitable for stationary rocks and buildings. For a moving prop that needs the pattern to stay attached, redesign the projection coordinates in Object space. The normal test that restricts snow to upward-facing surfaces can still remain in World space.

“No UVs required” does not mean “no inputs or conditions required.” The texture's Repeat setting, the normals, and the projection space are part of this effect's input requirements.

05 — Grass that bends around an approaching character

Watch this effect (0:43) · Implementation folder at the pinned commit

The graph is SG_05_InteractiveGrass.shadergraph. Assign the target Transform to the prefab's InteractiveGrassController.Interactor. Use SetBend(radius, strength) to adjust interaction bending, SetManualTime(seconds) for a frozen comparison, and UseRealtime() to return to normal time.

This adds bending around an approaching character to grass that already sways in the wind.

The central idea is to keep root vertices fixed and increase displacement toward each blade's tip. This changes the Vertex stage rather than just the surface color.

Define the mesh requirements first

In the basic version, narrow polygons form the grass silhouette. No grass image is used for Alpha Clipping.

Make each blade a tapered strip with roughly six subdivisions along its height. Set UV0's Y component to 0 at the root and 1 at the tip. Even when multiple blades share one mesh, each blade needs its own 0–1 range in UV0.Y.

A single unsubdivided Quad cannot form a curve along its length. The sample's MESH_GrassCluster.asset is already generated, with six vertical subdivisions per blade. You do not need to run a generation script in the destination project.

Graph settings and properties

Use a URP Unlit Graph with Opaque, Alpha Clipping = Off, and Render Face = Both. Because this basic version does not calculate lighting, we can leave reconstructing deformed normals out of the example.⁴

Reference	Type and starting value	Purpose
`_InteractorPositionWS`	Vector3, (0, 0, 0)	World position of the object pushing the grass aside
`_InteractorEnabled`	Float, 0–1; default 0	Stops proximity-based bending at 0
`_BendRadius`	Float, 1	Horizontal interaction radius
`_BendStrength`	Float, 0.6	Interaction displacement
`_WindDirectionXZ`	Vector2, (1, 0)	Wind direction
`_WindStrength`	Float, 0.08	Wind displacement
`_WindSpeed`	Float, 1.5	Wind animation speed
`_RootColor`	Color; dark green	Root color
`_TipColor`	Color; light green	Tip color

Also add the shared manual-time properties. Distances and displacements are tuned for the sample scenes' 1 Unity unit = 1 m scale.

Build the vertex displacement

Here, Pws is the undeformed Position / World, evaluated in the Vertex stage.

h       = Saturate(UV0.y)
rootMask = h * h

q       = Pws.xz - _InteractorPositionWS.xz
d       = Length(q)
outward = q / Max(d, 0.0001)
radius  = Max(_BendRadius, 0.0001)
weight  = (1 - Smoothstep(0, radius, d)) * Saturate(_InteractorEnabled)

windDir = _WindDirectionXZ / Max(Length(_WindDirectionXZ), 0.0001)
phase   = Pws.x * 0.7 + Pws.z * 0.9 + t * _WindSpeed
wind    = windDir * Sin(phase) * _WindStrength

moveXZ  = (outward * weight * _BendStrength + wind) * rootMask
movedWS = Pws + Vector3(moveXZ.x, 0, moveXZ.y)

At the root, h * h is 0, so the vertices stay fixed. Displacement increases toward the tip. The formula avoids division by zero even when a vertex lies exactly at the interaction center and d = 0. At that point, the outward direction is zero and only wind contributes to displacement.

Finally, pass movedWS through Transform / World → Object / Type = Position and connect the result to the Vertex Position input.

Position(World) → Add displacement
                → Transform(World → Object, Position)
                → Vertex / Position

The Vertex Position input expects Object space. Do not connect a World-space position directly. The Transform node's Position type includes translation, unlike Direction.³¹¹

For the Fragment color, start with a simple root-to-tip gradient:

Base Color = Lerp(_RootColor.rgb, _TipColor.rgb, Saturate(UV0.y))

The game supplies the interactor's position

On the C# side, pass the target Transform's world position to _InteractorPositionWS, and set _InteractorEnabled = 1 only while the target is valid. If it is unassigned or has been destroyed, return the value to 0 so that the grass does not react to a nonexistent character at the origin.

This basic version reacts only to horizontal distance. A character on a bridge at a different height can therefore affect grass below. For multilevel environments, add a height condition or separate the affected grass into groups. This is not physical collision, persistent footprints, or a simulation that preserves blade length.

Without correct bounds, grass can disappear at the screen edges

When a shader moves vertices, the bounds used for culling must contain the deformed geometry. Unity's Renderer.localBounds can be overridden for this purpose. However, that override is not saved into the Scene or Prefab, so it must be applied again at runtime.²²

The sample's InteractiveGrassController reapplies bounds when enabled and when SetBend is called. Its margin comes from boundsPadding—default 0.9—not from automatically estimating the deformation. Review that margin when increasing bend or wind strength, and reapply the bounds if scale changes at runtime. The bounds must cover the maximum displacement; the Collider is not updated.

Do not make Static Batching or Dynamic Batching a prerequisite for the first test. In particular, vertex processing that converts back to Object space needs separate checks to ensure batching does not change its coordinate assumptions. Both Static and Dynamic Batching involve combining vertices in world space.²³

06 — A scan pulse that travels across buildings and terrain

Watch this effect (0:53) · Implementation folder at the pinned commit

The graph is SG_06_ScanPulse.shadergraph. The prefab's ScanPulseController provides SetCenter(transform) and SetState(active, radius). When no center is assigned, it uses the component's own position.

This works for exploration scans, sonar, or magical detection. The same wave should travel across walls and steps as well as the floor.

The basic version is not a post-processing effect: the scan pulse is drawn inside the affected materials.

Graph settings and properties

Use a URP Lit Graph with Opaque and Alpha Clipping = Off.

Reference	Type and starting value	Purpose
`_ScanCenterWS`	Vector3, (0, 0, 0)	Wave center
`_ScanRadius`	Float, 0	Current radius
`_ScanWidth`	Float, 0.25	Half-width of the glowing band
`_ScanActive`	Float, 0–1; default 0	Whether the wave is visible
`_ScanColor`	HDR Color; blue-green	Wave color
`_ScanIntensity`	Float, 3	Wave brightness
`_BaseColor`	Color; gray	Normal surface color

Light up the area close to a spherical shell

In the Fragment stage, calculate the distance between Position / World and _ScanCenterWS.¹⁰

distanceToCenter = Distance(Pws, _ScanCenterWS)
radius           = Max(_ScanRadius, 0)
width            = Max(_ScanWidth, 0.0001)

distanceToShell  = Abs(distanceToCenter - radius)
ring             = (1 - Smoothstep(0, width, distanceToShell))
                   * Saturate(_ScanActive)

The glow is brightest on the sphere where distanceToCenter = radius, then fades inward and outward. Because _ScanWidth applies on both sides of the sphere, the full band with a nonzero value is approximately twice that width.

Base Color = _BaseColor.rgb
Emission   = _ScanColor.rgb * _ScanIntensity * ring
Metallic   = 0
Smoothness = 0.25

Increasing _ScanRadius moves the glowing band through the intersections between that sphere and the floor, walls, and buildings. This uses XYZ distance, not just XZ distance, so it is not the same calculation as projecting a flat circle from the floor onto a wall.

Send the same wave parameters to multiple objects

Give every participating Renderer the same center, radius, and width. If the wave lines up where it crosses from the floor to a wall, the coordinate spaces are consistent.

For a repeating pulse, set _ScanActive = 0 before resetting the radius to 0 to avoid an unwanted flash at the center. To run two independent waves simultaneously, separate the ownership of the materials they control as well.

Do not describe this as affecting the entire scene

Materials that do not use this graph will not show the pulse. To add it to an existing, more complex Lit Graph, move the distance-to-ring calculation into a Sub Graph and add its result to the existing Emission.

The effect also uses normal depth testing, so it does not reveal objects behind a wall. A full-screen scan or detection display through occluders requires a different rendering design.

Moving the effects into another project

Keep Runtime separate from Demo

The dependency direction is Demo → Runtime. Runtime prefabs contain no Camera, Light, Volume, Canvas, or Demo Manager, and they do not require the Gallery. That does not mean the destination scene needs no camera or lighting; it means you do not have to bring along the demonstration setup.

The reusable parts are the graph, its referenced Sub Graphs, materials, required textures and meshes, and runtime controllers only where needed. The prefabs bundle these into configured objects. Each package also includes a setup guide and a LICENSE file inside Assets.

Do not copy .shadergraph or .mat files arbitrarily through a file explorer. Transfer them in a way that preserves references and .meta files.²⁴ The sample's Package Exporter gathers dependencies, excludes other effects, Demo, Tests, Editor, and ProjectSettings, and passes the resulting set to Unity's Export Package API. Including the required dependencies is not the same as exporting the entire project.²⁵

Effect	What to bring for the visual effect	Destination requirements
Dissolve	Graph and material; control code for automated playback	A mesh with UV0
Intersection shield	Graph, material, and a mesh such as a sphere	Depth Texture and an opaque intersection target
Heat haze	Graph, time Sub Graph, material, and Quad	Opaque Texture; an opaque background for the basic version
Snow	Graph, material, and rock texture	Valid normals, projection coordinates, and Repeat settings
Grass	Graph, time Sub Graph, material, dedicated mesh, and position/bounds control	Root mask in UV0.Y and a target Transform
Scan pulse	Graph and material; control code for automated playback	Consistent parameters on every participating object

Generate packages locally, then import them

The six individual packages and ShaderGraphTechniques-Runtime-All.unitypackage have already been generated, inspected, and tested through isolated imports. However, the generated archives are excluded from Git. Open the original sample project and run Tools > Shader Graph Techniques > Export Runtime Packages to generate them locally under Artifacts/Packages/. The distribution and migration record lists package names and inspection results.

Prepare a new URP project in Unity 6000.3.22f1 and confirm that URP / Shader Graph resolve to 17.3.0. Use Unity's Assets > Import Package > Custom Package... to import just the .unitypackage for the effect you need.²⁶ Enable Depth Texture for effect 02 or Opaque Texture for effect 03 in the destination project, then place the corresponding PF_*.prefab in the scene or assign MAT_*.mat to your Renderer.

Individual packages include the Common files they need. When you import another effect later, shared assets retain the same original GUIDs. You do not need to copy the entire Runtime folder separately.

Share materials deliberately

When two prefabs are in a scene, changing the Progress of one should not unexpectedly make the other disappear.

In effects 01, 03, 05, and 06, MaterialInstanceOwner creates an instance for each Renderer material slot and reuses it while initialized. On disable, it restores the original references and destroys only the instances it created. It does not modify shared material assets or global shader values.

For effects 02 and 04, adjusting a material in its Inspector affects every object sharing that material. To control these independently per prefab, use separate material assets or instances with explicit ownership and cleanup. Distinguish changing a shared material asset from changing one placed object.

MaterialPropertyBlock is not an automatic optimization. Unity's API documentation explicitly states that it is incompatible with the SRP Batcher. Evaluate ease of per-object control separately from CPU rendering cost.²⁷

Isolated imports were tested in seven independent projects

The six individual packages and Runtime-All were imported separately into seven independent, newly created URP projects, without copying the original project's Assets or Library directories. All seven imports passed (7/7).

Without the Gallery or demo Manager, the tests checked prefabs, graphs, supported shaders, and actual Unity renders of states A/B controlled through the APIs or public material values, image differences, zero missing scripts, and no magenta fallback. In the Runtime-All project, all six effects were rendered individually. The package archives themselves were also checked against the manifest for every pathname, GUID, and asset SHA-256, with 7/7 content checks passing. These results are documented in the validation record and distribution and migration record.

Separately, a fresh clone was reimported without a Library directory. Package resolution for all 57 packages and script compilation succeeded, followed by EditMode 9/9 and GPU-rendered PlayMode 4/4. Attempts that failed to render with Null Graphics are not counted as successful results.

What remains untested

The tested GPU and Graphics API are the RTX 3060 Laptop GPU and Direct3D 12 listed earlier. XR, mobile, macOS / Linux, other GPUs, Direct3D 11 / Vulkan / Metal, and real-time 60 fps performance remain untested. Multiple cameras, Camera Stacks, Fog, Heat Haze compositing with transparent objects, and long-running integration into a real game are also untested. Zero, negative, and mirrored scales are outside the supported scope. Successful isolated imports do not guarantee support across all those environments.

Measure rendering cost with the target GPU, resolution, Graphics API, and number of visible instances held consistent. Do not call an effect lightweight just because it has few nodes. Background copies, depth sampling, overlapping transparent surfaces, and Triplanar's multiple texture samples are different sources of cost.

Conclusion

Rather than remembering these as six unrelated tricks, focus on the inputs they use.

Dissolve and snow turn values into regions to reveal or cover. The shield and heat haze read screen information from the camera. Grass and the scan pulse use positions and distances to drive their changes.

In the fixed environment, the sample passed EditMode 9/9, PlayMode 4/4, a Windows StrictMode build with 0 errors / 0 warnings, and package-content and isolated-import checks at 7/7 each. Both test suites also passed on a fresh clone. Use the pinned commit to follow along with the video and implementation.

Can you explain the inputs and assumptions when the effect moves to a different mesh, position, or project? Getting that right is what makes a Shader Graph easier to bring into your own game. Just do not confuse a recording at 60 fps with real-time performance—measure in your game's actual target environment.

Unity documentation: New in Unity 6.3. Revisited September 14, 2026. ↩
Unity documentation: Universal Render Pipeline asset reference for URP. Depth Texture, Opaque Texture, Opaque Downsampling, and related settings. ↩
Unity documentation: Lit shader graph reference for URP. Vertex/Fragment inputs and graph settings. ↩
Unity documentation: Unlit shader graph reference for URP. Transparent blending, Render Face, Depth Write/Test, and related settings. ↩
Unity documentation: Bloom in URP. ↩
Unity documentation: Camera component reference for URP. Camera Post Processing and Volume-related settings. ↩
Unity documentation: Post-processing in URP. ↩
Unity documentation: Step Node / Shader Graph 17.3. ↩
Unity documentation: Smoothstep Node / Shader Graph 17.3. ↩
Unity documentation: Position Node / Shader Graph 17.3. ↩
Unity documentation: Transform Node / Shader Graph 17.3. Coordinate spaces and the differences between Position, Direction, and Normal. ↩
Unity documentation: Property Types / Shader Graph 17.3. Reference, Show In Inspector, and related settings. ↩
Unity documentation: Time Node / Shader Graph 17.3. ↩
Unity documentation: Simple Noise Node / Shader Graph 17.3. ↩
Unity documentation: Scene Depth Difference node / Shader Graph 17.3. Eye mode, input coordinates, and the sign of the difference. ↩
Unity documentation: Fresnel Effect Node / Shader Graph 17.3. ↩
Unity documentation: Screen Position Node / Shader Graph 17.3. ↩
Unity documentation: Scene Color node / Shader Graph 17.3. Opaque Texture, shader stage, and draw-order requirements. ↩
Unity documentation: Default texture type reference. sRGB, Mip Maps, and Wrap Mode. ↩
Unity documentation: Triplanar Node / Shader Graph 17.3. Three-direction projection, three texture samples, and Input Space. ↩
Unity documentation: Normal Vector Node / Shader Graph 17.3. ↩
Unity documentation: Renderer.localBounds / Unity 6.3. Bounds for shader deformation and persistence limitations. ↩
Unity documentation: Introduction to batching meshes. Static/Dynamic Batching and world space. ↩
Unity documentation: Asset metadata. Asset identifiers, import settings, and preserving .meta files. ↩
Unity documentation: Create asset packages and AssetDatabase.ExportPackage. ↩
Unity documentation: Import local asset packages. Importing through Assets > Import Package > Custom Package. ↩
Unity documentation: MaterialPropertyBlock / Unity 6.3. The SRP Batcher compatibility warning. ↩

12 Practical Unity 2D Shader Graph Effects (with a Sample Project)

GameDevToolLab — Tue, 15 Sep 2026 04:37:53 +0000

You can transform the look of a Unity 2D game with shaders without redrawing the original artwork. Hit flashes, dissolves, color variants, glitches, holograms, the illusion of surface depth, and world-space scans all come down to manipulating UVs, color, alpha, and coordinates.

The implementation has its traps: packing a sprite into an Atlas changes the density of a pattern, an outline samples a neighboring sprite, moving vertices does not produce a smooth bend, or 2D lighting suddenly becomes expensive. This article covers 12 techniques together with ways to avoid those problems.

Watch the effects in motion

There is a demonstration video for the 2D shader effects in this article. Still images do not communicate timing and deformation particularly well, so start with the video to see the intended results, then jump to the implementation that interests you.

Use the video to inspect the appearance and motion. Use the article for coordinate choices, Sprite Atlas precautions, Shader Graph construction, and performance considerations.

Using the sample project

GitHub sample project (inspected commit c12a8ab)

The distributed project uses Unity 6000.5.11f1 and URP / Shader Graph 17.5.0. Keep it separate from the build-it-yourself recipes below, which target Unity 6.4 / Shader Graph 17.4. Compatibility of the distributed graphs with older versions has not been verified.

File locations and running the demos

Combine the filename in each technique with the corresponding folder below to get its full path. All paths are relative to the repository root.

Label in each technique	Folder	Purpose
Graph	`Assets/ShaderCapture/Shaders/Graphs/`	Edit the shader nodes
Material	`Assets/ShaderCapture/Materials/`	Duplicate and assign to a SpriteRenderer
Scene	`Assets/Scenes/`	Inspect the complete setup
Art	`Assets/ShaderCapture/Art/Generated/`	Images and sprite geometry
Runtime	`Assets/ShaderCapture/Scripts/Runtime/`	Control components

Open the complete project through Unity Hub, then open Assets/Scenes/00_CaptureHub.unity or the Scene listed for a technique and enter Play Mode. Space plays or pauses, the left and right arrow keys adjust the effect amount, and R resets the demo. The Scene files are already stored in the locations above; you do not need to run the generation menu commands.

Shared controls and requirements for reuse

Start with DemoCharacter.png in the Art folder. Copying a Material does not copy the demo controls. In a different Scene, add EffectDemoController.cs from Runtime to an empty GameObject. Assign the Art files Noise.png, DemoCharacter_Index.png, and Palette.png to Noise Texture, Index Texture, and Palette Texture, respectively. This controller supplies _SC_Effect, _SC_DemoTime, colors, textures, and other global shader values. It requires the Input System. Scene navigation uses the original build-index order. Avoid multiple controllers overwriting the same global values.

The per-renderer settings mentioned in each technique are Inspector fields on ShaderCapturePropertyBlock.cs, also in Runtime. Attach it to the target Renderer. It does not supply the shared global values. The recipe properties _Effect and _ScanCenter are different names from the sample properties _SC_Effect and _SC_ScanCenter; the controllers shown in the article cannot be used with the sample graphs unchanged.

When moving an effect to another project, copy the Graph, Material, technique-specific dependencies, and shared controls, including their .meta files. Do not rely on Export Assets to discover textures assigned through global properties. When changing the artwork, update _SC_SpriteSize, which is fixed at 2.56, and _SC_TexelSize, which is derived from the Index Texture. The distributed graphs have Use TexelSize disabled and use this separate value instead; do not overwrite their settings with the build-it-yourself Property table below. They do not automatically adapt to arbitrary pivots or Atlas layouts, so first check them outside an Atlas.

The sample-file guidance is based on source inspection at the pinned commit. Launching the project, compiling it in Unity, and testing an actual transfer to another project were not performed for this edition.

Target environment for the recipes

Read the node, formula, and custom C# explanations below separately from the ready-made sample project above.

The recipes target this configuration:

Unity 6.4
Universal Render Pipeline (URP)
2D Renderer
Shader Graph 17.4
SpriteRenderer

Use a Sprite Lit Shader Graph for effects that respond to 2D lights. The other effects generally use a Sprite Unlit Shader Graph. The Built-in Render Pipeline has different targets and lighting behavior, so these recipes target URP.

Start with three kinds of coordinates

Many 2D shader problems begin with the choice of coordinates.

Coordinates	Use cases	Behavior
Texture UV	Original image, outlines, RGB offsets	Refers to the packed region when using an Atlas
Object Position	Per-sprite dissolves, wind, local scan lines	Independent of the Atlas
World / Screen Position	Waves crossing multiple objects, screen-fixed dithering	The pattern does not stick to the object

Sprite Atlas UVs are not necessarily local 0–1 coordinates

A sprite packed into a Sprite Atlas has UVs that refer to positions in the entire Atlas. Feeding those UVs into sin(UV.x * Frequency) or floor(UV * Divisions) changes the density of stripes or waves when the sprite is packed.

Separate the responsibilities:

Sample the original image with the unmodified Texture UV.
Generate patterns with 0–1 coordinates derived from Object Position.
Specify Texture UV offsets in units such as “2 texels,” not an arbitrary value such as “0.01.”
Increase Atlas Padding for effects with large UV offsets, or keep those sprites out of the Atlas.

Do not use one coordinate stream for both pattern generation and image sampling.

Atlas-independent local 0–1 coordinates

For a SpriteRenderer using the Simple draw mode, derive local coordinates as follows:

local01 = Position(Object).xy / SpriteSize + Pivot01

SpriteSize is the sprite's width and height in local units. Pivot01 is its pivot normalized within the Rect; a centered pivot is (0.5, 0.5). This component supplies those values:

using UnityEngine;

[RequireComponent(typeof(SpriteRenderer))]
public sealed class SpriteShaderDriver : MonoBehaviour
{
    static readonly int SizeId = Shader.PropertyToID("_SpriteSize");
    static readonly int PivotId = Shader.PropertyToID("_Pivot01");
    static readonly int EffectId = Shader.PropertyToID("_Effect");
    static readonly int SeedId = Shader.PropertyToID("_Seed");

    [SerializeField, Range(0f, 1f)] float effect;
    [SerializeField] float seed;

    readonly MaterialPropertyBlock block = new MaterialPropertyBlock();
    SpriteRenderer target;
    Sprite cachedSprite;

    bool EnsureTarget()
    {
        if (target != null) return true;
        target = GetComponent<SpriteRenderer>();
        return target != null;
    }

    void Awake()
    {
        if (EnsureTarget()) Apply();
    }

    void LateUpdate()
    {
        if (!EnsureTarget()) return;
        if (target.sprite != cachedSprite) Apply();
    }

    public void SetEffect(float value)
    {
        effect = Mathf.Clamp01(value);
        if (!EnsureTarget()) return;
        target.GetPropertyBlock(block);
        block.SetFloat(EffectId, effect);
        target.SetPropertyBlock(block);
    }

    void Apply()
    {
        if (!EnsureTarget()) return;
        Sprite sprite = target.sprite;
        cachedSprite = sprite; // Cache null too, avoiding reapplication every frame.
        if (sprite == null) return;

        // Rect-based 0-1 coordinates. Do not mix these with Tight Mesh bounds.
        Vector2 size = sprite.rect.size / sprite.pixelsPerUnit;
        Vector2 pivot = new Vector2(
            sprite.pivot.x / sprite.rect.width,
            sprite.pivot.y / sprite.rect.height);

        target.GetPropertyBlock(block);
        block.SetVector(SizeId, new Vector4(size.x, size.y, 0f, 0f));
        block.SetVector(PivotId, new Vector4(pivot.x, pivot.y, 0f, 0f));
        block.SetFloat(EffectId, effect);
        block.SetFloat(SeedId, seed);
        target.SetPropertyBlock(block);
    }
}

In Shader Graph, Divide Object-space Position.xy by _SpriteSize, then Add _Pivot01. _SpriteSize is sprite.rect.size / sprite.pixelsPerUnit. With either a centered or off-center pivot, the Rect's bottom-left maps to 0 and its top-right maps to 1. An asymmetric Tight Mesh occupies only part of that 0–1 range, but the definition of the Rect coordinates does not change.

To normalize the visible Tight bounds instead, use a separate approach: supply both bounds.min and bounds.size, then calculate (Position - BoundsMin) / BoundsSize. Do not mix that approach with the pivot-based formula. For Sliced, Tiled, Sprite Skin, or configurations that make frequent use of Flip, check that the Renderer's actual mesh matches the local coordinates you expect.

MaterialPropertyBlock supplies per-renderer values, but removes SRP Batcher compatibility. It is convenient for a small number of individual settings. When setting values on many sprites every frame, compare it with shared Materials and global properties, and measure on the target device.

Build a common base graph

Before implementing the techniques, build the shared portion in a Sprite Unlit Shader Graph. These are the Properties for the Shader Graph 17.4 recipes:

Property	Type	Reference	Scope	Supply / attribute	Settings
Main Texture	Texture 2D	`_MainTex`	Per Material	Read Only ON (`PerRendererData`)	Set as Main Texture ON / Use TexelSize ON
Mask Texture	Texture 2D	`_MaskTex`	Per Material	Read Only ON (`PerRendererData`)	Match the Secondary Texture name
Normal Map	Texture 2D	`_NormalMap`	Per Material	Read Only ON (`PerRendererData`)	Mode: Normal Map / Fallback: Flat Normal
Sprite Size	Vector 2	`_SpriteSize`	Per Material	Override per Renderer with an MPB	Rect size in Object Space
Pivot 01	Vector 2	`_Pivot01`	Per Material	Override per Renderer with an MPB	Pivot within the Rect
Effect	Float	`_Effect`	Per Material	Override per Renderer with an MPB	0–1
Seed	Float	`_Seed`	Per Material	Override per Renderer with an MPB	Per-object variation

The three Texture Properties use Per Material, an actual Scope option in the Shader Graph 17.4 UI. Per Renderer Data is not a Scope option. Enabling Read Only adds the PerRendererData attribute so that SpriteRenderer can supply textures per renderer. The Normal Map fallback is Flat Normal. An Unlit Graph that does not use Secondary Textures does not need _MaskTex or _NormalMap.

Create a Texture 2D Property with Reference _MainTex and mark it as the Main Texture.
Read the original image with Sample Texture 2D.
Connect RGB to the Fragment Base Color.
Connect A to the Fragment Alpha.
Use Alpha as the starting Blending Mode in the Graph Inspector for an ordinary sprite.
Leave Disable Color Tint off when using SpriteRenderer.color.

From here on, baseRGBA means the original image's RGBA, textureUV means the UV used to sample that image, and local01 means 0–1 coordinates derived from Object Position.

Processing RGB in transparent regions before ordinary alpha blending can produce dark or light fringes. As a rule, multiply the final alpha by baseRGBA.a. If the edges of a transparent PNG are dirty, also inspect Alpha Is Transparency in the Import Settings, Sprite Atlas Padding, and the compression format.

Technique 1: Hit flashes and invincibility blinking

▶ Watch this effect (from 0:06)

Sample files (use the folders listed at the beginning)

Graph: Effect01_HitFlashInvincible.shadergraph

Material: Effect01.mat / Scene: 01_HitFlashInvincible.unity

Use the per-renderer Seed Offset setting to vary the blinking phase. The Bloom file is Assets/ShaderCapture/Settings/ShaderCaptureVolumeProfile.asset. In the inspected version, its saved component reference is empty (fileID: 0), so copying it alone does not reproduce Bloom. Configure the following:

Create and assign a new Profile to a Global Volume with Weight set to 1, then add Add Override > Post-processing > Bloom. Match the generation code with Threshold = 0.75, Intensity = 0.65, and Scatter = 0.62. Enable Bloom and the override checkbox for each setting.
On the Camera used for rendering, enable Rendering > Post Processing and include the Volume GameObject's Layer in Volume Mask. HDR shader colors alone do not create a glow outside the sprite's silhouette.

See the URP post-processing setup guide for the configuration requirements.

A simple Lerp between the original color and a flash color makes a hit much easier to read.

outRGB = Lerp(baseRGBA.rgb, FlashColor.rgb, FlashAmount)
outAlpha = baseRGBA.a

Add _FlashColor, _FlashAmount, and optionally _FlashPower. For an emissive look, add an HDR color:

outRGB = baseRGBA.rgb
       + FlashColor.rgb * FlashAmount * FlashPower

When using Bloom, reserve high brightness for meaningful moments, such as an attack telegraph.

For invincibility blinking, generate a square wave from Time:

blink = Step(0.5, Fraction(Time * BlinkSpeed + Seed))
outAlpha = baseRGBA.a * Lerp(1, blink, Invincible)

Change Seed per Renderer to avoid perfectly synchronized blinking. Combine the blinking with color or rim effects to communicate the state even during the invisible part of the cycle.

Technique 2: Palette swapping for character color variants

▶ Watch this effect (from 0:13)

Sample files (use the folders listed at the beginning)

Graph: Effect02_PaletteSwap.shadergraph

Material: Effect02.mat / Scene: 02_PaletteSwap.unity

This sample needs DemoCharacter_Index.png and Palette.png from Art. Its palette has four columns and four rows: the Index Map's R channel stores the color ID, G stores shading, and _SC_PaletteRow selects row 0–3. Different artwork needs a corresponding Index Map.

The Hue node can rotate the hue, but use an Index Map and a Palette Texture when skin, clothing, metal, and eyes need independent color changes.

Main Texture: the visible sprite.
Index Map: the color-group number for each pixel.
Palette Texture: a small texture containing replacement colors in a horizontal row.

encoded = Sample(IndexMap, textureUV).r
id = round(encoded * (PaletteCount - 1))
paletteUV = float2((id + 0.5) / PaletteCount, 0.5)
paletteRGB = Sample(PaletteTexture, paletteUV).rgb

outRGB = paletteRGB
outAlpha = baseRGBA.a

To preserve shading, store brightness in the Index Map's G channel:

outRGB = paletteRGB * Lerp(Shadow, Highlight, indexMap.g)

Normalize the region IDs 0–PaletteCount - 1 into the R channel's 0–1 range. G can hold shading and B an emission mask. Disable sRGB for the Index Map, use Point filtering, and disable compression and mipmaps when needed. Set the Palette Texture to Point filtering and Clamp wrapping as well.

When the Main Texture is packed into an Atlas, the Index Map must be sampled with a matching layout. Associate it as a Secondary Texture, or supply a separate UV Rect for the Index Map. Sampling a non-atlased Index Map directly with Atlas UVs does not work.

Replace Color is sufficient for a one-off effect, but Index Maps are easier to manage for a large set of assets containing anti-aliasing and shading.

Technique 3: Dissolves for burning, freezing, and digitizing

▶ Watch this effect (from 0:20)

Sample files (use the folders listed at the beginning)

Graph: Effect03_Dissolve.shadergraph

Material: Effect03.mat / Scene: 03_Dissolve.unity

The sample uses Noise.png from Art. The per-renderer Dissolve Softness setting controls the boundary. Set Dissolve Invert to 0 for disappearing or 1 for appearing. All four comparison views use the same Graph.

A dissolve compares a noise value with the effect's progress and removes alpha accordingly. Split it into three regions—Body, Edge, and Hidden—to make the result easier to control.

threshold = Lerp(-EdgeWidth, 1 + EdgeWidth, Dissolve)
visible = Step(threshold, noise)
body = Step(threshold + EdgeWidth, noise)
edge = Max(visible - body, 0)

// At 0: fully visible, no Edge. At 1: fully hidden.
start = 1 - Step(0.000001, Dissolve)
finish = Step(0.999999, Dissolve)
visible = Lerp(visible, 1, start) * (1 - finish)
body = Lerp(body, 1, start) * (1 - finish)
edge = edge * (1 - start) * (1 - finish)

outRGB = baseRGBA.rgb * body + EdgeColor.rgb * edge
outAlpha = baseRGBA.a * visible

At Dissolve=0, noise values 0, 0.5, and 1 all produce Body. At Dissolve=1, they all produce Hidden. At 0.5, low noise values are Hidden, high values are Body, and Edge appears only along the boundary. Max keeps Edge nonnegative.

For a Smoothstep version, keep the same threshold direction: use visibleSoft=Smoothstep(threshold-Softness, threshold+Softness, noise), bodySoft=Smoothstep(threshold+EdgeWidth-Softness, threshold+EdgeWidth+Softness, noise), and edgeSoft=Saturate(visibleSoft-bodySoft). Apply the same start/finish guards. Invert with One Minus to use the effect for appearing instead.

Noise and coordinate choices change the impression:

Look	Example input
Fire	Broad Gradient Noise + an orange HDR Edge
Ice	Voronoi + a thin light-blue Edge
Digitization	Noise quantized into horizontal bands + cyan
Turning to ash	Add World Position.y to Noise to progress from bottom to top
Reversing petrification	Use region masks to offset the start time

Object Position makes the effect progress through the same relative portion of each sprite. World Position makes it cross multiple objects at the same height.

For many sprites or a mobile target, measure whether a small shared Noise Texture performs better than procedural noise.

Technique 4: Outer outlines and inner rims

▶ Watch this effect (from 0:27)

Sample files (use the folders listed at the beginning)

Graph: Effect04_OutlineInnerRim.shadergraph

Material: Effect04.mat / Scene: 04_OutlineInnerRim.unity

Set the per-renderer Outline Directions to 4 or 8. Compare the geometry using DemoCharacter.png and DemoCharacter_Tight.png from Art. ShaderCapture.spriteatlas has Rotation OFF, Tight Packing OFF, and Padding 8, but you must still check the transparent margin and maximum UV offset.

Create an outline by comparing the center pixel's alpha with the alpha of neighboring pixels.

Four-direction outline

Let texel be the UV size of one texel in the source texture.

a0 = Alpha(textureUV)
aL = Alpha(textureUV + (-texel.x, 0))
aR = Alpha(textureUV + ( texel.x, 0))
aU = Alpha(textureUV + (0,  texel.y))
aD = Alpha(textureUV + (0, -texel.y))

neighbor = Max(aL, aR, aU, aD)
outline = Saturate(neighbor - a0)

Composite the output as follows:

outRGB = Lerp(OutlineColor.rgb, baseRGBA.rgb, a0)
outAlpha = Max(a0, outline * OutlineColor.a)

An eight-direction version adds diagonal samples and looks smoother, but takes nine samples including the center. It may be suitable for a few selected objects, but not as a permanent effect on hundreds of grass sprites or tiles.

Changing the thickness

Use texel * OutlinePixels as the offset. As the thickness increases to 2, 3, or 4 texels, the samples can skip intermediate pixels and leave gaps. For thick outlines, add samples at different distances or prepare a Signed Distance Field in advance to keep quality and cost manageable.

Inner rim

To illuminate only the inside edge rather than adding color outside the sprite, use the minimum neighboring alpha:

inner = a0 * (1 - Min(aL, aR, aU, aD))
outRGB = baseRGBA.rgb + InnerColor.rgb * inner * Strength
outAlpha = a0

This works well for state indicators: a red inner rim during a hit, or a light-blue rim while frozen.

Sprite Atlas and Mesh Type pitfalls

Offsetting UVs outward can sample a neighboring sprite in the Atlas. Also, no fragments are generated outside the sprite's rendered mesh. If opaque pixels extend all the way to the image Rect's edges, the outer outline can be cut off.

Check these conditions:

Disable Allow Rotation for Atlases containing direction-dependent UV effects; this is a requirement for these recipes.
For outer outlines, also check Atlas Tight Packing. Disable it or use a separate Atlas when needed.
Leave transparent space inside the source sprite's Rect at least as wide as the outline.
Check Alpha Dilation for color bleeding at transparent edges; it does not enlarge the drawable region.
Provide enough Sprite Atlas Padding.
Use a separate Atlas for sprites with large effects extending outward.
Consider Full Rect if Mesh Type: Tight cuts off the effect.
Keep UV offsets within the range you planned for.

Sprite Atlases can pack sprites with a 90-degree rotation. With Allow Rotation enabled, textureUV.x/y may not match the sprite's local horizontal and vertical directions. These recipes assume Allow Rotation is OFF for UV wobble, RGB glitches, pixelation, and directional outlines. To retain rotated packing, read packing information such as Sprite.packingRotation on the CPU and supply a rotation basis to the shader. Full Rect alone cannot draw beyond the source Rect, so check transparent margins, Tight Packing, and Padding together.

Technique 5: Animating grass, cloth, and hair

▶ Watch this effect (from 0:34)

Sample files (use the folders listed at the beginning)

Graph: Effect05_WindVertexSquash.shadergraph

Material: Effect05.mat / Scene: 05_WindVertexSquash.unity

Use DemoCharacter_Quad.png (4 vertices) and DemoCharacter_Subdivided.png (169 vertices) from Art together with their .meta files. Toggle the per-renderer UV Wiggle Amount, Vertex Wind Amount, and Squash Amount settings between 0 and 1. This demo uses the sprite geometry stored with the PNG and .meta, not a Mesh asset.

There are two approaches to swaying: offset the UVs or offset the vertices. They can look similar, but differ in whether the silhouette changes.

Wobbling only the UVs

phase = local01.y * Frequency
      + Time * Speed
      + Seed

offsetX = sin(phase) * AmplitudePixels
textureUV.x += offsetX * texel.x * local01.y

Multiplying by local01.y at the end anchors the bottom and increases the movement toward the top. This works for grass, flames, patterns inside a flag, and water reflections.

Specifying amplitude in pixel units such as “2 texels,” rather than “0.01 UV units,” makes adjustment easier when the Atlas size or source texture resolution changes.

UV wobble alone does not change the sprite's rectangular geometry. Without enough transparent margin, the displaced image is clipped at the Rect's edges.

Moving the vertices

Use Object Position as the starting point for the Master Stack's Vertex Position, and add a wave to X:

positionOS.x += sin(
    local01.y * Frequency
    + Time * Speed
    + Seed) * Amplitude * local01.y

This also moves the silhouette. However, a Full Rect sprite with only four vertices produces something closer to a shear than a smooth S-shaped curve.

For smooth bending, use one of these approaches:

Give the sprite enough vertices through 2D Animation's Sprite Skin workflow.
Subdivide the mesh in the Sprite Editor.
Render a custom mesh with a MeshRenderer.
Split the object into parts and animate them with Transforms or bones.

A shader cannot create vertices that do not exist. If the graph seems correct but the sprite only tilts like a board, mesh density—not the calculation—is the issue.

For a custom Graph using Sprite Skin, first check three prerequisites: (1) 2D Animation's SpriteSkin, (2) GPU Skinning enabled in Player Settings, and (3) SRP Batcher enabled in the URP Render Pipeline Asset. Feed Object-space Position, Normal, and Tangent into the Sprite Skinning node and use its skinned Position, Normal, and Tangent outputs. Add custom offsets after skinning, then connect the result to Vertex Position. Enabling SRP Batcher here is a functional prerequisite; losing SRP Batcher compatibility through MaterialPropertyBlock is a separate performance consideration.

Jelly-like squash

For a landing squash, widen the vertices along X and compress them along Y:

anchor01 = float2(0.5, 0.0) // Bottom anchor. For a center anchor, use float2(0.5, 0.5).
scale = float2(1 + Squash, 1 - Squash)
deformed01 = (local01 - anchor01) * scale + anchor01

// Convert normalized coordinates back to Object Space for Vertex Position.
deformedOS.xy = (deformed01 - Pivot01) * SpriteSize
deformedOS.z = Position(Object).z

At Squash=0, deformed01 == local01, so the result matches the original Object Position. Restoring Object Space with Pivot01 prevents a positional jump even with an off-center pivot. A bottom anchor uses anchor01.y=0, keeping vertices at local01.y=0 fixed vertically. For a center anchor, use anchor01=(0.5, 0.5). Compared with animating Transform Scale through an Animator, shader deformation makes it easier to mask the deformation to specific regions.

Technique 6: Row-based glitches and RGB splitting

▶ Watch this effect (from 0:41)

Sample files (use the folders listed at the beginning)

Graph: Effect06_GlitchRgbSplit.shadergraph

Material: Effect06.mat / Scene: 06_GlitchRgbSplit.unity

Additional required dependency: Assets/ShaderCapture/Shaders/Includes/ShaderCaptureEffects.hlsl and its .meta. The sample function is Effect06Fragment, which also composites RGB and supports both float and half. It differs from the recipe's GlitchUV, which only returns modified UVs. The sample HLSL contains four explicit texture samples: the original image, center, R, and B. Evaluate that separately from the three-sample minimal recipe below.

A glitch usually feels more convincing when a few horizontal blocks suddenly shift rather than continuously wobble. Put the row-and-time-based random calculation in a Custom Function to keep the graph readable.

// Assets/Shaders/Glitch2D.hlsl
#ifndef GLITCH_2D_INCLUDED
#define GLITCH_2D_INCLUDED

float Hash21(float2 p)
{
    p = frac(p * float2(123.34, 456.21));
    p += dot(p, p + 45.32);
    return frac(p.x * p.y);
}

void GlitchUV_float(
    float2 UV, float LocalY, float TimeValue,
    float BlockCount, float Rate,
    float AmountInTexels, float TexelX,
    float Threshold,
    out float2 OutUV, out float Mask)
{
    float row = floor(LocalY * max(BlockCount, 1.0));
    float tick = floor(TimeValue * max(Rate, 0.001));
    float random = Hash21(float2(row, tick));

    Mask = step(Threshold, random);
    OutUV = UV + float2(
        (random * 2.0 - 1.0)
        * AmountInTexels * TexelX * Mask, 0.0);
}

void GlitchUV_half(half2 UV, half LocalY, half TimeValue, half BlockCount, half Rate, half AmountInTexels, half TexelX, half Threshold, out half2 OutUV, out half Mask)
{
    float2 uv; float mask;
    GlitchUV_float((float2)UV, LocalY, TimeValue, BlockCount, Rate, AmountInTexels, TexelX, Threshold, uv, mask);
    OutUV = (half2)uv; Mask = (half)mask;
}

#endif

Set the Custom Function Node to File Mode and enter GlitchUV as the function name, without a suffix. The HLSL provides both _float and _half, so it resolves with Single or Half precision. Define the ports in this order: inputs UV Vector2, LocalY Float, TimeValue Float, BlockCount Float, Rate Float, AmountInTexels Float, TexelX Float, and Threshold Float; outputs OutUV Vector2 and Mask Float. Match the names, types, and order to the HLSL arguments. Connect local01.y to LocalY and the original Texture UV to UV.

RGB splitting uses three samples:

right = Sample(MainTex, glitchUV + (chroma, 0))
center = Sample(MainTex, glitchUV)
left = Sample(MainTex, glitchUV - (chroma, 0))
r = right.r
g = center.g
b = left.b
a = center.a

That is one sample on each side and one at the center: three Sample Texture 2D nodes in total. G and alpha reuse the same center sample. If all three samples remain active during normal rendering, another option is to switch Materials only while the effect is playing.

With an Atlas, provide Padding wider than the maximum AmountInTexels so that UV offsets do not reach neighboring sprites. An effect that tears the entire screen is better suited to a Renderer Feature or full-screen Blit than an individual sprite shader.

Technique 7: Pixelation, posterization, and dithering

▶ Watch this effect (from 0:48)

Sample files (use the folders listed at the beginning)

Graph: Effect07_PixelPosterizeDither.shadergraph

Material: Effect07.mat / Scene: 07_PixelPosterizeDither.unity

Set the per-renderer Dither Space to 0 for UV-based pixels or 1 for screen pixels. The sample adds a dither pattern to the color; it does not use the Alpha Clipping variation described below.

For a pixel-art-like result, separate the process into three stages: UV quantization, color quantization, and dithering.

Pixelation

Convert UVs to actual texture pixel coordinates, then quantize them into blocks:

pixel = textureUV * TextureSize
pixelated = floor(pixel / BlockPixels) * BlockPixels
sampleUV = (pixelated + BlockPixels * 0.5) / TextureSize

The 0.5 samples the center of each block. In Shader Graph, build this with Texel Size, Multiply, Divide, and Floor.

Quantizing in pixel coordinates across the entire Atlas can look acceptable with small BlockPixels values, but can sample neighboring sprites at the boundaries. To keep the effect strictly within each sprite, supply its UV Rect and convert to local coordinates, or keep the target sprite outside the Atlas.

Posterization

Round RGB values to the desired number of levels:

quantized = round(color * (Levels - 1)) / (Levels - 1)

Shader Graph also has a Posterize node. Around 4–8 levels produces retro-looking gradients. To constrain the actual colors rather than only their levels, map them to the nearest color in the Palette Texture from Technique 2.

Dithering

Add a Dither node when reducing the number of colors produces banding.

You can also enable Alpha Clipping in the Graph Inspector and connect the Dither result to Alpha Clip Threshold to represent transparency as a pattern of discarded pixels. However, Alpha Clipping and Depth Write are separate settings. Transparent rendering with Depth Write: Auto does not acquire opaque-cutout-style depth writing merely because Alpha Clipping is enabled. Consider Force Enabled only for a specific need to write depth, and check its effects on 2D sorting, SpriteMask, and overlapping transparent objects. Prioritize sorting for ordinary 2D sprites.

Using Screen Position for dithering keeps the pattern fixed on the screen while the sprite moves. Using UVs or local01 attaches it to the sprite. When combining this with a Pixel Perfect Camera, consistently use either the game resolution or the final output resolution as the pattern's reference; mixing them can make the pattern shimmer during camera movement.

Technique 8: Holograms, scan lines, and diagonal shine

▶ Watch this effect (from 0:55)

Sample files (use the folders listed at the beginning)

Graph: Effect08_HologramShine.shadergraph

Material: Effect08.mat / Scene: 08_HologramShine.unity

This Graph combines scan lines, UV offsets, and diagonal shine using standard nodes. It does not need the HLSL from Technique 6. The horizontal-line and diagonal-shine branches can be adjusted separately.

Scan lines

line = sin((local01.y * LineCount + Time * ScrollSpeed) * 6.283185)
lineMask = Smoothstep(LineThreshold, 1, line)

outRGB = baseRGBA.rgb * HologramTint
       + LineColor * lineMask * LinePower

outAlpha = baseRGBA.a * Lerp(MinAlpha, 1, lineMask)

Use Screen Position.y to keep the lines fixed on the screen like a CRT, or local01.y to attach them to a projected image. A mostly stable hologram with occasional horizontal shifts from Technique 6 is usually easier to read than a constantly unstable one.

Diagonal shine

A dot product creates a band that sweeps across a card or item:

p = dot(local01, float2(0.5, 0.5))
center = frac(Time * Speed)
d = abs(p - center)
d = min(d, 1 - d)
shine = 1 - Smoothstep(Width, Width + Softness, d)

Add shine as an HDR color and multiply it by baseRGBA.a to keep it out of transparent regions. A Mask Map that marks only metal or glass prevents faces and cloth from shining unnaturally.

Technique 9: Adding depth with normal maps and 2D lights

▶ Watch this effect (from 1:02)

Sample files (use the folders listed at the beginning)

Graph: Effect09_NormalMap2DLight.shadergraph

Material: Effect09.mat / Scene: 09_NormalMap2DLight.unity

This is a Sprite Lit Graph. Register DemoCharacter_Normal.png from Art as the _NormalMap Secondary Texture. To reproduce the moving Light 2D as well, include DeterministicLightRig.cs from Runtime and preserve the Scene's reference assignments. In addition to the standard normal connection, the sample Graph emphasizes shading in Base Color.

A Sprite Lit Shader Graph with a Normal Map registered as a Secondary Texture can add directional shading to a flat sprite.

Setup

Prepare a Normal Map with the same layout and dimensions as the Main Texture. If using a Mask Map, prepare one with the same layout and dimensions as well.
Import the Normal Map with Texture Type: Normal Map and sRGB OFF. Import the Mask Map with Texture Type: Default and sRGB OFF. For pixel-precise masks, check for channel contamination from mipmaps and compression in the actual target texture format.
Open Secondary Textures in the Sprite Editor, add the Normal Map, and set its Name to _NormalMap.
If using a Mask Map, add it on the same Secondary Textures screen and set its Name to _MaskTex.
Check the Texture assignments for _NormalMap and, when used, _MaskTex, then click Apply.
Create a Sprite Lit Shader Graph.
Connect _MainTex, _MaskTex, and _NormalMap to their respective Sample Texture 2D nodes.
Change the normal sample's Type to Normal.
Connect the results to Base Color, Sprite Mask, Normal (Tangent Space), and Alpha in the Master Stack.
Add Light 2D objects to the Scene and enable Normal Map support on the lights that need it.

Automatically generated normal maps tend to turn line art into surface bumps. Refine the large forms first: the face, clumps of hair, and curved armor surfaces.

Performance considerations

2D lighting uses Light Render Textures for each Blend Style. When normal maps are enabled, a full-size Render Texture is created for the depth prepass for each Layer Batch. The Unity 6.4 documentation describes this as expensive.

Start with one Blend Style, enable normals only for the Sorting Layers that need them, and measure Light Render Texture Scale, light count, and shadows on the target device.

Technique 10: Masking wetness, metal highlights, and weak points

▶ Watch this effect (from 1:09)

Sample files (use the folders listed at the beginning)

Graph: Effect10_MaskMapLighting.shadergraph

Material: Effect10.mat / Scene: 10_MaskMapLighting.unity

This is a Sprite Lit Graph. Register DemoCharacter_Mask.png from Art as the _MaskTex Secondary Texture. The sample uses R for wetness, G for metal lighting, and B for a pulsing weak point. Set the per-renderer Mask Channel to 0, 1, or 2; do not leave it at the initial value of −1. For G, the Light 2D uses Blend Style 3 (zero-based: Additive with Mask, G) from Assets/Settings/Renderer2D.asset. Set the target sprite's Sorting Layer to MaskMetal and configure the light to target that Sorting Layer. Recreate this correspondence in the destination project instead of overwriting its entire settings file.

Assigning the channels of a Mask Map lets you distinguish materials within a single sprite.

Channel	Example use
R	Ordinary shading
G	Metal or wet surfaces
B	Magic or weak points
A	Reserved for another effect

Set Mask Texture Channel in the 2D Renderer Data's Light Blend Styles, then select the corresponding Blend Style on the Light 2D. The Master Stack's Sprite Mask is the input for this 2D lighting Mask Map; it is not the SpriteMask component.

For rain, paint upward-facing surfaces and hair highlights into G, then multiply by _Wetness:

wet = mask.g * Wetness
outRGB += WetColor * wet

A boss core painted into B can pulse only while it is vulnerable:

pulse = 0.5 + 0.5 * sin(Time * PulseSpeed)
weak = mask.b * WeakPoint * pulse
outRGB += WeakColor * weak * WeakPower

Pack color-variation, wetness, and weak-point data into RGBA without giving a channel conflicting meanings. Check for channel contamination caused by lossy compression in the actual device texture format. Adding color in a Lit Graph modifies Base Color before lighting. If you need emission that does not depend on lighting, use an additional Unlit sprite or a separate additive effect.

Technique 11: Water reflections with a duplicated sprite

▶ Watch this effect (from 1:16)

Sample files (use the folders listed at the beginning)

Graph: Effect11_WaterReflection.shadergraph

Material: Effect11.mat / Scene: 11_WaterReflection.unity

Assign the Material only to the duplicated reflection sprite. In the Scene, Stable Subject is rendered normally, while Reflection is flipped vertically, dimmed, and UV-distorted. The Material does not create the reflection object for you.

For a small puddle or water in a side-scrolling scene, duplicating a SpriteRenderer is a lightweight alternative to using another Camera.

Place a reflection Renderer as a child of the original SpriteRenderer.
Flip it vertically and position it below the waterline.
Move it to the water's Sorting Layer.
Apply a horizontal wave and an alpha fade.

wave = sin(local01.y * Frequency + Time * Speed)
     * AmplitudePixels

sampleUV.x = textureUV.x + wave * texel.x
fade = Smoothstep(0, FadeLength, 1 - local01.y)

outAlpha = baseRGBA.a * fade * ReflectionAlpha

Depending on how the reflection is flipped, the waterline may be at the opposite end. Swap local01.y and 1 - local01.y when needed. Keep distortion within the transparent margin and Atlas Padding. This method reflects only the duplicated sprite. For background objects and occlusion, use a Camera plus a Render Texture; for a full-screen effect, use a Renderer Feature.

Technique 12: World-space scans and circular reveals

▶ Watch this effect (from 1:23)

Sample files (use the folders listed at the beginning)

Graph: Effect12_WorldScanReveal.shadergraph

Material: Effect12.mat / Scene: 12_WorldScanReveal.unity

Share the Material, _SC_ScanCenter, and _SC_ScanRadius across the target sprites. The sample's reveal does not completely hide the area outside the radius. To make it fully invisible, use the alpha formula below.

World Position lets one wave sweep across multiple sprites. Uses include item searches, sonar, boss attack telegraphs, and the end of a time-stop effect.

Circular scan

Supply a world-space center, _ScanCenter, and a radius, _ScanRadius:

distance = Distance(Position(World).xy, ScanCenter.xy)

ring = 1 - Smoothstep(
    RingWidth,
    RingWidth + Softness,
    abs(distance - ScanRadius))

outRGB = baseRGBA.rgb
       + ScanColor.rgb * ring
       * baseRGBA.a * ScanPower

Global shader properties are appropriate when all targets use the same values. Set the Scope of _ScanCenter and _ScanRadius to Global in the Blackboard. If they remain Per Material, the Material values take precedence.

using UnityEngine;

public sealed class WorldScanController : MonoBehaviour
{
    static readonly int CenterId = Shader.PropertyToID("_ScanCenter");
    static readonly int RadiusId = Shader.PropertyToID("_ScanRadius");

    [SerializeField] Transform center;
    [SerializeField] float radius;

    void Update()
    {
        Vector3 p = center != null ? center.position : transform.position;
        Shader.SetGlobalVector(CenterId, new Vector4(p.x, p.y, p.z, 0f));
        Shader.SetGlobalFloat(RadiusId, radius);
    }
}

Turning the scan into a reveal

To show only the area within the radius, multiply alpha by this mask:

inside = 1 - Smoothstep(
    ScanRadius - Softness,
    ScanRadius,
    distance)

outAlpha = baseRGBA.a * inside

For large numbers of hidden objects, disable distant Renderers and use the shader fade only near the boundary.

World Position makes the sprite appear to pass through the light. Object Position attaches the pattern to the sprite. Screen Position fixes it to the screen.

Combine techniques into more expressive effects

A small set of combinations with clear gameplay meaning is easier to maintain than a large collection of unrelated effects.

Use case	Combination
Taking damage	Brief white Flash + red Inner Rim + a momentary Glitch
Teleporting	Dissolve + HDR Edge + RGB splitting just before disappearance
Rare card	Palette + diagonal Shine + glow restricted to the metal Mask
Reversing petrification	Desaturation + Voronoi Dissolve + a return to the original Palette

Drive several features from one _Effect value with offset timing, and the script only needs to animate a single value from 0 to 1. For example, remap 0–0.2 for the Flash, 0.15–0.9 for the Dissolve, and 0.85–1.0 for the final glow.

Five factors that determine performance

1. Texture sample count

These estimates describe the article's minimal implementations. Measure them separately from the distributed sample's extra processing and the complete comparison Scenes.

Flash uses one sample; Palette uses three (Main + Index + Palette); a four-direction Outline uses five; an eight-direction Outline uses nine; and RGB Glitch uses three. Even at _Effect = 0, the effect's texture samples can remain in a graph that evaluates both sides of a Lerp. One option is to use a lightweight shader for the normal state and a different shader only while the effect is active.

2. Transparent overdraw

Large transparent margins, oversized particles, and nearly full-screen holograms can make overdraw more important than instruction count.

3. Render Textures for 2D lighting

Each Blend Style needs a Light Render Texture. Unity's optimization guide gives examples of using one for a simple Scene and keeping more general cases to around two. Include normal maps, shadows, and the light sets for each Sorting Layer in your measurements.

4. Per-renderer values

Accessing renderer.material creates a Material instance. MaterialPropertyBlock avoids that duplication, but removes SRP Batcher compatibility.

Choose the data path according to its scope:

Shared everywhere: shader properties with Global Scope.
Shared by a group: a shared Material.
A few individual characters: MaterialPropertyBlock.
Large amounts of per-object data: vertex streams, additional UVs, or custom meshes.

5. Shader variants

Keywords can remove unnecessary calculations by disabling features, but their combinations increase the number of variants. Do not combine Flash, Outline, Dissolve, and Glitch without limit in a single shader. Group only the features that need to run together.

Common failures and their causes

Symptom	Main cause and remedy
A horizontal offset becomes vertical after packing	`Allow Rotation` rotated the packed sprite. Disable it for direction-dependent UV effects.
An outer Outline is clipped or samples a neighbor	Check Tight Packing, transparent margins, Alpha Dilation, Padding, and Mesh Type together.
Stripes become denser after packing into an Atlas	The pattern uses Texture UVs. Separate it into `local01` derived from Object Position.
UV wobble reveals a neighboring image	Atlas Padding is insufficient. Revisit the maximum offset, Padding, and Atlas grouping.
An Outline is cut off at the rectangle's edge	Nothing is drawn outside the Sprite Rect or mesh. Add transparent margin and use Full Rect when needed.
Vertex deformation only tilts the sprite like a board	There are not enough vertices. Use Sprite Skin or a subdivided mesh.
Transparent edges look black	Check the RGB of transparent pixels, blending, Padding, compression, and whether the original alpha was applied.
SpriteRenderer.color is applied twice	Reconcile `Disable Color Tint` with any manual Vertex Color multiplication so tint is applied once.
The effect is cheap on PC but expensive on the target device	Check resolution, overdraw, texture formats, and 2D lighting Render Textures on the device GPU.

Which techniques should you introduce first?

A cautious implementation order is Flash, Palette, Dissolve, Inner Rim, Shine, selective use of Outline, and finally Normal Map + 2D Light. The later techniques need more attention to Atlases, additional samples, and Light Render Textures.

Give color and motion consistent meanings: white for damage, a red inner rim for danger, a blue scan for search targets, and diagonal shine for rare items. The visual effects then become part of the game's information design.

Conclusion

Unity 2D shader effects can be broken down into operations on UVs, RGB, alpha, and Object, World, or Screen coordinates. Separate Texture UVs from pattern coordinates, respect Atlas boundaries and the original alpha, and measure sample count and overdraw on the target device.

Start by adding Flash and Dissolve to a Sprite Unlit Shader Graph. Extract reusable parts into Sub Graphs, and the remaining effects can be built with the same ideas.

References

Sources for the distributed implementation

Generation code at the pinned revision: ShaderCaptureProjectGenerator.cs defines the artwork, Scenes, and Bloom settings; ShaderCaptureNativeGraphBuilder.cs defines the effect nodes; and ShaderCaptureGraphGenerator.cs defines the Graph settings.

Real-Time Networking for 3D FPS Games in UE5: Replication, EOS, Dedicated Servers, and Pitfalls

GameDevToolLab — Fri, 11 Sep 2026 04:40:55 +0000

Building an online FPS or TPS in Unreal Engine 5 is not a matter of choosing one "networking library." A production game usually has three networking layers:

Gameplay networking — movement, shooting, damage, ammo, projectiles, doors, objectives, and match state.
Online services — authentication, friends, invites, lobbies, sessions, matchmaking, voice, P2P, and relay.
Dedicated-server operations — allocation, region selection, health checks, deployment, logs, scaling, draining, and shutdown.

For most UE shooters, start with built-in Replication, RPCs, and UCharacterMovementComponent. Use a Dedicated Server when fairness matters; consider a Listen Server for small co-op. Add Steam/EOS, GAS, Replication Graph, Iris, or external SDKs only when targets or measurements justify them.

Technical baseline: August 31, 2026. The article uses UE 5.8 documentation and public UE 5.8.1/5.8.2 hotfix notes. The Network Emulation caveat below comes from source inspection of UE 5.8.0 CL 55116800; that engine build was not re-run while preparing this English edition.

Think in three layers, not one library

Gameplay networking

This layer synchronizes gameplay under latency, packet loss, reordering, relevance filtering, and bandwidth limits. UE Replication is a strong default because Actor ownership, per-connection relevancy, priority, dormancy, RPCs, property replication, and Character Movement prediction all live in the same networking model [1-9].

Online services

Steam and EOS answer questions such as "who is the player?", "which lobby are they in?", and "where should they connect?" They do not replace Actor replication after the connection is established. In UE 5.8, Online Services is still documented as Beta, so projects shipping soon should evaluate it against the established Online Subsystem path [17-21].

Server operations

A Dedicated Server still needs to be started, allocated, monitored, updated, drained, and terminated. Amazon GameLift Servers, PlayFab Multiplayer Servers, and Agones help with this operational layer [24-27]. They do not replace Replication.

Competitive FPS: start from a server-authoritative Dedicated Server

Unreal multiplayer is fundamentally client-server, with the server holding the authoritative world state [1,2]. That maps naturally to competitive shooters.

A Listen Server can be perfectly reasonable for a two-to-four-player co-op game, but the host has direct access to the authoritative process. In PvP, that becomes a fairness problem in addition to host departure, NAT, and hardware variance.

A Dedicated Server costs more to operate, but gives you a cleaner authoritative process for validation and consistent simulation. Choose by measured Actors, AI, shot frequency, server frame time, and bandwidth—not player count alone.

Put replicated state in the right gameplay class

A common Dedicated Server migration bug is trying to read server-only objects from client UI.

A useful division is:

GameMode: server-only rules such as win conditions, spawn rules, admission rules.
GameState: public match state such as phase, team score, and round-end server time.
PlayerState: public per-player data such as team, kills, and deaths.
PlayerController: input, owner-only UI, and owner-only notifications.
Pawn / Character: the current body, movement, and weapon interaction.

GameMode does not exist on clients. PlayerController is normally relevant only to its owning client, so it is also the wrong place for a scoreboard that everybody must see [31,32].

For countdowns, replicate a round end server timestamp, not "seconds remaining" every second. Clients can derive the display from AGameStateBase::GetServerWorldTimeSeconds() [31,35], including after late join.

Use `UCharacterMovementComponent` before inventing movement RPCs

Do not start an FPS by sending your own transform or velocity RPC every frame.

UCharacterMovementComponent already implements local prediction, saved moves, server simulation, correction, and smoothing for remote Characters [5]. Extend movement modes and saved moves for sprinting, sliding, or similar mechanics instead of creating a second synchronization system on top of it.

For unusual vehicles or physics, custom prediction or the Network Prediction plugin may be relevant, but the UE 5.8 API still marks that plugin Beta [12]. Prototype before depending on it.

Separate state from events

The most useful rule in UE networking is simple:

State that must be reconstructable belongs in Replicated Properties.
Transient events may use RPCs when appropriate.

HP, ammo, equipped weapon, death state, doors, score, and match phase should survive packet loss, late join, and becoming relevant again. That makes them state.

Muzzle flashes, impact particles, and one-shot sounds may fit Unreliable RPCs, but prefer deriving visuals from replicated state when possible. Reliable RPCs are for low-frequency operations retried while the connection and channel remain valid; overuse can block later reliable traffic [3].

Also remember ownership: a client can normally send a Server RPC only through an Actor it owns. Input RPCs therefore belong on the owning PlayerController, Pawn, or an owned Component/Weapon whose owner chain is correct [3,32].

Do not turn RPC ordering into a game rule

UE documents representative ordering for one Actor under specific send/bunch conditions [33]. Do not generalize that into a gameplay protocol across Actors, Components, frames, loss, or reordering.

ERemoteFunctionSendPolicy::ForceSend also has important limits: it is supported by Replication Graph or Iris, and only sends immediately when invoked in the supported NetDriver::PostTickDispatch / NetWorldTickTime phase. Outside that phase it behaves like Default. ForceQueue is different: it serializes later in the net update if bandwidth remains [3,33].

Use sequence numbers, generations/epochs, and idempotent application logic instead.

Server-authoritative shooting: separate intent from result

The most dangerous shooter implementation is accepting HitActor, bone, or damage values sent by the client.

The client may send intent: which weapon, aim direction, and a timestamp estimate. The server decides the result.

The example below focuses on hitscan weapons. Slow projectiles, predicted projectiles, explosive overlap, and physics interaction need different designs.

Give every shot a lifecycle-aware key

A plain uint16 Sequence is not enough if the weapon respawns, ownership changes, or a sequence wraps. Use a server-assigned source plus an epoch:

USTRUCT()
struct FShotKey
{
    GENERATED_BODY()

    UPROPERTY() uint32 FireSourceId = 0; // server assigned
    UPROPERTY() uint16 FireEpoch = 0;    // changes when the sequence space resets
    UPROPERTY() uint16 Sequence = 0;
};

USTRUCT()
struct FShotRequest
{
    GENERATED_BODY()

    UPROPERTY() FShotKey Key;
    UPROPERTY() uint8 WeaponSlot = 0;
    UPROPERTY() FVector_NetQuantizeNormal AimDirection;
    UPROPERTY() uint32 EstimatedServerTimeMs = 0;
};

Before calling the Server RPC, the owning client records (FireSourceId, FireEpoch, Sequence) in a client-process prediction history and plays predicted local FX once. Do not tie that history to the current possession state. Keep it long enough to cover your maximum network/reconciliation delay, and namespace or clear it across disconnect, Server Travel, and session changes.

This matters because a delayed multicast may arrive after death, unpossess, repossess, or controller transfer. Looking only at IsLocallyControlled() at receive time is not enough.

Validate the caller separately from the shot stream

There are two trust questions:

Which network connection actually sent this Server RPC?
Is the FireSourceId / epoch / slot in the request a stream that the server assigned to that connection?

Do not mix them.

A useful conceptual flow is:

CaptureOriginalCallerContext()
  -> ResolveReconciliationComponent(OriginalConnection)
  -> ValidateAssignedShotStream(Request, Caller)
  -> obtain CanonicalKey
  -> validate ammo/rate/time/aim
  -> authoritative trace
  -> PublishCanonicalShotResolution(...)

Only a canonical, server-validated shot key should enter the authoritative result cache or owner-only reconciliation snapshot.

Treat invalid keys differently from ordinary gameplay rejection:

Unassigned source, future epoch, or a source belonging to another connection: audit/strike/disconnect policy; do not mutate result state.
A stale epoch caused by an allowed switching race: optionally return one transient rejection to the original connection, but do not advance the authoritative snapshot.
Valid key but empty magazine, rate limit, invalid timing window, or excessive aim delta: normal rejection; cache it like an accepted shot so duplicates stay idempotent.

Keep the result route tied to the original connection

Do not resolve the destination again from the Weapon's current owner when the result is ready. Resolve the reconciliation component from the connection captured at RPC dispatch time, ideally on an object that outlives the Pawn such as the original PlayerController.

Conceptually:

UMyShotReconciliationComponent* Reconciliation =
    ResolveReconciliationComponent(Caller.OriginalConnection);

if (TryGetCachedResolution(CanonicalKey, Cached))
{
    Reconciliation->PublishCanonicalShotResolution(Stream, Cached);
    return;
}

if (!ValidateGameplayShot(...))
{
    Reconciliation->PublishCanonicalShotResolution(
        Stream,
        BuildResolution(CanonicalKey, false, false, Ammo, RejectReason));
    return;
}

const FServerShotResult Result = RewindAndTraceOnServer(Context);
ConsumeAmmoOnServer(Stream);
ApplyDamageOnServer(Result);

Reconciliation->PublishCanonicalShotResolution(
    Stream,
    BuildResolution(CanonicalKey, true, Result.bHitConfirmed, Ammo, None));

MulticastPlayConfirmedFireFx(CanonicalKey, Result.CosmeticData);

Duplicates return the cached result to the same original connection without repeating ammo consumption, damage, snapshot mutation, or multicast.

Reconciliation needs an immediate path and a state path

An Unreliable Client RPC is useful for low-latency feedback, but it can be lost. Keep a compact owner-only replicated state as the convergence path.

For example, track:

FireSourceId
FireEpoch
LastContiguousResolvedSequence
a small recent accepted/rejected/hit detail window
authoritative ammo

void UMyShotReconciliationComponent::GetLifetimeReplicatedProps(
    TArray<FLifetimeProperty>& OutLifetimeProps) const
{
    Super::GetLifetimeReplicatedProps(OutLifetimeProps);

    DOREPLIFETIME_CONDITION(
        UMyShotReconciliationComponent,
        ShotSyncState,
        COND_OwnerOnly);
}

If the reconciliation object is a replicated Component/Subobject, also configure its actual replication/registration path [4,16].

Predicted owner FX and confirmed remote FX are different responsibilities

The owner already played the shot immediately. The multicast mainly exists for other clients.

Use a client-process PredictedFxHistory to suppress a confirmed FX key that this local process already predicted, and a separate ConfirmedFxHistory to make remote FX idempotent. Perform that check in an application handler that does not depend on current possession:

void AMyWeapon::ApplyConfirmedFxIfNew(
    FShotKey Key,
    const FFireFxData& FxData)
{
    if (GetClientShotFxRegistry().WasPredictedByAnyLocalPlayer(Key))
    {
        return;
    }

    if (!ConfirmedFxHistory.RememberIfNew(Key))
    {
        return;
    }

    PlayConfirmedFireFx(FxData);
}

This survives delayed multicast delivery across death, unpossess, repossess, and ownership transfer; non-predicting AI/weapons simply play confirmed FX once.

A useful regression test delays each client's application-handler entry after network delivery but before the prediction-history check, changes possession/ownership, then resumes. The history-based implementation should still produce one total FX per client. A mutation that replaces the history check with IsLocallyControlled() should fail. Delaying only PlayConfirmedFireFx() is too late to catch that bug.

The handlers must be idempotent

Your design should remain correct for representative paths such as:

Scenario	Owner FX	Result convergence
Client RPC arrives first	1 predicted FX	Immediate result; later property is harmless
Property arrives first	1 predicted FX	Snapshot resolves; later RPC is harmless
Multicast arrives first	Still 1 predicted FX	Later RPC/property resolves the shot
Server RPC request is lost	1 predicted FX	Later sequence/heartbeat or owner timeout cancels provisional state
Client result RPC is lost	1 predicted FX	Owner-only property converges
Multicast is lost	Owner still has predicted FX	Authoritative damage/ammo remain correct
Same game handler injected twice	At most one FX	Ammo/damage/result apply once

Packet duplication does not prove the same gameplay RPC reached application code twice. Test idempotence by directly injecting the same key twice into authority, result, and FX handlers.

Aim validation and lag compensation

Checking that an aim vector is normalized is not enough.

Reconstruct the trace origin from server-known historical view/Pawn/weapon state, not a client position. Compare the submitted direction with the accepted server view using state-specific tolerance for hip fire, ADS, recoil, view switching, turrets, or vehicles; also validate range, spread, interval, ammo, reload, and equipment. This constrains impossible trajectories, not all aimbots.

For lag compensation, keep only needed history. Player hitboxes are common, while doors, shields, lifts, and destructible cover may also require historical collision state. Prefer a non-replicated historical collision proxy over moving live Actors. If real Components are rewound, use a scoped guard that restores transform/collision on every exit path and does not emit extra overlaps, gameplay events, physics wake-ups, or replication dirtiness.

For timestamps, GetServerWorldTimeSeconds() is a useful synchronization entry point, but do not blindly trust a client value. Account for RTT, jitter, outliers, reconnects, Server Travel, and long sessions [35]. A match-relative quantized integer tick or double is safer than an ever-growing absolute float.

Automatic weapons: design failure modes, not only happy paths

There is no single correct fire protocol.

Model	Benefit	Main failure mode
Reliable start/stop	Low message count, easy server timer	Stop can wait behind reliable traffic; add state number, max duration, and forced stop on death/weapon change
Unreliable input state + heartbeat	Converges on later heartbeat	Use sequence + timeout to discard stale input
Unreliable request per shot	Easy per-shot aim/result validation	Lost shot request means that shot never happened; high ROF increases traffic and reconciliation work

Choose by fire rate, aim-update needs, packet-loss behavior, reliable-queue pressure, and cheat resistance.

GAS, Replication Graph, and Iris solve different problems

GAS

Gameplay Ability System is valuable when abilities, attributes, effects, tags, cooldowns, costs, and prediction need one model [13,14]. A rifle-focused FPS may not need it everywhere; using normal gunplay Components plus GAS for complex abilities can be simpler.

Replication Graph

Replication Graph targets large Actor/connection counts by reusing persistent graph nodes for candidate selection [10]. Add it when relevance selection is measured as a bottleneck, after fixing unnecessary replication, relevancy/cull distance, update frequency, dormancy, priority, and data layout.

Iris

UE 5.8 documentation is awkward here: the 5.8 release notes call Iris production-ready, while UE 5.8 Iris pages still display Experimental warnings. Iris also remains opt-in [11,34]. Treat the exact engine patch, platform, plugins, replicated Subobjects, serializers, RepNotify behavior, Fast Arrays, and owner-only conditions as a regression-test matrix.

And one very important rule: Iris and Replication Graph are not used together on the same NetDriver. Iris does not support Replication Graph; filtering and prioritization take over those responsibilities [37-39]. Compare a Generic Replication + Replication Graph configuration against an Iris configuration rather than "adding Iris on top."

Steam and EOS are the control plane, not gameplay replication

For Steam-only PC games, Online Subsystem Steam can handle login/session/invite/presence, with Steam Sockets where appropriate [19,20]. For multi-store or cross-platform plans, EOS provides authentication, lobbies, sessions, stats, voice, and P2P-related services [17,18]. Keep vendor APIs behind a game-facing abstraction; Lyra's Common User plugin is a useful flow reference [21].

Photon Fusion for Unreal is a different authority model

Photon Fusion for Unreal 3 uses Shared Authority. That can be attractive for some co-op or distributed-authority games, but it is not the same model as one authoritative UE Dedicated Server [22].

Fusion still reuses replicated/RepNotify-style properties and UE Character Networking [22,40], but logic/tooling built around one server ROLE_Authority needs deeper redesign. At the August 31, 2026 baseline, Fusion for Unreal 3.0.0 is Preview; Windows/Android are supported, macOS/iOS are insufficiently tested, and console/Linux support is planned [23].

Use HTTP, WebSocket, and gRPC for backend work

Use HTTP, WebSocket, or gRPC for accounts, inventory, matchmaking, allocation, results, telemetry, and LiveOps—not per-frame Character Movement or shooting. Replacing NetDriver gameplay traffic means rebuilding UE networking behavior. Keep trusted databases/services behind server-side APIs.

Dedicated-server hosting choices

Amazon GameLift Servers: placement, process integration, health, and scaling [24].
PlayFab Multiplayer Servers: PlayFab-friendly hosting with an Unreal GSDK in the server build [25].
Agones: Kubernetes-native GameServer/Fleet/Allocation; its Unreal Client SDK/plugin belongs in the Dedicated Server process [26,27].

Compare regions, startup/warm pools, UDP/ports, rollout/rollback, autoscaling, DDoS boundaries, observability, crash handling, lock-in, and team expertise.

Optimize bandwidth by not sending data

Before compression, reduce who receives what.

Relevancy — owner relevancy, cull distance, conditional replication [4,6,9].
Update frequency — tune by Actor role; it is not the server simulation tick.
Dormancy — wake/flush before changing replicated state [7].
Priority — relative scheduling under saturation, not total bandwidth [8].
Representation — quantize data and send IDs/state instead of verbose payloads.

Fast Array Serializer helps with changing collections such as inventory/status effects [15]; do not treat replicated order as UI sort order. For replicated Subobjects, manage registration/removal carefully so replication never touches an invalid reference; Iris adds Subobject/fragment considerations [16,37].

Cheat resistance starts at the Server RPC boundary

Validate ownership, legal state transitions, ammo/rate/speed/distance, authoritative or historical spatial state, RPC frequency, and malformed values such as NaN, invalid enums, oversized arrays, and unknown IDs.

WithValidation failure can disconnect the caller [3]. Here, structural/protocol abuse is separated from ordinary latency/state-race rejection; that is a project policy, not a universal UE rule. Never embed service, admin, or database secrets in the player build.

Treat bad networks as a normal test environment

PIE with two local windows is not a networking test plan.

Also test separate processes, packaged Client/Server builds, different machines/VMs, real online-service accounts, travel/reconnect, and bot load.

Be careful with `DropUnreliableRPC` in UE 5.8.0

The official command reference documents NetEmulation.DropUnreliableRPC <RPCName> <0-100> [36]. Source inspection of Launcher UE 5.8.0 CL 55116800 found a contradictory percentage/block path, so 100 should not be used as proof that 100% of the target RPC was dropped. The public UE 5.8.1/5.8.2 hotfix lists do not identify a fix for that command [41,42].

Therefore, for deterministic acceptance tests, prefer a test-build-only project hook that explicitly skips the target call.

For example, a server-side test CVar can skip only ClientResolveShot while still updating the owner-only snapshot:

#if WITH_DEV_AUTOMATION_TESTS
static TAutoConsoleVariable<int32> CVarSkipClientResolveShotForTest(
    TEXT("game.NetTest.SkipClientResolveShot"),
    0,
    TEXT("1 skips ClientResolveShot in test builds."));
#endif

Then a property-only convergence test should prove that the client actually had predictions to resolve:

100 local predictions enqueued
Pending before snapshot apply == 100
Authority results == 100
ClientResolveShot received == 0
Snapshot source/epoch == test source/epoch
Snapshot contiguous prefix reaches the final issued sequence
Pending removed by snapshot == 100
Pending removed by timeout == 0
Pending after snapshot apply == 0
Displayed ammo == authoritative ammo
CVar/barrier/timeout settings restored during teardown

Freeze prediction timeout while the snapshot is deliberately blocked, otherwise timeout removal can create a false positive.

For transport degradation, PktLoss, PktIncomingLoss, PktDup, and PktOrder are useful [28], but inject duplicate keys directly to test gameplay-handler idempotence.

Use Networking Insights before changing architecture

Use Networking Insights/Network Profiler to identify expensive Actors, properties, and RPCs [29,30]. "Networking is heavy" is not actionable; "this UI array replicates every tick to every connection" is.

A practical starting matrix

These are evaluation starting points, not Unreal Engine limits.

Game shape	Baseline to prototype	Evaluate next
2-4 player co-op	Built-in Replication + Character Movement + Listen Server	Steam/EOS P2P/relay, whether host migration is worth it
8-16 player PvP	Dedicated Server + built-in Replication	GAS, bounded lag compensation, hosting platform
32-100 players / larger maps	Dedicated Server + spatial relevancy	Generic + Replication Graph or Iris, Fast Arrays, autoscaling
Very large Actor counts	Dedicated Server + bot load tests	Compare Replication Graph and Iris as separate NetDriver configurations

Implementation order I would use

Connect two clients to a minimal Dedicated Server C++ project.
Make movement, possession, death, respawn, HP, weapon, and ammo correct.
Split shooting into local prediction and authoritative resolution; add ownership checks, validation, and rate limits.
Fix late join and relevancy re-entry, then make latency/loss tests routine.
Add Steam/EOS login, sessions, and invites.
Run a packaged server remotely and load it with bots while measuring frame time and bandwidth.
Evaluate GAS, Replication Graph, or Iris only for measured problems.
Integrate allocation, health, and shutdown with the hosting platform.

Final takeaways

Start gameplay synchronization with UE Replication; treat Steam/EOS as online services and GameLift/PlayFab/Agones as server operations.
Let UCharacterMovementComponent handle normal Character prediction; replicate reconstructable state and use transient RPCs selectively.
Make shooting server-authoritative, keyed by source/epoch/sequence, with an immediate owner result plus owner-only replicated convergence state.
Keep predicted owner FX separate from confirmed remote FX, and make every entry point idempotent.
Add GAS, Replication Graph, Iris, or external networking SDKs only after fixed-version load tests show what problem you are actually solving.

References

uGUI or UI Toolkit? A Practical Unity 6.5 UI Selection Guide

GameDevToolLab — Wed, 09 Sep 2026 00:44:52 +0000

Choosing a UI system in Unity is not a simple "new UI Toolkit versus old uGUI" decision. Unity gives us three major options:

uGUI: GameObject- and Component-based runtime UI.
UI Toolkit: UXML, USS, and C# for runtime and Editor UI.
IMGUI: immediate-mode UI such as OnGUI.

Unity's 6.5 comparison still lists uGUI as the recommended general-purpose runtime UI, UI Toolkit as the runtime alternative, and UI Toolkit as the recommended Editor UI. That does not mean every runtime screen should use uGUI. A HUD, a 500-row inventory, a virtual joystick, a world-space panel, and an XR menu have different constraints.

This article uses two stages: first apply hard gates for version, render pipeline, input, XR, animation, and must-pass requirements; then compare only the surviving candidates using soft preferences and identical prototypes.

Version scope: rechecked September 9, 2026. The article targets Unity 6.5 and uses 6000.5.11f1, the latest 6.5 patch then listed in the Unity Download Archive. Unity 6.3 LTS is included where its world-space workflow differs. Input System is 1.20.0; XR Interaction Toolkit is 3.6.0. In production, pin ProjectVersion.txt and packages-lock.json and rerun the tests.

The short answer

Situation	First candidate	Why
HUD, virtual controls, Animator/Timeline-heavy presentation	uGUI	Strong Prefab, EventSystem, and animation workflows
Inventory, settings, search, large lists	UI Toolkit	`ListView`, USS, reusable styling, flexible layout
World-space or XR UI	Prototype after hard gates	Version and input route matter
Editor Window / Inspector	UI Toolkit	Unity's recommended Editor UI
Display-only runtime debug overlay	IMGUI can be acceptable	Small implementation for short-lived tools
Interactive Player debug UI	uGUI or UI Toolkit	Runtime IMGUI has Input System constraints
Mature uGUI project	Usually keep uGUI	Avoid migration and mixed-stack regression cost

A useful default is: gameplay-, GameObject-, and keyframe-heavy UI favors uGUI; data-, list-, and style-heavy UI favors UI Toolkit; Editor tooling favors UI Toolkit; IMGUI stays narrow. Hard gates override that default.

Apply hard gates before preferences

Hard gate	Check	If it fails
Unity version	6.3 world space uses `UIDocument`; 6.5 centers the workflow on `PanelRenderer`	Use documentation for the exact version
Render pipeline	UI Shader Graph in 6.5 is URP-only	Built-in/HDRP need another shader/material route
Input	Virtual Mouse is uGUI-only; standard tracked input is not UI Toolkit XR input	Use uGUI or the XRI-specific UI Toolkit path
Animation	PanelRenderer animation support is not general Timeline integration	Prefer uGUI if Timeline is mandatory
Runtime IMGUI	Input System-only Player input is incompatible with IMGUI	Test `Both` or move the tool
Product requirements	XR hardware, RTL, text scaling, accessibility, focus, performance budget	Do not adopt an unverified candidate

Record the Editor patch, packages, SRP, input route, build, and device before judging a result.

What each UI system is good at

uGUI: scene-oriented runtime UI

uGUI is built around Canvas, RectTransform, Image, TextMeshProUGUI, Button, Scenes, and Prefabs. It fits Inspector/Prefab/Animator/Timeline workflows and is a strong default for HUDs, reward popups, combat indicators, virtual sticks, and heavily animated menus. Its main risk is architectural: logic and update work can spread across Prefabs, MonoBehaviours, Layout components, and Canvases.

UI Toolkit: structure, style, and retained state

UI Toolkit uses UXML, USS, and C#. Its Flexbox-style layout is based on Yoga layout principles. It is attractive for inventories, filters, tables, settings, design systems, and repeated data; ListView is particularly useful for large reusable lists. UXML/USS are not identical to HTML/CSS: Panel Settings, events, atlases, supported properties, and runtime features remain Unity-specific and version-sensitive.

IMGUI: keep it narrow

private void OnGUI()
{
    GUILayout.Label($"Enemy Count: {_enemyCount}");
}

This is fine for a display-only diagnostic or small existing Editor tool. For product UI or a long-lived interactive Player tool, uGUI or UI Toolkit usually gives a safer input, styling, reuse, and accessibility path.

Runtime and Editor are different decisions

For runtime UI, uGUI and UI Toolkit are both candidates after the hard gates. Unity 6.5 still recommends uGUI overall, while UI Toolkit can fit data- and style-heavy screens better.

For Editor UI, start new Editor Windows and Custom Inspectors with UI Toolkit. A small stable IMGUI Editor tool does not need a rewrite. Editor IMGUI is also separate from Player OnGUI compatibility with the Input System.

Unity 6.3 and 6.5 use different world-space workflows

Area	Unity 6.3 LTS	Unity 6.5
Main world-space component	`UIDocument`	`PanelRenderer`
Size / pivot	UI Document `World-Space Dimensions`	Panel Renderer `World-Space Dimensions`
Multiple containers	UI Documents sharing Panel Settings	Panel Renderers sharing Panel Settings
Inspector references	Do not assume `VisualElementReference<T>`	Runtime `PanelRenderer` can use it
Legacy `UIDocument` access	UQuery / query-based	Still query-based
Editor `VisualElementReference<T>`	Not applicable	Not available
Animator / legacy Animation	Do not assume 6.5 support	PanelRenderer content has dedicated support
General Animation Clip / Timeline	Do not assume it	Comparison table still lists UI Toolkit as unsupported
World-space ordering	z distance, sibling `sortingOrder`, camera culling	Same; no 2D Sorting Layers integration

If you are on 6.3, do not search for a PanelRenderer from the 6.5 workflow. Use UIDocument.rootVisualElement and the 6.3 UI Document path.

VisualElementReference<T> is a 6.5 runtime feature for PanelRenderer; it is not a universal replacement for UQuery in Editor UI or legacy UIDocument setups.

Unity 6000.5.0f1 also added Animator/legacy Animation support for PanelRenderer content. That does not make UI Toolkit a general equivalent of uGUI's Animation Clip/Timeline workflow. If existing Timeline-authored UI is a hard requirement, favor uGUI unless a prototype proves the required path.

World-space UI Toolkit also does not integrate with 2D Sorting Layers. Use camera-relative z distance, sibling sortingOrder where applicable, and GameObject Layers plus camera culling. A design that depends on SpriteRenderer-style Sorting Layers needs a different plan.

World-space rendering is not XR controller input

A panel rendering in 3D space does not prove that a tracked VR controller can operate it.

Standard Input System tracked input

Input System 1.20 documents tracked UI input using InputSystemUIInputModule, tracked position/orientation actions, and TrackedDeviceRaycaster on a Canvas. That is the standard tracked uGUI route.

UI Toolkit is different: Input System 1.20 states that tracked-type XR input is not supported with UI Toolkit, and UI Toolkit does not support TrackedDeviceRaycaster because it performs its own raycasting.

InputSystemUIInputModule
  + trackedDevicePosition / trackedDeviceOrientation
  + TrackedDeviceRaycaster

Do not copy that Canvas route into UI Toolkit.

Panel Input Configuration

Unity 6.5 Panel Input Configuration handles Event Camera, Physics Layer, maximum distance, and EventSystem redirection, and can create helpers such as Panel Event Handler, Panel Raycaster, and World Document Raycaster.

Its screen-based pointer route converts screen position through an Event Camera into a world-space ray. By itself, it is not a tracked XR-controller solution. World Document Raycaster is also not the Input System's TrackedDeviceRaycaster.

XRI 3.6 dedicated UI Toolkit integration

This is what keeps UI Toolkit viable for VR. Pin XRI 3.6, import the World Space UI sample, follow that package's setup, and validate on hardware. Test Ray, Poke, both controllers, focus, colliders, modal behavior, and latency. If uGUI and UI Toolkit coexist, also test event routing and focus ownership.

The Unity 6.5 core manual and the XRI 3.6 sample can use different component arrangements. Follow the exact sample for the pinned package rather than mechanically replacing its components with names from newer core documentation.

Layout and information density

For a fixed combat HUD, uGUI anchors and RectTransforms are often enough, especially when the project already has Safe Area helpers, localization Prefabs, tween scripts, and animation assets.

For search, filters, multiple panes, reusable themes, text scaling, or hundreds of rows, prototype UI Toolkit first. ListView is built around reusable items; a naive uGUI list with hundreds of active GameObjects usually needs explicit pooling and careful layout design.

The real comparison is not "Flexbox versus RectTransform." It is the cost of the actual screen under realistic content.

Animation and shaders

If UI artists repeatedly tune Animator Controllers, Animation Clips, Timeline tracks, tween components, or UI particle assets, uGUI usually matches the production workflow better. UI Toolkit has USS transitions, class-driven state changes, and 6.5 PanelRenderer-specific animation, but that does not guarantee parity with an established uGUI pipeline.

Ask: who changes the animation, in which tool, and how often?

UI Shader Graph is URP-only

Unity 6.5 UI Shader Graph is a URP feature.

URP: prototype with the real masks, stencil behavior, blending, world-space setup, and target GPUs.
Built-in/HDRP: remove UI Shader Graph from the plan and validate another custom Material/Shader route.

Render Pipeline belongs in both the hard-gate table and every benchmark record.

Input

Virtual sticks, multi-touch gestures, EventSystem extensions, and Virtual Mouse generally push the decision toward uGUI. Input System 1.20's Virtual Mouse path is for uGUI rather than a general UI Toolkit/IMGUI cursor abstraction.

UI Toolkit also distinguishes pointer and navigation events. A pointer click raises ClickEvent; a gamepad submit uses navigation events. For a Button that should activate through either path, Button.clicked can be a better semantic hook than listening only for ClickEvent.

Prototype focus order, device switching, focus restoration after a modal, drag/scroll, IME, software keyboard, local multiplayer, and back/cancel routing.

Runtime IMGUI with the Input System

Input System 1.20 documents IMGUI as incompatible with the Input System package in the Player path. A display-only OnGUI overlay can still be useful, but an interactive Player debug menu should not silently assume Input System-only will work.

You can test Active Input Handling = Both, but then verify duplicate processing and performance. Long-lived interactive Player tools are usually better in uGUI or UI Toolkit. Editor IMGUI is a separate case.

Localization and accessibility

Do not choose from an English mockup alone. Where relevant, make maximum text length, RTL, fallback fonts, 200% text scaling, non-color-only states, keyboard operation, and platform assistive technology must-pass requirements.

Unity's Accessibility Hierarchy still needs deliberate names, roles, states, focus, and dynamic updates. Neither UI system makes accessibility automatic; validate on the target OS with the target assistive technology.

Performance: benchmark the update pattern, not the brand

Use the same device, data set, animation, render pipeline, and Graphics API.

For uGUI, Unity's optimization guidance emphasizes reducing expensive Canvas rebuilds, avoiding unnecessary layout work and raycast targets, and splitting Canvases by update behavior rather than arbitrary counts. Pool large repeated lists.

For UI Toolkit, test real ListView reuse, transforms, Dynamic Atlas, masks, transparency, and panel organization. Do not claim "more panels are always slower." Capture UI Toolkit-related Profiler data instead.

Predefine the metrics and aggregation: CPU time, GC allocations, draw calls, memory, first-open time, open spike, scroll p95/worst, and input response. A benchmark without a fixed measurement interval is not reproducible.

Mixing uGUI and UI Toolkit

Mixing is possible, but creates two focus systems, styling models, ordering rules, modal interactions, input-blocking concerns, and extra QA. Prefer screen/navigation boundaries: for example, "HUD is uGUI; inventory is UI Toolkit." Avoid alternating technologies inside one dialog.

Use a navigation service or presenter layer between systems rather than letting one hierarchy manipulate the other directly.

Keep game logic outside the View

A migration becomes expensive when the View owns inventory rules, purchases, networking, saves, analytics, and transitions. Put a small interface at the boundary:

public interface IInventoryView
{
    event Action<int> ItemSelected;
    void SetItems(IReadOnlyList<InventoryItemViewModel> items);
    void SetGold(int value);
}

A presenter can depend on this interface and game-side services. Migration is not free, but the blast radius is smaller when the View implementation changes.

A reproducible selection process

1. Freeze the test matrix

Record the exact Editor patch, package versions, SRP, Build Target, backend, Graphics API, device/OS, resolution, refresh rate, and thermal/power state. Different matrices are different tests.

2. Apply hard gates before soft preferences

Reject unavailable components, unsupported pipelines, unusable input routes, and failed product requirements first. Preserve evidence for rejected candidates. Only surviving candidates should be compared for team skill, authoring speed, layout, animation workflow, maintenance, and migration cost.

3. Resolve conflicts deterministically

Evaluate hard gates per candidate.
If the UI can split at a screen/navigation boundary, prototype that mixed design including focus, modal, ordering, input blocking, and transitions.
Otherwise compare uGUI and UI Toolkit on the same screen, build, data set, device, and input sequence.
Only candidates whose complete must-pass set is pass enter the final cost/performance comparison.

Pre-register the next action: unknown means retest; any fail means no-adopt; both candidates failing means revise-requirement; one passing candidate can be adopted; two passing candidates are compared against a predefined equivalence band. A tie requires a more discriminating fixture, then a pre-registered final tie-breaker such as migration cost. Do not invent a metric after seeing the result.

Prototype count is determined by coverage, not by a fixed number. Add fixtures for uncovered XR, RTL/text scaling/accessibility, mixed-stack focus/modal/back, shader/SRP, or mobile requirements. Every must-pass ID needs at least one procedure and one evidence artifact.

4. Keep candidate records and the ADR separate

A candidate record should be immutable and reproducible:

record-id: TR-UI-CMP-QUEST-UGUI-01
comparison-id: UI-CMP-QUEST-INVENTORY
candidate: ugui

environment:
  unity: 6000.5.11f1
  project-commit: <git-sha>
  build: {target: Android, backend: IL2CPP, sha256: <sha256>}
  rendering: {pipeline: URP, graphics-api: Vulkan}
  device: {model: Meta Quest 3, os: <version>, refresh-hz: 90}

fixture:
  dataset: {path: Tests/UI/inventory-500.json, sha256: <sha256>}
  input-sequence: "open -> scroll -> modal -> left/right ray -> poke"
  random-seed: 48151623

measurement:
  warm-up: 10
  trials: 30
  interval: "inventory-ready through end of scripted sequence"
  outlier-policy: "none; preserve all trials"
  aggregation: [median, p95, worst]

must-pass:
  - id: FUNC-FOCUS-001
    criterion: "Modal close restores previous focus"
    procedure: "Select item 3, open/close modal, continue navigation"
    expected: "Navigation resumes from item 3"
    actual: "30/30 restored focus"
    status: pass
    evidence: {path: Tests/UI/evidence/focus.mp4, sha256: <sha256>}

Each requirement needs criterion, procedure, expected, actual, pass|fail|unknown, and evidence. Any fail or unknown makes the candidate ineligible. Also preserve build configuration, package versions, fixture hashes, warm-up, measurement interval, trial count, aggregation, actual metric values/units, and whether each budget is an example or an approved threshold with its basis and approver.

The ADR is another file. It links all candidate record IDs/hashes and stores comparison scope, status, owner/date, alternatives, decision, rejection reasons, trade-offs, consequences, open issues, and revisit triggers:

adr-id: ADR-UI-QUEST-INVENTORY
comparison-id: UI-CMP-QUEST-INVENTORY
status: accepted
owner: UI Platform Lead

decision:
  action: adopt
  selected: ugui
  rationale: "All must-pass checks passed; uGUI won outside the predefined band"

revisit-triggers:
  - Unity/Input System/XRI upgrade
  - item count exceeds 1000
  - XR interaction requirements change

The test record answers what happened under a reproducible build. The ADR answers why this option won and when the decision must be reopened.

5. Let content authors test the workflow

Have UI designers or technical artists change copy, spacing, colors, and animation. Record merge conflicts, diff readability, what they can edit without programmer help, and time per representative change. Authoring cost is architecture cost.

Should an existing uGUI project migrate?

Ask whether migration cost can be recovered, not whether migration is technically possible. Benefits can include shared styling, better large-list workflows, flexible layouts, fewer Prefab conflicts, and shared runtime/Editor concepts. Costs include reimplementation, input, focus, animation, localization, analytics, plugins, and regression QA.

Migrate by screen boundary, preferably with an independent new screen. Avoid a broad rewrite when release is near, the current UI is stable, the alleged performance problem is unmeasured, a must-have path is unsupported, or mixed-stack QA is unfunded.

Final audit before adoption

Retest if any of these are true:

the team chose from "uGUI is obsolete" or "UI Toolkit is automatically faster" without measurement;
Unity 6.3 UIDocument and 6.5 PanelRenderer workflows are mixed;
PanelRenderer animation is treated as general Timeline integration;
UI Shader Graph is assumed outside URP;
UI Toolkit XR uses standard tracked input or TrackedDeviceRaycaster;
Panel Input Configuration alone is treated as the XR-controller solution;
Runtime IMGUI input or mixed focus/modal behavior is untested;
must-pass evidence, candidate records, thresholds, trial conditions, ADR, or revisit triggers are missing.

In practice: uGUI fits gameplay/keyframe-heavy UI; UI Toolkit fits list/layout/style/Editor-heavy UI; IMGUI fits narrow development UI. Production adoption should follow hard-gate success and reproducible target-device evidence.

References

How Optimized Is Unity Shader Graph in Unity 6? Where HLSL Still Wins

GameDevToolLab — Tue, 08 Sep 2026 02:11:03 +0000

A few years ago, I treated Shader Graph as a prototyping tool. When a shader became performance-sensitive, I often rewrote the bottleneck in HLSL because stage placement, precision, branching, reuse, and pass structure were easier to control by hand.

So how much of that old rule still applies?

This article uses Unity 6.3 LTS (6000.3) and Shader Graph 17.3 as the baseline: Shader Graph package information.

For ordinary URP and HDRP materials, starting with Shader Graph is a reasonable default. Do not rewrite a finished graph in HLSL just because it is a graph. Inspect the generated shader and measure the target GPU first.

If Shader Graph and handwritten HLSL express the same work in the same stage, with the same precision, samples, branches, passes, and pipeline features, both eventually enter the platform shader compiler. Their final code may be similar, though identical output is not guaranteed.

The useful question is therefore: what work is executed, in which stage, how many times, and across how many passes and variants?

This is not a fixed-hardware benchmark. It is a guide to what Shader Graph generates, what it does not optimize for you, and when profiling should push you toward Custom Function or handwritten ShaderLab/HLSL.

Three layers you should not confuse

Separate the graph, Unity-generated ShaderLab/HLSL, and the platform-compiled GPU code. Nodes are not runtime objects executed one by one; Shader Graph generates source, then normal shader compilation takes over.

That is why a 100-node graph does not mean 100 runtime function calls, and why a long generated file is not automatically slow. Pipeline templates, varyings, keywords, lighting integration, and helper code can inflate source length. Conversely, a tiny handwritten shader can still be expensive if it performs many texture reads, screen-space operations, or loops.

Compare generated passes/stages, texture samples, branch structure, varyings/register pressure, variant count, warm-up, and finally GPU time on the target device.

What Shader Graph optimizes today

Modern Shader Graph is best treated as a shader code generator and authoring system, not a runtime abstraction layer.

Stage	What it can do	What it will not do for you
Shader Graph generation	Trace dependencies, generate per-pass/per-stage code, emit fields/varyings	Redesign your algorithm, always choose the optimal stage, merge every redundant sample
HLSL compilation	Constant folding, dead-code elimination, inlining	Produce identical machine code on every GPU
Driver/backend	Generate target-specific instructions	Guarantee the same register/instruction count as handwritten HLSL

Unconnected nodes normally do not become runtime work

Shader Graph 17.3 collects nodes upstream from active Master Stack blocks/output nodes. Unity's implementation is visible in Generator.cs and GenerationUtils.cs. A disconnected experiment therefore does not automatically run every frame.

A connected Detail Map whose strength is 0 at runtime is different: unless the compiler can prove the path unnecessary, the sample may remain.

Code is generated per pass and stage

Targets/SubTargets define pass requirements. A simple-looking material may still participate in Forward, Depth, ShadowCaster, DepthNormals, MotionVectors, and other passes. Vertex deformation can therefore be repeated in shadow/depth passes.

Custom Interpolators move suitable work to the vertex stage

Custom Interpolators can pass vertex-calculated values to the fragment stage. A candidate must be vertex-valid, interpolation-safe, within the varying budget, and supported on every target. Shader Graph exposes up to 32 channels, each float4-equivalent, while real hardware/API limits can be lower. Check whether the value replaces an existing varying or merely adds another one.

Precision is controllable

Shader Graph supports Single and Half precision: Precision Modes. Start with Single for large ranges, accumulated time, and precision-sensitive UV math; test Half for normals, colors, directions, and limited-range masks. FP16 behavior varies by GPU/backend, so verify final code and image quality.

Branch node, static variants, and Dynamic Branch are different

Branch node: both inputs are evaluated

Unity's Branch node is effectively generated as:

void Unity_Branch_float4(float Predicate, float4 True, float4 False, out float4 Out)
{
    Out = Predicate ? True : False;
}

The True and False inputs are computed before the helper selects one. If both sides contain expensive samples or math, both sides remain work. See Branch node. It is useful for selecting values, not reliably disabling an expensive feature.

Shader Feature / Multi Compile: separate variants

Static keywords generate separate variants. Inside a compiled variant, an inactive path can be constant-folded or removed. Keep this separate from build stripping, which decides which variants survive into the Player.

Shader Feature generally makes unused combinations easier to strip; Multi Compile retains combinations more aggressively. See Unity's branching guidance and the Shader Graph keyword reference.

Dynamic Branch: one runtime program

A Shader Graph keyword defined as Dynamic Branch produces one runtime program with a uniform branch; Unity sends its state as a uniform integer for the draw: Keyword concepts.

So the keyword itself is not normally a per-pixel predicate. Classic wave/warp divergence is more relevant to a varying branch in custom HLSL, for example one driven by texture data. For Dynamic Branch keywords, measure branch overhead, both paths living in one program, register pressure, instruction-cache pressure, and path asymmetry.

Do not choose Dynamic Branch only because a value changes often. Static variants can also be selected at runtime if the required variants survived stripping. Compare variant count, switching granularity, path cost, warm-up, memory, and GPU time.

What Shader Graph still does not optimize for you

Duplicate work: repeated Sample Texture nodes are not guaranteed to collapse into one fetch. Reuse sampled results where possible; Sub Graphs are not memoization caches.
Expensive algorithms: triplanar mapping, POM, procedural noise, Scene Color/Depth, transcendental math, extra lights, and shadows remain expensive when their underlying work is expensive.
Overdraw: transparency, full-screen effects, particles, foliage, and decals can remain fill-rate problems. Alpha Clip has different behavior from blending but still interacts with discard, early depth, MSAA, and dense overlap.
Pipeline features: shadows, fog, decals, SSAO, motion vectors, and pipeline textures are not automatically "Shader Graph overhead." A handwritten comparison is unfair if it simply removes those features.
Variant explosion: ten independent two-way keywords already imply 1024 theoretical combinations before passes and pipeline keywords. This can hurt compile time, build size, loading, memory, and warm-up.

Think in three budgets: GPU execution, CPU/render submission, and build/load/variant cost.

When Custom Function or handwritten HLSL is worth it

Situation	Start with
Same passes/stages/samples/precision and already within budget	Keep Shader Graph
A local formula, loop, or special sample is awkward in nodes	Custom Function
Custom passes, unusual buffers, stencil/render-state control dominate	Handwritten ShaderLab/HLSL
The real issue is overdraw, pass count, lighting, or coverage	Fix rendering design first

Custom Function is useful when most of the graph is productive but one algorithm needs explicit HLSL. Check the official Custom Function Node rules for $precision, _half/_float suffixes, include guards, texture wrapper types, and Shader Model/API/Target restrictions.

Moving the same expression into a Custom Function does not automatically make it faster. The gain comes when handwritten code enables a real algorithm or execution-structure improvement.

A practical optimization workflow

Count texture samples before nodes. A graph with many arithmetic nodes can be cheap; dependent texture reads can dominate. Sample once and reuse where possible.
Separate affine from nonlinear vertex work. uv * tiling + offset, including uniform scrolling, is affine and can often move across interpolation without changing the result except for finite precision. sin, noise, normalization, and distance-based distortion are nonlinear; compare sparse meshes and the lowest LOD.
Choose precision from numeric range. Use Single for large ranges/accumulation; test Half for normals, colors, directions, and masks. Verify long runtimes and low-end targets.
Choose branching for its trade-off. Branch node = both inputs; Dynamic Branch = one uniform runtime program; Shader Feature/Multi Compile = variants; varying custom-HLSL branch = potential lane divergence.
Inspect every pass. Disable unnecessary transparency, Alpha Clip, Two Sided, Receive Shadows, and related features. Remember that vertex work can repeat in ShadowCaster/depth passes.
Avoid giant keyword-driven uber shaders when features barely overlap. Separate graphs or quality-specific graphs may be simpler.
Keep CPU and GPU shader optimization separate. The SRP Batcher improves CPU setup/state changes; it does not merge draw calls like GPU Instancing, nor does it directly remove fragment instructions.

How to compare Shader Graph and HLSL fairly

Keep the rendering specification identical: pipeline, renderer, surface mode, passes, lights, textures/samplers, precision, keywords, mesh, camera, resolution, Render Scale, MSAA, and quality settings. If the handwritten shader drops a feature or pass, you are measuring a specification change.

Use a Development Build for Unity Profiler and diagnostic logs. For final A/B decisions, use a product-like measurement build matching the shipping Graphics API, Render Pipeline Asset, quality, resolution, IL2CPP configuration, and shader stripping, with only the hooks needed by your GPU tool.

Unity 6.3's GPU Usage Profiler is unavailable or restricted on several configurations. Check the GPU Usage Profiler documentation and use RenderDoc, PIX, Xcode GPU tools, Android GPU Inspector, or platform-specific timing when appropriate. Frame Debugger is for draw/pass inspection, not GPU timing.

Warm caches. Control VSync, Dynamic Resolution, frame caps, power state, background work, and device temperature. Measure A→B and B→A; record sample count, median, p95, and thermal state. If the difference is below the noise floor, treat it as no meaningful difference. Amplified tests are useful for diagnosis, but make the final decision in the real scene. Measure GPU milliseconds, not only FPS.

Inspect generated code and variant logs

View Generated Shader / See Generated Code lets you check passes, stages, samples, keywords, precision, and varyings.

For per-shader build information, search Editor.log for Compiling shader; Unity reports variant counts before and after stripping: shader variant counts.

For URP aggregate stripping information in Unity 6.3:

Open Edit > Project Settings > Graphics and select the URP tab.
Under Additional Shader Stripping Settings, set Shader Variant Log Level to anything except Disabled.
Enable Development Build in File > Build Profiles and build.
Inspect the Shader Stripping section in Console or Editor.log.

With Export Shader Variants enabled, Unity documents Temp/graphics-settings-stripping.json and Temp/shader-stripping.json: URP shader stripping.

Two tiny generated-code tests

Use a fixed baseline such as Unity 6.3 LTS, Shader Graph 17.3, URP Unlit, Opaque, Alpha Clip off, Single precision.

Disconnected sample

Graph A samples one texture into Base Color. Graph B adds a second disconnected Sample Texture node. Search generated code for the second texture/sample reference. If it is absent, you have directly verified dependency-driven generation for that case. This does not prove that connected equivalent expressions are always merged.

Branch versus keyword

Create a heavy Detail path with an extra texture sample. Compare a Branch node, a Boolean Dynamic Branch keyword, and the same keyword as Shader Feature. Inspect branch/#pragma structure and build variant counts; verify whether the static OFF variant removes the Detail sample.

Practical examples

Scrolling water UVs: pure uv * scale + offset is affine and can be a good vertex-stage candidate. If you also move noise, sin, normalization, or distance-dependent distortion, compare the lowest LOD because those operations are nonlinear.
Detail Map on/off: Branch can still evaluate Detail upstream; Dynamic Branch keeps one runtime program; Shader Feature can remove the OFF path but needs variant management; Multi Compile retains combinations more aggressively.
Full-screen procedural noise: multiple noise octaves plus Scene Color distortion are expensive in both Shader Graph and HLSL. Try lower resolution, fewer octaves, smaller coverage, precomputed textures, LUTs, or approximations before rewriting. Handwritten HLSL matters when it enables real algorithmic changes such as early exits or specialized loops.

Decision flow

Build the same rendering specification in Shader Graph.
Inspect passes, stages, texture samples, branches, varyings, and variants.
Measure GPU time, image quality, loading, and stutter on the target device.
Fix sample reuse, stage placement, coverage, passes, and keyword design first.
Move only the remaining bottleneck to Custom Function or handwritten HLSL when the measured gain exceeds maintenance and portability cost.

For Unity 6.3 / Shader Graph 17.3, the useful shift from the old mindset is: Shader Graph can be the starting implementation; generated code and target-device profiling define the boundary where handwritten shader code becomes justified.

Release checklist

[ ] Product-like build: GPU time and image quality checked.
[ ] A/B tests use identical rendering specifications and conditions.
[ ] Caches warmed; median, p95, sample count, and thermal state recorded.
[ ] Generated code checked for samples, stages, branches, varyings, and passes.
[ ] Dynamic Branch keywords are not confused with varying per-pixel branches.
[ ] Static variant counts, stripping, and required runtime combinations verified.
[ ] Custom Interpolators checked for replacing versus adding varyings.
[ ] Half/Single verified on the target backend/GPU and against image quality.
[ ] Overdraw, Alpha Clip, lighting, and pipeline costs separated from authoring-format cost.
[ ] Any HLSL rewrite produces a repeatable gain larger than noise and maintenance cost.

References

Choosing the Right Real-Time Networking Stack for Unity in 2026

GameDevToolLab — Fri, 04 Sep 2026 06:54:03 +0000

When building an online game in Unity, the question is often framed as:

Should I use Photon, Netcode for GameObjects, FishNet, or Mirror?

That question is too small.

In 2026, there is still no single networking product that is optimal for every Unity game. The real decision is a stack: transport, netcode, authority model, session management, server hosting, and backend services.

For a GameObject-based action game that needs client prediction, Photon Fusion 2.1 is a strong first PoC baseline. If your priorities are Unity Gaming Services, DOTS/ECS, self-hosting, source access, or deterministic simulation, the starting point changes.

This article explains how to make that decision in production terms: latency, cheating, reconnection, hosting, bandwidth, operations, and total cost.

This article uses official documentation checked on August 31, 2026 as its factual baseline. SDK versions, pricing, licensing, and service availability can change, so re-check them before committing a production project.

What I mean by a real-time multiplayer game

The target is roughly this class of game:

2–32 players in the same session
continuously synchronized players, enemies, projectiles, or interactable objects
input latency that directly affects game feel
reconnects, host loss, and late joining that must be handled
co-op action, FPS/TPS, racing, or competitive action

If you only need turn-based play, leaderboards, chat, friends, or asynchronous PvP, you may not need a sophisticated state-synchronization netcode at all. A backend such as Nakama, PlayFab, or Unity Gaming Services may be the more important part of the architecture.

Do not treat “networking” as one product

A production multiplayer stack has at least five layers.

Layer	Responsibility	Examples
Transport	Packet delivery, reliability, connection path, secure channel integration	Unity Transport, Photon transport, UDP/WebSocket-based transports
Netcode	Replication, RPCs, input, prediction, interpolation, rollback	Fusion, NGO, Netcode for Entities, FishNet, Mirror
Session	Lobby, matchmaking, relay, connection metadata	Photon Realtime, MPS SDK, UGS Lobby/Relay/Matchmaker
Hosting	Dedicated-server allocation, startup, scaling, monitoring	GameLift, PlayFab MPS, Edgegap, Hathora, custom infrastructure
Backend	Authentication, persistence, inventory, ranking, result settlement	PlayFab, Nakama, UGS, custom APIs and databases

This is why “WebSocket or Photon?” is not a useful comparison. WebSocket is an application-layer protocol often used as a transport path in a game stack; Fusion is a netcode with prediction and simulation semantics.

A transport can move packets. It does not automatically give you prediction, snapshot interpolation, authority rules, lag compensation, reconnect restoration, or late-join state reconstruction.

Seven criteria that matter more than brand names

Criterion	What to decide
Prediction	Can local input run ahead and be reconciled against authoritative state? How much is built in?
Authority	Who is allowed to decide movement, hits, rewards, inventory, and match results?
Topology	Host, client-server, or distributed/shared authority?
Replication scale	Tick rate, visible objects, predicted physics, update frequency, interest management
Platforms	Mobile suspend/resume, WebGL constraints, console certification and invite flows
Team architecture	GameObject or ECS? Do not migrate architecture just because the networking SDK prefers it
Total cost	CCU, bandwidth, hosting, observability, operations, migration and maintenance work

A few terms used below: CCU is concurrent users, RTT is round-trip latency, SLO is a service-level objective, egress is outbound cloud traffic, and p95/p99 are percentile measurements.

Pick the synchronization model before the SDK

Most real-time games are built from three core synchronization models.

Snapshot replication

The authority sends periodic state snapshots, and remote clients interpolate between them. This is a natural fit for remote players, NPCs, doors, and many world objects.

The trade-off is bandwidth: higher update frequency improves responsiveness but increases traffic. Quantization, change detection, and interest management matter quickly.

Input prediction and resimulation

The local player applies input immediately, sends that input to the authority, then reconciles when authoritative state arrives. If needed, the client rewinds to the authoritative tick and resimulates to the present.

This is a strong fit for FPS, TPS, racing, and action games, but it requires simulation code that can be run again safely. External I/O, analytics, rewards, and one-shot side effects must not be mixed into replayable tick logic.

Deterministic lockstep with rollback

Peers advance from the same input stream and rollback when delayed input arrives. This can be excellent for fighting games, RTS, sports, and other deterministic simulations, but it usually requires stricter simulation constraints than ordinary MonoBehaviour/PhysX gameplay.

Real games are hybrids. Your local player may be predicted, remote players interpolated, cosmetic effects local-only, and economic rewards finalized by a backend.

My 2026 decision table

Option	Best fit	Main strength	Main caution
Photon Fusion	GameObject action, FPS/TPS, co-op	Prediction/resimulation, lag compensation, multiple topologies	Photon dependency, CCU/bandwidth cost, dedicated hosting is separate
NGO + MPS SDK	Unity 6, UGS-heavy co-op	Unity-first integration, Sessions/Relay/Lobby ecosystem	MPS Sessions requires Unity 6; advanced action prediction is not a turnkey system
Netcode for Entities	DOTS/ECS, many entities, dedicated servers	Ghosts, prediction, lag compensation	ECS commitment, learning curve, resimulation cost
FishNet	GameObject, source access, self-hosting	Prediction, server authority, transport flexibility	Custom license; surrounding infrastructure and QA remain your responsibility
Mirror	Existing codebases, MIT requirement, self-hosting	Snapshot interpolation, lag compensation, PredictedRigidbody	General prediction is still listed as Researching; PoC the exact physics/use case
Photon Quantum	Deterministic competitive games	Deterministic ECS and rollback	Separate simulation model from ordinary Unity physics/MonoBehaviours
Nakama	Backend-driven multiplayer	Auth, storage, matchmaking, chat, authoritative match loop	Not a drop-in 3D action-state netcode

Versions I used as the baseline

These are the specific versions/editor combinations checked for this article.

Product / stack	Version	Editor / delivery note
Photon Fusion	2.1.2 Stable	Unity 2021.3.45, 2022.3.45, 6.0.x, 6.3.x; console access has separate requirements
Netcode for GameObjects	2.13.2	Unity 6000.3; package manifest minimum is 6000.0
Multiplayer Services SDK	2.2.1	Unity 6.0 LTS+; `com.unity.services.multiplayer`
Netcode for Entities	1.14.2	Unity 6000.3 via UPM
Netcode for Entities core	6.5 / 6.6	Integrated with Unity 6000.5 / 6000.6 editor lines
FishNet	4.7.2R	Verify editor compatibility per release; custom source-available license
Mirror	v96.11.2	MIT; evaluate prediction maturity per feature
Photon Quantum	3.0.13 Stable	Unity 2021.3 LTS+; deterministic simulation environment
Nakama	Server v3.40.0 / Unity Client 3.21.1	Backend, not a transform-prediction netcode

For NGO and Netcode for Entities, do not confuse the broad product family with a specific package/editor combination. For example, NGO 2.13.2 is not something I would assume can simply be dropped into a Unity 2021/2022 project; older editors have their own package lines. Likewise, Netcode for Entities 6.5+ is tied to the corresponding Unity 6 editor line as a core package.

Primary references: NGO 2.13 changelog, Unity 6000.3 NGO, Unity 6000.3 Netcode for Entities, and the Unity 6000.6.0b9 release page.

When Fusion is a sensible first benchmark

I would start a GameObject action-game PoC with Fusion when all of these are acceptable:

movement, shooting, or physics needs client prediction;
Photon Cloud dependency and its pricing model are acceptable;
Host or client-server topology matches the product;
full source redistribution or unrestricted middleware reuse is not a hard requirement.

This is a comparison baseline, not an automatic production choice.

Fusion Host Mode is attractive for small PvE games because it can avoid dedicated-server compute cost. Server Mode is a better fit when match integrity matters. Shared Mode can reduce some topology friction for casual/mobile/WebGL use cases, but its authority model must not be treated as equivalent to a trusted dedicated server.

Photon provides Fusion Server Mode and the connection/session runtime. It does not automatically provide the infrastructure that builds, allocates, starts, scales, and monitors your Unity headless server fleet. That is a hosting/orchestration problem. See Photon’s Dedicated Server overview.

Console development also has separate access requirements. Photon’s Console Development Overview describes certification checks, platform-specific documentation, and native socket libraries. Authentication, invites, suspend/resume, cross-play, and platform certification still need device-level PoCs.

NGO + MPS SDK: best when Unity 6 and UGS are deliberate choices

Netcode for GameObjects is Unity’s GameObject/MonoBehaviour-oriented netcode. My current baseline is Unity 6000.3 + NGO 2.13.2.

The Multiplayer Services SDK Sessions requires Unity 6.0 LTS or newer. Sessions can automate host election, player join/leave handling, and network connection establishment. That does not mean it designs your gameplay state, authority model, session lifetime, migration payloads, or failure UX.

For existing Unity 2021/2022 projects, treat “stay on the editor-compatible NGO package” and “migrate to Unity 6 + current NGO + MPS Sessions” as separate estimates.

NGO can be a very good fit for small co-op games where UGS Authentication, Lobby, Relay, and Matchmaker are already part of the product. For highly latency-sensitive competitive action, I would PoC the actual movement and combat loop under 100–200 ms rather than assume anticipation features are equivalent to a complete rollback/resimulation architecture.

Netcode for Entities: use it when ECS is already the product architecture

Netcode for Entities provides Ghost snapshots, command streams, client prediction, rollback/resimulation, interpolation, and lag compensation in an ECS-oriented execution model.

Its strength is not “more players by magic.” You still need to control which ghosts are predicted, how often they update, and which clients receive them. Sending every entity every tick to every client will fail regardless of the framework.

I would choose it when DOTS/ECS and dedicated servers are already strategic decisions: large numbers of players, NPCs, projectiles, or units; data-oriented simulation; and a team that can profile prediction loops and server tick budgets.

I would not move a mature MonoBehaviour/Animator/PhysX/NavMesh project to ECS solely because the networking package looks attractive.

FishNet: strong for self-hosted GameObject stacks, but read the license correctly

FishNet offers server authority, prediction/reconciliation, NetworkTransform, observer systems, and transport choice. It can work well when you want to choose your own hosting and surrounding services.

However, do not describe it simply as “open source.” The current FishNet license permits game/content use and modification, while section 2.b restricts other networking-solution products from using, reverse-engineering, or implementing the FishNet software. Section 2.d explicitly says that exclusion does not apply to games developed with the software.

So separate normal game development from middleware/product reuse. If your plan includes forking, redistribution, an internal shared networking platform, a competing networking product, or FishNet-Pro distribution, get legal review of the current terms.

Self-hosting also means you own more of relay/NAT strategy, allocation, monitoring, DDoS considerations, upgrades, and regression testing.

Mirror: evaluate the current features, not the old reputation

Mirror remains relevant when you value an MIT license, existing assets, and self-hosting.

It has Snapshot Interpolation, Lag Compensation, and PredictedRigidbody. But the official project status still distinguishes feature maturity: snapshot interpolation is Stable, lag compensation is Beta, and general Prediction is Researching.

That does not make Mirror unsuitable for action games. It means the PoC must use the exact Unity version, transport, physics objects, character controller, abilities, knockback, and reconciliation requirements you expect to ship.

Quantum: deterministic does not mean “automatically cheat-proof”

Photon Quantum uses deterministic ECS and rollback. That can be a very good fit for fighting games, RTS, sports, and other simulations where replayability from input history is valuable.

But determinism is not the same as dedicated-server authority. Hidden information, fog of war, input validity, ranking, and reward settlement are separate security problems. Use the official Quantum Cheat Protection guidance to decide what is validated, what checksums can detect, and what must be verified or persisted elsewhere.

Nakama: backend first, not a replacement for action netcode

Nakama provides authentication, storage, matchmaking, chat, leaderboards, realtime sockets, and authoritative match handlers. It can fully own many card, board, or lower-frequency competitive games.

It is not, by itself, a drop-in replacement for a 3D action framework that predicts CharacterControllers, Rigidbodies, projectiles, and hitboxes. For a 60 Hz action game, pair it with a netcode or build a game-specific protocol deliberately.

Unity Multiplay changed: separate matchmaking from hosting

Unity’s directly provided Multiplay Game Server Hosting is marked deprecated as of April 1, 2026 in the Unity status notice.

That does not mean Matchmaker or the Multiplayer Services SDK disappeared. Unity’s game server hosting support documents an architecture where Cloud Code integrates with an external game-server hosting provider for allocation, session creation, and backfill.

A new design should therefore keep these responsibilities separate:

Authentication
   ↓
Matchmaker
   ↓
Cloud Code / allocation logic
   ↓
External game-server hosting
   ↓
MPS Session
   ↓
Netcode

The same principle applies to Fusion: netcode is not hosting.

Host Mode: the backend cannot magically make host-reported gameplay trustworthy

For small co-op games, a common design is:

Player-hosted match
   ↓
Backend
   ├─ authentication
   ├─ server-issued mission/reward rules
   ├─ eligibility and limit validation
   └─ capped provisional reward commit

This can be useful, but the participant acting as host owns State Authority and can modify the host process. Sending results to a backend does not prove that reported kills, drops, or clears actually happened.

Server-issued mission tokens, time windows, reward tables, and daily caps can verify eligibility and limit the maximum loss from cheating. They do not prove host-reported gameplay facts inside those limits.

If high-value rewards, ranking, or paid currency require stronger trust, move those facts behind a trusted authority: for example dedicated-server telemetry or another verifiable event source outside the player host’s trust boundary.

Send verifiable input or commands, not authoritative results

A client should not be trusted when it says:

“my position is X”
“I dealt 100 damage”
“this purchase succeeded”

For an action game, send movement, aim, buttons, and fire requests. The authority derives speed, cooldowns, ammo, collisions, and damage.

For a card or board game, raw device input is less useful. Send intent-level commands such as:

PlayCard(cardId, targetId)
UseSkill(skillId, targetId)
BuyItem(sku, quantity)

The authority validates ownership, turn/phase, cost, target, inventory, cooldown, and sequence, then derives the result.

The common principle is simple: the client should submit the minimum input/command that a trusted authority can validate and recompute.

Keep tick simulation replayable

For client-server prediction, gameplay code that affects authoritative results belongs in network ticks, not only in ordinary Update().

This is a conceptual Fusion Host/Server Mode example, not copy-paste production code:

public struct PlayerMoveInput : INetworkInput
{
    public Vector2 Move;
}

public sealed class NetworkPlayer : NetworkBehaviour
{
    private const byte MaxMoveReuseTicks = 2;

    [Networked] public int Hp { get; set; }
    [Networked] public NetworkBool IsStunned { get; set; }
    [Networked] private Vector2 LastAcceptedMove { get; set; }
    [Networked] private byte MissingMoveTicks { get; set; }

    public override void FixedUpdateNetwork()
    {
        if (!HasInputAuthority && !HasStateAuthority)
            return;

        // State that advances without player input must still tick.
        SimulateInputIndependentState(Runner.DeltaTime);

        Vector2 move;
        if (GetInput(out PlayerMoveInput input))
        {
            move = Vector2.ClampMagnitude(input.Move, 1f);
            LastAcceptedMove = move;
            MissingMoveTicks = 0;
        }
        else
        {
            MissingMoveTicks++;
            move = MissingMoveTicks <= MaxMoveReuseTicks
                ? LastAcceptedMove
                : Vector2.zero;
        }

        if (Hp <= 0 || IsStunned)
            move = Vector2.zero;

        SimulateMovement(move, Runner.DeltaTime);
    }
}

The important part is not the exact two-tick policy. It is that the policy is deterministic and explicit. Photon documents that GetInput() can occasionally fail even on the State Authority during packet loss or latency spikes.

Held input and edge input should not necessarily use the same missing-packet policy. Reusing a previous held movement state for a bounded number of ticks can be reasonable; inventing a new button-down edge from missing input is not.

Also keep external side effects out of replayable simulation. Do not call databases, HTTP services, anti-cheat services, analytics, or reward settlement directly from resimulatable tick code.

For economic or external effects, use a durable, retry-safe flow:

confirmed authoritative domain event
   ↓
durable event log / transactional outbox
   ↓  at-least-once delivery
worker / dispatcher
   ↓
backend with persistent idempotency key
   ↓
persisted result / retryable query
   ↓
apply only if match/player/revision is still valid

An “outbox” stored only in game-server memory or disposable local disk is not crash-safe. If the match state and outbox cannot be committed atomically, you still have a dual-write problem. Either make the durable event the source of truth, use a transactional boundary, or define how the match is invalidated/compensated after unrecoverable failures.

Design session lifetime and reconnection before polishing gameplay

A connection API returning success is not a session design.

Define the state transitions for create, join, ready, start, late join, temporary disconnect, reconnect, leave, result settlement, and destruction. Decide which record is authoritative when lobby, game server, and backend disagree.

Do not use a transient connection ID as the persistent player identity. Reconnect using an authenticated user identity plus match identity, with an expiring token that includes build/version and permissions. Invalidate the old connection when the new one is accepted.

Late joiners should receive scene/assets, current phase, and replicated state in a known order, then acknowledge readiness before spawning and accepting input.

Run a 1–2 week PoC with at most two candidates

Do not choose a multiplayer SDK from documentation alone.

A useful first timebox is one or two engineers, one to two weeks, and no more than two candidates. Build the same minimum slice in each:

real movement plus one important action such as dash/jump/dodge
shooting or melee, damage, death
one moving platform or pushable Rigidbody
match start/end, late join, disconnect, reconnect
headless build where relevant

Use the same gameplay and network conditions for every candidate.

Define pass/fail thresholds before testing

Examples:

Metric	Example acceptance rule
Reconciliation	At 100 ms RTT and 3% loss, p95 correction distance stays below your game-specific limit
Server tick	p99 tick time remains below 70% of the tick budget
Reconnect	p95 reconnect completes within the product target and restores authoritative state correctly
Bandwidth	Average billable bytes/sec per connection stays inside the business target
Allocation	Dedicated-server allocation success and cold-start p95 meet the SLO
Failure handling	Expired tokens, version mismatch, and region exhaustion fail explicitly and recover predictably
Result settlement	Crashes and duplicate submissions do not create missing or double-applied match results

Do not copy arbitrary values like “0.2 m correction” from another game. Derive thresholds from movement speed, match length, reconnect rules, platform constraints, and economic risk.

Network emulation should include not only RTT and random packet loss, but also jitter, burst loss, asymmetric uplink/downlink, packet reordering/duplication, temporary disconnects, host loss, backgrounding, different frame rates, and server tick stalls.

Cost: estimate from average CCU and billable traffic, not DAU alone

A rough average CCU estimate is:

average CCU
  ≈ DAU × sessions per day × average connected minutes / 1,440

For example, 10,000 DAU × 1.5 sessions × 20 minutes is roughly 208 average CCU.

Bandwidth is roughly:

monthly billable transfer
  ≈ average CCU × average billable bytes/sec per connection × seconds/month

Use peak CCU for capacity and server-count planning, but average usage for transfer estimates.

Then price each network leg separately:

client → relay and relay → host/server
host/server → client
game server → backend
cross-region and redundancy traffic

The same packet may be billable by multiple providers, while some hosting plans include certain bandwidth. Only remove a cost after verifying the provider’s pricing model. Relevant references include UGS pricing, Photon Fusion pricing, and Amazon GameLift Servers pricing.

Practical recommendation

In 2026, I would narrow a Unity real-time networking stack in this order:

decide GameObject vs ECS and the Unity/editor version you can actually ship;
choose where authority lives: host, dedicated client-server, or distributed/shared;
separate session, hosting, and backend responsibilities from netcode;
validate platform access, licensing, CCU/bandwidth, and operational cost;
compare the real movement/combat/reconnect slice under the same bad-network conditions.

If the game is GameObject-based, you accept Photon dependency and pricing, and you need Host or Client-Server prediction, Fusion 2.1 is a sensible benchmark candidate.

If Unity 6 + UGS integration is the priority, start with NGO 2.13.2 + MPS SDK. If DOTS/ECS is already the architecture, start with Netcode for Entities. If source access and self-hosting matter, compare FishNet and Mirror carefully under their actual licensing and feature-maturity constraints. If determinism is a core requirement, evaluate Quantum. Use Nakama primarily as a backend or authoritative match platform rather than as a drop-in transform prediction layer.

The key point is that “it connected” is not the success condition. Ship only after you have measurable acceptance criteria for 100–200 ms network conditions, reconciliation, authority and cheating, reconnect/late join, server allocation, bandwidth, and crash-safe result settlement.

Primary official references

Will HTTP/3 Make Unity Faster? Choosing HTTP for APIs, Asset Downloads, and Real-Time Networking

GameDevToolLab — Wed, 02 Sep 2026 06:19:56 +0000

Unity networking can look simple: call UnityWebRequest.Get(), wait, and parse. In production, protocol choice also affects concurrent APIs, Addressables, mobile packet loss, platform backends, CDNs, and real-time communication.

The practical default is:

Use normal protocol negotiation and treat HTTP/2 as the baseline. Evaluate HTTP/3 only where real-device measurements justify its integration and maintenance cost.

HTTP/3 is not automatically faster, and it does not determine action-game synchronization. This article separates APIs, asset delivery, and real-time networking.

Scope: Unity 6.3 through Unity 6.5. No benchmark numbers are claimed. Behavior depends on the Unity version, platform, package versions, server, and CDN. Compile against your actual package set and verify the negotiated protocol on real devices.

Recommendations by workload

Workload	Start with	Consider HTTP/3 when
Login, inventory, billing, and master-data APIs	`UnityWebRequest` with normal negotiation; HTTP/2 where available	Many independent calls run over lossy mobile links and measurements show a gain
Multiple small or medium assets	HTTP/2, CDN caching, sensible bundle layout, and bounded concurrency	Packet loss stalls unrelated parallel downloads
One large patch	HTTP/2 plus Range requests, resume logic, and integrity checks	Reconnects or network changes improve measurably with QUIC
Background download	Native OS download APIs through a plugin	Background execution and reliable resume justify native integration
Real-time state, chat, or presence	Photon, Unity Transport, WebSocket, or gRPC as appropriate	Evaluate separately from HTTP REST

Do not hard-code one version everywhere. Normal negotiation allows HTTP/2 with HTTP/1.1 fallback for incompatible devices, proxies, or networks.

HTTP/1.1, HTTP/2, and HTTP/3

HTTP/1.1: compatible, but awkward for many parallel requests

HTTP/1.1 runs over TCP and reuses connections with keep-alive, but cannot flexibly multiplex independent responses. Clients therefore open several connections to one host, which matters for many startup APIs or small bundles.

It remains sufficient for a few calls, server-dominated workloads, or one stable large transfer. Its main value is compatibility and rollback.

HTTP/2: the current baseline

HTTP/2 also uses TCP, but multiplexes streams in one connection. HPACK reduces repeated headers, helping APIs with similar authorization and cookies. Unity benefits from fewer TCP connections and efficient multi-file CDN delivery.

HTTP/2 still inherits TCP-level head-of-line blocking. If a TCP packet is lost, bytes after the gap wait for retransmission, so unrelated streams on that connection can pause.

HTTP/3: QUIC reduces interference between streams

HTTP/3 uses QUIC over UDP, integrates TLS 1.3, and provides independent streams. It can reduce cross-stream blocking, shorten setup, and better tolerate Wi-Fi-to-cellular transitions—especially on lossy mobile links.

The HTTP/3 specification explains how independent QUIC streams avoid the TCP-level cross-stream blocking that can affect HTTP/2.

Three caveats matter:

One huge file is not automatically faster. It normally uses one stream, where loss still requires retransmission. The advantage is clearer when catalogs, bundles, and APIs run together.
UDP/443 is not universal. Networks may restrict it, so HTTP/2 or HTTP/1.1 fallback is mandatory.
0-RTT has replay implications. Do not blindly resend purchases, currency spending, or loot-box draws. Use operation IDs, idempotency keys, deduplication, and status queries.

HTTP/3 over QUIC
    ↓ unavailable or unsuitable
HTTP/2 over TLS/TCP
    ↓ unavailable
HTTP/1.1 over TLS/TCP

This is a conceptual relationship. An implementation may race candidates rather than wait for every failure serially.

What version does Unity actually use?

Specifications are only half the answer. Unity's effective backend changes by editor version and platform.

Unity 6.3: HTTP/2 by default on supported platforms

Unity's 6.3 documentation says UnityWebRequest uses HTTP/2 by default on supported platforms, listing Android, Embedded Linux, Linux, macOS, PS4, PS5, UWP, and Windows.

That list does not prove that every unlisted platform lacks HTTP/2. iOS and web builds need separate verification.

Android also exposes a rollback switch:

Project Settings > Player > Android > Other Settings > Configuration
Force UnityWebRequest via HTTP/1.1

Use it for diagnosis or compatibility, not as the normal default.

Unity 6.5: forcing HTTP/1.1 or HTTP/2

Unity 6.5 adds UnityWebRequest.httpForcedVersion. Its default is HttpForcedVersion.NotForced, which leaves selection to negotiation. The available enum values stop at HTTP/2; there is no HTTP/3 value.

using System;
using System.Collections;
using UnityEngine.Networking;

public static class ApiClient
{
    public static IEnumerator GetJson(
        string url,
        Action<string> onSuccess,
        Action<long, string> onError)
    {
        using var request = UnityWebRequest.Get(url);
        request.timeout = 15;
        request.SetRequestHeader("Accept", "application/json");

#if UNITY_6000_5_OR_NEWER
        // Already the default; explicit here to show the intended policy.
        request.httpForcedVersion = HttpForcedVersion.NotForced;
#endif

        yield return request.SendWebRequest();

        if (request.result == UnityWebRequest.Result.Success)
            onSuccess?.Invoke(request.downloadHandler.text);
        else
            onError?.Invoke(request.responseCode, request.error);
    }
}

This demonstrates version policy, not a production client. Production code still needs cancellation, deadlines, bounded retries, status handling, size limits, authentication refresh, redirects, request IDs, and idempotency.

Force HTTP/1.1 or HTTP/2 only for comparison or rollback; permanent forcing can disable fallback. Unity's 6.5 release notes include an HTTP/2 fix for POST bodies above 600 KB, so test the exact editor patch you ship.

Unity 6.5 also adds UnityHttpMessageHandler for HttpClient and gRPC. It neither enables HTTP/3 automatically nor makes gRPC an action-game transport; test the exact IL2CPP, AOT, generated-code, and package combination.

iOS: separate client path, TLS, and HTTP/3 capability

URLSession on iOS 15 and later supports HTTP/3 and discovers support through Alt-Svc or DNS HTTPS resource records. That alone does not prove every Unity request uses URLSession.

For Unity 6.5, keep three facts separate:

The release notes state that iOS UnityWebRequest moved from NSURLSession to libcurl.
Mbed TLS concerns TLS processing; it is not the HTTP client replacing URLSession.
HttpForcedVersion has no HTTP/3 enum, so verify negotiation rather than infer it from iOS support.

Verify ordinary UnityWebRequest through CDN/server logs, ALPN, or platform instrumentation. For URLSession background transfer, resume integration, or an intentional HTTP/3 path, use a Swift or Objective-C plugin. See Apple's HTTP/3 in your app.

Unity Web: the browser chooses

Unity web builds route UnityWebRequest through the Fetch API. The application cannot directly open arbitrary TCP or UDP sockets, so the browser and hosting environment choose HTTP/2 or HTTP/3.

Verify CDN/origin support, CORS headers, the browser developer tools' Protocol column, and browser support for WebSocket, WebRTC, or WebTransport. Unity's web networking documentation describes the Fetch and CORS constraints.

Workload 1: ordinary game APIs

A slow login call may spend most of its time in the server. Measure the entire path:

DNS + connection + TLS + request upload + server wait
+ response download + decompression/JSON + main-thread application

HTTP/2 and HTTP/3 can improve connection reuse, concurrency, and loss behavior. They do not fix slow database queries, billing calls, lock contention, oversized JSON, or expensive deserialization.

A practical optimization order is:

measure server time per endpoint;
remove unnecessary startup dependencies and merge calls where sensible;
reduce redundant fields and headers;
use suitable compression;
verify HTTP/2 negotiation and connection reuse;
evaluate HTTP/3 only if mobile-network problems remain.

Multiplexing does not mean “send everything at once.” Group calls as boot-critical, first-screen, or deferrable, and shorten the critical path without overloading the server.

Retry according to semantics. A failed GET can often use bounded exponential backoff. Blindly retrying a purchase or currency spend can execute it twice. Idempotency remains an application concern under every HTTP version.

Workload 2: Addressables and asset delivery

Fix delivery design before adding HTTP/3

Slow Addressables downloads can come from too many tiny bundles, oversized bundles, duplicated dependencies, a distant CDN, broken cache keys, unsuitable compression, excessive concurrency, or weak catalog consistency.

HTTP/3 does not repair hundreds of tiny bundles or a URL scheme that always misses cache. First make bundle layout and CDN delivery work well over HTTP/2, then compare HTTP/3 under realistic packet loss.

Bound concurrency even with HTTP/2

Multiplexing does not remove receive buffers, decryption, decompression, storage writes, hash checks, or main-thread spikes when many downloads finish together. CDNs also limit concurrent streams.

Addressables exposes WebRequestQueue.SetMaxConcurrentRequests(int). Six is only a starting point; compare values such as four, six, and eight for your devices and bundle sizes.

using System;
using UnityEngine;
using UnityEngine.AddressableAssets;
using UnityEngine.Networking;
using UnityEngine.ResourceManagement;

public static class AddressablesNetworkSettings
{
    private static bool s_configured;
    private static Action<UnityWebRequest> s_existingOverride;

    [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.BeforeSceneLoad)]
    public static void Configure()
    {
        if (s_configured)
            return;

        s_configured = true;
        WebRequestQueue.SetMaxConcurrentRequests(6);

        s_existingOverride = Addressables.WebRequestOverride;
        Addressables.WebRequestOverride = ApplySettings;
    }

    private static void ApplySettings(UnityWebRequest request)
    {
        s_existingOverride?.Invoke(request);

        if (request.timeout <= 0)
            request.timeout = 60;

        // Keep the default NotForced behavior and allow negotiation.
    }
}

Do not erase an override that adds signed URLs, authorization, certificates, or telemetry. Compose with it or centralize settings. The guard only covers one AppDomain; Domain Reload settings, multiple bootstraps, and tests still need one owner before the first Addressables operation.

These APIs are from Addressables 2.9, listed as 2.9.1 in Unity 6.5.0f1. Other Unity 6.3–6.5 projects may differ; check manifest.json, packages-lock.json, and compile your shipped versions.

When HTTP/3 is promising for assets

Test HTTP/3 when iOS and Android dominate, users download over 4G/5G, dozens of files run together, packet loss stalls unrelated work, network transitions are common, the CDN supports UDP/443 and HTTP/3 advertisement, and p95/p99 completion time is a business problem.

Tail latency, failure rate, and retry volume can matter more than the mean. An internal Wi-Fi-only application with few requests may never recover the plugin cost.

One large file: prioritize resume and integrity

A multi-gigabyte patch needs application-level resume:

write to a temporary file;
resume through Accept-Ranges: bytes and a Range request;
verify identity with an ETag or content hash;
validate the final hash or signature;
atomically replace the production file and retain the last known-good version on failure.

HTTP/3 does not manage resume position, corrupted partial data, or catalog consistency. Apple's resumable file transfer session covers Range requests, ETags, background transfer, and URLSession resume behavior.

Should you add native iOS or Android plugins?

Ask whether measured gains justify another stack, not merely whether a plugin supports HTTP/3. Native integration adds C# bridging, cancellation, buffers, cookies, caches, certificates, build dependencies, and platform-specific debugging. Ordinary REST APIs should start with Unity's negotiated HTTP/2 path.

A plugin is reasonable when tail latency or failures improve materially, background delivery is mandatory, or content delivery is central. The CDN must support UDP/443, TLS 1.3, ALPN h3, Alt-Svc or DNS HTTPS records, and HTTP/2 fallback.

iOS: URLSession

Apple's API provides negotiation, caching, Range requests, background transfer, and resume. For a known-capable service, assumesHTTP3Capable can let URLSession attempt HTTP/3 before receiving an advertisement, but it does not guarantee h3 and still permits fallback. For large files, write to a native temporary file and report progress, path, and validation instead of copying a huge byte[] through Unity.

Unity C#
  ├─ StartDownload(url, destination, requestId)
  ├─ Cancel(requestId)
  └─ OnProgress / OnComplete / OnError
             ↓
iOS plugin: URLSessionDownloadTask / background URLSession
             ↓
CDN: HTTP/3 → HTTP/2 → HTTP/1.1 fallback

Short-lived signed URLs can avoid duplicating token state. URLSession and UnityWebRequest do not automatically share pools, cookies, cache, certificates, retries, or metrics. Native-enable a narrow path and assign ownership of authentication, cache deletion, and diagnostics.

Android: HttpEngine or Cronet

Stack	Protocols	Main condition
HttpEngine	HTTP/1.1, HTTP/2, HTTP/3 over QUIC	API 34 or S Extensions 7+
Cronet via Google Play services	HTTP/1.1, HTTP/2, HTTP/3 over QUIC	Requires Play services; small size impact
Embedded Cronet	HTTP/1.1, HTTP/2, HTTP/3 over QUIC	Bundled implementation; documentation cites about 8 MB
OkHttp	HTTP/1.1 and HTTP/2	Not an HTTP/3 option

Use HttpEngine when the minimum platform permits it. For wider coverage, Play services Cronet plus fallback may work; Embedded Cronet is relevant where Play services are unavailable.

Reuse engine instances. Running them beside UnityWebRequest splits connection pools, DNS behavior, caches, cookies, certificates, and metrics. Migrate one high-value path first.

Workload 3: real-time networking is a separate decision

Faster REST is not 60 fps state synchronization. Real-time selection depends on reliability, stale-data handling, ordering, authority, prediction, rollback, tick rate, bandwidth, NAT traversal, reconnect, matchmaking, and platform restrictions.

HTTP/3 uses QUIC, but an HTTP/3 REST endpoint is not automatically a game-state transport.

Requirement	Candidate
Turn-based or asynchronous play	HTTP API with normal negotiation
Lobby, friends, and light notifications	WebSocket or Photon Realtime
Chat	WebSocket, Photon Chat, or gRPC streaming
Co-op or competitive action	Photon Fusion, Unity Transport, or dedicated UDP
Typed bidirectional streams or telemetry	gRPC streaming
Browser low-latency communication	WebSocket, WebRTC, and possibly WebTransport

Photon does not replace asset HTTP. A common architecture uses HTTP APIs for account data, HTTP plus a CDN for bundles, and Photon for matchmaking and sessions. Web builds also have browser transport restrictions.

Photon protocol and ports

gRPC is typed RPC, not a universal action-game transport. HTTP/2 streaming fits internal APIs, telemetry, and typed streams, but not necessarily stale positions that should be dropped. Test channel reuse, stream limits, AOT, and generated code.

gRPC performance best practices

Benchmark protocol choices correctly

Do not decide from one Editor run on wired Ethernet. Test real iOS and Android devices under Wi-Fi, 4G/5G, 50–150 ms latency, 1–3% loss, network transitions, and cold versus reused connections. Record CDN HIT/MISS, local cache state, and first versus repeat download so cache effects are not mistaken for protocol gains.

Compare TTFB, time to first playable, all-files completion, p50/p95/p99, failures, retries, retransferred bytes, CPU, peak memory, battery, and network-change recovery—not only the mean.

“HTTP/3 enabled” at the CDN is not proof of use. Verify with CDN/origin logs, ALPN, iOS Instruments, the browser Protocol column, or Cronet's getNegotiatedProtocol(). Do not assume ordinary UnityWebRequest exposes h2 or h3.

Practical selection flow

Separate APIs, asset delivery, and real-time state.
Establish HTTP/2 negotiation; fix dependencies, bundle layout, caching, Range support, and idempotency first.
Measure latency, loss, transitions, tail latency, and failures on real devices.
Prototype a native stack on one high-value path, and adopt it only when gains exceed maintenance and diagnostic cost.

Keep HTTP/2 fallback even after a successful HTTP/3 rollout.

Conclusion

For most Unity projects:

use normal negotiation and HTTP/2 for ordinary APIs, with HTTP/1.1 as fallback;
fix CDN caching, bundle layout, concurrency, Range requests, hashes, and resume logic before changing transports;
use HTTP/3 only where mobile loss, parallel work, or network transitions show a measured benefit;
add URLSession, HttpEngine, or Cronet only when native integration is justified;
choose Photon, Unity Transport, WebSocket, or gRPC from real-time requirements, not the HTTP version number.

There is rarely a reason to move every request to HTTP/3 at once. Build a correct HTTP/2 path, measure real devices, and native-enable only the traffic where the data supports it.

A follow-up can compare Photon, Unity Transport/Netcode, WebSocket, gRPC, WebRTC, WebTransport, and custom UDP by reliability, tick model, authority, browser support, cost, and operations.

Primary references

Unity CLI + AI Agents: A Safe Observe-Act-Verify Workflow

GameDevToolLab — Tue, 01 Sep 2026 06:15:10 +0000

Checked against the official documentation available on September 1, 2026. Unity CLI and com.unity.pipeline are experimental, so the installed version's unity --help is the authoritative reference.

Why writing C# is not enough

AI agents can edit Unity C#, but an edit is not a verified result. Unity may need to recompile and reimport assets; tests, Console errors, Scene state, Play Mode, or a built Player may also need inspection.

A useful agent must close this loop without asking a human to copy every result from the Editor:

Observe -> Plan -> Act -> Wait -> Verify -> Recover

Unity's standalone CLI and com.unity.pipeline provide an official execution layer for that loop. The focus here is a restricted workflow for inspection, mutation, and verification—not a complete command reference or vendor-specific CI file.

Separate the three command-line surfaces

Unity developers often call three different systems “the CLI.”

Traditional Editor arguments

The Editor executable still accepts -batchmode, -projectPath, -executeMethod, -runTests, and related flags:

Unity.exe -batchmode -quit `
  -projectPath "C:\Projects\MyGame" `
  -executeMethod BuildCommand.BuildWindows `
  -logFile "C:\Logs\unity-build.log"

This remains useful for headless jobs, but it launches an Editor process and locks the project; it does not control an already-open Editor.

The standalone Unity CLI

The newer unity executable manages Editors, modules, authentication, projects, builds, tests, and connected instances without opening the Hub UI.

unity editors --installed --format json
unity install 6000.3.7f1 -m android
unity open ./MyGame

It supports human, TSV, JSON, NDJSON, and GitHub-oriented output, with structured stdout, diagnostic stderr, and exit codes for automation.

Unity Pipeline

After adding com.unity.pipeline, the CLI can discover commands registered by a running Editor or configured Development Player:

unity status --json
unity command
unity command get_console_logs --json

Surface	Best fit
Editor arguments	Existing headless automation
Standalone CLI	Editor/module management, projects, builds, tests, CI
Pipeline	Fast inspection and controlled operations in a running Editor or Player

Design a small capability surface

The agent reaches Unity through shell commands or the CLI's MCP server:

AI agent -> unity command / unity mcp -> Unity CLI
         -> com.unity.pipeline -> Editor / Development Player

Do not expose unlimited Unity API access as the default. Expose named commands with declared arguments and structured results. Your team can review that surface, restrict paths, require previews, and decide which operations need human approval.

Start with these three commands:

unity --version
unity status --json
unity list --json

They identify the CLI version, connected instance, and registered schemas. Next, add a read-only project_health command. After each C# edit, require proof of final compilation, passing targeted tests, zero new Console errors, and no forbidden asset changes.

Record versions and install deliberately

As of September 1, 2026, the current documented releases are Unity CLI 1.0.0-beta.6 and com.unity.pipeline 0.5.0-exp.1. Store a compatibility record:

Unity Editor: 6000.x.yf1
Unity CLI: 1.0.0-beta.6
com.unity.pipeline: 0.5.0-exp.1
Verified: 2026-09-01

A beta channel is not a version pin. Make CI fail when unity --version differs, and avoid unconditional upgrades inside jobs.

Install the CLI through an official route, then inspect it:

# macOS/Linux
curl -fsSL https://public-cdn.cloud.unity3d.com/hub/prod/cli/install.sh \
  | UNITY_CLI_CHANNEL=beta bash

# macOS/Linux alternative
brew install --cask unity-cli

unity --version
unity doctor

# Windows
winget install Unity.CLI

Installing modules with a new Editor and adding them later are separate operations:

unity install 6000.3.7f1 -m android webgl
unity install-modules -e 6000.3.7f1 -m android webgl

Open the project, install Pipeline, wait for compilation, and inspect the connection:

cd /path/to/MyGame
unity auth login
unity pipeline list-versions
unity pipeline install --package-version 0.5.0-exp.1
unity status --json
unity list --json

Confirm the exact Pipeline flags with local help. Pipeline-driven Editor control requires Unity 6.0 LTS or later. With several Editors open, run from the intended project or specify it explicitly:

unity command --project-path /path/to/MyGame editor_status --json

Old examples using --instance <host:port> are stale.

Direct commands or MCP?

Use unity command and unity eval directly when the agent can compose shell commands reliably. Unity's current guidance notes that this path is faster and consumes fewer model tokens than MCP.

Use the built-in MCP server when the client cannot run arbitrary commands or has a stronger tool-calling workflow:

unity mcp configure --list
unity mcp configure <client>
unity skill install <agent-name>

Client configuration, approval UI, working directory, and inherited permissions vary. MCP is transport and discovery, not authorization; keep policy in the repository and CI.

Unity has deprecated the MCP server bundled with the in-Editor AI assistant package in favor of unity mcp; third-party MCP packages are a separate choice.

Turn every task into a closed loop

Observe and Plan

Capture the initial Editor state, open Scenes, dirty state, and existing errors. Define success mechanically: a named test passes, new-error count is zero, only approved files changed, and Scene or Prefab edits are forbidden unless requested.

unity status --json
unity command editor_status --json
unity command list_open_scenes --json
unity command get_console_logs --json

Act and Wait

Use normal file editing for persistent C#, typed [CliCommand] methods for repeatable Unity operations, and eval only for narrow investigation. Start and completion can be different states:

recompile -> recompile_status
run_tests -> test_status
build -> build_status

Domain reloads, imports, and target switches can briefly interrupt the connection. Retry only within a bounded policy and poll a final status rather than treating request acceptance as success.

Pipeline 0.5.0-exp.1 also supports detached jobs and live progress:

unity command <long_command> --detach --json
unity job status <job-id> --json
unity job wait <job-id> --json

Detached jobs survive a client timeout, but remain serialized and do not survive domain reload.

Verify and Recover

Match evidence to the artifact:

Change	Required evidence
C#	final compile state, targeted tests, new Console errors
Scene/Prefab	serialized values, dirty/save state, Git diff
UI	Play Mode state, Game View capture, logs
Runtime	Player state, Player log, exceptions, capture
Build	final result, output path, artifact checks

Report commands, exit codes, test counts, new errors, changed paths, and outputs. “It looks fixed” is not evidence.

Add a typed read-only command

A custom command is a static method marked with [CliCommand]; arguments use [CliArg]. The example below depends on UnityEditor, so place it in an Editor folder or Editor-only Assembly Definition.

#if UNITY_EDITOR
using System.Linq;
using Unity.Pipeline.Commands;
using UnityEditor;
using UnityEngine;
using UnityEngine.SceneManagement;

public static class ProjectHealthCommands
{
    [CliCommand("project_health", "Return editor and scene state.")]
    public static object GetProjectHealth()
    {
        var scenes = Enumerable.Range(0, SceneManager.sceneCount)
            .Select(SceneManager.GetSceneAt)
            .Select(s => new
            {
                s.name,
                s.path,
                s.isLoaded,
                s.isDirty
            })
            .ToArray();

        return new
        {
            unityVersion = Application.unityVersion,
            isPlaying = EditorApplication.isPlaying,
            isCompiling = EditorApplication.isCompiling,
            buildTarget = EditorUserBuildSettings.activeBuildTarget.ToString(),
            scenes
        };
    }
}
#endif

unity command project_health --json

MainThreadRequired defaults to true; keep it unless the implementation is independent of main-thread-only Unity APIs. Return fields, not prose, so an agent can assert them. At the Pipeline layer, a response conceptually resembles:

{
  "success": true,
  "command": "project_health",
  "result": {
    "isCompiling": false,
    "scenes": [{ "name": "Main", "isDirty": false }]
  },
  "executionTimeMs": 3,
  "error": null
}

For failures, add stable codes such as INVALID_ARGUMENT, NOT_FOUND, or PRECONDITION_FAILED to your own result contract. Runtime commands belong in a Player-included assembly with no UnityEditor dependency.

Keep `eval` for investigation

eval is useful for a one-off read:

unity eval \
  "return UnityEngine.Object.FindObjectsByType<UnityEngine.Light>(UnityEngine.FindObjectsSortMode.None).Length;" \
  --json

It is close to arbitrary C# execution. Never send model-generated or prompt-derived code to it without review. Limit it to short, human-inspected, read-only expressions and do not concatenate untrusted external strings.

One-off inspection          -> eval
Repeated read               -> read-only CliCommand
Scene/Prefab authoring       -> typed CliCommand + Undo
Destructive asset operation -> dry_run + confirm + Git/backup
Stable CI task              -> unity run --command / unity test / unity build

Preview mutations and separate approval

dry_run and confirm are per-command conventions; Pipeline does not provide a central approval service.

using System.Linq;
using Unity.Pipeline.Commands;

[CliCommand("normalize_enemy_layers", "Preview before applying.")]
public static object NormalizeEnemyLayers(
    [CliArg("confirm", "Apply changes.")] bool confirm = false,
    [CliArg("dry_run", "Preview only.")] bool dryRun = false)
{
    var targets = FindTargets();

    if (dryRun)
        return new
        {
            status = "dry_run",
            count = targets.Length,
            samplePaths = targets.Take(10).Select(x => x.AssetPath),
            warnings = targets.Length > 50
                ? new[] { "Target count exceeds 50." }
                : System.Array.Empty<string>(),
            requiresApproval = targets.Length > 20 ||
                targets.Any(x => x.IsSceneOrPrefab)
        };

    if (!confirm)
        throw new System.ArgumentException(
            "Pass confirm=true or dry_run=true.");

    ApplyWithUndo(targets);
    return new { status = "applied", changed = targets.Length };
}

FindTargets and ApplyWithUndo are project-specific placeholders.

unity command normalize_enemy_layers --dry_run true --json
unity command normalize_enemy_layers --confirm true --json

Return a count, representative paths, warnings, and approval requirement instead of every target. This limits token usage and accidental disclosure of unpublished asset paths.

confirm=true is only an intent flag. It does not record who approved what, so it cannot replace a human approval log or pull-request diff. Automatic application should be limited to approved generated paths, no deletion, strict count limits, a clean dedicated worktree, and deterministic verification.

Require human approval for Scenes, Prefabs, ProjectSettings, Packages, deletion, bulk overwrites, external I/O, signing, or publishing. AuthoringUndoScope can group registered Scene/Object Undo operations, but AssetDatabase, Package Manager, and some settings changes need Git or backup recovery. Restrict file I/O to approved roots and reject absolute paths and .. traversal.

Parse JSON and exit codes at every layer

Use JSON for a buffered result and NDJSON for machine-readable progress:

unity editors --installed --format json
unity install 6000.3.7f1 --format ndjson
unity command project_health --json

There are two result layers:

Layer	Typical fields
Standalone CLI	`success`, `command`, `data`, `errors`, `warnings`
Pipeline response	`success`, `command`, `result`, `executionTimeMs`, `error`

Conceptually, the Pipeline response can be nested under CLI data. That is a parsing model, not a promise that every experimental build has an identical shape. Capture your installed version's actual unity command ... --json output before freezing a parser.

Unity CLI 1.0.0-beta.6 documents these process exit codes:

Code	Meaning
0	Success
1	General error
2	Invalid usage or arguments
3	Authentication or authorization failure
4	Required configuration or context missing
6	Primary operation failed; `unity test` produced no verdict
7	Unity service unreachable after retries; safe to retry
8	`unity test` ran and one or more tests failed; do not retry as infrastructure
130	Ctrl+C / SIGINT
143	SIGTERM or runner timeout

unity command project_health --json \
  1> result.json \
  2> error.log

Evaluate success in order: process exit code, outer CLI success, inner Pipeline success, then domain results such as failed tests or build output. Exit code 0 only proves success at the process layer.

Separate the running Editor from clean CI

A running Editor is ideal for current Scene state, Console inspection, targeted tests, small authoring operations, Play Mode, and exploratory reads. Use a fresh process and workspace for pull requests, full suites, deterministic generation, and release builds.

The same registered command can run headlessly:

unity run \
  --project-path ./MyGame \
  --command validate_release_assets \
  --json

Connect to a Development Player

Runtime connectivity targets Windows, macOS, or Linux standalone Development Builds, not release builds. Mobile, console, and WebGL are outside this article's scope.

Add Pipeline > Runtime Pipeline Manager to a startup Scene GameObject.
Enable enableInBuilds; normally keep autoStart enabled and port 0.
Make and launch a standalone Development Build.
Wait for its runtime descriptor.
Put --runtime or --runtime-path immediately after command.

unity command --runtime MyGame.exe runtime_status --json
unity command --runtime-path "C:\Builds\MyGame" runtime_status --json

Runtime server code is compiled only into Development Players. enableInBuilds=true does not create a release-build backdoor. Keep custom runtime commands in a Player assembly and return structured state—Scene, position, gameplay state, exception count—alongside logs or captures.

Local-only still requires security controls

Pipeline binds to local loopback and authenticates with a bearer token from a descriptor file. Let the CLI handle discovery. A custom HTTP client should use 127.0.0.1 explicitly because localhost can resolve to IPv6 ::1, which is unreliable on the relevant Mono HttpListener path.

The agent still has repository and shell access. Use a dedicated branch or worktree, inspect git status, and expand permissions from read-only inspection to narrowly scoped mutations.

Treat logs, captures, descriptor files, credentials, signing material, IDs, and unreleased art as sensitive; define what may reach a cloud model.

Put the operational rules in AGENTS.md:

## Unity workflow rules

- Use ProjectSettings/ProjectVersion.txt as the Editor version source.
- Run unity status and project_health before changes.
- Check git status before touching Scenes, Prefabs, or settings.
- Run dry_run first; dry_run is not approval.
- Require human approval or PR review for Scenes, Prefabs,
  ProjectSettings, Packages, deletion, and bulk updates.
- Use eval only for reviewed, read-only investigation.
- After C# edits, wait for compilation, run targeted tests,
  and prove that new Console error count is zero.
- Never sign or upload a release.

Common failure modes

No Editor found: check unity status --json, unity editors running --json, unity pipeline list --json, compilation state, and working directory.
Command missing: the method must be static, compile successfully, and live in the correct Editor or Player assembly.
Stale flags: read unity --help, command-specific help, and unity list --json after upgrades.
Temporary disconnect: bound retries and poll final status after domain reload, import, target switch, or the Pipeline 0.5 startup settling state.
False test success: request acceptance is not a passing suite; poll test_status or inspect the NUnit report.
Unsaved Scene: report dirty state and make saving a separate explicit operation.
Undo gap: use previews, Git, and backups for AssetDatabase, packages, and settings.

A staged adoption plan

Read: status, hierarchy, Console, test list, and project_health.
Verify: bounded compile waits, targeted tests, Play Mode, and captures.
Author narrowly: typed commands with preview, limits, approval, Undo, and Git diffs.
Inspect runtime: combine Development Player state, logs, exceptions, and captures.

The goal is a small command set with explicit preconditions, side effects, outputs, and recovery paths.

Conclusion

Unity CLI integration matters when it turns an AI edit into a verified engineering operation. Separate the standalone CLI, traditional Editor arguments, and Pipeline. Use eval only for narrow investigation, promote repeated work into typed commands, and require every task to observe, act, wait, and verify.

Combine dry_run, confirm, limits, Undo, Git, and human approval instead of trusting one safety mechanism. Keep the fast running-Editor loop separate from clean CI, and treat local help plus captured JSON as the source of truth for the experimental versions you run.

Begin with read-only project_health; expand only after the agent can prove the before-and-after state.

DEV Community: GameDevToolLab

Unity 6.3 Memory Management: When to Use GC, Destroy, and Dispose

Introduction

1. Choose the cleanup method by acquisition, not just type

2. Why memory remains even with garbage collection

Assigning null removes one reference

List<T>.Clear() does not discard capacity

Dispose is not another name for GC

3. What Destroy does—and does not—destroy

GameObject destruction is separate from asset cleanup

Unity's == null does not only mean “no C# reference”

Putting everything in OnDestroy is not enough

4. Track the Materials, Meshes, and Textures you create

Some getters can create instances

Example: destroy only the Material you explicitly cloned

5. Match Addressables acquisitions with releases

Release relinquishes an acquired reference

Example: release a screen's acquisition even during loading

Do not confuse ordinary Instantiate with InstantiateAsync

A zero reference count does not guarantee an immediate memory drop

6. Unloading a scene is not the same as unloading unused assets

UnloadSceneAsync does not unload every asset

UnloadUnusedAssets is not a universal “free everything” button

Direct asset and AssetBundle unloading also requires ownership

7. Manage NativeArray ownership alongside its final Job dependency

Respect the allocator's lifetime

Example: dispose only after the Job completes

Copying the struct does not duplicate the allocation

8. GPU resources need more than dropping C# references

RenderTexture Release and Destroy have different roles

Return GetTemporary resources with ReleaseTemporary

Explicitly clean up GraphicsBuffer and ComputeBuffer

Discard CPU copies only when you no longer need CPU access

9. Events, async operations, and pools can retain resources

A long-lived event publisher can retain its subscribers

Cancellation and resource cleanup are separate operations

Pools retain objects for reuse; returning is not final cleanup

10. Verify cleanup by returning to the same state

GC Alloc and leaks measure different problems

Distinguish used, reserved, and OS-reported memory

A repeatable measurement procedure

Narrow the investigation by symptom

Conclusion: decide ownership before choosing a cleanup API

References

UE5 Shader Optimization: Materials, Custom HLSL, and Global Shaders with RDG

Start with the simplest layer that meets your needs

Separate three kinds of shader cost

1. Runtime GPU work

2. Compilation and shader permutations

3. First-use PSO hitches

Profile outside the Material Editor

1. Establish whether the GPU is the bottleneck

2. Read Material Stats and Platform Stats

3. Use Shader Complexity and Quad Overdraw as clues

Material optimizations worth investigating first

Check blend mode, screen coverage, and overdraw

Evaluate texture access and arithmetic separately

Move suitable UV calculations to the vertex stage

Material Instances do not automatically remove instructions

Use Material Functions to improve maintainability

Inspect Substrate statistics and the GBuffer format

What “writing a shader in code” means in UE5

1. Custom Material Expression

2. .ush, .usf, and Global Shaders

3. Mesh Material Shaders and custom mesh passes

Custom HLSL example: a rounded-rectangle mask

Add a Global Compute Shader through a plugin

Folder layout

Build.cs

Map the shader directory

Write the HLSL

Register the Global Shader and add the RDG pass

What to optimize in this example

Decide between a Custom expression and a Global Shader

Stay with a Custom expression when the material model fits

Use a Global Shader when you need independent GPU work

Extend the renderer when the mesh pipeline itself must change

Design permutations and PSOs deliberately

Recompile and debug during development

A practical optimization checklist

Assigning `null` removes one reference

`List<T>.Clear()` does not discard capacity

`Dispose` is not another name for GC

3. What `Destroy` does—and does not—destroy

Unity's `== null` does not only mean “no C# reference”

Putting everything in `OnDestroy` is not enough

`Release` relinquishes an acquired reference

Do not confuse ordinary `Instantiate` with `InstantiateAsync`

`UnloadSceneAsync` does not unload every asset

`UnloadUnusedAssets` is not a universal “free everything” button

7. Manage `NativeArray` ownership alongside its final Job dependency

RenderTexture `Release` and `Destroy` have different roles

Return `GetTemporary` resources with `ReleaseTemporary`

2. `.ush`, `.usf`, and Global Shaders

`Build.cs` dependencies