DebugCommandについて

設定したデバッグコマンドを表示します。

デバッグコマンドはNOA Debuggerを組み込んだアプリケーション内で設定と登録を行うことで、
メソッドの実行やプロパティの表示などができます。
デバッグコマンドの設定方法は後述のデバッグコマンドの設定を参照してください。

画面のUI構成と操作方法

debug-command

1.カテゴリ名

選択しているカテゴリ名を表示します。

2.カテゴリ変更ボタン

[≡]ボタン押下でカテゴリ選択ダイアログを表示します。

3.グループ名

デバッグコマンドのグループ名を表示します。

4.グループ選択

専用ウィンドウ内に表示するグループを選択します。
チェックが入ったグループのコマンドを専用ウィンドウに表示します。

5.コマンド要素

設定したデバッグコマンドを表示します。
設定内容ごとに表示するコマンドのUI構成が変わります。
各コマンド要素の説明については、後述のコマンドUI構成を参照してください。

コマンドUI構成

IntProperty、FloatProperty

intまたはfloatのプロパティを指定した際に表示するコマンド要素です。
テキスト入力による値の変更、またはドラッグによる値の増減を行うことができます。

int-property

StringProperty

stringのプロパティを指定した際に表示するコマンド要素です。
テキスト入力による値の変更を行うことができます。

string-property

BoolProperty

boolのプロパティを指定した際に表示するコマンド要素です。
トグルによる値の変更を行うことができます。

bool-property

EnumProperty

enumのプロパティを指定した際に表示するコマンド要素です。
ドロップダウンによる値の変更を行うことができます。

enum-property

Method

メソッドを指定した際に表示するコマンド要素です。
ボタン押下で指定したメソッドを実行します。
非同期の場合は、処理が完了するまでボタンは押下できません。

method

GetOnlyProperty

プロパティにpublicなgetterが存在する場合に表示するコマンド要素です。
GetOnlyPropertyは同グループ内の最下部に表示します。

get-only-property

デバッグコマンドの設定

NOA Debuggerを組み込んだアプリケーション内でDebugCategoryBaseを継承したクラスを作成します。
NOA Debuggerが提供する機能を利用する場合は、必ずNOA_DEBUGGERのシンボル定義を利用してください。
作成したクラス内の以下条件に当てはまるプロパティ、メソッドをDebugCommandの画面に表示します。

表示するプロパティの条件

  • publicなgetterが存在する
  • int,float,string,bool,enumいずれかの型を持っている

表示するメソッドの条件

  • publicである
  • IEnumerator,NoaDebugger.MethodHandler,voidいずれかの返り値を持っている
  • パラメータが設定されていない

補足：NoaDebugger.MethodHandlerの説明はMethodHandlerについてを参照してください。

カテゴリクラスのサンプルコード

#if NOA_DEBUGGER
using NoaDebugger;

public class DebugCommandSample : DebugCategoryBase
{
    public void ExampleMethod()
    {
        // 何らかの処理
    }

    [CommandGroup("Group1"), DisplayName("Property1"), SaveOnUpdate]
    public int ExampleProperty1
    {
        get;
        set;
    }

    // GetOnlyPropertyとして扱われる例
    [CommandGroup("Group1"), DisplayName("Property2"), SaveOnUpdate]
    public int ExampleProperty2
    {
        get;
        private set;
    }
}
#endif

カテゴリクラスの登録

作成したクラスをDebugCommandの画面に表示するためには、
NOA Debuggerを組み込んだアプリケーション内で NoaDebugger.DebugCommandRegister.AddCategory() を呼び出し、作成したクラスを登録します。

AddCategory() の引数にカテゴリ名を指定できます。
指定された文字列をNOA Debugger上で表示します。指定がなかった場合はクラス名を表示します。

AddCategory() の引数に並び順を指定できます。
指定した値が小さいものから順にカテゴリの一覧に表示します。
値を指定しなかった場合は、読み込み順かつ並び順を指定したカテゴリよりも後ろに並びます。

同じ名前で複数のカテゴリを登録した場合、自動的に -1 ・ -2 という接尾辞を追加します。

#if NOA_DEBUGGER
using NoaDebugger;
#endif

