LiveProperty でリモートアプリにパラメータを公開する

警告

実験的な機能が多く、破壊的な仕様変更が入ることがあります。

VirgoMotionStudioTemplate のスタジオアプリ側スクリプトに [LiveClass] / [LiveField] / [LiveProperty] などの属性を付けると、そのメンバーは LiveProperty（ライブプロパティ） になります。LiveProperty は次の用途で共通して使われます。

• リモートアプリからの値の編集・関数の呼び出し
• ライブシーン（*.live.json）への保存と復元
• ライブデータ（*.live.bin）への収録と再生

旧 Exposed* 属性からの移行

RemoteControl 0.26.0 で [ExposedClass] などの Exposed* 属性は Live* に改名されました。対応表は旧名からの移行を参照してください。

最小例

1. スクリプトを書く

MonoBehaviour に [LiveClass] と [LiveField] を付けます。

using UnityEngine;
using Lilium.RemoteControl;

[LiveClass]
public class MyEffect : MonoBehaviour
{
    [LiveField]
    public int hoge;
}

2. GameObject を追加してスクリプトをアタッチする

VirgoMotionStudioTemplate の Studio シーンに空の GameObject を作り、上のスクリプトをアタッチします。

3. Remote Control Container に登録する

シーンに配置済みの Remote Control Container GameObject を選択し、Remote Control Container コンポーネントの Objects リストに項目を追加します。

1. Objects の + ボタンを押し、型ドロップダウンから LiveGameObject を選択する
2. その項目の Reference に手順 2 で作った GameObject をドラッグして割り当てる

Id は項目を追加したときに自動で割り振られます。ライブシーンに保存した値はこの Id を宛先にして復元されるため、後から書き換えないでください。

[LiveClass] を付けただけでは、リモートアプリの「ライブシーン」ページには現れません。Objects に登録した GameObject に付いている [LiveClass] コンポーネントが、まとめて公開されます。

ヒント

位置・回転・スケールもリモートアプリから操作したい場合は、LiveGameObject の代わりに LiveGameObjectWithTransform を選びます。

4. 動作確認

Unity Editor で Play するか、ビルドしたアプリを起動してリモートアプリを接続します。リモートアプリの「ライブシーン」ページに MyEffect が並び、hoge フィールドが整数入力として表示されます。値を変更するとその場で反映され、ライブシーンを保存すると *.live.json に書き込まれます。

ヒント

Play しなくても、エディタツールバーのサーバートグル（devices アイコン）でサーバーを開始すれば、エディットモードのままリモートアプリから接続できます。

注記

追加した [LiveField] 等がリモートアプリ側で正常に認識されないことがあります。その場合は Play を停止した後、Window > Lilium Remote Control > UI Designer の Reset ボタンを押して、Play を再実行してください。

属性の使い分け

属性	付ける対象	用途
[LiveClass]	class / struct	この型を LiveProperty を持つ型として登録する
[LiveField]	field	フィールドを公開し、編集可能にする
[LiveProperty]	property	プロパティを公開する。setter があれば編集可能、getter のみなら読み取り専用の表示になる
[LiveFunction]	method	メソッドをボタンとして公開する
[LiveEnum]	enum	enum 値をドロップダウンとして表示するために必要
[Help("...")]	上記いずれか	リモートアプリ上にヘルプテキストを表示する
[Hide]	field / property / method	公開済みのメンバーをリモートアプリの UI から隠す

[LiveField] で十分なケースが大半です。値が変わったときに処理を走らせたい場合は [LiveProperty] を使います。

LiveProperty で値の変更時に処理を走らせる

[LiveProperty] を付けたプロパティは、リモートアプリから値を書き込むと setter が呼ばれます。setter に処理を書けば、値の変更をその場でシーンに反映できます。

using UnityEngine;
using Lilium.RemoteControl;

[LiveClass]
public class MyLight : MonoBehaviour, ILiveDeserializeCallback
{
    [SerializeField]
    private Light targetLight;

    // 保存される実体（shadow field）
    [LiveField, Hide, FormerlyNamedAs("intensity")]
    private float _intensity = 1f;

    // リモートアプリに表示されるメンバー
    [LiveProperty, Slider(0f, 8f)]
    public float intensity
    {
        get => _intensity;
        set
        {
            _intensity = value;
            targetLight.intensity = value; // 変更時の処理
        }
    }

    // ライブシーンの読み込み後に呼ばれる
    public void OnAfterLiveDeserialize()
    {
        targetLight.intensity = _intensity;
    }
}

• [LiveProperty] だけではライブシーンに保存されません。保存するには、[LiveField, Hide, FormerlyNamedAs("プロパティ名")] を付けたフィールドをペアにします。このフィールドを shadow field と呼び、リモートアプリにはプロパティ側だけが表示されます。
• ライブシーンの保存・復元は shadow field を直接読み書きし、setter は呼ばれません。読み込み後に必要な処理は ILiveDeserializeCallback.OnAfterLiveDeserialize に書きます。
• 値の実体が他のコンポーネントにあるなど、shadow field が古くなりうる場合は、ILiveSerializeCallback.OnBeforeLiveSerialize で保存直前に shadow field を更新します。

表示コントロールを変える

数値スライダー、ラベル、表示順などは属性で制御できます。

