FAQ & troubleshooting

Answers before you ask

Troubleshooting

"No UI state key registered for MyUiState"

The state class name must equal the state key exactly, and Build Runtime UiConfig must have run after you created the state.

"Failed to locate UiConfig via Addressables"

Run Build Runtime UiConfig, then make sure Addressables can find it: play mode script Use Asset Database in the editor, or build Addressables content for a player.

Nothing appears on screen

Check the element's status in the Elements tab (✓), that your content is under Root, that there is an EventSystem and, for Screen Space – Camera canvases, that a camera is assigned at runtime. Look for [UiManager] errors in the Console.

My list doubles every time I come back to the screen

Populate runs again when a state reuses the scene. Rebuild lists instead of appending, and guard one-time setup with a flag.

Code in my UiState subclass never runs

State classes are only type markers; the runtime builds states from the config. Put behaviour in elements.

Two fast taps show the wrong screen

Calls aren't queued for you. Await each call, or route navigation through one place that queues calls, like the showcase's ShowcaseNavigator.

Questions

Can several people add screens and states at the same time?

Yes. Each state is its own UiStateDefinition asset and each element its own scene and script, so parallel branches add different files and merge cleanly. The only shared files, RuntimeUiConfig and the Addressables group, are generated: after a merge, press Build Runtime UiConfig and they are rebuilt from the state definitions. Never resolve them by hand.

Does it work with TextMeshPro, my own components, my art?

Yes. The framework only cares about the scene's shape; anything UGUI can draw works inside Root.

Screen Space Overlay or Camera?

Both. Pick the default in Global Canvas Settings and per element in the Canvas section. With Camera, assign your UI camera at runtime as scenes load (the showcase's UiCanvasCamera shows how).

Can I load UI scenes from a remote content server?

Element scenes are ordinary Addressables, so any Addressables setup works, including remote groups.

Is it heavy on mobile?

Only what is on screen is loaded. Animations use a small allocation-light loop on unscaled time, and shared elements are never reloaded.

Can I add my own animation presets?

Override ShowAsync / HideAsync / PrepareForShow in an element for one-off motion, or contribute a preset to TweenPresets.

What does it cost?

Nothing. It's open source under the MIT license.

Still stuck?

Open an issue or start a discussion.