### Start Local Development Server

Source: https://github.com/bdunderscore/modular-avatar/blob/main/docs~/README.md

Starts a local development server for live previewing changes. The browser will open automatically.

```bash
$ yarn start
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/bdunderscore/modular-avatar/blob/main/docs~/README.md

Run this command to install all necessary project dependencies using Yarn.

```bash
$ yarn
```

--------------------------------

### Menu Installer Configuration

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Configure the ModularAvatarMenuInstaller to install an Expressions Menu into the avatar's menu tree at build time. The install target can be changed by the end-user. Inline menus can be added directly to the same GameObject.

```csharp
// Prefab developer setup:
// MyGimmick
//   ├─ ModularAvatarMenuInstaller   ← installs "GimmickMenu" into the avatar menu
//   ├─ ModularAvatarParameters
//   └─ ...

// Inspector settings (ModularAvatarMenuInstaller component):
//   Install target menu : (blank = top level of avatar menu)  ← end-user configurable
//   Menu to install     : Assets/MyGimmick/GimmickMenu.asset   ← set by prefab author

// Inline menus (no separate asset needed):
// Just add MA Menu Item OR MA Menu Group on the same GameObject as the Menu Installer.
// MA will generate the menu items from the component instead of a menu asset.

// Extending another asset's menu:
//   Install target menu : drag the submenu asset used by another Menu Installer
//   MA will append your items to that submenu at build time.

// Overflow handling:
//   When the target menu has more than 8 items, MA automatically creates
//   a "next ->" submenu page and continues appending there.
```

--------------------------------

### Sync Parameter Sequence Setup

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Add ModularAvatarSyncParameterSequence to your avatar's root to ensure parameter order consistency across platforms. Upload the PC build first to establish the correct order.

```plaintext
// Scene hierarchy:
// MyAvatar                  ← add ModularAvatarSyncParameterSequence here

// Inspector settings:
//   Primary Platform : PC   ← upload PC build first

// Workflow:
//   1. Set up your full avatar on PC (all synced parameters present).
//   2. Upload PC build — MA records the parameter order.
//   3. Set up Android variant (may have fewer non-synced parameters).
//   4. Upload Android build — MA reorders parameters to match PC order,
//      inserting placeholders for any parameters missing on Android.

// VRChat per-platform overrides:
//   Add MA Sync Parameter Sequence only to the base avatar.
//   It will automatically propagate missing parameters to override avatars.
```

--------------------------------

### Merge Armature Setup

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Use ModularAvatarMergeArmature to merge a clothing/accessory bone hierarchy onto the base avatar's armature. The 'Setup Outfit' shortcut simplifies configuration.

```csharp
// Scene hierarchy before build:
// MyAvatar (VRC Avatar Descriptor)
//   └─ SailorOutfit
//        └─ Armature              ← add ModularAvatarMergeArmature here
//             ├─ SailorOutfit_Hips
//             └─ ...

// Inspector settings (ModularAvatarMergeArmature component):
//   Merge Target   : MyAvatar/Armature/Hips   (drag avatar's Hips bone)
//   Prefix         : "SailorOutfit_"          (auto-detected by Setup Outfit)
//   Suffix         : ""
//   Lock mode      : Base =======> Target (Unidirectional)
//   Avoid name collisions: ✓ (checked)

// Shortcut – right-click the outfit root in the Hierarchy and choose:
//   [ModularAvatar] Setup Outfit
// MA will auto-detect the armature, set Merge Target, and configure the prefix.

// Nested merge example:
// Outfit B's Merge Armature targets Outfit A, which itself targets the base avatar.
// MA resolves dependency order automatically.

// Reset bone positions to base avatar (inspector button):
//   "Do It!" with options:
//     □ Also set rotation
//     □ Also set local scale
//     ☑ Adjust outfit overall scale to match base avatar  ← recommended
```

--------------------------------

### Extend Modular Avatar Build Pipeline with NDMF

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Use NDMF to hook into the Modular Avatar build pipeline. This C# example shows how to run custom logic before or after MA's processing phases.

```csharp
// Package: your-package/Editor/MyPlugin.cs
using nadena.dev.ndmf;
using nadena.dev.ndmf.fluent;