using UnityEngine;
using Lilium.RemoteControl;

[LiveClass(Category = "Effect", Icon = "auto_fix_high")]
public class MyEffect : MonoBehaviour
{
    [LiveField, Slider(0f, 1f, 0.01f)]
    public float intensity = 0.5f;

    [LiveField, Slider(1, 10)]
    public int repeat = 3;

    [LiveField]
    public Color tint = Color.white;

    [LiveFunction(label = "リセット")]
    public void ResetParams()
    {
        intensity = 0.5f;
        repeat = 3;
        tint = Color.white;
    }
}

指定	効果
[Slider(min, max, step)]	数値をスライダーで表示する（step を省略すると範囲の 1/20）
[LiveClass(Category = "...")]	「ライブシーン」ページでの分類見出し
[LiveClass(Icon = "...")]	Material Icons のアイコン名を指定
label	表示名（[LiveField(label = "強さ")] など）
order	表示順（負で前、正で後ろ）
[LiveFunction(icon = "...")]	ボタンに表示するアイコン（Material Icons）

enum を選択肢として公開する

enum 型のフィールドは [LiveEnum] を付けた enum である必要があります。

using UnityEngine;
using Lilium.RemoteControl;

[LiveEnum]
public enum EffectMode
{
    Off,
    Soft,
    Strong,
}

[LiveClass]
public class MyEffect : MonoBehaviour
{
    [LiveField]
    public EffectMode mode = EffectMode.Soft;
}

HumanBodyBones のように自分で属性を付けられない enum は、アセンブリ属性 [LiveExternalEnum] で登録します。

[assembly: Lilium.RemoteControl.LiveExternalEnum(typeof(UnityEngine.HumanBodyBones), excludeNames = new[] { "LastBone" })]

条件付き表示

ShowIf / HideIf で他のフィールドの値に応じた表示制御ができます。複数付けた場合は、すべての条件を満たしたときに表示されます。[LiveFunction] のボタンにも付けられます。

[LiveField]
public bool useColor;

[LiveField, ShowIf(nameof(useColor), true)]
public Color color = Color.white;

保存先を選ぶ

既定では、LiveProperty の値はライブシーン（*.live.json）に保存されます。

指定	保存先
指定なし	ライブシーン（*.live.json）
[LiveField(persistable = false)]	保存しない（リモートアプリには公開される）
[LiveField(persistScope = PersistScope.Project)]	ライブプロジェクト全体の設定ファイル（{クラス名}.settings.json）

persistable = false は、一時的な実験用の値や、起動時に毎回リセットしたい値に使います。PersistScope.Project は、ポート番号などシーンを切り替えても変わらない設定に使います。

ライブシーンに保存されるメンバーは、ライブデータの収録対象にもなります。保存しないメンバーやプロジェクト設定に保存するメンバーは収録されません。

注記

公開メンバーの追加・型変更・リネームを行うと、過去に保存した *.live.json との互換性が崩れることがあります。リネーム時は [FormerlyNamedAs("旧名")] を付けると、旧名で保存された値も復元できます。クラス名の変更にも使えます。

スクリプトを変更せずに公開する（Live Class Asset）

Unity の組み込みコンポーネントやサードパーティ製のコンポーネントなど、属性を付けられないクラスは Live Class Asset で公開できます。

1. Window > Lilium Remote Control > Live Class Asset を開く
2. Preset に Live Class Asset を割り当てる（New で新規作成）
3. クラス一覧の +（全クラスから検索）または From Selected（選択中の GameObject のコンポーネントから選ぶ）でクラスを追加する
4. 右側の詳細ペインの + で、公開するプロパティ・フィールド・メソッドにチェックを入れる。ラベルやコントロール（スライダーなど）もここで設定する
5. アセットを適用する。プロジェクト全体に適用するなら Project Settings > Lilium Remote Control のリストに、シーンやセットと一緒に持ち運ぶなら Remote Control Container の Assets に追加する

公開したいコンポーネントを持つ GameObject は、手順 3 と同じく Remote Control Container の Objects に登録します。詳しい手順は LiveClassAsset で任意のプロパティを公開する を参照してください。

旧名からの移行

RemoteControl 0.26.0 で「Exposed」の名前はすべて「Live」に改名されました。

旧	新
[ExposedClass]	[LiveClass]
[ExposedField]	[LiveField]
[ExposedProperty]	[LiveProperty]
[ExposedFunction]	[LiveFunction]
[ExposedEnum]	[LiveEnum]
[ExposedExternalEnum]	[LiveExternalEnum]
[ExposedKey]	[LiveKey]
[ExposedDefault]	[LiveDefault]
[ExposedHelp("...")]	[Help("...")]
[FormerlyExposedAs("...")]	[FormerlyNamedAs("...")]
ExposedGameObject / ExposedGameObjectWithTransform	LiveGameObject / LiveGameObjectWithTransform
OnExposedChanged / OnExposedReset	OnLiveChanged / OnLiveReset

• Remote Control Container などに登録済みの項目は、新しい型名で自動的に読み込まれます。

関連リンク

• SDKの構成内容 — RemoteControl パッケージを含む SDK の構成
• Remote Control リリースノート — 0.26.0 の変更の詳細