Official Invitation to try out Unity Safe Mode

Unity Safe Mode

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 we report compilation errors that happen during startup of Unity, as well as the initial process of bringing up the environment/domain that contains your project. In this post, we wanted to share why and what we have been working on and invite you to provide feedback on how we can make it even better


How compilation errors are handled

Today any compilation errors in scripts and packages during startup will result in their respective assemblies not being loaded since they couldn't be compiled. After the compilation is completed, Unity then continues to import assets. 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.

This causes four problems that make project upgrades time consuming:

1) All asset imports have to be completed before you can fix any compile errors, which can take a significant amount of time on a large project.

2) Asset imports might result in various other errors simply because some of the dll's that a project expects to be loaded were not loaded due to compilation errors. Thus you might experience a bunch of errors that aren't real errors, giving you misleading information in terms of an efficient debugging workflow.

3) If asset dependencies are not correctly declared in Asset Importers & post-processors, the project Library cache folder caches incorrect artifacts because the code couldn’t be loaded.

4) If asset dependencies are correctly declared in the asset importer / postprocessor C# code, it results in importing those assets once before fixing compile errors and once after fixing compile errors, increasing the total import time significantly.


Introducing Unity Safe Mode

With our latest changes and Safe Mode, if any compile errors occur while Unity is starting up, we now prompt 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.




Safe mode is entered before any other assets are imported. Thus opening a project into safe mode and fixing compile errors is significantly quicker than waiting for the whole project to import first and then fixing compile errors.

It also makes it much clearer which errors need to be fixed and as an added benefit makes it less likely to have incorrectly cached artifacts.






Safe Mode has a limited set of functionality compared with the regular Unity editor, that helps you resolve the compilation errors that occurred and bring your project back into a working state, without causing any additional runtime errors from missing loaded assemblies.

This includes, but is not limited to:

• Project View with the ability to manage scripts and assembly definitions
  
  
• Code editors integration
  
  
• Packman window
  
  
• Console
  
  
• Inspector

We feel that this will greatly improve the process of upgrading projects and significantly reduce the risk of projects needing to be rolled back or recovered.


How to try it out today and how you can help

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. Please use this forum thread to provide us with your feedback.

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

If you like to know more about how you can get access to preview features and our beta program, please visit our official beta program pages.

 

I imagine this will save some headache. While on the topic of a slimming down the editor, any chance of a lightweight/portable editor build?

 

Is the safe mode editor the actual unity editor or another application like your out-of-process-profiler?
How does this behave in -batchmode?

 

Hi Peter, it is the actual Unity Editor.

AFAIK compilation errors prevents -batchmode from starting. So no changes there.

 

Part of the thinking behind using packages was exactly that. To slim down what the editor and unity builds had to ship with. It is somewhat out of the context of this thread, but if you can list what a lightweight / portable editor would look like for you, I can bring it to the editor team.

 

