Blendshape Synchronization

BlendshapeSynchronizer copies blendshape weights from the character body mesh to equipped item meshes at runtime.

Typical use case:

• Body has CDG_BODY_FULL.breast_smaller

• Outfit has SUIT.breast_smaller

• Changing the body blendshape also updates the equipped outfit blendshape

Important: Configuration Ownership (Current Workflow)

Most blendshape matching behavior is now configured per equipment item in EquipmentManager.

BlendshapeSynchronizer is primarily the runtime sync engine.

Where to Configure What

Location	Purpose
BlendshapeSynchronizer component	Source body renderer and sync timing/runtime behavior
EquipmentManager -> Equipment Prefabs -> Blendshape Matching	Per-item enable/disable, match mode, threshold, and custom mappings

What It Solves

When equipment is equipped at runtime, those meshes are created dynamically. BlendshapeSynchronizer auto-registers runtime equipment renderers (through EquipmentManager) and keeps them in sync with the source body.

Requirements

• BlendshapeSynchronizer and EquipmentManager on the same GameObject

• BlendshapeSynchronizer.sourceRenderer assigned to the character body SkinnedMeshRenderer

• target/equipment meshes contain compatible blendshape names (or explicit custom mappings)

One-Click Setup

Use: Tools/Character Creator/Character Creator Setup Wizard

The wizard configures:

• BlendshapeSynchronizer component

• sourceRenderer from your selected Source Body Mesh

EquipmentManager Per-Item Settings (Primary)

In each equipment entry (EquipmentManager -> Equipment Prefabs), use:

• Enable Blendshape Sync

  • excludes this equipment from runtime sync when disabled

• Blendshape Match Mode

  • SmartMapping (default): exact first, fuzzy fallback

  

  • CustomMapped: explicit target->source mapping rows

• Match Threshold (shown for SmartMapping)

  • higher = stricter fuzzy matching

• Custom Mappings + Auto-Populate Blendshape Mappings (shown for CustomMapped)

Exact and Fuzzy remain in enum for backward compatibility but are hidden in the inspector dropdown.

BlendshapeSynchronizer Component Settings (Secondary)

On the BlendshapeSynchronizer component:

• sourceRenderer (required)

• syncInterval

• syncOnRegister

• noiseWords (global fuzzy token cleanup)

• debugMatching (verbose matching logs)

These are shared runtime settings, while actual matching strategy is item-specific in EquipmentManager.

Cross-Rig / Re-Skinned Behavior

For cross-rig baked assets, sync may be intentionally skipped unless explicitly configured:

• Bake Re-Skinned Prefab (Experimental) sets Enable Blendshape Sync = false on the updated equipment entry by default.

• Runtime safety check also skips sync when all of these are true:

  • skipRuntimeRootAlignment = true

  • blendshapeMatchMode = SmartMapping

  • no custom blendshape mappings

This prevents aggressive auto-matches from deforming cross-rig equipment.

If you want sync on a baked cross-rig item, enable sync explicitly and prefer CustomMapped with validated mappings.

Custom Mapping Workflow

When an equipment entry uses CustomMapped:

1. Expand that equipment entry in the EquipmentManager inspector.

2. In Blendshape Matching, add mapping rows:

   • left: target/equipment blendshape

   • right: source/body blendshape

3. Use Auto-Populate Blendshape Mappings as a starting point.

4. Manually validate and correct problematic rows.

Runtime Behavior

• Sync runs every syncInterval.

• On equip:

  • equipment renderers are registered automatically (if allowed by per-item settings/safety checks)

  • optional immediate push via syncOnRegister

  • SyncNow() is triggered after equipment changes

• On unequip:

  • equipment renderers are unregistered

This is event-driven via EquipmentManager.EquipmentChanged.

Runtime API (Common)

• SyncNow() - force immediate full sync pass

• RegisterTarget(...) / RegisterTargets(...) - manually add target renderer(s)

• UnregisterTarget(...) / UnregisterTargets(...) - manually remove target renderer(s)

• RegisterCurrentlyEquippedTargets(syncImmediately) - safety re-register pass

• AutoPopulateCustomMappings(replaceExisting) - generate custom mapping entries

Troubleshooting

Problem	Likely Cause	Fix
Equipment blendshapes do not react	sourceRenderer missing or wrong	Assign body mesh as sourceRenderer
Nothing syncs on equip	BlendshapeSynchronizer missing or not on same object as EquipmentManager	Put both on same character root
One specific item does not sync	Enable Blendshape Sync disabled on that equipment entry	Enable it in the item's Blendshape Matching section
Baked cross-rig item does not sync	Safety skip condition active, or bake disabled per-item sync	Enable sync and use CustomMapped mappings for that item
Wrong auto-match deformation	SmartMapping matched unrelated names	Use CustomMapped and validate mappings manually
CustomMapped appears to do nothing	Mapping list empty/incorrect	Auto-populate mappings, then verify row-by-row
Sync feels delayed	syncInterval too high	Lower syncInterval or call SyncNow()