Merge remote-tracking branch 'origin/master' into merge-1.5

.docs/content/docs/developers/_index.ja.md

@@ -0,0 +1,5 @@
+---
+weight: 3
+bookFlatSection: true
+title: "開発者向け"
+---

.docs/content/docs/developers/_index.md

@@ -0,0 +1,5 @@
+---
+weight: 3
+bookFlatSection: true
+title: "For Developers"
+---

.docs/content/docs/developers/make-your-tool-compatible-with-aao/index.ja.md

@@ -0,0 +1,121 @@
+---
+title: ツールをAvatar Optimizerとの互換性をもたせる
+---
+
+# ツールをAvatar Optimizerとの互換性をもたせる
+
+このページでは以下の２つのことを説明します。
+
+- どのようなときにツールがAvatar Optimizerと非互換になるか
+- どのように互換性を改善するか
+
+もし質問があれば[fediverseで`@[email protected]`][fediverse]に気軽に聞いてください。
+
+## どのようなときにツールがAvatar Optimizerと非互換になるか {#when-incompatible}
+
+もしあなたのツールがコンポーネントを追加せず、ビルド時に何もしないのであれば、すでにAvatarOptimizerと互換性があります！
+
+もしあなたのツールがコンポーネントをアバターに追加する場合、そのツールはAvatar Optimizerと非互換である可能性があります
+
+Avatar Optimizerはコンポーネントに対するガベージコレクションを実装しているため、Avatar Optimizerはアバターに存在する
+すべてのコンポーネントについて知る必要があります。
+
+未知なコンポーネントの問題を避けるため、Avatar Optimizerは道のコンポーネントが以下のようなものであると仮定します。(この仮定は将来的に変更される可能性があります。)
+- 副作用があるコンポーネントである
+- コンポーネントによって参照されてるコンポーネントに依存している
+
+しかし、この仮定は正しくない可能性があるので、Avatar Optimizerは未知のコンポーネントを見つけた場合、以下のような警告を生成します。
+
+![unknown-component-warning](unknown-component-warning.png)
+
+もしあなたのツールがNDMF[^NDMF]をベースにしていない非破壊ツールで、Play modeに入るときに適用されるツールの場合、 Avatar
+Optimizerがそのツールより前に適用される可能性があるため、非互換です。
+
+## どのように互換性を改善するか {#improve-compatibility}
+
+### NDMFを使用した非破壊ツールの場合 {#improve-compatibility-ndmf-based}
+
+もしあなたのツールがNDMF[^NDMF]を使用した非破壊ツールの場合、Avatar Optimizerが実行される前にそのツールのコンポーネントを削除してください。
+
+Avatar OptimizerはOptimization passに処理を実行するため、もしあなたのツールがOptimization passに何もしないのであれば、特に問題がありません。
+もしあなたのツールがOptimization passになにか実行する場合、[`BeforePlugin`][ndmf-BeforePlugin]を用いてAvatar Optimizerの前に実行するようにしてください。
+Avatar OptimizerのNDMFのQualifiedNameは`com.anatawa12.avatar-optimizer`です。
+
+もしあなたのツールがAvatar Optimizerよりあとにあなたのコンポーネントを用いて実行する必要がある場合、 Avatar Optimizerに[コンポーネントを登録][register-component]してください.
+
+### NDMFを使用していない非破壊ツールの場合 {#improve-compatibility-non-ndmf-based}
+
+もしあなたのツールがNDMF[^NDMF]を使用していない非破壊ツールの場合、NDMFを使用するのを検討してください。
+
+もしあなたのツールがPlayモードに入るときに適用される場合、Avatar Optimizerとの処理順を保証するためにはNDMFを使用する必要があります。
+もしあなたのツールがPlayモードに入るときに適用されない場合、NDMFを使用しなくても問題ないことは多いです。
+
+もしあなたのツールでNDMFを使用したくない場合、Avatar Optimizerが実行される前にそのツールのコンポーネントを削除してください。
+これを達成するためにはNDMFのOptimization passの実行より前にあなたのツールを実行するようにしてください。
+現在、NDMFはOptimization passをVRCSDKの`RemoveAvatarEditorOnly`の直前のorder `-1025`で実行するので、
+あなたのツールの`IVRCSDKPreprocessAvatarCallback`をそれより小さい`callbackOrder`で登録してください。
+
+もしあなたのツールがAvatarOptimizerの実行後(NDMFのOptimization passのあと)に処理したい場合、Avatar Optimizerに[コンポーネントを登録][register-component]してください.
+
+### データを保持するだけのコンポーネントを持つツールの場合 {#non-destructive-tools}
+
+もしあなたのツールのコンポーネントがビルド時に意味を持たず、情報保持のための場合、
+AvatarOptimizerの処理の前に`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除するか、Avatar Optimizerにコンポーネントを登録してください。
+
+もし`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除する場合、[この部分](#improve-compatibility-non-ndmf-based)を参照してください。
+
+もしAvatar Optimizerにコンポーネントを登録する場合、[この部分][register-component]を参照してください。
+
+## コンポーネントを登録する {#register-component}
+
+もしあなたのツールのコンポーネントをAvatar Optimizerの処理後まで保持したり、またはAvatar Optimizerによって削除されたい場合、
+Avatar Optimizerにコンポーネントの情報を登録できます。
+
+Avatar OptimizerのAPIを呼び出すため、まず初めにassembly definition file[^asmdef]を存在しない場合作成してください。
+
+次に、asmdefファイルのアセンブリ参照に`com.anatawa12.avatar-optimizer.api.editor`を追加してください。
+もしあなたのツールがAvatar Optimizerに依存したくない場合、[Version Defines]を使用してください。
+Avatar Optimizer 1.6.0より前では公開APIがなく、またAvatar Optimizer v2.0.0でAPIを破壊する可能性があるため、
+バージョンの範囲を`[1.6,2.0)`(やもっと厳しい `[1.7,2.0)`など)のように指定するのを推奨します。
+
+![version-defines.png](version-defines.png)
+
+次に、あなたのコンポーネントに関する`CompoinentInformation`を定義してください。
+
+```csharp
+#if AVATAR_OPTIMIZER && UNITY_EDITOR
+
+[ComponentInformation(typeof(YourComponent))]
+internal class YourComponentInformation : ComponentInformation<YourComponent>
+{
+    protected override void CollectMutations(YourComponent component, ComponentMutationsCollector collector)
+    {
+        // call methods on the collector to tell about the component
+    }
+
+    protected override void CollectDependency(YourComponent component, ComponentDependencyCollector collector)
+    {
+        // call methods on the collector to tell about the component
+    }
+}
+
+#endif
+```
+
+`CollectDependency`ではビルド時、または実行時のあなたのコンポーネントの依存関係を登録してください。
+`CollectMutations`ではあなたのコンポーネントが実行時に変更する可能性があるプロパティを登録してください。
+詳しくはxmldocやメソッド名を参照してください。
+
+もしあなたのコンポーネントがエディタ上のツールのためのデータを保持するだけの場合、どちらも空にします。
+
+[fediverse]: https://misskey.niri.la/@anatawa12
+[ndmf-BeforePlugin]: https://ndmf.nadena.dev/api/nadena.dev.ndmf.fluent.Sequence.html#nadena_dev_ndmf_fluent_Sequence_BeforePlugin_System_String_System_String_System_Int32_
+[register-component]: #register-component
+
+[^asmdef]: Assembly-CSharp以外のアセンブリを定義するためのファイル。[unity docs](https://docs.unity3d.com/2019.4/Documentation/Manual/ScriptCompilationAssemblyDefinitionFiles.html)を参照してください。.
+[^NDMF]: [NDMF] (Non-Destructive Modular Framework)は非破壊改変ツールのためのbdunderscoreさんによるフレームワークです。 
+Avatar Optimizerはこのフレームワークを他の非破壊改変ツールとの互換性のために使用しています。
+
+[NDMF]: https://ndmf.nadena.dev/
+[modular-avatar]: https://modular-avatar.nadena.dev/
+[Version Defines]: https://docs.unity3d.com/2019.4/Documentation/Manual/ScriptCompilationAssemblyDefinitionFiles.html#define-symbols

.docs/content/docs/developers/make-your-tool-compatible-with-aao/index.md

@@ -0,0 +1,130 @@
+---
+title: Make your tool compatible with Avatar Optimizer
+---
+
+# Make your tool compatible with Avatar Optimizer
+
+This page describes the following two things.
+
+- When your tool can be incompatible with Avatar Optimizer?
+- How to improve the compatibility?
+
+If you have some question, please feel free to ask [`@[email protected]` on fediverse][fediverse].
+
+## When your tool can be incompatible with Avatar Optimizer? {#when-incompatible}
+
+If your tool doesn't add any components to the avatar and does nothing on the build time,
+your tool is already compatible with Avatar Optimizer!
+
+If your tool adds some components to some portion of Avatar, your tool can be incompatible with Avatar Optimizer.
+
+Since Avatar Optimizer has Garbage Collection system for Components and else, Avatar Optimizer have to 
+know about all existing components in your Avatar at the optimization.
+
+To avoid problem with unknown components, the Avatar Optimizer currently assumes unknown components
+- have some side-effects.
+- will have dependency relationship to all components referenced in the component.
+  (They can be changed in the future.)
+
+However, the assumption can be incorrect so Avatar Optimizer will generate the following warning.
+
+![unknown-component-warning](unknown-component-warning.png)
+
+If your tool is non-NDMF[^NDMF]-based non-destructive tools that will also be applied on entering play mode,
+Avatar Optimizer might be proceed before applying your plugin.
+
+## How to improve the compatibility? {#improve-compatibility}
+
+### For NDMF based non-destructive tools {#improve-compatibility-ndmf-based}
+
+If your tool is a non-destructive tools based on NDMF[^NDMF], please remove your components before
+Avatar Optimizer process. Avatar Optimizer does most thing in Optimization pass
+so if your plugin do nothing in Optimization pass, nothing is problem.
+If your tool needs your components in Optimization pass, 
+please execute before Avatar Optimizer with [`BeforePlugin`][ndmf-BeforePlugin]. 
+QualifiedName of Avatar Optimizer in NDMF is `com.anatawa12.avatar-optimizer`.
+
+If your tool actually want to do something with your components in Optimization pass,
+please [register your component][register-component] to Avatar Optimizer.
+
+### For non-NDMF based non-destructive tools {#improve-compatibility-non-ndmf-based}
+
+If your tool is a non-destructive tools not based on NDMF[^NDMF], please consider
+make your tool based on NDMF.
+
+If your tool is applied on play, to ensure compatibility with Avatar Optimizer, you have to use NDMF to
+guarantee applying ordering between Avatar Optimizer and your tool.
+If your tool does something only on building avatar, making your tool based on NDMF is not required.
+
+If you don't want to make your took based on NDMF, please remove your component before processing Avatar Optimizer.
+To achieve this, please execute your tool before NDMF's Optimization pass.
+Currently NDMF executes Optimization passes in order `-1025`, JUST before VRCSDK's `RemoveAvatarEditorOnly` callback so
+your tool should register `IVRCSDKPreprocessAvatarCallback` with smaller `callbackOrder`.
+
+If your tool actually want to do something with your components after Avatar Optimizer (Optimization pass in NDMF),
+please [register your component][register-component] to Avatar Optimizer.
+
+### For other tools that just holds data with components. {#non-destructive-tools}
+
+If your tool holds some information with components and doesn't have meaning at the build time, 
+please remove your component before Avatar Optimizer with `IVRCSDKPreprocessAvatarCallback` or 
+register your component to Avatar Optimizer.
+
+When you want to remove your component with `IVRCSDKPreprocessAvatarCallback`, please refer [this section](#improve-compatibility-non-ndmf-based).
+
+When you want to register your component to Avatar Optimizer, please refer [this section][register-component].
+
+### Registering your components {#register-component}
+
+If your tool want to keep your component after processing Avatar Optimizer, or want to removed by Avatar Optimizer,
+you can register your component to Avatar Optimizer to tell about your component.
+
+To call APIs in Avatar Optimizer, first, Please make assembly definition file[^asmdef] if your tool doesn't have.
+
+Next, add `com.anatawa12.avatar-optimizer.api.editor` to assembly references in asmdef file.
+If your tool doesn't want to depends on Avatar Optimizer, please use [Version Defines].
+Because Avatar Optimizer didn't have public API piror to 1.6.0 and will break api in 2.0.0, 
+it's recommended to add version range like `[1.6,2.0)` (or more stricter like `[1.7,2.0)`).
+
+![version-defines.png](version-defines.png)
+
+Then, define `CompoinentInformation` for your component in your assembly.
+
+```csharp
+#if AVATAR_OPTIMIZER && UNITY_EDITOR
+
+[ComponentInformation(typeof(YourComponent))]
+internal class YourComponentInformation : ComponentInformation<YourComponent>
+{
+    protected override void CollectMutations(YourComponent component, ComponentMutationsCollector collector)
+    {
+        // call methods on the collector to tell about the component
+    }
+
+    protected override void CollectDependency(YourComponent component, ComponentDependencyCollector collector)
+    {
+        // call methods on the collector to tell about the component
+    }
+}
+
+#endif
+```
+
+In `CollectDependency`, you should register build-time or run-time dependencies of your component.
+In `CollectMutations`, you should register any mutation your component may do.
+Please refer xmldoc and method name for more datails.
+
+If your component is just for keeping data for your in-editor tools, both will be empty method.
+
+[fediverse]: https://misskey.niri.la/@anatawa12
+[ndmf-BeforePlugin]: https://ndmf.nadena.dev/api/nadena.dev.ndmf.fluent.Sequence.html#nadena_dev_ndmf_fluent_Sequence_BeforePlugin_System_String_System_String_System_Int32_
+[register-component]: #register-component
+
+[^asmdef]: The file defines assembly other than Assembly-CSharp. Please refer [unity docs](https://docs.unity3d.com/2019.4/Documentation/Manual/ScriptCompilationAssemblyDefinitionFiles.html).
+[^NDMF]: [NDMF], Non-Destructive Modular Framework, is a framework for running non-destructive build plugins when 
+building avatars by bdunderscore. Avatar Optimizer uses that framework for compatibility 
+with many non-destructive tools based on NDMF.
+
+[NDMF]: https://ndmf.nadena.dev/
+[modular-avatar]: https://modular-avatar.nadena.dev/
+[Version Defines]: https://docs.unity3d.com/2019.4/Documentation/Manual/ScriptCompilationAssemblyDefinitionFiles.html#define-symbols

API-Editor/AssemblyInfo.cs

@@ -0,0 +1,3 @@
+using System.Runtime.CompilerServices;
+
+[assembly:InternalsVisibleTo("com.anatawa12.avatar-optimizer.editor")]