Luna UI Documentation

Modals and screens belong to navigation now. None of the Luna samples drive their UI through UIPrefabLoaderString anymore — view prefabs are registered as destinations on a NavGraphSO, spawned by a scene NavHost, and opened with LunaNavigation.Push(destination). If you're opening modals, popups, or screens, start with Navigation instead.

UIPrefabLoader<TKey> is a generic spawner for UI-flavored prefabs keyed by an arbitrary type (commonly string). Lives in com.cupkekgames.luna runtime (namespace CupkekGames.Luna.UI); the concrete UIPrefabLoaderString is the most common entry point.

It extends the base PrefabLoader<TKey> (in com.cupkekgames.prefabloaders) and adds Luna-specific UI integration:

Instantiate(key) additionally calls Show() on the spawned prefab's UIViewComponent, so UI prefabs fade in on spawn.
FadeOutDestroy(key, duration) — fade out all spawned instances of a key before destroying the GameObject. Because PanelRenderer delivers its visual tree asynchronously, the fade registers a one-shot reload callback and runs against the live root once it arrives.

When to use it

UIPrefabLoader remains in the runtime for plain key → prefab spawning outside any nav graph:

Spawn a UI prefab by string key at runtime, with auto-tracking of all live instances
Fade out + destroy on close (instead of cutting the GameObject)
Reuse the same loader instance across scenes (UIPrefabLoaderString calls DontDestroyOnLoad on itself)

API

csharp

public abstract class UIPrefabLoader<TKey> : PrefabLoader<TKey>
{
    public override GameObject Instantiate(TKey key); // spawn + Show() the UIViewComponent
    public void FadeOutDestroy(TKey key, float duration = 0.5f);
}

public class UIPrefabLoaderString : UIPrefabLoader<string>
{
    public static UIPrefabLoaderString Instance { get; }
}

Inherited from PrefabLoader<TKey> (in com.cupkekgames.prefabloaders):

Member	Returns	Description
`Instantiate(TKey key)`	`GameObject`	Spawn the prefab registered to `key` and track the instance. Returns `null` (with a warning) for unknown keys, and `null` when instances of `key` are already live — one live key at a time.
`GetInstances(TKey key)`	`List<GameObject>`	All currently-live instances of `key`.
`DestroyAllOf(TKey key)`	`void`	Destroy every live instance of `key` immediately.
`DestroyAll()`	`void`	Destroy every live instance of every key.
`ContainsKey(TKey key)`	`bool`	Whether the loader has a prefab registered for `key` (via the `KeyValueDatabaseMono` base).
`event OnInstanceDestroyed`	`EventHandler<TKey>`	Fired when any instance is destroyed (manually or via `FadeOutDestroy`).

Setup

UIPrefabLoaderString extends MonoBehaviour (via KeyValueDatabaseMono<TKey, GameObject>). Drop it on a GameObject in your boot scene and either assign key → prefab pairs directly in the Inspector, or configure the _searchFolder (FolderReference) so it auto-populates the prefab database from a folder of UI prefab assets.

No Luna sample script calls the loader anymore (the samples' modal flows all go through LunaNavigation), so treat it as an opt-in utility rather than a pattern the samples model for you.

Variants

Variant	Package	Use case
`UIPrefabLoader<TKey>`	`com.cupkekgames.luna`	Base — folder-scan prefabs (no Addressables)
`UIPrefabLoaderAddressable<TKey>`	`com.cupkekgames.addressableassets`	Addressables-keyed loading + caching
`UIPrefabLoaderAddressableString`	`com.cupkekgames.addressableassets`	Concrete `string`-keyed addressables variant

The non-addressable chain lives in Luna so projects without Addressables installed can still use the prefab-loader pattern. See PrefabLoader for the addressable-flavored variants.

UIPrefabLoader

When to use it

API

Setup

Variants

See also