Character Preset Manager

This page documents CharacterPresetManager.

It explains:

• What data is captured in a preset.

• How save/load and key scoping work.

• How material color slots/tracking are configured.

• How portraits are handled.

• How to integrate custom providers and metadata.

Purpose

CharacterPresetManager is the core save/apply system for character appearance.

It captures and restores:

• equipped item IDs

• body blendshape weights

• body part length multipliers (optional adjuster)

• uniform scale

• tracked material floats/colors/textures

• optional metadata (name/title/notes)

• optional portrait file name

Source

• Assets/Arawn/CharacterCreator/Runtime/CharacterPresetManager.cs

Core References

Field	Required	Notes
equipmentManager	Recommended	Used for equipment capture/apply by unique IDs.
bodyRenderer	Recommended	Source body blendshapes.
blendshapeSynchronizer	Optional but recommended	Forces equipment blendshape sync after apply.
bodyPartAdjuster	Optional	Reflection-based support for body part multipliers.

Metadata + Key Scoping

Field	Purpose
presetMetadataProvider	Optional component implementing ICharacterPresetMetadataProvider.
captureMetadataFromProvider	If enabled, provider metadata is written during capture/save.
scopePresetKeysByNamespace	Adds namespace:: prefix to stored keys.
presetKeyNamespace	Explicit namespace. If empty, fallback namespace is auto-built from scene/root name.
filterSavedKeysByNamespace	Filters returned key list to this namespace and strips prefix for UI display.

Material Tracking

Tracked Renderers

trackedRenderers defines which material properties are serialized.

Each tracker contains:

• renderer reference

• float property names

• color property names

• texture property names

Explicit Skin/Eye Color Slots

explicitSkinColorSlots and explicitEyeColorSlots are optional overrides used by demo color UI and material tracking.

Each slot contains:

• renderer

• material index

• color property name

Equipment Color Property Names

equipmentColorPropertyNames controls which color properties are considered during auto-configuration, for example:

• _BaseColor

• _Color

• _BaseMapColor

• _TintColor

• _EmissionColor

Provider + Event Surface

Public members:

• Provider (lazy default: JsonFilePresetProvider)

• SetProvider(ICharacterPresetProvider customProvider)

• event Action PresetsChanged

PresetsChanged fires on successful save/delete and is used by CharacterPresetGalleryUI and other UI listeners.

Public API Summary

Key Scoping

• BuildScopedPresetKey(string key)

Capture / Save

• CapturePreset(string presetName = "New Preset")

• CapturePreset(string presetName, string presetKey)

• SavePreset(string key, string presetName = null)

Apply / Load

• ApplyPreset(CharacterPreset preset)

• LoadAndApplyPreset(string key)

• LoadPreset(string key)

Management

• GetSavedPresetKeys()

• DeletePreset(string key)

Auto Configuration

• AutoConfigureExplicitColorSlots(bool resetExisting = false)

• AutoConfigureMaterialTracking(bool resetExisting = false)

Portrait

• LoadPortrait(string key)

• LoadPortrait(CharacterPreset preset)

• CapturePortrait(string key)

Save/Load Behavior Details

Save

SavePreset:

1. Resolves logical key to stored key (with namespace if enabled).

2. Captures full current appearance into CharacterPreset.

3. Captures portrait if enabled.

4. Calls provider Save.

5. Raises PresetsChanged on success.

Load

LoadPreset:

• accepts either logical key or already-scoped key

• tries direct key first, then scoped key fallback

LoadAndApplyPreset:

• loads by key

• calls ApplyPreset

ApplyPreset:

• applies equipment, blendshapes, body-part scales, uniform scale, materials

• calls blendshapeSynchronizer.SyncNow() if available

Portrait Storage

Portrait files are stored under:

• Application.persistentDataPath/CharacterPresets/Portraits

File name pattern:

• <sanitizedKey>_portrait.png

Notes:

• LoadPortrait returns a runtime Texture2D.

• UI code should destroy textures when no longer needed.

Namespace Behavior Example

If namespace is player01 and key is main:

• stored key becomes player01::main

With filterSavedKeysByNamespace = true:

• GetSavedPresetKeys() returns main (prefix removed for display)

Metadata Provider Integration

If a metadata provider is present and enabled:

• metadata is captured during save/capture

• values are written into preset fields (characterName, characterTitle, characterNotes)

If no provider is present:

• save/load still works, metadata just remains optional.

Typical Runtime Setup

1. Attach manager on character root.

2. Assign equipment manager + body renderer + synchronizer.

3. Run:

   • AutoConfigureExplicitColorSlots(...)

   • AutoConfigureMaterialTracking(...)

4. Save/load presets through manager or API facade.

Common Troubleshooting

Symptom	Likely cause	Fix
Preset loads but equipment not correct	Missing/invalid equipment IDs or manager reference	Ensure equipmentManager is valid and IDs are stable
Blendshapes apply then revert	Animator clip overrides blendshape channels	Remove blendshape animation keys or enforce desired values
Colors do not restore	Missing tracked renderer/property	Re-run auto-config or manually track correct properties
Different characters overwrite each other	Shared unscoped keys	Enable key scoping and set stable namespace
GetSavedPresetKeys shows unexpected keys	Namespace filtering disabled	Enable filterSavedKeysByNamespace and scopePresetKeysByNamespace