public class Example
{
    void Initialize()
    {
#if NOA_DEBUGGER
        DebugCommandRegister.AddCategory<DebugCommandSample>("CategoryName", 1);
#endif
    }
}

表示するカテゴリクラスの条件

DebugCommandの画面に登録できるクラスには以下の条件があります。

  • 引数なしでインスタンスを生成できる

登録済みカテゴリのインスタンスの参照

NoaDebugger.DebugCommandRegister.AddCategory() で登録したカテゴリのインスタンスを参照するためには、
NOA Debuggerを組み込んだアプリケーション内で NoaDebugger.DebugCommandRegister.GetCategoryInstance() を呼び出します。

#if NOA_DEBUGGER
using NoaDebugger;
using UnityEngine;
#endif

public class Example
{
    void AccessToDebugCategoryInstance()
    {
#if NOA_DEBUGGER
        // 引数に登録時に指定したカテゴリ名を指定します。
        var instance = DebugCommandRegister.GetCategoryInstance<DebugCommandSample>("CategoryName");
        instance.ExampleMethod();
        Debug.Log($"Value: {instance.ExampleProperty}");

        // 同じ名前で登録すると自動的に '-1' ・ '-2' という接尾辞を追加するため、取得するカテゴリ名の指定にも反映する必要があります。
        var anotherInstance = DebugCommandRegister.GetCategoryInstance<DebugCommandSample>("CategoryName-1");
 #endif
    }
}

プロパティの更新処理について

メソッドからプロパティの値を変更した際、DebugCommand機能を再度表示しないと描画の更新ができません。
すぐに描画の更新を行いたい場合は NoaDebugger.DebugCommandRegister.RefreshProperty() をメソッド内で実行してください。

#if NOA_DEBUGGER
using NoaDebugger;

public class DebugCommandSample : DebugCategoryBase
{
    int _exampleProperty;
    [CommandGroup("Group1"), DisplayName("Property1")]
    public int ExampleProperty
    {
        get => _exampleProperty;
    }

    public void ExampleMethod()
    {
        _exampleProperty = 2;

        // プロパティの描画更新
        DebugCommandRegister.RefreshProperty();
    }
}
#endif

プロパティの値の保存

表示対象となるプロパティに SaveOnUpdateAttribute 属性を追加することで、変更した値を保存することができます。

保存したプロパティの値の削除

以下のAPIを呼び出すことで保存したプロパティの値を削除することができます。

  • NoaDebugger.DebugCommandRegister.DeleteSavedProperty(categoryName, propertyName)
  • NoaDebugger.DebugCommandRegister.DeleteAllPropertiesInCategory(categoryName)
  • NoaDebugger.DebugCommandRegister.DeleteAllSavedProperties()

categoryName には NoaDebugger.DebugCommandRegister.AddCategory() を実行した時に指定したカテゴリ名を、
propertyName には対象のプロパティ名を指定します。

#if NOA_DEBUGGER
// 指定カテゴリ・プロパティ名の保存した値を削除します。
DebugCommandRegister.DeleteSavedProperty("CategoryName", nameof(Property));

// 指定カテゴリのすべてのプロパティの保存した値を削除します。
DebugCommandRegister.DeleteAllPropertiesInCategory("CategoryName");

// すべてのプロパティの保存した値を削除します。
DebugCommandRegister.DeleteAllSavedProperties();
#endif

デバッグコマンドに指定できる属性

デバッグコマンドに指定できる属性は以下のとおりです。

属性説明
CommandGroupAttribute対象コマンドのグループを指定します。指定がない場合「Others」に内包されます。
DisplayNameAttribute 対象コマンドの表示名を指定します。指定がない場合プロパティ名またはメソッド名を表示します。
CommandOrderAttribute対象コマンドの並び順を指定します。指定された値の小さいものから順に表示します。
CommandInputRangeAttributeint,floatプロパティの入力できる範囲を指定します。
CommandIncrementAttributeint,floatプロパティのドラッグ操作で増減する値の量を指定します。指定が無い場合は1ずつ増減します。
CommandCharacterLimitAttributestringプロパティの入力文字数の上限を指定します。
SaveOnUpdateAttribute対象のプロパティを指定のキーに保存します。指定がない場合は値の保存を行いません。
CommandExcludeAttribute表示する条件を満たすプロパティ・メソッドを表示対象から除外します。