My game allows Editor to be used as a modding tool but not very many people want to because it's too difficult and slow to set up. There's a few Unity games out there that tried this. Modding should always be accessible and easy, to make it work would take a build that is portable (doesn't require Hub or registration), open/create projects via context menu, and download size reduced to under 500mb. I've toyed with various new/upcoming engines and had them downloaded & a project created + opened in 5 minutes or less. No idea how viable this is, I'm sure Unity has a lot more behind the scenes than these other engines, but for me and my game it would beat a custom runtime modding solution by a longshot.

 

Maybe add a "don't open Unity" button? If our artists gets this in their face, the correct approach for them is probably to not open Unity, and tell me or some of the other programmers that everything is broken and we need to fix it. There's not really anything useful for them in entering safe mode.

Other than that, seems like a great feature.

 

Thanks for the feedback Baste.

The flow of safe mode, especially when does it make sense to allow what is a broken build to be loaded is something we need to get more feedback on.

We mostly assume that Safe Mode will be something you encounter very rarely and in the project life cycle of upgrading unity versions. Once done in Safe Mode, someone would commit / push the changes to the rest of the team.

 

Thanks for the feedback Crayz. How to simplify modding games in Unity is something that has been discussed a fair bit recently. I hope we can give more information later on when we have more concrete changes to show.

I will pass this on.

 

I like the feature but the name Safe Mode brings back some painful windows memories.

 

It's kind of a weird one to test, because we have to intentionally put our project into a broken state to try it.

I guess a good use case to test would be to download the special build, and then open a copy of our 2018.4 project in it, to see if it kicks in. Would that be useful?

 

@Joachim_Ante I'd like to but this one makes me to afraid to even test it:

Do you have more info when and why that happens to avoid it? Sounds like the exact reason I'd want to use Safe Mode for (updating packages, including our custom ones) would be defeated by this.
I'll test it once on a larger (> 40 GB) project that I want to update anyways, but on the first of those "accidental re-imports" I'm out as that would just take too long.

 

I assume "when upgrading a package" means that it happens when you opens the package manager and change the package version (or change it in manifest.json). Since it's a Known Issue (tm), I assume the team's aware that it's a problem!

 

Yep, I think that's actually a big part of "upgrading non-trivial projects to a newer Unity version" - packages change, get auto-updated or need manual updates, and we're also using packages for our own code (which will usually need some ifdefs here and there to properly work on a new version).

 

@Joachim_Ante first round of feedback: Opening a (relatively small, wanted to try that first) project that was on 2019.4.1f1 in the custom build goes into what seems to be an infinite import loop.



Actually it seems that the compiler saturates 2 cores and is stuck:


The project opens fine on 2020.2.0a16 (regular build) and has 173 compile errors there I guess I found a good test candidate for you.
It happens to be public on GitHub: https://github.com/hybridherbst/ggj-2020/tree/vulkan-xr (note it's on the Vulkan-XR branch).

EDIT: after opening with 0a16 I tried 0a17 again, and this time I'm getting the "Safe Mode" question.

Note 1: honestly I'm not sure if you want to write "Do not enter Safe Mode (not recommended)". 90% of people working in mixed teams (artists, devs, ...) on projects shouldn't be using that EVER and will only be super confused. Add to that the fact that Hub still doesn't properly pick up engine version changes after VCS updates (Case 1173030) and a lot of people will end up in Safe Mode that shouldn't.

Note 2: the Project Window layout has reset itself to 2-pane layout, guess that's because you load a custom layout in safe mode.

Then I started updating some packages and some asset store packages (Oculus Integration), which reduced the number of errors considerably.
Then I started fixing the remaining things, but as before, after fixing all shown compile errors new ones popped up (I guess because they're in the same assembly?).

Note 3: the "warning/lock icon" design isn't very legible, I first thought there was some graphic corruption.


Note 4: after fixing all compile errors, Unity automatically went back out of safe-mode – I'm not 100% sure that should be automatic (as that kicks in the expensive library reimport) but I guess I'm fine with that.

I like the idea! Workflow feels good, and I like very much that I can gauge how much work updating a project will be (code-wise) without having to reimport assets. The initial freeze is probably a bug.

Note 5: after thinking about this some more, I'd actually love if I could manually invoke safe mode, even without compiler errors. Could you add a cmdline flag for it? Reason: I often have to update packages and see whether that still works (e.g. update Timeline package, or update URP package, or ...) and some of these cause major reimports (e.g. updating any graphics package might reimport all heavy things in a project, close to full reimport time, due to changed importers). In these cases I could then manually invoke safe mode, check if everything still compiles (and find the right version where it does), and then exit safe mode.

-----------------

Tried on another project;

This time I had a package error (which I could resolve by upgrading the respective Unity package), but afterwards I'm stuck in Safe Mode with this:


I think "deterministic compilation" is also a new feature in 2020.2? And the package that fails is the deprecated HLAPI. Just wanted to let you know that this blocks exiting Safe Mode as well. Plus, in Safe Mode I cannot do what the recommendation is here – "Player Settings" are not available in safe mode

After upgrading the HLAPI package instead (from 1.0.4 to 1.0.6) I get a new bunch of error messages, this time definitely from other packages / different assemblies.
Wasn't one of the ideas of Safe Mode that I will be able to see compile errors across assemblies at the same time? Or was this blocked by the "deterministic compilation" thing in this case here?

Oh, and I think I found a pretty serious bug in the ScriptUpdater:
it automatically updates all "ScriptableImporters" from UnityEditor.Experimental.AssetImporters.ScriptableImporter to UnityEditor.AssetImporters.ScriptableImporter; the docs mention that this is the right new namespace; but seems actually it's still in Experimental in a16 and a17. This affects both our code as well as a number of Unity packages (e.g. SVGImporter, USD, InputSystem).

 

I just tried the safe mode to fix the constantly crashing inspector after selecting a gameobject with a script that doesn't exist anymore in 2020.2. Bummer: one cannot access the inspector. I was expecting to at least be able to remove gameobjects in my hierarchy which would be really helpful. Right now I don't really see the advantage compared to the normal build, where I can also fix script errors until none are left (if there wouldn't be the constant crashing whenever I press editor buttons). So I think the idea of safe mode is great, but could cover more scenarios

 

@Joachim_Ante @MartinGram curious for your feedback and if you need further information.

 

After updating Unity from 2019.4 to 2020.2 it constantly crashed when I selected a game object in the inspector that contained a script which did not compile anymore. My line of thinking was, great, with safe-mode enabled I can remove the script component from the game object safely and then restart without safe mode and would have gotten rid of the crash. As that was not possible, I went back to 2019.4, removed all the scripts that WOULD have errors in 2020.2 preemptively and then went back to 2020.2 and voila, no more crash. But then Oculus Integration does not work anymore due to unknown "Boundary" class so I gave up and went to 2020.1 instead. This works but is a mess VR-wise. The Oculus plugin is not as good yet as the original included integration was with constant rendering errors. I really hope you have that on the radar.

 

Updated the original post to reflect the release of a new build containing:

• When upgrading a package in Safe Mode sometimes all project assets are re-imported.
• Latest version of Unity 2020.2

 

@MartinGram that's a bit confusing - is that bug (asset re-import) now fixed? It was already mentioned before, and is still mentioned under "Known Issues".

 

Then how about you kick it from the "Known Issues"

 

A kind moderator did that while I was on holiday. Thanks for all the feedback.

 

Personally, I'd do 2 things:

1. Have the window text be more concise so that it will all be read and understood, flag Safe Mode as an 'advanced' option, and include a quit option:

Unity is unable to load the project due to compilation errors at startup.

Safe Mode allows advanced users to fix compilation errors without getting unnecessary imports of non-script assets.

Button 1: Quit
Button 2: Enter Safe Mode (for advanced users)
Button 3: Enter with Safe Mode (not recommended)

2. Put the more detailed usage text in a separate window after Safe Mode is launched, and put the "don't show" option there.

 

Where is the Linux build?

 

This would have saved me so much time a few months ago!

What occurred in this case was that an editor script (which tried to initialize an Editor only mode websocket connection) had initialized fine when I made a change with the editor open, but after closing the editor and opening again, the script tossed an exception that blocked the editor from opening.

IIRC, the issue was that the WebSocket API I was using tossed the error apparently deep into the .NET stack. Even try/catch wasn't letting the editor open, and was only resolvable by the mercy that the project was isolated to developing that new Editor feature.

Feedback:

• In safe mode, give easy access to the current and previous log dump files. Highlight the error line. That would save a ton of headache to find the log file and refresh it each attempt
• In this case, store more log files in the history, so we don't have to try to track error on attempt 1 vs error on attempt 6
• Put an easy to access "Restart Editor" which gives the user a cautious way to boot in. Maybe a full restart, but lets let the user skip the whole open Hub Select Project
  
• Even better would be a hot restart where the editor doesn't close, but goes to an initial state and tries again, bypassing any scripts that detect editor window state, and reports back any errors
• Would there be a way to hot attach the debugger, if Visual Studio was open and waiting for the connection? In my previous attempts, Unity wouldn't let me step. The debugger connection was apparently at a later time that initial Editor script execution

 

So, no Linux version?

 

Hugely upvoting, I'm working on a big moddable project using DOTS, and lightweight Unity that is super fast to setup would bring much more people to try it out!

Perfect example: Godot, can be downloaded with two clicks as a single exe under 60 mb. =)
I can see that most of the Unity's size goes from external SDKs and libraries.
Most of the time they stay the same, but always redownloaded per version. Why not store them in AppData?
Downloading new version takes more than hour for me.
And there is no way to lauch editor without waiting for packages dependency check / recompilation.
It is terrible right now.

I'll suggest the possible solution:
1) Core Unity build without setup, without huge platform-related libraries.
2) Immediate launch of already compiled projects in Preview mode. (No code modification, but fully functional edit and playmode)
3) Greeting screen, download all missing packages in background.
4) Import and exit preview
*User modifies project*
5) Build stage. Tell user to setup missing libraries.