[assembly: ExportsPlugin(typeof(MyAvatarPlugin))]

namespace com.example.my_avatar_plugin
{
    public class MyAvatarPlugin : Plugin<MyAvatarPlugin>
    {
        // Plugin qualified name (stable across versions):
        public override string QualifiedName => "com.example.my_avatar_plugin";
        public override string DisplayName   => "My Avatar Plugin";

        protected override void Configure()
        {
            // Run BEFORE Modular Avatar processes its own components.
            // Ideal for generating MA components programmatically.
            InPhase(BuildPhase.Generating)
                .BeforePlugin("nadena.dev.modular-avatar")
                .Run("Generate MA components", ctx =>
                {
                    var avatarRoot = ctx.AvatarRootObject;

                    // Example: add a Merge Armature component to an outfit at build time
                    var outfit = avatarRoot.transform.Find("MyDynamicOutfit");
                    if (outfit != null)
                    {
                        var ma = outfit.gameObject.AddComponent
                            <nadena.dev.modular_avatar.core.ModularAvatarMergeArmature>();
                        ma.mergeTarget = new nadena.dev.modular_avatar.core.AvatarObjectReference();
                        ma.mergeTarget.referencePath = "Armature/Hips";
                    }
                });

            // Run AFTER Modular Avatar has finished (e.g. post-processing cleanup).
            InPhase(BuildPhase.Optimizing)
                .AfterPlugin("nadena.dev.modular-avatar")
                .Run("Post-process avatar", ctx =>
                {
                    // ctx.AvatarRootObject is the fully merged, processed avatar
                });
        }
    }
}
```

--------------------------------

### Convert Constraints Setup

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Add ModularAvatarConvertConstraints to your avatar root to non-destructively convert Unity constraints to VRChat constraints at build time. This component is automatically added by VRCSDK's 'Auto Fix' if absent.

```plaintext
// Scene hierarchy:
// MyAvatar     ← add ModularAvatarConvertConstraints here (avatar root recommended)

// No configuration options.
// When MA is installed, the VRChat VRCSDK "Auto Fix" button automatically
// adds this component to the avatar root if it is absent.

// To disable constraint conversion for debugging:
//   Simply remove the ModularAvatarConvertConstraints component.
//   No other changes are needed.
```

--------------------------------

### Build Static Website Content

Source: https://github.com/bdunderscore/modular-avatar/blob/main/docs~/README.md

Generates the static website content into the 'build' directory, ready for hosting.

```bash
$ yarn build
```

--------------------------------

### Deploy Website Using SSH

Source: https://github.com/bdunderscore/modular-avatar/blob/main/docs~/README.md

Deploys the website using SSH. Ensure your SSH keys are configured correctly.

```bash
$ USE_SSH=true yarn deploy
```

--------------------------------

### Configure Mesh Settings for Consistent Rendering

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Use ModularAvatarMeshSettings to propagate anchor override and bounding box settings to all SkinnedMeshRenderers in a subtree. This ensures consistent lighting and culling across all meshes. 'Set or inherit' mode is recommended for outfit prefabs.

```csharp
// Scene hierarchy:
// MyAvatar                    ← add ModularAvatarMeshSettings here for global settings
//   └─ SailorOutfit
//        └─ SailorTop_Mesh    ← optionally add another for outfit-specific override

// ModularAvatarMeshSettings on MyAvatar:
//   Anchor Override Mode : Set
//   Anchor Override      : MyAvatar/AnchorPoint    (drag a Transform)
//   Bounds Override Mode : Set
//   Root Bone            : MyAvatar/Armature/Hips
//   Bounds               : Center (0,1,0)  Extents (0.5, 1, 0.5)

// Override modes:
//   Inherit      – no effect; defers to parent Mesh Settings
//   Set          – applies this component's settings to all children
//   Don't set    – blocks parent settings from propagating further
//   Set or inherit – uses parent if available, otherwise this component's settings
//                    (recommended for outfit prefabs)

