DEV Community: GameDevToolLab

Does Unity Really Need DI? Keeping Zenject, Choosing Reflex, and Comparing VContainer

GameDevToolLab — Mon, 03 Aug 2026 11:33:13 +0000

Introduction

As a Unity project grows, dependencies become harder to see and replace. Typical signs are more GameManager.Instance calls, repeated scene lookups, and input, networking, save, analytics, or billing code that cannot be swapped without changing its callers.

Dependency injection, or DI, addresses these problems by moving construction and lifetime management to explicit composition boundaries.

Zenject and its fork Extenject were the best-known Unity DI containers for years. As of July 26, 2026, the latest Zenject release is 9.2.0 from May 2020, while Extenject has been quiet since its 9.3.1 prerelease in July 2022.

Reflex 14.3.1 was released in June 2026 and VContainer 1.19.0 in July 2026. This article uses Unity 6-era APIs and describes the libraries as they existed on July 26, 2026.

Keep Zenject or Extenject in an existing project if it is stable.

For a new project, evaluate Reflex first.

Compare VContainer when you need its broader lifecycle features; use manual DI when the project is small.

Zenject is not suddenly unusable. The concern is that a DI container affects scene startup, prefab creation, lifetimes, editor tooling, generated code, and IL2CPP builds. For a new multi-year project, maintenance matters as much as convenience.

DI is not the same as using interfaces

DI means that an object receives dependencies instead of constructing them internally.

public sealed class PlayerMoveService
{
    private readonly IPlayerInput _input;

    public PlayerMoveService(IPlayerInput input)
    {
        _input = input;
    }
}

The composition root can create IPlayerInput and pass it to PlayerMoveService. This is already DI; a container is optional.

Manual construction is often clearer for a small graph. A container becomes useful when the project needs consistent registration, scopes, disposal, and scene-aware object creation. DI should expose dependencies, not hide them behind a global resolver.

Why Unity makes DI more complicated

Plain C# objects can use constructor injection. Unity adds MonoBehaviour, scenes, prefabs, Inspector references, and callback order.

A practical split is:

Plain C# classes: constructor injection
Scene MonoBehaviour components: method or field injection
References local to one prefab: SerializeField
Runtime-created prefabs: a project-owned factory plus explicit injection

Do not move every reference into DI. Buttons, labels, and child transforms are usually clearer in the Inspector. DI is most useful for networking, save data, input, time, randomness, purchases, logging, and analytics.

`Awake` and dynamic prefabs

For ordinary scene objects, Reflex intends to inject before Awake and OnEnable when a ContainerScope exists. Do not assume the same behavior for altered script execution order, additive or asynchronous loading, or manually instantiated prefabs.

An active prefab runs Awake and OnEnable during Instantiate; later injection cannot change that. A safe project-wide rule is to keep Awake self-contained and begin DI-dependent work from Initialize or StartAsync.

Model lifetimes explicitly

Singleton: one shared instance
Scoped: one instance per container
Transient: one instance per resolution

API clients may belong in the root scope. Battle score, waves, and enemy collections usually belong to a scene scope. DI is valuable because it makes lifetime and disposal boundaries explicit, not because it creates more singletons.

Why Zenject became popular

Zenject addressed Unity-specific problems through contexts, installers, initialization and tick interfaces, factories, pools, SignalBus, validation, subcontainers, and prefab injection. Its feature set and documentation made it a natural default.

The cost appears when application code directly depends on DiContainer, PlaceholderFactory<T>, SignalBus, ITickable, or IInitializable. Replacing the container then requires redesigning factories, events, update loops, and startup order.

Keep container-specific conveniences near the composition boundary.

Is Zenject still usable?

Yes, especially in an existing project.

Existing projects

Do not rewrite a stable foundation only because upstream development is quiet. Migration can affect scene startup, prefab ownership, factories, pools, signals, tests, Addressables, and IL2CPP stripping.

Keeping Zenject is reasonable when current builds are continuously tested, the team can patch or fork it, and the project already relies on Zenject-specific features. “Unmaintained” should trigger risk assessment, not an automatic rewrite.

New projects

The justification is weaker. Unity has continued to change editor APIs, IL2CPP, code generation, and Unity 6 internals since the last main Zenject release. Reflex and VContainer have shipped recent compatibility updates.

A DI package touches scenes, generated code, reflection, editor tools, and build pipelines. Choosing Zenject for a new multi-year project means accepting that your team may become its effective maintainer.

Is Zenject too slow?

The Reflex README publishes a benchmark that resolves a transient object with a four-level dependency chain 10,000 times.

Environment	Reflex	Zenject	VContainer
Android / Mono	4.9 ms / 54.7 KB	34.4 ms / 503.9 KB	20.3 ms / 70.3 KB
Android / IL2CPP	4.0 ms / 140.6 KB	15.8 ms / 1,000 KB	4.2 ms / 140.6 KB
Windows / Mono	0.7 ms / 140.6 KB	5.6 ms / 1,000 KB	1.9 ms / 140.6 KB
Windows / IL2CPP	1.4 ms / 140.6 KB	6.2 ms / 1,000 KB	3.0 ms / 140.6 KB

Each cell is time / GC allocation. See the current Reflex performance table.

This is a Reflex-published benchmark, not an independent test. It measures resolution throughput, not scene scanning, initial container construction, player size, or a complete startup path.

Within this workload, Reflex is faster and allocates less than Zenject. That may matter when resolving many transient objects at startup, but it does not make Zenject unusable. DI should normally resolve at composition boundaries, while gameplay uses already-injected references.

If a project resolves thousands of dependencies every frame, redesigning that path matters more than replacing the container.

Why Reflex is a strong default for new projects

Reflex provides a relatively small Unity-focused DI surface instead of reproducing every Zenject feature. As of July 2026 it includes root and scene containers, three lifetimes, lazy and eager resolution, multiple injection styles, factories, manual scopes, runtime GameObject injection, a debugger, and a Roslyn Source Generator.

It does not depend on runtime code emission and targets IL2CPP and WebGL. Version 14.3.1 also continued Unity 6 compatibility work.

Recent releases do not guarantee future health. Inspect issue response, contributor concentration, community knowledge, and whether your team can diagnose failures without upstream help.

Keep application-facing factories and events behind project-owned abstractions:

public interface IEnemyFactory
{
    EnemyView Create(EnemySpawnParameter parameter);
}

Only the composition root should know about Reflex's Container or RegisterFactory. The DI package should assemble the architecture, not become it.

Installing Reflex

This article uses the Reflex 14.x API. Older examples may use AddSingleton, AddScoped, or AddTransient, so check the package version.

In Unity Package Manager, select Add package from git URL:

https://github.com/gustavopsantos/reflex.git?path=/Assets/Reflex/#14.3.1

Pin a release tag and check Reflex Releases before adoption.

Create ReflexSettings directly under Assets/Resources with Create > Reflex > Settings. For application-wide registrations, create a RootScope prefab and add it to those settings. For each DI-enabled scene, create GameObject > Reflex > SceneScope, which adds a ContainerScope component.

Registering plain C# classes

using UnityEngine;

public interface IPlayerInput
{
    Vector2 ReadMove();
}

public sealed class UnityPlayerInput : IPlayerInput
{
    public Vector2 ReadMove()
    {
        return new Vector2(
            Input.GetAxisRaw("Horizontal"),
            Input.GetAxisRaw("Vertical"));
    }
}

public sealed class PlayerMoveService
{
    private readonly IPlayerInput _input;

    public PlayerMoveService(IPlayerInput input)
    {
        _input = input;
    }

    public Vector3 CalculateVelocity(float speed)
    {
        Vector2 move = _input.ReadMove().normalized;
        return new Vector3(move.x, 0f, move.y) * speed;
    }
}

The service does not know the Unity input API and can use a test implementation of IPlayerInput. The sample uses the legacy Input Manager only to stay small.

using Reflex.Core;
using Reflex.Enums;
using UnityEngine;

public sealed class GameplayInstaller : MonoBehaviour, IInstaller
{
    public void InstallBindings(ContainerBuilder builder)
    {
        builder.RegisterType(
            typeof(UnityPlayerInput),
            new[] { typeof(IPlayerInput) },
            Lifetime.Singleton,
            Resolution.Lazy);

        builder.RegisterType(
            typeof(PlayerMoveService),
            new[] { typeof(PlayerMoveService) },
            Lifetime.Scoped,
            Resolution.Lazy);
    }
}

Lifetime.Singleton: one instance shared by the registering container and its children
Lifetime.Scoped: one instance per container
Lifetime.Transient: a new instance per resolution
Resolution.Lazy: create on first use
Resolution.Eager: create while building the container

Injecting a `MonoBehaviour`

using Reflex.Attributes;
using UnityEngine;

public sealed class PlayerView : MonoBehaviour
{
    [SerializeField] private CharacterController _controller;
    [SerializeField] private float _speed = 5f;

    private PlayerMoveService _moveService;

    [Inject]
    private void Construct(PlayerMoveService moveService)
    {
        _moveService = moveService;
    }

    private void Update()
    {
        Vector3 velocity = _moveService.CalculateVelocity(_speed);
        _controller.Move(velocity * Time.deltaTime);
    }
}

The controller and speed are prefab-local configuration, so they stay in the Inspector. The input-dependent service is injected.

If Construct is not called, check that the scene contains a SceneScope or ContainerScope, the scene was loaded through the expected path, and PlayerMoveService is registered in that scene or a parent scope.

For production code, validate injection during explicit initialization before the view joins the update loop.

Registering a `ScriptableObject` or existing instance

Use RegisterValue for an existing settings asset:

[CreateAssetMenu(menuName = "Game/Player Move Settings")]
public sealed class PlayerMoveSettings : ScriptableObject
{
    public float Speed = 5f;
}

public sealed class GameplayInstaller : MonoBehaviour, IInstaller
{
    [SerializeField] private PlayerMoveSettings _settings;

    public void InstallBindings(ContainerBuilder builder)
    {
        builder.RegisterValue(
            _settings,
            new[] { typeof(PlayerMoveSettings) });
    }
}

RegisterValue creates a singleton registration. If the value implements IDisposable, Reflex disposes it with the container, so avoid duplicate ownership by another SDK or scope.

Dispose is not UnityEngine.Object.Destroy; Unity objects still follow scene, prefab, and explicit Unity ownership rules.

Avoid many raw string or numeric registrations. Reflex has no direct WithId equivalent, so use small types such as ApiBaseUrl and AssetBaseUrl to prevent accidental wiring.

Do not turn `Resolve` into a Service Locator

Passing Container through application code and calling Resolve<T> hides the class's real dependencies and forces tests to construct a container.

Inject the services directly:

public sealed class BattleService
{
    private readonly ISaveDataRepository _saveData;
    private readonly IAnalytics _analytics;

    public BattleService(
        ISaveDataRepository saveData,
        IAnalytics analytics)
    {
        _saveData = saveData;
        _analytics = analytics;
    }
}

Limit container access to composition roots, installers, DI-aware factories, and framework boundaries. Microsoft's DI guidelines recommend the same approach.

When explicit resolution is necessary, Single<T> detects duplicate registrations. Resolve<T> returns the last valid registration. Use IEnumerable<T> or distinct contracts when multiple implementations are intentional.

Source Generator and IL2CPP

Reflex supports IL2CPP without runtime code emission and provides a Roslyn Source Generator.

For generated field, property, or method injection, add SourceGeneratorInjectable and make the type public partial:

[SourceGeneratorInjectable]
public partial class PlayerView : MonoBehaviour
{
    [Inject]
    private void Construct(PlayerMoveService moveService)
    {
        _moveService = moveService;
    }
}

For nested types, every containing type must also be public partial.

Source generation does not remove every AOT limitation. The Reflex README notes a possible ExecutionEngineException for constructor-injected IEnumerable<T> when required IL2CPP code is missing.

Test early with desktop and Android IL2CPP, production stripping settings, iOS Xcode generation when relevant, and Addressables-created scenes and prefabs.

Creating dynamic prefabs safely

Scene objects can be injected by SceneScope. Runtime prefabs should go through one project-owned factory. Reflex provides GameObjectSelfInjector and the GameObjectInjector APIs.

The exact implementation changes with Addressables and pooling, so this is conceptual code:

public sealed class EnemyViewFactory : IEnemyViewFactory
{
    private readonly EnemyView _prefab;
    private readonly Transform _parent;

    public EnemyViewFactory(EnemyView prefab, Transform parent)
    {
        _prefab = prefab;
        _parent = parent;
    }

    public EnemyView Create(Vector3 position)
    {
        EnemyView view = Object.Instantiate(
            _prefab, position, Quaternion.identity, _parent);

        Container container =
            _parent.gameObject.scene.GetSceneContainer();

        GameObjectInjector.InjectRecursive(
            view.gameObject, container);

        view.Initialize();
        return view;
    }
}

Keep container-specific types inside the factory and choose the container that represents the object's actual scene or child scope.

Recommended rules:

do not use DI dependencies in Awake or OnEnable,
keep create -> inject -> initialize -> join gameplay,
inject pooled instances once and reset them on reuse,
reconsider pool sharing when the parent scope changes,
keep Addressables handles and release responsibility in the factory or pool.

SetActive(false) after creation cannot undo callbacks that already ran, and GameObjectSelfInjector cannot guarantee every component's relative Awake order.

VContainer is the main alternative

VContainer 1.19.0 remains actively maintained. It provides LifetimeScope, source generation, PlayerLoop integration, pure C# entry points, UniTask and ECS integration, diagnostics, async-scene child scopes, and keyed registration.

These features matter when DI should coordinate async startup, Entities, or a pure C# update loop. They are not requirements for every GameObject project.

Decision point	Reflex	VContainer
Direction	Small Unity-focused DI surface	DI plus lifecycle and entry-point integration
Scene injection	SceneScope injects the scene	Explicit component registration is central
Pure C# entry points	Project-owned when needed	Interfaces such as `IStartable`
UniTask integration	Separate from DI core	Official integration
Keyed registration	Use distinct types	Supported

In the Reflex-published Android IL2CPP benchmark, Reflex records 4.0 ms and VContainer 4.2 ms. The difference is too small to choose by ranking alone.

Compare registration style, PlayerLoop requirements, lifetime design, team experience, and debugging needs in a small prototype.

Manual DI is also valid

For a small game or isolated feature, direct construction may be safer than adding a container:

private void Awake()
{
    var input = new UnityPlayerInput();
    var moveService = new PlayerMoveService(input);
    _playerView.Initialize(moveService);
}

This is only a minimal composition example. A real project can place async startup in a separate bootstrap flow.

Manual DI is easy to inspect, has no container-specific AOT behavior, and is unaffected by third-party maintenance. Add a container when the dependency graph, scopes, or disposal requirements justify it.

Mapping Zenject concepts to Reflex

Zenject / Extenject	Reflex or project-owned replacement
`ProjectContext`	RootScope
`SceneContext`	Scene `ContainerScope`
`MonoInstaller`	`MonoBehaviour, IInstaller`
`BindInstance`	`RegisterValue`
`AsSingle` / `AsTransient`	Singleton / Transient lifetime
`AsCached`	Re-evaluate as scoped or singleton
`NonLazy`	`Resolution.Eager`
`PlaceholderFactory`	Project factory plus `RegisterFactory`
`SignalBus`	C# events, R3, or a project EventBus
`MemoryPool`	`UnityEngine.Pool` or a project pool
`IInitializable` / `ITickable`	Explicit bootstrap and project update loop
SubContainer	Child scopes or scene hierarchy

Do not mechanically rename APIs. Lifetimes, subscription disposal, and update order must be reconsidered.

A safer migration order is:

Stop adding new Zenject-specific types.
Wrap factories and events in project-owned interfaces.
Remove Zenject references from plain C# domain code.
Separate composition roots by scene or feature.
Add startup and disposal tests.
Replace installers and contexts last.

Avoid long-term coexistence and never let both containers create the same singleton.

Common DI failures in Unity

Creating an interface for everything

Not every value object or calculation class needs an IFoo. Prioritize external I/O, time, randomness, input, networking, storage, purchases, and analytics.

Using the container as a global variable

Calling Container.Resolve<T>() everywhere hides dependencies and makes tests require a configured container.

Resolving every frame

private void Update()
{
    var input = _container.Resolve<IPlayerInput>();
}

Inject once and keep the reference. Fixing this design usually matters more than choosing a faster container.

Storing scene state in root singletons

Root scope suits APIs, authentication, master data, logging, and analytics. Battle state and screen-specific presenters normally belong to a scene scope.

Expecting DI to define async startup order

DI resolves dependencies; it does not define the correct order for loading master data, save files, and scenes. Use an explicit bootstrap flow.

Conclusion

DI is not about eliminating every singleton or creating an interface for every class. It exposes dependencies, centralizes composition, and makes root, scene, and prefab lifetimes explicit.

Zenject can remain a reasonable foundation for a stable existing project. Its latest main release dates from 2020, however, and Extenject has also been quiet since 2022. For a new project that must follow future Unity versions, it is difficult to justify Zenject as the default.

Reflex remains actively maintained and provides Unity-focused scopes, source generation, debugging, and runtime prefab injection. VContainer offers a broader lifecycle and entry-point model when a project needs it.

Keep an existing Zenject project when migration cost is not justified.

Evaluate Reflex first for a new Unity project.

Compare VContainer when PlayerLoop integration, pure C# entry points, UniTask, ECS, or broader lifecycle management are real requirements.

Start with manual DI when the project is small.

A DI container automates construction and lifetime management; it does not design the software. Keep it near composition boundaries and preserve the option to replace it later.

References

Testing in Unreal Engine 5: CQTest, Automation Spec, Functional Tests, and CI

GameDevToolLab — Fri, 31 Jul 2026 05:21:19 +0000

Introduction

The hardest part of writing tests in Unreal Engine 5 is often not the assertion syntax. It is deciding which testing system to use.

UE provides several overlapping options:

IMPLEMENT_SIMPLE_AUTOMATION_TEST
Complex Automation Tests
Automation Spec
CQTest
Functional Tests
Python Automation Tests
Automation Driver
Gauntlet
Low-Level Tests

Games also require very different execution environments. Some rules can be tested as ordinary C++ functions. Others require UObject, UWorld, Actors, PIE, level streaming, UI input, rendering, network sessions, or a packaged build.

Trying to force all of those cases into one framework usually creates a slow and fragile test suite.

This article uses Unreal Engine 5.8 documentation as its baseline and explains how to divide responsibilities across C++ tests, CQTest, Automation Spec, asynchronous waits, Functional Tests, command-line execution, and CI.

Code sample scope: The snippets reference UE 5.8 APIs, but they are explanatory fragments rather than a complete sample project. Project-specific types, includes, .Build.cs dependencies, module API macros, and some setup code must be adapted to your project. The examples were not fully compiled in a UE 5.8 project while preparing this article.

The practical rule is simple:

Use the lightest execution environment that can prove the behavior you care about.

Which UE Test System Should You Use?

Target	Good first choice	Typical environment
Math, rules, and data conversion	CQTest, Automation Spec, or Simple Automation Test	Editor / command line
Behavior expressed as readable scenarios	Automation Spec	Editor / command line
The same logic with many inputs	Complex Automation Test	Editor / command line
Actors, Components, Blueprints, and level wiring	Functional Test	Editor / PIE
Asset and content-production rules	Python Automation Test	Editor
Mouse, keyboard, scrolling, and UI flows	Automation Driver	Editor / Client
Packaged builds, devices, clients, and servers	Gauntlet	Build machine / device
Fast tests in a dedicated executable	Low-Level Tests	Dedicated test target

Do not introduce everything at once. Keep most rule verification in fast C++ tests, add a small number of Functional Tests for critical gameplay wiring, and introduce Gauntlet only when the packaged runtime or multi-process environment is part of the requirement.

Separate Game Rules from Actors and Widgets

The most effective preparation for testing is to move deterministic rules out of Actors and Widgets.

// DamageCalculator.h
#pragma once

#include "CoreMinimal.h"

class FDamageCalculator
{
public:
    static int32 CalculateFinalDamage(
        const int32 BaseDamage,
        const int32 Defense)
    {
        if (BaseDamage <= 0)
        {
            return 0;
        }

        return FMath::Max(1, BaseDamage - FMath::Max(0, Defense));
    }
};

This function can be checked without creating a World or spawning an Actor. The gameplay Actor can read input values and apply the result, while a much smaller Functional Test verifies that the Unreal-side wiring is correct.

The goal is not to remove every Unreal type from the codebase. The goal is to separate:

Logic that benefits from many fast boundary-value tests
Engine integration that requires a World, Actor, Component, Blueprint, or level

Where to Put Test Code

Epic's documentation shows Automation Tests near the related module, commonly under Private/Tests.

Source/MyGame/
├─ Public/Combat/DamageCalculator.h
└─ Private/
   ├─ Combat/DamageCalculator.cpp
   └─ Tests/DamageCalculatorTest.cpp

This is a reasonable starting point for small tests that only depend on modules such as Core and Engine.

However, wrapping registration code with WITH_DEV_AUTOMATION_TESTS does not remove .Build.cs dependencies. When tests begin to require CQTest, editor-only modules, or Functional Testing support, move them into a dedicated module such as Source/MyGameTests or a Tests plugin.

Source/MyGameTests/
├─ MyGameTests.Build.cs
└─ Private/
   ├─ Unit/
   └─ Functional/

The examples below omit repeated guards for readability. In real files, guard C++ test registration code—Automation Tests, Specs, and CQTest tests—with the appropriate development-test configuration. Keep test-only classes and dependencies out of Shipping targets according to your project's build policy.

The sample names FInventoryService, FProfileService, APickupActor, and UInventoryComponent represent project-specific types. Replace them with your own implementations and dependencies.

Simple Automation Tests

A traditional Automation Test derives from FAutomationTestBase. A single test can be registered with IMPLEMENT_SIMPLE_AUTOMATION_TEST.

#include "Misc/AutomationTest.h"
#include "Combat/DamageCalculator.h"

#if WITH_DEV_AUTOMATION_TESTS

IMPLEMENT_SIMPLE_AUTOMATION_TEST(
    FDamageCalculatorMinimumDamageTest,
    "MyGame.Unit.Combat.DamageCalculator.MinimumDamage",
    EAutomationTestFlags::EditorContext |
    EAutomationTestFlags::ProductFilter)

bool FDamageCalculatorMinimumDamageTest::RunTest(const FString& Parameters)
{
    const int32 Actual = FDamageCalculator::CalculateFinalDamage(10, 100);

    TestEqual(
        TEXT("Positive attacks return at least one damage"),
        Actual,
        1);

    return true;
}

#endif

RunTest can use helpers such as TestEqual, TestTrue, TestFalse, and TestNotNull. Stop early when a missing prerequisite would make later code unsafe.

UObject* Object = CreateObjectUnderTest();
if (!TestNotNull(TEXT("The object under test was created"), Object))
{
    return false;
}

Treat Test Names as a CI Hierarchy

The test name is both a display name and a command-line filter.

MyGame.Unit.Combat.DamageCalculator.MinimumDamage
MyGame.Integration.Save.LoadRoundTrip
MyGame.Functional.Gameplay.Pickup

A pattern such as Project.Layer.Feature.Subject.Condition makes it easy to run MyGame.Unit before submission and reserve MyGame.Functional for a heavier job.

Common flags include:

EditorContext: Run in the Editor
ClientContext / ServerContext: Run in a client or server context
SmokeFilter: Extremely short checks
ProductFilter: Project or product functionality
PerfFilter / StressFilter: Performance or stress testing
NonNullRHI: Requires a rendering environment

ProductFilter is normally appropriate for game-project tests, while EngineFilter is intended for engine functionality. Epic's guidance treats Smoke Tests as checks that should complete in roughly one second or less.

CQTest for Fixture-Style C++ Tests

CQTest extends the Automation Test infrastructure with fixtures, setup and teardown, assertions, and latent actions.

Add CQTest to the module that builds the tests—not automatically to the product Runtime module.

PrivateDependencyModuleNames.AddRange(
    new string[] { "Core", "CoreUObject", "Engine", "CQTest" }
);

A minimal test is concise:

#include "CQTest.h"
#include "Combat/DamageCalculator.h"

TEST(DamageCalculator_StandardReduction, "MyGame.Unit.Combat")
{
    const int32 Actual = FDamageCalculator::CalculateFinalDamage(100, 30);
    ASSERT_THAT(AreEqual(70, Actual));
}

Use TEST_CLASS when several tests share a fixture.

TEST_CLASS(InventoryServiceTest, "MyGame.Unit.Inventory")
{
    TUniquePtr<FInventoryService> Inventory;

    BEFORE_EACH()
    {
        Inventory = MakeUnique<FInventoryService>(10);
    }

    AFTER_EACH()
    {
        Inventory.Reset();
    }

    TEST_METHOD(AddItem_IncreasesCount)
    {
        ASSERT_THAT(IsTrue(Inventory->AddItem(TEXT("Potion"), 3)));
        ASSERT_THAT(AreEqual(
            3,
            Inventory->GetItemCount(TEXT("Potion"))));
    }

    TEST_METHOD(AddItem_RejectsCapacityOverflow)
    {
        Inventory->AddItem(TEXT("Potion"), 10);
        ASSERT_THAT(IsFalse(Inventory->AddItem(TEXT("Ether"), 1)));
    }
};

Rebuilding the state before each method reduces order dependence. CQTest is a strong default for new fixture-style C++ tests, but an existing project that already uses Automation Spec consistently does not need to replace it only for stylistic reasons.

Automation Spec for Readable Behavior Scenarios

Automation Spec uses a BDD-style structure with Describe, BeforeEach, and It.

BEGIN_DEFINE_SPEC(
    FInventoryServiceSpec,
    "MyGame.Unit.Inventory.InventoryService",
    EAutomationTestFlags::EditorContext |
    EAutomationTestFlags::ProductFilter)

    TUniquePtr<FInventoryService> Inventory;

END_DEFINE_SPEC(FInventoryServiceSpec)

void FInventoryServiceSpec::Define()
{
    BeforeEach([this]()
    {
        Inventory = MakeUnique<FInventoryService>(10);
    });

    Describe("when adding an item to an empty inventory", [this]()
    {
        It("increases the count by the added amount", [this]()
        {
            Inventory->AddItem(TEXT("Potion"), 3);
            TestEqual(
                TEXT("Potion count"),
                Inventory->GetItemCount(TEXT("Potion")),
                3);
        });
    });
}

Specs work well when the scenarios themselves should read like documentation. Epic recommends the .spec.cpp suffix.

Avoid deeply nested Describe blocks. Two or three levels are usually enough; beyond that, the active setup becomes difficult to understand.

Complex Automation Tests for Parameter Sets

A Complex Automation Test uses GetTests to expose multiple cases and passes each command string to RunTest.

#include "Misc/LexFromString.h"

IMPLEMENT_COMPLEX_AUTOMATION_TEST(
    FDamageCalculatorCasesTest,
    "MyGame.Unit.Combat.DamageCalculator.Cases",
    EAutomationTestFlags::EditorContext |
    EAutomationTestFlags::ProductFilter)

void FDamageCalculatorCasesTest::GetTests(
    TArray<FString>& Names,
    TArray<FString>& Commands) const
{
    Names.Add(TEXT("Standard"));
    Commands.Add(TEXT("100,30,70"));

    Names.Add(TEXT("MinimumDamage"));
    Commands.Add(TEXT("10,100,1"));
}

bool FDamageCalculatorCasesTest::RunTest(const FString& Parameters)
{
    TArray<FString> Values;
    Parameters.ParseIntoArray(Values, TEXT(","));

    if (!TestEqual(TEXT("Parameter count"), Values.Num(), 3))
    {
        return false;
    }

    int32 BaseDamage = 0;
    int32 Defense = 0;
    int32 Expected = 0;

    if (!LexTryParseString(BaseDamage, *Values[0]) ||
        !LexTryParseString(Defense, *Values[1]) ||
        !LexTryParseString(Expected, *Values[2]))
    {
        AddError(FString::Printf(
            TEXT("Could not parse numeric parameters: %s"),
            *Parameters));
        return false;
    }

    TestEqual(
        TEXT("Final damage"),
        FDamageCalculator::CalculateFinalDamage(BaseDamage, Defense),
        Expected);

    return true;
}

FCString::Atoi turns invalid text into zero, which can hide broken test data. LexTryParseString lets the test fail explicitly.

For only a few scenarios, separate CQTest or Spec cases may be more readable. Complex Tests become especially useful when enumerating every map, Data Table row, or asset in a folder because each input appears as a separate test result.

Testing Work That Spans Multiple Frames

Asset loading, level transitions, HTTP, async tasks, PIE startup, and similar work cannot finish in one frame. Do not block the Game Thread with Sleep; wait for an observable completion condition.

CQTest provides TestCommandBuilder. The following assumes that the same TEST_CLASS owns a TUniquePtr<FProfileService> initialized in BEFORE_EACH.

TEST_METHOD(LoadProfile_CompletesWithSavedName)
{
    TestCommandBuilder
        .Do([this]()
        {
            ProfileService->BeginLoad(TEXT("Player01"));
        })
        .Until(
            TEXT("Wait for profile loading to complete or fail"),
            [this]()
            {
                return ProfileService->IsLoadCompleted() ||
                    ProfileService->HasFailed();
            },
            FTimespan::FromSeconds(10))
        .Then([this]()
        {
            ASSERT_THAT(IsFalse(ProfileService->HasFailed()));
            ASSERT_THAT(AreEqual(
                FString(TEXT("Alice")),
                ProfileService->GetLoadedProfile().PlayerName));
        })
        .OnTearDown([this]()
        {
            ProfileService->Cancel();
        });
}

Prefer Until over a fixed WaitDelay. A timeout must still exist: otherwise, a condition that never becomes true is one of the hardest CI failures to investigate. Include the operation, target ID, last observed state, and error code in diagnostics.

Traditional Simple Automation Tests can use DEFINE_LATENT_AUTOMATION_COMMAND and ADD_LATENT_AUTOMATION_COMMAND. For new code, CQTest or Spec latent features often keep the sequence easier to read.

Expected Warnings and Errors

The Automation Framework records warnings and errors emitted during a test. Register an error first when the error is the expected behavior.

AddExpectedError(
    TEXT("Inventory capacity exceeded"),
    EAutomationExpectedErrorFlags::Contains,
    1);

The count is checked as well. Keep the matching text narrow: a broad Contains pattern can accidentally absorb an unrelated error. Prefer a stable identifier and an exact occurrence count.

Routine invalid input is often easier to test through return values or result types instead of Error logs. Reserve Error logging for genuinely abnormal states.

Functional Tests for Actors and Levels

Use Functional Tests for behavior that depends on Actors, Components, Blueprints, or level wiring—for example, collecting a pickup, opening a door through a trigger, AI movement, or startup spawning.

Enable the Functional Testing plugin and place a Functional Test Actor in a small dedicated test map. A C++ module that derives from AFunctionalTest needs the FunctionalTesting dependency.

The lifecycle is:

Start preparation in PrepareTest
Wait in IsReady when preparation spans frames
Perform assertions in StartTest
Call FinishTest for both success and failure
Restore state during cleanup

Forgetting FinishTest leaves the test running until timeout.

The following example expects an APickupFunctionalTest instance in a dedicated map, with PickupClass and Inventory configured in Details. It is intentionally simplified. A production test should usually own a test Pawn or Fixture Actor and obtain the Component from that fixture instead of depending on ordinary gameplay state.

// PickupFunctionalTest.h
#pragma once

#include "FunctionalTest.h"
#include "PickupFunctionalTest.generated.h"

class APickupActor;
class UInventoryComponent;

UCLASS()
class MYGAMETESTS_API APickupFunctionalTest : public AFunctionalTest
{
    GENERATED_BODY()

protected:
    virtual void PrepareTest() override;
    virtual bool IsReady_Implementation() override;
    virtual void StartTest() override;
    virtual void CleanUp() override;

private:
    UPROPERTY(EditAnywhere, Category = "Test")
    TSubclassOf<APickupActor> PickupClass;

    UPROPERTY(EditInstanceOnly, Category = "Test")
    TObjectPtr<UInventoryComponent> Inventory;

    TWeakObjectPtr<APickupActor> SpawnedPickup;
    bool bPreparationFinished = false;
};

void APickupFunctionalTest::PrepareTest()
{
    Super::PrepareTest();
    bPreparationFinished = false;

    if (PickupClass && Inventory && GetWorld())
    {
        APickupActor* Pickup = GetWorld()->SpawnActor<APickupActor>(
            PickupClass,
            GetActorLocation(),
            GetActorRotation());

        if (Pickup)
        {
            SpawnedPickup = Pickup;
            RegisterAutoDestroyActor(Pickup);
        }
    }

    bPreparationFinished = true;
}

bool APickupFunctionalTest::IsReady_Implementation()
{
    // Wait only for preparation to finish so StartTest can report failures.
    return bPreparationFinished;
}

void APickupFunctionalTest::StartTest()
{
    Super::StartTest();

    if (!PickupClass)
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("PickupClass is not configured"));
        return;
    }

    if (!Inventory)
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("Inventory is not configured"));
        return;
    }

    if (!GetWorld())
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("GetWorld() returned nullptr"));
        return;
    }

    if (!SpawnedPickup.IsValid())
    {
        FinishTest(EFunctionalTestResult::Failed,
            TEXT("Failed to spawn APickupActor"));
        return;
    }

    const int32 Before = Inventory->GetItemCount(TEXT("Potion"));
    SpawnedPickup->Collect(Inventory);
    const int32 After = Inventory->GetItemCount(TEXT("Potion"));

    const bool bSucceeded = AssertEqual_Int(
        After,
        Before + 1,
        TEXT("Collecting the pickup adds one Potion"),
        this);

    FinishTest(
        bSucceeded
            ? EFunctionalTestResult::Succeeded
            : EFunctionalTestResult::Failed,
        bSucceeded ? TEXT("Succeeded") : TEXT("Item count did not increase"));
}

