Lots of docs updates

docs/docs/intro.md

@@ -8,11 +8,8 @@ Modular Avatar is a suite of **non-destructive** tools for modularizing your ava
 components.
 With Modular Avatar, adding a new outfit or gimmick to your avatar is as easy as drag-and-drop!
 
-Modular Avatar currently supports:
+Modular Avatar's features are packaged as individual components, which can be added as needed. You can opt-in to just the features
-
+you want to use. It can automatically merge outfits onto your avatar, build an animator out of multiple components, and much more.
-* Merging prefab armatures into the parent avatar, as is often done to add outfits. MA minimizes the number of bones
-  that are created in this process, reusing existing bones where possible.
-* Merging subcomponent animators into the parent avatar, for use with various types of avatar gimmicks.
 
 :::caution
 
@@ -22,86 +19,11 @@ be made prior to version 1.0. As such, it is not recommended to distribute prefa
 
 :::
 
-## Merging outfits (and similar things)
+To install Modular Avatar, download and import the `unitypackage` file from the "Assets" section on [the latest release](https://github.com/bdunderscore/modular-avatar/releases).
 
-![img_1.png](img_1.png)
+Then, check out one of the tutorials below:
+* [Simple clothing setup](tutorials/clothing)
 
-By attaching the Modular Avatar Merge Armature script to the armature of an outfit, Modular Avatar will merge this
+You can also check out some of the [detailed reference documentation](reference) on individual components.
-outfit armature into the parent armature automatically at build or play time. The result looks a bit like this:
 
-![img_3.png](img_3.png)
+Finally, if you are developing your own prefabs using Modular Avatar, check out the [page on prefab distribution](distributing-prefabs).
-
-Note that new bones have only been created for bones that are present only in the outfit.
-
-The Merge Armature script will automatically find corresponding bones under the Merge Target for each bone under the
-transform it is attached to. It assumes each bone under the prefab to be merged to start with the Prefix and end with
-the Suffix. If it finds an object that does not match, or if it can't find a corresponding base object, it will attach
-this transform as a new child object in the base avatar (this can be used for bones corresponding to e.g. skirts or
-ribbons).
-
-The outfit can be enabled or disabled (including physbones and other dynamics) simply by toggling the prefab. To
-facilitate this, any physbones or other components on the armature bones will remain at their old location, but will be
-adjusted to reference the bones in the armature instead. For PhysBones and contacts, the root transform will be set to
-point to the corresponding armature bone. For other components, a parent constraint will be automatically generated if
-necessary.
-
-Note also that as part of the armature merge, skinned meshes are adjusted (bindposes recalculated) in order to be
-compatible with the base avatar's mesh. This means that outfits generated using different 3D software are still
-compatible.
-
-If fine adjustments to positioning are required, they can be made to the prefab armature before merging; as long as
-the 'locked' option (described later) is disabled, the world position of the bones will be retained (effectively, it
-will behave as if each bone was moved inside the corresponding bone in the base avatar).
-
-## Merging more complex gimmicks
-
-For gimmicks involving animators, Modular Avatar has a `Merge Animator` component.
-
-![img_4.png](img_4.png)
-
-This component will merge the specified animator controller into the corresponding Avatar 3.0 playable layer.
-If `Delete Attached Animator` is enabled, any animator on the same gameobject will also be deleted (having such an
-animator around can be handy for editing animations).
-
-In order to ease editing, animations on a merged animator should have their clips created based off of the location of
-the Merge Animator script in the hierarchy. In other words, you don't cite the path up to the merge animator script, but
-only the path from that point:
-
-![img_5.png](img_5.png)
-
-If you use the unity 'record animation' mode to record an animation on an animator on the same game object, this should
-all Just Work.
-
-### Placing objects elsewhere in the avatar
-
-Your gimmick may sometimes need to put objects (eg contacts) at other places in the hierarchy. To do this, you could use
-the Merge Armature script as described above, but this depends on matching up bone names and positions, and so is not
-ideal for a gimmick that is meant to work with any avatar.
-
-Instead, you can use the `Modular Avatar Proxy Bone` component. Attaching this component to a transform will cause that
-transform to match its position and orientation to the humanoid bone (or sub-bone) in question.
-
-![img_6.png](img_6.png)
-
-Just drag the transform your want to reference onto Target, and the bone reference and sub path will be automatically
-configured.
-
-At build time, the proxy bone object will be moved under the actual bone in question, and animation references will be
-updated to match.
-
-### Animating humanoid bones
-
-Normal humanoid animations can be used with merged animators without special setup.
-
-### Animating non-humanoid bones
-
-When animating non-humanoid bones (e.g. cat ears), some special setup is needed. Use a `Modular Avatar Merge Armature`
-component with the `Locked` setting enabled:
-
-![img_7.png](img_7.png)
-
-When locked is enabled, the base bone and prefab bone will be locked together; if you move one, the other will move.
-This means you can move your prefab's merge-armature proxy bones when recording an animation, and the corresponding
-base-avatar bone will also update, making it easy to see what you're doing.
-
-At build time, these proxy bones will be merged into the base avatar, so they won't count against performance stats.

docs/docs/reference/blendshape-sync.md

@@ -0,0 +1,40 @@
+import ReactPlayer from 'react-player'
+
+# Blendshape Sync
+
+![Blendshape Sync](blendshape-sync.png)
+
+The Blendshape Sync component allows you to ensure that a particular blendshape on one renderer always matches that of another.
+
+<ReactPlayer controls muted loop playsinline url='/img/blendshape-sync.mp4' />
+
+## When should I use it?
+
+Often, avatars will have blendshapes to adjust the shape of their body. If you are creating (or using) an outfit for such an avatar, and the outfit has a matching shapekey, Blendshape Sync is the component for you!
+
+This can also be useful in base avatars as well - to sync up blendshapes between different objects.
+
+## When shouldn't I use it?
+
+Blendshape Sync always copies the same value from one renderer's blendshape to another. If the scale or animation curves need to be different, then it will not work properly.
+
+Blendshape Sync does not support copying values where the blendshape name isn't exactly the same on both renderers.
+
+## Setting up Blendshape Sync
+
+Add the Blendshape Sync component to an object in your prefab. Then click the + button to open a selection window.
+
+![Selection window](blendshape-select-1.png)
+
+Double-click on a blendshape to add it to the list to sync. When you've added enough, click the X to close the editor window.
+
+Blendshape Sync supports multi-selection editing as well, so you can select multiple meshes to configure at once.
+
+Note that blendshape sync currently does not support syncing through multiple levels of objects (object A -> object B -> object C).
+
+### What does it do, exactly?
+
+Blendshape Sync does two things:
+
+* In edit mode, it copies the blendshape values from the base automatically, so changes to the base object's shapekeys will take effect in the other objects immediately.
+* In play mode, it modifies any animations which animate the base object's blendshapes to also animate the other objects' blendshapes.

docs/docs/reference/bone-proxy.md

@@ -1,5 +1,29 @@
----
+# Bone Proxy
-sidebar_position: 3
----
 
-TODO
+![Bone Proxy](bone-proxy-compare.png)
+
+The Bone Proxy allows you to place objects from your prefab inside of objects that are part of the original avatar.
+For example, in the Clap sample, this is used to place contacts inside the avatar's hands.
+
+Bone Proxy will also adjust any animators referencing the old location of the objects so that they reference the
+new paths after the objects are moved.
+
+## When should I use it?
+
+Bone Proxy should be used when you have objects that you want to place inside of existing objects inside the avatar.
+
+## When shouldn't I use it?
+
+Bone Proxy isn't intended to be used to configure clothing. Try using [Merge Armature](merge-armature.md) instead.
+
+## Setting up Bone Proxy
+
+Add the Bone Proxy component to an object in your prefab, and drag the destination of this object to the "Target" field.
+The Bone Proxy-annotated object will then be placed inside the target object.
+
+### Usage in prefabs
+
+The Bone Proxy component automatically translates the object you specify into a humanoid bone and relative path reference.
+This ensures that it can restore this reference automatically after it is saved in a prefab.
+
+If you want to adjust the internal references, you can see them in the Advanced foldout.

docs/docs/reference/menu-installer.md

@@ -1,5 +1,26 @@
----
+# Menu Installer
-sidebar_position: 4
----
 
-TODO
+The Modular Avatar Menu Installer allows you to easily add menu items to the avatar's expressions menu.
+Unlike the other components, it is not fully automatic, and requires the end-user to select which menu to install to.
+
+![Menu Installer](menu-installer.png)
+
+## When should I use it?
+
+When you have a menu item to add!
+
+## How do I use it?
+
+### End-users
+
+Click "Select Menu" and double-click the menu you want to install the prefab's controls to. Done!
+
+If the selected menu gets full, it will be automatically split into multiple pages (submenus).
+
+### Prefab developers
+
+First, create an expressions menu with the controls you want to add. This menu will be _appended_ to a selected submenu of the avatar's Expressions Menu tree.
+As such, if you want a submenu of your own, you will need to create two menu assets: One for the submenu control, and one for the inner menu itself.
+
+Add a Menu Installer component to your prefab, at the same level as your [Parameters](parameters.md) component.
+Then, open the Prefab Developer Options tag, and add the desired menu to "Menu to install". Done!

docs/docs/reference/merge-animator.md

@@ -1,5 +1,43 @@
----
+# Merge Animator
-sidebar_position: 2
----
 
-TODO
+![Merge Animator](merge-animator.png)
+
+The merge animator component will add the provided animator to a specified layer of the avatar it is added to. This can be used to make complex AV3 gimmicks that install themselves just by dragging and dropping onto an avatar.
+
+Two samples are included that use this component: A hand-clap effect, and a finger-pen gimmick.
+
+## When should I use it?
+
+Merge Animator should be used when you have animations you'd like to play back as part of your gimmick.
+
+## When shouldn't I use it?
+
+Merge Animator adds to, but does not replace existing animator layers. If you want the end-user to completely replace an animator layer, it may be better to have them replace it in the avatar descriptor in the traditional way.
+
+## Setting up Merge Animator
+
+Add the Merge Animator component to an object in your prefab, and attach the animator in the "Animator to merge" field. Set the "Layer Type" field to the avatar layer this should be added to (e.g. FX).
+
+### Recording animations
+
+By default, paths in your animator are interpreted as relative to the merge animator component. This makes it easy to record new animations, provided you're animating object underneath the Merge Animator component.
+
+Just attach an Animator component to your GameObject, and you can use the Animation panel to record animations:
+
+![Recording an animation using Merge Animator](merge-animator-record.png)
+
+As a development convenience, you can check the "Delete attached animator" box to remove the animator component at build time.
+
+### Humanoid bone animations
+
+Animations that move humanoid bones ignore the relative path logic, and will always apply to the overall avatar. As such most humanoid animations (e.g. AFK animations) can be used as-is.
+
+### Absolute path mode
+
+If you want to animate objects that are already attached to the avatar (that aren't under your object), set the path mode to "Absolute". This will cause the animator to use absolute paths, and will not attempt to interpret paths relative to the Merge Animator component.
+This means you will need to record your animations using the avatar's root animator instead.
+
+### Write Defaults
+
+By default, the write defaults state of your animator will not be changed. If you want to ensure that the WD settings of your animator states always matches the avatar's animator, click "Match Avatar Write Defaults".
+This will detect whether the avatar is using write defaults ON or OFF states consistently, and if so your animator will be adjusted to match. If the avatar is inconsistent in its use of write defaults, your animator will be unchanged.

docs/docs/reference/merge-armature.md

@@ -1,8 +1,4 @@
----
+# Merge Armature
-sidebar_position: 1
----
-
-# Merge Armature
 
 The Merge Armature component merges a tree of GameObjects onto the armature of the avatar.
 
@@ -41,3 +37,8 @@ Where necessary, PhysBone objects will have their targets updated, and ParentCon
 If the locked option is enabled, the position and rotation of the merged bones will be locked to their parents in the editor. This is a two-way relationship; if you move the merged bone, the avatar's bone will move, and vice versa.
 
 This is intended for use when animating non-humanoid bones. For example, you could use this to build an animator which can animate cat-ear movements.
+
+## Object references
+
+Although the editor UI allows you to drag in a target object for the merge armature component, internally this is saved as a path reference.
+This allows the merge armature component to automatically restore its Merge Target after it is saved in a prefab.

docs/docs/reference/parameters.md

@@ -1,5 +1,42 @@
----
+# Parameters
-sidebar_position: 4
----
 
-TODO
+The Modular Avatar Parameters component allows you to define the animator parameters your prefab uses either internally, or to communicate with other components.
+It allows the end-user to easily rename parameters to avoid conflicts, or to wire up multiple prefabs without having to alter animators directly.
+It also allows for automatic configuration of synced parameters.
+
+The Parameters component has two display modes: One for end-users of prefabs, and one for prefab developers.
+End-users can rename fields, and configure their AV3 parameters settings (saved state and default value).
+Developers can adjust the sync type and set parameters to be internal/hidden from end-users.
+
+![End-user display](parameters-enduser.png) ![Developer display](parameters-devmode.png)
+
+## When should I use it?
+
+The Parameters component should be used when you're building a prefab which makes use of animator parameters other than VRChat builtins.
+
+## How do I use it?
+
+### End-users
+
+The parameters component on prefabs can be used to rename parameters to avoid conflicts, and to adjust whether synced parameters are saved across avatar reloads (and their default value).
+By renaming multiple prefab parameters to be the same, you can make them all share the same state and animate at the same time.
+Alternately, by changing conflicting names to be different, you can resolve prefab conflicts.
+
+### Prefab developers
+
+Add the parameters component to the root of your prefab, and click "Show Prefab Developer Options". You'll see a list of all parameters used in your prefab.
+
+Each parameter can be configured with the following options:
+
+* Internal - Hides the parameter, and automatically renames the parameter with a unique name.
+* PhysBones Prefix - Indicates this is a parameter passed to a PhysBone "parameter" field (and thus it really references a number of sub-parameters)
+* Sync Mode - Indicates if a parameter is synced, and if so what its type is
+
+Parameters components can be nested. This lets you build up a complex prefab out of sub-prefabs, some which may be added multiple times, and while avoiding parameter name conflicts.
+
+Parameter renaming will be applied to the following components underneath (or on the same GameObject as) the Parameters component:
+* [Modular Avatar Merge Animator](merge-animator.md)
+* [Modular Avatar Menu Installer](menu-installer.md)
+* VRC Physics Bone
+* VRC Contact Receiver
+* Animator (although this is unlikely to be very useful)