From 7a3b782fae9b1901686be34509debbcf78ffd62d Mon Sep 17 00:00:00 2001 From: bd_ Date: Sun, 4 Aug 2024 20:44:10 -0700 Subject: [PATCH] docs: documentation for general reactive components (#946) --- .../for-outfit-creators/index.md | 3 +- docs~/docs/reference/object-toggle.md | 43 -------------- .../reference/reactive-components/index.md | 56 +++++++++++++++++++ .../reactive-components/object-toggle.md | 19 +++++++ .../shape-changer.md | 3 + .../for-outfit-creators/index.md | 3 +- .../reference/reactive-components/index.md | 52 +++++++++++++++++ .../object-toggle.md | 0 .../shape-changer.md | 0 9 files changed, 134 insertions(+), 45 deletions(-) delete mode 100644 docs~/docs/reference/object-toggle.md create mode 100644 docs~/docs/reference/reactive-components/index.md create mode 100644 docs~/docs/reference/reactive-components/object-toggle.md rename docs~/docs/reference/{ => reactive-components}/shape-changer.md (94%) create mode 100644 docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/index.md rename docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/{ => reactive-components}/object-toggle.md (100%) rename docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/{ => reactive-components}/shape-changer.md (100%) diff --git a/docs~/docs/distributing-prefabs/for-outfit-creators/index.md b/docs~/docs/distributing-prefabs/for-outfit-creators/index.md index f8b674e3..ebd20622 100644 --- a/docs~/docs/distributing-prefabs/for-outfit-creators/index.md +++ b/docs~/docs/distributing-prefabs/for-outfit-creators/index.md @@ -253,7 +253,8 @@ This is an unreleased feature, which is planned to be released with Modular Avat Many avatars have shape keys which can be used to shrink and hide parts of the base mesh, to avoid clipping into the outfit. Modular Avatar has a feature which can be used to automate this process. By configuring the -[Shape Changer](../../reference/shape-changer.md) component, Modular Avatar will automatically shrink or hide shape keys +[Shape Changer](../../reference/reactive-components/shape-changer.md) component, Modular Avatar will automatically +shrink or hide shape keys when the corresponding object is enabled. This will also respond to animations which turn on/off parts of the outfit, and can even outright _delete_ portions of the mesh, if the Shape Changer object is always enabled. diff --git a/docs~/docs/reference/object-toggle.md b/docs~/docs/reference/object-toggle.md deleted file mode 100644 index 6c78ffb5..00000000 --- a/docs~/docs/reference/object-toggle.md +++ /dev/null @@ -1,43 +0,0 @@ -# Object Toggle - - - -The Object Toggle component allows you to change the active state of one or more other GameObjects, based on the active -state of a controlling object. - -## When should I use it? - -This component is useful to disable one mesh when another mesh is covering it entirely. For example, you might want to -disable an underwear mesh when it's fully covered by other clothing. - -## Setting up Object Toggle - -Simply add an Object Toggle component to the controlling object, then click the + and select a target object to be -controlled. The checkmark controls whether the target object will be enabled or disabled. - -### Conflict resolution - -When multiple Object Toggles are active and try to control the same target object, the Object Toggle that is last in -hierarchy order will win. When no Object Toggles are active, the original state of the object, or animated state (if -some other animation is trying to animate that object) wins. - -### Response timing - -Object Toggle updates the affected objects one frame after the controlling object is updated. To avoid any unfortunate -"accidents", when an Object Toggle is disabled, the object that was disabled (either the Object Toggle itself or one of -its parents) in its parent hierarchy will be disabled one frame later than they would otherwise. This ensures that if -you use Object Toggle to hide a mesh when it's fully covered, the covering mesh will remain visible until the same frame -as when the inner mesh is enabled again. - -When you use an Object Toggle to control another Object Toggle, this delay only applies to each Object Toggle -individually. That is, if you have A -> B -> C, and A is turned off, the timing will be as follows: - -* Frame 1: Nothing happens (A's disable is delayed) -* Frame 2: A is disabled (B's disable is delayed) -* Frame 3: B and C are disabled at the same time. - -### Preview system limitations - -The effect of Object Toggles on mesh visibility is immediately reflected in the editor scene view. However, the impact -of Object Toggles on other responsive components, such as other Object Toggles or [Shape Changers](./shape-changer.md) -will not be reflected in the preview display. To see the full effect of Object Toggles, you must enter play mode. \ No newline at end of file diff --git a/docs~/docs/reference/reactive-components/index.md b/docs~/docs/reference/reactive-components/index.md new file mode 100644 index 00000000..bf2f3e6f --- /dev/null +++ b/docs~/docs/reference/reactive-components/index.md @@ -0,0 +1,56 @@ +--- +sidebar_position: 1 +--- + +# Reactive Components + +Reactive Components are components which apply some effect to your avatar based on the active state of their GameObject +(and its parents), or [Menu Item](../menu-item.md) enabled states. This allows you to build up simple toggles, adjust +blendshapes as you change your outfit, and more - without needing to manually set up any animations. + +The following reactive components are currently available: + +* [Object Toggle](./object-toggle.md) - controls the active state of other game objects +* [Shape Changer](./shape-changer.md) - modifies blendshapes on a target renderer + +## General rules for reactive components + +In general, reactive components apply some kind of effect when they are _active_. A reactive component is considered +active when: + +- Its GameObject, and all parents, is active in the scene hierarchy. +- If the reactive object is on the same GameObject as a [Menu Item](../menu-item.md), the Menu Item is selected. + +After building your avatar, reactive components respond to the following: + +- Animations which change the state of GameObjects +- Object Toggles which influence the active state of other reactive components +- Menu Item selections + +### Priority rules + +If multiple reactive components are active at the same time, and their effects conflict (e.g., one tries to turn off a +game object, one tries to turn on a game object), the component lowest in the hierarchy takes precedence. + +### Reaction timing + +Reactive components responding to the change of a GameObject's active state will do so after a one frame delay. When the +game object is being deactivated, the game object's deactivation will be delayed by one frame to happen at the same +time. +See [Shape Changer](./shape-changer.md) for more information on why this is the case. + +If one reactive component controls the state of another reactive component, then there will be a one frame delay between +each reactive component triggering. The delay will be applied to each reactive component individually, so if you have +A -> B -> C, and A is turned off, the timing will be as follows: + +* Frame 1: Nothing happens (A's disable is delayed) +* Frame 2: A is disabled (B's disable is delayed) +* Frame 3: B and C are disabled at the same time. + +### Preview system + +The effect of reactive components on mesh visibility is immediately reflected in the editor scene view. However, this +has some limitations; in particular, it considers the current active state of objects, and the "default" state of Menu +Items, but does not consider the effect of Object Toggles on other reactive components. To see the full effect of +reactive +components, you must enter play mode. \ No newline at end of file diff --git a/docs~/docs/reference/reactive-components/object-toggle.md b/docs~/docs/reference/reactive-components/object-toggle.md new file mode 100644 index 00000000..6187f993 --- /dev/null +++ b/docs~/docs/reference/reactive-components/object-toggle.md @@ -0,0 +1,19 @@ +# Object Toggle + + + +The Object Toggle component allows you to change the active state of one or more other GameObjects, based on the active +state of a controlling object. + +Object Toggle is a type of [Reactive Component](./index.md). See that page for general rules and behavior of reactive +components. + +## When should I use it? + +This component is useful to disable one mesh when another mesh is covering it entirely. For example, you might want to +disable an underwear mesh when it's fully covered by other clothing. + +## Setting up Object Toggle + +Simply add an Object Toggle component to the controlling object, then click the + and select a target object to be +controlled. The checkmark controls whether the target object will be enabled or disabled. diff --git a/docs~/docs/reference/shape-changer.md b/docs~/docs/reference/reactive-components/shape-changer.md similarity index 94% rename from docs~/docs/reference/shape-changer.md rename to docs~/docs/reference/reactive-components/shape-changer.md index ae8b79e5..cc985ee6 100644 --- a/docs~/docs/reference/shape-changer.md +++ b/docs~/docs/reference/reactive-components/shape-changer.md @@ -5,6 +5,9 @@ The Shape Changer component modifies the shape keys (blendshapes) of another renderer on the avatar, when the Shape Changer component is enabled. +Shape Changer is a type of [Reactive Component](./index.md). See that page for general rules and behavior of reactive +components. + ## When should I use it? This component is intended to be used on outfit meshes, in order to delete or shrink parts of the avatar base model diff --git a/docs~/i18n/ja/docusaurus-plugin-content-docs/current/distributing-prefabs/for-outfit-creators/index.md b/docs~/i18n/ja/docusaurus-plugin-content-docs/current/distributing-prefabs/for-outfit-creators/index.md index b13daacd..0321567a 100644 --- a/docs~/i18n/ja/docusaurus-plugin-content-docs/current/distributing-prefabs/for-outfit-creators/index.md +++ b/docs~/i18n/ja/docusaurus-plugin-content-docs/current/distributing-prefabs/for-outfit-creators/index.md @@ -230,7 +230,8 @@ Modular Avatarをサポートするための最低限の要件について話し 多くのアバターには、素体メッシュの一部を縮小したり非表示にしたりするためのシェープキーが含まれています。これにより、衣装が素体メッシュに めり込むことを防ぐことができます。Modular Avatarには、この処理を自動化する機能があります。 -[Shape Changer](../../reference/shape-changer.md)コンポーネントを設定することで、Modular Avatarは対応するオブジェクトが有効になると、 +[Shape Changer](../../reference/reactive-components/shape-changer.md)コンポーネントを設定することで、Modular +Avatarは対応するオブジェクトが有効になると、 シェープキーを自動的に縮小または非表示にします。また、アニメーションによって衣装の一部がオン/オフになる場合にも応答し、 Shape Changerオブジェクトが常に有効であれば、メッシュの一部を削除することさえできます。 diff --git a/docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/index.md b/docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/index.md new file mode 100644 index 00000000..09840690 --- /dev/null +++ b/docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/index.md @@ -0,0 +1,52 @@ +--- +sidebar_position: 1 +--- + +# 反射コンポーネント + +反射コンポーネントとは、付属しているGameObject、その親のアクティブ状態、そして[Menu Item](../menu-item.md)の選択状態に応じて何かを +引き起こすコンポーネントです。これにより、手動でアニメーションを設定することなく、簡単なトグルを構築したり、衣装の状態に応じてブレンドシェープを +変えたりすることができます。 + +現在利用可能な反射コンポーネントは次の通りです: + +- [Object Toggle](./object-toggle.md) - 他のゲームオブジェクトのアクティブ状態を制御します +- [Shape Changer](./shape-changer.md) - レンダラーのブレンドシェープを変更します + +## 反射コンポーネントの一般的なルール + +一般的に、反射コンポーネントは起動状態ときに何らかの効果を適用します。反射コンポーネントは次の条件が満たされるときに起動状態とみなされます: + +- 付属しているGameObjectとその親がシーン階層でアクティブである +- 反射オブジェクトが[Menu Item](../menu-item.md)と同じGameObjectにある場合、Menu Itemが選択されている + +アバターを構築した後、反射コンポーネントは以下に反応します: + +- GameObjectの状態を変更するアニメーション +- 他の反射コンポーネントのアクティブ状態に影響を与えるObject Toggle +- Menu Itemの選択 + +### 優先ルール + +同時に複数の反射コンポーネントが起動状態であり、その効果が競合する場合(例: 1つがゲームオブジェクトをオフにしようとし、もう1つが +オンにしようとする場合)、階層の一番下にあるコンポーネントが優先されます。 + +### 反応タイミング + +GameObjectのアクティブ状態の変更に反応する反射コンポーネントは、1フレームの遅延後に反応します。ゲームオブジェクトが非アクティブになる場合、 +ゲームオブジェクトの非アクティブ化は1フレーム遅れて行われ、同時に行われます。この理由については[Shape Changer](./shape-changer.md) +を +参照してください。 + +1つの反射コンポーネントが他の反射コンポーネントの状態を制御する場合、各反射コンポーネントの発動に1フレームの遅延があります。遅延は +個々の反射コンポーネントに適用され、A -> B -> Cのような構造でAがオフになる場合、タイミングは次のようになります: + +- フレーム1: 何も起こらない(Aの無効化が遅延) +- フレーム2: Aが無効化される(Bの無効化が遅延) +- フレーム3: BとCが同時に無効化される + +### プレビューシステム + +反射コンポーネントのメッシュ可視性への影響は、エディタのシーンビューに即座に反映されます。ただし、これにはいくつかの制限があります。特に、 +オブジェクトの現在のアクティブ状態とMenu Itemの「デフォルト」状態を考慮しますが、Object Toggleが他の反射コンポーネントに与える影響は考慮しません。 +反射コンポーネントの完全な効果を見るには、再生モードに入る必要があります。 diff --git a/docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/object-toggle.md b/docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/object-toggle.md similarity index 100% rename from docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/object-toggle.md rename to docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/object-toggle.md diff --git a/docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/shape-changer.md b/docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/shape-changer.md similarity index 100% rename from docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/shape-changer.md rename to docs~/i18n/ja/docusaurus-plugin-content-docs/current/reference/reactive-components/shape-changer.md