docs: documentation for general reactive components (#946)

This commit is contained in:
bd_ 2024-08-04 20:44:10 -07:00 committed by GitHub
parent 8e7526e711
commit 7a3b782fae
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
9 changed files with 134 additions and 45 deletions

View File

@ -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.

View File

@ -1,43 +0,0 @@
# Object Toggle
<!-- TODO: Screenshot -->
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.

View File

@ -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.

View File

@ -0,0 +1,19 @@
# Object Toggle
<!-- TODO: Screenshot -->
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.

View File

@ -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

View File

@ -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オブジェクトが常に有効であれば、メッシュの一部を削除することさえできます。

View File

@ -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が他の反射コンポーネントに与える影響は考慮しません。
反射コンポーネントの完全な効果を見るには、再生モードに入る必要があります。