# Blendshape Creation and Editing
This guide explains the optional Blendshape Creation module for the `Equipment Fit Sculptor`.
The module adds a `Blendshapes` tab to the sculptor. It lets you create new blendshapes from sculpted deltas, preview existing blendshapes, rename blendshapes, delete blendshapes, and load existing blendshapes back into the sculptor for editing.
Use this guide when you want to author blendshape data inside Unity. For runtime copying of body blendshape weights to equipment, see Blendshape Synchronization.
### What This Module Does
The Blendshapes tab is intended for editor-time mesh morph authoring.
You can use it to:
* create a new editable mesh asset for blendshape authoring
* bake existing fit sculpt corrections into the editable mesh base
* create a new blendshape from the current sculpt deltas
* replace an existing blendshape with newly sculpted deltas
* load an existing blendshape into sculpt deltas for editing
* rename existing blendshapes
* delete existing blendshapes
* preview blendshape weights on the selected renderer
* keep the original imported FBX mesh untouched
Typical examples:
* create `Chest_Size` for a shirt after fitting it to the body
* create `Belly_Size` for armor or clothing
* create muscular, slim, or bulky outfit variants
* correct a bad vendor blendshape without leaving Unity
* rename vendor blendshapes to match the character body naming convention
* remove facial/expression blendshapes from an equipment mesh when they are not useful
### What This Module Is Not
This module is not a full DCC replacement.
Do not treat it as:
* a replacement for Blender, Maya, DAZ Studio, or ZBrush
* a general topology editor
* a tool for creating corrective blendshape drivers or expression logic
* a facial animation authoring suite
* a tool for editing blendshape curves over time
* a safe way to destructively edit original imported FBX mesh data
The module is best used for Character Creator workflows where a mesh is already skinned and you need practical morph editing inside Unity.
### Optional Module Behavior
The `Blendshapes` tab only appears when the Blendshape Creation add-on module is present in the project.
In source form, the module lives under:
```
Assets/Arawn/CrystalCharacterCreator/Editor/Modules/Blendshapes
```
### Requirements
Before using the `Blendshapes` tab, make sure:
* the selected object has an `EquipmentManager`
* the Equipment Fit Sculptor can load the target body or equipment renderer
* the target is a `SkinnedMeshRenderer`
* the target renderer has a valid `sharedMesh`
* the mesh can be made readable
* the target mesh vertex count stays stable while editing
* the sculptor preview is correctly aligned before creating editable blendshape assets
The module can create an editable mesh copy when the current mesh comes from an imported model. If the source mesh is imported from an FBX and Read/Write is disabled, the module attempts to enable Read/Write through the model importer and reimport the asset. If Unity cannot make the mesh readable, the operation fails instead of writing unsafe data.
### Recommended Workflow: Fit First, Then Create A Blendshape
This is the safest workflow when you already used the Equipment Fit Sculptor to make equipment fit the body.
Example: you fitted a shirt and now want a `Chest_Size` blendshape.
1. Open the `Equipment Fit Sculptor` from the `EquipmentManager`.
2. Select the shirt mesh in the sculptor.
3. Fit the shirt with `Project`, `Push/Pull`, `Smooth`, `Sliders`, or `Transform`.
4. Open the `Blendshapes` tab.
5. Click `Create Editable Blendshape Mesh Asset`.
6. Confirm the shirt still looks fitted.
7. Sculpt only the chest-size morph.
8. Enter `Chest_Size` in `Blendshape Name`.
9. Keep `Clear Sculpt Deltas` enabled.
10. Keep `Keep Visual Result` enabled if you want the preview to stay visually unchanged after capture.
11. Click `Capture Sculpt Deltas As Blendshape`.
12. Move `Preview Weight` between `0` and `100` to verify the morph.
13. Test in play mode and, if needed, configure runtime sync or UI controls.
The important step is `Create Editable Blendshape Mesh Asset`. It makes the currently fitted shape the new editable mesh base. After that, the next sculpt pass becomes only the desired morph delta.
If you skip that step and immediately capture after fitting, the fit correction itself becomes part of the blendshape. At runtime, the mesh can appear to lose its fit at weight `0` and only regain it when the new blendshape is applied. That is usually not what you want.
### Recommended Workflow: Create A New Morph On An Unmodified Mesh
Use this when the mesh is already in the correct base shape and you only want to add a new morph.
1. Open the `Equipment Fit Sculptor`.
2. Select the target mesh.
3. Open the `Blendshapes` tab.
4. Click `Create Editable Blendshape Mesh Asset`.
5. Sculpt the morph with the normal sculptor tools.
6. Enter a clear `Blendshape Name`.
7. Click `Capture Sculpt Deltas As Blendshape`.
8. Preview and test the result.
If the mesh had no fit corrections before step 4, the editable mesh base is simply a safe copy of the source mesh.
### Recommended Workflow: Edit An Existing Blendshape
Use this when a mesh already has a blendshape but the result needs correction.
1. Open the `Blendshapes` tab.
2. In `Existing Blendshapes`, select the blendshape.
3. Set `Preview Weight` to `100` and inspect the current result.
4. Click `Load To Sculpt Deltas`.
5. The selected blendshape frame is loaded into the sculptor as editable deltas.
6. Adjust the shape with `Push/Pull`, `Smooth`, `Sliders`, or `Transform`.
7. Click `Replace From Deltas`.
8. Preview the result again with `Preview Weight`.
`Load To Sculpt Deltas` uses the last frame of the selected blendshape. The current module writes new blendshapes as a `100` weight frame.
### Data Model
The Blendshapes tab does not overwrite the original imported FBX mesh directly.
When you click `Create Editable Blendshape Mesh Asset`, the module creates a generated editable mesh asset under:
```
Assets/Arawn/CrystalCharacterCreator/Generated/Blendshapes
```
The generated mesh is then assigned to the active renderer and, for equipment prefab targets, written back to the prefab renderer.
This means:
* the original imported model asset remains intact
* the generated mesh asset becomes the mesh used by the prefab
* blendshape names and frames are stored on the generated mesh asset
* the generated mesh asset must stay in the project if the prefab references it
* generated assets are authoring output and are excluded from the core DLL export
Use version control before large blendshape edits. The generated mesh is safer than editing an imported FBX directly, but it is still a project asset.
### Opening The Blendshapes Tab
1. Select a character with `EquipmentManager`.
2. Expand an equipment entry.
3. Click `Open Equipment Fit Sculptor`.
4. Select the desired target in the sculptor.
5. Click the `Blendshapes` tab.
The tab can target body meshes and equipment meshes. For equipment authoring, make sure the target mesh shown in the tab is the equipment mesh you intend to modify.
### UI Reference
#### Target Mesh
`Target Mesh` chooses which loaded renderer the Blendshapes tab edits.
Use it when:
* multiple equipment meshes are loaded
* an equipment prefab contains multiple `SkinnedMeshRenderer`s
* you need to switch between a body mesh and an equipment mesh
Do not assume the visible clothing is the active target. Always confirm this dropdown before creating, replacing, renaming, or deleting blendshapes.
#### Renderer
`Renderer` shows the active `SkinnedMeshRenderer`.
Use it to confirm that the tab is editing the correct object in the scene or prefab preview.
#### Mesh
`Mesh` shows the mesh asset being edited.
If the mesh is an imported model mesh, destructive operations are disabled until you click `Create Editable Blendshape Mesh Asset`.
#### Create Editable Blendshape Mesh Asset
Creates a generated editable mesh asset and assigns it to the selected renderer.
Use this before creating or editing blendshapes when:
* the mesh is imported from an FBX
* the current mesh is not editable
* you have already fit-sculpted the equipment and want that fit to become the new base shape
When clicked from a fitted mesh workflow, the button bakes current sculpt deltas into the editable mesh base. This keeps later blendshape captures relative to the fitted base instead of recording the fit correction as part of the blendshape.
Do not use this casually on the wrong target. It changes the renderer's `sharedMesh` reference to the generated mesh asset and writes that reference back to the equipment prefab when editing equipment.
#### Existing Blendshapes
Shows blendshapes already stored on the editable mesh.
If the list says `None`, the mesh currently has no blendshape frames.
#### Blendshape
Selects which existing blendshape to preview, rename, delete, load, or replace.
#### Preview Weight
Sets the selected blendshape weight on the active renderer for preview.
Use this to inspect the result at `0`, `50`, and `100`.
This is a preview control. Runtime behavior is controlled by your runtime UI, by saved presets, or by `BlendshapeSynchronizer` depending on your project setup.
#### Name
The editable name field for the selected existing blendshape.
Use clear names that match your runtime workflow. If this blendshape should follow a body blendshape through `BlendshapeSynchronizer`, use a compatible name or configure an explicit mapping.
The tool sanitizes `/` and `\` into `_`.
#### Rename
Renames the selected blendshape.
The tool rebuilds the mesh blendshape list internally to preserve the other frames. It refuses empty names and duplicate names.
Use this when:
* vendor names do not match your body names
* you want clearer UI names
* you need names that work better with `BlendshapeSynchronizer`
#### Delete
Deletes the selected blendshape after confirmation.
Use this when:
* the blendshape is not needed
* a facial/expression morph should not exist on equipment
* an old test morph should be removed before shipping
Deleting a blendshape cannot be undone after the mesh asset is saved unless you restore from version control.
#### Load To Sculpt Deltas
Loads the selected blendshape frame into the current sculpt target as editable deltas.
Use this when you want to edit an existing blendshape with the normal sculptor tools.
After loading, the tab sets the selected renderer blendshape weight to `0` so the visible shape is driven by sculpt deltas instead of both the blendshape and the sculpt deltas at the same time.
#### Replace From Deltas
Replaces the selected blendshape with the current sculpt deltas.
Use this after `Load To Sculpt Deltas` and sculpting corrections.
If the current target has no sculpt deltas, the operation fails because there is nothing to capture.
#### Create From Current Sculpt
This section creates a new blendshape from the current target's sculpt deltas.
The sculpt deltas can come from:
* `Push/Pull`
* `Smooth`
* `Sliders`
* `Transform`
* an existing blendshape loaded through `Load To Sculpt Deltas`
#### Blendshape Name
Name for the blendshape that will be created or replaced.
Use stable names if the blendshape will be saved, synced, or referenced by UI. Avoid temporary names for production meshes.
#### Replace Existing
When enabled, capturing with a name that already exists replaces the old blendshape.
When disabled, the tool refuses to capture if a blendshape with the same name already exists.
Use `Replace Existing` when iterating on a morph. Disable it when you want to protect existing shapes from accidental overwrite.
#### Clear Sculpt Deltas
When enabled, sculpt deltas are cleared after capture.
This is recommended for most workflows. Once the deltas have been captured as a blendshape, leaving the same deltas active in the sculptor can make the result appear doubled.
Example:
* sculpt adds chest size
* capture creates `Chest_Size`
* if sculpt deltas stay active and `Chest_Size` is also previewed at `100`, the chest change appears twice
#### Keep Visual Result
Available when `Clear Sculpt Deltas` is enabled.
When enabled, the tab sets the captured blendshape preview weight to `100` after clearing the sculpt deltas. The visual result stays close to what you saw before capture, but it is now driven by the blendshape instead of by sculpt deltas.
When disabled, the preview returns to `0` after capture.
Use `Keep Visual Result` while iterating because it makes capture feel stable. Disable it when you want to immediately inspect the neutral base after capture.
#### Capture Sculpt Deltas As Blendshape
Captures the current sculpt deltas as a blendshape on the editable mesh.
This button is enabled only when the target mesh is an editable mesh asset.
The tool:
1. Reads the current sculpt delta snapshot from the active renderer.
2. Validates that the delta vertex count matches the mesh vertex count.
3. Builds normal deltas when needed.
4. Adds or replaces a `100` weight blendshape frame.
5. Saves the mesh asset.
6. Updates the sculptor mesh base.
7. Optionally clears sculpt deltas and previews the new blendshape.
#### Create Editable Asset And Capture Current Deltas
Creates an editable mesh asset and immediately captures the current sculpt deltas as a blendshape.
Use this only when the current sculpt deltas are intentionally the blendshape delta.
Do not use this after general equipment fitting unless you want the fit correction itself to become the blendshape. For the common "fit first, then create morph" workflow, use `Create Editable Blendshape Mesh Asset` first, then sculpt the morph, then capture.
#### Clear Target Sculpt Deltas
Clears the current sculpt deltas for the active target.
Use this when:
* you loaded a blendshape to deltas but want to abandon the edit
* you captured a shape and want to remove remaining temporary deltas
* the preview looks doubled because both sculpt deltas and blendshape weight are visible
### Naming Guidance
Blendshape names matter because runtime systems often match by name.
Recommended naming:
* `Chest_Size`
* `Belly_Size`
* `Arm_Muscle`
* `Waist_Slim`
* `Breast_Larger`
* `Hips_Wide`
Avoid:
* duplicate names
* names that differ only by punctuation
* names that contain `/` or `\`
* temporary names like `test_01` on production meshes
* names that accidentally match unrelated facial expressions if runtime sync is enabled
If the blendshape should follow a body blendshape, either:
* name it similarly enough for `SmartMapping`, or
* configure `CustomMapped` in the equipment entry, or
* attach `BlendshapeSyncConfig` to the prefab and define the mapping there.
### Body Mesh vs Equipment Mesh Authoring
The tab can target body meshes and equipment meshes, but the risk profile is different.
For equipment meshes:
* creating editable assets is generally safe
* the generated mesh can be assigned back to the equipment prefab
* addressable equipment can carry the edited mesh as part of the prefab dependency
For body meshes:
* changes affect the body mesh used by the selected character setup
* runtime UI and preset systems may reference body blendshape names
* deleting or renaming body blendshapes can break existing UI, presets, or sync mappings
Prefer creating and editing equipment blendshapes unless you explicitly intend to change the character body mesh.
### Addressable Equipment Notes
Addressable equipment prefabs can use blendshape-created generated meshes, but the generated mesh asset must be included as a dependency of the addressable prefab.
Recommended workflow:
1. Open the addressable equipment prefab through the normal Equipment Manager authoring flow.
2. Create the editable blendshape mesh asset.
3. Confirm the prefab renderer references the generated mesh.
4. Save the prefab.
5. Rebuild Addressables after authoring changes.
6. Test in a clean project or play-mode addressable load.
For addressable equipment, prefer storing runtime sync rules on the prefab with `BlendshapeSyncConfig` so the rules travel with the prefab.
### Runtime Sync Is Separate From Authoring
Creating a blendshape only adds morph data to a mesh.
It does not automatically create:
* a UI slider
* a saved preset entry
* a runtime mapping to a body blendshape
* a runtime animation driver
To drive the new blendshape at runtime, use one of these workflows:
* expose it through your UI/presenter system
* save and restore it with `CharacterPresetManager`
* sync it from the body with `BlendshapeSynchronizer`
* control it from your own gameplay code
If you want equipment to follow body blendshapes, configure Blendshape Synchronization after creating the equipment blendshape.
### Safe Workflow Checklist
Before capture:
* confirm `Target Mesh` is correct
* confirm the mesh is editable
* confirm the base fit is already baked into the editable mesh if this is a fitted equipment workflow
* confirm only the intended morph deltas are currently active
* choose a final blendshape name
* decide whether replacement is allowed
After capture:
* preview at `0`, `50`, and `100`
* check for doubled deformation
* test the equipment in play mode
* test with body blendshape sync if applicable
* save the prefab and rebuild Addressables if applicable
* keep generated mesh assets in source control
### Common Mistakes
#### Capturing Fit Corrections As The Blendshape
Symptom:
* the mesh looks unfitted at blendshape weight `0`
* the mesh only looks fitted when the new blendshape is active
* the blendshape seems to include both fit correction and the desired morph
Cause:
* you fitted the equipment and captured directly without first creating an editable base.
Fix:
1. Revert or restore the mesh from version control if needed.
2. Fit the equipment again.
3. Click `Create Editable Blendshape Mesh Asset`.
4. Sculpt only the morph.
5. Capture the morph.
#### Doubled Deformation After Capture
Symptom:
* the morph looks too strong after capture
* the shape appears to be applied twice
Cause:
* sculpt deltas and blendshape preview are both visible.
Fix:
* enable `Clear Sculpt Deltas`
* use `Clear Target Sculpt Deltas`
* set `Preview Weight` to `0` when checking the base shape
#### Editing The Wrong Renderer
Symptom:
* the expected mesh does not change
* another mesh gets a generated blendshape asset
Cause:
* `Target Mesh` pointed to another renderer.
Fix:
* confirm `Target Mesh`, `Renderer`, and `Mesh` before editing
* be careful with equipment prefabs that contain multiple renderers
#### Blendshape Sync Deforms The Wrong Thing
Symptom:
* a body blendshape drives an unrelated equipment morph
Cause:
* `SmartMapping` matched by name similarity but the names mean different things.
Fix:
* use `CustomMapped`
* lower ambiguity by renaming the equipment blendshape
* attach `BlendshapeSyncConfig` and define explicit mappings or exclusions
### Troubleshooting
| Problem | Likely Cause | Fix |
| -------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `Blendshapes` tab is missing | Optional module DLL/source is not installed | Install the Blendshapes module under `Editor/Modules/Blendshapes` or include its editor DLL |
| `Capture Sculpt Deltas As Blendshape` is disabled | Mesh is not an editable mesh asset | Click `Create Editable Blendshape Mesh Asset` first |
| Capture says there are no sculpt deltas | No active sculpt changes on the target | Sculpt the morph first, or load an existing blendshape to sculpt deltas |
| Capture says vertex counts do not match | Mesh changed after deltas were created | Clear deltas, recreate the editable asset, or restart the sculptor |
| Mesh becomes unfitted at weight `0` | Fit correction was captured as a blendshape | Create the editable mesh asset before sculpting the morph |
| Morph appears doubled | Sculpt deltas were not cleared after capture | Enable `Clear Sculpt Deltas` or click `Clear Target Sculpt Deltas` |
| Rename fails | Name is empty or already exists | Use a unique non-empty name |
| Delete removed the wrong shape | Wrong blendshape selected | Restore from version control, then verify the `Blendshape` dropdown before deleting |
| Runtime equipment does not react to new blendshape | No runtime driver or sync mapping configured | Add UI control, preset support, or configure `BlendshapeSynchronizer` |
| Addressable prefab loads without the new mesh | Addressables were not rebuilt after editing | Save the prefab and rebuild Addressables |
### Related Docs
* Equipment Fit Sculptor
* Blendshape Synchronization
* EquipmentManager
* Custom UI Integration
* Custom Save System Integration
### Related Files
* `Assets/Arawn/CrystalCharacterCreator/Editor/Modules/Blendshapes/EquipmentBlendshapeSculptorTab.cs`
* `Assets/Arawn/CrystalCharacterCreator/Runtime/BlendshapeSynchronizer.cs`
* `Assets/Arawn/CrystalCharacterCreator/Runtime/BlendshapeSyncConfig.cs`
* `Assets/Arawn/CrystalCharacterCreator/Runtime/BlendshapeSyncTarget.cs`
* `Assets/Arawn/CrystalCharacterCreator/Runtime/EquipmentManager.cs`
---
# Agent Instructions: 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/add-on-modules/blendshape-creation-and-editing.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.