動的なデバッグコマンドの追加

NoaDebugger.DebugCommandRegister クラスで定義している以下のAPIを使用することで、
動的に DebugCategoryBase を継承しないクラスのプロパティ・メソッドをデバッグコマンドとして追加することができます。

コマンド定義の生成:

// getterのみを持つプロパティコマンドの定義を生成します。
CommandDefinition CreateGetOnlyIntProperty(string categoryName, string displayName, Func<int> getter, Attribute[] attributes = null);
CommandDefinition CreateGetOnlyFloatProperty(string categoryName, string displayName, Func<float> getter, Attribute[] attributes = null);
CommandDefinition CreateGetOnlyStringProperty(string categoryName, string displayName, Func<string> getter, Attribute[] attributes = null);
CommandDefinition CreateGetOnlyBoolProperty(string categoryName, string displayName, Func<bool> getter, Attribute[] attributes = null);
CommandDefinition CreateGetOnlyEnumProperty(string categoryName, string displayName, Func<Enum> getter, Attribute[] attributes = null);

// getterとsetterを持つプロパティコマンドの定義を生成します。
CommandDefinition CreateMutableIntProperty(string categoryName, string displayName, Func<int> getter, Action<int> setter, Attribute[] attributes = null);
CommandDefinition CreateMutableFloatProperty(string categoryName, string displayName, Func<float> getter, Action<float> setter, Attribute[] attributes = null);
CommandDefinition CreateMutableStringProperty(string categoryName, string displayName, Func<string> getter, Action<string> setter, Attribute[] attributes = null);
CommandDefinition CreateMutableBoolProperty(string categoryName, string displayName, Func<bool> getter, Action<bool> setter, Attribute[] attributes = null);
CommandDefinition CreateMutableEnumProperty<T>(string categoryName, string displayName, Func<T> getter, Action<T> setter, Attribute[] attributes = null) where T : Enum;

// メソッドコマンドの定義を生成します。
CommandDefinition CreateMethod(string categoryName, string displayName, Action method, Attribute[] attributes = null);

// コルーチンコマンドの定義を生成します。
CommandDefinition CreateCoroutine(string categoryName, string displayName, Func<IEnumerator> coroutine, Attribute[] attributes = null);

// ハンドルメソッドコマンドの定義を生成します。
CommandDefinition CreateHandleMethod(string categoryName, string displayName, Func<MethodHandler> method, Attribute[] attributes = null);

各APIの attributes には、以下の属性を除くデバッグコマンドに指定できる属性を指定できます。

  • DisplayNameAttribute
  • SaveOnUpdateAttribute
  • CommandExcludeAttribute

生成したコマンド定義を用いたコマンドの追加・削除:

// 生成したコマンド定義によるコマンドを追加します。
void AddCommand(CommandDefinition commandDefinition);

// 追加したコマンドを削除します。
// コマンドに関係するオブジェクトが破棄されるタイミングで、このAPIを用いて追加したコマンドを削除してください。
void RemoveCommand(CommandDefinition commandDefinition);

デバッグコマンドを動的に追加・削除するサンプルコードは以下のとおりです。

getterのみを持つプロパティ:

#if NOA_DEBUGGER
using System;
using NoaDebugger;
using UnityEngine;

public class DynamicDebugCommand : MonoBehaviour
{
    readonly int constantValue = 0;
    CommandDefinition commandDefinition = null;

    // コマンドを生成して登録します。
    void Start()
    {
        var attributes = new Attribute[]
        {
            new CommandGroupAttribute("Dynamic Command Group"),
            new CommandOrderAttribute(0)
        };
        commandDefinition = DebugCommandRegister.CreateGetOnlyIntProperty(
            "Dynamic Command Category",
            "Get-Only Property",
            () => constantValue,
            attributes);
        DebugCommandRegister.AddCommand(commandDefinition);
    }

    // 生成したコマンドを削除します。
    void OnDestroy() => DebugCommandRegister.RemoveCommand(commandDefinition);
}
#endif

getterとsetterを持つプロパティ:

#if NOA_DEBUGGER
using System;
using NoaDebugger;
using UnityEngine;

public class DynamicDebugCommand : MonoBehaviour
{
    int mutableValue = 0;
    CommandDefinition commandDefinition = null;

