Troubleshoot

Find your symptom, get the cause and the fix. Entries are ordered by how early they tend to bite — the first three cover almost every "it doesn't work out of the box" report.

The Showcase scene is blank or unstyled

Symptom: you open LunaShowcase.unity, press Play, and get an empty screen — or views render but look unthemed, with missing icons and sprites.

Cause: the Essentials sample isn't imported, or was imported after Showcase. Showcase references Essentials assets (theme, Panel Settings, nav config, UXML templates, sprites) via sibling-relative paths — without Essentials those references are broken; and if Showcase was imported first, its files resolved against targets that didn't exist yet and stay broken until reimported.

Fix:

1. In Window > Package Manager > In Project > LunaUI > Samples, import Essentials (or open Tools > CupkekGames > LunaUI Panel and use its one-click import buttons).
2. If Showcase was already imported before Essentials: right-click Assets/Samples/LunaUI/<version>/Showcase in the Project window and choose Reimport so its references re-resolve.

The Quick Start import order — Essentials first, Showcase second — avoids this entirely.

Input doesn't respond, or the loading screen won't skip

Symptom: demo scenes render but nothing reacts to clicks or keys; the boot loading screen sits there and can't be skipped.

Cause: Luna's demos read input through the Input System package's project-wide actions, and your project doesn't have the Luna action asset assigned there.

Fix: go to Project Settings > Input System Package and set Project-wide Actions to the Luna_InputSystem_Actions asset from the Essentials sample (Assets/Samples/LunaUI/<version>/Essentials/Input/Luna_InputSystem_Actions.inputactions).

The LunaUI Panel (Tools > CupkekGames > LunaUI Panel) surfaces the same tip with an Open Input Settings button.

Element queries return null in Awake

Symptom: root.Q<Button>("...") (or any element lookup) returns null in Awake/OnEnable/Start, usually followed by a NullReferenceException.

Cause: Luna renders views through PanelRenderer (Unity 6.6's replacement for the deprecated UIDocument), and PanelRenderer delivers its visual tree asynchronously. At Awake time the tree simply doesn't exist yet — this is the single most common Luna scripting mistake.

Fix: in a UIViewComponent, query elements in the OnUILoaded override — it fires once the tree is mounted, with root already scoped to your view's subtree:

From outside the component, use myView.WhenUILoaded(() => { ... }) — it runs immediately if the UI is already loaded, otherwise on the load event. You'll meet this pattern hands-on in First View.

Fades or transitions don't play on a view

Symptom: a view's fade-in/out or transition animations don't run — or only part of the view animates while sibling elements pop in instantly. The Console shows a [UIViewComponent] warning about top-level children.

Cause: your view's UXML has multiple root elements. With the Parent Name field empty, UIViewComponent auto-resolves its content root to the first top-level child of the UXML — any sibling roots stay in the tree but get no fade/transition wiring.

Fix: wrap your UXML content in a single outer VisualElement so the whole view animates as one unit — or set the component's Parent Name field to the element that should own the fade.

UI Effects don't render at all

Symptom: no glow/outline/gradient/shine on anything, and the Console warns [Luna] FilterFunctionDefinition not found.

Cause: the effects filter pipeline is uninitialised. LunaUIManager registers a UIEffectSettings asset as the global instance in its Awake — if your scene has no LunaUIManager, or its Effect Settings field is empty, no UIEffectElement can render.

Fix: drop the Essentials Prefabs/LunaUIManager.prefab into your scene — it ships pre-wired with Essentials/Effects/UIEffectSettings.asset (which references the LunaFilter definition). If you built your own manager, assign that asset to its Effect Settings field; for bootstrap code that runs without a manager, call UIEffectSettings.SetInstance(settings) yourself. For effects that render but look wrong (washed-out shadows, black glows), see the UI Effects troubleshooting table.

UI Effects look blurry or soft

Symptom: glows, outlines, and other shader effects render, but edges look soft or smeared instead of crisp.

Cause: your Panel Settings uses Scale With Screen Size at a non-integer effective scale — the panel's render output (including the custom-filter passes) gets resampled.

Fix: use Constant Pixel Size. Luna's shipped LunaPanelSettings.asset uses Constant Pixel Size with Scale = 1; if you need a larger UI, prefer an integer Scale (e.g. 2) over Scale With Screen Size. See Theme Stack for the Panel Settings rundown.

Compile errors right after import

Symptom: the Console fills with compile errors the moment Luna finishes importing.

Cause: your editor is older than Unity 6000.6. Luna 2.3 builds on Unity 6.6 APIs (PanelRenderer and the custom-filter pipeline); the package's package.json declares 6000.6 as the minimum, and older editors can't compile it.

Fix: upgrade the project to Unity 6000.6 or later, then reimport.

Styles are broken everywhere (USS failed to import)

Symptom: Luna UI renders with default-looking, unstyled controls in every scene, even though Essentials is imported and the theme chain is wired.

Cause: occasionally USS files fail to import correctly and need a manual reimport.

Fix: go to Packages > LunaUI > Runtime > USS and reimport the files in each subfolder (Components, Effects, Library, Unity): enter the folder, select all files (Ctrl+A), right-click > Reimport. Reimport the files, not the folder — and do not click "Reimport All".

If styles still don't recover, also reimport Packages > LunaUI > Runtime > Setup > CupkekGamesMainTheme.

Luna styles don't show in UI Builder

Symptom: your UXML looks right in Play mode but unstyled inside UI Builder.

Cause: UI Builder previews with its own active theme — it doesn't know about Luna's theme until you select it.

Fix: in the UI Builder viewport toolbar, switch the Theme dropdown to Luna's theme (LunaUIDemoTheme from the Essentials sample).

Not listed here?

• The Community FAQ covers install, packaging, and "do I need all 49 packages" questions.
• The Release Notes document behavior changes between versions — worth a scan after any upgrade.
• Discord is the fastest route to a human. Bring your Unity version, Luna version, and a Console screenshot.