> For the complete documentation index, see [llms.txt](https://arawn-software-publishing.gitbook.io/character-creator/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://arawn-software-publishing.gitbook.io/character-creator/tutorials/tutorial-addressable-equipment-prefab-workflow.md). # Tutorial: Addressable Equipment Prefab Workflow This guide explains the complete Addressables workflow for Crystal Character Creator equipment prefabs. Use it when an equipment prefab is not permanently registered on the scene `EquipmentManager`, but should still carry its own: * blendshape synchronization rules * Equipment Fit Sculptor fit data * body culling masks * equipment-on-equipment culling masks * stable runtime identity for save/load The main idea is simple: > Addressable equipment should carry its authoring data on the equipment prefab itself, then register into the `EquipmentManager` only when the player discovers or equips it. This keeps the player prefab light while still supporting thumbnails, UI entries, on-demand loading, body culling, equipment layer culling, blendshape sync, Crystal Save, and custom save systems. ### Recommended Runtime Model A practical RPG-style flow looks like this: 1. The player defeats a mob, opens a chest, buys an outfit, or receives a quest reward. 2. Your inventory code registers the equipment as an available catalog entry using its Addressable key. 3. The UI refreshes and shows the item as available. 4. The player clicks `Equip`. 5. The `EquipmentManager` loads the Addressable prefab on demand.

When using Addressables the Equipment Manager stays usually empty (No registered Equipment Prefabs)

6. The loaded prefab is registered with the same stable ID. 7. Equipment fit, culling holder data, and blendshape sync config are imported from the prefab. 8. The item equips immediately. 9. `RememberCharacterPreset` and/or `RememberEquipmentManager` persist the equipped Addressable entry with ID, key, and slot. You do not need to load every equipment prefab at character startup. ### Required Components On The Character
Your character root should have: | Component | Purpose | | --------------------------------- | ------------------------------------------------------------------------------------------------------ | | `EquipmentManager` | Registers, loads, equips, unequips, and saves equipment state | | `AddressableEquipmentAssetLoader` | Loads prefabs through Unity Addressables and registers itself as the manager's `IEquipmentAssetLoader` | | `RuntimeBodyOcclusionCuller` | Applies body culling and equipment layer culling at runtime | | `BlendshapeSynchronizer` | Copies source body blendshape weights to equipped meshes | | `CharacterPresetManager` | Captures full appearance presets, including addressable equipment asset entries | | `RememberCharacterPreset` | Crystal Save component for full appearance persistence | | `RememberEquipmentManager` | Crystal Save component for equipment-only persistence | `RememberCharacterPreset` and `RememberEquipmentManager` are only needed when you use Crystal Save. ### Required Components On The Equipment Prefab
For Addressable prefab-side authoring, use these components: | Component | Lives On | Purpose | | ----------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------ | | `BlendshapeSyncConfig` | Equipment prefab root or parent of equipment renderers | Stores prefab-owned blendshape exclusions, include filters, manual mappings, weight scale, and weight offset | | `EquipmentFitDataHolder` | Equipment prefab root | Stores Equipment Fit Sculptor mesh deltas so fit data travels with the prefab | | `EquipmentAndBodyCullingDataHolder` | Equipment prefab root | Stores body culling mode, manual body masks, equipment layer mode, layer, and equipment-on-equipment masks | These components are important because the equipment prefab may not exist in the scene's `EquipmentManager` list while you are authoring or saving the game. ### Stable ID Rule Every equipment item needs a stable `uniqueID`. For Addressables, the recommended rule is: > Use the Addressable key as the `uniqueID`. Example: ``` Addressable Key: ccc/equipment/outfits/formal-outfit Unique ID: ccc/equipment/outfits/formal-outfit ``` Using the same string for both fields avoids save/load mismatches. It also makes runtime discovery, UI binding, and Crystal Save restore easier to reason about. Do not rely on generated GUIDs for runtime-discovered equipment. A random generated ID can work in the same editor session, then fail after restarting the game because the save file cannot find the same item again. ### Step 1: Mark The Equipment Prefab As Addressable 1. Select the equipment prefab asset. 2. Enable `Addressable` in the Inspector. 3. Assign a stable Addressable key.
Use readable, content-stable keys: ``` ccc/equipment/outfits/casual-outfit ccc/equipment/outfits/formal-outfit ccc/equipment/armor/iron-chest-v1 ``` Avoid keys that include random numbers, temporary folder names, or build-specific strings. ### Step 2: Add The Culling Holder And Set The ID Add `Equipment & Body Culling Data Holder` to the equipment prefab root. Set: | Field | Recommended Value | | -------------------------------------- | ------------------------------------------------------------------------------------- | | `Unique ID` | Same as the Addressable key | | `Authoring Slot` | The slot used by this item, for example `Chest` | | `Authoring Reference Character Prefab` | The body prefab used for ghost-body mask painting | | `Authoring Body Renderer Name` | The body renderer name, for example `Body`, when the character has multiple renderers | The `Unique ID` stored on this holder is used by: * runtime registration when no explicit ID is passed * manual body culling mask ownership * equipment-on-equipment mask target lookup * save/load restore paths
If you change this ID after painting masks or shipping saves, repaint or migrate the saved data that references the old ID. ### Step 3: Author Body Culling On The Prefab Use this when the equipment should hide body triangles, but the equipment is not registered on an `EquipmentManager` at design time. 1. Open the equipment prefab in Prefab Mode. 2. Select the prefab root. 3. In `Equipment & Body Culling Data Holder`, assign the `Authoring Reference Character Prefab`. 4. Set `Authoring Body Renderer Name` if needed.
5. Set `Body Culling Mask -> Culling Mode` to `Manual Culling` if you want fully painted masks. 6. Click `Open Body Painter`.
7. Paint the ghost body where this equipment should hide body triangles. 8. Close the painter so the mask writes back to the holder. The editor creates a temporary ghost authoring context. The ghost body is not saved into the equipment prefab and is cleaned up after the painter closes. Use manual body masks when: * Auto Culling removes too much body near garment edges. * Auto Culling misses problem areas on tight clothing. * You want deterministic culling for shipped content. * You are preparing addressable equipment that should behave the same in every scene. Use `Auto Culling` when: * the equipment covers a predictable body area * you prefer runtime detection * the item can work with the culler's probe settings You can combine both: keep the item in `Auto Culling`, paint a manual mask, and let `RuntimeBodyOcclusionCuller` apply manual masks additively when available. ### Step 4: Author Equipment Layer Culling On The Prefab Equipment layer culling hides lower-layer equipment under higher-layer equipment. Example: | Layer | Equipment | | ----- | --------- | | 1 | underwear | | 2 | shirt | | 3 | jacket | | 4 | armor | For an Addressable jacket prefab: 1. Open the jacket prefab in Prefab Mode. 2. Add or select `Equipment & Body Culling Data Holder`. 3. Set `Equipment Layer Culling Mode` to `Manual Culling` or `Auto Culling`. 4. Set `Equipment Occlusion Layer` to `3`. 5. Add lower-layer target prefabs to `Authoring Lower Layer Targets`, such as the shirt prefab. 6. Click `Open Equipment Layer Painter`. 7. Paint which triangles on lower-layer equipment should be hidden by this item. 8. Close the painter to write the mask data back into the holder. **Manual equipment masks reference lower-layer items by stable**** ****`uniqueID`****. Make sure every lower-layer target prefab also has an**** ****`Equipment & Body Culling Data Holder`**** ****with a stable ID.** ### Step 5: Author Equipment Fit Data `EquipmentFitDataHolder` stores Equipment Fit Sculptor deltas on the equipment prefab.
This is the recommended Addressables fit workflow because the fit data travels with the prefab and is automatically imported when the prefab is registered at runtime. **Workflow:** 1. Temporarily register the equipment prefab on an `EquipmentManager` in a setup scene. 2. Click `Open Equipment Fit Sculptor`. 3. Sculpt the equipment until it fits the reference body. 4. Keep `Write Fit to Prefab` enabled. 5. Click `Save`. 6. Confirm the equipment prefab now has `Equipment Fit Data Holder`. 7. Remove the equipment from the design-time `EquipmentManager` list if you want a fully on-demand Addressables setup. At runtime, `EquipmentManager.RegisterEquipmentPrefab` and Addressable resolution import `EquipmentFitDataHolder.meshAdjustments` into the runtime equipment entry. No extra runtime code is needed for the fit data. **Important:** * **Fit data is mesh-vertex-index based. If you replace or re-export the mesh later, recreate the fit data.** * If you clear all sculpt deltas and save, the holder may be removed or left empty. * Keep generated editable mesh assets referenced by the equipment prefab if the fit was made on an editable generated mesh. ### Step 6: Configure Blendshape Sync On The Prefab For Addressable equipment, prefer `BlendshapeSyncConfig` on the equipment prefab.
This lets blendshape rules travel with the prefab instead of relying on a pre-existing `EquipmentManager` entry. 1. Add `Blendshape Sync Config` to the equipment prefab root. 2. In the inspector, assign `Source Body Prefab` under the editor-only authoring section. 3. Choose the `Source Body Renderer`. 4. Configure `Filter Mode`. 5. Add exclusions or include filters. 6. Add manual mappings when automatic matching is not reliable. The `Source Body Prefab` and `Source Body Renderer` fields are editor-only helpers for dropdowns. Runtime sync still uses stored string names, so the equipment prefab does not need to load the source body prefab in a build. #### Exclude Mode Use `Exclude` when most equipment blendshapes should sync, but some should not. Common exclusions: ``` mouth eye brow jaw viseme expression ``` This prevents facial or expression blendshapes on clothing meshes from being matched as body shape sliders. #### Include Mode Use `Include` when only a small set of equipment blendshapes should sync. Example include patterns: ``` breast chest waist hip glute thigh ``` This is safer for third-party equipment that contains many unrelated blendshapes. #### Manual Mapping Use manual mappings when the body and equipment blendshape names differ. Example: | Target Equipment Blendshape | Source Body Blendshape | Scale | Offset | | --------------------------- | ---------------------- | ------ | ------ | | `shirt_breast_large` | `body_breast_large` | `0.85` | `0` | | `shirt_hips_wide` | `body_hips_wide` | `1` | `0` | Use scale below `1` when the clothing should react more subtly than the body. ### Step 7: Configure The Character For On-Demand Loading Add `AddressableEquipmentAssetLoader` to the same GameObject as the `EquipmentManager`, or assign its target `EquipmentManager` field.
Recommended: * `Auto Initialize On Start` disabled for pure on-demand catalogs. * `Auto Initialize On Start` enabled only when you have inspector-registered Addressable entries that should preload at startup. For inventory discovery workflows, you usually do not need to preload. You register catalog entries when the player discovers the item. ### Step 8: Register Discovered Equipment Without Loading The Prefab When the player finds an outfit, register a catalog entry: ```csharp using Arawn.CharacterCreator.Runtime; using UnityEngine; public class OutfitDiscovery : MonoBehaviour { [SerializeField] private EquipmentManager equipmentManager; [SerializeField] private Sprite thumbnail; private const string FormalOutfitKey = "ccc/equipment/outfits/formal-outfit"; public void OnPlayerFoundFormalOutfit() { equipmentManager.RegisterAddressableEquipmentCatalogEntry( addressableKey: FormalOutfitKey, slot: EquipmentSlot.Chest, uiMode: EquipmentUiMode.Normal, uniqueID: FormalOutfitKey, displayName: "Formal Outfit", thumbnailSprite: thumbnail, boneMappingMode: BoneMappingMode.SmartMapping); } } ``` This creates a UI-ready equipment entry with: * `prefab = null` * `Asset Load Mode = Addressable` * `Addressable Key = FormalOutfitKey` * `Unique ID = FormalOutfitKey` The prefab is still not loaded. `EquipmentManager.EquipmentChanged` fires with a `Registered` event, so UI layers such as `CharacterCreatorDemoUI` can rebuild their equipment list. ### Step 9: Equip On Click And Load On Demand When the player clicks `Equip`, use the asset-entry path: ```csharp using System.Collections.Generic; using System.Threading.Tasks; using Arawn.CharacterCreator.Runtime; public async Task EquipFormalOutfitAsync(EquipmentManager equipmentManager) { const string key = "ccc/equipment/outfits/formal-outfit"; string slotId = EquipmentManager.GetBuiltInSlotId(EquipmentSlot.Chest); var entries = new List { new EquipmentAssetEntry( uniqueID: key, addressableKey: key, slot: slotId) }; await equipmentManager.SetEquippedEquipmentFromAssetEntriesAsync(entries); } ``` This one call: 1. Finds the entry if it is already registered. 2. Loads the prefab if needed. 3. Imports `EquipmentFitDataHolder`. 4. Imports `EquipmentAndBodyCullingDataHolder`. 5. Registers blendshape targets. 6. Equips the item. If you are using `CharacterCreatorDemoUI`, the default UI can handle a registered Addressable catalog entry. The entry appears before its prefab is loaded, and clicking `Equip` calls the on-demand load path. ### Step 10: Save With Crystal Save Crystal Character Creator supports two Crystal Save bridge components. #### RememberCharacterPreset Use this when you want to save the full character appearance. It captures: * equipped equipment asset entries * body blendshape values * body part scale values * material colors/floats/textures * Equipment Fit Sculptor deltas * body fit deltas For Addressables, the important field is: ``` CharacterPreset.equippedAssetEntries ``` Each entry stores: | Field | Meaning | | ---------------- | --------------------------- | | `uniqueID` | Stable equipment ID | | `addressableKey` | Key used to load the prefab | | `slot` | Equipment slot | When the save is restored, `ApplyPreset` uses these asset entries to reload missing Addressable equipment. #### RememberEquipmentManager Use this when you only need to save currently equipped equipment. It captures: * equipped unique IDs * equipped asset entries with Addressable keys and slots On restore, it calls the asset-entry restore path. Missing Addressable equipment is loaded through the assigned `IEquipmentAssetLoader`. #### Use One Or Both Recommended setups: | Goal | Components | | ------------------------------------------------ | -------------------------- | | Save full visual character state | `RememberCharacterPreset` | | Save only equipment state | `RememberEquipmentManager` | | Max compatibility and explicit equipment restore | Both | If you use both, keep them on the same character root as `CharacterPresetManager` and `EquipmentManager`. ### Step 11: Save With A Custom Save System If you do not use Crystal Save, save `EquipmentAssetEntry` data yourself: ```csharp [System.Serializable] public class EquipmentSaveData { public List equipped = new List(); } public string SaveEquipment(EquipmentManager equipmentManager) { var data = new EquipmentSaveData { equipped = equipmentManager.GetEquippedEquipmentAssetEntries() }; return UnityEngine.JsonUtility.ToJson(data); } ``` Restore with the async path: ```csharp public async Task LoadEquipmentAsync(EquipmentManager equipmentManager, string json) { EquipmentSaveData data = UnityEngine.JsonUtility.FromJson(json); await equipmentManager.SetEquippedEquipmentFromAssetEntriesAsync(data.equipped); } ``` Always assign the `AddressableEquipmentAssetLoader` before restore. ### What Gets Imported From The Prefab When the Addressable prefab loads and resolves into an `EquipmentPrefab` entry, the manager imports prefab-carried data: | Prefab Component | Imported Into | | ------------------------------------------------------------- | --------------------------------------------------------------------- | | `EquipmentFitDataHolder.meshAdjustments` | `EquipmentPrefab.meshAdjustments` | | `EquipmentAndBodyCullingDataHolder.bodyCullingMask` | `EquipmentPrefab.bodyCullingMask` | | `EquipmentAndBodyCullingDataHolder.equipmentLayerCullingMode` | `EquipmentPrefab.equipmentLayerCullingMode` | | `EquipmentAndBodyCullingDataHolder.equipmentOcclusionLayer` | `EquipmentPrefab.equipmentOcclusionLayer` | | `EquipmentAndBodyCullingDataHolder.equipmentCullingMasks` | `EquipmentPrefab.equipmentCullingMasks` | | `BlendshapeSyncConfig` | Read by `BlendshapeSynchronizer` when the equipped renderers register | This is why prefab-side components are the correct place for Addressable equipment authoring data. ### Thumbnails And UI Addressable catalog entries can appear in UI before their prefab is loaded. You have three options: | Option | Result | | ------------------------------------------------------------------------ | ------------------------------------------------------- | | Pass `thumbnailSprite` during `RegisterAddressableEquipmentCatalogEntry` | UI has an image immediately | | Pass `thumbnailImpostorSprites` | UI can show pinned/rotating previews before prefab load | | Let runtime generation happen after load | Thumbnail appears after the prefab is resolved | For loot discovery UI, pass explicit thumbnails when possible. It avoids loading the prefab only to render a UI icon. ### Game Creator 2 Visual Scripting If you use the Game Creator 2 integration, the same flow can be built with instructions: | GC2 Action | Character Creator Instruction | | ------------------------------------- | ----------------------------------------------------- | | Player discovers an item | `EquipmentManager Register Addressable Catalog Entry` | | Player clicks Equip | `EquipmentManager Equip Addressable By Unique ID` | | Load but do not equip | `EquipmentManager Load Addressable By Unique ID` | | Restore saved equipment asset entries | `EquipmentManager Set Equipped From Asset Entries` | Use `Event On Equipment Registered` to refresh UI or trigger feedback when a catalog entry becomes available. ### Complete Example Flow Example item: ``` Display Name: Formal Outfit Slot: Chest Addressable Key: ccc/equipment/outfits/formal-outfit Unique ID: ccc/equipment/outfits/formal-outfit ``` Authoring: 1. Mark `FormalOutfit.prefab` as Addressable with key `ccc/equipment/outfits/formal-outfit`. 2. Add `Equipment & Body Culling Data Holder`. 3. Set holder `Unique ID` to `ccc/equipment/outfits/formal-outfit`. 4. Assign the reference character prefab and body renderer name. 5. Paint body culling masks through `Open Body Painter`. 6. Configure equipment layer culling if the outfit hides lower-layer equipment. 7. Temporarily register the outfit and use the Equipment Fit Sculptor. 8. Save with `Write Fit to Prefab` enabled so `EquipmentFitDataHolder` is created. 9. Add `Blendshape Sync Config`. 10. Use the source body authoring prefab dropdown to map body blendshapes without typing names manually. 11. Save the prefab. 12. Build Addressables. Runtime: 1. Character spawns with `EquipmentManager`, `AddressableEquipmentAssetLoader`, `RuntimeBodyOcclusionCuller`, and `BlendshapeSynchronizer`. 2. Player finds the outfit. 3. Inventory code calls `RegisterAddressableEquipmentCatalogEntry`. 4. UI receives the registered equipment event and shows the outfit. 5. Player clicks `Equip`. 6. UI calls the async asset-entry restore/equip path. 7. The prefab loads from Addressables and equips. 8. Fit, culling, and blendshape sync settings come from the prefab. 9. Crystal Save stores the currently equipped Addressable entry. 10. Future loads restore the outfit from the saved key. ### Common Mistakes #### Equipment Restores In The Same Session But Not After Restart Cause: * `uniqueID` was generated randomly or differs from the Addressable key used in the save. Fix: * Use the Addressable key as the `uniqueID`. * Set the same value on `EquipmentAndBodyCullingDataHolder.uniqueID`. * Pass the same value to `RegisterAddressableEquipmentCatalogEntry` and `EquipmentAssetEntry`. #### Body Culling Does Not Apply After Addressable Load Cause: * No `EquipmentAndBodyCullingDataHolder` on the prefab. * Holder has no authored mask data. * `RuntimeBodyOcclusionCuller` is missing or body renderer is wrong. * The item was registered under a different ID than the holder/mask data expected. Fix: * Add the holder to the prefab. * Paint masks in Prefab Mode. * Make sure the character has `RuntimeBodyOcclusionCuller`. * Use one stable ID everywhere. #### Equipment Fit Is Lost After Runtime Load Cause: * Fit data only existed on a temporary `EquipmentManager` entry. * `Write Fit to Prefab` was disabled. * The mesh was replaced after fit data was authored. Fix: * Open the sculptor with `Write Fit to Prefab` enabled. * Save again. * Confirm `EquipmentFitDataHolder.meshAdjustments` is populated. * Recreate fit data if the mesh changed. #### Blendshape Sync Does Nothing Cause: * Character has no `BlendshapeSynchronizer`. * `BlendshapeSynchronizer.sourceRenderer` is not assigned. * Equipment prefab has no compatible target blendshapes. * Cross-rig safety skipped Smart Mapping because no explicit mapping exists. * `BlendshapeSyncConfig` filter excludes everything. Fix: * Assign the source body renderer. * Add `BlendshapeSyncConfig` to the prefab root. * Use Include Mode for only the morphs you actually want. * Add manual mappings for important shapes. #### UI Entry Appears But Equip Does Nothing Cause: * No `AddressableEquipmentAssetLoader` assigned. * Addressable key is empty or wrong. * Addressables were not built. * The UI registered a different unique ID than the entry used on equip. Fix: * Add `AddressableEquipmentAssetLoader`. * Use the same key for `uniqueID` and `addressableKey`. * Build Addressables. * Check Console for Addressables load errors. ### Safe Checklist Before Shipping For each Addressable equipment prefab: * Addressable key is stable. * `uniqueID` uses the Addressable key. * `EquipmentAndBodyCullingDataHolder.uniqueID` matches the key. * Body culling mode is intentional. * Manual body mask was tested in play mode. * Equipment layer and lower-layer target IDs are correct. * `EquipmentFitDataHolder` exists when sculpted fit is needed. * `BlendshapeSyncConfig` exists when prefab-owned blendshape rules are needed. * Generated mesh assets referenced by the prefab are included in Addressables. * Addressables have been rebuilt. * Equip was tested in a clean play session with no pre-registered prefab reference. * Crystal Save or custom save restore was tested after restarting play mode. ### Related Docs * [Addressable Equipment On-Demand Loading](/character-creator/basics/addressable-equipment-on-demand-loading.md) * [EquipmentManager](/character-creator/basics/equipment-manager.md) * [Equipment Fit Sculptor](/character-creator/basics/equipment-fit-sculptor.md) * [Blendshape Synchronization](/character-creator/basics/blendshape-synchronization.md) * [Body Culling and Mask Painter](/character-creator/basics/body-culling-and-mask-painter.md) * [Crystal Save Integration](/character-creator/integrations/crystal-save-integration.md) * [Custom Save System Integration](/character-creator/integrations/custom-save-system-integration.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://arawn-software-publishing.gitbook.io/character-creator/tutorials/tutorial-addressable-equipment-prefab-workflow.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.