Upgrading from v3.x to v4.x

v4 is a massive rewrite and upgrade from v3. A huge amount of features and improvements have been added, and while FlexBuilder will attempt to auto-upgrade as much as possible, there are a few things that require you to make your own decisions and/or confirm before they happen to make sure they are correct.

In particular, note the first item below! Existing projects will NOT compile after the upgrade, until you update the namespaces

Namespaces have changed

In all your source files, replace:

using Flexbox4Unity;

With:

using NinjaTools.FlexBuilder;

Warning

Until you do this step you will not be able to compile/build your project, and the UnityEditor will ask you to open it in 'Safe Mode' on startup.

Additionally, if you had customised the LayoutAlgorithm or similar, you may find some of the classes you were accessing have now moved to new namespaces. They are all still public, but now better-organized. The main namespaces currently in use:

 using NinjaTools.FlexBuilder;
 using NinjaTools.FlexBuilder.CSS3;
 using NinjaTools.FlexBuilder.LayoutAlgorithms;
 using NinjaTools.FlexBuilder.ContentSizing;
 using NinjaTools.FlexBuilder.Helpers;
 using NinjaTools.Workarounds;
 using NinjaTools.FlexBuilder.Editor.Windows;
 using NinjaTools.FlexBuilder.Editor;

Explanation: In 2021 Unity required us to rename the asset (new Unity policies forbid using the old name), forcing a change to the website domain, and hence the namespaces. Unfortunately C# had no way to auto-update namespaces (Microsoft's mistake in designing C#).

Each RootFlexContainer requires a LayoutAlgorithm

In v3 you could only have one LayoutAlgorithm at a time, and it was used globally. In v4 you can have multiple different ones in the same scene - this requires you to confirm/choose one for each RootFlexContainer. FlexBuilder will automatically detect the missing items, automatically select the most recent LayoutAlgorithm, and offer you a button to apply it to each RFC:

You will have to select each RootFlexContainer in your scene, and each one will present you with the option, and then individually confirm for each one which LayoutAlgorithm you want it to use.

RootFlexContainers are more stringent about misconfiguration

In v3 there were several ways you could misconfigure an RFC that 'usually work' but weren't fully supported. v4 will now discourage you from doing that (most of the time it is fine to have these misconfigurations, but occasionally it has unexpected effects).

These are not strictly speaking errors - they are now generally supported - but it's recommended that you revert each RFC to the default settings, and only change the values that are provided by the Inspector UI.

Select each RFC and - if FlexBuilder detects unusual hidden config settings - it will give you Warnings like this, with the option to reset the unusual settings to their (recommended) defaults:

Warning

⚠ this will sometimes (not always) change how your UI displays on the screen - this is why it is worth you doing each RFC individually, and visually checking whether you need to adapt your UI after the change.

Some FlexItem settings have changed

Some of the dropdown fields - in particular the settings for width/height - have changed in v4. V3 only had incomplete options, and/or used "NONE" to mean two different things that are actually very subtly different in CSS/Flexbox. Fixing this bug means it will work correctly for all future projects you create - but projects created in v3 or older will often find that some/all the FlexItems have acquired unexpected size settings.

🚧 For most projects this is quick to fix by hand - but if you have a particularly huge project where this isn't feasible, please Contact Support - preferably via Discord and I will see if I can get you an automated or semi-automated upgrade script. I have already written one, but it sometimes guesses 'wrong' and overwrites other settings, so it's not included by default.

Tip

💡 Remember that you can multi-select GameObjects in the Hierarchy, and if they all have a FlexItem attached, you can set the values of all of them at once.

Problems?

For any other issues, please Contact Support - preferably via Discord. V4 is a major update and while I've personally checked upgrading from projects as much as three years old there's always a possibility that some projects will encounter problems during the upgrade.