Search Unity

Unity Safe Mode available in 2020.2 beta

October 9, 2020 in Technology | 6 min. read
Topics covered

Unity Safe Mode is available in Unity 2020.2 beta. This improves how Unity behaves when opening a project that has script compilation errors.

If there are compilation errors at Editor startup, you will be prompted to enter Safe Mode. This mode is designed to provide the best environment for resolving compilation errors, so that you can quickly return your project to a functional state, without waiting for all of your project’s assets to be imported. This feature will simplify and speed up the process of upgrading a project to a new Unity version, and it will help teams working on large projects by reducing the number of cases in which the library folder contains incorrect import artifacts.

How Unity Safe Mode is triggered

Challenges learned in production

We are always looking to improve the experience of working with Unity based on feedback from you and our internal production teams. One of the areas identified was how Unity behaves as errors are detected and reported during initial script compilation and asset importing when upgrading a project.

Consequently, we have recently improved how Unity behaves during startup and how it reports compilation errors that happen during startup to users, as well as the initial process of bringing up the environment or domain that contains their project. In this post, we want to share what we did in 2020.2 to solve your problems in this area and invite you to provide feedback.

In practice, many projects depend on scripts being present for post-processing or custom scriptable importers, or simply to correctly deserialize Prefabs – either through code directly in your project or the packages you depend on. In the presence of compilation errors in scripts and packages, their respective assemblies cannot be loaded and, since they couldn’t be compiled, their code cannot execute. After the compilation is completed, previous versions of Unity load the project partially and continue to import all assets. This partial project state causes a range of problems that we are addressing with the introduction of Safe Mode.

Introducing Unity Safe Mode

In Unity 2020.2, if any compilation errors occur during startup, Unity now prompts you to enter the new Safe Mode, where you can manage your project, solve compilation errors and bring the project environment back into a working state.

In Safe Mode, Unity provides a minimal version of the Editor user interface, with limited functions, which help you focus on resolving compilation errors before the rest of your project is opened. This interface includes, but is not limited to:

  • Project View, with the ability to manage scripts and assembly definitions
  • Code editors integration
  • Package Manager window
  • Console
  • Inspector
  • Project settings
  • Version control support, excluding Unity Collaborate

Safe Mode never allows managed code to run from your project or its packages. This ensures the Editor in Safe Mode is always fully functional and reliable, even when opening a project that is in a very broken state. 

Unity automatically exits Safe Mode when it detects there are no more compilation errors. When it exits Safe Mode, your project is imported in full and the Editor restores its normal full functionality.

What problems does Safe Mode solve?

  • Waiting for assets to import before seeing errors: Unity now enters Safe Mode before it imports any non-script assets. Thus opening a project in Safe Mode and fixing compilation errors is significantly quicker than waiting for the whole project to import first and then fixing compilation errors. This is particularly valuable when upgrading projects to new versions of Unity when there is API breakage.
  • Misleading error messages: Previously when opening a project with compilation errors after a Unity upgrade, the project would start importing with scripts not loaded, generating error messages. But these errors aren’t “real” (simply, the scripts rely on information that hasn’t been loaded yet), so the messages are misleading. This has been known to complicate and slow down project upgrade and troubleshooting workflows. Once the compilation errors are fixed, the resulting errors no longer occur. With Safe Mode, asset import is delayed until compilation errors are fixed, so these error messages are never generated.
  • Caching of corrupt artifacts: Commonly known as, “Why are my material previews pink?” (“Have you tried deleting the Library folder?”). When assets are imported in the context of partially loaded projects, the Library cache folder often caches incorrect artifacts. If asset dependencies are not correctly declared, Unity cannot automatically recover the project from cached incorrect artifacts, which results in unpredictable behaviors when working with the project. Using Safe Mode significantly reduces the cases where corrupt artifacts are cached. 
  • Increased import time: Or “Why did Unity reimport all my textures?” If asset dependencies are correctly declared in the asset importer and post-processor C# code, the partially loaded project imports many assets once before fixing compilation errors (which is unnecessary) and once again after fixing compilation errors, increasing the total import time significantly. By resolving all compilation errors in Safe Mode, this double importing is avoided.
  • Unnecessary reimports: Restarting Unity while iterating on project scripts can trigger unnecessary reimports if the current version of the scripts does not compile. For such workflows, Safe Mode helps bring the project environment to a working state faster, so the code iteration process is only minimally affected after an Editor restart.
  • Accidental corruption: Users sometimes unintentionally work on a partially loaded project, potentially corrupting Scenes or Prefabs because scripts that are necessary for saving a Scene or Prefab correctly failed to load due to compilation errors. Safe Mode stands in the way of this, limiting users to only safe actions when opening a project with broken scripts.

By addressing these issues, Safe Mode greatly improves the process of upgrading projects and significantly reduces the risk of projects needing to be rolled back or recovered.

Using Unity Safe Mode to fix a wrong declaration for a Vector3 inside a Unity project

What about batch mode?

In previous versions, Unity in batch mode would also partially load a project with compilation errors and proceed to import all assets. Once the imports are finished, by default, it would exit with an error message unless instructed otherwise via command line arguments. We changed this behavior in Unity 2020.2: now batch mode, by default, no longer makes use of partial project load and asset imports, and exits with an error message as soon as compilation errors are detected. This makes batch mode completion much faster in the presence of compilation errors. It also prevents continuous integration (CI) systems from populating the project’s asset cache server with incorrect import artifacts, which causes the problems listed above not only locally on one computer, but for everyone working on the project.

How to try it out today and help us refine it

We are looking for feedback on all aspects of the new Safe Mode state of Unity. We are especially interested in knowing if we have missed functionality that you feel is important to have present during Safe Mode. You can provide feedback in the forum.

Our R&D and QA staff work hard to make sure that our releases are stable, our features are polished and the workflows help you be more productive, but we couldn’t do it without all the feedback from the community.

About Unity 2020.2 beta

With Unity 2020.2, we’re continuing our 2020 focus on performance, stability, and workflow improvements. Join the beta and let us know what you think about the upcoming tools.

October 9, 2020 in Technology | 6 min. read
Topics covered