Asset serialization mode

When opening a Unity project, Rider will check that the project’s asset serialisation mode is set to “Force Text”. If not, it shows a notification popup saying that some advanced features require text based serialisation mode.

Some advanced integration features are unavailable when the Unity asset serialisation mode is not set to “Force Text”. Enable text serialisation to allow Rider to learn more about the structure of your scenes and assets.

The serialisation mode setting controls whether assets, such as .prefab, .unity and .asset files from scriptable objects are saved as either binary or text. Binary is more efficient in terms of file size, but is less maintainable. Text files can be larger, but are more easily modified and are more source control friendly - binary files cannot be diff’d or merged. The default for new Unity projects is Force Text.

What "advanced integration features" does Rider support?

When the asset mode is set to Force Text, Rider will parse and index your assets, prefabs and scenes, in much the same way as it does for C# files. Once indexed, these files are included in the results of Find Usages on Unity script components as well as methods and properties used as event handlers.

The Find Usages results are displayed in the standard Find Results tool window, grouped as “Unity event handler”. If the Unity Editor is running, and Rider’s plugin is installed in your project, Rider will also display the Find Usages results in a tool window inside Unity. Double-clicking the item in the tool window will select and highlight it in Unity’s Hierarchy tool window.

Furthermore, using the Rename refactoring on a method or property used as an event handler will also rename the usage inside the asset, prefab or scene. After specifying the new name, Rider will prompt for confirmation of the rename, and to make sure that the file is saved in Unity before proceeding. After clicking Next, the method is renamed inside the asset file. Switching back to Unity will prompt to reload any open scenes that have been modified.

Implications of updating to Force Text

If the project is set to Force Binary or Mixed, Rider will suggest to change to Force Text. However, Rider does not provide a quick link to do this automatically.

This is a major change to a project and should be carried out deliberately and safely. It is also important to make such a significant change as a single, standalone commit to source control that does not include any other changes. This makes it much easier to rollback to a known state if necessary.

Updating to Force Text is not just for Rider functionality - Unity recommend using this setting, and it is the default for new projects in recent versions of Unity. Text files are easier to maintain, and can be handled more efficiently by most source control systems - it's not possible to diff or merge a binary file.

It is also sometimes useful to be able to manually modify an asset file. While this is not necessarily recommended, it is possible to manually update GUIDs of asset references that have been broken due to failing to rename or move a .meta file correctly. Rider will keep .meta files up to date correctly, and the Rename refactoring will update text based asset files correctly, too.

To convert a project from Force Binary or Mixed mode requires changing the Asset Serialization value in the Editor Settings dialog. Changing the setting will immediately reserialise all assets in the new format, which can take some time for really large projects.

Notes

Some assets are always serialised as binary, due to asset size and type. For example, LightingData.asset and NavMesh.asset are usually massive arrays of numbers, and it is much more efficient to serialise these particular files as binary. Also, if a scriptable object class has the [PreferBinarySerialisation] attribute, the file will be serialised as binary. Rider does not parse these files (and this is not a problem as they do not usually contain event handler references).

Also note that while Rider will parse assets, prefabs and scenes, if the project is significantly massive, it will automatically disable parsing for performance reasons.

Files serialised as text are serialised as YAML files. More details about the file format can be found in the Unity documentation.