English Documents Available(英語ドキュメント)
直感的で整理されたデバッグメニューを簡単に作成できる、Unityのための階層型デバッグメニューシステムです。
一般的に、ゲーム開発中には多くのデバッグコマンドが作られ、またその数は開発が進むにつれて増えていきます。
そのため次第に目的のコマンドが見つけづらくなり、結果として開発効率の低下を招きます。
Unity Debug Sheet を使うと、階層構造を持つデバッグメニューを簡単に作ることができます。
誰でも迷わず直感的に扱えるGUIを目指しており、特にモバイルプラットフォームでも操作性が悪化しないことを意識しています。
もちろん縦方向のレイアウトにも対応しています。
デバッグコマンドの追加も以下のように簡単です。
// Label
AddLabel("Example Label");
// Button
AddButton("Example Button", clicked: () => { Debug.Log("Clicked"); });
// Switch
AddSwitch(false, "Example Switch", valueChanged: x => Debug.Log($"Changed: {x}"));
// Slider
AddSlider(0.5f, 0.0f, 1.0f, "Example Slider", valueChanged: x => Debug.Log($"Value Changed: {x}"));デモシーンはこのリポジトリ自体をクローンし、当該シーンを再生することで利用できます。
以下のデモシーンを用意しています。
キャラクタービューワー: CharacterViewerDemo.unity
キャラクターモデルやモーションなどをデバッグメニューから切り替えるデモです。
また、Graphy や In-Game Debug Console といった他ライブラリとインテグレーションを行い、パフォーマンスをモニタリングできるサンプルを実装しています。
デフォルトセル: DefaultCellsDemo.unity
本ライブラリにデフォルトで組み込まれているセル（ボタンやラベル、スライダーといった各項目の総称）の挙動を一通り確認することができます。
カスタムセル: CustomCellsDemo.unity
デフォルトセルの他、ユーザは自由にカスタムしたセルを使うこともできます。
これはカスタムセルの使い方を示したデモです。
エントリーシーン: DemoEntry.unity
上記三つのシーンは以下のシーンから遷移することも可能です。
各シーンに置かれているデバッグメニューがシングルトンとして振る舞う様子を確認できます。
本ツールは以下の環境に対応しています。
- Unity 2020.3 以上
インストールは以下の手順で行います。
- Window > Package Manager を選択
- 「+」ボタン > Add package from git URL を選択
- 以下を入力してインストール
あるいは Packages/manifest.json を開き、dependencies ブロックに以下を追記します。
{
"dependencies": {
"com.harumak.unitydebugsheet": "https://github.com/Haruma-K/UnityDebugSheet.git?path=/Assets/UnityDebugSheet"
}
}バージョンを指定したい場合には以下のように記述します（末尾のバージョンは適宜書き換えてください）。
バージョンを更新するには上述の手順でバージョンを書き換えてください。
バージョンを指定しない場合には、Packages/package-lock.json ファイルを開いて本ライブラリの箇所のハッシュを書き換えることで更新できます。
{
"dependencies": {
"com.harumak.unitydebugsheet": {
"version": "https://github.com/Haruma-K/UnityDebugSheet.git?path=/Assets/UnityDebugSheet",
"depth": 0,
"source": "git",
"dependencies": {},
"hash": "..."
}
}
}ここでは Unity Debug Sheet を簡単にセットアップして使う方法をまとめます。
まず DebugSheetCanvas という名前の Prefab を Hierarchy にドラッグ&ドロップして配置します。
また、EventSystem が存在していなかったら作成しておきます。
次にデバッグ用のページを作成します。
ページは以下のように DefaultDebugPageBase を継承することで作成します。
以下では、押下したときに Clicked とログ出力されるボタンを一つだけ持つページを作成しています。
using System.Collections;
using UnityDebugSheet.Runtime.Core.Scripts;
using UnityEngine;
public sealed class ExampleDebugPage : DefaultDebugPageBase
{
protected override string Title { get; } = "Example Debug Page";
public override IEnumerator Initialize()
{
// Add a button to this page.
AddButton("Example Button", clicked: () => { Debug.Log("Clicked"); });
yield break;
}
}次に、前節で作ったデバッグページに遷移するためのリンクを追加します。
以下のように、ルートページを取得して、 ExampleDebugPage へのリンクボタンを追加します。
using UnityDebugSheet.Runtime.Core.Scripts;
using UnityEngine;
public sealed class DebugSheetController : MonoBehaviour
{
private void Start()
{
// Get or create the root page.
var rootPage = DebugSheet.Instance.GetOrCreateInitialPage();
// Add a link transition to the ExampleDebugPage.
rootPage.AddPageLinkButton<ExampleDebugPage>(nameof(ExampleDebugPage));
}
}NOTE 上記のようにページへのリンクをするのではなく、ルートページに自身で作成したページを使いたい場合には、
GetOrCreateInitialPage().AddPageLinkButton<ExampleDebugPage()の代わりにInitialize<ExampleDebugPage>()を使用します。
デバッグメニューは画面の端の方を上下にフリックすることで開いたり閉じたりすることができます。
実機では、画面端からセーフエリア内およそ6mmまでがこの範囲となります。
デモシーンでは、このエリアに赤い帯を表示してフリック可能な範囲を可視化しています。
また、この挙動は Debug Sheet の Flick To Open から変更することができます。
画面の左右どちらかだけを有効にしたり、フリックによる操作を無効にしたりできます。
Warning Unityエディタでは、実機の解像度が擬似的にシミュレーションされるため、必ずしもこの範囲が6mmにはなりません。後述のキーボードショットカットによる操作も併用することをお勧めします。
また、ボタンを使って開閉することもできます。
これを行うには、Debug Sheet の Click To Open からクリックするエリアの設定を行います。
その下の Click Count To Open には、何回連続でクリックをしたら開くかを設定できます。
キーボードを使って開閉することもできます。
デフォルトでは、Control (Mac の場合はCommand) + Shift + D でデバッグメニューをトグルします。
ショートカットは Debug Sheet の Keyboard Shortcut から自由に変更することができます。
また、以下のようにすればスクリプトで開閉することもできます。
// These scripts are attached on the GameObject "DebugSheetCanvas > Drawer".
StatefulDrawer drawer;
StatefulDrawerController drawerController;
// Toggle debug sheet.
var isClosed = Mathf.Approximately(drawer.Progress, drawer.MinProgress);
var targetState = isClosed ? DrawerState.Max : DrawerState.Min;
drawerController.SetStateWithAnimation(targetState);ここまでの実装で、再生をすると以下のようなデバッグメニューが動作することを確認できます。
次に Unity Debug Sheet を使う上での基礎知識を解説します。
クイックスタートの内容が前提知識となりますので、そちらを先にお読みください。
デフォルトで使用できるセル一覧は以下の通りです。
| セル名 | 追加するためのメソッド名 | 用途 |
|---|---|---|
| Label | AddLabel | 文字列を表示するために使用します。 |
| Button | AddButton | 押下した時にアクションを起こすために使用します。 |
| InputField | AddInputField | 文字を入力するために使用します。 |
| Switch | AddSwitch | ON・OFFを切り替えるために使用します。 |
| Slider | AddSlider | 指定した範囲で数値を指定するために使用します。 |
| Picker | AddPicker | 複数の選択肢から一つを選択するために使用します。 |
| Enum Picker | AddEnumPicker | Enumの要素から一つを選択するために使用します。 |
| Multi Picker | AddMultiPicker | 複数の選択肢から複数を選択するために使用します。 |
| Enum Multi Picker | AddEnumMultiPicker | Enumの要素から複数を選択するために使用します。 |
| Search Field | AddSearchField | 検索フィールドを表示するために使用します。 |
| Page Link Button | AddPageLinkButton | 押下した時に他のデバッグページへの遷移を行うために使用します。 |
| Button Collection | AddButtonCollection | 小さいボタンを多数表示したい場合に使用します。 |
なおデフォルトセルのデモシーンを再生すると、これらのセルの挙動を確認することができます。
また独自のセルを作成することもできます。これについての詳細はカスタムセルの項目を参照してください。
デフォルトで使用できるページの一覧は以下の通りです。
| ページクラス名 | 説明 |
|---|---|
| DebugPage | デフォルトセルの追加メソッドを持ったページです。 |
| FloatingButtonPage | 下部にフローティングボタンを持つページです。ページの入力内容を決定・送信するためのボタンが必要な時に使用します。 |
| DefaultDebugPageBase | デフォルトセルの追加メソッドを持ったデバッグページの基底クラスです。抽象クラスなので継承して使用します。 |
| DebugPageBase | デバッグページの基底抽象クラスです。抽象クラスなので継承して使用します。 |
CellModel を使うことで、一度生成したセルの内容を更新することができます。
以下は生成したボタンの名前を Space キーが押されるたびに変更する例です。
詳細はコメントに記述してあるので参照してください。
using System.Collections;
using UnityDebugSheet.Runtime.Core.Scripts;
using UnityDebugSheet.Runtime.Core.Scripts.DefaultImpl.Cells;
using UnityEngine;
public sealed class ExampleDebugPage : DefaultDebugPageBase
{
private int _buttonCellIndex;
private ButtonCellModel _buttonCellModel;
private int _counter;
protected override string Title => "Example Debug Page";
public override IEnumerator Initialize()
{
// Create the CellModel and set data and events.
var buttonCellModel = new ButtonCellModel(false);
buttonCellModel.CellTexts.Text = GetButtonName();
buttonCellModel.Clicked += () => { Debug.Log("Clicked"); };
// Keep the index of the cell and the CellModel.
_buttonCellIndex = AddButton(buttonCellModel);
_buttonCellModel = buttonCellModel;
yield break;
}
private void Update()
{
if (Input.GetKeyDown(KeyCode.Space))
{
// Update the cell data
_counter++;
_buttonCellModel.CellTexts.Text = GetButtonName();
// Refresh the target cell.
RefreshDataAt(_buttonCellIndex);
// You can also refresh all data by calling RefreshData().
//RefreshData();
}
}
private string GetButtonName()
{
return $"Example Button {_counter}";
}
}デフォルトでは、DebugSheetCanvas はシングルトンとして扱われます。
つまり二つのシーンに DebugSheetCanvas が配置されていた場合、先にインスタンス化されたものが使用され、後からロードされたものは破棄されます。
初期化は最初にインスタンスされた DebugSheet にのみ行う必要があります。
シーンの読み込み順が不定の場合、DebugSheet.GetOrCreateInitialPage() を使うことで、既に初期化されているページがあればそれを取得し、なければ初期化することができます。
複数シーンにおけるワークフローは DemoEntry シーンを参考にしてください。
なお、DebugSheet コンポーネントの Singleton のチェックを外すとシングルトンとしては扱わず、複数のデバッグシートをインスタンス化することができます。
リリースビルドでは、デバッグメニューの GameObject やスクリプトファイル、リソースファイルを除外する必要があります。
Scripting Define Symbols に EXCLUDE_UNITY_DEBUG_SHEET を 加えると Unity Debug Sheet に関連する全てのコードがコンパイル対象から除外されます。
したがって、Unity Debug Sheet にアクセスするコードをすべて#if !EXCLUDE_UNITY_DEBUG_SHEET と #endifで囲っておけば、リリース時に関連するスクリプトを全て除外できます。
Unity Debug Sheet にアクセスするコードを一つのアセンブリにまとめて、asmdef の Define Constraints を設定するのもいいかもしれません。
加えて以下の対応を行うと、ビルドから完全にデバッグメニューを除外できます。
- デバッグメニュー用のリソースを入れた Resources フォルダを作成していたらそれを削除する
- シーン上の Unity Debug Sheet の GameObject を削除する
独自のセルを作るためには、まず Cell を継承したコンポーネントとそれにデータをセットするための CellModel を継承したモデルを作成します。
using UnityDebugSheet.Runtime.Core.Scripts;
using UnityEngine;
using UnityEngine.UI;
public sealed class CustomTextCell : Cell<CustomTextCellModel>
{
[SerializeField] private Text _text;
[SerializeField] private LayoutElement _layoutElement;
private const int Padding = 36;
protected override void SetModel(CustomTextCellModel model)
{
_text.text = model.Text;
_text.color = model.Color;
_layoutElement.preferredHeight = _text.preferredHeight + Padding;
}
}
public sealed class CustomTextCellModel : CellModel
{
public string Text { get; set; }
public Color Color { get; set; } = Color.black;
}あとは GUI を作成し、このコンポーネントをアタッチして Prefab 化します。
セルのリサイクルシステムの実装の関係上、以下の点に注意してセルを実装してください。
- ルート GameObject に Layout Element をアタッチし、Preferred Height に高さを入力すること
- セルの横幅は固定値に設定すること
次にこのセルを Debug Sheet の Cell Prefabs に設定します。
あとは通常通りこのセルをページに追加するだけです。
実際の実装はカスタムセルのデモシーンを参考にしてください。
デバッグページを作る際、以下のようにコルーチンの代わりに非同期メソッドを使用してライフサイクルイベントを定義することもできます。
using UnityDebugSheet.Runtime.Core.Scripts;
using System.Threading.Tasks;
public class SomePage : DefaultDebugPageBase
{
protected override string Title => "Some Page";
// 非同期メソッドを使ってライフサイクルイベントを定義する
public override async Task Initialize()
{
await Task.Delay(100);
}
}非同期メソッドを使うには、以下の手順でScripting Define Symbolsを追加します。
- Player Settings > Other Settingsを開く
- Scripting Define Symbolsに
UDS_USE_ASYNC_METHODSを追加
Scripting Define Symbolsは全てのプラットフォームに対して設定する必要がある点に注意してください。
デフォルトではデバッグメニューの背景として、半透明の黒い GUI が表示されます。
これを非表示にするには、DebugSheetCanvas > Backdrop の GameObject を非アクティブにします。
デフォルトでは、デバッグメニューの背景をクリックするとデバッグメニューが閉じる挙動になっています。
背景を表示しつつも、クリックしても閉じないようにするには、DebugSheetCanvas > Drawer にアタッチされている Stateful Drawer Backdrop Controller の Close When Backdrop Clicked のチェックを外します。
Drawerが表示または非表示になる時のアニメーションを変更するには DebugSheetCanvas > Drawer にアタッチされている Stateful Drawer Controller の Animation Duration や Animation Type を変更します。
デフォルトでは、デバッグメニューは画面の外側から出現し、非表示状態になると画面の外側に格納されます。
Debug Sheet Canvas > Drawer にアタッチされている Debug Sheet Drawer の Move Inside Safe Area にチェックを入れると、セーフエリアの外側から出現し、セーフエリアの外側に格納される挙動に変更することができます。
デバッグメニューが最小化されているときや最大化されているときのサイズを調整することもできます。
これを調整すると、例えば、以下のように、最小化されている状態でも常に画面下に表示しておくことができます。
各状態のサイズを変更するには、Debug Sheet Canvas > Drawer にアタッチされている Debug Sheet Drawer のプロパティを編集します。
最小化されている時の大きさを変えるには Min の Progress を、最大化されている時の大きさを変えるには Size を調整します。
Middle は縦持ちにした時に適用される、中間のサイズです。
Debug の Set State ボタンを押下すると、各状態におけるサイズを適用してデバッグ用に確認することができます。
Unity Debug Sheet は uGUI で構成されているので、プロパティを調整することであらゆる箇所の色を自由に変更することができます。
- 戻るボタンや閉じるボタンの色
- シートの背景色
- タイトルの文字色
各セルのデザインはカスタムセルを作成することで自由に作成できます。
これについての詳細はカスタムセルの項目を参照してください。
複数のページをまとめて戻るには、DebugSheet.PopPage()の第二引数に戻る画面数を指定します。
DebugSheet debugSheet;
debugSheet.PopPage(true, 2);また、戻り先の PageID を指定してまとめて戻ることもできます。
PageID は、以下のように PushPage() の onLoad コールバックを使うことで取得できます。
DebugSheet debugSheet;
debugSheet.PushPage<DebugPage>(true, onLoad: x =>
{
var pageId = x.pageId;
});また、PushPage() の pageId 引数を指定することで、任意の ID を指定することもできます。
DebugSheet debugSheet;
debugSheet.PushPage<DebugPage>(true, pageId: "MyPageId");なお、まとめて戻る際にスキップされるページについては、遷移前後のライフサイクルイベントは呼ばれず、破棄前のイベントだけ呼ばれます。
またスキップされるページの遷移アニメーションは再生されません。
LabelCell や ButtonCell などの組み込みセルのPrefabは以下の手順で拡張することができます。
- 組み込みPrefabのPrefabバリアントを作成し、任意の変更を加える
- このとき、Prefabの名前は元のPrefabと同じにする
- このPrefabを Debug Sheet コンポーネントの Cell Prefabs に設定する
Unity Debug Sheet はどんなアプリケーションでも汎用的に使う機能を拡張パッケージとして提供しています。
Unityのシステム情報を表示する拡張パッケージです。
表示できる情報は以下の通りです。
| DebugPageのクラス名 | 説明 |
|---|---|
| SystemInfoDebugPage | SystemInfoクラスの情報を表示します。 |
| ApplicationDebugPage | Applicationクラスの情報を表示します。 |
| TimeDebugPage | Timeクラスの情報を表示します。 |
| QualitySettingsDebugPage | QualitySettingsクラスの情報を表示します。 |
| ScreenDebugPage | Screenクラスの情報を表示します。 |
| InputDebugPage | Inputクラスの情報を表示します。 |
| GraphicsDebugPage | Graphicsクラスの情報を表示します。 |
| PhysicsDebugPage | Physicsクラスの情報を表示します。 |
| Physics2DDebugPage | Physics2Dクラスの情報を表示します。 |
使用方法は以下の通りです。
- （独自のアセンブリで使用する場合）UnityDebugSheet.Unity を参照アセンブリに加える
DefaultDebugPageBase.AddPageLinkButton<SystemInfoDebugPage>("System Info")のようにしてページへのリンクセルを追加する
ランタイムでコンソールを表示するためのOSS In-game Debug Console と Unity Debug Sheet を連携する拡張パッケージです。
これを導入するとコンソールを表示するデバッグメニューを簡単に追加することができます。
使用方法は以下の通りです。
- In-game Debug Console をインストール&セットアップする（複数のインストール方法があります）
- （Package Managerを経由しない方法で1.をインストールした場合のみ）Scripting Define Symbols に
UDS_INGAMEDEBUGCOSOLE_SUPPORTを追加して Unity を再起動する - （独自のアセンブリで使用する場合）UnityDebugSheet.IngameDebugConsole を参照アセンブリに加える
DefaultDebugPageBase.AddPageLinkButton<IngameDebugConsoleDebugPage>("In-Game Debug Console", onLoad: x => x.page.Setup(DebugLogManager.Instance));のようにしてページへのリンクセルを追加する
FPSやメモリなどの情報を表示するOSS Graphy と Unity Debug Sheet を連携する拡張パッケージです。
使用方法は以下の通りです。
- Graphy をインストール&セットアップする（複数のインストール方法があります）
- （Package Managerを経由しない方法で1.をインストールした場合のみ）Scripting Define Symbols に
UDS_GRAPHY_SUPPORTを追加して Unity を再起動する - （独自のアセンブリで使用する場合）UnityDebugSheet.Graphy を参照アセンブリに加える
DefaultDebugPageBase.AddPageLinkButton<GraphyDebugPage>("Graphy", onLoad: x => x.page.Setup(GraphyManager.Instance));のようにしてページへのリンクセルを追加する
本ソフトウェアはMITライセンスで公開しています。ライセンスの範囲内で自由に使っていただけますが、使用の際は以下の著作権表示とライセンス表示が必須となります。
また、本ドキュメントの目次は以下のソフトウェアを使用して作成されています。
デモシーンでは以下のソフトウェアを使用しています。
これらのライセンスの詳細は Third Party Notices.md を参照してください。