void APickupFunctionalTest::CleanUp()
{
    SpawnedPickup.Reset();
    bPreparationFinished = false;
    Super::CleanUp();
}

RegisterAutoDestroyActor removes the spawned Actor when the test ends. Do not wait forever in IsReady when a class reference is missing or spawning failed. Complete preparation and report a specific failure in StartTest.

Prefer several small test maps over one giant functional-test map. Smaller maps reduce startup cost, hidden dependencies, and interference between tests.

Running Tests in the Editor

In UE 5.8, open the automation interface from Tools > Test Automation. Depending on the version, enabled plugins, and layout, it may also be available through Tools > Session Frontend and its Automation tab.

A typical workflow is:

Enable the required testing plugins
Compile C++ and restart the Editor
Open Test Automation
Select tests under MyGame
Start the tests
Inspect the result events for failures

When a test is missing, verify the module is loaded, the context flags match, dependencies such as CQTest are present, required plugins are enabled, and the Editor has been fully restarted. New registrations may not appear reliably after Live Coding alone.

Running Tests from the Command Line

Use Automation RunTest through -ExecCmds.

"C:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" ^
  "D:\Projects\MyGame\MyGame.uproject" ^
  -Unattended ^
  -NoSplash ^
  -NullRHI ^
  -ExecCmds="Automation RunTest MyGame.Unit;Quit" ^
  -ReportExportPath="D:\Projects\MyGame\Saved\AutomationReports\Unit"

-Unattended suppresses blocking dialogs. -ReportExportPath writes report data, including JSON and HTML-related files. Preserve both the report directory and Saved/Logs as CI artifacts.

Do Not Trust Only the Process Exit Code

Use the process result to detect startup failures, crashes, and job timeouts, but also parse the Automation Report JSON.

Fail the CI job when:

A test failed or timed out
A required test unexpectedly remained NotRun or incomplete
The expected report JSON was not generated

Decide explicitly whether reasoned exclusions reported as Skipped are allowed. Preserve reports even on success, and upload HTML-related output plus logs on failure.

Functional Tests also need the map containing the test Actor.

"C:\Program Files\Epic Games\UE_5.8\Engine\Binaries\Win64\UnrealEditor-Cmd.exe" ^
  "D:\Projects\MyGame\MyGame.uproject" ^
  "/Game/Tests/Maps/L_PickupFunctionalTest" ^
  -Unattended ^
  -NoSplash ^
  -ExecCmds="Automation RunTest MyGame.Functional.Gameplay.Pickup;Quit" ^
  -ReportExportPath="D:\Projects\MyGame\Saved\AutomationReports\Pickup"

-NullRHI reduces cost when rendering is unnecessary. Remove it for screenshots, Slate, Viewports, Materials, GPU-specific checks, and tests marked NonNullRHI. Separate rendering and non-rendering jobs instead of assuming every Functional Test can run headlessly.

Groups can be defined in DefaultEngine.ini.

[/Script/AutomationController.AutomationControllerSettings]
+Groups=(Name="PreSubmit", Filters=((Contains="MyGame.Unit.", MatchFromStart=true)))
+Groups=(Name="Nightly", Filters=((Contains="MyGame.Functional.", MatchFromStart=true)))

-ExecCmds="Automation RunTest Group:PreSubmit;Quit"

Temporarily exclude a flaky test through configuration instead of commenting it out, and include both a reason and a removal condition.

+ExcludeTest=(Test="MyGame.Functional.Gameplay.Pickup",Reason="UE-12345: Remove after fixing spawn wait",Warn=False)

A Practical CI Split

Running every test on every change makes feedback too slow. Running everything only at night allows several unrelated changes to accumulate before a failure appears.

Pull Request or Pre-Submit

Keep this within a few minutes:

CQTest and Simple Automation Tests for deterministic C++
Important serialization round trips
Critical data validation
Smoke Tests that finish in roughly one second

Use -NullRHI when rendering is not required.

After Updating the Main Branch

Add moderately expensive integration checks:

Small Functional Tests
Important map loads
Blueprint compilation
Save/load with real files
Asset Registry reference validation

Nightly or Scheduled Jobs

Reserve expensive environments for:

Loading all maps and major assets
Screenshot comparisons
Multiple clients and a Dedicated Server
Packaged builds
Long-running memory or stress tests
Target-device execution

This is where Gauntlet becomes useful. It can launch and coordinate multiple Unreal sessions, clients, and servers. Do not move ordinary rule tests into Gauntlet; use it when the packaged runtime or process topology is part of what must be proven.

Python Automation Tests for Content Workflows

Python tests are useful for naming rules, folder structure, import settings, and forbidden references. With the Python Automation Test support enabled, scripts under Content/Python named test_*.py can be discovered.

The following sample uses EditorAssetLibrary, so it assumes an Editor environment with the required Python and Editor Scripting plugins. Confirm API and plugin names for your exact engine version.

import unreal

assets = unreal.EditorAssetLibrary.list_assets(
    "/Game/Characters",
    recursive=True,
    include_folder=False,
)

invalid_assets = [
    path for path in assets
    if not path.rsplit("/", 1)[-1].startswith(("SK_", "SM_", "T_", "MI_"))
]

max_reported = 20
preview = "\n".join(f"- {path}" for path in invalid_assets[:max_reported])
omitted = max(0, len(invalid_assets) - max_reported)
omitted_note = f"\n...and {omitted} more" if omitted else ""

if invalid_assets:
    raise AssertionError(
        f"Naming violations: {len(invalid_assets)}\n"
        f"{preview}{omitted_note}\n"
        "Rename assets to use SK_, SM_, T_, or MI_."
    )

Do not dump thousands of paths into CI logs. Report the count, a limited preview, and the correction rule. When combining several checks, log each summary and raise an exception at the end; logging errors without failing can leave the CI job green.

Python execution does not automatically advance Editor ticks during asynchronous work. Split such operations with unreal.AutomationScheduler.add_latent_command.

Automation Driver for UI Input

Automation Driver simulates mouse input, clicks, keys, scrolling, and drag-and-drop. Give UI elements stable driver IDs instead of locating them only by visible text or hierarchy.

SNew(STextBlock)
    .Text(ViewModel, &FViewModel::GetPlayerName)
    .AddMetaData(FDriverMetaData::Id("PlayerNameLabel"));

The driver is disabled by default. Enable it at test start and always disable it during cleanup.

Synchronous Driver APIs block until completion. Calling them on the Game Thread can deadlock. Keep input operations outside the Game Thread, but do not move Slate or UObject validation indiscriminately to a worker thread. Slate TSharedPtr instances are not thread-safe by default and should not be copied into worker-thread lambdas.

A safe conceptual split is:

BeforeEach [Game Thread]
  Create the Widget, Window, ViewModel, and Driver; enable the Driver
        ↓
Input phase [outside Game Thread]
  Perform clicks, typing, scrolling, and other synchronous Driver actions
        ↓
Validation phase [Game Thread]
  Inspect UObject, Slate, and ViewModel state
        ↓
AfterEach [Game Thread]
  Destroy the Driver, close the Window, and disable the Driver

Use Spec async blocks or latent commands to return to the Game Thread after input completes. Ensure failure paths still reach Disable().

UI tests are slower and more fragile than service-layer tests. Limit them to representative flows such as starting from the title screen, saving settings, or selecting a save slot. Test detailed branches in C++ beneath the UI.

When to Use Low-Level Tests

UE5 Low-Level Tests use Catch2 and run through a dedicated test executable with their own .Build.cs and .Target.cs. Avoiding full Editor startup can make a large low-level suite much faster.

They are not limited strictly to pure C++; with the right target and modules, they can exercise UObject, assets, and Engine Components. However, they require dedicated build and CI setup, and World- or Editor-workflow-heavy tests may remain easier in Automation or Functional Tests.

Consider Low-Level Tests when you already have hundreds of small tests, Editor startup dominates execution time, or BuildGraph should run them as an independent job. For the first test in a project, CQTest or a Simple Automation Test is usually the shorter path.

Common Failure Modes

Waiting with Sleep

FPlatformProcess::Sleep can stop the Game Thread from ticking. Use latent actions and observable completion conditions.

Depending on Test Order

Each test must create its own state and restore it during teardown. A test that assumes a previous test already logged in will fail in isolation or parallel execution.

Leaving Files or Actors Behind

Register generated Actors with RegisterAutoDestroyActor. Write files under a test-only temporary directory and remove them in teardown. Clean stale artifacts before startup as well, and make cleanup run after failures.

Comparing Floating-Point Values Exactly

Use an explicit tolerance for physics, timing, and coordinates.

TestTrue(
    TEXT("X is within tolerance"),
    FMath::IsNearlyEqual(Actual.X, Expected.X, 0.1f));

Creating Unreproducible Random Tests

Fix the seed and print both the seed and generated input on failure. Randomized testing should supplement deterministic boundary cases, not replace them.

Writing Vague Failure Messages

Include the condition, expected value, actual value, and target ID. A developer should be able to begin investigation from the CI log alone.

Expecting Live Coding to Register Everything

When a new test is missing from the list, close the Editor, run a normal build, and restart it. Registration depends on module loading.

Starting with Coverage Percentage

Begin with failures that matter: save compatibility, currency rules, combat boundaries, data references, or a level that cannot start. Frequently changed rules and QA flows that are checked manually every time are also strong candidates.

The first objective is not a percentage. It is preventing one important regression from returning.

A Gradual Adoption Plan

Add one World-independent rule test with CQTest or a Simple Automation Test.
Add a regression test before fixing the next reproducible bug.
Automate save/load compatibility and static-data validation.
Stabilize one representative Functional Test in a small dedicated map.
Commit the command-line scripts so local and CI execution use the same commands.
Track duration, retry success rate, and timeout locations, then remove flakiness instead of normalizing reruns.

Conclusion

Unreal Engine testing works best as a layered system:

CQTest, Automation Spec, and Simple or Complex Automation Tests for fast C++ behavior
Functional Tests for Actors, Components, Blueprints, and level wiring
Python Automation Tests for content-production rules
Automation Driver for a small number of representative UI flows
Gauntlet for packaged builds and multi-process environments
Low-Level Tests when dedicated execution speed justifies the extra build setup

For multi-frame work, wait for explicit completion or failure conditions with a clear timeout. In CI, parse Automation Reports instead of trusting only the Editor process exit code.

Do not start by building an end-to-end test for the whole game. Start with deterministic tests that run quickly and fail with enough information to diagnose the problem.

The useful milestone is not “we reached a coverage target.” It is:

When an important old bug returns, the build stops automatically.

References

A Practical Guide to Testing in Unity: EditMode, PlayMode, Async, and CI

GameDevToolLab — Thu, 30 Jul 2026 13:03:01 +0000

Introduction

Testing in Unity is more complicated than testing ordinary C# code.

A damage formula can be covered with a normal NUnit [Test], but a real game also contains MonoBehaviour, ScriptableObject, frame updates, coroutines, scenes, prefabs, physics, and asynchronous asset loading.

The practical questions are where to split EditMode and PlayMode, when [UnityTest] is necessary, how to handle lifecycle and asynchronous code, and which tests belong in CI.

This article uses Unity 6 and Unity Test Framework 1.6 as its baseline. It is written for programmers introducing automated tests or adding them incrementally to an existing project. The samples are intentionally small, so adjust omitted namespaces and project-specific types to your own assemblies.

The basic strategy is to keep game rules in fast pure-C# EditMode tests, test thin Unity adapters only where needed, reserve PlayMode for PlayerLoop or lifecycle behavior, and leave visual quality or device-specific performance to QA and device tests.

Tests do not prove that a game has no bugs. They provide a fast safety net when you refactor code, change specifications, or fix a regression.

What Unity Test Framework provides

Unity Test Framework is Unity's built-in testing system. It is based on NUnit and adds support for Unity-specific concepts such as frames, the application loop, domain reloads, and player execution.

The common ways to run tests are:

Test Runner inside the Unity Editor
Unity command-line execution for CI
TestRunnerApi for custom tooling

Use Test Runner during development, command-line execution in CI, and TestRunnerApi only when you need a custom test workflow.

Unity ships its own NUnit-compatible environment, so APIs from the latest standalone NUnit may not all be available or behave identically. Check the documentation for the Test Framework version bundled with your Editor, especially for asynchronous assertions.

EditMode and PlayMode tests

Unity tests are broadly divided into EditMode and PlayMode tests.

EditMode tests

EditMode tests run in the Editor without normal Play Mode. They suit calculations, save migration, probability rules, data validation, ScriptableObject logic, editor tooling, serialization, and static prefab or scene checks. Pure C# EditMode tests are usually fast enough to run continuously.

PlayMode tests

PlayMode tests execute in Unity's runtime environment. Use them for lifecycle callbacks, frame updates, coroutines, scene loading, runtime prefab wiring, animation transitions, physics, and behavior that appears only in a Player. They are slower and more sensitive to global state, so an all-PlayMode suite becomes expensive to diagnose.

A practical decision process

Ask these questions in order:

Does the behavior work without Unity APIs?
Does it need Unity objects but not frame progression?
Does it depend on the PlayerLoop, lifecycle events, scenes, or physics?
Does it require an actual target device?

Use pure EditMode tests for case 1, Unity-aware EditMode tests for case 2, PlayMode tests for case 3, and Player/device testing for case 4.

Create test assemblies first

Tests should live in assemblies that reference NUnit and the production assemblies they test.

A practical folder structure is:

Assets/
├── Game/
│   ├── Runtime/
│   │   ├── Game.Runtime.asmdef
│   │   ├── Battle/
│   │   └── Save/
│   └── Editor/
│       ├── Game.Editor.asmdef
│       └── Validation/
└── Tests/
    ├── EditMode/
    │   ├── Game.EditModeTests.asmdef
    │   ├── Battle/
    │   └── Save/
    └── PlayMode/
        ├── Game.PlayModeTests.asmdef
        ├── Battle/
        └── Scene/

An EditMode test assembly conceptually looks like this:

{
  "name": "Game.EditModeTests",
  "references": [
    "Game.Runtime"
  ],
  "includePlatforms": [
    "Editor"
  ],
  "optionalUnityReferences": [
    "TestAssemblies"
  ]
}

A PlayMode test assembly can target runtime platforms:

{
  "name": "Game.PlayModeTests",
  "references": [
    "Game.Runtime"
  ],
  "includePlatforms": [],
  "optionalUnityReferences": [
    "TestAssemblies"
  ]
}

Treat these JSON blocks as conceptual examples. Unity versions can generate different fields, so verify the settings in the Inspector instead of blindly replacing an .asmdef file.

A common obstacle in older projects is that production code still belongs to Assembly-CSharp.dll, which a test assembly cannot directly reference. Move one independent class into Game.Runtime.asmdef, reference it from the test assembly, and expand gradually. Keep UnityEditor APIs in a separate editor assembly and preserve a one-way dependency from presentation code toward lower-level logic.

Write the first pure C# test

Start with a class that has no Unity dependency.

namespace Game.Battle
{
    public sealed class DamageCalculator
    {
        public int Calculate(int attack, int defense)
        {
            var damage = attack - defense;
            return damage < 1 ? 1 : damage;
        }
    }
}

The test is ordinary NUnit code:

using Game.Battle;
using NUnit.Framework;

namespace Game.Tests.EditMode.Battle
{
    public sealed class DamageCalculatorTests
    {
        [Test]
        public void Calculate_AttackIsGreaterThanDefense_ReturnsDifference()
        {
            // Arrange
            var calculator = new DamageCalculator();

            // Act
            var actual = calculator.Calculate(attack: 100, defense: 30);

            // Assert
            Assert.That(actual, Is.EqualTo(70));
        }

        [Test]
        public void Calculate_DefenseIsGreaterThanAttack_ReturnsMinimumDamage()
        {
            var calculator = new DamageCalculator();

            var actual = calculator.Calculate(attack: 30, defense: 100);

            Assert.That(actual, Is.EqualTo(1));
        }
    }
}

Arrange, Act, and Assert are useful as a mental model:

Arrange the subject and inputs.
Act by executing one behavior.
Assert the result.

Comments are not mandatory in every short test. Clear spacing is often enough.

Test names should explain a failure. A useful convention is:

Method_Condition_ExpectedResult

For example:

Calculate_DefenseIsGreaterThanAttack_ReturnsMinimumDamage

The exact convention matters less than being able to infer what broke from the failed test name in CI.

Parameterize boundary cases

Use [TestCase] when the same rule must be checked with multiple inputs.

[TestCase(100, 30, 70)]
[TestCase(30, 100, 1)]
[TestCase(50, 50, 1)]
[TestCase(1, 0, 1)]
public void Calculate_WithVariousParameters_ReturnsExpectedDamage(
    int attack,
    int defense,
    int expected)
{
    var calculator = new DamageCalculator();

    var actual = calculator.Calculate(attack, defense);

    Assert.That(actual, Is.EqualTo(expected));
}

Parameterization is especially useful for:

minimum and maximum values
zero, one, and negative values
just below, exactly at, and just above a threshold
level and inventory caps
date boundaries
probability-table edges
rounding rules

For more complex cases, use [TestCaseSource]. TestCaseData allows readable names in CI output.

private static readonly TestCaseData[] Cases =
{
    new TestCaseData(100, 30, 70)
        .SetName("AttackGreaterThanDefense"),
    new TestCaseData(30, 100, 1)
        .SetName("DefenseGreaterThanAttack"),
};

[TestCaseSource(nameof(Cases))]
public void Calculate_WithCases_ReturnsExpected(
    int attack,
    int defense,
    int expected)
{
    var calculator = new DamageCalculator();

    Assert.That(calculator.Calculate(attack, defense), Is.EqualTo(expected));
}

Do not combine unrelated rules merely because the inputs fit into one parameter list. Parameterize data variations of the same behavior.

Assert behavior, not every field

A test becomes difficult to understand when it verifies many unrelated values. The goal is not "one assertion per test" but "one behavior per test."

Multiple assertions are appropriate when they describe one atomic result:

[Test]
public void ConsumePotion_WhenStockExists_HealsAndDecreasesStock()
{
    var inventory = new Inventory(potionCount: 2);
    var player = new Player(currentHp: 50, maxHp: 100);

    inventory.ConsumePotion(player);

    Assert.That(player.CurrentHp, Is.EqualTo(80));
    Assert.That(inventory.PotionCount, Is.EqualTo(1));
}

Healing the player and consuming one item are two parts of the same operation. Splitting them would duplicate setup without improving clarity.

Test ScriptableObject rules in EditMode

A ScriptableObject can be created without saving an asset.

using NUnit.Framework;
using UnityEngine;

public sealed class EnemyParameterTests
{
    private EnemyParameter _parameter;

    [SetUp]
    public void SetUp()
    {
        _parameter = ScriptableObject.CreateInstance<EnemyParameter>();
    }

    [TearDown]
    public void TearDown()
    {
        Object.DestroyImmediate(_parameter);
    }

    [Test]
    public void IsBoss_HpIsAtLeast10000_ReturnsTrue()
    {
        _parameter.Hp = 10000;

        Assert.That(_parameter.IsBoss, Is.True);
    }
}

The production type might be:

using UnityEngine;

[CreateAssetMenu(menuName = "Game/Enemy Parameter")]
public sealed class EnemyParameter : ScriptableObject
{
    [field: SerializeField]
    public int Hp { get; set; }

    public bool IsBoss => Hp >= 10000;
}

Destroy temporary EditMode objects with DestroyImmediate when appropriate. Put cleanup in [TearDown] so it still runs after an assertion failure.

Separate two concerns:

Test class rules with temporary instances.
Validate all real project assets in a dedicated project-validation test.

Tests that depend on exact asset paths or GUIDs are more fragile than tests against temporary instances.

Validate prefabs and assets

Automated tests are also effective at finding authoring mistakes.

Suppose every enemy prefab under Assets/Game/Enemies must have an EnemyController on its root:

using System.Linq;
using NUnit.Framework;
using UnityEditor;
using UnityEngine;

public sealed class EnemyPrefabValidationTests
{
    [Test]
    public void EnemyPrefabs_AllHaveEnemyController()
    {
        var guids = AssetDatabase.FindAssets(
            "t:Prefab",
            new[] { "Assets/Game/Enemies" });

        var invalidPaths = guids
            .Select(AssetDatabase.GUIDToAssetPath)
            .OrderBy(path => path)
            .Where(path =>
            {
                var prefab = AssetDatabase.LoadAssetAtPath<GameObject>(path);
                return prefab == null ||
                       prefab.GetComponent<EnemyController>() == null;
            })
            .ToArray();

        Assert.That(
            invalidPaths,
            Is.Empty,
            $"Prefabs without EnemyController:\n{string.Join("\n", invalidPaths)}");
    }
}

This is closer to project validation than a unit test, but it is highly valuable. The same approach can detect missing components or scripts, broken references, duplicate IDs, invalid Addressables labels, missing localization keys, incorrect Layers or Tags, and assets that violate project rules.

The sample above only checks for EnemyController. Missing scripts require a separate validation, for example with GameObjectUtility.GetMonoBehavioursWithMissingScriptCount while traversing the prefab hierarchy.

A full project scan may be slow. Categorize it separately and run it in CI or at night instead of blocking every local edit.

[Category("AssetValidation")]
[Test]
public void EnemyPrefabs_AllHaveEnemyController()
{
    // Validation logic
}

Test MonoBehaviour correctly

Never instantiate a MonoBehaviour with new. Create a GameObject and use AddComponent<T>().

A method that does not require frame progression can still be tested in EditMode:

using NUnit.Framework;
using UnityEngine;

public sealed class HealthViewTests
{
    private GameObject _gameObject;

    [SetUp]
    public void SetUp()
    {
        _gameObject = new GameObject("HealthViewTest");
    }

    [TearDown]
    public void TearDown()
    {
        Object.DestroyImmediate(_gameObject);
    }

    [Test]
    public void SetHealth_WithHalfValue_StoresRatio()
    {
        var view = _gameObject.AddComponent<HealthView>();

        view.SetHealth(current: 50, max: 100);

        Assert.That(view.Ratio, Is.EqualTo(0.5f).Within(0.0001f));
    }
}

This does not test Awake or Start. It only verifies a public method on a component. Move to PlayMode when Unity lifecycle behavior is part of the specification.

Cross frames with UnityTest

When a PlayMode test must cross frames, use [UnityTest] and return IEnumerator. The attribute is also available in EditMode, but this example focuses on runtime lifecycle behavior.

using UnityEngine;

public sealed class PlayerInitializer : MonoBehaviour
{
    public bool IsInitialized { get; private set; }

    private void Start()
    {
        IsInitialized = true;
    }
}

The PlayMode test waits one frame before checking the result:

using System.Collections;
using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;

public sealed class PlayerInitializerTests
{
    [UnityTest]
    public IEnumerator Start_AfterOneFrame_InitializesPlayer()
    {
        var gameObject = new GameObject("Player");

        try
        {
            var initializer = gameObject.AddComponent<PlayerInitializer>();

            yield return null;

            Assert.That(initializer.IsInitialized, Is.True);
        }
        finally
        {
            Object.Destroy(gameObject);
        }
    }
}

yield return null waits until the next frame.

Object.Destroy is delayed until the end of the frame. try/finally ensures that destruction is requested even when an assertion fails. For fixtures that create multiple objects, or when destruction must complete before the next test, centralize cleanup in [UnityTearDown] and wait one frame.

Avoid arbitrary frame waits:

// Avoid this when there is no reason for exactly ten frames.
for (var i = 0; i < 10; i++)
{
    yield return null;
}

Prefer a completion condition with an upper bound:

[UnityTest]
public IEnumerator Load_WhenStarted_CompletesWithinFrames()
{
    var gameObject = new GameObject("Loader");

    try
    {
        var loader = gameObject.AddComponent<TestLoader>();
        loader.Begin();

        const int maxFrames = 120;
        for (var frame = 0; frame < maxFrames && !loader.IsCompleted; frame++)
        {
            yield return null;
        }

        Assert.That(
            loader.IsCompleted,
            Is.True,
            "Loading did not complete within 120 frames.");
    }
    finally
    {
        Object.Destroy(gameObject);
    }
}

Do not use a frame limit for work whose duration depends heavily on machine performance or real I/O. For those cases, inject the dependency or expose an explicit completion signal.

Choose Test or UnityTest by behavior

Use [Test] when the operation is synchronous and does not need frame progression:

[Test]
public void Calculate_WhenCalled_ReturnsExpected()
{
    // Synchronous behavior
}

Use [UnityTest] when you need:

yield return null
coroutine progression
WaitForFixedUpdate
lifecycle changes across frames
Unity-specific yield instructions

A test in a PlayMode assembly does not automatically require [UnityTest]. A normal [Test] is valid there when it completes synchronously.

Keep physics tests broad and deterministic

A physics test may wait for fixed updates:

[UnityTest]
public IEnumerator Rigidbody_AfterFixedUpdate_FallsDown()
{
    var gameObject = GameObject.CreatePrimitive(PrimitiveType.Cube);

    try
    {
        gameObject.AddComponent<Rigidbody>();
        var initialY = gameObject.transform.position.y;

        yield return new WaitForFixedUpdate();
        yield return new WaitForFixedUpdate();

        Assert.That(
            gameObject.transform.position.y,
            Is.LessThan(initialY));
    }
    finally
    {
        Object.Destroy(gameObject);
    }
}

This verifies only the broad behavior: gravity moves the object downward. Exact coordinates after a fixed number of frames are fragile because they depend on Unity version, physics settings, fixed delta time, and floating-point behavior.

Prefer these strategies:

use tolerances instead of exact floating-point equality
verify direction or range rather than a precise final coordinate
extract your own decision logic into pure C# tests
set and restore physics settings explicitly
isolate high-precision simulation in a dedicated suite

You do not need to retest Unity's physics engine. Test that your code configures it correctly and interprets its results correctly.

Test asynchronous code without real waiting

Unity Test Framework supports tests that return .NET Task.

using System.Threading.Tasks;
using NUnit.Framework;

public sealed class UserRepositoryTests
{
    [Test]
    public async Task LoadAsync_ExistingUser_ReturnsUser()
    {
        var repository = new FakeUserRepository();
        repository.Add(new User(id: 10, name: "Alice"));

        var user = await repository.LoadAsync(10);

        Assert.That(user.Name, Is.EqualTo("Alice"));
    }
}

Avoid real delays:

// Avoid this in an ordinary unit test.
await Task.Delay(5000);

Twenty five-second tests already add 100 seconds. Real network access also makes results depend on authentication, server data, and connectivity.

Most asynchronous tests should verify the result, error conversion, cancellation, state update, and duplicate-execution rules rather than elapsed time.

Inject external work behind an interface:

public interface IUserApi
{
    Task<UserDto> GetAsync(int userId);
}

public sealed class UserService
{
    private readonly IUserApi _api;

    public UserService(IUserApi api)
    {
        _api = api;
    }

    public async Task<User> LoadAsync(int userId)
    {
        var dto = await _api.GetAsync(userId);
        return new User(dto.Id, dto.Name);
    }
}

Use a fake that completes immediately:

public sealed class FakeUserApi : IUserApi
{
    private readonly UserDto _response;

    public FakeUserApi(UserDto response)
    {
        _response = response;
    }

    public Task<UserDto> GetAsync(int userId)
    {
        return Task.FromResult(_response);
    }
}

Then test conversion without network access:

[Test]
public async Task LoadAsync_ApiSucceeds_ConvertsDto()
{
    var api = new FakeUserApi(new UserDto(10, "Alice"));
    var service = new UserService(api);

    var user = await service.LoadAsync(10);

    Assert.That(user.Id, Is.EqualTo(10));
    Assert.That(user.Name, Is.EqualTo("Alice"));
}

Keep real connectivity checks in a small integration suite with controlled credentials and environments.

Awaitable and UniTask require extra care

Unity 6 projects increasingly use Awaitable, while many existing projects use UniTask.

Separate two questions:

What return type does the test method use?
What asynchronous type does production code return?

For Unity Test Framework 1.6, prefer supported async Task test methods. Use [UnityTest] and IEnumerator for coroutine-style frame tests. Production code may return Awaitable or UniTask, but tests must be able to observe completion.

Being awaitable does not mean a workflow is safe in an EditMode test. Pure C# transformations and cancellation rules belong in EditMode. Operations based on Awaitable.NextFrameAsync, UniTask Yield or DelayFrame, scene loading, Addressables, and Unity object lifecycles should be tested in PlayMode or in a built Player.

Important constraints are that Unity Awaitable instances are pooled and must not be awaited twice; UniTask should also be treated as single-consumption unless its documented preservation mechanisms are used. PlayerLoop-dependent APIs can differ across EditMode, PlayMode, Player, and BatchMode. Return to the main thread before touching Unity APIs, avoid async void, UniTaskVoid, and .Forget() in testable inner APIs, and provide cancellation for operations that may not complete.

A production event handler may need fire-and-forget behavior. Keep the inner operation awaitable and test that inner method directly. Otherwise an exception or state change can occur after the test has already finished and leak into another test.

Also run PlayerLoop-dependent asynchronous tests in CI with -batchmode. Do not terminate the Editor before the test result XML and exit code are produced.

Inject time and randomness

Current time and randomness are common sources of flaky tests.

Avoid reading local time inside business logic:

public bool CanReceiveDailyBonus()
{
    return DateTime.Now.Date > _lastReceivedAt.Date;
}

The result changes at a date boundary and may differ across CI time zones.

Make the clock explicit:

public interface IClock
{
    DateTimeOffset UtcNow { get; }
}

public sealed class DailyBonusService
{
    private readonly IClock _clock;

    public DailyBonusService(IClock clock)
    {
        _clock = clock;
    }

    public bool CanReceive(DateTimeOffset lastReceivedAt)
    {
        return _clock.UtcNow.Date >
               lastReceivedAt.ToUniversalTime().Date;
    }
}

Use a fixed clock in tests:

public sealed class FixedClock : IClock
{
    public FixedClock(DateTimeOffset utcNow)
    {
        UtcNow = utcNow.ToUniversalTime();
    }

    public DateTimeOffset UtcNow { get; }
}

[Test]
public void CanReceive_WhenUtcDateChanged_ReturnsTrue()
{
    var clock = new FixedClock(
        new DateTimeOffset(2026, 7, 26, 0, 0, 0, TimeSpan.Zero));
    var service = new DailyBonusService(clock);

    var result = service.CanReceive(
        new DateTimeOffset(2026, 7, 25, 23, 59, 59, TimeSpan.Zero));

    Assert.That(result, Is.True);
}

The actual product specification must also define whether the source of truth is UTC, server time, or a region-specific reset time.

Randomness should be injected in the same way:

public interface IRandom
{
    int Range(int minInclusive, int maxExclusive);
}

A fake can return a chosen value so rare drops and critical-hit branches are deterministic. This also helps replay systems, debugging, and synchronization with a server.

A mock library is optional

Do not introduce a mocking framework merely because an article about testing mentions mocks. A handwritten fake is often clearer in Unity projects.

public sealed class RecordingAnalytics : IAnalytics
{
    public List<string> Events { get; } = new();

    public void Send(string eventName)
    {
        Events.Add(eventName);
    }
}

[Test]
public void Purchase_WhenSucceeded_SendsAnalyticsEvent()
{
    var analytics = new RecordingAnalytics();
    var service = new PurchaseService(analytics);

    service.Complete();

    Assert.That(analytics.Events, Does.Contain("purchase_completed"));
}

Handwritten fakes are easy to inspect, debug, and keep compatible across Unity and .NET versions. A mocking library becomes useful when many dependencies require extensive call and argument verification.

If mock setup dominates the test, the production class may have too many responsibilities.

Test exceptions and logs

For synchronous exceptions, use Assert.Throws:

[Test]
public void Constructor_MaxHpIsZero_ThrowsArgumentOutOfRangeException()
{
    Assert.Throws<ArgumentOutOfRangeException>(
        () => new Player(maxHp: 0));
}

Be careful with Assert.ThrowsAsync in Unity. Unity's documentation warns that blocking the caller while an operation needs the main thread can freeze the Editor. A safe pattern is to await in an async Task test and inspect the exception with try/catch:

[Test]
public async Task LoadAsync_WhenApiFails_ThrowsUserLoadException()
{
    try
    {
        await _service.LoadAsync(userId: 10);
        Assert.Fail("UserLoadException was not thrown.");
    }
    catch (UserLoadException exception)
    {
        Assert.That(exception.ErrorCode, Is.EqualTo("network_error"));
    }
}

For failures that are part of normal control flow, a result type can be clearer than exceptions.

Unity normally fails a test when an unexpected error or exception is logged. Register expected logs explicitly:

using NUnit.Framework;
using UnityEngine;
using UnityEngine.TestTools;

[Test]
public void Load_InvalidId_LogsError()
{
    LogAssert.Expect(LogType.Error, "Invalid user id: -1");

    var loader = new UserLoader();
    loader.Load(-1);
}

Use a regular expression for dynamic values:

using System.Text.RegularExpressions;

LogAssert.Expect(
    LogType.Error,
    new Regex(@"Invalid user id: -?\d+"));

Do not use logs as the only failure signal when callers must react. Return a result, throw a meaningful exception, or expose a state that can be asserted.

Isolate state with SetUp and TearDown

Every test must behave the same alone and as part of the full suite.

public sealed class PlayerControllerTests
{
    private GameObject _gameObject;
    private PlayerController _controller;

    [SetUp]
    public void SetUp()
    {
        _gameObject = new GameObject("Player");
        _controller = _gameObject.AddComponent<PlayerController>();
    }

    [TearDown]
    public void TearDown()
    {
        Object.DestroyImmediate(_gameObject);
    }

    [Test]
    public void SetSpeed_PositiveValue_UpdatesSpeed()
    {
        _controller.SetSpeed(5f);

        Assert.That(_controller.Speed, Is.EqualTo(5f));
    }
}

