From 4713a8f0def791266d133d2b0f01e5ac6abfafac Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Tue, 13 Aug 2024 18:37:56 +0900 Subject: [PATCH 01/12] docs: initial improvements on editor public api --- API-Editor/ComponentInformation.cs | 89 +++++++++++++++++++++++------- 1 file changed, 68 insertions(+), 21 deletions(-) diff --git a/API-Editor/ComponentInformation.cs b/API-Editor/ComponentInformation.cs index f57805108..dfd90b48e 100644 --- a/API-Editor/ComponentInformation.cs +++ b/API-Editor/ComponentInformation.cs @@ -60,9 +60,12 @@ internal sealed override void ApplySpecialMappingInternal(Component component, M ApplySpecialMapping((TComponent)component, collector); /// - /// Collects runtime mutations by . - /// You have to call . - /// for all property mutations by the component. + /// Collects runtime depencencies of . + /// + /// This information is used for Garage Collection system in Avatar Optimizer. + /// You have to call some methods on to declare dependencies. + /// + /// Please refer for more information about GC system and collecting dependencies. /// /// The component. /// The callback. @@ -100,6 +103,41 @@ protected virtual void ApplySpecialMapping(TComponent component, MappingSource m // and do fallback process in that method. } + /// + /// Callback for collecting dependencies information of the component. + /// This information is currently used by Garbage Collection system and automatic component disable. + /// + /// # Components Garbage Collection + /// Avatar Optimizer has a Garbage Collection system for components (GC components). + /// `AddDependency` and `MarkEntryPoint` methods are used to declare the dependency relationship used by the GC system. + /// + /// The GC system is based on tracing garbage collection or mark-and-sweep algorithm. + /// + /// In Avatar Optimizer, root objects are the components that are enabled, gameObject is active, + /// and the component is marked as EntryPoint with `MarkEntryPoint`. + /// The dependency relationship is declared by `AddDependency` methods on this callback. + /// There is option to declare condition of the dependency relationship based on the enabled / active state + /// of the dependant and / or dependency. + /// Please refer and `AddDependency` methods for more information. + /// + /// # Automatic Component Disable + /// Avatar Optimizer has runtime-load optimization feature that disables components that are not needed. + /// In addition to the information provided for GC Components, + /// `HeavyBehaviour` and `Behaviour` methods are used to declare the activeness of the component. + /// + /// Avatar Optimizer tries to disable `HeavyBehaviour` as long as possible and enable it when needed. + /// Avatar Optimizer thinks a component is needed when any of the EntryPoint component that + /// depends on the component is active and enabled. + /// + /// In current Avatar Optimizer, the optimization does animate enabled of the HeavyBehavior component, + /// and does not change the enabled / active state of any other components. + /// In the future, to reduce animation property count, Avatar Optimizer may change the active state of game object + /// and this may affects to other components. + /// However, some components are not heavy but enabled state is important. + /// Please mark such components as Behavior with `MarkBehaviour`. + /// Active / Enabled of components marked as Behaviour will not be changed by Avatar Optimizer. + /// Please note that this does not prevent Avatar Optimizer to remove the component. + /// [PublicAPI] public abstract class ComponentDependencyCollector { @@ -108,21 +146,28 @@ internal ComponentDependencyCollector() } /// - /// Marks this component as EntryPoint component, which means has some effects to non-avatar components. - /// For example, Renderer components have side-effects because it renders something. - /// VRC Contacts have some effects to other avatars in the instance so they have side-effects. + /// Marks this component as EntryPoint component. + /// + /// Avatar Optimizer will recognize EntryPoint compponents as components that have side effects to outside the avatar. + /// Therefore, Avatar Optimizer will not remove such a components if the component can be active and enabled. + /// Please note that Avatar Optimizer may remove the component if the component is not active or enabled. /// - /// If your component has some effects only for some specific component(s), you should not mark your component - /// as EntryPoint. You should make dependency relationship from affecting component to your component instead. + /// For example, Renderer components have side effects because it renders something. + /// VRC Contacts have some effects to other avatars in the instance, so they have side effects. /// - /// One of such components is VRCPhysBone without animating parameters. - /// VRCPhysBone has effects if and only if some other EntryPoint components are attached to PB-affected - /// transforms or their children, or PB-affected transforms are dependencies of some EntryPoint components. - /// So, for VRCPhysBone, There are bidirectional dependency relationship between PB and PB-affected transforms - /// and VRCPhysBone is not a EntryPoint component. + /// If your component has some effects only for some specific component(s) in the avatar, + /// you should not mark your component as EntryPoint. + /// You should declare dependency relationship from affecting component to your component instead. + /// This allows Avatar Optimizer to remove your component if the affecting component is removed. + /// + /// One of components that is not EntryPoint is VRCPhysBone without animating parameters. + /// VRCPhysBone only affects a specific subset of the transforms in the avatar. + /// Therefore, VRCPhysBone has no effects if the affected transforms are not used by any Renderers or some other EntryPoint components. + /// So, VRCPhysBone are not marked as EntryPoint and they declare bidirectional dependency relationship between + /// PhysBone and PhysBone-affected transforms. /// /// With same reasons, Constraints are not treated as EntryPoint, they have bidirectional - /// dependency relationship between Constraintas and transform instead. + /// dependency relationship between Constraints and transform instead. /// [PublicAPI] public abstract void MarkEntrypoint(); @@ -130,35 +175,37 @@ internal ComponentDependencyCollector() /// /// Marks this component as HeavyBehaviour component, which means the component uses some resources while /// enabled but doesn't eat if not enabled and AAO can (almost) freely change enablement of the component. - /// When you mark some components Behaviour component, Avatar Optimizer will generate animation that disables - /// the component when entrypoint is not active / enabled. + /// When you mark some components HeavyBehaviour component, Avatar Optimizer will generate animation that disables + /// the component when all entrypoints that using this component is not active / enabled. /// /// If your component have some runtime load and can be skipped if your component is not needed by all /// enabled EntryPoint components, you should mark your component as Behaviour for runtime-load optimization. /// - /// For example, VRCPhysBone and Constraints are marked as HeavyBehaviour. + /// For example, VRCPhysBone is marked as HeavyBehaviour. /// [PublicAPI] public abstract void MarkHeavyBehaviour(); /// /// Marks this component as Behaviour component, which means the activeness of the component has meaning. - /// When you mark your some components Behaviour component, Avatar Optimizer will never change activeness of - /// the component. + /// When you mark your some components Behaviour component, Avatar Optimizer will never change + /// `isActive` and `enabled` of the component, but this doesn't prevent AAO to remove the component. /// /// If your component is not a Behaviour component, AAO may change enablement of the component. /// /// NOTE: In AAO 1.6.0, AAO will not change enablement of non-Behaviour components but in the feature releases, /// AAO may change enablement of non-Behaviour components to change enablement of HeavyBehaviour components /// effectively. + /// + /// For example Constraints are marked as Behaviour. /// [PublicAPI] public abstract void MarkBehaviour(); /// /// Adds as dependencies of . - /// The dependency will be assumed as the dependant will have dependency if dependant is enabled and - /// even if dependency is disabled. You can change the settings by . + /// The dependency will be assumed as the dependant will have dependency if dependant can be enabled and + /// even if dependency can be disabled. You can change the settings by . /// /// WARNING: the instance can be shared between multiple AddDependency /// invocation so you MUST NOT call methods on IComponentDependencyInfo after calling AddDependency other time. From 443dd6ce1240e78664307750778612be7858ac32 Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Tue, 20 Aug 2024 00:39:50 +0900 Subject: [PATCH 02/12] docs: more improvements on developer documents --- .../index.md | 86 ++++++++++++++----- API-Editor/ComponentInformation.cs | 7 +- 2 files changed, 67 insertions(+), 26 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md index 8cbc6e6a4..cee1fff95 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md @@ -16,57 +16,97 @@ If you have some question, please feel free to ask [`@anatawa12@misskey.niri.la` If your components are on the avatar and still exist when Avatar Optimizer processes it, your components can be incompatible with Avatar Optimizer. -Since Avatar Optimizer has Garbage Collection system for Components and others, Avatar Optimizer has to -know about all existing components in the Avatar at the optimization. +Avatar Optimizer is designed to process at the last of the build process, +components unknown to Avatar Optimizer is not supported. + +For example, Avatar Optimizer has Garbage Collection system for Components and others. +To correctly remove unused components, and correctly keep used components, +Avatar Optimizer has to know about all existing components in the Avatar at the optimization. To avoid problem with unknown components, Avatar Optimizer currently assumes unknown components -- have some side-effects. +- have to keep if the component can be enabled and active at runtime. + - This is because Avatar Optimizer assumes unknown components are runtime components. - 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. +(Those assumption above can be changed in the future.) + +However, the assumption can be incorrect, so Avatar Optimizer will generate a warning like below. ![unknown-component-warning](unknown-component-warning.png) ## How to improve the compatibility? {#improve-compatibility} -Please remove your components before Avatar Optimizer processes as much as possible. -If you cannot remove some components, please register them to Avatar Optimizer. +To improve the compatibility, you may implement one of the following methods. + +1. Remove your components before Avatar Optimizer processes as much as possible. + + If your component is not working at runtime, (in other words, it's a build-time or edit mode only component), + it's mostly better for your tool to process avatar before Avatar Optimizer processes, + and remove your components before Avatar Optimizer processes. + + Please refer [section below](#remove-component) for more details. + + Avatar Optimizer internally uses this method for most Avatar Optimizer components, + that will be processed before Trace and Optimize. + +2. Register your components to Avatar Optimizer with API -Since Avatar Optimizer v1.7.0, [Asset Description] is added for components that doesn't process on build or at runtime. -If your tool process nothing at build time, you can use this to register your components. + If your component is working at runtime, or your tool actually want to process avatar after Avatar Optimizer processes, + you can register your components to Avatar Optimizer to tell about your components. -If your tool process something at build time, registering with Asset Description is not recommended. -This prevents Avatar Optimizer from accidentally removing components and causing your tool to not work properly when the processes execution order is unexpected/incorrect. + Please refer [section below](#register-component) for more details. + + Avatar Optimizer internally uses this method to keep some components that are processed after Trace and Optimize, + and components from Unity, VRCSDK, and other avatar platform components. + +3. Register your components as no problems to remove with Asset Description. + + Since Avatar Optimizer v1.7.0, you can use [Asset Description] to register components only for preserving data + for edit-mode tools, that doesn't effects on build or at runtime. + If your tool process nothing at build time or runtime, you can use this to register your components instead of + removing your components before Avatar Optimizer processes. + Please refer [Asset Description] for more details. + + If your tool process something at build time, registering with Asset Description is not recommended. + Using Asset Description for components that process something at build time may unexpectedly + remove your components and disables your tool if the execution order is incorrect or unexpectedly changed. + + This method is internally used by Avatar Optimizer to keep compatibility with well-known edit-mode tools. [Asset Description]: ../asset-description ### Removing your components {#remove-component} -You can remove your components with several ways. +You can remove your components with [`DestroyImmediate`][DestroyImmediate] to remove your components. + +There is several ways to process and remove your component from avatar before Avatar Optimizer processes on build. -If your tool is a non-destructive tool based on NDMF[^NDMF], removing your components before the Optimizing phase -or before `com.anatawa12.avatar-optimizer` plugin (with [`BeforePlugin`][ndmf-BeforePlugin]) -in the Optimizing phase is recommended. +If your tool is a non-destructive tool based on NDMF[^NDMF], you can remove your components before the phases +prior to the Optimizing phase of NDMF or before `com.anatawa12.avatar-optimizer` plugin +(with [`BeforePlugin`][ndmf-BeforePlugin]) in the Optimizing phase. +If your tool removes your components in Optimizing phase, it's highly recommended to specify [`BeforePlugin`][ndmf-BeforePlugin] +even if your default callback order is before `com.anatawa12.avatar-optimizer` plugin. If your tool is a non-destructive tool not based on NDMF[^NDMF], removing your components before the NDMF's Optimizing phase is recommended. In this case, current NDMF executes Optimizing phase in order `-1025`, which is JUST before VRCSDK's `RemoveAvatarEditorOnly` -callback, so your tool should remove components with `IVRCSDKPreprocessAvatarCallback` with smaller `callbackOrder`. +callback, so your tool should remove components with `IVRCSDKPreprocessAvatarCallback` with `callbackOrder` smaller than `-1025`. + +If your components is only for holding information for your edit mode tool and has no meaning on the build time, +you can remove your components in `IVRCSDKPreprocessAvatarCallback` as described above, or +you can somply use [Asset Description] to register your components to be removed. -If your components holds some information for your tool and has no meaning on the build time, -removing your components before Avatar Optimizer processes with `IVRCSDKPreprocessAvatarCallback` is recommended. -See above for the ordering of `IVRCSDKPreprocessAvatarCallback`. +[DestroyImmediate]: https://docs.unity3d.com/2022.3/Documentation/ScriptReference/Object.DestroyImmediate.html ### Registering your components {#register-component} -If your tool wants to keep your component after Avatar Optimizer processes, +If you want to keep your component after Avatar Optimizer processes, you can register your components to Avatar Optimizer to tell about your components. First, to call APIs of Avatar Optimizer, please make an 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]. +If your tool doesn't want to depend on Avatar Optimizer, please use [Version Defines]. Because Avatar Optimizer didn't have public API prior to 1.6.0 and will break in 2.0.0, it's recommended to add version range like `[1.6,2.0)` (or stricter like `[1.7,2.0)` when you need new APIs that can be available in the future). @@ -96,8 +136,8 @@ internal class YourComponentInformation : ComponentInformation ``` In `CollectMutations`, you should register any mutation your component may do.\ -In `CollectDependency`, you should register build-time or run-time dependencies of your component.\ -Please refer xmldoc and method name for more datails. +In `CollectDependency`, you should register build-time or run-time dependencies and related information of your component.\ +Please read xmldoc of each methods for more details. [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_ diff --git a/API-Editor/ComponentInformation.cs b/API-Editor/ComponentInformation.cs index dfd90b48e..60c91b01a 100644 --- a/API-Editor/ComponentInformation.cs +++ b/API-Editor/ComponentInformation.cs @@ -60,10 +60,11 @@ internal sealed override void ApplySpecialMappingInternal(Component component, M ApplySpecialMapping((TComponent)component, collector); /// - /// Collects runtime depencencies of . + /// Collects runtime dependencies and runtime behavior information of . /// - /// This information is used for Garage Collection system in Avatar Optimizer. - /// You have to call some methods on to declare dependencies. + /// This information is used for Garage Collection system and automatic activeness toggle system in Avatar Optimizer. + /// You have to call some methods on to declare dependencies + /// and runtime behavior of the component. /// /// Please refer for more information about GC system and collecting dependencies. /// From f8bbe51e0946157bb4c9ee0839f0e62582c564ac Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Tue, 20 Aug 2024 01:24:18 +0900 Subject: [PATCH 03/12] docs: localize to ja developer documents --- .../index.ja.md | 125 +++++++++++++++--- 1 file changed, 107 insertions(+), 18 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index faee69b01..83777d91b 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -15,44 +15,133 @@ title: コンポーネントにAvatar Optimizerとの互換性をもたせる Avatar Optimizerが処理する時点でアバターにコンポーネントが存在している場合、そのコンポーネントはAvatar Optimizerと互換性が無い可能性があります。 -Avatar Optimizerはコンポーネント等に対するガベージコレクションシステムを実装しているため、最適化時にアバターに存在するすべてのコンポーネントのことを知る必要があります。 +Avatar Optimizerはビルドプロセスの最後の方に処理するようにデザイされており、Avatar Optimizer にとって未知のコンポーネントはサポートされていません。 -未知のコンポーネントによる問題を避けるため、Avatar Optimizerは未知のコンポーネントが以下のようなものであると仮定します。(この仮定は将来的に変更される可能性があります。) -- 副作用のあるコンポーネントである。 +例えば、Avatar Optimizerはコンポーネント等に対するガベージコレクションシステムを実装しています。 +未使用のコンポーネントを正しく削除し、使用されているコンポーネントを正しく保持するためには、 +最適化時にアバターに存在するすべてのコンポーネントのことを知る必要があります。 + +未知のコンポーネントによる問題を避けるため、Avatar Optimizerは未知のコンポーネントが以下のようなものであると仮定します。 +- コンポーネントが実行時に有効でアクティブになる可能性がある場合は保持する必要がある。 + - これは、Avatar Optimizerが未知のコンポーネントを実行時コンポーネントと仮定しているためです。 - コンポーネントが参照している全てのコンポーネントに依存している。 -この仮定は正しくない可能性があるため、Avatar Optimizerは未知のコンポーネントを見つけた場合に以下のような警告を生成します。 +(上記の仮定は将来変更される可能性があります。) + +しかしながら、この仮定は正しくない可能性があるため、Avatar Optimizerは以下のような警告を生成します。 ![unknown-component-warning](unknown-component-warning.png) ## どのように互換性を改善するか {#improve-compatibility} -Avatar Optimizerが処理する前にコンポーネントを削除出来る場合は、そのようにしてください。 -削除出来ない場合はAvatar Optimizerにコンポーネントを登録してください。 -Avatar Optimizer v1.7.0以降では、ビルド時やランタイムで処理を行わないコンポーネント向けに[Asset Description]が追加されています。 -ビルド時に処理を行わないようなツールであれば、こちらを利用して登録することもできます。 +To improve the compatibility, you may implement one of the following methods. + +1. Remove your components before Avatar Optimizer processes as much as possible. + + If your component is not working at runtime, (in other words, it's a build-time or edit mode only component), + it's mostly better for your tool to process avatar before Avatar Optimizer processes, + and remove your components before Avatar Optimizer processes. + + Please refer [section below](#remove-component) for more details. + + Avatar Optimizer internally uses this method for most Avatar Optimizer components, + that will be processed before Trace and Optimize. + +2. Register your components to Avatar Optimizer with API + + If your component is working at runtime, or your tool actually want to process avatar after Avatar Optimizer processes, + you can register your components to Avatar Optimizer to tell about your components. + + Please refer [section below](#register-component) for more details. + + Avatar Optimizer internally uses this method to keep some components that are processed after Trace and Optimize, + and components from Unity, VRCSDK, and other avatar platform components. + +3. Register your components as no problems to remove with Asset Description. + + Since Avatar Optimizer v1.7.0, you can use [Asset Description] to register components only for preserving data + for edit-mode tools, that doesn't effects on build or at runtime. + Please refer [Asset Description] for more details. + If your tool process nothing at build time or runtime, you can use this to register your components instead of + removing your components before Avatar Optimizer processes. + + If your tool process something at build time, registering with Asset Description is not recommended. + Using Asset Description for components that process something at build time may unexpectedly + remove your components and disables your tool if the execution order is incorrect or unexpectedly changed. + + This method is internally used by Avatar Optimizer to keep compatibility with well-known edit-mode tools. + + +互換性を改善するためには、以下のいずれかの方法を実装できます。 -ビルド時に何らかの処理を行うツールやコンポーネントの場合は、Asset Descriptionで登録するのは非推奨です。 -これは、Asset Descriptionによる登録では、ビルド時の処理順が意図しないものになってしまった場合などにAvatar Optimizerがコンポーネントを削除してしまうことにより、ツールが正しく動作出来なくなる可能性があるためです。 +1. Avatar Optimizerが処理する前にコンポーネントを削除する -[Asset Description]: ../asset-description + あなたのコンポーネントが実行時には動作しない場合(つまり、ビルド時や編集モードのみのコンポーネントである場合)、 + あなたのツールがAvatar Optimizerの処理より前にアバターを処理し、コンポーネントを削除するのが殆どの場合で最善です。 + + 詳細は[以下のセクション](#remove-component)を参照してください。 + + Avatar Optimizerは、TraceとOptimizeの前に処理されるAvatar Optimizerコンポーネントに対してこの方法を内部で使用しています。 + +2. APIを使ってAvatar Optimizerにコンポーネントを登録する + + コンポーネントが実行時に動作する場合、またはあなたのツールがAvatar Optimizerの処理後にアバターを処理したい場合、 + コンポーネントをAvatar Optimizerに登録して、コンポーネントについて知らせることができます。 + + 詳細は[以下のセクション](#register-component)を参照してください。 + + Avatar Optimizerは、TraceとOptimizeの後に処理される一部のコンポーネントや、Unity、VRCSDK、などアバターのプラットフォームのコンポーネントを保持するためにこの方法を内部で使用しています。 + +3. Asset Descriptionで削除しても問題がないものとしてコンポーネントを登録する + + Avatar Optimizer v1.7.0以降では、ビルド時やランタイムで処理を行わないコンポーネント向けに[Asset Description]が追加されています。 + ツールがビルド時やランタイムで何も処理しない場合、Avatar Optimizerがコ��ポーネントを削除する代わりに、 + この方法を使用してコンポーネントを登録することができます。 + 詳細は[Asset Description]を参照してください。 + + ツールがビルド時に何かしらの処理を行う場合、Asset Descriptionでコンポーネントを登録することは推奨されません。 + Asset Descriptionを使用してビルド時に何かしらの処理を行うコンポーネントを登録すると、 + 実行順序が正しくないか、予期しない変更があった場合に、コンポーネントが予期せず削除され、ツールが無効になる可能性があります。 + + この方法は、Avatar Optimizerがよく知られた編集モードツールとの互換性を保つために内部で使用されています。 ### コンポーネントを削除する {#remove-component} -コンポーネントを削除する方法はいくつかあります。 +You can remove your components with [`DestroyImmediate`][DestroyImmediate] to remove your components. -ツールがNDMF[^NDMF]を使用した非破壊ツールの場合は、NDMFのOptimizing phaseより前、 -またはOptimizing phaseの中で([`BeforePlugin`][ndmf-BeforePlugin]を用いて)`com.anatawa12.avatar-optimizer` plugin +There is several ways to process and remove your component from avatar before Avatar Optimizer processes on build. + +If your tool is a non-destructive tool based on NDMF[^NDMF], you can remove your components before the phases +prior to the Optimizing phase of NDMF or before `com.anatawa12.avatar-optimizer` plugin +(with [`BeforePlugin`][ndmf-BeforePlugin]) in the Optimizing phase. +If your tool removes your components in Optimizing phase, it's highly recommended to specify [`BeforePlugin`][ndmf-BeforePlugin] +even if your default callback order is before `com.anatawa12.avatar-optimizer` plugin. + +[`DestroyImmediate`]を使用してコンポーネントを削除できます。 + +ビルド時にAvatar Optimizerが処理する前に処理し、コンポーネントを削除する方法はいくつかあります。 + +ツールがNDMF[^NDMF]を使用した非破壊ツールの場合は、NDMFのOptimizing phaseより前のPhaseか、 +Optimizing phaseの中で([`BeforePlugin`][ndmf-BeforePlugin]を用いて)`com.anatawa12.avatar-optimizer` plugin より前にコンポーネントを削除することを推奨します。 +もし、ツールがOptimizing phaseでコンポーネントを削除する場合、デフォルトのコールバック順序が`com.anatawa12.avatar-optimizer` pluginより前であっても、 +[`BeforePlugin`][ndmf-BeforePlugin]を指定することを強く推奨します。 ツールがNDMF[^NDMF]を使用していない非破壊ツールの場合は、NDMFのOptimizing phaseより前にコンポーネントを削除することを推奨します。 この場合、現在のNDMFはVRCSDKの`RemoveAvatarEditorOnly`の直前であるorder `-1025`でOptimizing phaseを実行するので、 それより小さい`callbackOrder`を指定した`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除してください。 -ツールのコンポーネントがデータを保持する役割しかなく、ビルド時には意味を持っていない場合、 -`IVRCSDKPreprocessAvatarCallback`を用いてAvatar Optimizerが処理する前にコンポーネントを削除することを推奨します。 -`IVRCSDKPreprocessAvatarCallback`の順序については上記を参照してください。 + +If your components is only for holding information for your edit mode tool and has no meaning on the build time, +you can remove your components in `IVRCSDKPreprocessAvatarCallback` as described above, or +you can somply use [Asset Description] to register your components to be removed. + +もし、ツールのコンポーネントがデータを保持する役割しかなく、ビルド時には意味を持っていない場合、 +上記のように`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除するか、 +[Asset Description]を使用してコンポーネントを削除できるコンポーネントとして登録することができます。 + +[DestroyImmediate]: https://docs.unity3d.com/ScriptReference/Object.DestroyImmediate.html ### コンポーネントを登録する {#register-component} @@ -92,7 +181,7 @@ internal class YourComponentInformation : ComponentInformation `CollectMutations`では、コンポーネントの処理によって変更される可能性があるプロパティを登録します。\ `CollectDependency`では、ビルド時や実行時でのコンポーネントの依存関係を登録します。\ -詳しくはxmldocやメソッド名を参照してください。 +詳しくはそれぞれのメソッドの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_ From 59054616b5a7286877462cdbf0d82388ff3e8b8e Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Thu, 22 Aug 2024 03:00:24 +0900 Subject: [PATCH 04/12] docs: Update index.ja.md --- .../index.ja.md | 49 ------------------- 1 file changed, 49 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index 83777d91b..a3191b975 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -34,45 +34,6 @@ Avatar Optimizerはビルドプロセスの最後の方に処理するように ## どのように互換性を改善するか {#improve-compatibility} - -To improve the compatibility, you may implement one of the following methods. - -1. Remove your components before Avatar Optimizer processes as much as possible. - - If your component is not working at runtime, (in other words, it's a build-time or edit mode only component), - it's mostly better for your tool to process avatar before Avatar Optimizer processes, - and remove your components before Avatar Optimizer processes. - - Please refer [section below](#remove-component) for more details. - - Avatar Optimizer internally uses this method for most Avatar Optimizer components, - that will be processed before Trace and Optimize. - -2. Register your components to Avatar Optimizer with API - - If your component is working at runtime, or your tool actually want to process avatar after Avatar Optimizer processes, - you can register your components to Avatar Optimizer to tell about your components. - - Please refer [section below](#register-component) for more details. - - Avatar Optimizer internally uses this method to keep some components that are processed after Trace and Optimize, - and components from Unity, VRCSDK, and other avatar platform components. - -3. Register your components as no problems to remove with Asset Description. - - Since Avatar Optimizer v1.7.0, you can use [Asset Description] to register components only for preserving data - for edit-mode tools, that doesn't effects on build or at runtime. - Please refer [Asset Description] for more details. - If your tool process nothing at build time or runtime, you can use this to register your components instead of - removing your components before Avatar Optimizer processes. - - If your tool process something at build time, registering with Asset Description is not recommended. - Using Asset Description for components that process something at build time may unexpectedly - remove your components and disables your tool if the execution order is incorrect or unexpectedly changed. - - This method is internally used by Avatar Optimizer to keep compatibility with well-known edit-mode tools. - - 互換性を改善するためには、以下のいずれかの方法を実装できます。 1. Avatar Optimizerが処理する前にコンポーネントを削除する @@ -108,16 +69,6 @@ To improve the compatibility, you may implement one of the following methods. ### コンポーネントを削除する {#remove-component} -You can remove your components with [`DestroyImmediate`][DestroyImmediate] to remove your components. - -There is several ways to process and remove your component from avatar before Avatar Optimizer processes on build. - -If your tool is a non-destructive tool based on NDMF[^NDMF], you can remove your components before the phases -prior to the Optimizing phase of NDMF or before `com.anatawa12.avatar-optimizer` plugin -(with [`BeforePlugin`][ndmf-BeforePlugin]) in the Optimizing phase. -If your tool removes your components in Optimizing phase, it's highly recommended to specify [`BeforePlugin`][ndmf-BeforePlugin] -even if your default callback order is before `com.anatawa12.avatar-optimizer` plugin. - [`DestroyImmediate`]を使用してコンポーネントを削除できます。 ビルド時にAvatar Optimizerが処理する前に処理し、コンポーネントを削除する方法はいくつかあります。 From 4e1ce34223eddc70199aeeeeddf49e7b0bff235b Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Thu, 22 Aug 2024 03:01:02 +0900 Subject: [PATCH 05/12] docs: Update index.ja.md --- .../make-your-components-compatible-with-aao/index.ja.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index a3191b975..1b8b851da 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -83,11 +83,6 @@ Optimizing phaseの中で([`BeforePlugin`][ndmf-BeforePlugin]を用いて)`com.a この場合、現在のNDMFはVRCSDKの`RemoveAvatarEditorOnly`の直前であるorder `-1025`でOptimizing phaseを実行するので、 それより小さい`callbackOrder`を指定した`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除してください。 - -If your components is only for holding information for your edit mode tool and has no meaning on the build time, -you can remove your components in `IVRCSDKPreprocessAvatarCallback` as described above, or -you can somply use [Asset Description] to register your components to be removed. - もし、ツールのコンポーネントがデータを保持する役割しかなく、ビルド時には意味を持っていない場合、 上記のように`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除するか、 [Asset Description]を使用してコンポーネントを削除できるコンポーネントとして登録することができます。 From c84ad983a72cae5ee6caedc3764f21dd885dde61 Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Fri, 23 Aug 2024 03:34:32 +0900 Subject: [PATCH 06/12] docs: Apply suggestions from code review Co-authored-by: Sayamame-beans <61457993+Sayamame-beans@users.noreply.github.com> --- .../index.ja.md | 43 +++++++++---------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index 1b8b851da..1805efa14 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -15,57 +15,56 @@ title: コンポーネントにAvatar Optimizerとの互換性をもたせる Avatar Optimizerが処理する時点でアバターにコンポーネントが存在している場合、そのコンポーネントはAvatar Optimizerと互換性が無い可能性があります。 -Avatar Optimizerはビルドプロセスの最後の方に処理するようにデザイされており、Avatar Optimizer にとって未知のコンポーネントはサポートされていません。 +Avatar Optimizerはビルド処理の最後の方で動作するように設計されているため、Avatar Optimizerにとって未知のコンポーネントについてはサポートしていません。 例えば、Avatar Optimizerはコンポーネント等に対するガベージコレクションシステムを実装しています。 -未使用のコンポーネントを正しく削除し、使用されているコンポーネントを正しく保持するためには、 -最適化時にアバターに存在するすべてのコンポーネントのことを知る必要があります。 +使用されているコンポーネントを保持し、未使用のコンポーネントを適切に削除するためには、 +最適化時にアバターに存在するすべてのコンポーネントのことを知っておく必要があります。 未知のコンポーネントによる問題を避けるため、Avatar Optimizerは未知のコンポーネントが以下のようなものであると仮定します。 -- コンポーネントが実行時に有効でアクティブになる可能性がある場合は保持する必要がある。 - - これは、Avatar Optimizerが未知のコンポーネントを実行時コンポーネントと仮定しているためです。 +- コンポーネントが有効かつアクティブになる可能性がある場合は保持される必要がある。 + - これは、未知のコンポーネントを実行時(VRC上など)に動作するコンポーネントであると仮定しているためです。 - コンポーネントが参照している全てのコンポーネントに依存している。 -(上記の仮定は将来変更される可能性があります。) +(上記の仮定は将来的に変更される可能性があります。) -しかしながら、この仮定は正しくない可能性があるため、Avatar Optimizerは以下のような警告を生成します。 +しかしながら、これらの仮定は正しくない可能性があるため、Avatar Optimizerは以下のような警告を生成します。 ![unknown-component-warning](unknown-component-warning.png) ## どのように互換性を改善するか {#improve-compatibility} -互換性を改善するためには、以下のいずれかの方法を実装できます。 +以下の対応のいずれかを行うことで、互換性を改善することができます。 1. Avatar Optimizerが処理する前にコンポーネントを削除する - あなたのコンポーネントが実行時には動作しない場合(つまり、ビルド時や編集モードのみのコンポーネントである場合)、 - あなたのツールがAvatar Optimizerの処理より前にアバターを処理し、コンポーネントを削除するのが殆どの場合で最善です。 + コンポーネントが実行時では動作しないものである場合、(すなわち、ビルド時や編集モードでのみ動作するコンポーネントである場合、) + Avatar Optimizerより前にアバターを処理し、コンポーネントを削除することが殆どの場合で最善です。 詳細は[以下のセクション](#remove-component)を参照してください。 - Avatar Optimizerは、TraceとOptimizeの前に処理されるAvatar Optimizerコンポーネントに対してこの方法を内部で使用しています。 + Avatar Optimizerは、Trace and Optimizeの前に処理を行う殆どのAvatar Optimizerコンポーネントにおいて、内部的にこの方法を使用しています。 -2. APIを使ってAvatar Optimizerにコンポーネントを登録する +2. APIを使用してAvatar Optimizerにコンポーネントを登録する - コンポーネントが実行時に動作する場合、またはあなたのツールがAvatar Optimizerの処理後にアバターを処理したい場合、 - コンポーネントをAvatar Optimizerに登録して、コンポーネントについて知らせることができます。 + 実行時に動作するコンポーネントや、Avatar Optimizerより後にアバターを処理するために残しておく必要があるコンポーネントの場合、 + そのコンポーネントの情報をAvatar Optimizerに登録することができます。 詳細は[以下のセクション](#register-component)を参照してください。 - Avatar Optimizerは、TraceとOptimizeの後に処理される一部のコンポーネントや、Unity、VRCSDK、などアバターのプラットフォームのコンポーネントを保持するためにこの方法を内部で使用しています。 + Avatar Optimizerは、Trace and Optimizeの後に処理を行う一部のコンポーネントや、Unity純正のコンポーネント、VRCSDKのコンポーネントなどを保持するために、内部的にこの方法を使用しています。 -3. Asset Descriptionで削除しても問題がないものとしてコンポーネントを登録する +3. Asset Descriptionを使用して、削除しても問題のないコンポーネントとしてAvatar Optimizerに登録する Avatar Optimizer v1.7.0以降では、ビルド時やランタイムで処理を行わないコンポーネント向けに[Asset Description]が追加されています。 - ツールがビルド時やランタイムで何も処理しない場合、Avatar Optimizerがコ��ポーネントを削除する代わりに、 - この方法を使用してコンポーネントを登録することができます。 + ツールが実行時やビルド時に何も行わない場合は、「Avatar Optimizerが処理する前にコンポーネントを削除する」代わりにこの方法を使用してコンポーネントを登録することができます。 詳細は[Asset Description]を参照してください。 - ツールがビルド時に何かしらの処理を行う場合、Asset Descriptionでコンポーネントを登録することは推奨されません。 - Asset Descriptionを使用してビルド時に何かしらの処理を行うコンポーネントを登録すると、 - 実行順序が正しくないか、予期しない変更があった場合に、コンポーネントが予期せず削除され、ツールが無効になる可能性があります。 + なお、ツールが実行時やビルド時に何らかの処理を行う場合は、そのコンポーネントをAsset Descriptionで登録することは非推奨です。 + 実行時やビルド時に何らかの処理を行うコンポーネントをAsset Descriptionで登録してしまうと、 + 実行順に予期しない変更があったり、指定が正しくなかったりした場合に、コンポーネントがAvatar Optimizerに意図せず削除されてツールが正常に動作できなくなる可能性があります。 - この方法は、Avatar Optimizerがよく知られた編集モードツールとの互換性を保つために内部で使用されています。 + Avatar Optimizerは、編集モードでのみ動作するよく知られているツールとの互換性を保つために、内部的にこの方法を使用しています。 ### コンポーネントを削除する {#remove-component} From a17989fce64a1692c1e5f9691ab5f982a7445b9e Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Fri, 23 Aug 2024 21:34:00 +0900 Subject: [PATCH 07/12] =?UTF-8?q?docs:=20=E4=BB=A5=E4=B8=8B=E3=81=AE?= =?UTF-8?q?=E3=82=BB=E3=82=AF=E3=82=B7=E3=83=A7=E3=83=B3=20=3D>=20?= =?UTF-8?q?=E4=B8=8B=E3=81=AE=E3=82=BB=E3=82=AF=E3=82=B7=E3=83=A7=E3=83=B3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../make-your-components-compatible-with-aao/index.ja.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index 1805efa14..91e56b1d0 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -41,7 +41,7 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 コンポーネントが実行時では動作しないものである場合、(すなわち、ビルド時や編集モードでのみ動作するコンポーネントである場合、) Avatar Optimizerより前にアバターを処理し、コンポーネントを削除することが殆どの場合で最善です。 - 詳細は[以下のセクション](#remove-component)を参照してください。 + 詳細は[下のセクション](#remove-component)を参照してください。 Avatar Optimizerは、Trace and Optimizeの前に処理を行う殆どのAvatar Optimizerコンポーネントにおいて、内部的にこの方法を使用しています。 @@ -50,7 +50,7 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 実行時に動作するコンポーネントや、Avatar Optimizerより後にアバターを処理するために残しておく必要があるコンポーネントの場合、 そのコンポーネントの情報をAvatar Optimizerに登録することができます。 - 詳細は[以下のセクション](#register-component)を参照してください。 + 詳細は[下のセクション](#register-component)を参照してください。 Avatar Optimizerは、Trace and Optimizeの後に処理を行う一部のコンポーネントや、Unity純正のコンポーネント、VRCSDKのコンポーネントなどを保持するために、内部的にこの方法を使用しています。 From 81356834ee8ced963f80715b8944897ca310faef Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Sun, 25 Aug 2024 04:13:55 +0900 Subject: [PATCH 08/12] docs: Apply suggestions from code review Co-authored-by: Sayamame-beans <61457993+Sayamame-beans@users.noreply.github.com> --- .../index.ja.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index 91e56b1d0..dfb728d14 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -23,7 +23,7 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 未知のコンポーネントによる問題を避けるため、Avatar Optimizerは未知のコンポーネントが以下のようなものであると仮定します。 - コンポーネントが有効かつアクティブになる可能性がある場合は保持される必要がある。 - - これは、未知のコンポーネントを実行時(VRC上など)に動作するコンポーネントであると仮定しているためです。 + - これは、未知のコンポーネントを実行時(VRChat上など)に動作するコンポーネントであると仮定しているためです。 - コンポーネントが参照している全てのコンポーネントに依存している。 (上記の仮定は将来的に変更される可能性があります。) @@ -56,7 +56,7 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 3. Asset Descriptionを使用して、削除しても問題のないコンポーネントとしてAvatar Optimizerに登録する - Avatar Optimizer v1.7.0以降では、ビルド時やランタイムで処理を行わないコンポーネント向けに[Asset Description]が追加されています。 + Avatar Optimizer v1.7.0以降では、実行時やビルド時で処理を行わないコンポーネント向けに[Asset Description]が追加されています。 ツールが実行時やビルド時に何も行わない場合は、「Avatar Optimizerが処理する前にコンポーネントを削除する」代わりにこの方法を使用してコンポーネントを登録することができます。 詳細は[Asset Description]を参照してください。 @@ -70,21 +70,21 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 [`DestroyImmediate`]を使用してコンポーネントを削除できます。 -ビルド時にAvatar Optimizerが処理する前に処理し、コンポーネントを削除する方法はいくつかあります。 +ビルド時において、Avatar Optimizerより前にアバターを処理し、コンポーネントを削除するための方法はいくつかあります。削除には[`DestroyImmediate`]を用います。 ツールがNDMF[^NDMF]を使用した非破壊ツールの場合は、NDMFのOptimizing phaseより前のPhaseか、 Optimizing phaseの中で([`BeforePlugin`][ndmf-BeforePlugin]を用いて)`com.anatawa12.avatar-optimizer` plugin より前にコンポーネントを削除することを推奨します。 -もし、ツールがOptimizing phaseでコンポーネントを削除する場合、デフォルトのコールバック順序が`com.anatawa12.avatar-optimizer` pluginより前であっても、 -[`BeforePlugin`][ndmf-BeforePlugin]を指定することを強く推奨します。 +Optimizing phaseの中でコンポーネントを削除する場合は、デフォルトのコールバック順序が`com.anatawa12.avatar-optimizer` pluginより前であっても、 +[`BeforePlugin`][ndmf-BeforePlugin]を指定しておくことを強く推奨します。 ツールがNDMF[^NDMF]を使用していない非破壊ツールの場合は、NDMFのOptimizing phaseより前にコンポーネントを削除することを推奨します。 この場合、現在のNDMFはVRCSDKの`RemoveAvatarEditorOnly`の直前であるorder `-1025`でOptimizing phaseを実行するので、 それより小さい`callbackOrder`を指定した`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除してください。 -もし、ツールのコンポーネントがデータを保持する役割しかなく、ビルド時には意味を持っていない場合、 +ツールのコンポーネントにデータを保持する役割しかなく、ビルド時には意味を持っていない場合、 上記のように`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除するか、 -[Asset Description]を使用してコンポーネントを削除できるコンポーネントとして登録することができます。 +[Asset Description]を使用し、削除しても問題のないコンポーネントとして登録することができます。 [DestroyImmediate]: https://docs.unity3d.com/ScriptReference/Object.DestroyImmediate.html From d5c544cb5b15d8ce0af615e3520b26ec4b6bf5d3 Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Sun, 25 Aug 2024 04:14:26 +0900 Subject: [PATCH 09/12] docs: remove duplicated --- .../make-your-components-compatible-with-aao/index.ja.md | 1 - 1 file changed, 1 deletion(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index dfb728d14..bdb24a215 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -68,7 +68,6 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 ### コンポーネントを削除する {#remove-component} -[`DestroyImmediate`]を使用してコンポーネントを削除できます。 ビルド時において、Avatar Optimizerより前にアバターを処理し、コンポーネントを削除するための方法はいくつかあります。削除には[`DestroyImmediate`]を用います。 From 7828873b453e79646f70f8b5cdf3b93e182ad059 Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Mon, 26 Aug 2024 18:54:10 +0900 Subject: [PATCH 10/12] docs: Apply suggestions from code review Co-authored-by: Sayamame-beans <61457993+Sayamame-beans@users.noreply.github.com> --- .../index.ja.md | 3 +- .../index.md | 29 +++++++++---------- 2 files changed, 16 insertions(+), 16 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index bdb24a215..7c59f989f 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -58,6 +58,7 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 Avatar Optimizer v1.7.0以降では、実行時やビルド時で処理を行わないコンポーネント向けに[Asset Description]が追加されています。 ツールが実行時やビルド時に何も行わない場合は、「Avatar Optimizerが処理する前にコンポーネントを削除する」代わりにこの方法を使用してコンポーネントを登録することができます。 + 詳細は[Asset Description]を参照してください。 なお、ツールが実行時やビルド時に何らかの処理を行う場合は、そのコンポーネントをAsset Descriptionで登録することは非推奨です。 @@ -79,7 +80,7 @@ Optimizing phaseの中でコンポーネントを削除する場合は、デフ ツールがNDMF[^NDMF]を使用していない非破壊ツールの場合は、NDMFのOptimizing phaseより前にコンポーネントを削除することを推奨します。 この場合、現在のNDMFはVRCSDKの`RemoveAvatarEditorOnly`の直前であるorder `-1025`でOptimizing phaseを実行するので、 -それより小さい`callbackOrder`を指定した`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除してください。 +`-1025`より小さい`callbackOrder`を指定した`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除してください。 ツールのコンポーネントにデータを保持する役割しかなく、ビルド時には意味を持っていない場合、 上記のように`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除するか、 diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md index cee1fff95..be118fe9a 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md @@ -24,13 +24,13 @@ To correctly remove unused components, and correctly keep used components, Avatar Optimizer has to know about all existing components in the Avatar at the optimization. To avoid problem with unknown components, Avatar Optimizer currently assumes unknown components -- have to keep if the component can be enabled and active at runtime. +- have to be kept if the component can be enabled and active at runtime. - This is because Avatar Optimizer assumes unknown components are runtime components. - will have dependency relationship to all components referenced in the component. -(Those assumption above can be changed in the future.) +(Those assumptions above can be changed in the future.) -However, the assumption can be incorrect, so Avatar Optimizer will generate a warning like below. +However, those assumptions can be incorrect, so Avatar Optimizer will generate a warning like below. ![unknown-component-warning](unknown-component-warning.png) @@ -51,7 +51,7 @@ To improve the compatibility, you may implement one of the following methods. 2. Register your components to Avatar Optimizer with API - If your component is working at runtime, or your tool actually want to process avatar after Avatar Optimizer processes, + If your component is working at runtime, or your tool actually wants to keep your components for processing avatar after Avatar Optimizer processes, you can register your components to Avatar Optimizer to tell about your components. Please refer [section below](#register-component) for more details. @@ -61,25 +61,24 @@ To improve the compatibility, you may implement one of the following methods. 3. Register your components as no problems to remove with Asset Description. - Since Avatar Optimizer v1.7.0, you can use [Asset Description] to register components only for preserving data - for edit-mode tools, that doesn't effects on build or at runtime. + Since Avatar Optimizer v1.7.0, you can use [Asset Description] to register components only for holding data + for edit-mode tools, that doesn't affects on build or at runtime. If your tool process nothing at build time or runtime, you can use this to register your components instead of removing your components before Avatar Optimizer processes. + Please refer [Asset Description] for more details. - If your tool process something at build time, registering with Asset Description is not recommended. - Using Asset Description for components that process something at build time may unexpectedly - remove your components and disables your tool if the execution order is incorrect or unexpectedly changed. + If your tool process something at build time or runtime, registering with Asset Description is not recommended. + If you use Asset Description for components that process something at build time or runtime, it may cause unexpectedly + removing your components and your tool not working properly when the execution order is incorrect or unexpectedly changed. - This method is internally used by Avatar Optimizer to keep compatibility with well-known edit-mode tools. + Avatar Optimizer internally uses this method to keep compatibility with well-known edit-mode tools. [Asset Description]: ../asset-description ### Removing your components {#remove-component} -You can remove your components with [`DestroyImmediate`][DestroyImmediate] to remove your components. - -There is several ways to process and remove your component from avatar before Avatar Optimizer processes on build. +There are several ways to process and remove your components from avatar before Avatar Optimizer processes on build. You can use [`DestroyImmediate`][DestroyImmediate] method for removing your components. If your tool is a non-destructive tool based on NDMF[^NDMF], you can remove your components before the phases prior to the Optimizing phase of NDMF or before `com.anatawa12.avatar-optimizer` plugin @@ -92,9 +91,9 @@ the NDMF's Optimizing phase is recommended. In this case, current NDMF executes Optimizing phase in order `-1025`, which is JUST before VRCSDK's `RemoveAvatarEditorOnly` callback, so your tool should remove components with `IVRCSDKPreprocessAvatarCallback` with `callbackOrder` smaller than `-1025`. -If your components is only for holding information for your edit mode tool and has no meaning on the build time, +If your components is only for holding data for your edit-mode tool and doesn't affects on build or at runtime, you can remove your components in `IVRCSDKPreprocessAvatarCallback` as described above, or -you can somply use [Asset Description] to register your components to be removed. +you can simply use [Asset Description] to register your components as safe-to-remove components [DestroyImmediate]: https://docs.unity3d.com/2022.3/Documentation/ScriptReference/Object.DestroyImmediate.html From e4c64ba354b2efa23468056f51245c16ebdf982f Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Mon, 26 Aug 2024 21:34:02 +0900 Subject: [PATCH 11/12] docs: Apply suggestions from code review Co-authored-by: Sayamame-beans <61457993+Sayamame-beans@users.noreply.github.com> --- .../make-your-components-compatible-with-aao/index.ja.md | 4 ++-- .../make-your-components-compatible-with-aao/index.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index 7c59f989f..2978666e8 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -23,7 +23,7 @@ Avatar Optimizerはビルド処理の最後の方で動作するように設計 未知のコンポーネントによる問題を避けるため、Avatar Optimizerは未知のコンポーネントが以下のようなものであると仮定します。 - コンポーネントが有効かつアクティブになる可能性がある場合は保持される必要がある。 - - これは、未知のコンポーネントを実行時(VRChat上など)に動作するコンポーネントであると仮定しているためです。 + - これは、未知のコンポーネントが実行時(VRChat上など)に動作するコンポーネントであると仮定しているためです。 - コンポーネントが参照している全てのコンポーネントに依存している。 (上記の仮定は将来的に変更される可能性があります。) @@ -82,7 +82,7 @@ Optimizing phaseの中でコンポーネントを削除する場合は、デフ この場合、現在のNDMFはVRCSDKの`RemoveAvatarEditorOnly`の直前であるorder `-1025`でOptimizing phaseを実行するので、 `-1025`より小さい`callbackOrder`を指定した`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除してください。 -ツールのコンポーネントにデータを保持する役割しかなく、ビルド時には意味を持っていない場合、 +ツールのコンポーネントにデータを保持する役割しかなく、実行時やビルド時では処理を行わない場合、 上記のように`IVRCSDKPreprocessAvatarCallback`でコンポーネントを削除するか、 [Asset Description]を使用し、削除しても問題のないコンポーネントとして登録することができます。 diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md index be118fe9a..b780d5eb6 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md @@ -93,7 +93,7 @@ callback, so your tool should remove components with `IVRCSDKPreprocessAvatarCal If your components is only for holding data for your edit-mode tool and doesn't affects on build or at runtime, you can remove your components in `IVRCSDKPreprocessAvatarCallback` as described above, or -you can simply use [Asset Description] to register your components as safe-to-remove components +you can simply use [Asset Description] to register your components as safe-to-remove components. [DestroyImmediate]: https://docs.unity3d.com/2022.3/Documentation/ScriptReference/Object.DestroyImmediate.html From a0c5ebf022649b1dc43058afd829c6a366fe267b Mon Sep 17 00:00:00 2001 From: anatawa12 Date: Mon, 26 Aug 2024 22:05:02 +0900 Subject: [PATCH 12/12] chore: add asset description section --- .../make-your-components-compatible-with-aao/index.ja.md | 4 ++++ .../make-your-components-compatible-with-aao/index.md | 4 ++++ 2 files changed, 8 insertions(+) diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md index 2978666e8..8a2660ed8 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.ja.md @@ -128,6 +128,10 @@ internal class YourComponentInformation : ComponentInformation `CollectDependency`では、ビルド時や実行時でのコンポーネントの依存関係を登録します。\ 詳しくはそれぞれのメソッドのxmldocを参照してください。 +### Asset Descriptionを作成する {#asset-description} + +別ページにある[Asset Description]を参照してください + [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 diff --git a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md index b780d5eb6..bfcbb6c5e 100644 --- a/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md +++ b/.docs/content/docs/developers/make-your-components-compatible-with-aao/index.md @@ -138,6 +138,10 @@ In `CollectMutations`, you should register any mutation your component may do.\ In `CollectDependency`, you should register build-time or run-time dependencies and related information of your component.\ Please read xmldoc of each methods for more details. +### Use Asset Description {#asset-description} + +Please refer [Asset Description] for more details. + [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