Flexbuilder FAQ

Common Errors

“Impossible CSS3Width enum value” ...

This usually happens when you take a project created in a much older version of FlexBuilder (e.g. Flexbox4Unity) and open it in a newer version. The direct fix is to find the FlexItem (or FlexContainer) that has the problem, and manually set each dropdown to the value you intended. In almost all cases you can see the 'Impossible' property: it will be a blank dropdown (no text in the dropdown) -- that's how the UnityEditor displays invalid enum values (as of Unity 2020/2021).

Note

For most cases I've already included auto-detecting, auto-upgrading routines that detect when you're moving between major versions of FlexBuilder (e.g. from v3.x to v4.x), and you won't see this error. However there are situations where it's impossible for the code to know what the 'correct' new value should be, and those ones are left unchanged for you to decide yourself.

In most cases, if you click on the RootFlexContainer that holds your layout it will run its own auto-checks for this error and either correct them or give you an option to auto-correct them.

Warning

It's impossible to auto-detect this problem inside Prefabs (Unity doesn't give us a fast API call for this, and doing it for all prefabs, all the time, would slow down your Editor). For Prefabs in particular you need to manually open the Prefab and find the wrong dropdown value and change it.

Until you do this, every time you instantiate that prefab at runtime you will get this error message again, because it inherits the 'impossible' value from the prefab.

Problems

How do I set the aspect ratio of images (or any UI element) and have them automatically resize?

CSS will maintain aspect ratios automatically for images where possible, unless you mark a FlexContainer as using “STRETCH” for its children/contents. There’s a couple of ways you can use this to control aspect-ratios for any object. The easiest one is this:

  1. Build your UI and choose which FlexItem (“Target”) you want to have a fixed aspect-ratio
  2. Make sure Target’s parent FlexContainer does NOT have “alignItems” set to “STRETCH”
    • (if you need the parent to be STRETCH: insert a new FlexContainer into the hierarchy between Target and its original parent, and keep the old parent on STRETCH, but set the new parent to something else)
  3. Create a transparent image in the aspect-ratio you want (i.e. 1x1 pixels for a 1:1 ratio)
  4. Insert this image as the first child of Target -- if Target already had an Image, or Button, or etc: keep them, but as the 2nd/3rd/etc children of Target, not the 1st one

NOTE: FlexBuilder will now find that image when trying to automatically size Target, and use it to deduce that the aspect-ratio you want, using pure CSS3

If you didn’t already have UI elements on Target, add the ones you want, but make sure your transparent image is still the first child

NOTE: FlexBuilder will ignore these 2nd/3rd/etc elements when sizing Target -- only the first valid item is used for sizing Resize the parent FlexContainer however you like - grow it, or set min sizes, etc - and Target will size inside it while maintaining the aspect-ratio you chose

My text doesnt appear even though its AUTO sized?

There is a bug in Unity text rendering that Unity staff decided not to fix (as of 2022 Unity staff have stated they won't fix any more bugs in their Font API). They misreport the size of fonts, and then choose to block rendering because of the mismatch between their two API values. The net result is that Unity says a font needs e.g. "30 pixels" of vertical space, but if you give the font less than e.g. "32 pixels" of space, Unity silently refuses to render it.

Flexbuilder has a built-in feature to workaround these Unity bugs: when you select a FlexItem with an attached Text, or that has a child Text component, an extra feature appears in the inspector: you can artificially 'expand' the width/height of the text by a few pixels. Tweak this and find the right value for your font/text/size combination.

How do I disable the warning: "Unity staff have stated they will NOT fix this core bug in their API - June 2022 - please complain to them for creating this bug in your game. Can't layout text"?

First find the ContentSizeCalculatorBasic4x1 instance that's controlling content-sizes for your project. The easy way is to go to Unity Project Settings, select 'Flexbox', and click on the Layout Algorithm - the LayoutAlgorithm instance in your project will have a direct link to your ContentSizeCalculatorBasic4x1.

Once you've found your ContentSizeCalculatorBasic4x1, select it and set "suppressUnityBugWarning" to true by ticking the tick-box.

Known bugs in Unity

Adding a new FlexContainer in the Editor doesn't automatically size the new FlexContainer

This is due to internal bugs in the UnityEditor (affected: Unity all versions through at least 2020.3.19). The following method is (incorrectly) NOT invoked by Unity unless you are in Play mode:

protected virtual void OnTransformChildrenChanged()

Right now we have no solution to this. The workaround is to trigger a relayout by clicking the FlexContainer in the SceneView and dragging any edge using the RectTransform tool. FlexBuilder will detect this attempt to change the size, and then see that a re-layout is required, and instantly set the correct size/position.

Things that aren’t supported

Opening two Inspector tabs at once

This breaks some of Unity’s own code. As a result: if you ever open a new Inspector tab - even if you close it! - nothing is supported any more, until you close the UnityEditor and restart it (due to bugs in Unity itself).