In PlayMode, destruction is delayed. Use [UnityTearDown] when you must destroy multiple objects and wait for completion:

private readonly List<GameObject> _createdObjects = new();

[UnityTearDown]
public IEnumerator TearDown()
{
    foreach (var gameObject in _createdObjects)
    {
        if (gameObject != null)
        {
            Object.Destroy(gameObject);
        }
    }

    _createdObjects.Clear();

    yield return null;
}

Record each created object immediately after creation so cleanup still occurs after an assertion failure.

Common leaks include static fields, singletons, PlayerPrefs, time and physics settings, Random.state, scenes, temporary assets, event subscriptions, cancellation sources, Addressables handles, and DontDestroyOnLoad objects.

Save global settings before changing them and restore them in teardown:

private float _originalTimeScale;

[SetUp]
public void SetUp()
{
    _originalTimeScale = Time.timeScale;
    Time.timeScale = 2f;
}

[TearDown]
public void TearDown()
{
    Time.timeScale = _originalTimeScale;
}

Never depend on test order

A suite that assumes this order is fragile:

1. CreateUser
2. UpdateUser
3. DeleteUser

UpdateUser fails when run by itself. Each test should create and remove its own state:

[Test]
public void UpdateUser_ExistingUser_ChangesName()
{
    var repository = new InMemoryUserRepository();
    repository.Add(new User(10, "Before"));

    repository.Update(new User(10, "After"));

    Assert.That(repository.Find(10).Name, Is.EqualTo("After"));
}

Long end-to-end flows can be useful, but treat them as a separate scenario layer rather than chaining unit tests.

Write tests that survive refactoring

Test observable behavior instead of implementation details.

Private methods are implementation details; extract a separate responsibility when it deserves direct testing. Call counts alone do not prove player-visible behavior, so combine interactions with output or state assertions. Avoid hard-coding Transform hierarchy details: a UI test tied to a path such as this breaks during harmless cleanup:

Canvas/Root/Window/Content/Panel/Buttons/Button_01

Assert identifiers, components, and visible states that are part of the specification, not child indices that exist only for implementation convenience.

Wait for completion, not elapsed time

Prefer a completion flag, event, or task over:

yield return new WaitForSeconds(3f);

Keep whole-scene tests rare

Scene tests are valuable but expensive to prepare and diagnose. Build a pyramid of pure logic tests, prefab-level tests, and a small number of scene-level scenarios.

Testable design does not mean removing MonoBehaviour

MonoBehaviour is the correct place to receive Unity events, hold Inspector references, and control GameObjects. The problem is placing game rules, storage, networking, time, randomness, and presentation logic in the same component.

A useful division is:

PlayerPresenter : MonoBehaviour
├── receives input and lifecycle events
├── updates the View
└── calls PlayerUseCase

PlayerUseCase : Pure C#
├── damage and item rules
├── state transitions
└── calls repositories

Cover PlayerUseCase with many fast EditMode tests. Give PlayerPresenter a small number of tests that verify wiring between Unity events, the use case, and the view.

A dependency-injection container is not required. Constructors, initialization methods, serialized references, or factories are sufficient when they make dependencies explicit.

Introduce tests into an existing project incrementally

Do not begin by redesigning the entire codebase.

1. Select frequently changed, high-impact rules

Good first targets include:

paid-item grants
save-data migration
daily reset logic
stamina recovery
damage formulas
reward selection
API response conversion
master-data validation

2. Add characterization tests

When the intended specification is unclear, record the current input and output before refactoring. A characterization test does not claim that the existing implementation is ideal. It prevents accidental behavior changes while you improve it.

3. Cut one Unity-dependent boundary

Extract the dependency that blocks testing most: time, randomness, networking, or file I/O. There is no need to convert the entire project to a new architecture at once.

4. Add a regression test with each bug fix

When possible:

reproduce the bug with a failing test
fix the code
confirm that the test passes

5. Standardize new and modified code first

A rule that new features and changed high-risk code receive tests is more sustainable than trying to cover every legacy class immediately.

Decide what not to test

More tests do not automatically mean higher quality.

Do not retest Unity's own APIs or trivial properties without custom rules. Pixel-perfect visuals, animation appeal, input feel, thermal behavior, and device memory need QA, screenshots, performance tests, or device runs. Avoid detailed tests for short-lived prototypes, but still cover complex calculations. Derive expectations from specification examples rather than copying the production formula into the test.

Run tests in CI

Once tests matter, manual execution is not enough.

A conceptual Windows command for EditMode tests is shown below. The example assumes that CI provides the path to the project-pinned Unity Editor through an environment variable named UNITY_EDITOR_PATH.

$UnityPath = $env:UNITY_EDITOR_PATH

if ([string]::IsNullOrWhiteSpace($UnityPath) -or
    -not (Test-Path $UnityPath))
{
    throw "UNITY_EDITOR_PATH is not configured correctly."
}

& $UnityPath `
  -runTests `
  -batchmode `
  -projectPath "D:\Projects\MyGame" `
  -testPlatform EditMode `
  -testResults "D:\TestResults\editmode-results.xml" `
  -logFile "D:\TestResults\editmode-editor.log"

Run PlayMode separately:

& $UnityPath `
  -runTests `
  -batchmode `
  -projectPath "D:\Projects\MyGame" `
  -testPlatform PlayMode `
  -testResults "D:\TestResults\playmode-results.xml" `
  -logFile "D:\TestResults\playmode-editor.log"

UNITY_EDITOR_PATH is not a Unity-reserved name. It is only an example of how to provide the exact Editor executable chosen by your project.

At minimum, retain:

test-result XML
Editor log
Unity process exit code
Unity Editor version
branch and commit hash

Layer the pipeline: pull requests run compilation, fast EditMode tests, critical validation, and a small PlayMode smoke suite; main-branch builds run the full Editor suite and asset checks; nightly or release jobs run built-Player, target-platform, long-scenario, and performance tests. Do not put every slow test on every pull request.

Also avoid adding -nographics blindly when tests require rendering or a GPU-dependent path.

Use categories as CI execution units

Categories are useful only when they are connected to actual workflows.

[Category("Fast")]
[Test]
public void Calculate_ReturnsExpected()
{
}

[Category("AssetValidation")]
[Test]
public void ValidateAllAssets()
{
}

[Category("Integration")]
[UnityTest]
public IEnumerator LoginFlow_Completes()
{
    yield return null;
}

Run the Fast EditMode category in CI:

