Character Preset Gallery UI

This page documents CharacterPresetGalleryUI.

It explains:

• What the component does.

• Which fields are required.

• How selection/load behavior works.

• How metadata and portraits are resolved.

• How it reacts to preset save/delete updates.

Purpose

CharacterPresetGalleryUI is a preset-only runtime UI.

It builds a list of preset cards and supports:

• portrait preview

• optional metadata rows (character name/title/notes)

• selection highlight

• load button reveal on selection

• optional double-click-to-load

It is designed for preset browser screens where you do not need full customization controls.

Source

• Assets/Arawn/CrystalCharacterCreator/Demo/Scripts/CharacterPresetGalleryUI.cs

Core Requirements

Required references:

• presetManager (CharacterPresetManager)

• presetListContent (RectTransform)

• presetEntryTemplate (GameObject)

Optional:

• metadataProviderBehaviour implementing ICharacterPresetMetadataProvider

• emptyStateText (Text)

Inspector Reference

Core

Field	Required	Notes
presetManager	Yes	Used to list/load presets and portraits.
metadataProviderBehaviour	Optional	Must implement ICharacterPresetMetadataProvider to inject custom metadata.

UI References

Field	Required	Notes
presetListContent	Yes	Parent container where runtime entries are instantiated.
presetEntryTemplate	Yes	Disabled template cloned per preset key.
emptyStateText	Optional	Displays setup/empty-state messages.

Behavior

Field	Default	Behavior
autoRefreshOnEnable	true	Calls RefreshPresetList() on OnEnable.
showLoadButtonOnlyWhenSelected	true	Load button only visible on selected card.
loadOnDoubleClick	true	Double-click selected card to load quickly.

Events

Event	Payload	When fired
onPresetSelected	presetKey	After card selection changes.
onPresetLoaded	presetKey	After LoadAndApplyPreset is triggered.

Runtime Flow

RefreshPresetList() does this:

1. Subscribes to presetManager.PresetsChanged.

2. Resolves metadata provider.

3. Clears old spawned entries and portrait textures.

4. Validates required references.

5. Gets keys via presetManager.GetSavedPresetKeys().

6. Instantiates one card per valid preset.

7. Binds UI children by expected child names.

8. Loads portrait (if available) and caches texture for cleanup.

9. Wires select/load callbacks.

10. Selects first entry and updates visuals.

Auto-Refresh on Save/Delete

The gallery subscribes to:

• CharacterPresetManager.PresetsChanged

So when presets are saved or deleted through the manager, the gallery refreshes automatically while enabled.

Metadata Resolution

Priority order:

1. metadataProviderBehaviour (ICharacterPresetMetadataProvider) result

2. Fallback to metadata fields already stored in CharacterPreset

If a provider object is assigned but does not implement the interface, a warning is logged.

Template Contract

presetEntryTemplate should include child objects named:

• PresetName (Text) - required for display label

• Portrait (RawImage) - optional

• LoadButton (Button) - expected for load action

• CharacterName (Text) - optional

• Title (Text) - optional

• Notes (Text) - optional

If some expected children are missing, the gallery logs warnings and continues.

Public API

• RefreshPresetList()

Use this when:

• the manager reference changes at runtime

• you want explicit manual refresh timing

Empty State Messages

Common messages:

• "Preset gallery is not configured."

• "No presets saved yet."

• "No valid presets found."

Memory / Cleanup

On refresh and destroy:

• spawned entries are destroyed

• loaded portrait Texture2D objects are destroyed

This prevents portrait texture leaks during repeated refreshes.

Typical Setup

1. Build gallery UI through Scene Demo Setup Wizard (Preset Gallery Only or Both).

2. Assign presetManager if not auto-wired.

3. Optionally assign metadata provider.

4. Enter play mode and call RefreshPresetList() if needed.

Troubleshooting

Symptom	Likely cause	Fix
No cards appear	Missing presetManager, presetListContent, or presetEntryTemplate	Assign required references
Cards show but metadata rows empty	No metadata provider and preset metadata fields empty	Provide metadata provider or save metadata into presets
Load button never visible	showLoadButtonOnlyWhenSelected enabled but nothing selected	Ensure list has entries; first entry is auto-selected on refresh
Double-click load not working	loadOnDoubleClick disabled or clicks too slow	Enable the setting or use LoadButton
Gallery does not update after save/delete	Different manager instance or not enabled	Bind the correct presetManager and keep gallery active