This Unity would be much friendlier to the end user

 

Here's one compilation issue I've faced a few weeks ago:

1. Unity IAP plugin requires to be activated under Services and then to import some packages (outside of the PackageManager) that you will build against
2. every now and then the packages to install get updated
3. if the update fails, you can be left without any package installed, as it first delete the old version
4. if that happens, your code that points to the IAP plugin fails to build in the editor, and the import cannot proceed

Current official solution as per unity support: move your files out of Assets...

Solution we've found is to disable IAP under Services, reenable it, and quickly re-import the module before the editor kicks in.

Can safe mode help with this? I mean, it's great if the compilation can happen earlier. Can we also make it so that the editor is still usable even if the code doesn't build?

 

Not before Unity resolve any other high priorities.

I don't believe making modding easier would add anything to the development experience as a whole, as modding is not a strong requirement in many games, while many others struggle to keep their assets and binaries secure. Also, dedicated people would always find their way. On hacking sites, people already make resource extractors for Unity asset formats with zero support from Unity. If Unity makes modding easier, Unity essentially makes hacking Unity games easier. Thus, I don't see any reason Unity should spend any resources actively cater to modding. If a developer wants to support modding, it is their responsibility to provide the toolchain.

 

Can we force Unity to enter safe mode? I was thinking this could be used to troubleshoot crashes when opening the project. It would be useful if it let me do a step by step opening of the project, or make a log on what went wrong.

 