& $UnityPath `
  -runTests `
  -batchmode `
  -projectPath "D:\Projects\MyGame" `
  -testPlatform EditMode `
  -testCategory "Fast" `
  -testResults "D:\TestResults\fast-editmode-results.xml" `
  -logFile "D:\TestResults\fast-editmode-editor.log"

Unity Test Framework also supports filtering by test assembly with -assemblyNames. Check the command-line reference for the exact syntax supported by your Unity version, including multiple categories and exclusions.

Keep the category list small and aligned with pipeline stages. Examples include Fast, Integration, Scene, AssetValidation, RequiresGraphics, RequiresDevice, and Performance.

Do not leave [Ignore] without a reason. Record the issue, reason, and condition for re-enabling the test.

Do not optimize for 100% coverage

Coverage shows which lines ran, not whether important behavior was asserted. Prioritize rules such as preventing duplicate paid-item grants, preserving save data during migration, enforcing daily-reward and currency caps, and avoiding duplicate requests during retries. Use coverage to find suspicious gaps, not as the sole performance target.

Monitor test duration

Developers stop running slow suites. Watch for EditMode tests that take seconds, repeated full AssetDatabase scans, unnecessary scene loads, real services, arbitrary waits, and expensive setup. Separate fast and slow suites, record duration in CI, and never improve speed by sharing mutable state between tests.

Common failure patterns

Avoid five recurring mistakes:

Do not write every test in PlayMode; keep game rules in pure C# where possible.
Do not add test-only branches to production code; inject alternate dependencies instead.
Do not depend on the scene that happened to be open when Test Runner started.
Do not hide unexpected errors with broad LogAssert.ignoreFailingMessages or retries.
Review test code for weak assertions, arbitrary waits, and cleanup leaks.

A minimal team policy

A small rule set is enough to begin:

Prefer EditMode for game rules and use [UnityTest] only for frame progression.
Make tests independent and clean up objects, assets, events, and global state.
Replace real time, real networks, current time, and uncontrolled randomness with explicit dependencies.
Add regression tests for important bug fixes.
Run a fast suite on pull requests and record why any test is ignored.
Explicitly decide which concerns remain in QA, device, or performance testing.

Measure whether tests reduce regression risk and verification time, not merely how many tests exist.

Recommended adoption priority

Start with save migration, paid-item grants, response conversion, date rules, reward and currency calculations, caps, duplicate IDs, and recurring bugs. Next, add prefab, scene, Addressables, localization, presenter, state-machine, and analytics validation. Visual appeal, input feel, GPU behavior, device heat, memory pressure, long sessions, and multi-device communication need QA, performance, screenshot, or scenario testing rather than ordinary unit tests.

Unreal Engine uses a different stack—Automation Framework, Automation Spec, Functional Testing, and Gauntlet—so it is better treated in a separate article.

Conclusion

Unity testing is not about reproducing the entire game in every test. Cover game rules and data transformations with fast EditMode tests, validate assets with focused editor checks, and use PlayMode only where lifecycle events, frames, scenes, or physics are part of the behavior.

For asynchronous work, inject external services, clocks, randomness, storage, and cancellation so tests can observe completion without real waiting. Existing projects can start with high-impact rules, recurring bugs, save migration, and static asset validation instead of an immediate rewrite.

The useful metric is whether the team can change the game and verify critical behavior quickly. Unity Test Framework is a programmer's safety net, not a replacement for QA.

References

Using Unreal MCP in UE 5.8 from Codex: Setup, Toolsets, and Safe Editor Automation

GameDevToolLab — Tue, 28 Jul 2026 05:30:59 +0000

Introduction

Unreal Engine 5.8 adds Unreal MCP, an experimental plugin that exposes Unreal Editor operations to AI agents through the Model Context Protocol. Once Codex is connected, it can inspect or edit actors, configure lighting, create material instances, run automation tests, and invoke project-specific editor tools from natural language.

That does not mean you should hand a production project to Codex and hope it figures everything out.

In UE 5.8, Unreal MCP is still experimental. Epic Games notes that APIs and data formats may change. Its HTTP server has no authentication layer, and tool calls are executed serially on Unreal Engine's game thread. Without guardrails, an agent can edit the wrong level, save an asset to the wrong folder, duplicate an object after a timeout, or conflict with another connected client.

This guide builds the integration in stages: understand the architecture, connect Codex, verify reads, allow one sandboxed write, then add approval, recovery, source-control, and custom-tool rules.

Version note: This article is based on UE 5.8 and Codex documentation checked on July 21, 2026. It is an implementation and operations guide, not a repeated benchmark. Verify the plugin settings, Output Log, and actual schemas in your installed build before adoption.

Understand the three Unreal-side layers

Codex CLI / Codex IDE extension
        │ MCP over Streamable HTTP
        ▼
http://127.0.0.1:8000/mcp
        │
        ▼
Unreal Editor
  ├─ Unreal MCP (ModelContextProtocol)
  │    └─ Server, connection, Tool Search
  ├─ Toolset Registry
  │    └─ Toolset discovery and schemas
  └─ AllToolsets / individual toolsets
       └─ Actor, scene, material, and other operations

The Plugin Browser name is Unreal MCP; its identifier and console-command prefix are ModelContextProtocol.

Unreal MCP mainly provides the server and protocol endpoint. The Toolset Registry discovers executable operations and generates schemas. AllToolsets enables the toolsets bundled with UE 5.8.

Enabled state	Meaning
Unreal MCP only	The server exists, but expected editor tools may be absent.
Toolset Registry	Unreal can discover toolsets; it is enabled as a dependency.
`AllToolsets`	Bundled UE 5.8 toolsets are enabled together.
Selected toolsets only	Smaller exposure, but you manage features and dependencies.

Use AllToolsets for initial connectivity testing. For regular work, disable unnecessary toolsets and narrow permissions on both Unreal and Codex.

Unreal MCP can expose actor editing, lighting, material-instance creation, Slate inspection, automation tests, and custom project tools. It is not a UI macro. Codex can call only tools published by the server, and vague instructions do not reliably identify the correct asset, level, coordinate space, save location, or overwrite policy.

UE 5.8's bundled implementation focuses on MCP Tools rather than Resources or Prompts. A connected server showing no Resources is not necessarily broken. Tool calls also run serially on the game thread, so do not let multiple Codex sessions or MCP clients issue overlapping writes to one editor.

Prepare a disposable sandbox

Do not begin in a production map. Use:

a UE 5.8 test project or production-project copy;
a dedicated source-control branch;
a level such as MCP_Sandbox;
a folder such as /Game/MCPTest;
Codex CLI or the Codex IDE extension;
a commit or checkpoint before the first write.

Keep the level simple. A floor, one light, and one static mesh are enough. Avoid World Partition, active Sequencer work, or anything that makes diffs harder to understand.

Before expanding the scope, prove that Codex connects to the intended editor, reads the selected actor accurately, and discovers tool schemas. It must also limit writes to the requested level and folder, re-read saved results, and stop on unexpected state. Check for actors left in another level, duplicate assets, extra components, and unsaved packages.

Install Codex

Skip this section if Codex CLI is already available.

Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

macOS or Linux:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Node.js and npm:

npm install -g @openai/codex

The first two are official installation paths but execute a remote script directly. If pipe-to-shell installation is prohibited, inspect the script first, use npm or Homebrew, install an official GitHub release, or follow your internal distribution process.

Configure Unreal Editor

Open Edit > Plugins, enable Unreal MCP, and restart when prompted. The Toolset Registry dependency should be enabled automatically. Then enable AllToolsets and restart again if required.

Open Edit > Editor Preferences > General > Model Context Protocol. The UE 5.8 documentation lists these defaults:

Setting	Default
Auto Start Server	`false`
Server Port Number	`8000`
Server URL Path	`/mcp`
Enable Tool Search	`true`

After an engine update, treat the values shown by your editor and Output Log as authoritative.

Keep Auto Start disabled during early testing and start the server manually:

ModelContextProtocol.StartServer

To specify a port:

ModelContextProtocol.StartServer 8000

The default endpoint is:

http://127.0.0.1:8000/mcp

Search Output Log for LogModelContextProtocol and confirm the bind address, port, and path. Stop the server when finished:

ModelContextProtocol.StopServer

The server has no authentication layer, so leaving it running indefinitely is a poor default.

Generate the Codex configuration

Run this in the Unreal Editor console:

ModelContextProtocol.GenerateClientConfig Codex

Codex uses ~/.codex/config.toml for user-level settings and can read .codex/config.toml from a trusted project. Check Output Log for the generated destination.

The Codex TOML generation step is effectively write-once: the generator does not overwrite an existing TOML. The file itself remains editable. If other MCP servers are already configured, merge the Unreal entry manually.

UE 5.8's Unreal MCP uses HTTP and Server-Sent Events, not stdio or WebSocket transport. Register a Streamable HTTP url:

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8000/mcp"
required = false
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

required = false prevents an unavailable editor from blocking unrelated Codex work. The default tool timeout is 60 seconds; 120 is only an initial adjustment for operations that consistently exceed it. After a timeout, inspect the editor before retrying because an operation may have completed or partially changed state.

Keep default_tools_approval_mode = "prompt" while learning the exposed schemas. The writes mode allows tools marked read-only and prompts for others, but Unreal's default Tool Search funnels inner operations through call_tool. Codex may not classify each inner operation independently, so writes is not automatically a fine-grained safety boundary.

Important: Codex's filesystem sandbox and MCP operations inside Unreal Editor are different boundaries. Limiting workspace writes does not necessarily stop an approved MCP tool from changing a level or asset. Combine approval, limited toolsets, sandbox levels, dedicated content folders, and source control.

Start Codex from the project root

cd C:\Work\Unreal\MCPExample
codex

In the Codex TUI, inspect servers active in the current session with:

/mcp

From a terminal, list configured servers with:

codex mcp list

codex mcp list confirms configuration registration; it does not prove the Unreal endpoint is reachable. /mcp shows the current-session state. End-to-end verification requires a response from list_toolsets or describe_toolset, or a successful MCP Inspector connection.

Project-local .codex/config.toml is loaded only for a trusted project. If a user-level entry works but the project entry does not, check the launch directory and trust state.

Why only three tools may be visible

With Enable Tool Search enabled, Unreal MCP initially exposes three meta-tools instead of hundreds of schemas:

Tool	Purpose
`list_toolsets`	Lists available toolsets.
`describe_toolset`	Returns schemas inside a toolset.
`call_tool`	Invokes an inner tool by toolset, name, and arguments.

These are the UE 5.8 documented names; confirm them with /mcp or MCP Inspector after an update.

This design affects allowlists. Codex's enabled_tools filters names exposed by the server. When Tool Search collapses operations behind call_tool, allowing that outer tool does not create a separate permission rule for every inner tool.

For schema discovery only:

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8000/mcp"
enabled_tools = ["list_toolsets", "describe_toolset"]
default_tools_approval_mode = "prompt"

Add execution only when ready:

enabled_tools = ["list_toolsets", "describe_toolset", "call_tool"]

Keep approval enabled and reduce active Unreal toolsets. Disabling Tool Search exposes individual tools and permits a more precise Codex allowlist, but increases the initial schema payload and ongoing maintenance for renamed schemas, stale allowlists, and accidental over-permission.

Verify reads before writes

First, discover schemas without invoking an inner operation:

Check the Unreal MCP connection without changing any editor state.

1. Use list_toolsets to list available toolsets.
2. Identify candidates for actors, scenes, and material instances.
3. Use describe_toolset and separate read operations from writes.
4. Do not invoke call_tool. Report only the tools and arguments you would use next.

After review, add call_tool to enabled_tools, restart Codex, select a cube in MCP_Sandbox, and request a read:

Read the actor currently selected in Unreal Editor.
Report Actor Label, Class, Object Path, world Transform, and owning Level.
Do not modify, save, or change the selection.
Inspect the schema first, then perform only the read operation.

Compare the response with the editor. Move the cube and read again to detect stale data. A successful check identifies the intended editor state, distinguishes Actor Label from Object Path, reports the correct world transform, causes no side effects, and names the toolset and tool used.

Do not proceed to writes until this is reliable.

Make the first write small and observable

Add one point light to the sandbox rather than generating a complex Blueprint:

Use Unreal MCP to edit only the open MCP_Sandbox level.

Goal:
- Add one Point Light named MCP_TestPointLight.
- Location: X=0, Y=0, Z=300.
- Intensity: 5000.

Rules:
- Show the toolset, tool, arguments, and target before execution.
- Wait for approval before call_tool.
- If the actor already exists, stop instead of duplicating it.
- Do not modify another level, asset, or Project Setting.
- Re-read the result before saving.
- Never use Save All; save only the target level.
- Re-read the Object Path and values after saving.
- Stop if any unexpected actor or component appears.

The completion criterion is not a confident chat message. Use this sequence: plan and approve → execute one operation → re-read → save only the target package → re-read again → inspect the editor and source-control diff.

Do not split writes across multiple Codex subagents. A second agent can invalidate the assumptions of an already approved plan.

Fix material and test inputs explicitly

For a Material Instance, define the parent, destination, asset name, allowed parameters, overwrite behavior, and verification:

Create one Material Instance through Unreal MCP.

Parent: /Game/MCPTest/Materials/M_Master
Output: /Game/MCPTest/Materials/Instances/MI_MCP_Red
BaseColor: R=1, G=0, B=0, A=1
Roughness: 0.6

Stop if the asset already exists, the output folder is missing, or either parameter is absent.
Do not modify the parent or anything outside /Game/MCPTest.
Inspect the tool schema first. After creation and after saving, re-read the parent,
parameter values, and Object Path. Save only the new asset.

Never leave overwrite policy to the tone of natural language. Choose stop, another name, or explicit approval.

Automation Tests are often a lower-risk starting point, although tests can still load maps or create assets:

Run only the Automation Test Project.MCP.Smoke.
Confirm an exact name match first.
Do not modify code, Blueprints, or config, and do not auto-fix failures.
Report the result, failed test names, important log lines, and duration.

Keep observation and modification in separate turns.

Put persistent rules in AGENTS.md

Store repeated project rules in AGENTS.md at the project root:

# Unreal MCP Working Agreement

## Scope
- Writes are limited to `/Game/MCPTest` and `MCP_Sandbox`.
- Do not modify other levels, assets, plugins, or Project Settings.

## Workflow
- Inspect schemas before execution.
- Show toolset, tool, arguments, and targets before every write.
- Execute `call_tool` one at a time; never parallelize writes.
- After a timeout, re-read state instead of resending the write.
- Check for duplicates before creation.
- Re-read after creation and after saving.
- Never use `Save All`.

## Stop conditions
- The target is outside the allowed scope.
- An existing asset has no overwrite policy.
- The schema changed, the editor is unresponsive, or an unexpected diff appears.
- The target editor instance cannot be identified unambiguously.

AGENTS.md is not an authorization system. Continue using MCP approval, limited toolsets, source control, and the sandbox. Start a new project-root session after changing it when you need the new instructions loaded.

Troubleshooting and MCP Inspector

If unreal-mcp does not appear or respond, check in this order:

Start the server and confirm its endpoint in Output Log.
Compare that endpoint with .codex/config.toml.
Confirm the project root and trust state.
Restart Codex; use codex mcp list for registration.
Use /mcp for current-session state.
Call list_toolsets or connect with MCP Inspector for live traffic.

Only seeing the three meta-tools is normal with Tool Search enabled. If list_toolsets is empty, confirm Unreal MCP, Toolset Registry, and AllToolsets, then restart the editor.

After adding or changing a toolset, run:

ModelContextProtocol.RefreshTools

Reconnect Codex afterward. A new C++ UFUNCTION declaration may require an editor restart rather than Live Coding alone.

If the port changes, update both Unreal and Codex:

[mcp_servers.unreal-mcp]
url = "http://127.0.0.1:8123/mcp"

A timeout does not prove nothing happened. Do not resend the same write. Check editor responsiveness, Output Log, the target object, and source-control diff, then plan only the remaining work.

To separate Codex issues from server issues, run MCP Inspector:

npx @modelcontextprotocol/inspector

The first run may download a package and require Node.js, npm, network access, and execution approval. Choose Streamable HTTP and connect to:

http://127.0.0.1:8000/mcp

Inspector shows exposed tools, schemas, argument forms, and protocol errors. It can also execute tools, so prefer discovery and reads while troubleshooting. If Inspector fails too, investigate Unreal. If Inspector works but Codex fails, focus on Codex configuration, approval, or prompt interpretation.

For more Unreal-side detail, temporarily use:

Log LogModelContextProtocol Verbose

Restore normal verbosity afterward and treat project logs as potentially sensitive.

Localhost is not authentication

Unreal MCP binds to loopback by default and rejects non-loopback origins, but it has no authentication layer. Do not casually bind it to 0.0.0.0, forward the port for remote use, expose it to a LAN without authentication, let several people control one editor, or use it as a production-build endpoint.

A VPN, office LAN, or localhost proxy is not a substitute for authentication. This article assumes Codex and Unreal Editor run on the same developer machine.

Repeated work belongs in narrow custom tools

Generic actor and scene tools are useful for exploration. Repeated workflows are safer as project-specific operations with fewer valid failure modes:

CreateValidatedEnemyActor(
  enemyDefinition,
  targetLevel,
  transform,
  outputFolder,
  overwritePolicy,
  dryRun
)

The implementation should validate scope and duplicates, return planned changes from dryRun, and verify source-control checkout or locks. It should group undoable editor changes in a transaction, run post-validation, track dirty packages, save only intended packages, and return structured state before and after saving.

MCP does not automatically wrap a tool call in an Unreal transaction. C++ FScopedTransaction and Python unreal.ScopedEditorTransaction help only with operations the editor can undo. Imports, saved packages, external files, and source-control state may need explicit compensation and checkpoints.

A practical flow is:

dryRun
→ validate input, permissions, and source control
→ execute undoable work in a transaction
→ post-validate
→ save target packages only
→ re-read state
→ return a structured result

On failure, report separately what was undone, cleaned up, and left for a human. In UE 5.8, custom toolsets can derive from unreal.ToolsetDefinition in Python or UToolsetDefinition in C++. After adding one, run ModelContextProtocol.RefreshTools and reconnect Codex.

The value of a custom tool is not merely convenience. Moving natural-language constraints into implementation reduces the choices through which the AI can fail.

PCG requires references and a reviewed plan

Epic also documents using Unreal MCP and LLMs with PCG graphs. PCG is a poor first connectivity test because a graph can be technically valid while its data flow is wrong or needlessly complex.

Some official examples assume Claude Code-specific supporting material. With Codex, place equivalent instructions in a Codex Skill, AGENTS.md, or a project reference document and require them to be read before planning. Have a human choose the reference graph and assets, ask Codex to explain the intended data flow, review the plan, and generate small sections in stages. A working MCP connection does not imply correct domain design.

Measure safety before adoption

Repeat the same tasks and record first-pass success, human intervention, out-of-scope changes, duplicate creation, and persistence after reload. Also track tool-call count, duration, recovery time, and schema stability after restarts or plugin updates.

Prioritize zero out-of-scope changes, understandable failures, and reliable recovery over a small speed improvement. Blueprints, materials, PCG graphs, and Sequencer content also require in-editor validation; a text diff alone rarely proves a visual asset is correct.

Conclusion

A safe UE 5.8 Unreal MCP workflow from Codex is:

Enable Unreal MCP and AllToolsets.
Start the local server with ModelContextProtocol.StartServer.
Generate the entry with ModelContextProtocol.GenerateClientConfig Codex.
Launch Codex from the project or workspace root.
Verify /mcp, list_toolsets, and describe_toolset before writing.
Use call_tool with approval and make one sandboxed change at a time.
Re-read after saving and inspect source-control diffs.
Move repeated work into narrow, validated custom tools.

Remember the division of responsibilities: Unreal MCP provides the server, Toolset Registry provides discovery and schemas, and AllToolsets provides bundled editor operations. Tool Search also funnels operations through call_tool, so an allowlist around that outer tool is not automatically a fine-grained permission model for every inner operation.

Treat Unreal MCP as an editor-extension entry point, not natural-language control for everything. Start with reads, expand to bounded sandbox writes, and only then expose reviewed project-specific tools.

References

Verified on July 21, 2026:

Unity 6.5 DirectStorage: Interpreting an 18.6% Load-Time Reduction and the 'Up to 40%' Claim

GameDevToolLab — Sun, 26 Jul 2026 00:26:43 +0000

Introduction

Unity introduced DirectStorage support in Unity 6.4 and expanded it in 6.5 so qualifying custom reads through AsyncReadManager can use the Windows DirectStorage path.

This makes the feature relevant to local map chunks, master data, and other large custom binaries as well as built-in assets. It does not make network transfer, parsing, object creation, scene activation, or shaders faster. The practical question is which part of a loading pipeline is eligible, how much time that part consumes, and whether the player actually submitted work to a DirectStorage queue.

What Unity 6.4 and 6.5 Changed

Unity 6.4 divided archive work into chunks, submitted lower-level reads in parallel, and moved decompression work into jobs. On Windows, Unity can replace that queue with DirectStorage for Texture, Mesh, and DOTS/ECS Entities asset data.

Unity 6.5 extends the path to C# reads performed through AsyncReadManager. Treat the following as minimum conditions:

Unity 6.5 and a Windows 64-bit player
Enable DirectStorage turned on
A local file read through AsyncReadManager
A test separated from Editor Play Mode and ordinary .NET file I/O
PIX evidence that the enabled build uses a DirectStorage queue

File.ReadAllBytes, FileStream, and ordinary file access inside a third-party library do not switch automatically.

Workload	Unity 6.5 status	Notes
Texture and Mesh	Supported	Windows player with DirectStorage enabled
Local AssetBundle or Addressables Texture/Mesh	Supported path	Only the local-file stage is relevant
DOTS Entities asset data	Supported	Explicitly documented by Unity
Custom `AsyncReadManager` reads	Conditional	Verify the queue in PIX
`File.ReadAllBytes` / `FileStream`	Not automatic	Requires an I/O redesign
Remote Addressables download	Not covered	Network transfer is separate
JSON / MessagePack parsing	Not covered	CPU work after reading
`Instantiate` / scene activation	Not covered	Object creation and initialization
DirectStorage GPU decompression	Not used	Unity 6.5 does not enable it automatically

AudioClip and other undocumented asset types should be treated as unconfirmed and checked with PIX or AsyncReadManagerMetrics.

Reading the Public Benchmark Correctly

A Unity Discussions user published an HDRP test on an SSD rated at roughly 5 GB/s sequential throughput. Later loads were compared to avoid the first PSO warm-up pass.

Condition	Reported load time
DirectStorage off	About 7.49 seconds
DirectStorage on	About 6.10 seconds
Difference	1.39 seconds

The elapsed-time reduction is:

(7.49 - 6.10) / 7.49 × 100 = 18.56%

The load time therefore fell by approximately 18.6%.

The post described the result as about “22% faster.” That uses a rate ratio:

7.49 / 6.10 = 1.2279...

The work completed at about 1.228 times the previous rate, a 22.8% processing-rate increase. Both numbers are valid, but “load-time reduction” should use 18.6% and state the denominator.

The same post showed HWiNFO values of about 15 MB/s off and 530 MB/s on. The poster also said the off value did not match the elapsed time and might be affected by Windows caching. That is not evidence for a “35x faster” claim.

Another user reported a 40% improvement for a Windows 10 scene containing 17 GB of Texture2D data. It is useful as a lead, not a universal prediction: detailed timings, repetitions, CPU, and SSD information were not provided.

Why “Up to 40%” Does Not Mean 40% Faster Total Loading

Unity's figure describes a favorable supported-I/O case. Total loading can also contain unsupported reads, decompression, deserialization, object creation, shader work, and scene activation.

Let p be the fraction of total time spent in eligible I/O and r the reduction in that section. The approximate total reduction is:

p × r

If only half of a 10-second load is eligible and that half improves by 40%, the total becomes about 8 seconds: a 20% reduction.

Enable DirectStorage and Control the Build

The setting is available at:

Edit
  > Project Settings
    > Player
      > Other Settings
        > Configuration
          > Enable DirectStorage

Unity 6.5 also exposes PlayerSettings.enableDirectStorage:

PlayerSettings.enableDirectStorage = true;

Unity issue UUM-133978 affected prerelease 6.4/6.5 versions. Unity lists fixes in 6000.4.1f1 and 6000.5.0a9, and the 6000.5.0f1 notes describe Project Settings, version-control, and C# support. Projects upgraded from the older storage location can start with the setting disabled, so recheck it.

A custom Build Profile can override global Player settings. The following sample intentionally requires the standard Platforms > Windows profile.

Place it in Assets/Editor/DirectStorageBuildMenu.cs or an Editor-only assembly.

#if UNITY_EDITOR
using System;
using System.IO;
using System.Linq;
using UnityEditor;
using UnityEditor.Build.Profile;
using UnityEditor.Build.Reporting;
using UnityEngine;

public static class DirectStorageBuildMenu
{
    [MenuItem("Build/Windows/DirectStorage A-B")]
    private static void BuildBoth()
    {
        ValidateBuildContext();
        bool original = PlayerSettings.enableDirectStorage;

        try
        {
            Build(false, "Builds/DS-Off/Game.exe");
            Build(true,  "Builds/DS-On/Game.exe");
        }
        finally
        {
            PlayerSettings.enableDirectStorage = original;
        }
    }

    private static void ValidateBuildContext()
    {
        if (EditorUserBuildSettings.activeBuildTarget !=
            BuildTarget.StandaloneWindows64)
        {
            throw new InvalidOperationException(
                "Activate the Windows 64-bit target before running this menu item.");
        }

        if (BuildProfile.GetActiveBuildProfile() != null)
        {
            throw new InvalidOperationException(
                "This sample expects the standard Platforms > Windows profile.");
        }
    }

    private static void Build(bool enabled, string output)
    {
        string[] scenes = EditorBuildSettings.scenes
            .Where(scene => scene.enabled)
            .Select(scene => scene.path)
            .ToArray();

        if (scenes.Length == 0)
            throw new InvalidOperationException("No enabled scenes were found.");

        string directory = Path.GetDirectoryName(output);
        if (!string.IsNullOrEmpty(directory))
            Directory.CreateDirectory(directory);

        PlayerSettings.enableDirectStorage = enabled;
        Debug.Log(
            $"Build DS={PlayerSettings.enableDirectStorage}, Unity={Application.unityVersion}, Output={output}");

        BuildReport report = BuildPipeline.BuildPlayer(new BuildPlayerOptions
        {
            scenes = scenes,
            locationPathName = output,
            target = BuildTarget.StandaloneWindows64,
            options = BuildOptions.None
        });

        if (report.summary.result != BuildResult.Succeeded)
            throw new InvalidOperationException(
                $"Build failed: {report.summary.result}");
    }
}
#endif

The script restores the original setting and fails instead of silently switching targets. Folder names and log lines are labels, not proof. Only the enabled build should show a DirectStorage queue in PIX.

Keep the Unity patch, packages, scripting backend, Graphics API, content, and every other build option identical.

Measure a Reproducible Windows Player

Editor Play Mode includes AssetDatabase behavior and persistent Editor caches, so use Windows player builds.

First run a stress test with large supported assets or a custom binary, then measure the real startup, transition, or streaming path. If only the stress test improves, investigate parsing, object creation, activation, and main-thread work. If neither improves, investigate the setting, target types, caching, OS, and PIX queue.

Unity's AssetBundle guide states that LoadFromFile and LoadFromFileAsync open LZMA bundles through conversion to an LZ4 in-memory file. That adds whole-bundle and memory effects, so validate the DirectStorage path first with LZ4 or an uncompressed bundle. Treat a production LZMA download/cache workflow as a separate condition.

Do not mix cold and warm runs. Alternate off and on builds for at least 10 runs; 20 to 30 is better for a production decision. Keep the median and p95, and record Unity version, Git commit, Windows version, CPU, storage, drivers, BitLocker, Graphics API, scripting backend, compression, and run number.

Record AssetBundle Timing to CSV

The following stress test mounts a local AssetBundle and loads every asset. Place the Windows bundle at Assets/StreamingAssets/ds_test so it is included in the player.

using System;
using System.Collections;
using System.Diagnostics;
using System.IO;
using UnityEngine;
using Debug = UnityEngine.Debug;

public sealed class BundleBenchmark : MonoBehaviour
{
    private const string CsvHeader =
        "utc,unity,condition,runIndex,mountMs,assetsMs,totalMs,assetCount";

    private string bundleName;
    private string condition;
    private int runIndex;

    private void Awake()
    {
        bundleName = Arg("-bundleName", "ds_test");
        condition = Arg("-condition", "Unknown");
        int.TryParse(Arg("-runIndex", "0"), out runIndex);
    }

    private IEnumerator Start()
    {
        yield return null;

        string path = Path.Combine(Application.streamingAssetsPath, bundleName);
        if (!File.Exists(path))
        {
            Debug.LogError($"Bundle not found: {path}");
            Quit();
            yield break;
        }

        Stopwatch total = Stopwatch.StartNew();
        Stopwatch mount = Stopwatch.StartNew();
        AssetBundleCreateRequest open = AssetBundle.LoadFromFileAsync(path);
        yield return open;
        mount.Stop();

        if (open.assetBundle == null)
        {
            Debug.LogError($"Load failed: {path}");
            Quit();
            yield break;
        }

        AssetBundle bundle = open.assetBundle;
        try
        {
            Stopwatch assets = Stopwatch.StartNew();
            AssetBundleRequest load = bundle.LoadAllAssetsAsync();
            yield return load;
            assets.Stop();
            total.Stop();

            string line = FormattableString.Invariant(
                $"{DateTime.UtcNow:O},{Application.unityVersion},{condition},{runIndex},{mount.Elapsed.TotalMilliseconds:F3},{assets.Elapsed.TotalMilliseconds:F3},{total.Elapsed.TotalMilliseconds:F3},{load.allAssets?.Length ?? 0}");

            string csv = Path.Combine(
                Application.persistentDataPath, "ds_results.csv");

            try
            {
                if (!File.Exists(csv) || new FileInfo(csv).Length == 0)
                    File.WriteAllText(csv, CsvHeader + Environment.NewLine);

                File.AppendAllText(csv, line + Environment.NewLine);
            }
            catch (Exception ex)
            {
                Debug.LogException(ex);
            }
        }
        finally
        {
            bundle.Unload(true);
            Quit();
        }
    }

    private static string Arg(string name, string fallback)
    {
        string[] args = Environment.GetCommandLineArgs();
        int index = Array.FindIndex(args, value =>
            string.Equals(value, name, StringComparison.OrdinalIgnoreCase));

        return index >= 0 && index + 1 < args.Length
            ? args[index + 1]
            : fallback;
    }

    private static void Quit()
    {
#if !UNITY_EDITOR
        Application.Quit();
#endif
    }
}

Example launches:

Builds\DS-Off\Game.exe -bundleName ds_test -condition DS-Off -runIndex 1
Builds\DS-On\Game.exe  -bundleName ds_test -condition DS-On  -runIndex 1

condition is only an aggregation label. In production, store OS, Graphics API, profiler state, cold/warm state, Build Profile, and diagnostic/release mode in separate columns.

Mount, Assets, and Total are wall-clock times until the coroutine resumes. They can include PlayerLoop scheduling, frame boundaries, and main-thread congestion; they are not pure storage timings. Use PIX, the Profiler, and AsyncReadManagerMetrics for queue-level analysis. The first run can also include JIT, type initialization, and first-use paths.

LoadAllAssetsAsync is deliberately a stress test. Also measure the actual Addressables key, scene, dependency, or subset-loading path used by the product.

Custom Binary Data with `AsyncReadManager`

AsyncReadManager.Read accepts a path and ReadCommand values containing offset, size, and destination-buffer information. A ReadHandle represents progress and completion.

This is not a mechanical replacement for File.ReadAllBytes. Production code must define unsafe-buffer ownership, allocator and release pairing, success/failure/cancellation cleanup, ReadHandle.Dispose() timing, range validation, and the boundary between background parsing and main-thread application. A mistake can cause a crash, memory corruption, or a leak, so start from Unity's official sample or a tested I/O wrapper.

Do not submit a read and immediately block the main thread on completion. Separate the pipeline and measure it as:

ReadMs  : Data reaches the buffer
ParseMs : Bytes become structured data
ApplyMs : Parsed data reaches Unity-side state

For open-world data, read a small header and chunk table first, then prioritize nearby cells. Request granularity, priority, cancellation, and backpressure remain game-side responsibilities.

Confirm the Path with Metrics and PIX

Use AsyncReadManagerMetrics only in diagnostic builds:

using Unity.IO.LowLevel.Unsafe;

#if ENABLE_PROFILER
AsyncReadManagerMetrics.StartCollectingMetrics();
// Run the workload.
AsyncReadManagerMetrics.StopCollectingMetrics();
#endif

-enable-file-read-metrics starts collection at process launch. Remove instrumentation and repeat the final measurement with a release-like build.

In PIX Timing Capture, enable File IO > File accesses. Compare the presence of the DirectStorage queue, Enqueue/Submit pattern, batch size, duration, I/O-waiting threads, and main-thread stalls between the two builds.

Unity supports DirectStorage on Windows 10 and 11, but Windows 11 is the better-optimized environment. First prove activation through the setting, Build Profile, and PIX queue; then compare Windows version, NVMe or SATA storage, BitLocker, and filter drivers.

On Windows 11, fsutil bypassIo can report I/O-stack blockers. It is a supporting diagnostic, not proof that Unity used DirectStorage.

fsutil bypassIo state /v "D:\Builds\DS-On"

The command accepts a volume, directory, or file path. Combine it with PIX and elapsed-time results.

Apply Existing Loading-Optimization Experience

DirectStorage rewards rather than replaces good loading architecture:

Remove synchronous choke points such as large File.ReadAllBytes calls and tasks completed immediately on the main thread.
Chunk large files so important data can be prioritized and cancelled.
Overlap work: read chunk N+2, parse N+1, and apply N on the main thread.
Revisit bundle boundaries and duplicated dependencies.
Track native buffers, decompressed data, Unity objects, and GPU-upload memory as overlapping peaks.
Judge success by time-to-interaction, median, p95, worst-frame duration, and minimum-spec memory—not the best run on a development PC.

Production Checklist

[ ] Unity 6.5 Windows 64-bit player and exact patch recorded
[ ] Every condition except DirectStorage fixed; Git commit recorded
[ ] DirectStorage queue appears only in the enabled PIX capture
[ ] Workload uses a supported asset type or AsyncReadManager
[ ] Stress test and actual product path both measured
[ ] I/O, parsing, object creation, and activation separated
[ ] LZ4 or uncompressed path validated before LZMA workflow testing
[ ] Cold and warm runs separated; median and p95 retained
[ ] OS, storage, BitLocker, filters, worst frame, and memory recorded

Conclusion

Unity 6.5 extends DirectStorage beyond built-in Texture, Mesh, and DOTS data to qualifying AsyncReadManager reads.

The public 7.49-second to 6.10-second case is an 18.6% elapsed-time reduction, not a promise for every project. Unity's “up to 40%” figure applies to favorable eligible I/O; its effect on total loading depends on how much of the pipeline that I/O occupies.

Build controlled off/on Windows players, confirm the enabled queue in PIX, separate storage from parsing and application, and decide from median, p95, worst-frame time, and memory on target hardware. DirectStorage is not a substitute for loading optimization. It is a lower-level path that lets good chunking, parallelism, and measurement pay off more effectively.

References

Unity Documentation

Unity Discussions

Microsoft Documentation

Unity 6.6 Finally Supports Dictionary Serialization: Do We Still Need Custom Implementations or Odin?

GameDevToolLab — Sun, 26 Jul 2026 00:25:38 +0000

Introduction

Unity projects constantly need mappings: an item ID to its definition, a status-effect type to its parameters, an input name to a Sprite, or a cell coordinate to its gameplay data. In ordinary C#, Dictionary<TKey, TValue> is the natural choice.

Until now, however, Unity could not directly serialize a regular Dictionary into a Scene, Prefab, or ScriptableObject, and the default Inspector could not display one. Teams usually worked around that limitation by converting keys and values into two Lists through ISerializationCallbackReceiver, adopting an existing SerializableDictionary, or bringing in Odin Inspector and Odin Serializer.

Unity 6.6 finally adds built-in serialization for the standard Dictionary<TKey, TValue>. The Inspector gets a dedicated editor with entry addition and removal, sorting, duplicate-key detection, and adjustable column widths.

That does not mean every custom serializer or every use of Odin immediately becomes obsolete. This article looks at the supported range, Inspector behavior, Prefab pitfalls, and migration concerns so that you can decide where the new built-in support is enough—and where it is not.

Important: This article is based on the Unity 6.6 Beta documentation available on July 15, 2026, specifically 6000.6.0b3. Attribute names, behavior, and limitations may change before the final release. Before adopting the feature in production, check the release notes and manual for the exact Unity version you intend to ship.

The conclusion first

When all of the following are true, there is now far less reason to create a new SerializableDictionary implementation:

Unity 6.6 or later can be your minimum supported Editor version.
The key and value types fit Unity's supported serialization rules.
The standard Inspector provides enough editing functionality.
You can accept the current Prefab Override behavior.

In this article, a plain Dictionary means the exact, non-derived Dictionary<TKey, TValue> type whose key and value are both supported by Unity serialization.

using System.Collections.Generic;
using UnityEngine;

[CreateAssetMenu(menuName = "Example/Item Price Table")]
public sealed class ItemPriceTable : ScriptableObject
{
    [SerializeField]
    private Dictionary<string, int> prices = new();

    public bool TryGetPrice(string itemId, out int price)
        => prices.TryGetValue(itemId, out price);
}

This example can be created from Create > Example > Item Price Table in the Project window. The prices field is stored in the ScriptableObject asset and can be edited in the Inspector.

The standard feature does not replace every existing solution:

Requirement	Default direction
Support Unity 6.5 or earlier	Keep the existing custom implementation or Odin
Serialize `SortedDictionary`, `HashSet`, or a Dictionary-derived type	Use custom serialization
Store interfaces, abstract types, or polymorphic managed references	Consider Odin or another dedicated mechanism
Provide search, bulk editing, or advanced validation UI	A Custom Editor or Odin is still useful
Migrate a large amount of existing custom or Odin data	Plan an explicit migration process

The most accurate interpretation is not “Unity solved every serialization problem.” It is that the extremely common need to serialize an ordinary Dictionary without a custom wrapper has finally become a built-in feature.

Why Dictionary serialization used to be painful

Through Unity 6.5, the official serialization rules did not support Dictionary. A common workaround copied entries into List<TKey> and List<TValue> before serialization, then paired elements with the same index to reconstruct the Dictionary after loading.

The basic idea is simple. Production behavior is not. A team still has to define:

What happens when the key and value counts differ.
How null and duplicate keys are handled.
What work is safe inside serialization callbacks.
How Undo and Prefab Overrides behave in a custom Inspector.
Whether each concrete type needs a derived class or Property Drawer.
How old serialized data remains compatible after the implementation changes.

A short serializer may be enough to “make it save.” Turning it into a tool that an entire team can edit safely is much more expensive. That is also why Odin has remained popular: it can solve both serialization and Inspector presentation instead of leaving every project to maintain both layers.

The important part of Unity 6.6 is therefore not merely that Dictionary data can be stored. Unity itself now owns the Inspector UI, warnings, Prefab Override integration, and serialization-rule diagnostics around the feature.

Minimal setup—and `[SerializeField]` is required even for public fields

The basic form is straightforward:

using System.Collections.Generic;
using UnityEngine;

public sealed class Inventory : MonoBehaviour
{
    [SerializeField]
    private Dictionary<string, int> itemCounts = new();
}

The same feature is available in ScriptableObject and inside nested classes or structs marked with [Serializable].

The easiest rule to miss is that Dictionary requires explicit opt-in. Unlike many traditionally supported Unity field types, making the field public is not enough.

// Demonstration only: public, but not serialized.
public Dictionary<string, int> notSerialized = new();

// Demonstration only: public and explicitly serialized.
[SerializeField]
public Dictionary<string, int> serialized = new();

notSerialized remains unsaved even though it is public. Any Dictionary that should be serialized needs [SerializeField], whether the field is private or public.

This avoids turning every public Dictionary in an existing project into serialized data merely because the Editor was upgraded. It makes serialization intentional rather than implicit.

In production code, private plus [SerializeField] is usually easier to control than a freely replaceable public field. Expose only the operations or read-only access that other code actually needs.

The serialization rules analyzer reports a public Dictionary without [SerializeField] as UAC1015. If a Dictionary is deliberately a runtime-only cache, consider marking that intent with [NonSerialized] rather than leaving its role ambiguous.

`[SerializeReference]` cannot be applied to the Dictionary field

Dictionary entries are stored inline as a sequence of key-value entries, so [SerializeReference] cannot be applied to the Dictionary field itself.

[SerializeReference] // Invalid
private Dictionary<string, IEffect> effects = new();

This example is unsupported for a second reason: the value type is an interface. Unity 6.6's Dictionary feature does not extend the polymorphic managed-reference behavior of [SerializeReference] into Dictionary fields.

The declared type must be exactly `Dictionary<TKey, TValue>`

The manual requires the field's declared type to be the exact Dictionary<TKey, TValue> type.

using System.Collections.Generic;
using UnityEngine;

[System.Serializable]
public sealed class ItemPriceDictionary : Dictionary<string, int>
{
}

public sealed class LegacyItemDatabase : ScriptableObject
{
    [SerializeField]
    private ItemPriceDictionary prices = new(); // Not handled by the new built-in backend
}

If an existing project uses derived types such as StringIntDictionary, upgrading to Unity 6.6 does not silently convert them to the new built-in representation. You need to change the declared type and migrate the stored data explicitly.

What the built-in Inspector can and cannot do

The standard Dictionary editor supports at least the following operations:

Add and remove entries with + and -.
Resize the key and value columns.
Sort the displayed rows by key in ascending or descending order.
Warn about duplicate and null keys.
Switch the display layout.
Show Prefab Overrides at the key or value level.

That covers a great deal of ordinary project configuration, but several details matter in production.

Sorting changes the display, not the stored order

Clicking the key column changes only the order shown in the Inspector. The serialized entry order remains insertion order.

This distinction matters for YAML diffs and Prefab Overrides. A Dictionary may look alphabetically sorted in the Inspector while the serialized file still follows a different order. Game logic also should not assign meaning to the Dictionary's enumeration order.

When priority or presentation order is part of the specification, store it explicitly in the value or use a List as the authoritative structure.

Duplicate keys can remain temporarily in serialized data

The Inspector does not immediately delete a duplicate row while you are editing. It keeps the row and shows a warning so that you can correct the data without losing the value.

According to the Unity 6.6 Beta documentation, loading serialized data that still contains duplicates produces a warning, and only the first entry in serialized order is added to the runtime Dictionary. Verify that behavior again in the final release and in the exact patch version used by your project.

As a result, the number of rows visible in serialized data may differ from Dictionary.Count at runtime. Which value survives depends on serialized insertion order, not the current sort order in the Inspector.

Do not treat the warning as harmless editor noise. Duplicate-key checks should be part of your content-validation process.

A Custom Inspector can retrieve duplicate positions through SerializedProperty.GetDictionaryDuplicateEntryIndices.

Null keys are preserved as placeholders, then omitted at runtime

When a UnityEngine.Object reference is used as a key, an unassigned field or missing reference can create a null-key row. The Inspector preserves that row as a placeholder so that the value is not immediately lost during editing.

A runtime Dictionary still cannot contain a null key. Unity warns during loading and leaves that entry out of the reconstructed Dictionary.

In other words, “visible in the Inspector” does not necessarily mean “present in the runtime Dictionary.”

There is no Multi-Object Editing, search, or filtering

In the Unity 6.6 Beta, Dictionary fields do not support Multi-Object Editing. Selecting multiple GameObjects or assets displays a Help Box instead of the Dictionary editor.

The standard Inspector also has no entry search or filtering. That is perfectly reasonable for a few dozen entries. It becomes a workflow problem when designers or developers must edit hundreds or thousands of records directly.

At that scale, a Custom Editor or external authoring pipeline is still the better tool.

Supported key and value types

The following are representative supported types rather than an exhaustive list. Run the exact types used by your project through the serialization rules analyzer for the Unity version you adopt.

Primitive and common built-in types such as int, float, double, bool, and string.
Enums whose underlying type is 32 bits or smaller.
Unity built-in serializable types such as Vector2, Vector3, and Color.
Custom classes and structs marked with [Serializable].
References to types derived from UnityEngine.Object.

Ordinary interfaces, abstract types, and custom types without [Serializable] are not supported. UnityEngine.Object inheritance is different because those values are stored as Unity object references.

Lists and arrays can be values, but not keys

These fields are valid:

[SerializeField]
private Dictionary<int, List<string>> stageEnemies = new();

[SerializeField]
private Dictionary<string, int[]> scoreTables = new();

Collection-like IEnumerable types such as List and array cannot be used as keys. string is the exception.

// Unsupported
[SerializeField]
private Dictionary<List<int>, string> invalid = new();

A mutable collection is a dangerous key even outside Unity's restrictions. Changing its contents can change equality or hash behavior after it has already been inserted.

A Dictionary cannot be placed directly inside a List or array

The following forms are unsupported:

[SerializeField]
private List<Dictionary<string, int>> histories = new(); // Unsupported

[SerializeField]
private Dictionary<string, int>[] tables; // Unsupported

Wrap the Dictionary in a serializable class or struct instead:

[System.Serializable]
public sealed class ItemCountTable
{
    [SerializeField]
    private Dictionary<string, int> values = new();
}

[SerializeField]
private List<ItemCountTable> snapshots = new();

The official manual also shows a Dictionary used as the value of another Dictionary:

[SerializeField]
private Dictionary<int, Dictionary<string, SkillLevel>> skillsPerTier = new();

That combination can feel surprising: List<Dictionary<...>> is unsupported, while a nested Dictionary value is documented. Do not infer the nesting rules from intuition. Run the concrete type through the analyzer and verify it by saving and reloading the Scene or asset.

Custom key types still need a correct equality design

When a custom class or struct is used as a key, implement Equals and GetHashCode appropriately. Without an override, two class instances with identical serialized fields are still different keys because reference equality is used.

A struct can work with its default equality behavior, but Unity's documentation recommends implementing IEquatable<T> for value-type keys rather than relying on reflection-based default comparison.

using System;

[Serializable]
public struct GridCellKey : IEquatable<GridCellKey>
{
    public int x;
    public int y;

    public bool Equals(GridCellKey other)
        => x == other.x && y == other.y;

    public override bool Equals(object obj)
        => obj is GridCellKey other && Equals(other);

    public override int GetHashCode()
    {
        unchecked
        {
            return (x * 397) ^ y;
        }
    }
}

For class keys in particular, do not modify fields that participate in equality after inserting the object into a Dictionary. If the hash code changes, the key can become effectively unreachable even though the entry still exists internally.

Struct keys are copied on insertion, but the clearest way to change a key is still to remove the old entry and add a new one. Keep mutable state in the value and treat keys as effectively immutable.

If a custom Equals or GetHashCode implementation throws while Unity reconstructs the Dictionary, Unity skips affected entries and logs a warning. Built-in serialization cannot protect a project from an incorrect equality implementation.

Serializable does not always mean Dictionary is the right structure

“Unity can now save it” and “Dictionary best represents the data” are separate questions.

The order itself has meaning

Dialogue sequence, attack priority, tutorial progression, and similar data belong naturally in a List. Dictionary exists for key-based lookup, and its Inspector sorting is display-only.

When order is part of the specification, keep the List as the source of truth and build a lookup Dictionary during initialization when necessary.

[SerializeField]
private List<ItemDefinition> items = new();

private readonly Dictionary<string, ItemDefinition> itemById = new();

Here, itemById is a derived cache. It should not be serialized; rebuild it in Awake or another initialization step. Not every Dictionary needs [SerializeField] simply because the option now exists.

Multiple rows with the same key are legitimate data

An enemy may have several drop candidates. Multiple events may occur at the same timestamp. In those cases, repeated keys are not invalid input—they are the model.

Do not add artificial sequence numbers merely to force uniqueness. Represent the relationship directly with something like Dictionary<EnemyId, List<DropEntry>> or with an ordinary List.

An external format is the source of truth

A server API, CSV file, spreadsheet, or existing save-data schema may own the real contract. The fact that Unity can edit a Dictionary in the Inspector is not a reason to replace that external schema with Unity's internal representation.

Keeping external DTOs separate from Unity authoring data, then converting at a boundary, often makes compatibility much easier to manage.

Humans must edit a very large dataset

The standard Inspector has no search or filtering. For large datasets, input validation, diff review, referential integrity, and bulk updates matter more than whether the final generated object happens to be a serialized Dictionary.

The built-in Dictionary may be a useful storage target. It is not a replacement for the complete data-authoring workflow.

Customizing the Inspector with `DictionaryDisplay`

[DictionaryDisplay] lets you define initial column labels, column width, and layout.

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

[Serializable]
public sealed class ItemDefinition
{
    public string displayName;
    public int price;
    public Sprite icon;
}

[CreateAssetMenu(menuName = "Example/Item Database")]
public sealed class ItemDatabase : ScriptableObject
{
    [SerializeField]
    [DictionaryDisplay(
        keyLabel = "Item ID",
        valueLabel = "Definition",
        keyColumnFraction = 0.35f,
        layout = DictionaryLayout.OneColumnWithValueFoldout)]
    private Dictionary<string, ItemDefinition> items = new();
}

DictionaryLayout provides three layouts:

Value	Display
`TwoColumns`	Shows the key and value side by side
`OneColumnWithValueVisible`	Always shows the value below the key
`OneColumnWithValueFoldout`	Shows the value below the key in a Foldout

The attribute defines the initial presentation. If a user changes the column width or layout in the Inspector, Unity stores that preference per property path and the user setting takes precedence afterward.

Choose Reset to Defaults from the column-header menu to return to the attribute's values.

For a shared configuration applied to the same closed Dictionary type, Unity also provides the assembly-level [DictionaryDisplayForType] attribute.

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

[assembly: DictionaryDisplayForType(
    typeof(Dictionary<string, SkillLevel>),
    keyLabel = "Skill",
    valueLabel = "Level",
    layout = DictionaryLayout.OneColumnWithValueVisible)]

[Serializable]
public struct SkillLevel
{
    public int rank;
    public float bonus;
}

This is useful for nested Dictionaries where no directly annotated field exists. The target must be an exact closed Dictionary type, and the assembly declaring the attribute must itself define the key type, value type, or one of the nested types involved.

The restriction prevents one assembly from globally changing the display of a Dictionary made entirely from types it does not own. Consequently, an assembly cannot apply a global setting to a combination such as Dictionary<string, int> when both types come only from the .NET Base Class Library.

Because this attribute affects an entire assembly, reusable packages should also consider how broad that display policy becomes.

Prefab Overrides are tracked by serialized position, not by key

Unity 6.6 lets an individual Dictionary key or value be overridden in a Prefab instance. The override is not tracked by the logical key, however. It is recorded against the serialized entry position, effectively behaving like a List or array index.

The Inspector's displayed sort order can differ from the stored insertion order, so the row visible on screen does not necessarily correspond to the serialized position used by the override.

If entries are added or removed in the Prefab asset and serialized positions shift, an instance override may end up applying to a different key than the one originally intended. The official manual therefore warns developers to check instance overrides after editing the asset.

Practical precautions include:

Move frequently edited shared tables into ScriptableObject assets.
Check Prefab variants and instances after adding or removing entries in the Prefab asset.
Review YAML diffs and the Overrides list rather than trusting only the visible Inspector order.
Never assume that an override follows an entry merely because its key text remains the same.
Avoid mixing Dictionary migration and unrelated Prefab changes in the same commit.

This is arguably the most important trap in the first version of the feature: the data structure is key-based, but Prefab Override tracking is not.

Use the serialization rules analyzer to catch unsupported shapes

Unity 6.6's analyzer reports several common Dictionary mistakes:

Diagnostic	Meaning
`UAC1009`	A Dictionary is placed directly inside an unsupported collection shape
`UAC1012`	An interface or abstract type is used as the key or value
`UAC1013`	An `IEnumerable` type is used as the key
`UAC1014`	`[SerializeReference]` is applied to a Dictionary
`UAC1015`	A public Dictionary does not have `[SerializeField]`
`UAC1016`	The key or value type is not serializable

This makes it easier to catch the old failure mode where code compiles but the data is silently not persisted as expected.

Monitor these analyzer warnings in CI as well, and avoid suppressing Dictionary-related warnings without a deliberate reason.

Do custom `SerializableDictionary` implementations become unnecessary?

Unity's custom serialization documentation now recommends using the built-in serializer for ordinary Dictionaries and reserving callback-based conversion for collection types Unity still cannot handle directly.

For a new implementation, start with the built-in Dictionary when all of these conditions hold:

The minimum supported version is Unity 6.6 or later.
A plain Dictionary<TKey, TValue> is sufficient.
Both key and value are within the supported range.
The standard Inspector supports the editing workflow.
The Prefab Override limitations are acceptable.
There is no external serialized format that must remain stable.

Custom implementations still have a role when you need:

SortedDictionary, HashSet, or a Dictionary-derived type.
Normalization, compression, encryption, or ID conversion while saving.
A fixed schema shared with tools outside Unity.
Backward compatibility with older Unity versions.
Custom duplicate merging, change notifications, or automatic key generation.
Import from CSV or spreadsheets.
Search, bulk editing, or specialized validation.

When an existing SerializableDictionary owns responsibilities beyond storage, replacing only its type mechanically is unsafe.

It is also too early to claim that the built-in implementation always loads several times faster or always creates smaller files. The largest guaranteed benefit is maintenance: less conversion code, fewer Drawers, fewer compatibility paths, and a smaller test surface.

Measure performance with your actual data when that difference matters.

Does Odin become unnecessary?

If a project uses Odin only to serialize and display ordinary Dictionaries, Unity 6.6 may let you reduce that dependency. Moving plain Dictionaries back to Unity's built-in serializer can reduce the number of serialization paths and package-specific behaviors the project must maintain.

Sirenix's own best-practice guidance also recommends leaving data to Unity's serializer when Unity can handle it and limiting Odin serialization to the places that require it.

Odin's value is much broader than Dictionary support:

A wider range of types than Unity's built-in serializer supports.
Interfaces and polymorphic data structures.
Inspector grouping, buttons, and conditional display.
Validation, custom Drawers, and editor tooling.
Compatibility with existing Odin Serializer data.

When a project is deeply built around Odin attributes and editor workflows, removing the package only because Unity gained Dictionary support may provide little benefit. A practical hybrid is to use Unity's standard serializer for new, simple Dictionaries and keep Odin for complex types and advanced Inspector UI.

The dangerous migration order is to upgrade Unity, change the field types, and remove Odin before reading the old data. Once the old serialization backend is gone, those values may no longer be accessible.

Keep Odin operational while reading the old fields, copy the data into the new standard Dictionaries, save and reload every affected asset, and remove the dependency only after verification.

Migrating existing data safely

Do not assume that replacing a custom type or Odin-managed field with Dictionary<TKey, TValue> automatically migrates existing serialized data. The stored representation and serialization backend can differ, so the project needs an explicit migration step.

[FormerlySerializedAs] preserves an old field name. It is not a universal converter between unrelated types or serialization systems.

Recommended migration sequence

Create a dedicated migration branch and a backup.
Add the new standard Dictionary under a different field name while keeping the old field.
Copy the old data into the new field with Editor-only code.
Detect duplicates, null keys, missing references, and count differences.
Save all affected ScriptableObjects, Prefabs, and Scenes.
Reload scripts, restart the Editor, and test a Player build.
Compare key counts, keys, and values between the old and new formats mechanically.
Remove the old field, custom Drawer, or Odin dependency only after the comparison passes.

During migration, the fields may temporarily look like this:

[SerializeField, HideInInspector]
private LegacyStringIntDictionary legacyPrices = new();

[SerializeField]
private Dictionary<string, int> prices = new();

The following is a conceptual migration example:

#if UNITY_EDITOR
[ContextMenu("Migration/Copy legacy prices")]
private void CopyLegacyPrices()
{
    var migrated = new Dictionary<string, int>();
    bool hasError = false;

    foreach (var pair in legacyPrices)
    {
        if (pair.Key == null)
        {
            Debug.LogError("Null key was found.", this);
            hasError = true;
            continue;
        }

        if (migrated.ContainsKey(pair.Key))
        {
            Debug.LogError($"Duplicate key: {pair.Key}", this);
            hasError = true;
            continue;
        }

        migrated.Add(pair.Key, pair.Value);
    }

    if (hasError)
    {
        Debug.LogError("Migration was aborted.", this);
        return;
    }

    UnityEditor.Undo.RecordObject(this, "Migrate item prices");
    prices = migrated;
    UnityEditor.EditorUtility.SetDirty(this);
}
#endif

Replace LegacyStringIntDictionary and its enumeration API with the types used by your own project.

A Context Menu may be enough for a handful of assets. Large migrations should use a dedicated tool based on APIs such as AssetDatabase, PrefabUtility.LoadPrefabContents, and explicit Scene opening and closing so that no asset is skipped.

Put a large migration tool in an Editor folder or an Editor-only assembly definition so that UnityEditor references cannot leak into a Player assembly. The sample fully qualifies UnityEditor.Undo and UnityEditor.EditorUtility and wraps its body in #if UNITY_EDITOR, but separating the whole tool into an Editor assembly is safer.

Seeing correct values in memory immediately after the copy is not enough. Restart the Editor, reopen the Scenes and Prefabs, and confirm that a Player build reconstructs the same values.

For an Odin migration, keeping Odin installed until the old fields have been read successfully is especially important.

Do not assume `JsonUtility` and network JSON are the same feature

Unity 6.6's Dictionary support is primarily about Unity serialization for Scenes, Prefabs, ScriptableObjects, and similar Unity data.

The JsonUtility Scripting API says that it processes the same supported types as Unity's standard serializer, which can be read as implying Dictionary support. At the same time, the Unity 6.6 JSON Serialization manual available on July 15, 2026 still contains the older statement that Dictionary<> is unsupported.

Because those official pages are inconsistent, this article does not treat JsonUtility Dictionary support as a settled guarantee.

Even when a Beta build appears to work, test the exact target version for:

A complete ToJson and FromJson round trip, including the actual JSON shape produced.
Compatibility with external API schemas and existing save data.
Behavior in an IL2CPP Player build.
Null keys, duplicates, and custom key types.

“Unity can persist this internally” and “this is an appropriate long-term save or network contract” are different claims.

For external formats, choose the tool that fits the contract: Newtonsoft.Json, MessagePack, dedicated DTOs, or another deliberate schema may still be the better choice.

Practical decision table

Scenario	Recommendation
New Unity 6.6+ project with simple ID lookup data	Start with the built-in Dictionary
Active Unity 6.0–6.5 production project	Do not upgrade to a Beta only for Dictionary support
Hundreds or thousands of static game-data records	The Dictionary may be a storage target, but use an external tool or dedicated Editor for authoring
Asset Store package or shared package that supports older Unity versions	Keeping the existing implementation can be reasonable
Project already uses Odin extensively	Move only new, simple Dictionaries first and migrate incrementally
Prefab instances frequently override entries	Understand position-based overrides and consider moving the table to a ScriptableObject

Dictionary serialization does not provide type-safe code generation, referential-integrity checks, localization workflows, server sharing, or live data-update infrastructure. It fills a major gap in Unity serialization; it is not a complete game-data platform.

Adoption checklist

[ ] Record whether the target Unity version is a Beta or a final release.
[ ] Add [SerializeField] to every Dictionary that should be persisted.
[ ] Confirm that the declared type is exactly Dictionary<TKey, TValue>.
[ ] Confirm that both key and value are supported types.
[ ] Implement Equals and GetHashCode for custom keys.
[ ] Remove all duplicate and null keys.
[ ] Remember that Inspector sorting and serialized order are different.
[ ] Recheck variants and instances after changing a Prefab asset.
[ ] Confirm that the lack of Multi-Object Editing and search is acceptable, or provide an alternative.
[ ] Test Scene reload, Domain Reload, and Editor restart.
[ ] Test a Player build on every relevant target platform.
[ ] Compare migrated counts and contents mechanically.
[ ] Round-trip test JsonUtility in the exact target version when you use it.
[ ] Do not remove old fields or Odin before migration verification passes.

Summary

Unity 6.6 allows a standard Dictionary<TKey, TValue> marked with [SerializeField] to be stored in Unity assets and edited through the Inspector. Built-in sorting, duplicate and null warnings, and configurable layouts greatly reduce the need to build a serialization backend and Drawer merely because a project needs key-based lookup data.

Important boundaries remain:

[SerializeField] is required even on public Dictionary fields.
Only the exact Dictionary<TKey, TValue> declared type uses the new backend.
Interfaces and abstract types are generally unsupported.
A Dictionary cannot be placed directly inside a List or array.
Multi-Object Editing, search, and filtering are unavailable in the Beta.
Prefab Overrides follow serialized positions rather than logical keys.
Existing custom and Odin formats require explicit migration.
The Unity 6.6 Beta documentation is inconsistent about JsonUtility support.

So, do custom implementations and Odin become unnecessary?

For the sole purpose of saving a plain Dictionary and editing it in the standard Inspector, they will be unnecessary in many Unity 6.6+ projects.

For unsupported types, advanced Inspector workflows, older Unity versions, custom external formats, or compatibility with existing data, they remain necessary.

In new projects, the built-in Dictionary should become the first option. In existing projects, do not delete a working serialization system merely because the Editor gained a built-in alternative. Inventory the old system's responsibilities, migrate explicitly, reload everything, and verify the result before reducing dependencies.

References

Unity's Official MCP with Codex: Safely Evaluating Console Fixes, Scene Edits, and Prefab Creation

GameDevToolLab — Tue, 21 Jul 2026 06:47:09 +0000

Introduction

Having an AI write C# and then reviewing the Git diff before returning to Unity is no longer unusual.

Unity work, however, rarely ends with a source-code change. A task may also require editing the Hierarchy, configuring Components, saving a Prefab, switching or saving a Scene, waiting for compilation, and checking the Console after a Domain Reload. An AI that can only inspect repository files cannot directly observe all of that Editor state.

Unity's official Unity MCP Server is intended to close that gap. It allows an external MCP client to connect to the Unity Editor and work with capabilities related to Scenes, GameObjects, Assets, scripts, and the Console.

This article explains how to start using the official Unity MCP Server from Codex without immediately giving the model broad write access. It focuses on connection setup, permission boundaries, failure recovery, and a repeatable evaluation method built around three tasks:

Read the Unity Console and apply a minimal compile-error fix.
Create, edit, and save a disposable sandbox Scene.
Create a Prefab with a precisely defined structure.

The order is deliberate. Start with a mostly read-oriented Console workflow, continue with a disposable Scene, and only then create a persistent Prefab Asset. Each stage should proceed only after the previous stage proves that the target Editor, exposed tools, and verification loop are under control.

The goal is not to watch one successful demo and conclude that the integration is production-ready. A useful evaluation must distinguish first-attempt success, automatic recovery, human intervention, unintended changes, timeouts, and Editor hangs.

Important: This article does not contain measured success rates or elapsed-time results. It is an evaluation and safety-design guide based on official documentation checked on July 21, 2026. Paths, UI labels, and described behavior come from documentation rather than the author's own execution results. Decide whether the integration is suitable for production only after measuring it with fixed versions and a representative project.

What “Unity's Official MCP” Means Here

This article covers the Unity MCP Server included in the com.unity.ai.assistant package. It does not cover community MCP servers with similar names.

As of July 21, 2026, Unity's documentation describes Assistant 2.14.0-pre.1 and requires Unity 6 (6000.0) or later. Unity AI is in Open Beta, and the setup requires a project connected to Unity Cloud plus an active Trial or Subscription. Unity's official introductory blog states that using the MCP Server itself does not consume Unity AI credits.

Because this is Beta and pre-release software, pin the package version used for every evaluation.

The official Unity MCP overview describes this architecture:

Codex (MCP client)
  │ MCP over stdio
Unity Relay (~/.unity/relay/)
  │ local IPC
  │ Windows: named pipe
  │ macOS/Linux: Unix socket
Unity Editor (MCP Bridge)
  ├─ built-in tools
  └─ custom tools

Codex starts the Relay process. The Relay then connects to the MCP Bridge running inside the Unity Editor.

In Assistant 2.14.0-pre.1, the following menu entries point in opposite directions:

AI > Assistant MCP Extensions: Unity Assistant consumes external MCP servers.
AI > Unity MCP Server: Unity exposes Unity capabilities to an external client such as Codex.

That distinction is easy to miss.

The labels also vary between package versions. For example, Assistant 2.7.0-pre.3 documentation used names such as AI > MCP Client and AI > Unity MCP. When following older screenshots or blog posts, identify the direction of the connection instead of relying on an exact menu string.

There is another naming distinction worth preserving:

Unity_ManageScene and Unity_ReadConsole are examples of tool names exposed to the client.
get_components is described in Unity's troubleshooting documentation as an operation name.

Do not assume an operation belongs to a particular tool without checking the schema discovered by Codex in the actual environment.

Freeze the Evaluation Environment

MCP behavior can change with the Unity version, Assistant package, Codex version, operating system, and project state. A success rate without that context is not useful.

Record at least the following:

Item	Example
OS	Windows 11 24H2
Unity	`6000.x.xf1`
Assistant package	`2.14.0-pre.1`
Codex	Exact CLI or IDE-extension version
Model	Exact model selected for the run
Project	New Unity 6 URP project
Git state	Reset to the same commit before every attempt
Open Unity Editors	One, or explicitly identify the target
Console state	Cleared before each run
MCP debug logs	Enabled

Use a small evaluation repository or a disposable worktree, not a copy of an active production project.

Every attempt should begin from the same commit, Scene, Console state, and permission configuration. Keep the attempt number, prompt, tool calls, debug logs, and Git diff linked together.

Do not mix ordinary runs that reuse Library with runs that intentionally clear caches. Those are different conditions and should be reported separately.

Unity-Side Setup

The basic requirements are Unity 6 or later and the com.unity.ai.assistant package.

After opening the Editor:

Open Edit > Project Settings > AI > Unity MCP Server.
Confirm that Unity Bridge reports Running.
Enable Show Debug Logs.
Check Validation Level.
Enable only the tools required for the current task.

The official setup documentation for Assistant 2.14.0-pre.1 states that the Bridge normally starts when the Editor loads and that the Relay executable is placed under the user's .unity/relay directory. Treat that as documented behavior, then verify the Running state and actual Relay file in the target environment.

If the Bridge remains Stopped, inspect:

Unity Console compile errors
Package installation state
Whether the Relay binary exists
MCP debug logs

In Assistant 2.14.0-pre.1, Validation Level controls the validation strength of Unity_ManageScript and offers basic, standard, comprehensive, and strict. For code-editing evaluation, starting with strict is reasonable, while recording any speed difference.

This setting does not represent one universal validation level for every Scene and Prefab operation. Confirm its exact scope in the configuration reference for the package version being tested.

Register the Unity MCP Server in Codex

According to the Codex MCP documentation, Codex can register a stdio MCP server in ~/.codex/config.toml or in .codex/config.toml inside a trusted project.

For the first connection check, expose only Unity_ReadConsole:

[mcp_servers.unity]
command = "/absolute/path/to/unity-relay"
args = [
  "--mcp",
  "--project-path",
  "/absolute/path/to/UnityMcpLab",
]
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"
enabled_tools = ["Unity_ReadConsole"]

The example above uses operating-system-neutral placeholders. Replace both paths with absolute paths from the evaluation machine.

On Windows, TOML literal strings make paths easier to read because backslashes do not need to be doubled:

command = 'C:\Users\name\.unity\relay\relay_win.exe'
args = ["--mcp", "--project-path", 'C:\work\UnityMcpLab']

The Assistant 2.14.0-pre.1 documentation provides the following Relay path examples. They are documentation examples, not observations from this article's author. Confirm them with Locate Server and the actual filesystem.

OS	Documented example
macOS Apple Silicon	`~/.unity/relay/relay_mac_arm64.app/Contents/MacOS/relay_mac_arm64`
macOS Intel	`~/.unity/relay/relay_mac_x64.app/Contents/MacOS/relay_mac_x64`
Windows	`%USERPROFILE%\.unity\relay\relay_win.exe`
Linux	`~/.unity/relay/relay_linux`

Some clients do not expand ~, so use an absolute path for command.

The server can also be registered with the CLI:

codex mcp add unity -- \
  /absolute/path/to/unity-relay \
  --mcp \
  --project-path /absolute/path/to/UnityMcpLab

Important: This CLI command registers the MCP server only. It does not establish the read-only tool allowlist shown above. After running it, open the resulting config.toml—normally ~/.codex/config.toml—and explicitly add or verify enabled_tools = ["Unity_ReadConsole"] and default_tools_approval_mode = "prompt" before starting the evaluation.

After registration, use codex mcp list and /mcp in the interactive session to inspect the connection and the tools actually exposed to Codex.

A useful permission progression is:

Stage	Tools exposed to Codex	Purpose
Connection check	`Unity_ReadConsole` only	Verify target Editor, approval, Relay, and Console access
Script fix	Console read plus the script-editing tool found in the environment	Apply one minimal code change
Scene edit	Scene and GameObject tools found in the environment	Edit only a sandbox Scene
Prefab creation	GameObject/Component tools plus Asset/Prefab saving tools found in the environment	Save one Prefab under an approved folder

The labels “script-editing tool,” “Scene/GameObject tool,” and “Asset/Prefab-saving tool” are conceptual descriptions. They are not guaranteed official tool names. Use the Unity Tools list and the schemas discovered through /mcp, then copy only the exact names shown in that environment into enabled_tools.

Do not guess a Prefab-saving tool name from an article. If the built-in tools cannot satisfy the requirement, record the task as unsupported with built-ins and evaluate a Custom Tool separately.

Always Select the Target When Multiple Editors Are Open

According to the Assistant 2.14.0-pre.1 setup guide, the Relay may connect to the first Unity Editor it discovers when no target is specified.

That is dangerous for developers who keep multiple projects, samples, or test Editors open at the same time.

Select the target with one of these approaches:

--project-path <path> or UNITY_PROJECT_PATH
--instance-id <pid> or UNITY_INSTANCE_ID

Prefer --project-path for a persistent configuration. A process ID changes whenever the Editor restarts, so it is more useful for temporary diagnosis than long-lived setup.

“Edit the test Scene” is not a safe instruction if Codex might be connected to another client's project.

Connected Clients is the UI label used in the documentation for the target package version. During evaluation, capture both the Codex-side connection state and the Unity-side client display so that the selected project can be verified later.

Approve the First Connection in Unity

The official flow requires Unity-side approval for the first direct connection from an external MCP client.

The Assistant 2.14.0-pre.1 package documentation says that clients appear under Pending Connections, where Allow approves the connection and Revoke Access rejects it. An approved client can reconnect automatically in later sessions.

Unity's May 11, 2026 blog post uses Accept for the same approval action. Other versions may also use different page or button labels.

Do not search only for one exact word. Find the approval action for the client shown under the target version's pending-connections UI, and record the actual label used by the installed version.

This approval boundary matters, but it is not fine-grained authorization. It means “this Codex client may connect.” It does not by itself mean “Prefab creation is allowed but Scene deletion is forbidden.” Operation-level limits need additional layers.

Classify Results into Four Outcomes

Do not use the model's “Done” message as the success criterion. Judge the result from Unity's actual state.

Outcome	Definition
First-attempt success	The initial instruction satisfies every condition without an extra save or verification instruction
Automatic recovery	The model re-observes the failure and completes the task within at most two additional tool calls, without human intervention
Human-assisted success	A person selects, deletes, restarts the Bridge, edits directly, or otherwise intervenes before completion
Failure	Retry limit exceeded, unintended change occurred, Editor stopped, or the run was rolled back with Git

Do not merge human-assisted success into automatic success. A final state that a person repaired does not erase the failed automation attempt.

Metrics to Record

Run each task ten times from the same initial state. Allow no more than two recovery attempts. Stop a run immediately after an unintended change, target mismatch, or Editor hang.

Record:

First-attempt success
Automatic recovery
Human intervention
Elapsed time
Number of tool calls
Timeouts
Out-of-scope diffs
Editor hangs or crashes
Number of changed files
Tool configuration: built-in or Custom Tool
Exact tool names and important arguments

The following formulas keep the categories separate:

First-attempt success rate = first-attempt successes / all attempts
Recovery-inclusive success rate =
    (first-attempt successes + automatic recoveries) / all attempts
Human-intervention rate = human-assisted attempts / all attempts
Side-effect rate = attempts with unintended changes / all attempts

Ten runs are not enough to estimate universal model performance. They are a small, repeatable unit for discovering serious failures in one environment and comparing package or configuration changes.

Do not combine runs that use different allowlists, cache conditions, or built-in/Custom Tool configurations into the same denominator.

Evaluation Task 1: Read the Console and Fix a Compile Error

Start with a read-only connection check

Before allowing any code edit, keep:

enabled_tools = ["Unity_ReadConsole"]

Ask Codex to summarize the number of Errors and Warnings and show the first few entries. Do not count this connection check among the ten code-fix attempts.

Proceed only after confirming all of the following:

The correct Editor is connected.
Unity has approved the client.
Codex discovers only Unity_ReadConsole for this stage.
Console reading works.

Then add the exact script-editing tool discovered in the environment to the allowlist.

Test input

Create Assets/MCPTest/Scripts/Health.cs with one missing semicolon:

using UnityEngine;

public sealed class Health : MonoBehaviour
{
    [SerializeField] private int maxHp = 100;
    public int CurrentHp { get; private set; }

    private void Awake()
    {
        CurrentHp = maxHp
    }
}

The challenge is not C# syntax. It is whether the workflow can:

Read the Unity Console.
Identify the correct source location.
Apply the smallest possible change.
Wait for Unity to import and compile.
Read the Console again.
Confirm that compile Errors are zero.
Leave unrelated Warnings untouched.

Prompt

Read the Unity Console and apply only the minimum change required to fix the compile error.

Constraints:
- Do not change the API design, names, fields, or access modifiers.
- Do not fix Warnings unrelated to the Error.
- Wait for Unity compilation to finish.
- Read the Console again and verify that compile Errors are zero.
- Report the changed file and line.

When the Bridge cannot start

Unity's MCP troubleshooting documentation notes that compile errors can prevent the MCP Bridge from starting. The evaluation therefore needs two explicit paths:

Bridge state	Procedure
Running	`Unity_ReadConsole` → minimal edit → wait for compile → read Console again
Stopped	Use Codex's ordinary repository editing to fix only the blocking error → let Unity compile → start the Bridge → read Console

It is acceptable to divide responsibilities: normal file editing for the source change, Unity MCP for observing the Editor result.

Success requires:

Zero compile Errors after recompilation
No diff beyond the expected semicolon
A second Console read after compilation
The correct recovery path for the Bridge state

Use two difficulty stages

The missing semicolon is Stage A: it verifies the connection and feedback loop.

Stage B should use a slightly more semantic but still deterministic error. For example, assign GetComponent<Rigidbody2D>() to a Rigidbody field and define the only accepted fix as GetComponent<Rigidbody>().

Predefine the expected diff and acceptance conditions. Do not use an ambiguous bug when evaluating the reliability of the Editor loop.

Saving the file is not completion. Observe Asset Import, compilation, and the post-Domain-Reload Console state.

Evaluation Task 2: Edit a Sandbox Scene

Required Scene

Create and save:

Assets/MCPTest/Scenes/MCP_Sandbox.unity

with this Hierarchy:

MCP_Sandbox (Scene)
├─ Environment
│  ├─ Floor
│  └─ Directional Light
├─ Main Camera
└─ SpawnPoint

Acceptance conditions:

The Scene is saved at the exact path.
Environment, Main Camera, and SpawnPoint are at the Scene root.
Environment has Position and Rotation set to zero and Scale set to one.
Floor is a child of Environment and has Cube rendering Components plus a BoxCollider.
Floor.localPosition = (0, -0.5, 0).
Floor.localScale = (10, 1, 10).
Directional Light has a Light Component with the Directional type.
SpawnPoint has only a Transform and position = (0, 1, -4).
Main Camera has a Camera Component and the MainCamera tag.
The Scene is saved and no other Scene changes.
The Console has no Errors.

Prompt

Use Unity MCP to create Assets/MCPTest/Scenes/MCP_Sandbox.unity with the following state.

Hierarchy:
- Environment
  - Floor
  - Directional Light
- Main Camera
- SpawnPoint

Settings:
- Environment Position/Rotation = 0 and Scale = 1.
- Create Floor as a Cube with localPosition = (0, -0.5, 0)
  and localScale = (10, 1, 10).
- Directional Light must contain a Directional Light component.
- SpawnPoint must contain only a Transform and use position = (0, 1, -4).
- Main Camera must contain a Camera and use Tag = MainCamera.

Constraints:
- Do not edit an existing Scene.
- If a Scene already exists at the target path, stop without overwriting it.
- UI and Canvas objects are outside this evaluation task.

After saving, re-read the active Scene path, Hierarchy, Components, Transforms,
Light Type, Camera Tag, save state, and Console Errors.

What to inspect

A Scene may look correct while still being dirty and unsaved. After saving, re-read the Scene path and Hierarchy. In a multi-Scene setup, verify the Active Scene and the owning Scene of every created GameObject.

World and local coordinates must remain explicit. Parenting can change the effective result, so the prompt and the acceptance test should both distinguish position from localPosition.

Exclude UI Hierarchies for This Version

Unity's troubleshooting documentation for Assistant 2.14.0-pre.1 warns that running the documented get_components operation on GameObjects in a Canvas or UI hierarchy may stop or crash the Editor. The listed affected Components include:

Canvas
CanvasScaler
GraphicRaycaster
RectTransform

get_components is the operation name used in the documentation. Confirm which discovered tool and input schema produce that operation in the installed version.

For this evaluation:

Do not retrieve Components from UI hierarchies.
Do not broadly enumerate the entire Scene.
Limit queries to a known root.
Save every tool call and its arguments.
If the Editor hangs, identify the last call and stop the run.

Add UI only after the relevant Issue Tracker entry and release notes show that the problem is fixed for the pinned version.

Evaluation Task 3: Create a Prefab

Expand the allowlist first

The read-only configuration:

enabled_tools = ["Unity_ReadConsole"]

cannot create a Prefab.

Before the task, inspect the actual environment and add only the tools required for:

GameObject creation
Component configuration
Asset or Prefab saving

If no built-in saving tool can satisfy the task, record “unsupported with built-in tools” and move the Custom Tool attempt into a separate result group.

Required Prefab

Create:

Assets/MCPTest/Prefabs/Crate.prefab

Crate
├─ Visual
└─ Handle

Acceptance conditions:

Root name is Crate.
The root contains only Transform, BoxCollider, and Rigidbody.
Rigidbody.mass = 10.
Visual contains only Transform, MeshFilter, and MeshRenderer.
Visual does not retain a BoxCollider added by CreatePrimitive.
Handle contains only a Transform.
Handle.localPosition = (0, 0.6, 0).
The Prefab is saved at the exact path.
No temporary GameObject remains in the Scene.
Reopening the saved Prefab preserves the structure and values.
The Console has no Errors.

Prompt

Use Unity MCP to create Assets/MCPTest/Prefabs/Crate.prefab.

Requirements:
- Root name: Crate
- Add BoxCollider and Rigidbody to the root.
- Set Rigidbody.mass to 10.
- Child Visual must contain only the Cube MeshFilter and MeshRenderer.
- If CreatePrimitive added a BoxCollider to Visual, remove it before saving.
- Child Handle must contain only a Transform.
- Set Handle.localPosition to (0, 0.6, 0).
- Do not leave a temporary GameObject in the Scene.
- If a Prefab already exists at the target path, stop without overwriting it.

After saving, re-read the Prefab and report the Hierarchy, Components, mass,
localPosition, save path, and Console Errors. Do not classify the task as
successful if any unspecified Component remains.

The evaluated workflow includes creation, configuration, save, cleanup, and re-open verification.

Treat all of the following as failures:

A temporary Scene object remains.
A required value was never set.
World and local coordinates were confused.
An existing Asset was overwritten.
An extra Collider remains on Visual.
The saved Prefab was never reopened and checked.

After a failed attempt, observe the current Asset and Scene state before changing anything. Repair one condition at a time.

For repeated production use, consider replacing a series of generic calls with a narrow Custom Tool such as CreateOrValidatePrefab that provides a dryRun mode, path allowlist, and explicit overwrite policy.

Evaluation Record Template

Copy this table for Console, Scene, and Prefab tasks and fill ten rows for each configuration.

Run	Tool setup	Tools used	First	Recovery	Human	Time	Calls	Timeout	Out-of-scope diff	Notes
1
2
3
4
5
6
7
8
9
10

Summarize the results separately:

Task	Tool setup	First-attempt success	Recovery-inclusive success	Human-intervention rate	Side-effect rate	Median time	Editor stops
Console fix	Built-in / ordinary editing	—	—	—	—	—	—
Scene edit	Built-in only	—	—	—	—	—	—
Prefab creation	Built-in only	—	—	—	—	—	—
Prefab creation	With Custom Tool	—	—	—	—	—	—

Do not report only the average. Record median time, maximum time, timeouts, and Editor stops separately. Keep built-in and Custom Tool runs in different result groups.

Preserve evidence

For an internal adoption decision or a public report, save evidence for both successful and failed runs:

Unity MCP Server settings
Codex tool list
Prefab Hierarchy and Inspector
Console before and after the code fix
Scene Hierarchy after editing
Debug logs or tool-call details for failures

Associate every screenshot and log with a run number. Before publishing, mask user names, absolute paths, project names, credentials, and other confidential data.

Suggested pilot thresholds

The following are proposed internal thresholds, not Unity or OpenAI requirements:

At least 80% first-attempt success
At least 95% success including automatic recovery
Zero unintended changes
Zero Editor hangs or crashes
No more than one human-assisted run per ten attempts
Faster median completion than the same task performed manually

For Scene and Prefab work, side effects matter more than speed. Nine fast successes do not compensate for one run that damages another Scene.

For Console fixes, give the highest weight to a minimal diff and post-compilation verification.

Define Recovery as a State Machine

A free-form “try again” prompt makes the recovery process different on every run. Fix the workflow to a small state machine:

Observe → Plan → Act one step → Wait → Verify
   ↑                                  │
   └──────── known temporary failure ─┘
                                      ├─ success: Stop
                                      └─ destructive risk: Stop and roll back

State	Action
Observe	Read the Active Scene, target Asset, Hierarchy, Console, Bridge state, and Git diff
Plan	Choose one next operation and define the state that should follow it
Act one step	Limit the change to one GameObject, one Component, or one-file diff
Wait	Wait for import, compilation, Domain Reload, or save completion
Verify	Judge the acceptance conditions from newly retrieved Unity state and Git diff
Stop / roll back	Stop immediately after target mismatch, unintended change, Editor stop, or overwrite risk

After a timeout, return to Observe. Do not immediately send the same write operation again.

Common stop conditions:

The connected project or target Scene is not the expected one.
An existing Asset may be overwritten.
A non-target Scene, Asset, or script changed.
The Unity Editor stopped or crashed and the final call cannot be identified.
State cannot be re-read after a timeout, so execution status is unknown.
An unapproved tool or Custom Tool was called.

Task-specific sections should add only their own acceptance conditions instead of redefining this common list.

Use Four Permission Layers

Unity's connection approval alone is not sufficient. Combine four layers.

Layer 1: Git and the work environment

Use a dedicated branch or worktree, a clean baseline commit, and one task per commit. Begin with a sandbox Scene rather than a production Scene. Inspect the result in Unity as well as in serialized YAML diffs.

Layer 2: Codex sandbox and approvals

The Codex sandbox controls local command access. Approval policy controls when human confirmation is required.

Unity MCP tool calls are a separate path from shell editing, so the sandbox is not the only boundary. Do not begin with sandbox_mode = "danger-full-access" or disabled approval. For shell operations, start with --sandbox workspace-write --ask-for-approval on-request or the equivalent configuration, while keeping MCP tool approval in prompt mode.

Layer 3: Codex MCP tool restrictions

Use enabled_tools, disabled_tools, and approval modes to expose only the tools needed for the current task.

For the connection check, expose only Unity_ReadConsole. For write operations, add only exact tool names verified through the installed environment.

Layer 4: Unity MCP Server and narrow Custom Tools

Disable unnecessary tools on the Unity side as well.

For repeated workflows, prefer a narrow Custom Tool that enforces:

Approved folders
Approved Scenes
Overwrite policy
Maximum object count
Dry-run support
Undo
Validation

Examples include CreateEnemySpawnPoint or ValidatePrefabReferences rather than a generic “modify anything” endpoint.

Local IPC Does Not Mean All Data Stays Local

The Relay-to-Editor connection uses local IPC, but Codex reasoning may still involve remote services.

Before using the integration with production data, review:

OpenAI plan and workspace data controls
Unity AI terms and data settings
Client confidentiality requirements
Whether Console logs may contain credentials or personal data
Storage location and retention of MCP debug logs and Codex history

“Communication with the Editor is local” is not enough to conclude that confidential project data can be sent through the workflow.

Be Careful with Batch Mode Auto-Approval

Auto-approve in Batch Mode allows an MCP client running in Batch Mode to connect without the normal interactive approval step.

That can be useful in CI, but it removes an important boundary. Do not enable it at the beginning of an evaluation.

A safe progression is:

Human-supervised local evaluation
Read-only automation
Narrow write operations in an isolated runner

If Batch Mode auto-approval is eventually enabled, require:

Disposable runners
A fixed repository and fixed write locations
A strict tool allowlist
Automated diff validation
No direct writes to the main branch

Custom Tools Are the Path to Production Use

Built-in tools are useful for small experiments. Repeated production workflows are often safer when they are consolidated into narrow Custom Tools registered through Unity's official extension mechanism.

For Prefab creation, instead of allowing the model to compose many generic operations, expose something like:

CreateValidatedPrefab(sourceDefinition, outputPath, overwritePolicy, dryRun)

Its implementation can:

Validate the output path and overwrite policy.
Create and configure objects inside one Undo group.
Save the Prefab.
Reopen the saved Asset.
Run a project-specific validator.
Destroy temporary objects.
Return a structured result.

The important shift is to treat Unity's official MCP not as “natural language can do anything in the Editor,” but as a standard interface through which an AI can reach carefully designed internal Editor tools.

That makes the failure surface and ownership boundary much smaller.

Write Prompts as Input Specifications

The recovery state machine defines what happens after a failure. The prompt defines what is allowed to change.

A useful prompt specifies five things:

Item	What to include
Target	Project, Scene, Asset path, and root GameObject
Completion	Save, reopen, values, and Console verification
Prohibitions	No overwrite, no other Scene, no UI query, and similar limits
Change size	One creation, setting, or code change at a time
Verification	Newly retrieved Unity state, not model self-report

Do not ask only, “Did it work?”

Ask for concrete evidence:

Reopen the saved Prefab and return its Hierarchy, Components, values, save path, and Console state.

The purpose is to turn an ambiguous natural-language request into executable acceptance criteria.

Treat Timeouts as Unknown State

Unity tool calls can be delayed while the Editor imports Assets, builds, compiles scripts, or reloads the domain.

Record these as separate events:

Relay startup
Bridge connection
Tool discovery
Import or compilation
Domain Reload
Tool-internal hang

Do not hide the cause by increasing every timeout indiscriminately.

A timed-out write call does not prove that nothing happened. The operation may have completed while the response was lost.

Before retrying, re-read:

The target Asset
The Hierarchy
The Git diff
The Console

Repeated Custom Tools should ideally be idempotent through existing-state checks or a request ID.

Conclusion

Unity's official MCP Server provides an official connection surface from Codex to Unity Editor state, including Scenes, GameObjects, Assets, scripts, and the Console.

That access is useful, but it is not automatically safe. A production-minded setup must control the target Editor, exposed tools, save behavior, re-read verification, and timeout recovery.

Before adoption, repeat the Console, sandbox Scene, and Prefab tasks from the same initial state. Measure first-attempt success, automatic recovery, human intervention, unintended changes, and Editor stops separately.

Begin with read-only Console observation. Expand access only to a disposable Scene, then to Prefab creation. Treat any out-of-scope modification as more important than raw speed.

Only workflows that meet the team's threshold should become candidates for routine use. Everything else can remain observation-only.

The most practical mental model is not “let natural language control the whole Editor.” It is:

Use allowlists and narrow Custom Tools to make Unity MCP a controlled entry point into well-defined Editor automation.

References

The following sources were checked on July 21, 2026. Paths, labels, Validation Level values, and known issues in this article are based on these primary sources. Unity AI and the Assistant package are Beta/pre-release software, so recheck the exact version before evaluation.

Unity Data Formats in Practice: When to Use YAML, JSON, MessagePack, or JSON + gzip

GameDevToolLab — Fri, 17 Jul 2026 03:02:22 +0000

Introduction

A Unity project can start with one small JSON file and remain perfectly healthy for a long time.

As the project grows, however, the data requirements usually split in different directions:

Some files must be easy for humans to edit.
Some must produce readable Git diffs.
Some must load quickly on a mobile device.
Some must be shared with a server or an operations tool.
Some must remain compatible with older clients or save files.
Some must work correctly under IL2CPP and AOT restrictions.

Trying to satisfy all of those requirements with one format eventually creates conflicts.

This article compares YAML, JSON, and MessagePack from a production Unity perspective. It focuses on user settings, save data, runtime distribution, server communication, and static game data—often called master data in Japanese game development.

The central idea is simple:

Use human-friendly formats at authoring time, machine-friendly formats at runtime, and choose network formats by balancing observability against efficiency.

The question is not which format is universally best. The useful question is who reads the data, who edits it, when it is validated, and where it is consumed.

The Practical Answer First

The following table is a useful starting point for many Unity projects.

Use case	Good default	Why
Hand-written configuration	YAML	Comments, hierarchy, and reviewable diffs
Simple external integration or Web API	JSON	Broad compatibility and excellent tooling
Small Unity user settings	PlayerPrefs or JSON	Minimal implementation cost and easy inspection
Save data	JSON or MessagePack	Choose between observability and size/parse cost
Authoring static game data	Spreadsheet, Excel, YAML, or CSV	Match the format to the people editing it
Runtime static game data	MessagePack, generated code, or a project-specific binary	Favor validated data and efficient loading
Initial server API implementation	JSON	Easier debugging, logging, and integration
High-volume or high-frequency APIs	JSON + gzip or MessagePack	Reduce network size, parse cost, or both
Operations tools, admin panels, and logs	JSON	Easy for both people and tools to consume

The common mistake is to make one global rule:

“YAML is readable, so everything should be YAML.”
“JSON is standard, so everything should be JSON.”
“MessagePack is fast, so everything should be MessagePack.”

A more useful mental model is:

YAML leans toward human authoring.
JSON leans toward interoperability and investigation.
MessagePack leans toward runtime efficiency.

What to Evaluate Before Choosing a Format

Will people read or edit it directly?

For hand-edited data, readability and diff quality matter more than raw parsing speed.

YAML supports comments and can represent nested structures without as much punctuation as JSON. JSON is still reasonably readable, but standard JSON does not allow comments or trailing commas. MessagePack is not intended for direct editing at all.

How much data is there, and how often is it loaded?

For a few small settings, the difference between YAML and JSON is rarely important.

At tens of thousands of rows or millions of cells, the costs become visible:

Parsing
String allocation
Numeric conversion
Garbage collection
File size
Object construction after deserialization

The acceptable threshold depends on the target device, compression, load frequency, and the shape of the resulting object graph. Measure with representative data instead of relying on format reputation.

For large runtime datasets, possible options include:

MessagePack
A project-specific binary format
Generated C# data or loaders
SQLite
FlatBuffers
MemoryPack
Partitioned ScriptableObject assets loaded through Addressables

MessagePack is a strong option, but it is not the only runtime-oriented format.

Is it network data or a local file?

Network data passes through more systems than a local file:

The server
The client
Logging and monitoring
Debug proxies
Customer-support tooling
Admin panels
Automated tests

Binary formats can reduce payload and parsing costs, but they also make incident investigation harder.

It also helps to separate serialization format from compression.

For example:

JSON can be sent with gzip to reduce transfer size.
MessagePack can reduce representation size and parsing overhead.
MessagePack can also be compressed, although that is a separate decision.

A practical distinction is:

Use JSON when compatibility and observability dominate.
Use JSON + gzip when bandwidth is the main issue and JSON parsing is still acceptable.
Consider MessagePack when parsing time, allocation, or very frequent traffic is also a bottleneck.

How must schema changes be handled?

Games regularly add fields, rename data, change types, and support older clients or save files.

The important part is not only the format. It is the versioning policy.

JSON includes field names, so readers can often ignore unknown fields. MessagePack can behave similarly with map-style string keys, though this reduces some of its size and speed advantages. Array-style integer keys can be more compact, but key-number management becomes part of the compatibility contract.

YAML is often best treated as an authoring format. Validate and normalize it during conversion, then give the generated runtime data an explicit version.

YAML: Strong for Human-Edited Configuration

YAML is designed to be comfortable for people to read and write.

Typical uses include:

Build configuration
CI configuration
Tool settings
Environment settings
Small data definitions
Conversion rules

A stage definition might look like this:

stages:
  - id: stage_001
    name: Beginning Forest
    enemyLevel: 3
    bgm: forest_day
    notes: "The first stage after the tutorial"

  - id: stage_002
    name: Old Mine
    enemyLevel: 6
    bgm: mine
    notes: "Dark area with limited-visibility mechanics"

One of YAML's most practical advantages is comments:

# Early-game stage. Keep enemy attack values low.
- id: stage_001
  enemyLevel: 3
  # New players tend to struggle here, so give slightly more gold.
  rewardGold: 120

In game development, comments such as “why this value exists” or “this is a temporary tuning override” can be more valuable than the syntax itself.

Where YAML fits in a Unity project

YAML is useful for:

Configuration edited directly by engineers
Data that needs comments
Settings reviewed in Git
Environment-specific configuration
Build and CI tooling
Small or medium hand-written datasets
Source data converted before the player build

Examples include:

Addressables helper configuration
Custom build-pipeline settings
Data-conversion rules
Localization conversion rules
Static-data generation settings
Development cheat-menu definitions
Server endpoint definitions by environment

This does not mean manually editing Unity's serialized .prefab, .unity, or .asset text files. The YAML discussed here is project-owned configuration or source data.

Unity does not provide a general-purpose YAML parser comparable to JsonUtility. A practical YAML workflow usually depends on one of the following:

A library such as YamlDotNet
A project-specific conversion tool
A CI conversion step
An external data pipeline

Reading YAML directly at runtime is possible, but it introduces parsing cost, allocations, package size, error handling, and IL2CPP/AOT considerations. In many projects, a safer workflow is to convert YAML into JSON, MessagePack, generated code, or another validated runtime format during the build or CI process.

YAML is also not automatically the best authoring format for every static dataset. When designers need to edit thousands of rows as a table, a spreadsheet, Excel workbook, or dedicated admin UI is usually more practical.

YAML pitfalls

YAML is convenient, but its flexibility can produce surprising behavior.

Consider these values:

value1: 001
value2: yes
value3: 2026-07-08

Whether they are interpreted as strings, numbers, booleans, or dates can depend on the YAML version and parser behavior.

For example, tools that retain YAML 1.1 behavior may interpret yes as a boolean. YAML 1.2 narrowed implicit typing, but production projects still need to verify the behavior of the selected parser and surrounding tools.

Game data often uses IDs and code-like values that must remain strings:

characterId: "001"
itemId: "yes"
releaseDate: "2026-07-08"

A safe project rule is to quote IDs, date-like values, and codes with leading zeroes.

YAML also supports anchors and aliases:

defaultEnemy: &defaultEnemy
  hp: 100
  attack: 20
  defense: 5

enemies:
  - <<: *defaultEnemy
    id: slime
    hp: 80
  - <<: *defaultEnemy
    id: goblin
    attack: 25

This can remove duplication, but heavy use makes the final resolved value harder to see during review.

The << merge key in this example comes from a YAML 1.1-era extension and is not part of the YAML 1.2 core schema. Support and configuration vary by parser, so confirm the exact behavior before relying on it.

For production data, it is often wise to restrict the YAML features allowed by the project and emit a normalized representation during conversion.

JSON: The Default for Interoperability and Investigation

JSON is a practical general-purpose data-exchange default.

It is readable text, supported by almost every server language, and deeply integrated into HTTP tooling, browsers, command-line utilities, admin panels, logs, and monitoring systems.

Why JSON remains so useful

JSON is not the most compact or fastest format. Its strength is the surrounding ecosystem.

When an API fails, a JSON request or response can be inspected directly in:

Server logs
Browser developer tools
curl
Postman
jq
Monitoring dashboards
Automated scripts

That makes JSON a very practical starting point for game-server APIs.

JSON limitations

JSON has several weaknesses:

Standard JSON has no comments.
Binary data must be encoded separately, often with Base64.
Payloads can become large because field names repeat.
Parsing requires text processing.
Numeric interoperability needs care.

The numeric issue is especially important for 64-bit IDs. Unity and C# can represent a value as long, while JavaScript or another consumer may lose integer precision. Large account IDs, transaction IDs, or order numbers are often safer as strings across system boundaries.

In Unity, loading large JSON documents at runtime also deserves measurement. Parsing several megabytes or tens of megabytes at startup and materializing the entire object graph can affect startup time, peak memory, and garbage collection.

That does not make JSON a bad format. A few kilobytes of settings, a small save file, or a low-frequency API response may be completely fine. Problems appear when the data size and access pattern outgrow the original design.

Unity's `JsonUtility`

Unity includes JsonUtility.

It is lightweight for simple types that follow Unity's serialization rules. In suitable cases, it can allocate less than a general-purpose JSON library.

However, JsonUtility is not a fully general JSON document API. It works with structured JSON that maps to known C# types and inherits important Unity-serialization limitations.

Notable constraints include:

Dictionary<TKey, TValue> is not supported.
Top-level arrays and primitive values are awkward and usually need wrapper classes.
Arbitrary JSON trees are not its intended use case.
Fine-grained naming and polymorphism support are limited.

It works well for:

Simple configuration classes
Small save DTOs
Inspector-friendly data shapes
Known request or response structures

For complex server responses, dictionaries, custom naming rules, or polymorphic data, Newtonsoft.Json may be a better fit.

System.Text.Json can also be considered, but first verify the exact Unity version, .NET profile, IL2CPP/AOT behavior, source-generation setup, package integration, and stripping behavior. Success in the Editor under Mono does not prove that an iOS or Android IL2CPP build is production-ready.

ToJson still creates a JSON string, and FromJson creates a new object. Large datasets still allocate and must be profiled. When updating an existing instance is appropriate, FromJsonOverwrite can reduce object replacement and is worth considering.

MessagePack: A Runtime-Oriented Binary Format

MessagePack represents JSON-like structures in binary form.

Its main appeal is that it can be smaller than JSON and faster to serialize or deserialize, especially for numeric, array-heavy, or frequently processed data.

In Unity, it becomes attractive when one of these costs is visible in profiling:

JSON parsing
Temporary string allocation
Garbage collection
Startup loading
Network transfer
Large local caches

Where MessagePack fits well

MessagePack is most useful when machines, rather than people, own the final data.

A common static-data pipeline is:

Spreadsheet / YAML / CSV
        ↓ conversion and validation
MessagePack / project-specific binary
        ↓
Unity runtime

Designers and engineers work with a readable source format. The game loads a validated runtime artifact.

That conversion step separates authoring convenience from runtime efficiency.

MessagePack performance is conditional

“MessagePack is fast” is a useful tendency, not a universal guarantee.

Performance, size, and allocation depend on:

The selected library
Resolver configuration
String keys versus integer keys
DTO shape
Generated serialization code
IL2CPP/AOT setup
Compression settings
The number of objects created after deserialization

MessagePack is also not compression. If LZ4 or another compressor is added, measure both compression ratio and decompression cost with representative data.

Even fast deserialization does not help much if the application then:

Builds an enormous object graph
Runs LINQ queries repeatedly over the data
Loads content that is not needed at startup
Copies results into multiple collections
Uses inefficient lookup structures

If JSON is transmitted with HTTP gzip compression, its transfer size may approach MessagePack for some payloads. The JSON still has to be decompressed, parsed, and converted into objects, so profile network cost separately from CPU time and garbage collection.

For some datasets, generated C# code, SQLite, FlatBuffers, MemoryPack, a custom binary, or partitioned ScriptableObjects may be more appropriate. MessagePack should earn its place through measurements and operational fit.

MessagePack operational and security considerations

The biggest operational weakness is that people cannot inspect MessagePack directly.

It is not suitable for hand-editing or Git diff review. During an incident, opening a binary file does not immediately explain what it contains.

A production-friendly MessagePack workflow should include:

A debug exporter that produces JSON
A decode CLI or internal inspection tool
Explicit data versions
Schema validation
Conversion logs
Source-data references
Clear load-error messages
Checksums or hashes for corruption detection and artifact matching

Deserializing external input also makes the deserializer configuration part of the attack surface.

With MessagePack for C#, consider the following for untrusted input:

Use MessagePackSecurity.UntrustedData where appropriate.
Avoid Typeless APIs and resolvers unless the use case is tightly controlled.
Deserialize only approved DTO types.
Apply input-size limits.
Track security advisories and patch versions.
Validate the resulting DTO after deserialization.

A safer deserializer mode is not a substitute for validation or server-side trust boundaries.

Unity IL2CPP builds add AOT constraints. As of July 2026, MessagePack for C# v3 uses source generation for AOT workflows and lists Unity 2022.3.12f1 as its minimum supported version. Older Unity releases or older package versions require their own compatibility checks.

Even with current versions, test custom resolvers, generic types, code stripping, error paths, and actual device builds early. Package requirements can change, so confirm the official documentation for the exact Unity and package versions used by the project.

MessagePack is not encryption

MessagePack is harder to read in a text editor, but it is not encrypted. Anyone who understands the format can decode it.

Do not treat “binary” as tamper protection.

Checksums and ordinary hashes are useful for detecting accidental corruption or confirming that generated artifacts match. They do not stop an attacker who can modify both the data and the stored hash.

For malicious-tampering detection, consider:

A keyed MAC
A digital signature
Server-side validation
A server-authoritative design for important state

Encryption primarily provides confidentiality. It does not automatically provide complete tamper protection.

The same rule applies to network traffic. MessagePack does not replace HTTPS, authentication, authorization, replay defenses, or input validation.

Choosing Formats by Unity Use Case

User settings

Audio volume, graphics quality, vibration, language, and control preferences are normally small.

A reasonable default is:

Use PlayerPrefs for a few independent values.
Use JSON when the settings have a clear structure.
Prefer JSON when easy inspection is valuable.

MessagePack is rarely necessary for ordinary user preferences.

PlayerPrefs should remain within its natural boundary. It is not a good place for a large structured save file, secret values, or data that requires tamper resistance.

Save timing also matters. Unity normally writes PlayerPrefs during application shutdown, but mobile platforms may terminate an app without a reliable quit callback. Important settings should therefore be saved at meaningful checkpoints controlled by the application, such as confirming an options screen or entering a pause state when appropriate.

Do not call PlayerPrefs.Save() for every slider movement. The write may cause a noticeable hitch. Save at deliberate points rather than continuously during gameplay.

Save data

Save-data decisions depend heavily on game size and write frequency.

For a small game, JSON is a reasonable starting point because:

Developers can inspect it.
Customer-support investigations are easier.
Early schema changes are easier to understand.

For a large save file or frequent autosaves, MessagePack or a project-specific binary may be worth evaluating.

The format is only one part of save reliability. A robust save design also needs:

A version number
Migration from older versions
Validation and normalization
Writing to a temporary file first
Controlled replacement of the previous file
Backup and recovery behavior
Corruption detection
A policy for tampered data

JSON stored as plain text can be edited easily. Even in an offline game, edited values can cause cheating, support confusion, or crashes caused by impossible state.

Important state may require a keyed MAC, signature, or server validation. An ordinary hash is insufficient if the attacker can replace both the file and the hash.

Whether the payload is JSON or MessagePack, add a version field or equivalent from the beginning. Binary serialization does not create compatibility automatically.

Static game data

Static game data includes definitions such as:

Characters
Items
Skills
Stages
Quests
Shops
Gacha tables
Localization entries

This is one of the easiest areas to outgrow a single-format design.

A practical pipeline separates authoring from runtime delivery:

Authoring: Spreadsheet / Excel / YAML / CSV / dedicated admin UI
Conversion: Validate / normalize / generate code / export binary
Runtime: MessagePack / project-specific binary / generated C# data

Choose the authoring source based on the people and workflow:

Designers editing large tables: Spreadsheet or Excel
Engineers maintaining structured configuration: YAML
Simple interoperable tables: CSV
Live operations teams: Dedicated browser-based tooling

Choose the runtime format based on loading cost, memory behavior, validation guarantees, and update strategy.

Small datasets may remain in JSON without issue. If growth is expected, building the conversion and validation pipeline early is often more valuable than prematurely optimizing the final serializer.

A “project-specific binary” should mean a documented, validated runtime artifact with versioning, migration rules, debug export, and generation tooling. It should not merely mean “a file that is difficult to read.”

ScriptableObject and external formats

ScriptableObject is excellent for Unity-owned data that benefits from Inspector editing and asset references.

Examples include:

Enemy AI tuning
Effect references
Prefab references
Camera settings
Small gameplay configuration assets

It is less convenient as the only solution for huge tabular datasets, data shared with a server, or data that needs spreadsheet-style editing and cross-table validation.

A useful division of responsibility is:

ScriptableObject for Unity asset-oriented configuration
Spreadsheet, YAML, or CSV for authoring external static data
MessagePack or another binary for runtime distribution

Localization data

Localization datasets grow quickly and are often exchanged with translators.

Spreadsheet or CSV is usually convenient for authoring and vendor exchange. At runtime, partition by language or feature and convert the source into a structure that supports efficient ID lookup.

Addressables and AssetBundle metadata

Human-reviewed Addressables labels, download groups, or build settings may fit YAML. Generated metadata and tool-to-tool interchange often fit JSON.

There is usually no need to parse YAML on every player startup. Data known at build time should be validated and converted into a stable runtime representation.

Choosing a Format for Server APIs

Server communication is where the JSON-versus-MessagePack discussion becomes most visible.

The decision should include incident response, customer support, monitoring, and deployment—not only payload size.

APIs that usually fit JSON

JSON is a good default for APIs such as:

Login
User-profile retrieval
News and announcement retrieval
Shop information
Static-data version checks
Admin-panel APIs
External-service integration
Diagnostic APIs
Low-frequency operations

For these endpoints, observability and compatibility often matter more than a small payload reduction.

JSON works naturally with curl, Postman, server logs, dashboards, and proxy tools.

APIs that may benefit from MessagePack

MessagePack becomes more attractive for:

Very frequently called endpoints
Large list responses
Real-time or near-real-time traffic
Battle logs or state synchronization
Mobile traffic where transfer volume matters
Endpoints where JSON parsing is a measured bottleneck

Adopting MessagePack should come with operational support:

A JSON decoder for investigations
API and data versioning
Shared DTO rules between client and server
Backward-compatibility policy
Readable server-side diagnostic logging
Request and response validation

Using MessagePack for every endpoint often adds more operational cost than it saves. Limiting it to measured hot paths is usually easier to maintain.

Using JSON in development and MessagePack in production

A development-versus-production switch can be useful, but it has a dangerous failure mode: testing only JSON in development while production alone uses MessagePack.

Avoid that design.

Instead, separate the wire format from the debug representation.

A practical setup is:

Local development: Switch between JSON and MessagePack
CI and staging: Test both, and always exercise the production path
Production: Use MessagePack only for endpoints where it provides value
Investigation: Render decoded DTOs as masked JSON

Keep the following common across both formats:

DTO meaning
Data version
Normalization
Validation
Error handling

Change only the encoder and decoder based on Content-Type, Accept, or explicit configuration.

Automated tests can serialize the same DTO through JSON and MessagePack, deserialize both, and compare the normalized results. Once MessagePack is selected for production, engineers should exercise that path continuously rather than only before release.

This is especially important for IL2CPP/AOT behavior, resolver configuration, integer-key compatibility, compression, and client/server implementation differences.

When JSON + gzip remains the right production choice

Production does not automatically mean MessagePack.

If transfer size is the main problem while JSON parsing and allocation remain acceptable, JSON + gzip is a strong tradeoff.

Repeated property names and recurring text usually compress well. The project keeps the compatibility and investigation benefits of JSON while reducing bandwidth.

In HTTP terms, the media type and compression are separate concerns:

Content-Type: application/json
Content-Encoding: gzip

Small responses may not benefit because headers and compression work become significant relative to the payload. Use representative data to choose a minimum size threshold rather than compressing every response blindly.

If request bodies are also compressed, client and server support must be explicitly aligned.

gzip is compression, not encryption. It may prevent a raw byte dump from being immediately readable as plain JSON, but identifying and decompressing it is straightforward. Treat that as incidental obfuscation at most, not as a security boundary.

Use HTTPS/TLS for transport confidentiality and integrity. Use authentication, authorization, replay defenses where needed, and server-side validation for game rules.

A useful decision split is:

Only transfer size is a problem: evaluate JSON + gzip.
JSON parsing and GC are also a problem: evaluate MessagePack.
Neither is a measured problem: keep plain JSON.
The payload is a large binary asset: avoid Base64 inside JSON and use file delivery or a separate endpoint.

Mixing JSON and MessagePack is acceptable

A project does not need one wire format for every API.

For example:

Normal APIs and admin tools: JSON
Large or latency-sensitive endpoints: MessagePack
Logs and audit events: JSON Lines

Even when the encoding differs, preserve common DTO semantics, versions, validation rules, and monitoring conventions.

DTO Design Matters More Than the Serializer

A poor DTO remains difficult to maintain in every format.

Separate Unity runtime models from DTOs

Do not serialize a Unity gameplay object directly just because it already contains the values you need.

public sealed class Player
{
    public string Name;
    public int Level;
    public GameObject AvatarPrefab;
    public RuntimeAnimatorController Animator;
}

This class mixes data with Unity asset references and runtime state.

Create a dedicated DTO instead:

[Serializable]
public sealed class PlayerDto
{
    public string name = "";
    public int level;
    public string avatarId = "";
}

The lowercase field names above intentionally produce name, level, and avatarId with JsonUtility. If the project uses PascalCase C# members, configure property naming through the selected JSON library instead.

DTOs should primarily contain values such as:

int, long, float, and bool
Strings
Arrays and List<T>
IDs that reference assets or definitions

Avoid putting these directly into persistence or network DTOs:

GameObject
Texture or Sprite
ScriptableObject references
Events
Runtime caches
UI state

Define field and null policies

With JSON and string-key MessagePack, field names become part of the serialized contract. With integer-key MessagePack, the key numbers become the contract.

Treat published fields like API fields:

Do not casually rename them.
Avoid removing them without migration.
Prefer adding new optional fields.
Normalize older data during loading.

Also define whether missing collections become null or empty collections.

A normalization step reduces repeated null checks in gameplay code:

public sealed class InventoryDto
{
    public List<string> itemIds = new List<string>();

    public void Normalize()
    {
        itemIds ??= new List<string>();
    }
}

Validation should still reject impossible ranges, unknown enum values, oversized strings, and invalid IDs.

Manage MessagePack integer keys deliberately

With MessagePack for C#, integer keys may improve compactness and speed:

[MessagePackObject]
public sealed class CharacterDto
{
    [Key(0)] public int Id { get; set; }
    [Key(1)] public string Name { get; set; } = "";
    [Key(2)] public int Hp { get; set; }
}

They also create a compatibility obligation.

A safe policy is:

Never change an existing key number.
Never reuse a deleted key number.
Append new fields at the end.
Give the data an explicit version where migration is required.
Test old payloads against new readers.

String keys favor readability and evolution. Integer keys favor compactness and throughput. Choose based on data lifetime and compatibility needs, not only benchmark numbers.

Common Failure Modes

Failure 1: Using the authoring format directly at runtime

Reading designer-owned YAML or JSON directly in the player is convenient at first.

As the dataset grows, loading, allocation, validation, and error reporting become harder. Convert the source into a normalized runtime representation, remove comments and unused columns, validate references, and emit only the values the game needs.

Failure 2: Assuming JSON is safe because it is standard

External JSON and user-editable JSON are untrusted input.

Prepare for:

Missing required fields
Wrong types
Out-of-range numbers
Huge strings or arrays
Unknown enum values
Invalid IDs

JSON and MessagePack both require validation after deserialization.

Failure 3: Expecting MessagePack to make the whole load fast

MessagePack can reduce representation size and parse cost. It cannot fix inefficient data partitioning, repeated searches, unnecessary copies, or excessive object construction.

Measure the complete loading path.

Failure 4: Making binary data impossible to investigate

Binary formats reduce observability unless the team deliberately restores it.

Record enough metadata to answer:

Which source produced this file?
Which converter version was used?
When was it generated?
Which data version does it contain?
How many records were loaded?
Can it be exported back to readable JSON?

Without those answers, a compact file can become an expensive operational problem.

Recommended Project Structures

Small project

Keep the system simple:

User settings: PlayerPrefs / JSON
Save data: JSON
Static game data: JSON / ScriptableObject
Server APIs: JSON
Tool configuration: YAML

For small datasets, MessagePack's operational cost may exceed its benefit.

Medium project

Separate source data from runtime data:

User settings: JSON
Save data: JSON, with MessagePack evaluated if needed
Static-data source: Spreadsheet / YAML / CSV
Static-data runtime: MessagePack / project-specific binary
Server APIs: JSON
Large API payloads or production hot paths: JSON + gzip / MessagePack
Logs: JSON Lines

Run validation before the build and reject duplicate IDs, missing references, invalid ranges, and unsupported values.

Large or long-running project

Design the pipeline rather than choosing one serializer:

Authoring: Spreadsheet / Excel / YAML / dedicated admin UI
Conversion: Validate / normalize / generate code / export binary
Unity runtime: MessagePack / project-specific binary / generated loader
Server: JSON APIs / gzip compression / MessagePack hot paths
Operations: JSON logs / decode tools / data-version tracking

Make ownership explicit: where conversion happens, where validation happens, and how incidents are investigated.

A Simple Decision Flow

1. Do people edit the data directly?
   Yes → YAML / Spreadsheet / CSV / dedicated UI
   No  → Continue

2. Must it integrate with external services or admin tools?
   Yes → Start with JSON
   No  → Continue

3. Is network size or frequency a measured problem?
   Yes → Evaluate JSON + gzip, MessagePack, or API partitioning
   No  → Continue

4. Does the Unity runtime load a large local dataset?
   Yes → Evaluate MessagePack, generated code, partitioning, or another binary
   No  → JSON or ScriptableObject may be enough

5. Must people inspect the data during an incident?
   Yes → Keep JSON in the workflow or provide a decoder
   No  → A binary-oriented representation may be acceptable

Do not try to predict one perfect format at the beginning of the project. Change formats at clear boundaries and optimize only the parts that need it.

Conclusion

YAML, JSON, and MessagePack solve different problems.

YAML is strong for hand-written configuration, comments, and reviewable source data.
JSON is strong for interoperability, observability, APIs, tools, and small datasets.
MessagePack is strong for validated runtime data and measured hot paths where size, parsing, or allocation matters.
JSON + gzip is a legitimate production option when bandwidth is the main issue and JSON parsing remains acceptable.

None of them is universal.

If MessagePack is introduced, introduce the supporting tools as well: decoders, versioning, validation, device testing, and representative benchmarks.

The durable rule is still this:

Use human-friendly formats at authoring time, machine-friendly formats at runtime, and choose network formats by balancing observability against efficiency.

References

What MasterMemory Solves—and What It Doesn't: A Practical Guide to Static Game Data in Unity

GameDevToolLab — Wed, 15 Jul 2026 03:52:57 +0000

Introduction

When you build games with Unity, you eventually run into the problem of managing static game data—often called master data in Japanese game development.

At first, ScriptableObject may be more than enough. If your project has a few dozen items, a few dozen enemies, and only a small number of stage definitions, ScriptableObject is convenient because you can inspect and edit everything directly in the Unity Editor.

As the project grows, however, the situation changes.

You may end up with tables for items, characters, skills, quests, rewards, shops, gacha pools, stages, enemy placements, progression curves, and localization text. The data is no longer edited only by programmers. Planners and game designers may need to work with it in Excel or Google Sheets.

At that point, the problem is no longer just choosing a file format. You need to think about questions such as:

How do you load a large amount of data quickly?
How do you write ID lookups and composite-key queries safely?
Should CSV or JSON be parsed directly at runtime?
Is it reasonable to create a large number of Dictionaries?
How do you validate references between tables?
How do you debug data after converting it to binary?
How do you connect the source data edited by planners to the data loaded by Unity?

For the runtime loading and lookup part of that problem, one strong option is Cysharp's MasterMemory.

The official README describes MasterMemory as a “Source Generator based Embedded Typed Readonly In-Memory Document Database” for .NET and Unity. In practical terms, you define your schema as C# types, a Source Generator creates a typed read-only in-memory database API, and the application loads MessagePack binary data that can be queried through type-safe methods.

The official README highlights performance compared with SQLite, low allocation during queries, a small database size, and generated database structures that are type-safe and IDE-friendly.

Cygames Engineers' Blog also has useful articles about the design philosophy behind MasterMemory and the Validator introduced in v2. These articles are in Japanese, but they are valuable references:

There are also clear Japanese articles covering Unity setup and basic usage:

One thing to keep in mind is that information about MasterMemory v2 and earlier often assumes the old Code Generator workflow, while v3 and later are based on Source Generators. Always check the README and release notes for the version you actually plan to use.

Unless otherwise noted, the API behavior described in this article refers to MasterMemory v3.0.4.

This article is not a step-by-step installation tutorial. Instead, it focuses on what MasterMemory solves in a production Unity project and where its responsibilities end.

The conclusion is straightforward: MasterMemory is a strong option when you need to handle large amounts of read-only static game data with fast loading, low memory overhead, and type-safe queries. It does not, however, decide how planners edit the source data, how localization is managed, how diffs are reviewed, how CI generates the database, or how environment-specific data is deployed.

The most useful way to evaluate it is as a fast, type-safe, read-only database, separate from the pipeline around it.

The Basic Role of MasterMemory

Three characteristics are central to understanding MasterMemory:

Read-only
In-memory
Strongly typed

That combination is a good fit for static game data.

Most game master data is not supposed to be mutated continuously during gameplay.

A live-service game may download a new data package from a server or switch to a different dataset for an event. But once the client has loaded a dataset, it is usually treated as immutable for the rest of the session.

If item definitions or skill definitions can be modified directly during gameplay, several problems become more likely:

It becomes difficult to know when a value changed.
It becomes difficult to identify which system changed it.
Cached data can become inconsistent.
Threading and asynchronous processing become harder to reason about.
Bugs become less reproducible.

Treating master data as immutable after loading simplifies the runtime architecture.

MasterMemory is designed around that assumption.

“Read-only” does not mean that a running game can never switch to new master data. It means that the active MemoryDatabase should be treated as an immutable snapshot. When new data is needed, you can construct a new database from a new binary package, or use ToImmutableBuilder() to apply changes and build another immutable database, then replace the shared reference.

The data is converted to binary ahead of time, loaded into a MemoryDatabase at startup or another appropriate point, and queried through generated table APIs.

var db = new MemoryDatabase(binary);
var item = db.ItemMasterTable.FindByItemId(1001);

The examples in this article use FindBy..., but production code must also account for missing keys.

In the v3.0.4 README, some older wording still appears in one place, but the MemoryDatabase / RangeView section and the Generator Option documentation describe the current behavior: for a unique key, FindBy... throws KeyNotFoundException when the key is missing. A generated TryFindBy... method is also available.

For IDs originating outside the validated master-data package—such as save data, server responses, or QA commands—using TryFindBy... is usually the safest default.

If the Generator Option IsReturnNullIfKeyNotFound is enabled, unique-key lookups can return null instead. A FindBy... query on a NonUnique key returns a RangeView<T>, and an unmatched query produces an empty result.

A useful division of responsibility is:

Detect invalid references inside the master-data package with Validator.
Defend against invalid external IDs at runtime.

Once this structure is in place, runtime access becomes much simpler.

You no longer need to parse CSV at startup. You can reduce the amount of JSON-to-Dictionary conversion code. You also need fewer hand-written lookup Dictionaries for every table.

ScriptableObject, SQLite, or JSON loaded through Addressables may still be the right choice in some projects. But for a large set of read-heavy tabular data, MasterMemory's design maps well to common game requirements.

What MasterMemory Solves

MasterMemory is particularly effective in the following areas:

Storing master data in a read-only in-memory database
Generating type-safe query APIs with a Source Generator
Supporting PrimaryKey and SecondaryKey lookups
Supporting composite keys, range queries, and closest-value queries
Loading MessagePack binary data
Interning repeated strings to share references
Validating data consistency through Validator
Exposing Metadata that can support surrounding tools

Existing articles often focus on setup, raw performance, or comparisons with Dictionary.

The official README includes claims such as 4700 times faster than SQLite, zero allocation per query, and DB size is small. Those numbers come from specific benchmark conditions and example datasets. The actual difference in your project depends on the schema, record count, query frequency, load timing, and target platform.

In Unity, perceived performance can also change depending on:

Editor versus device
Mono versus IL2CPP
Whether the binary is loaded from Resources, StreamingAssets, Addressables, an AssetBundle, or a remote server
The I/O cost of retrieving the binary
Whether the caller applies LINQ or copies results into another collection

zero allocation per query should be understood as a property of the query API itself. If the calling code adds LINQ chains or copies the result into a new List, those operations may allocate separately.

Even with those caveats, the underlying direction is well suited to static game data: build sorted structures ahead of use, rely on binary search, and avoid unnecessary runtime work.

The Cygames article explains that MasterMemory uses sorted arrays and binary search to achieve lookup performance close to Dictionary while improving construction cost and memory efficiency in suitable workloads.

The following sections focus on the production benefits that become important beyond a simple benchmark.

Read-Only Is a Strength, Not Just a Restriction

MasterMemory is read-only.

That can sound like a limitation, but for game master data it is often a major advantage. Master data usually describes definitions used to interpret the mutable state of the game.

For example, the number of items owned by a player belongs to save data and changes over time.

The definition that item ID 1001 is a herb with a price of 50 and a healing value of 100 is master data. That definition should normally remain stable while the game is running.

Mixing those two categories makes the architecture harder to maintain.

// Mutable state
playerInventory.SetCount(itemId, count);

// Immutable definition
var item = master.ItemMasterTable.FindByItemId(itemId);

Treating master data as read-only provides several benefits:

Better reproducibility
Less rebuilding of lookup caches after data changes
Simpler code on the consumer side
More stable behavior after asynchronous initialization
Easier tests with deterministic inputs
Protection against accidental runtime mutation

The same master data may be consumed by battle logic, UI, shops, rewards, tutorials, localization, and visual presentation. If any of those systems can mutate the shared definitions, assumptions made by the other systems can collapse.

Read-only data narrows runtime responsibilities and makes those shared assumptions safer.

Repeated Strings Can Be Shared Automatically

By default, MasterMemory interns identical strings while constructing the database.

Static game data often repeats category names, localization keys, asset identifiers, and other strings across many rows. Without interning, identical text may exist as multiple string instances. With interning, those rows can share the same reference.

This can be useful for denormalized tables where strings are repeated to make queries or exports simpler. The behavior can be disabled through the internString argument of MemoryDatabase, so it can be evaluated against the actual characteristics of the data and measured on target devices.

It is less visible than query speed, but for a game that keeps large tables resident in memory, it is a practical benefit.

Type-Safe Query APIs Improve Maintainability

One of MasterMemory's strongest features is the type-safe query API generated by its Source Generator.

The official README explains that the C# schema produces a typed database structure with IDE completion.

For a small project, loading CSV into a Dictionary may be enough.

var value = row["ItemId"];

As a project grows, string-based access becomes fragile:

Column-name typos are not detected until runtime.
Renaming a column is difficult to propagate safely.
Refactoring support is weak.
Type conversion logic spreads across the codebase.
It becomes unclear which columns are valid lookup keys.

With MasterMemory, PrimaryKey and SecondaryKey attributes define the indexes, and query methods are generated from the schema.

The following is a conceptual example. Follow the recommended definitions for the versions of MasterMemory and MessagePack used by your project.

[MemoryTable("item"), MessagePackObject(true)]
public sealed class ItemMaster
{
    [PrimaryKey]
    public int ItemId { get; init; }

    [SecondaryKey(0), NonUnique]
    public ItemType Type { get; init; }

    public string NameKey { get; init; }
    public int Price { get; init; }
}

In this article, the generated table API for ItemMaster is consistently written as ItemMasterTable. The string in [MemoryTable("item")] identifies the table in the database binary; it serves a different purpose from the generated C# type and property names.

var item = db.ItemMasterTable.FindByItemId(itemId);
var weapons = db.ItemMasterTable.FindByType(ItemType.Weapon);

The benefit is not merely shorter code.

The available lookup paths become explicit in the API. IDE completion shows the generated methods, renames are easier to track, and incorrect types are detected at compile time.

Master data is rarely maintained by only its original author. Another programmer may inherit it years later. Large balance changes may arrive near the end of production. In a live-service game, new tables and rows continue to accumulate.

If access logic is scattered across string keys and custom Dictionaries, the system becomes difficult to understand. A generated typed API preserves the intent of each lookup in code.

Composite Keys, Range Queries, and Closest-Value Queries Fit Game Data

Game master data often needs more than a simple ID lookup.

ID queries are still the foundation:

var item = db.ItemMasterTable.FindByItemId(itemId);

But production games regularly need queries such as:

Retrieve a reward by stage ID and difficulty.
Retrieve progression values by character ID and level.
Retrieve products by shop ID and category.
Retrieve rewards for a rank.
Find the rating definition closest to a score.
Retrieve active rows for an event ID.
Retrieve experience values within a level range.

A Dictionary-only implementation tends to accumulate supporting structures:

Dictionary<int, ItemMaster> itemById;
Dictionary<ItemType, List<ItemMaster>> itemsByType;
Dictionary<(int stageId, Difficulty difficulty), StageRewardMaster> rewardByStageAndDifficulty;
Dictionary<int, List<LevelMaster>> levelsByCharacterId;

There is nothing inherently wrong with that approach. For a small project, a few custom Dictionaries may be the clearest solution.

As the table count, lookup patterns, and team size grow, however, common problems appear:

Nobody is sure which Dictionary is the canonical lookup path.
Multiple Dictionaries are created for the same purpose.
Initialization order becomes complicated.
Memory usage becomes difficult to understand.
Rebuild logic is missed when data changes.
Composite-key conventions differ across the project.

MasterMemory can generate unique and non-unique lookups, composite-key queries, range queries, and closest-value queries from PrimaryKey and SecondaryKey definitions.

The official README includes examples such as multi-key queries, FindClosestBy***, and FindRangeBy***.

This moves the decision about how a table should be queried closer to the schema itself. Lookup structures are less likely to spread throughout consumer code.

In a multi-programmer project, consistency has value by itself. If the team knows that a particular piece of data always comes from a particular generated table method, reviews become easier and unnecessary caches are less likely to proliferate.

The Value of Reducing Hand-Written Dictionaries

Discussions about MasterMemory often turn into a simple question: “Is it faster than Dictionary?”

Performance matters, but production value also comes from leaving behind a workflow where every new query requires another custom Dictionary.

A data repository that starts small can gradually turn into something like this:

public sealed class MasterDataRepository
{
    Dictionary<int, ItemMaster> itemById;
    Dictionary<int, SkillMaster> skillById;
    Dictionary<int, CharacterMaster> characterById;
    Dictionary<int, List<SkillMaster>> skillsByCharacterId;
    Dictionary<(int stageId, int difficulty), StageMaster> stageByKey;
    Dictionary<int, List<ShopItemMaster>> shopItemsByShopId;
}

This repository may initially be convenient. Over time, it often develops familiar problems:

Initialization grows longer.
Dictionary construction code accumulates.
It becomes unclear which caches are actually required.
Unused caches remain in memory.
Every new query pattern adds another structure.
Tests become harder to write.
Validation logic becomes mixed with cache construction.

At that point, the data repository itself has become technical debt.

MasterMemory moves many of these basic lookup structures into the schema and generated code.

Project-specific convenience methods and cross-table queries will still be necessary. But the team no longer has to reimplement ID lookup, composite-key lookup, range lookup, and non-unique grouping every time.

That improves not only performance characteristics, but also architectural clarity.

Dictionary is still the better choice in some cases. If there are only a few tables, every query is a simple ID lookup, and the data is temporary or frequently replaced during runtime, a straightforward Dictionary may be easier to manage. The same may be true for editor tooling or debugging data that developers want to inspect and modify directly.

The goal is not to reject Dictionary. MasterMemory becomes valuable when lookup patterns and cache-construction code begin to scale faster than the team can manage comfortably.

Binary Data Simplifies the Runtime Loading Path

Reading CSV or JSON directly at runtime is convenient early in development.

CSV is easy to export from Excel or Google Sheets. JSON represents structure clearly and is easy to inspect while debugging.

In a production runtime, however, parsing CSV or JSON may introduce additional work:

Parsing is required.
String processing increases.
Values must be converted to their target types.
Errors appear at runtime.
GC allocations may increase.
Loading may take longer.
Platform-specific behavior may surface.

For a small dataset, this may not matter. Keeping a lightweight configuration file as JSON can be the simpler choice for debug builds, operations tools, A/B test settings, or other small and frequently inspected data.

For a mobile game or a long-running live-service project where the amount of static data continually grows, runtime text parsing is often something worth reducing.

MasterMemory builds the data as a MessagePack binary package ahead of time. At runtime, the client retrieves that binary and constructs a MemoryDatabase.

var binary = await LoadMasterBinaryAsync();
var db = new MemoryDatabase(binary);

Binary data does not make MemoryDatabase construction free. Large datasets should still be profiled on target hardware. If necessary, the constructor's maxDegreeOfParallelism option can also be evaluated.

The runtime path becomes focused on three responsibilities: retrieve the binary, build the database, and query it.

CSV column resolution, string-to-integer conversion, enum conversion, date parsing, null handling, and empty-string rules no longer need to run as part of every client startup path.

Unity still needs a project-specific strategy for retrieving the binary.

MasterMemory's responsibility begins once the binary has been obtained. The project must decide whether it lives in Resources, StreamingAssets, Addressables, an AssetBundle, or a remote content-delivery system.

The application must also prevent database access before asynchronous initialization completes. If the game supports hot updates or event-specific dataset swaps, the team must define when the active database changes and how long consumers of the previous snapshot may continue to exist.

Production code should also decide what happens when loading fails:

Stop startup and show an error
Retry
Continue using the last known-good database

A single reference point such as MasterDataProvider can help ensure that every system observes the same database generation. When a binary is obtained as a TextAsset through Addressables or AssetBundle, the lifetime of the handle and the data required after database construction should also be verified.

It is safer to avoid caching row objects or RangeView<T> values from an old database for long periods after a swap.

A clean division is:

Convert and validate data before the build, or in CI.
Load only validated binary data at runtime.

That separation makes the runtime code more predictable.

Writing Validators in C# Is Practical

The most dangerous master-data errors are often not failures to parse. They are values that parse successfully but describe an invalid game state.

Examples include:

A reward item ID that does not exist
A skill referencing a missing effect ID
A gap in a level progression table
A missing localization key
A start date later than an end date
Probabilities that do not add up to 100 percent
Duplicate values inside a group that requires uniqueness

Types alone cannot catch these problems.

An integer may be valid as an integer while still referencing a nonexistent record. A string may be valid as a string while still naming a missing localization entry.

MasterMemory includes Validator support.

The Cygames article about MasterMemory v2 explains that a schema can implement IValidatable<T>, allowing validation logic to stay close to the data definition. It can validate reference-like relationships, numeric ranges, and rules involving the entire dataset.

A conceptual example that verifies a reward item reference may look like this:

[MemoryTable("quest"), MessagePackObject(true)]
public sealed class QuestMaster : IValidatable<QuestMaster>
{
    [PrimaryKey]
    public int QuestId { get; init; }

    public int RewardItemId { get; init; }

    void IValidatable<QuestMaster>.Validate(IValidator<QuestMaster> validator)
    {
        if (RewardItemId > 0)
        {
            var items = validator.GetReferenceSet<ItemMaster>();

            // Conceptual example: verify that the current QuestMaster.RewardItemId
            // exists as an ItemMaster.ItemId.
            items.Exists(quest => quest.RewardItemId, item => item.ItemId);
        }

        // Additional validation can still run when RewardItemId <= 0.
    }
}

Validator is easiest to reason about when it runs after database generation, before a build, or as part of the CI conversion pipeline. Its role is to stop invalid data before the game loads it, rather than discovering the problem after the runtime has already started.

Writing the rules in C# is flexible.

The team can use IDE completion, refactoring tools, compile-time type checking, and its normal code-review process instead of introducing a separate DSL or rule-file format.

Game-data validation also tends to exceed simple foreign-key checks:

Another column is required only when a flag is true.
Allowed ranges differ by rarity.
The referenced table depends on the event type.
Certain ID ranges are reserved.
A value is allowed in development but forbidden in production.
Consistency must be checked across several tables.

Those rules are often easier to maintain as normal program logic.

Validator therefore makes MasterMemory more than a runtime lookup database. It also gives the data pipeline a place to enforce data quality.

Metadata Leaves Room for Surrounding Tools

The official README also describes Metadata APIs that can be used when building custom importers and exporters.

This is less visible than lookup performance, but it matters in production.

A complete game-data workflow usually needs more than the runtime database:

A CSV conversion tool
A Google Sheets importer
A diff viewer
HTML or Markdown validation reports
Readable CI error output
A debug exporter that converts data back to JSON
Planner-facing tools that identify the exact source of an error

When building these tools, it helps to inspect table and column definitions programmatically.

Metadata makes it possible to build a custom pipeline around MasterMemory.

That does not mean MasterMemory automatically provides a finished operational platform. It means the library exposes enough structure for teams to build the workflow they need.

This extensibility becomes valuable when MasterMemory is treated as one component of a larger data pipeline rather than only as a runtime database.

How It Compares with ScriptableObject

ScriptableObject remains a powerful option for static data in Unity.

It has a different set of strengths:

Data is visible in the Unity Editor.
Designers can edit it through the Inspector.
It can be referenced as an Asset.
It integrates naturally with Prefabs and Addressables.
It can be convenient for artists and level designers.

There is no need to reject ScriptableObject.

For many kinds of data, ScriptableObject is the better tool:

A small number of configuration objects
Data that benefits from references between ScriptableObjects
Data that should be edited visually in the Unity Editor
Data that directly references Unity Assets
Presentation settings for individual levels

Managing a large tabular dataset entirely with ScriptableObject becomes more difficult:

One Asset per record creates many files.
The data is difficult to view as a complete table.
Spreadsheet-style editing is awkward for planners.
Diffs are harder to review.
Bulk conversion and validation require additional tooling.
ID and composite-key queries still need to be implemented.

MasterMemory is better suited to large tabular datasets that need fast, type-safe lookup.

For Asset references, a MasterMemory row can store an Addressables key, GUID, Resources path, or project-specific Asset ID, while another layer resolves that identifier to the actual Unity Asset. Separating tabular game data from Asset resolution often produces a cleaner workflow than forcing both responsibilities into the same system.

ScriptableObject and MasterMemory are therefore less direct competitors than they first appear. Their strengths differ:

Use ScriptableObject for a small number of editor-friendly configuration Assets.
Use MasterMemory for large tabular datasets that require structured, type-safe lookup.

How It Compares with SQLite

SQLite is another established option for a local database.

It has a long track record, supports flexible SQL queries, and benefits from a mature ecosystem of tools.

For client-side static game data, however, that flexibility may be more than the project needs.

Most games do not construct arbitrary SQL queries during gameplay. They usually perform a known set of lookups:

Find by ID
Find by composite key
Retrieve all rows for a group ID
Retrieve a range
Retrieve the closest value

For those patterns, type-safe generated APIs, low allocation, fast loading, and compact memory usage may be more useful than unrestricted SQL.

String-based SQL also means that some query errors remain invisible until runtime.

MasterMemory defines the lookup patterns ahead of time and exposes generated methods.

It is less flexible than SQLite, but that trade-off can make it easier to use for read-only game data.

The point is not that one tool is universally better.

SQLite may be the right choice when runtime updates or flexible ad hoc queries are required. MasterMemory is a better fit when the application reads a large, predefined dataset through known query paths.

When MasterMemory Is—and Is Not—a Good Fit

The following table summarizes the decision:

Consideration	MasterMemory is a good fit	Another approach may be simpler
Data size	Many tables or records	Only a small amount of data
Update frequency	Mostly immutable during a session	Mutated frequently at runtime
Queries	Many ID, composite-key, or range queries	Only a few simple lookups
Performance	Startup time, GC, or memory usage matters	Performance is not currently a concern
Type safety	Query mistakes should be caught at compile time	Minimal setup is more important
Validation	Cross-table references and ranges need C# validation	Manual inspection is sufficient
Pipeline	Conversion and validation should run in CI	Local manual work is sufficient
Existing architecture	Custom Dictionaries have grown complex	ScriptableObject already works well

The most important considerations are usually data size, lookup patterns, and update frequency.

If the dataset is large, the game uses more than simple ID lookups, and the active data is effectively immutable during a session, MasterMemory is a natural candidate.

If ScriptableObject already handles a small dataset comfortably, if the data is temporary and frequently mutated, or if the project requires arbitrary SQL queries, another approach may remain simpler.

Adoption also has a cost.

A MasterMemory project needs schema management based on Source Generators and MessagePack attributes. Migrating from ScriptableObject, CSV, or JSON may require conversion tools and a validation pipeline.

Schema changes also require the team to consider binary regeneration, compatibility, and consistency with already distributed data. In Unity, package updates, generated code, IL2CPP/AOT behavior, and CI generation steps become part of the operational process.

The Unity version must support the Source Generator workflow, and package installation generally involves NuGetForUnity or an equivalent setup. At the time of writing, the v3.0.4 README lists Unity 2022.3.12f1 as the minimum supported version.

If examples use C# 9 init accessors, some Unity configurations may require an IsExternalInit definition so the compiler can resolve that feature. In IL2CPP builds, the generated MasterMemoryResolver must also be registered with MessagePack's Resolver configuration.

This is not an installation tutorial, so the exact setup is left to the official README and version-specific guides. The important point is that a project can appear to work in the Editor and still fail later in an IL2CPP device build if these requirements are ignored.

MasterMemory is not a magic box that instantly solves every master-data problem.

What it does provide is a clear owner for the runtime read-only database layer, which makes the rest of the runtime architecture easier to organize.

What MasterMemory Does Not Solve

So far, this article has focused primarily on MasterMemory's strengths.

The remaining areas are not necessarily weaknesses. They are responsibilities outside the scope of the library.

MasterMemory is effective at providing fast, type-safe runtime access to static data. A production game-data workflow also has stages before and after that runtime database.

Area	Decisions MasterMemory does not make for you
Source of truth	Whether Excel, Google Sheets, or CSV is authoritative
Editing workflow	How planners edit and review changes
Conversion	How source rows become C# objects and then a database binary
Localization	How keys, missing translations, per-language CSV files, and translation returns are handled
Diff review	How humans compare revisions
Debugging	How a binary record maps back to its source row
CI/CD	How conversion, validation, and failure reporting are automated
Environments	How development, QA, production, and pre-release event data are separated

If Google Sheets is the source of truth, the project still needs code that retrieves the sheets through an API, converts rows to typed objects, and passes them to MasterMemory's DatabaseBuilder.

If Excel is the source of truth, the team still needs rules for reading files, interpreting sheet and column names, handling blank rows and comments, and converting values to their target types.

Localization is another separate workflow.

Text keys can be stored in MasterMemory, but the library does not decide how to export per-language CSV files, detect missing translations, remove obsolete keys, exchange files with a translation vendor, or review changes when translations return.

Binary data is efficient for the runtime but inconvenient for humans to inspect directly.

A production workflow often needs tools that answer questions such as:

Did the number of records remain consistent after conversion?
How was a specific ID transformed?
What changed since the previous build?
Did development-only data leak into the production package?
Is the device actually using the latest dataset?
Which row in the original spreadsheet caused the validation error?

Validator is useful for data correctness, but planner and QA workflows such as reviewing diffs, inspecting conversion results, and tracing an error back to a source row usually require additional tools.

CI/CD and environment-specific data require the same kind of explicit design.

MasterMemory can be the final database that the client reads, but the project still decides which source generates which binary, under what conditions, and where that binary is deployed.

Leaving those decisions vague can lead to serious mistakes: development data being shipped to production, builds using stale binaries, or unvalidated data entering a release.

The distinction matters.

Adopting MasterMemory does not automate the entire lifecycle of game data. It does, however, give the runtime lookup layer a clear and reliable shape.

Once that layer is stable, the surrounding import, validation, conversion, deployment, diff, and debugging pipeline becomes easier to design deliberately.

Conclusion

MasterMemory is a strong option for Unity and .NET projects that need to handle a large amount of read-only static game data.

Its Source Generator creates type-safe query APIs, while composite-key, range, and closest-value queries, MessagePack binary loading, Validator, Metadata, and string interning help organize runtime data access. Read-only behavior is also a good fit for game data because the active database can be treated as an immutable snapshot.

The source of truth in Excel or Google Sheets, planner-facing editing, localization, diff review, CI conversion, environment-specific deployment, and debugging remain responsibilities of the surrounding pipeline.

That is not a defect so much as a boundary of responsibility.

Evaluating MasterMemory as a fast, type-safe, read-only database, rather than as a complete master-data management platform, makes adoption decisions much clearer. Its runtime strengths become most valuable when they are combined with a deliberate pipeline for importing, converting, validating, reviewing, and distributing the data around it.

Speed Up Game Tuning with ScriptableObject: Edit and Save Values During Play Mode in the Unity Editor

GameDevToolLab — Tue, 14 Jul 2026 08:43:44 +0000

Introduction

ScriptableObject is often one of the first tools developers reach for when they need to manage data in a Unity project.

Typical examples include enemy parameters, weapon settings, camera shake, player movement speed, skill cooldowns, and per-stage tuning values.

Because a ScriptableObject exists as an asset in the Unity Editor, it is easy to inspect, edit, and reference independently from scenes and prefabs. For small to medium-sized configuration data, it is an extremely convenient option.

Unity's documentation describes ScriptableObject as a data container that exists independently from class instances. It can also reduce duplicated data by allowing multiple prefabs to reference the same asset.

Unity Manual - ScriptableObject

However, the real value of ScriptableObject is not limited to storing data as an asset.

One of its most useful properties in day-to-day game development is that you can change values while the game is running in the Unity Editor and immediately apply those changes to gameplay.

Movement speed, jump force, enemy attack intervals, camera following, knockback, hit-stop, and input-buffer timing rarely have a single correct value from the beginning. You normally decide them by playing the game and checking how they interact with the screen, controls, enemy movement, level size, and animation timing.

That process becomes slow when every adjustment requires the following cycle:

Change code.
Compile.
Enter Play Mode.
Test the result.
Exit Play Mode.
Change the value again.

If tuning values are collected in a ScriptableObject and the game reads them during Play Mode, you can make adjustments from the Inspector without repeatedly restarting the game.

This article looks at ScriptableObject not only as a place to keep small master-data sets, but as a practical workflow for speeding up game tuning.

The word "save" in this article refers to development work performed inside the Unity Editor. The samples primarily target Unity 2022.3 LTS and later. For older Unity versions, check whether the Editor APIs used here are available.

This is not a workflow for modifying a ScriptableObject asset in a player build and using it as user save data. Runtime save data should normally use a separate destination such as JSON, a binary format, PlayerPrefs, cloud storage, or a project-specific database.

ScriptableObject Stores Data as a Project Asset

Unlike a MonoBehaviour, a ScriptableObject does not need to be attached to a GameObject. It can exist directly as an asset in the Project window.

For example, the following asset holds player-tuning values:

using UnityEngine;

[CreateAssetMenu(
    fileName = "PlayerTuning",
    menuName = "Game/Tuning/Player Tuning")]
public sealed class PlayerTuning : ScriptableObject
{
    [Header("Move")]
    [Min(0f)] public float moveSpeed = 5.0f;
    [Min(0f)] public float dashSpeed = 8.0f;
    [Min(0f)] public float acceleration = 20.0f;

    [Header("Jump")]
    [Min(0f)] public float jumpPower = 12.0f;
    [Min(0f)] public float gravityScale = 2.5f;

    [Header("Camera")]
    [Range(0f, 1f)] public float cameraFollowLerp = 0.12f;
}

Create this asset and reference it from a component such as PlayerController.

using UnityEngine;

public sealed class PlayerController : MonoBehaviour
{
    [SerializeField] private PlayerTuning tuning;

    private Vector3 velocity;

    private void Awake()
    {
        if (tuning == null)
        {
            Debug.LogError("PlayerTuning is not assigned.", this);
            enabled = false;
        }
    }

    private void Update()
    {
        float inputX = Input.GetAxisRaw("Horizontal");
        float targetSpeed = inputX * tuning.moveSpeed;

        velocity.x = Mathf.MoveTowards(
            velocity.x,
            targetSpeed,
            tuning.acceleration * Time.deltaTime);

        transform.position += velocity * Time.deltaTime;
    }
}

This separates the player's movement parameters from the controller implementation.

The sample disables the component when tuning is not assigned, preventing a null reference in Update.

The input code uses the old Input Manager's Input.GetAxisRaw only to keep the sample short. Replace it with the Input System or whatever input layer your project uses.

You no longer need to open PlayerController.cs just to change moveSpeed. Select the PlayerTuning asset in the Project window and edit the value in the Inspector.

When tuning values are scattered across source files, developers spend more time finding them. A ScriptableObject gives the team a clear location: "The tuning values for this feature are in this asset."

Shared References Are a Major Advantage

Because a ScriptableObject is an asset, multiple prefabs and components can reference the same instance.

Suppose a scene creates 100 enemy instances. You can store definitions such as "Slime base parameters" and "Goblin base parameters" in ScriptableObject assets instead of copying the same values into every prefab.

In this design, the enemy instance owns its current state while the ScriptableObject owns its definition.

Current HP, current position, status effects, and the current target are runtime state.
Maximum HP, attack power, movement speed, and sight range are definitions or tuning values.

Separating state from definition allows you to change shared parameters in one place.

That ability to share one asset across multiple systems is also what makes ScriptableObject useful for tuning during Play Mode.

Editing During Play Mode Speeds Up Development

The largest practical benefit is how easily ScriptableObject values can be changed and reflected while the game is running.

If PlayerController reads PlayerTuning every frame, changing moveSpeed in the Inspector changes the player's movement speed on the next frame.

This sounds simple, but it has a large impact on gameplay tuning.

A common adjustment loop looks like this:

Change a value in code or on a prefab.
Enter Play Mode.
Test the game.
Exit Play Mode.
Change the value again.
Enter Play Mode again.

When values can be changed and applied during Play Mode, the loop becomes:

Enter Play Mode.
Change values in the Inspector while playing.
Immediately test the result.
Save the values that feel right.

You can keep the current gameplay context instead of restarting it.

This is especially valuable when the situation is expensive to reproduce, such as a specific boss phase, a long encounter, or a point deep inside a stage.

Shorter tuning loops lead to more iterations. In game development, an environment where you can test many variations quickly is often more valuable than trying to guess the perfect value on the first attempt.

Design the Game to Apply Changes Immediately

Changing a ScriptableObject value during Play Mode does nothing unless the game reads or reapplies that value.

For example, the following component copies the value once in Awake.

public sealed class PlayerController : MonoBehaviour
{
    [SerializeField] private PlayerTuning tuning;

    private float moveSpeed;

    private void Awake()
    {
        moveSpeed = tuning.moveSpeed;
    }

    private void Update()
    {
        // Changing tuning.moveSpeed during Play Mode does not update this value.
        Move(moveSpeed);
    }
}

This is not inherently a bad design. Caching can be useful, and some settings should not be recalculated every frame.

However, when Play Mode tuning is important, values that should update immediately must either be read directly from the ScriptableObject or reapplied through a dedicated mechanism.

The simplest option is to read the asset directly:

private void Update()
{
    Move(tuning.moveSpeed);
}

Another option is to cache the value once for builds but reapply it every frame in the Editor.

private void Awake()
{
    // Apply the initial value in both the Editor and player builds.
    ApplyTuning();
}

private void Update()
{
#if UNITY_EDITOR
    // Reapply Play Mode changes every frame in the Editor.
    ApplyTuning();
#endif

    Move(moveSpeed);
}

private void ApplyTuning()
{
    moveSpeed = tuning.moveSpeed;
}

Possible policies include:

Read lightweight values every frame when immediate updates are useful.
Use an Apply button when a value requires expensive recalculation.
Put only the Editor-only reapplication logic behind #if UNITY_EDITOR.

Because this example calls ApplyTuning from Awake, moveSpeed is also initialized in a player build. In the Editor it is reapplied every frame, while a build continues using the cached value from startup.

The final behavior should still be verified under build-equivalent conditions. Editor-only reapplication can hide assumptions that do not exist in the player build.

ScriptableObject alone does not automatically make a system easy to tune. You must also decide when a changed value is applied to the running game.

Make the Save Policy Explicit

Unity's behavior during Play Mode can be confusing.

Values changed on scene GameObjects and MonoBehaviours usually return to their pre-Play Mode state when Play Mode stops.

You may find a good value in the Inspector, stop the game, and then discover that the value has reverted because you forgot to write it down.

ScriptableObject is different because it is an asset.

When you edit the actual ScriptableObject asset selected in the Project window, you are modifying that asset object even during Play Mode. This is not the same as modifying a runtime copy created with Instantiate, and you should not assume the value will automatically revert when Play Mode ends.

The details depend on what is being edited:

A MonoBehaviour on a scene object
The ScriptableObject asset in the Project window
A component referencing the original asset
A runtime copy created with Instantiate
A value modified through SerializedProperty
A field modified directly from code

These cases can look similar in the Inspector while having different persistence behavior.

The following discussion assumes normal Play Mode settings. If your project disables Domain Reload or Scene Reload through Enter Play Mode Options, initialization timing and value lifetime can change. Verify the behavior under your project's settings.

Unity Manual - Configurable Enter Play Mode

It is also important to distinguish between these two states:

The ScriptableObject asset object has changed in the Editor.
The change has been written to the .asset file on disk.

Editing a ScriptableObject in the Project window changes the Editor-side asset object. When the change is committed to disk depends on explicit save operations and the AssetDatabase workflow.

In a team environment, use an explicit save action and inspect the version-control diff instead of relying on whether the value appears to remain after stopping Play Mode.

A workflow such as "adjust runtime values, then press Save only when the result is approved" makes the intent much clearer.

Relying on an asset accidentally remaining dirty after Play Mode is less predictable than providing an explicit save path.

Save Runtime Values Back to a ScriptableObject Asset

The following example adjusts runtime values on a MonoBehaviour and writes the approved values back to a ScriptableObject asset.

This is Unity Editor-only functionality. Code using the UnityEditor namespace must be placed in an Editor folder, guarded by #if UNITY_EDITOR, or compiled in a separate Editor assembly.

The workflow is:

Load initial values from the ScriptableObject asset.
Adjust runtime values during Play Mode.
Press a Save button.
Copy the runtime values to the asset.
Mark the asset dirty.
Save the asset to disk.

EditorUtility.SetDirty marks an object as dirty. AssetDatabase.SaveAssetIfDirty saves a specific asset when it is dirty. Because this article targets Unity 2022.3 LTS and later, the main sample uses SaveAssetIfDirty so that it saves only the target asset.

There is one important difference between these APIs.

SaveAssetIfDirty directly saves the specified asset and does not invoke AssetModificationProcessor.OnWillSaveAssets. If your version-control integration or a custom save hook relies on OnWillSaveAssets, confirm that SaveAssetIfDirty is appropriate for the project.

SaveAssets writes all unsaved asset changes. If a material, prefab, ScriptableObject, or another settings asset is also dirty, it may be saved together with the tuning asset.

For this reason, it is useful to think of these as two separate operations:

Copy runtime values into the target asset.
Flush asset changes to disk.

The target in this example is an existing ScriptableObject asset in the Project window. It is not a temporary object created only through ScriptableObject.CreateInstance.

The save destination is the PlayerTuning asset defined earlier.

The runtime component keeps its editable values separate from the asset:

using UnityEngine;

public sealed class PlayerTuningRuntime : MonoBehaviour
{
    [SerializeField] private PlayerTuning tuningAsset;

    [Min(0f)] public float moveSpeed;
    [Min(0f)] public float dashSpeed;
    [Min(0f)] public float acceleration;
    [Min(0f)] public float jumpPower;
    [Min(0f)] public float gravityScale;
    [Range(0f, 1f)] public float cameraFollowLerp;

    public PlayerTuning TuningAsset => tuningAsset;

    private void Awake()
    {
        if (tuningAsset == null)
        {
            Debug.LogError("PlayerTuning asset is not assigned.", this);
            enabled = false;
            return;
        }

        LoadFromAsset();
    }

    public void LoadFromAsset()
    {
        if (tuningAsset == null)
        {
            Debug.LogWarning("PlayerTuning asset is not assigned.", this);
            return;
        }

        moveSpeed = tuningAsset.moveSpeed;
        dashSpeed = tuningAsset.dashSpeed;
        acceleration = tuningAsset.acceleration;
        jumpPower = tuningAsset.jumpPower;
        gravityScale = tuningAsset.gravityScale;
        cameraFollowLerp = tuningAsset.cameraFollowLerp;
    }
}

The fields are public in this sample so they are easy to edit in the default Inspector.

In a production project, you can replace them with [SerializeField] private fields and properties, a dedicated tuning DTO, or a custom Inspector.

The game reads the runtime values rather than the asset values directly:

using UnityEngine;

public sealed class PlayerController : MonoBehaviour
{
    [SerializeField] private PlayerTuningRuntime tuning;

    private void Awake()
    {
        if (tuning == null || tuning.TuningAsset == null)
        {
            Debug.LogError(
                "PlayerTuningRuntime or its PlayerTuning asset is not assigned.",
                this);

            enabled = false;
        }
    }

    private void Update()
    {
        Move(tuning.moveSpeed);
    }

    private void Move(float speed)
    {
        // Add the actual movement logic here.
    }
}

Now changing PlayerTuningRuntime.moveSpeed in the Inspector immediately affects the running game.

Place the custom Editor in a path such as Assets/Editor/PlayerTuningRuntimeEditor.cs.

using UnityEditor;
using UnityEngine;

[CustomEditor(typeof(PlayerTuningRuntime))]
public sealed class PlayerTuningRuntimeEditor : Editor
{
    public override void OnInspectorGUI()
    {
        DrawDefaultInspector();

        var runtime = (PlayerTuningRuntime)target;
        var asset = runtime.TuningAsset;

        EditorGUILayout.Space();

        using (new EditorGUI.DisabledScope(
            asset == null || !EditorApplication.isPlaying))
        {
            if (GUILayout.Button("Load From ScriptableObject"))
            {
                Undo.RecordObject(
                    runtime,
                    "Load Player Tuning From Asset");

                runtime.LoadFromAsset();
            }

            if (GUILayout.Button(
                "Save Runtime Values To ScriptableObject"))
            {
                SaveToAsset(runtime, asset);
            }
        }
    }

    private static void SaveToAsset(
        PlayerTuningRuntime runtime,
        PlayerTuning asset)
    {
        Undo.RecordObject(asset, "Save Player Tuning");

        asset.moveSpeed = Mathf.Max(0f, runtime.moveSpeed);
        asset.dashSpeed = Mathf.Max(0f, runtime.dashSpeed);
        asset.acceleration = Mathf.Max(0f, runtime.acceleration);
        asset.jumpPower = Mathf.Max(0f, runtime.jumpPower);
        asset.gravityScale = Mathf.Max(0f, runtime.gravityScale);
        asset.cameraFollowLerp =
            Mathf.Clamp01(runtime.cameraFollowLerp);

        EditorUtility.SetDirty(asset);
        AssetDatabase.SaveAssetIfDirty(asset);
    }
}

The buttons are enabled only during Play Mode.

Pressing Save copies the runtime values to the PlayerTuning asset, marks the asset dirty, and saves that specific asset to disk through SaveAssetIfDirty.

After Play Mode stops, the saved values remain in the .asset file.

The sample also clamps values before saving them.

Attributes such as [Min] and [Range] are useful Inspector aids, but they do not guarantee that code or debug tooling cannot assign an invalid value.

A production validation layer should also consider relationships between values, units, and upper bounds. For example:

dashSpeed should be greater than or equal to moveSpeed.
jumpPower and gravityScale should produce a valid jump curve.
Camera interpolation values should stay within a project-defined range.
Values that affect physics should use consistent units.

If project-specific version-control integration or save hooks require AssetDatabase.SaveAssets, document that it can save every dirty asset, not only the tuning asset.

The Save timing is explicit, so you can experiment freely and commit only values that you have approved.

This sample intentionally targets Play Mode tuning. If the same custom Editor must also support Edit Mode or prefab-instance editing, account for SerializedObject, SerializedProperty, prefab overrides, scene dirty state, and the relevant Undo behavior.

There is another maintenance trade-off in this example.

The same field list appears in PlayerTuning, PlayerTuningRuntime, LoadFromAsset, and SaveToAsset. Adding a new parameter requires updating every related location.

Treat this synchronization as reviewable code, or consider a shared synchronization method, generic copying through SerializedObject, or source generation when the parameter set becomes large.

Undo.RecordObject during Play Mode should also be treated as a convenience for the current Play session. Do not assume that the Undo stack will remain useful after leaving Play Mode. Verify saved values through the version-control diff and revert them there when necessary.

Directly Editing the ScriptableObject Asset

The previous workflow keeps experimental values on a MonoBehaviour and copies them to the ScriptableObject only when Save is pressed.

A simpler alternative is to select the ScriptableObject asset and edit it directly during Play Mode.

public sealed class PlayerController : MonoBehaviour
{
    [SerializeField] private PlayerTuning tuning;

    private void Update()
    {
        Move(tuning.moveSpeed);
    }
}

Select the PlayerTuning asset in the Project window and change moveSpeed while the game is running.

If PlayerController reads tuning.moveSpeed every frame, the new value is applied immediately.

This method is convenient, but you are editing the original project asset during Play Mode. Treat the Editor-side asset change and the on-disk save as separate concerns, and use explicit save or discard actions together with version-control diffs.

A runtime copy created with Instantiate does not write back to the original asset. Editing the original asset does.

That means an extreme debug value can remain in the project or accidentally appear in a commit.

A practical comparison looks like this:

Approach	Good fit	Main concern
Edit the ScriptableObject asset directly	Small teams, local experimentation, simple settings	You are modifying the original asset, so save explicitly and inspect the version-control diff
Tune runtime values and save them with a button	Team development and safer experimentation	Requires a small Editor extension
Create a runtime copy of the ScriptableObject	Keep the original asset untouched during testing	Requires an explicit copy-back step when saving

For gameplay feel, I generally prefer "edit runtime values, then press Save when the result is good."

As the team grows, explicit persistence usually causes fewer accidents than implicit asset changes.

How This Differs from Saving MonoBehaviour `[SerializeField]` Values

A MonoBehaviour can also contain [SerializeField] values that are edited during Play Mode and written somewhere through a Save button.

However, values on a scene MonoBehaviour normally revert when Play Mode stops.

To preserve them, you must copy the values before stopping into a persistent destination such as:

A prefab
A ScriptableObject
An external file
Another Editor-managed asset

This pattern is useful for scene-specific data such as stage gimmicks, Timeline-driven sequences, or camera choreography.

When the same values must be shared by multiple scenes or prefabs, keeping them on a MonoBehaviour can become difficult to manage.

Neither approach is universally better.

Use a MonoBehaviour for scene-specific values.
Use a ScriptableObject for definitions shared by multiple scenes, prefabs, or systems.

Player movement feel, weapon recoil, enemy-type parameters, and global difficulty multipliers are often natural ScriptableObject candidates.

A camera sequence unique to one stage may be more naturally stored on a MonoBehaviour or Timeline.

The useful distinction is responsibility, not which type is "superior."

Data That Fits ScriptableObject Well

ScriptableObject is especially useful for data that developers want to inspect and tune inside the Unity Editor.

Examples include:

Player controls
Camera following
Camera shake
Base parameters per enemy type
Small to medium weapon or skill data
UI animation settings
Difficulty multipliers
Debug balance settings

It is particularly strong when the data naturally references Unity assets.

Sprite, prefab, AudioClip, AnimationClip, AnimationCurve, and Gradient references can be assigned directly in the Inspector.

[CreateAssetMenu(
    fileName = "WeaponData",
    menuName = "Game/Master/Weapon Data")]
public sealed class WeaponData : ScriptableObject
{
    public int weaponId;
    public string displayName;
    public int attack;
    public float coolTime;

    public Sprite icon;
    public GameObject hitEffectPrefab;
    public AudioClip attackSe;
}

With Excel or CSV, those references usually need to be represented through a path, GUID, Addressables key, or another project-specific identifier.

For settings that include gameplay feel and Unity-asset references, the clarity of ScriptableObject can directly improve development speed.

Do Not Force Every Data Set into ScriptableObject

ScriptableObject is useful, but it becomes awkward when every large table is represented as ScriptableObject assets.

Examples include:

Items
Skills
Quests
Rewards
Shops
Gacha data
Progression tables
Localization text

At some point, planners may want to edit thousands of rows in Excel or Google Sheets. The project may also need ID lookup, composite keys, range queries, reference validation, and CI checks.

At that scale, common problems include:

Too many assets
Poor overview of the full table
Noisy version-control diffs
Conflicts during simultaneous editing
Difficult bulk validation
Custom lookup dictionaries scattered through the project

Do not reduce the design to "ScriptableObject or Excel" or "ScriptableObject or MasterMemory."

A hybrid approach is often better.

For example:

Player movement, camera shake, hit-stop, and presentation values stay in ScriptableObject assets.
Thousands of item rows, localization records, progression tables, and reward tables are managed in Excel or Google Sheets and converted for runtime use.

ScriptableObject should not be treated as a temporary solution that only belongs at the beginning of a project.

As a gameplay-tuning layer, it can remain useful late into production.

Practical ScriptableObject Pitfalls

1. Do Not Put Too Much Runtime State in Shared Assets

A ScriptableObject is shared by reference.

That is useful for definitions, but dangerous for per-instance state.

For example, storing the enemy's current HP in a shared EnemyParameter asset causes every enemy referencing that asset to share the same current HP.

public sealed class EnemyParameter : ScriptableObject
{
    public int maxHp;

    // Dangerous: this is runtime state, not a shared definition.
    public int currentHp;
}

Current HP, current position, status effects, and the active target belong on the enemy instance or in a dedicated runtime-state object.

ScriptableObject is safest when it contains definitions, tuning values, and shared settings.

2. Be Conscious of Dirtying Project Assets

Editing a ScriptableObject asset in the Editor marks the asset dirty.

Decide whether the team edits the original asset directly or works on runtime values and writes them back only through an explicit Save button.

The latter requires more tooling, but it makes the decision to persist a change clear.

3. Keep Editor Code Out of Player Builds

Code that uses UnityEditor cannot be included in a player build.

Place Editor extensions in an Editor folder or guard them with #if UNITY_EDITOR.

Assets/
  Scripts/
    Runtime/
      PlayerTuning.cs
      PlayerTuningRuntime.cs
      PlayerController.cs
    Editor/
      PlayerTuningRuntimeEditor.cs

When using assembly definitions, separating the Runtime and Editor assemblies is even safer.

4. Make the Save Target Obvious

A Save button should clearly state what it saves and where the data goes.

A button named only Save could refer to a scene, prefab, ScriptableObject, or external file.

A longer label such as Save Runtime Values To ScriptableObject is safer because its purpose is explicit.

When MasterMemory Becomes a Better Fit

A different system becomes worth considering when the project needs:

Large tables edited in Excel or Google Sheets
Frequent ID or composite-key lookup
CI validation of references and data constraints
Lower parsing cost and fewer runtime allocations
A type-safe, read-only runtime database

This is not a competition between tools.

ScriptableObject is excellent for accelerating gameplay tuning. MasterMemory is designed for large, read-only master-data sets that need fast, type-safe queries.

In the next article, I will examine what MasterMemory solves, what it does not solve, and where it fits in a practical Unity data pipeline.

Conclusion

ScriptableObject is more than a container for static data.

Its practical strengths are that it is visible in the Unity Editor, can be shared as an asset, and can feed changes into a running game during Play Mode.

Movement speed, jump force, camera interpolation, enemy attack intervals, hit-stop, camera shake, and UI timing are often faster to tune while playing than through repeated code edits and restarts.

A small Editor extension can add an explicit Save button so that approved runtime values are written back to a ScriptableObject asset.

When implementing that workflow, use APIs such as Undo.RecordObject, EditorUtility.SetDirty, and AssetDatabase.SaveAssetIfDirty, and keep the Editor-only code out of player builds.

At the same time, do not force large tabular data, localization, composite-key queries, CI validation, and spreadsheet integration into ScriptableObject.

Use each tool for the job it handles best.

ScriptableObject is a powerful way to shorten the gameplay-tuning loop. Used in its natural role, it can make Unity data management and iteration considerably easier.

Unity Save Data Writing Tips: Make Local Saves Harder to Break and Easier to Recover

GameDevToolLab — Tue, 14 Jul 2026 08:38:24 +0000

Introduction

If you only need to save a few small settings in Unity, PlayerPrefs is usually the natural first option.

For example, saving volume and vibration settings can be as simple as this:

PlayerPrefs.SetFloat("option.masterVolume", currentMasterVolume);
PlayerPrefs.SetInt("option.vibration", currentVibration ? 1 : 0);
PlayerPrefs.Save();

var loadedMasterVolume = PlayerPrefs.GetFloat("option.masterVolume", 1.0f);
var loadedVibration = PlayerPrefs.GetInt("option.vibration", 1) != 0;

For prototypes, or for a small number of independent option values, this is often enough.

However, PlayerPrefs.Save() is not something you should call for every frequent input event, such as every OnValueChanged call from a slider.
It is better to call it when the value is confirmed: when the user presses OK, closes the options screen, or when the app is about to pause as a final safeguard.

First, decide whether PlayerPrefs is enough for the data you are saving.

In a released game, save data tends to grow over time.
What started as only a volume setting may later include language, display settings, tutorial progress, read flags, and other state.
Once that happens, PlayerPrefs becomes awkward for consistency, migration, and recovery.

The next common option is to write a JSON file under Application.persistentDataPath.

var json = JsonUtility.ToJson(saveData);
var path = Path.Combine(Application.persistentDataPath, "save.json");
File.WriteAllText(path, json);

But "convert it to JSON and write it" is not the end of the story.
There are several quiet traps: quit-time saves may not run, the app may be killed during a write, failed loads may accidentally overwrite recoverable data with defaults, and multiple save paths may overwrite newer data with older data.

Save data is not flashy, but when it breaks, the user experience is awful.
Even small data, such as volume or language settings, becomes frustrating if it resets every time.

This article collects practical notes for writing local saves and option settings in Unity.

This is not an article about creating a save system that can never break.
The goal is to reduce the chance of save failure, and to make recovery easier when failure does happen.

The main target is mobile Unity projects, including Android.
That said, most of the ideas apply to PC builds as well.

Scope of this article

This article focuses on lightweight local data such as option settings, tutorial progress, simple local save data, and cache metadata.

It does not cover full anti-cheat design, server synchronization, guarantees for paid items or currency, cloud save conflict resolution, or large custom binary formats.

In this article, "safe" mainly means the following:

Make files less likely to break during writes
Avoid relying too much on app quit events
Make failed loads easier to recover from
Avoid accidental overwrites caused by implementation mistakes

Once data is stored locally, you should assume the user can access or modify it.
Important currency, paid items, rankings, and values that affect competitive play should not trust local saves as the source of truth.

Keep PlayerPrefs for small use cases

PlayerPrefs is not a bad API.
For small settings, it is convenient and often the right tool.

It can be fine for values such as master volume, vibration, graphics preset, last selected language, or a simple "tutorial already shown" flag.

The decision should be based on operational requirements, not only on the item name.
A single language setting can be fine in PlayerPrefs.
But if you need to manage language together with other settings, progress, read flags, migration, and recovery, it is safer to move that state into a JSON file.

PlayerPrefs stores values by key.
It is not a great fit when you want to treat multiple values as one coherent save file.
It also makes it harder to express requirements such as:

Migrate based on a save version
Recover from a .bak file
Avoid overwriting immediately when a load fails
Keep broken files for investigation

Also, this is not specific to PlayerPrefs: local data should be treated as user-editable.
Do not use PlayerPrefs alone as the source of truth for paid items, currency, rankings, or values that affect multiplayer or competitive results.

A practical split is:

Use PlayerPrefs for a small number of independent settings
Use JSON files for grouped state, migrated state, or data that should be recoverable

From here on, we will assume that the data has grown beyond what should live in PlayerPrefs, and that we are saving JSON files under persistentDataPath.
First, let us look at the simplest direct file write approach many projects start with.

Use persistentDataPath as the default location

When you need to save data created at runtime in Unity, Application.persistentDataPath is usually the first place to consider.
Unity describes it as a directory for data that should persist across app launches.

using System.IO;
using UnityEngine;

public static class SaveFiles
{
    public static string OptionsPath =>
        Path.Combine(Application.persistentDataPath, "options.json");

    public static string ProgressPath =>
        Path.Combine(Application.persistentDataPath, "progress.json");
}

However, persistentDataPath does not mean "this data can never disappear".

With a normal app update, data is expected to remain as long as the bundle identifier stays the same.
But data may be lost if the bundle identifier changes, the app is uninstalled, the user clears app data, a backup is restored, or the storage state changes.

So loading code should treat "the file does not exist" as a normal case.

if (!File.Exists(path))
{
    return CreateDefaultOptions();
}

In some cases, local code cannot tell whether this is the first launch or whether the user deleted the data.
For important data, you need to think about consistency with server-side data or cloud saves as well.

JSON is convenient, but use a save DTO

For lightweight data, JSON is easy to inspect and debug.
For small data such as option settings, Unity's JsonUtility is often enough.

For example, option settings can be represented like this:

using System;

[Serializable]
public sealed class OptionSaveData
{
    public int version = 1;
    public float masterVolume = 1.0f;
    public float bgmVolume = 1.0f;
    public float seVolume = 1.0f;
    public string language = "ja";
    public bool vibration = true;
}

var json = JsonUtility.ToJson(optionData, prettyPrint: true);
File.WriteAllText(SaveFiles.OptionsPath, json);

Because JsonUtility uses Unity's serializer, keep these practical constraints in mind:

Add [Serializable]
Prefer fields for saved values
Avoid property-centered save classes
Dictionaries, complex types, and top-level arrays are awkward
Prepare migration when deleting or renaming fields
Add a version field from the beginning

A property-centered class like this is not a good save DTO for JsonUtility:

[Serializable]
public sealed class BadOptionData
{
    public float MasterVolume { get; set; } = 1.0f;
    public float BgmVolume { get; set; } = 1.0f;
}

The class you use inside the game and the DTO you serialize do not have to be the same class.
Trying to force them to be one class often makes future changes harder.

Do not write directly; write to a temp file and replace

File.WriteAllText is convenient, but direct overwriting is scary for existing save files.

File.WriteAllText(path, json);

If the app crashes during the write, the device loses power, or the OS kills the process, a partially written file may remain.

For example, you may end up with broken JSON like this:

{
  "version": 1,
  "masterVolume": 0.8,
  "bgmVolume":

On the next launch, loading fails.
If the failure path is careless, the game may write default data immediately and destroy any chance of recovery.

A common improvement is to write to a temporary file first, then replace the main file.

The basic flow is:

Write the new contents to save.json.tmp
Flush the written contents
Move the existing save.json to save.json.bak
Move save.json.tmp to save.json
Delete .bak after success

Android has an AtomicFile API based on a similar idea: write first, then commit by renaming.
The Unity C# sample below does not provide the same guarantees, but the idea is useful.

The following is a minimal explanatory sample.
This is not an "atomic save" implementation.
It is a best-effort approach that improves recoverability.
In production, centralize the save entry point and serialize writes to the same path.
Fixed .tmp and .bak names are also vulnerable to leftover files from previous failures and concurrent saves.

using System;
using System.IO;
using System.Text;

public static class SafeFileWriter
{
    public static void WriteAllText(string path, string contents)
    {
        // Explanatory sample.
        // Do not call this concurrently for the same path.
        // The caller should serialize writes and combine this with startup recovery.
        var directory = Path.GetDirectoryName(path);
        if (string.IsNullOrEmpty(directory))
        {
            throw new ArgumentException("Invalid path.", nameof(path));
        }

        Directory.CreateDirectory(directory);

        var tempPath = path + ".tmp";
        var backupPath = path + ".bak";

        WriteTemp(tempPath, contents);

        try
        {
            if (File.Exists(backupPath))
            {
                File.Delete(backupPath);
            }

            if (File.Exists(path))
            {
                File.Move(path, backupPath);
            }

            File.Move(tempPath, path);

            if (File.Exists(backupPath))
            {
                File.Delete(backupPath);
            }
        }
        catch
        {
            TryRestore(path, backupPath);
            throw;
        }
    }

    private static void WriteTemp(string tempPath, string contents)
    {
        var bytes = Encoding.UTF8.GetBytes(contents);

        using var stream = new FileStream(
            tempPath,
            FileMode.Create,
            FileAccess.Write,
            FileShare.None);

        stream.Write(bytes, 0, bytes.Length);
        stream.Flush(flushToDisk: true);
    }

    private static void TryRestore(string path, string backupPath)
    {
        try
        {
            if (!File.Exists(path) && File.Exists(backupPath))
            {
                File.Move(backupPath, path);
            }
        }
        catch
        {
        }
    }
}

This sample does not guarantee a fully atomic replace on every platform.
Because it uses fixed .tmp and .bak names, avoid parallel saves to the same file and use it together with a centralized save entry point or per-path serialization.
There is a moment during replacement where the main file may temporarily not exist, so startup recovery is also required.
Flush(flushToDisk: true) helps flush file contents, but it does not magically make directory entries after rename fully crash-proof.

If your target environment supports it, File.Replace(tempPath, path, backupPath) can be another option.
However, you should verify runtime support, OS behavior, and exception behavior on your actual Unity target platforms.

The important point is to create the temp file in the same directory as the main file.
If you cross drives, mounts, or directories, a rename may behave more like a copy, which can reduce safety.

Recover from tmp and bak on startup

If you use temp-file replacement, also prepare startup recovery.

If the previous save failed halfway, you may find files like these:

save.json
save.json.tmp
save.json.bak

A simple policy is enough for many projects:

If the main file can be read, use it
If the main file cannot be read but the backup can be read, use the backup
Basically delete the temp file
If recovery succeeds, rewrite the main file if possible

In this sample, .tmp is not treated as a committed save result.
The design prioritizes consistency over latestness.
If you want to recover from .tmp as a possible latest save, design extra metadata such as generation numbers, checksums, or commit markers.

public OptionSaveData Load()
{
    var path = SaveFiles.OptionsPath;
    var tempPath = path + ".tmp";
    var backupPath = path + ".bak";

    TryDelete(tempPath);

    if (TryLoad(path, out var data))
    {
        Normalize(data);
        return data;
    }

    if (TryLoad(backupPath, out data))
    {
        Normalize(data);
        TrySaveRecoveredData(data); // Best-effort rewrite
        return data;
    }

    return new OptionSaveData();
}

private void TrySaveRecoveredData(OptionSaveData data)
{
    try
    {
        Save(data);
    }
    catch (Exception e)
    {
        Debug.LogWarning($"Recovered save data, but failed to rewrite main file.\n{e}");
        // Treat the load itself as successful.
        // If needed, mark the data dirty and retry later.
    }
}

The key point is: do not overwrite with default data the moment loading fails.
Returning defaults may be fine, but saving them immediately can overwrite a broken main file or backup and remove any chance of investigation or recovery.

If the backup can be loaded, start the game with that data first.
Rewriting the main file should be best effort.

So far, we have looked at where to save, what format to use, and how to write.
Next is when to save.

Do not trust app-quit saves too much

A common save design is to write everything when the app quits.

private void OnApplicationQuit()
{
    Save();
}

This may be acceptable for small PC tools, but it should not be your main strategy on mobile.

Unity's Application.quitting documentation notes that Android does not detect quitting when the app is paused.
It recommends using OnApplicationFocus(bool) or OnApplicationPause(bool) instead for those cases.
The OnApplicationQuit documentation also notes that on iOS, applications are usually suspended instead of quit, and suggests using OnApplicationPause for suspension and cleanup.

In other words, "save when the app quits" is a weak assumption on mobile.

Users do not always explicitly quit the app.
They press Home, switch apps, receive phone calls, get killed by the OS, or hit a crash.

This kind of design is risky:

public void SetMasterVolume(float volume)
{
    _data.masterVolume = volume;
}

private void OnApplicationQuit()
{
    Save();
}

The user changes the volume, but the value is only written when the app quits.
If the app is killed before that, or the quit event never arrives, the change is lost.

Treat quit-time saving as the last safety net, not the main save timing.

Save option settings at confirmation points

Option settings such as volume, language, vibration, and graphics quality have clear save timing.
Instead of saving every time a slider moves, update the UI immediately and save when the user presses OK, applies the change, or closes the screen.
This also makes the design easier to extend later if saves become asynchronous or tied to cloud sync.

public sealed class OptionController
{
    private readonly OptionSaveData _current;
    private readonly OptionSaveData _editing;
    private readonly OptionSaveService _saveService;

    public void SetMasterVolume(float value)
    {
        _editing.masterVolume = value;
        AudioListener.volume = value; // Apply immediately
    }

    public void Apply()
    {
        Copy(_editing, _current);
        _saveService.Save(_current);
    }

    public void Cancel()
    {
        Copy(_current, _editing);
        AudioListener.volume = _current.masterVolume;
    }
}

When canceling, restore not only the visible UI or audio output, but also the editing data.
If _editing keeps the changed value, it may be saved later when the screen is opened again or when another option is applied.

With this structure, OK saves, Cancel discards, and leaving the screen can also be made into a clear save point.

If you choose to save immediately when a value changes, it is still often better to debounce the request.
For example, save after 0.5 seconds without further slider movement.

You do not have to make the first version complex.
Saving when the options screen closes, or when the user presses OK, is already much safer than relying on app quit.

Save progress at meaningful milestones

Game progress should also avoid relying only on app quit.

Choose save points based on where the player would be unhappy to be rolled back.

Examples:

Data	Save timing example
Tutorial progress	When each step is completed
Stage progress	Clear, checkpoint
Inventory item	When acquisition or consumption is confirmed
Shop purchase	When purchase is confirmed
Quest reward	When reward is received
Option setting	OK, Apply, screen close

If the stage clear animation plays, the player quits, and the next launch treats the stage as uncleared, that feels terrible.
On the other hand, saving every enemy position and projectile state every frame is usually unnecessary.

Define how far rollback is acceptable, and save at that boundary.

Use OnApplicationPause as a safeguard

On mobile, it is common to save when the app moves to the background using OnApplicationPause(true) or OnApplicationFocus(false).

This is useful.
But it should not be the only save timing.

private void OnApplicationPause(bool pause)
{
    if (pause)
    {
        SaveIfDirty();
    }
}

private void OnApplicationFocus(bool focus)
{
    if (!focus)
    {
        SaveIfDirty();
    }
}

Normally, save at user actions and game milestones first.
Then, when the app is about to move to the background, save any remaining dirty data.

Keep background-transition work as light as possible:

Save data that already exists in memory
Write small JSON files
Save only when dirty
Treat network sync separately

Doing huge JSON generation, compression, encryption, file writes, and cloud sync all at the last moment is risky.
It is usually better to treat cloud or server saves as a separate system from local saves.

Write loading code as if failure is normal

No matter how carefully you write saves, you cannot make corruption impossible.
Crashes during writes, low storage, user deletion, migration bugs, and manual editing can all break files.
So loading code should assume failure is normal.

public static bool TryLoad<T>(string path, out T data) where T : class
{
    data = null;

    if (!File.Exists(path))
    {
        return false;
    }

    try
    {
        var json = File.ReadAllText(path);
        if (string.IsNullOrWhiteSpace(json))
        {
            return false;
        }

        data = JsonUtility.FromJson<T>(json);
        return data != null;
    }
    catch (Exception e)
    {
        Debug.LogWarning($"Failed to load json: {path}\n{e}");
        return false;
    }
}

This TryLoad only checks whether the file can be read as JSON.
In a real load flow, treat the following as one pipeline:

Check whether the file exists
Parse JSON
Check version
Migrate old versions
Normalize and validate values
Decide what to do with future versions or validation failures

Even successfully loaded data may not be valid.
A volume value could be -999, a language code could be empty, the version could be missing, or an array could be unexpectedly huge.
Normalize values after loading.

private static void Normalize(OptionSaveData data)
{
    data.version = Mathf.Max(1, data.version);
    data.masterVolume = Mathf.Clamp01(data.masterVolume);
    data.bgmVolume = Mathf.Clamp01(data.bgmVolume);
    data.seVolume = Mathf.Clamp01(data.seVolume);

    if (string.IsNullOrEmpty(data.language))
    {
        data.language = "ja";
    }
}

It is safer to treat save files almost like external input, even if your own app created them.

Add a version field from the beginning

I recommend adding a version field to save data from the start.

At first it feels unnecessary.
But once the app is released and the save format changes, you will almost certainly want it.

For example, an early version might have only one volume field, and later you may want separate masterVolume, bgmVolume, and seVolume fields.

Without a version, you need to infer which format a file uses.
Inference is possible, but annoying and error-prone.

private const int CurrentSaveVersion = 2;

public static OptionSaveData Migrate(OptionSaveData data)
{
    if (data.version > CurrentSaveVersion)
    {
        throw new InvalidOperationException($"Unsupported save version: {data.version}");
    }

    if (data.version <= 0)
    {
        data.version = 1;
    }

    if (data.version == 1)
    {
        // v1 -> v2 migration
        data.version = 2;
    }

    return data;
}

Also decide how to handle future versions.
For example, if a user saves data with a newer app and then rolls back to an older app, the old app will see an unknown format.
Immediately overwriting it with default data is dangerous.
Depending on the project, you may stop loading and show a warning, read only compatible fields, or ask the user to update the app.

Even if you throw an exception for future versions, connect that failure to backup handling, logging, user notification, or retry logic rather than blindly overwriting with defaults.

For more complex save data, you may prepare old DTOs and migrate step by step.
Even for option settings, having a version field from day one often helps later.

Split files by lifecycle

Save data should not always be one huge JSON file.

Option settings and game progress often have different lifecycles, so splitting them can make the system easier to manage.
If game progress breaks, you do not want volume or language settings to break with it.
If only options change frequently, you also avoid rewriting all progress data every time.

A useful guideline is to split by lifecycle.

File	Contents	Save frequency
`options.json`	Volume, language, vibration	When settings change
`profile.json`	Name, avatar, basic profile settings	When changed
`progress.json`	Stage progress, unlock state	At milestones
`cache_meta.json`	Cache metadata	When needed

But do not split too much.

If two pieces of data must be updated together, keep them in the same file or design transaction-like handling.
For example, if item consumption and stage unlock live in separate files and only one save succeeds, you may create inconsistent data.
That is a sign the design needs another look.

Do not let multiple places save the same file

A common save bug is allowing multiple classes to directly write the same file.

1. A saves newer data
2. B saves older data it had from earlier
3. A's change disappears

This is not a file I/O problem.
It is a design problem.

The fix is to centralize the save entry point.

public sealed class SaveRepository
{
    private SaveData _current;

    public void Update(Action<SaveData> update)
    {
        update(_current);
        SaveInternal(_current);
    }
}

In Unity, much of your logic may run on the main thread, so you may not always need a lock.
Still, centralizing "update save data and write it" is important.

If save logic is scattered everywhere, it becomes hard to know what data is saved and when.
This is often underestimated in small projects, but fixing it later is painful.

Use a dirty flag

A dirty flag is useful for controlling save frequency.

public sealed class OptionStore
{
    private OptionSaveData _data;
    private bool _dirty;

    public void SetMasterVolume(float value)
    {
        if (Mathf.Approximately(_data.masterVolume, value))
        {
            return;
        }

        _data.masterVolume = value;
        _dirty = true;
    }

    public void SaveIfDirty()
    {
        if (!_dirty)
        {
            return;
        }

        try
        {
            Save();
            _dirty = false;
        }
        catch (Exception e)
        {
            Debug.LogError(e);
            _dirty = true;
        }
    }
}

With a dirty flag, callers can freely call SaveIfDirty() during screen transitions or OnApplicationPause.
If nothing changed, nothing happens.
The caller does not need to know the details.

This is a minimal synchronous-save example.
If you extend it to asynchronous saves, use an in-progress flag, revision number, or save queue so an old save completion does not clear a newer dirty state.

Depending on platform and Unity version, OnApplicationPause and OnApplicationFocus may both be called or may occur close together.
Make repeated save requests safe by combining dirty flags with centralized, serialized save entry points.

One important detail: do not clear dirty when saving fails.
If you clear it after a failure, memory may contain changed data while the file still contains old data.

Do not make saving too heavy

For small JSON files, saving on the main thread is often fine.

But as save data grows, the cost can become noticeable.

Potentially expensive steps include:

JSON string generation
String allocation
UTF-8 conversion
Compression
Encryption
File writing
Flush

If too many of these happen at once, you may cause frame drops or a short freeze.

Moving heavy work to a background thread can help.
However, code that touches UnityEngine.Object is generally expected to run on the main thread.
First copy the required data into a save DTO, then decide how much of the remaining work can run off the main thread.

The following is a minimal example that mainly moves file writing to a background thread.
JsonUtility.ToJson runs before Task.Run, so this sample does not avoid frame drops caused by heavy JSON generation.
If JSON generation itself is heavy, copy the data into a DTO that does not touch Unity APIs or UnityEngine.Object, then consider moving JSON generation and file writing into the same background operation.

// Minimal explanatory sample.
// In this example, JsonUtility.ToJson runs on the main thread.
// In production, serialize save requests to the same file,
// or control the system so only the latest snapshot is committed.
public async Task SaveAsync(OptionSaveData data)
{
    var snapshot = Clone(data); // Copy to a save DTO that does not touch UnityEngine.Object
    var json = JsonUtility.ToJson(snapshot, prettyPrint: false);
    var path = SaveFiles.OptionsPath;

    await Task.Run(() =>
    {
        SafeFileWriter.WriteAllText(path, json);
    });
}

Once saving becomes asynchronous, completion order can reverse.
A newer save with volume 0.8 may finish first, then an older save with volume 0.5 may finish later and overwrite it.
Avoid this by serializing saves, or by designing the system so only the latest snapshot is written.

You do not have to make everything asynchronous from the start.
For option settings, synchronous saving is often enough.

Separate encryption and tamper detection from durability

When saving JSON, the contents are visible, so it is natural to consider encryption or tamper detection.
But local encryption only makes casual inspection or editing harder.
It is not complete anti-cheat.
Important currency, paid items, rankings, and values that affect competitive play should be validated on the server side.

Durability and anti-cheat are different goals.
First prioritize save timing, corruption handling, recovery, versions, and normalization.
Then add encryption or tamper detection if the project needs it.

Test cases to cover

Save systems often look fine during normal play.
You should intentionally break them during testing.

At minimum, test these cases:

First launch with no save file
Valid JSON can be loaded
Empty file does not crash the app
Broken JSON does not crash the app
Old-version JSON can be loaded
Strange values are normalized
App can start even if .tmp remains
A valid-looking .tmp is still discarded if that is the design
If the main file is valid and an old .bak remains, the main file is used
Recovery from .bak works
App can start even if .bak loads but rewriting the main file fails
Repeated or simultaneous saves do not overwrite newer data with older data
App can start after an exception during save
If possible, test near-low-storage conditions
On Android, test Home, app switching, and task kill
Confirm data remains after app update

Android in particular can behave differently depending on device and OS settings.
Do not assume that working in the Editor is enough.

Also decide what to do when saving fails.
User notification, retry, returning to title, or server resync are gameplay and product decisions, not only engineering details.

Summary

The first step of Unity save data is simple.
For small settings, PlayerPrefs works.
For grouped data, JsonUtility.ToJson plus persistentDataPath can also work.

But in a released game, issues appear: quit-time saves may not run, files may break during writes, failed loads may overwrite recoverable data with defaults, and old data may overwrite newer data.

On mobile especially, do not rely too much on saving only when the app quits.

A practical policy is:

Keep PlayerPrefs for small settings and simple flags
Call PlayerPrefs.Save() at confirmation points
Save options and game progress at points where rollback would feel bad
Avoid direct overwrite; replace via a temp file
Prepare recovery from .tmp and .bak
Do not overwrite immediately with defaults when loading fails
Use version and Normalize to absorb old data and strange values
Centralize save entry points and avoid parallel saves to the same file

Local saving is easy to overlook, but painful when it fails.
Separate the range where PlayerPrefs is enough from the range where JSON files are better, and design save timing, corruption handling, and recovery together.

References

Unity Scripting API: PlayerPrefs.Save: https://docs.unity3d.com/ScriptReference/PlayerPrefs.Save.html
Unity Scripting API: Application.persistentDataPath: https://docs.unity3d.com/ScriptReference/Application-persistentDataPath.html
Unity Scripting API: JsonUtility: https://docs.unity3d.com/ScriptReference/JsonUtility.html
Unity Scripting API: Application.quitting: https://docs.unity3d.com/ScriptReference/Application-quitting.html
Unity Scripting API: MonoBehaviour.OnApplicationQuit: https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnApplicationQuit.html
Unity Scripting API: MonoBehaviour.OnApplicationPause: https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnApplicationPause.html
Unity Scripting API: MonoBehaviour.OnApplicationFocus: https://docs.unity3d.com/ScriptReference/MonoBehaviour.OnApplicationFocus.html
Android API reference: AtomicFile: https://developer.android.com/reference/android/util/AtomicFile

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

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

Introduction

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

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

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

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

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

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

The three rules to take away are:

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

Use SubscribeAwait for repeated-click protection

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

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

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

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

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

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

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

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

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

A simple team rule can start like this:

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

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

Repeated-click protection and simultaneous-input protection are different

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

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

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

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

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

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

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

private enum DialogAction
{
    Ok,
    Cancel
}

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

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

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

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

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

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

private bool _closed;

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

    _closed = true;
    SetButtonsInteractable(false);

    await ExecuteAsync(action, ct);
}

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

private bool _isProcessing;

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

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

    try
    {
        SetButtonsInteractable(false);

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

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

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

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

A useful way to separate responsibilities is this:

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

A good team rule is:

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

Do not overuse EveryUpdate

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

A bad example:

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

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

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

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

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

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

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

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

A practical rule:

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

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

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

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

Be explicit about TimeProvider and FrameProvider

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

Use Timer or Interval when waiting by time.

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

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

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

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

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

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

Use Observable Tracker for review and investigation

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

When a team first introduces R3, common problems include:

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

Observable Tracker is useful for investigating these problems.

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

Do not let R3 leak too deeply into domain logic

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

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

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

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

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

Use R3 to notify the result.

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

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

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

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

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

The basic policy is:

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

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

Split complex chains

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

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

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

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

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

var sortedItems = visibleItems
    .Select(SortItems);

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

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

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

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

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

Do not overuse ToObservable

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

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

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

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

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

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

Do not rely on AddTo(this) for every lifetime

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

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

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

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

private DisposableBag _tabDisposables;

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

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

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

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

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

private DisposableBag _bindDisposables;

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

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

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

How to think about OnErrorResume

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

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

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

            Debug.LogException(ex);

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

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

In production code, decide these rules:

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

Patterns to avoid

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

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

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

Team operation rules

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

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

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

Adoption scope

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

A practical adoption order is:

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

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

Notes for migrating from UniRx

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

Important points include:

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

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

Recommended practical structure

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

Model

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

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

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

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

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

ViewModel / Presenter

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

private DisposableBag _disposables;
private ReadOnlyReactiveProperty<bool> _canDecide;

public ReadOnlyReactiveProperty<bool> CanDecide => _canDecide;

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

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

    _canDecide.AddTo(ref _disposables);
}

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

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

View

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

private DisposableBag _bindDisposables;

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

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

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

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

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

Choosing not to use R3 is also important

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

Examples where R3 is often unnecessary:

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

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

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

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

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

Conclusion

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

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

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

DEV Community: GameDevToolLab

Does Unity Really Need DI? Keeping Zenject, Choosing Reflex, and Comparing VContainer

Introduction

DI is not the same as using interfaces

Why Unity makes DI more complicated

Awake and dynamic prefabs

Model lifetimes explicitly

Why Zenject became popular

Is Zenject still usable?

Existing projects

New projects

Is Zenject too slow?

Why Reflex is a strong default for new projects

Installing Reflex

Registering plain C# classes

Injecting a MonoBehaviour

Registering a ScriptableObject or existing instance

Do not turn Resolve into a Service Locator

Source Generator and IL2CPP

Creating dynamic prefabs safely

VContainer is the main alternative

Manual DI is also valid

Mapping Zenject concepts to Reflex

Common DI failures in Unity

Creating an interface for everything

Using the container as a global variable

Resolving every frame

Storing scene state in root singletons

Expecting DI to define async startup order

Conclusion

References

Testing in Unreal Engine 5: CQTest, Automation Spec, Functional Tests, and CI

Introduction

Which UE Test System Should You Use?

Separate Game Rules from Actors and Widgets

Where to Put Test Code

Simple Automation Tests

Treat Test Names as a CI Hierarchy

CQTest for Fixture-Style C++ Tests

Automation Spec for Readable Behavior Scenarios

Complex Automation Tests for Parameter Sets

Testing Work That Spans Multiple Frames

Expected Warnings and Errors

Functional Tests for Actors and Levels

Running Tests in the Editor

Running Tests from the Command Line

Do Not Trust Only the Process Exit Code

A Practical CI Split

Pull Request or Pre-Submit

After Updating the Main Branch

Nightly or Scheduled Jobs

Python Automation Tests for Content Workflows

Automation Driver for UI Input

When to Use Low-Level Tests

Common Failure Modes

Waiting with Sleep

Depending on Test Order

Leaving Files or Actors Behind

Comparing Floating-Point Values Exactly

Creating Unreproducible Random Tests

Writing Vague Failure Messages

Expecting Live Coding to Register Everything

Starting with Coverage Percentage

A Gradual Adoption Plan

Conclusion

References

A Practical Guide to Testing in Unity: EditMode, PlayMode, Async, and CI

Introduction

What Unity Test Framework provides

EditMode and PlayMode tests

EditMode tests

PlayMode tests

A practical decision process

Create test assemblies first

Write the first pure C# test

Parameterize boundary cases

Assert behavior, not every field

Test ScriptableObject rules in EditMode

Validate prefabs and assets

Test MonoBehaviour correctly

`Awake` and dynamic prefabs

Injecting a `MonoBehaviour`

Registering a `ScriptableObject` or existing instance

Do not turn `Resolve` into a Service Locator

Custom Binary Data with `AsyncReadManager`