// "Setup Outfit" automatically adds a Mesh Settings component with
// "Set or inherit" mode to new outfit prefabs.

```

--------------------------------

### Deploy Website Without SSH

Source: https://github.com/bdunderscore/modular-avatar/blob/main/docs~/README.md

Deploys the website without using SSH. Replace '<Your GitHub username>' with your actual GitHub username.

```bash
$ GIT_USER=<Your GitHub username> yarn deploy
```

--------------------------------

### Manual Bake Avatar Workflow

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Manually bake Modular Avatar transformations to a scene copy without entering Play Mode. This is useful for debugging and exporting to non-VRChat platforms.

```plaintext
// Trigger via context menu:
//   Right-click your avatar in the Hierarchy
//   → Modular Avatar → Manual bake avatar

// Output:
//   A cloned avatar is created in the scene with all MA transformations applied.
//   Generated assets are saved to:
//     Assets/ModularAvatarOutput/

// Unpacking generated assets:
//   Select the ModularAvatarOutput file in the Project window.
//   Click "Unpack" in the Inspector.
//   Assets are split into individual files for inspection.

// Cleanup:
//   Delete the cloned baked avatar from the scene.
//   It is then safe to delete Assets/ModularAvatarOutput/ as well.

// Non-VRChat platforms (e.g. Resonite):
//   Open Tools → NDM Framework → NDMF Console
//   Select avatar, set Avatar Platform to "Resonite", then click Build.
```

--------------------------------

### Bone Proxy Reparenting

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Use ModularAvatarBoneProxy to reparent a prefab object into any existing bone of the avatar at build time. It automatically fixes animator path references.

```csharp
// Scene hierarchy:
// MyAvatar
//   └─ FingerPenGimmick
//        └─ RightHandCollider   ← add ModularAvatarBoneProxy here

// Inspector settings (ModularAvatarBoneProxy component):
//   Target           : MyAvatar/Armature/Hips/Spine/.../Hand.R   (drag target bone)
//   Attachment mode  : As child at root      ← for non-avatar-specific prefabs
//                   OR As child keep world pose ← for precise avatar-specific placement

// Advanced options:
//   □ Match Parent Scale   – sets local scale to (1,1,1) after reparenting
//                            useful for accessories that must stay the same
//                            relative size as the target bone

// After build the object is located at:
//   MyAvatar/Armature/.../Hand.R/RightHandCollider
// Any animator clips that animated "FingerPenGimmick/RightHandCollider/..."
// are automatically rewritten to the new path.
```

--------------------------------

### Run Code in Generating Phase with NDMF

Source: https://github.com/bdunderscore/modular-avatar/blob/main/docs~/docs/extending.md

Use this pattern to execute custom code during the Generating phase of Modular Avatar processing. It allows you to run logic before or after specific NDMF plugins, including Modular Avatar's own processing.

```csharp
using nadena.dev.ndmf;

[assembly: ExportsPlugin(typeof(SetViewpointPlugin))]

