A deterministic asset importer always produces the same output from the same input and set of dependencies. Non-determinism happens when the same asset file produces different import results, usually through cached import results.
When you download an import result from the cache, Unity assumes that the result is identical to the output of importing the asset locally. If you receive incorrect cached data, then you might experience inconsistent or failed builds, visual differences, or unexplained bugs. These issues are often subtle and difficult to debug because the source isn’t immediately clear.
A common cause of non-determinism is through any asset importers that you make with scripted importers, or AssetPostprocessor instances. Ensure that any scripted importers you write are deterministic. Register import dependencies, bump version numbers, and avoid creating non-deterministic AssetPostprocessor or ScriptedImporter code. For more information, refer to Import dependencies and determinism.
Some Unity Editor-generated assets are non-deterministic and can produce different binary outputs when regenerated, even with identical source data and settings.
To maintain deterministic builds, avoid regenerating these assets unless the source content changes, and keep previously baked or generated data under version controlA system for managing file changes. You can use Unity in conjunction with most common version control tools, including Perforce, Git, Mercurial and Unity Version Control (UVCS). More info
See in Glossary. Only rebuild lightmapsA pre-rendered texture that contains the effects of light sources on static objects in the scene. Lightmaps are overlaid on top of scene geometry to create the effect of lighting. More info
See in Glossary, or other baked assets when the source content changes, and not as part of every build routine.
| Asset type | Behavior |
|---|---|
| Lightmaps | Re-baking lightmaps for every build produces different binary data, even with the same lighting setup. This is because the baking system involves not only floating-point rounding but also sampling noise that can make lightmaps non-reproducible. |
| NavMeshA mesh that Unity generates to approximate the walkable areas and obstacles in your environment for path finding and AI-controlled navigation. More info See in Glossary |
Build NavMeshes under identical input and environmental conditions. However, NavMeshes are sensitive to floating-point operations because Unity calculates the NavMesh based on the sceneA Scene contains the environments and menus of your game. Think of each unique Scene file as a unique level. In each Scene, you place your environments, obstacles, and decorations, essentially designing and building your game in pieces. More info See in Glossary’s meshes. Therefore, the NavMesh might bake differently on other architectures. |
| Generated assets based on noise sampling | Creating assets based on sampling noise textures or other randomness can generate assets differently each time. |
Before you build assets, you can confirm whether the imported assets are deterministic with the -consistencyCheck command-line argument. You can also use the Import Activity window to inspect re-import reasons and timestamps.
You can disable automatic artifact cleanup when analyzing imports as follows:
EditorUserSettings.artifactGarbageCollection = false
This prevents Unity from deleting previous import artifacts. Deleting the Library folder clears all historical import data.
To get more information about the non-deterministic assets in your project, inspect the Editor log file. To open the log:
The Editor log displays inconsistencies in the following format:
ConsistencyChecker - guid: <asset_guid>, dependenciesHash.value: <dep_hash_a>, importResultID: <result_id_a>, producedFiles[0].extension: , producedFiles[0].contentHash: <content_hash_a>
ConsistencyChecker - guid: <asset_guid>, dependenciesHash.value: <dep_hash_a>, importResultID: <result_id_b>, producedFiles[0].extension: , producedFiles[0].contentHash: <content_hash_b>
Importer(<importer_name>) generated inconsistent result for asset(<asset_guid>) <asset_path>
For more information, refer to Check the consistency of the import process.