Add a tutorial for a simple object toggle

docs/docs/tutorials/index.md

@@ -8,4 +8,5 @@ sidebar_label: Tutorials
 Here are some step-by-step guides on how to set up things using Modular Avatar.
 
 * [Configuring a simple outfit](clothing/) - in most cases, you can set up an outfit with just a few clicks. Check out this tutorial for details.
-* [Configuring a complex (cloth) outfit](adv_clothing/) - this tutorial shows an example of an outfit that requires just a little bit more setup
+* [Configuring a complex (cloth) outfit](adv_clothing/) - this tutorial shows an example of an outfit that requires just a little bit more setup
+* [Toggle an object](object_toggle/) - In this tutorial we'll build a simple gimmick that toggles a cube on and off. This shows off the basics of animator-based gimmicks.

docs/docs/tutorials/object_toggle/index.md

@@ -0,0 +1,119 @@
+---
+sidebar_position: 2
+sidebar_label: Toggle an object
+---
+
+# Toggle an object
+
+In this tutorial, we'll create a simple prefab that makes a cube appear and disappear. We'll also
+attach it to the avatar's hand, so it's easy to see.
+
+## Step 1: Creating our objects
+
+We'll start by creating the GameObjects we'll be showing. Start by dropping a test avatar in the scene,
+and adding an empty GameObject to be the base of your prefab (we'll call this `ToggleDemo`). Inside this GameObject, create a `HandRef` object
+which we'll use to track the hand, and put the cube we want to display inside of that object.
+
+![Initial object setup](setup1.png)
+
+### Attach the cube to your hand
+
+Next, let's have the HandRef track the avatar's right hand. Select the `HandRef` object, and click `Add Component` in the inspector.
+Add a `MA Bone Proxy`.
+
+![Adding a bone proxy](setup2.png)
+
+Drag-and-drop the avatar's right hand bone into the "Target" field. Set "Attachment Mode" to "As child; at root".
+The cube will immediately snap to the avatar's hand. Adjust its scale and position until it's not quite so in the way.
+Don't forget to remove the Box Collider from the Cube as well!
+
+![Configuring a bone proxy](setup3_en.png)
+
+## Step 2: Creating our animator controller
+
+Next, we'll create an animator controller that will control the cube's visibility.
+Create a new Animator Controller, and two animation clips (we'll call them `CubeOff` and `CubeOn`). Open the Animator Controller, and drag the two clips in.
+Then right click `Any State` and choose add transition to connect it to `CubeOff`. Do the same for `CubeOn`.
+
+![Initial animator setup](controller1.png)
+
+### Setting up transitions
+
+Create a new bool parameter called `Cube`. Then, for each of your transitions, set Transition Duration to be 0, and Can Transition to Self off.
+Add our Cube parameter to the conditions, and for the CubeOff transition set it to false.
+
+![Transition setup](controller2.png)
+
+## Step 3: Merge Animator, and recording our animations
+
+Go back to your top-level GameObject, and add a `MA Merge Animator` component.
+Set the `Animator to merge` to your new animator controller. Check the `delete attached animator` and `match avatar write defaults` boxes.
+Then, _also_ add an Animator component, and point it to your new animator controller as well.
+
+![Adding merge animator](merge-animator-en.png)
+
+:::tip
+
+Merge Animator doesn't need to be at the top level GameObject. Feel free to put it further
+down the hierarchy if you prefer. Just make sure that `MA Parameters` (which we'll discuss further down)
+is on either the same object, or a parent of all your `Merge Animator`s and `Menu Installers`!
+
+Adding an Animator here is also optional; we're just using it so that Unity allows us to
+record animations. By checking the `delete attached animator` box, Modular Avatar will delete the
+`Animator` component at build time.
+
+:::
+
+## Step 4: Recording our animations
+
+Go to the unity "Animation" tab. If you don't have it, press Ctrl-6 to open it.
+You should see `CubeOff` and `CubeOn` (only) in the list of animations; if not, make sure that your `ToggleDemo` object is selected.
+
+With `CubeOff` selected, click the red record button, then turn the `Cube` GameObject off.
+
+![Recording CubeOff](rec1.png)
+
+Then, with `CubeOn` selected, click the red record button, and turn the `Cube` GameObject off, then on again.
+
+![Recording CubeOn](rec2.png)
+
+## Step 5: Setting up synced parameters
+
+Almost there! Next, we'll set up our synced parameters, so they are automatically added.
+
+Head back to our `ToggleDemo` object, and add a `MA Parameters` component. Click the `Show Prefab Developer Options` checkbox.
+You'll see that our `Cube` parameter is automatically added. Set Sync Mode to `Bool` and check the `Internal` box.
+
+![MA Parameters configuration](params-en.png)
+
+:::tip
+
+If you set the internal checkbox, modular avatar will ensure that your `Cube` parameter doesn't interfere with anything else on the avatar using the same parameter name.
+If you leave it unchecked, the end-user will be able to rename the parameter if they want, but can also choose to have multiple prefabs use the same parameter.
+
+:::
+
+## Setup 6: Setting up the menu
+
+Finally, we'll set up the Av3 menu entry. Create an Expressions Menu asset:
+
+![Creating an expressions menu asset](exp-menu-create.png)
+
+Add one control to it; set the name to Cube, type to Toggle, and for the parameter field, enter `Cube` in the text box. Note that because we haven't actually built the avatar yet, the parameter isn't in the dropdown yet. That's okay!
+
+![Expressions menu setup](exp-menu-setup.png)
+
+Now add a `MA Menu Installer` component to your `ToggleDemo` object. Open up the `Prefab Developer Options` section, and put your expressions menu asset there.
+
+![Menu installer](menu-installer-en.png)
+
+At this point, we're done! If you build and upload the avatar, you should have a menu item which will summon a cube to your right hand.
+
+## Finishing up: Prefab conversion and component ordering
+
+Let's get our cube ready to distribute. First, the components our end-users might want to mess with are primarily the Menu Installer and (if you disabled the Internal checkbox) possibly MA parameters.
+We might want to drag those up to the top of our inspector.
+
+![Component ordering](component-ordering-en.png)
+
+Once you're happy with things, drag ToggleDemo into your project pane to create a prefab. Now you can drop that onto any other avatar, and have an instant cube!

docs/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/index.md

@@ -8,4 +8,5 @@ sidebar_label: かんたんな使い方
 Modular Avatarを使ったセットアップ方法を紹介するチュートリアルがいくつかあります。
 
 * [簡単な衣装セットアップ](clothing/) - 多くの場合は衣装を数クリックだけでセットアップできます。このチュートリアルで詳細をチェック！
-* [複雑なCloth衣装セットアップ](adv_clothing/) - もう少しだけセットアップが必要になる、複雑な衣装の例です。
+* [複雑なCloth衣装セットアップ](adv_clothing/) - もう少しだけセットアップが必要になる、複雑な衣装の例です。
+* [オブジェクトを出し入れしよう](object_toggle/) - 簡単なオブジェクト出し入れギミック。アニメーターを使ったギミックの基礎をカバーします。

docs/i18n/ja/docusaurus-plugin-content-docs/current/tutorials/object_toggle/index.md

@@ -0,0 +1,119 @@
+---
+sidebar_position: 2
+sidebar_label: オブジェクトを出し入れしよう
+---
+
+# オブジェクトを出し入れしよう
+
+このチュートリアルでは、キューブを出したり消したりするプレハブを作ります。ついでに分かりやすいように、アバターの右手に追従させます。
+
+## ①　オブジェクトを作成
+
+まずは表示するGameObjectを作ります。適当なテストアバターをシーンにおいて、プレハブのルートとなる空のGameObjectを追加します（`ToggleDemo`と命名します）
+このGameObjectの中に、手の追従に使う`HandRef`オブジェクトを作り、さらにその中にキューブを作ります。
+
+![Initial object setup](setup1.png)
+
+### キューブを手に
+
+次はHandRefを右手に追従させます。`HandRef`を選択肢、`Add Component`から`MA Bone Proxy`を追加します。
+
+![Adding a bone proxy](setup2.png)
+
+アバターの右手ボーンを「ターゲット」において、配置モードを「子として・ルートに配置」にします。すると、キューブがアバターの手に移動します。
+
+![Adding a bone proxy](setup3_ja.png)
+
+邪魔にならないようにキューブの位置や大きさを調整しましょう。キューブからBox Colliderを消すのもお忘れなく！
+
+## ②　アニメーターコントローラーを作成
+
+次はキューブの表示状態を制御するアニメーターコントローラーを作成します。
+Animator Controllerアセットを作成し、アニメーションクリップを二つ作成します（`CubeOff`と`CubeOn`）。クリップをコントローラーに追加します。
+`Any State`に右クリックし、Add TransitionでCubeOffとCubeOnにつなげます。
+
+![Initial animator setup](controller1.png)
+
+### トランジションを設定
+
+`Cube`というboolパラメーターを追加します。そして、各トランジションで、Transition Durationを0にして、
+Can Transition To Selfをオフにします。Cubeパラメーターをコンディションに追加し、CubeOffの方は条件をfalseにします。
+
+![Transition setup](controller2.png)
+
+## ③ Merge Animatorの設定とアニメーションの作成
+
+一番上の`ToggleDemo`オブジェクトに戻って、`MA Merge Animator`のコンポーネントを追加します。
+`統合されるアニメーター`に先ほど作成したアニメーターを設定します。そして、`付属アニメーターを削除`と`アバターのWrite Defaults設定に合わせる`をオンにします。
+
+そして、さらにAnimatorコンポーネントを追加し、同じアニメーターコントローラーを設定します。
+
+![Adding merge animator](merge-animator-ja.png)
+
+:::tip
+
+Merge Animatorは必ずしも一番上に配置する必要がありません。お好みに応じてより埋まった場所においてもいいでしょう。
+ただし、この後解説する`MA Parameters`コンポーネントが必ず、すべての`Merge Animator`や`Menu Installers`の
+同オブジェクトもしくは親（や親の親など）に配置する必要があります。
+
+また、ここでAnimatorを追加するのが絶対必要というわけではありません。Unityのアニメーション録画UIが使える裏技としておいているだけです。
+`付属アニメーターを削除`を入れることで、このアニメーターがビルド時に削除されます。
+
+:::
+
+## ④　アニメーションの録画
+
+UnityのAnimationタブへ行きましょう。見当たらないなら、Ctrl-6で開けます。
+アニメーションのリストに、CubeOffとCubeOnだけが載っているはずです。見えてない場合は`ToggleDemo`のオブジェクトを選択しましょう。
+
+`CubeOff`を選択した状態で、赤い録画ボタンを押して、`Cube`のGameObjectをオフにします。
+
+![Recording CubeOff](rec1.png)
+
+そして、`CubeOn`を選択した状態で、赤い録画ボタンを押して、`Cube`のGameObjectを一回オフにしてからオンにします。
+
+![Recording CubeOn](rec2.png)
+
+## ⑤　同期パラメーターの設定
+
+もう少しです！次は同期パラメーターが自動的に追加されるように設定します。
+
+`ToggleDemo`オブジェクトに戻って、`MA Parameters`コンポーネントを追加します。
+`プレハブ開発者向け設定を表示`をONにすると、`Cube`のパラメーターが自動的に追加されているのが分かります。
+同期モードをBoolにして、内部値をONにします。
+
+![MA Parameters configuration](params-ja.png)
+
+:::tip
+
+内部値のチェックを入れると、Cubeのパラメーターが同じパラメーター名を使っている他のアセットと干渉しないように処理されます。
+チェックを入れない場合は、エンドユーザーが自由に名前を変えることができたり、あえて複数のプレハブを干渉させるように設定して、連動する動きが作れるようになります。
+
+:::
+
+## ⑥　メニューを作成しましょう
+
+最後にアバター3.0のメニューを作成します。Expressions Menuアセットを作成します：
+
+![Creating an expressions menu asset](exp-menu-create.png)
+
+Controlを一つ追加します。名前をCubeにして、TypeをToggleにして、そしてパラメーターの方は右側の入力欄で`Cube`打ち込みます。
+アバターはまだビルドされないので同期パラメーターが存在せず、ドロップダウンに入っていませんが、問題ないです！
+
+![Expressions menu setup](exp-menu-setup.png)
+
+次は`ToggleDemo`のオブジェクトに`MA Menu Installer`コンポーネントを追加します。`プレハブ開発者向け設定`を開き、
+先ほど作成したメニューアセットを設定します。
+
+![Menu installer](menu-installer-en.png)
+
+設定終わりです！ここでアバターをビルドしアップロードすると、右手にキューブを出現させるスイッチがアバターのメニューに追加されているはずです。
+
+## 仕上げ：プレハブ変換とコンポーネント順
+
+配布できるように準備しましょう。まず、エンドユーザーが最も操作しそうなコンポーネントはMenu Installerと（内部値に設定してなければ）Parametersなので、
+そちらを一番上にドラッグしましょう。
+
+![Component ordering](component-ordering-ja.png)
+
+仕上げに満足したら、ToggleDemoをプロジェクトパネルにドラッグし、プレハブを作成します。どのアバターでもポンと置いただけで追加できるトグルキューブの出来上がりです！