namespace nadena.dev.ndmf.sample
{
    public class MyPlugin : Plugin<MyPlugin>
    {
        protected override void Configure()
        {
            InPhase(BuildPhase.Generating)
                .BeforePlugin("nadena.dev.modular-avatar")
                .Run("Do something", ctx => { /* ... */ });
        }
    }
}
```

--------------------------------

### Configure Avatar Parameters with Modular Avatar

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Defines, renames, and configures animator parameters. Prevents name collisions by auto-renaming parameters at build time and registers synced/saved parameters.

```csharp
// Prefab structure:
// MyGimmick
//   ├─ ModularAvatarParameters          ← parameter declarations
//   │     ┌──────────────────────────────────────────────┐
//   │     │ Name      │ Type  │ Change to │ Default │ Saved │ Synced │
//   │     ├──────────────────────────────────────────────┤
//   │     │ GimmickOn │ Bool  │ (auto)    │ false   │ ☑     │ ☑      │
//   │     │ Intensity │ Float │ (auto)    │ 0.5     │ ☑     │ ☑      │
//   │     │ InternalA │ Animator Only │   │         │       │        │
//   │     │ PB_       │ Prefix│          │         │       │        │
//   │     └──────────────────────────────────────────────┘
//   └─ FX.controller  (references "GimmickOn" and "Intensity")
```

```csharp
// At build time MA renames "GimmickOn" to e.g. "MA/MyGimmick/abc123/GimmickOn"
// ensuring it never conflicts with another prefab's "GimmickOn" parameter.
```

```csharp
// Connecting two gimmicks intentionally (both use the same external parameter):
//   GimmickA/ModularAvatarParameters: GimmickOn → Change name to: SharedToggle
//   GimmickB/ModularAvatarParameters: GimmickOn → Change name to: SharedToggle
// Both gimmicks now share the same synced parameter "SharedToggle".
```

```csharp
// Nesting:
//   Inner MA Parameters renames "foo" → "bar"
//   Outer MA Parameters renames "bar" → auto
//   Objects between inner and outer can still reference "bar" as usual.
```

--------------------------------

### Create Global Colliders for Inter-Avatar Physics

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Add ModularAvatarGlobalCollider to create a VRChat 'global collider' that can physically interact with other avatars' PhysBones. This component hijacks one of the avatar's built-in finger/body colliders at build time. Use sparingly due to VRChat's limit of 6 global colliders.

```csharp
// Scene hierarchy:
// MyWeapon
//   └─ BarrelTip     ← add ModularAvatarGlobalCollider here

// Inspector settings (ModularAvatarGlobalCollider component):
//   Shape         : Capsule (or Sphere — same as VRCPhysBoneCollider)
//   Radius        : 0.05
//   Height        : 0.2
//   □ Manual Remap         ← leave unchecked unless you need to specify
//                             which finger collider to hijack
//   □ Low Priority Collider ← mark as replacable if another asset needs the slot

// VRChat limit: 6 global colliders maximum before the index finger collider
// is overwritten. Use sparingly.

// Example use cases:
//   • Recoil/shockwave: animate the GlobalCollider object's position to sweep
//     through other avatars' PhysBones.
//   • Bite effect: place on mouth bone to interact with others' ear PhysBones.

```

--------------------------------

### Replace Object Functionality

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Use ModularAvatarReplaceObject to replace an existing avatar GameObject with one from a prefab. It rewrites component cross-references and updates animation paths.

```csharp
// Scene hierarchy:
// MyAvatar
//   └─ Body              ← original body mesh (SkinnedMeshRenderer)
// ReplacementPrefab
//   └─ Body_Custom       ← add ModularAvatarReplaceObject here

// Inspector settings (ModularAvatarReplaceObject component):
//   Target Object : MyAvatar/Body   (drag the original object to replace)

// Result after build:
//   • Body_Custom occupies the slot where Body was
//   • Children of both Body and Body_Custom are merged under Body_Custom
//   • All animator paths referencing "Body" are updated to "Body_Custom"
//   • Component references (e.g. PhysBone → SkinnedMeshRenderer) are remapped
//     by index; mismatched component types are nulled out

// Limitations:
//   Only one Replace Object may target each GameObject.
//   Component fuzzy-matching is not performed (BoxCollider ≠ SphereCollider).
```

--------------------------------

### Block Parent PhysBone Chain with PhysBone Blocker

Source: https://context7.com/bdunderscore/modular-avatar/llms.txt

Add ModularAvatarPhysBoneBlocker to a child accessory to prevent a parent PhysBone chain from affecting it. The child is added to the PhysBone's Ignore list at build time. This component has no configuration options.

```csharp
// Scene hierarchy:
// MyAvatar
//   └─ Armature
//        └─ Tail_Root (VRCPhysBone — affects all children)
//             └─ TailAccessory   ← add ModularAvatarPhysBoneBlocker here
//                  └─ Pendant    (uses its own VRCPhysBone, not affected by Tail)

// No configuration options.
// Combine with Bone Proxy to attach an accessory rigidly to a PhysBone chain:
//   TailAccessory
//     ├─ ModularAvatarBoneProxy   (Target = Tail_Root/Tail_Bone_3)
//     └─ ModularAvatarPhysBoneBlocker

```