    // コマンドを生成して登録します。
    void Start()
    {
        var attributes = new Attribute[]
        {
            new CommandGroupAttribute("Dynamic Command Group"),
            new CommandOrderAttribute(0)
        };
        commandDefinition = DebugCommandRegister.CreateMutableIntProperty(
            "Dynamic Command Category",
            "Mutable Property",
            () => mutableValue,
            value => mutableValue = value,
            attributes);
        DebugCommandRegister.AddCommand(commandDefinition);
    }

    // 生成したコマンドを削除します。
    void OnDestroy() => DebugCommandRegister.RemoveCommand(commandDefinition);
}
#endif

メソッド:

#if NOA_DEBUGGER
using System;
using NoaDebugger;
using UnityEngine;

public class DynamicDebugCommand : MonoBehaviour
{
    CommandDefinition commandDefinition = null;

    // コマンドを生成して登録します。
    void Start()
    {
        var attributes = new Attribute[]
        {
            new CommandGroupAttribute("Dynamic Command Group"),
            new CommandOrderAttribute(0)
        };
        commandDefinition = DebugCommandRegister.CreateMethod(
            "Dynamic Command Category",
            "Method",
            () => Debug.Log("Executing Dynamic Command."),
            attributes);
        DebugCommandRegister.AddCommand(commandDefinition);
    }

    // 生成したコマンドを削除します。
    void OnDestroy() => DebugCommandRegister.RemoveCommand(commandDefinition);
}
#endif

コルーチン:

#if NOA_DEBUGGER
using System;
using System.Collections;
using NoaDebugger;
using UnityEngine;

public class DynamicDebugCommand : MonoBehaviour
{
    CommandDefinition commandDefinition = null;

    // コマンドを生成して登録します。
    void Start()
    {
        var attributes = new Attribute[]
        {
            new CommandGroupAttribute("Dynamic Command Group"),
            new CommandOrderAttribute(0)
        };
        commandDefinition = DebugCommandRegister.CreateCoroutine(
            "Dynamic Command Category",
            "Coroutine",
            DebugCommandCoroutine,
            attributes);
        DebugCommandRegister.AddCommand(commandDefinition);
    }

    // 生成したコマンドを削除します。
    void OnDestroy() => DebugCommandRegister.RemoveCommand(commandDefinition);

    // デバッグコマンドで呼び出されるコルーチンです。
    IEnumerator DebugCommandCoroutine()
    {
        yield return new WaitForSeconds(1);
    }
}
#endif

ハンドルメソッド:

#if NOA_DEBUGGER
using System;
using NoaDebugger;
using UnityEngine;

public class DynamicDebugCommand : MonoBehaviour
{
    MethodHandler handler = new();
    CommandDefinition commandDefinition = null;

    // コマンドを生成して登録します。
    void Start()
    {
        var attributes = new Attribute[]
        {
            new CommandGroupAttribute("Dynamic Command Group"),
            new CommandOrderAttribute(0)
        };
        commandDefinition = DebugCommandRegister.CreateHandleMethod(
            "Dynamic Command Category",
            "Handle Method",
            DebugCommandHandleMethod,
            attributes);
        DebugCommandRegister.AddCommand(commandDefinition);
    }

    // 生成したコマンドを削除します。
    void OnDestroy() => DebugCommandRegister.RemoveCommand(commandDefinition);

    // デバッグコマンドで呼び出されるハンドルメソッドです。
    MethodHandler DebugCommandHandleMethod()
    {
        handler.IsDone = false;
        return handler;
    }

    // ハンドルメソッドを完了します。
    void CompleteHandleMethod() => handler.IsDone = true;
}
#endif

Unity Test Runnerでの利用について

PlayMode時のみ、登録したカテゴリクラスのインスタンスを取得し、テストに利用できます。

#if NOA_DEBUGGER
using System.Collections;
using UnityEngine.TestTools;
using NoaDebugger;

public class Example
{
    [UnityTest]
    public IEnumerator Test()
    {
        NoaDebug.Initialize();
        DebugCommandRegister.AddCategory<DebugCommandSample>();

        var instance = DebugCommandRegister.GetCategoryInstance<DebugCommandSample>();
        instance.ExampleMethod();

        yield return null;
    }
}
#endif