After reading the blog post, seems like there's a lot of good changes coming with this feature, but is there any documentation on the full process(as in the list of processes and their order) that currently occurs currently when you open a project with compilation errors(ie without the new safe mode)?

 

This seems like a good improvement! Thanks

I have two suggestions:

• Extend the batch mode support to allow a "compile then quit" command - having CI able to do a super speedy compile check without importing any other assets sounds tantalisingly close!
• In the warning message presented to users, either allow developers to customise this for their dev team, or write a few suggestions about what could have gone wrong, in simple language for non-technical folk. I can see artists/designers getting very confused, where for our team at least, 90% of the time a compile error on an artist machine is because Perforce has gotten in a pickle - and the user needs to either sync, resolve conflicts, check for local changes, or reconcile offline work.

 

We're in the same place - if there's a compilation error on startup on an artist's project, there's probably somebody that messed up a commit or merge somewhere.

We're a small company, so it's pretty straight forward for them to just ask us, but in an organization with scale, it seems like it'd be great to have the message that shows up be configurable, as in "if you don't know what's going on, ask Tom on Slack" or whatever.

 

We use editor scripts to manage our assets. Often fixing compile errors during boot is simply running one of our built in scripts. Will these work in safe mode? We keep these scripts in assemblies that always compile and have no dependencies on code that is likely to have compile errors

Perhaps an annotation to show a menu item even in safe mode?

 

SAFE MODE ROCKS. THANK YOU

 

Alright, makes sense but means it is not useful for us right now. I can give an example: our scripts add and strip code and assets to switch between different similar applications within the same code base. Currently we do have issues where compile errors cause prefabs and assets to load with errors. The issue usually arrives when git or some other tool changes up the local file structure or we have old dependencies in the project. The editor scripts fix this.
It would be great to be able to stop asset importing before one of our team have chosen a build profile and had the environment set up properly

 

Best feature of 2020.2!

 

Hi, we have hard crash on c4d models during the initial import and need to open the project directly in SAFE MODE. How can we do it? Are we able to import maxon importer while in SAFE MODE?