UnityDebugSheet

<h1 align="center">Unity调试表单</h1>

用于Unity的分层调试菜单系统,可轻松创建直观有序的调试菜单。

概述

概念与特性

通常在游戏开发过程中会创建许多调试命令,随着开发的推进,这些命令的数量也会不断增加。结果就是很难找到所需的命令,从而降低了开发效率。

Unity调试表单允许您轻松创建具有层次结构的调试菜单。它的GUI可以被任何人,特别是在移动平台上,轻松直观地控制。

当然,它也支持垂直布局。

添加调试命令也很容易。

// 标签
AddLabel("示例标签");

//　按钮
AddButton("示例按钮", clicked: () => { Debug.Log("已点击"); });

// 开关
AddSwitch(false, "示例开关", valueChanged: x => Debug.Log($"已更改: {x}"));

// 滑动条
AddSlider(0.5f, 0.0f, 1.0f, "示例滑动条", valueChanged: x => Debug.Log($"值已更改: {x}"));

演示

您可以通过克隆`此存储库本身并播放演示场景来尝试演示。以下演示场景可用。

角色查看器: CharacterViewerDemo.unity

此演示允许您从调试菜单切换角色模型、动作等。它还包括与其他库(如Graphy和In-Game调试控制台)集成的示例,用于监控性能。

默认单元格: DefaultCellsDemo.unity

此演示允许您检查此库默认包含的所有单元格(按钮、标签、滑块等项目的通用名称)的行为。

自定义单元格: CustomCellsDemo.unity

除了默认单元格,您还可以创建自己的自定义单元格。此演示展示了如何创建自定义单元格。

入口场景: DemoEntry.unity 上述三个场景也可以从这个场景进行切换。您可以看到放置在每个场景中的调试表单的单例行为。

设置

要求

此工具兼容以下环境。

Unity 2020.3 或更高版本

安装

您可以通过以下步骤安装此库。

从菜单栏选择 Window > Package Manager。
单击左上角的 + 按钮,选择 Add package from git URL...。
在输入框中输入以下URL,然后单击 Add。

https://github.com/Haruma-K/UnityDebugSheet.git?path=/Assets/UnityDebugSheet

或者,您也可以通过在 Packages 文件夹的 manifest.json 文件的 dependencies 块中添加以下行来安装。

{
  "dependencies": {
    "com.harumak.unitydebugsheet": "https://github.com/Haruma-K/UnityDebugSheet.git?path=/Assets/UnityDebugSheet"
  }
}

如果您想指定版本,您可以通过在URL末尾添加版本号来实现。

https://github.com/Haruma-K/UnityDebugSheet.git?path=/Assets/UnityDebugSheet#1.0.0

您可以通过更改上述版本号来更新版本。如果您没有指定版本,可以通过打开文件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调试表的简单方法。

将预制件放置在场景中

首先,将名为DebugSheetCanvas的预制件拖放到层次结构窗口中,将其放置在场景中。如果EventSystem不存在,请创建它。

创建调试页面

接下来,创建一个用于调试的页面。如下所示,通过继承DefaultDebugPageBase来创建页面。以下是一个具有单个按钮的示例页面,当单击该按钮时会记录Clicked。

using System.Collections;
using UnityDebugSheet.Runtime.Core.Scripts;
using UnityEngine;

public sealed class ExampleDebugPage : DefaultDebugPageBase
{
    protected override string Title { get; } = "示例调试页面";

    public override IEnumerator Initialize()
    {
        // 向此页面添加一个按钮。
        AddButton("示例按钮", clicked: () => { Debug.Log("已单击"); });

        yield break;
    }
}

添加到调试页面的链接

接下来,添加一个链接来转换到上面创建的调试页面。获取根页面,并如下所示添加一个链接按钮。

using UnityDebugSheet.Runtime.Core.Scripts;
using UnityEngine;

public sealed class DebugSheetController : MonoBehaviour
{
    private void Start()
    {
        // 获取或创建根页面。
        var rootPage = DebugSheet.Instance.GetOrCreateInitialPage();

        // 添加到ExampleDebugPage的链接过渡。
        rootPage.AddPageLinkButton<ExampleDebugPage>(nameof(ExampleDebugPage));
    }
}

注意如果您想使用自己的页面作为根页面,而不是像上面那样链接,请使用Initialize<ExampleDebugPage>()而不是GetOrCreateInitialPage().AddPageLinkButton<ExampleDebugPage()。

打开和关闭调试菜单

可以通过沿屏幕边缘向上和向下滑动来打开和关闭调试菜单。在实际设备上,该区域从屏幕边缘延伸到安全区域内约6mm处。在演示场景中,红色条带显示在此区域内,以可视化可滑动范围。

此行为可以从Debug Sheet组件上的Flick To Open进行更改。您可以只启用左侧或右侧屏幕,或禁用滑动操作。

警告在Unity编辑器中,此范围不一定是6mm,因为它模拟实际设备的分辨率。建议您也使用下面描述的键盘快捷键操作。

您也可以通过按按钮来打开和关闭调试菜单。要做到这一点,请在Debug Sheet组件上设置Click To Open。您可以在Click Count To Open中设置需要连续单击的次数才能打开它。

您可以使用键盘快捷键来打开和关闭调试菜单。默认情况下,Control(Mac上为Command) + Shift + D可切换调试菜单。您可以在Debug Sheet组件的Keyboard Shortcut中自由更改快捷键。

您也可以从脚本中打开/关闭调试菜单,如下所示。

// 这些脚本附加在GameObject "DebugSheetCanvas > Drawer"上。
StatefulDrawer drawer;
StatefulDrawerController drawerController;

// 切换调试表。
var isClosed = Mathf.Approximately(drawer.Progress, drawer.MinProgress);
var targetState = isClosed ? DrawerState.Max : DrawerState.Min;
drawerController.SetStateWithAnimation(targetState);

结果

根据到目前为止的实现,您可以确认调试菜单如下所示工作。

基本用法

本节描述了Unity调试表的基本用法。请先阅读快速开始部分,因为那是先决条件。

可用单元格列表

默认情况下,您可以使用以下单元格。

单元格名称	添加方法名称	描述
标签	AddLabel	用于显示字符串。
按钮	AddButton	用于在单击时触发操作。
输入字段	AddInputField	用于输入文本。
开关	AddSwitch	用于开启和关闭。
滑块	AddSlider	用于在范围内指定数值。
选择器	AddPicker	用于从多个选项中选择一个。
枚举选择器	AddEnumPicker	用于从枚举元素中选择一个。
多选选择器	AddMultiPicker	用于从多个选项中选择多个。
枚举多选选择器	AddEnumMultiPicker	用于从枚举元素中选择多个。
搜索字段	AddSearchField	用于显示搜索字段。
页面链接按钮	AddPageLinkButton	用于在单击时转换到其他调试页面。
按钮集合	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 => "示例调试页面";

    public override IEnumerator Initialize()
    {
        // 创建 CellModel 并设置数据和事件。
        var buttonCellModel = new ButtonCellModel(false);
        buttonCellModel.CellTexts.Text = GetButtonName();
        buttonCellModel.Clicked += () => { Debug.Log("已点击"); };
        
        // 保存单元格索引和 CellModel。
        _buttonCellIndex = AddButton(buttonCellModel);
        _buttonCellModel = buttonCellModel;
        
        yield break;
    }

    private void Update()
    {
        if (Input.GetKeyDown(KeyCode.Space))
        {
            // 更新单元格数据
            _counter++;
            _buttonCellModel.CellTexts.Text = GetButtonName();
            
            // 刷新目标单元格。
            RefreshDataAt(_buttonCellIndex);
            
            // 你也可以调用 RefreshData() 来刷新所有数据。
            //RefreshData();
        }
    }

    private string GetButtonName()
    {
        return $"示例按钮 {_counter}";
    }
}

多场景工作流程

默认情况下,DebugSheetCanvas 被用作单例。也就是说,如果在两个场景中都放置了 DebugSheetCanvas,先实例化的那个将被使用,后实例化的将被销毁。

在这种情况下,初始化应该只在第一个 DebugSheet 上进行。如果场景加载顺序不确定,你可以使用 DebugSheet.GetOrCreateInitializePage() 来获取已初始化的页面(如果有的话),并对其进行初始化。请参考 DemoEntry 场景了解多场景工作流程。

请注意,如果你不想使用单例,你可以通过取消勾选 DebugSheet 组件中的 Singleton 来实现。

从发布版本中排除

你应该将与调试菜单相关的 GameObject、脚本文件和资源文件从发布版本中排除。

你可以通过在 Player Settings 的 Scripting Define Symbols 中添加 EXCLUDE_UNITY_DEBUG_SHEET 来排除所有 Unity Debug Sheet 脚本。这样,如果你使用 #if EXCLUDE_UNITY_DEBUG_SHEET 包含访问 Unity Debug Sheet 的自有代码,就可以将所有代码从发布版本中排除。将访问 Unity Debug Sheet 的自有脚本合并到单个程序集并在 asmdef 中设置 Define Constraints 也是一个好主意。

此外,你可以通过以下方式完全从构建中排除调试菜单:

删除包含调试菜单资源的 Resources 文件夹(如果你创建了)。
删除场景中包含 DebugSheet 组件的 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,将这个组件附加到上面,并将其制作成一个预制体。由于单元格回收系统的实现,在实现单元格时应考虑以下几点:

将一个 Layout Element 附加到根 GameObject 并在 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 来禁用此行为。

更改显示/隐藏动画

你可以通过更改 DebugSheetCanvas > Drawer 上的 Stateful Drawer 组件中的 AnimationDuration 和 AnimationCurve 属性来更改显示/隐藏动画。

在安全区域内工作

默认情况下，调试菜单会从屏幕外弹出，并在隐藏时放置在屏幕外。您可以通过勾选附加在"DebugSheetCanvas > Drawer"上的"Debug Sheet Drawer"组件中的"Move Inside Safe Area"属性来在安全区域内工作。

更改调试菜单的最小/最大大小

您还可以更改调试菜单的最小/最大大小。如果您更改了这个,它总是可以显示在屏幕底部,即使最小化了,如下所示。

要更改每个状态的大小,请编辑附加到"Debug Sheet Canvas > Drawer"的"Debug Sheet Drawer"的属性。调整"Min's Progress"来更改最小化时的大小,"Size"来更改最大化时的大小。"Middle"是竖直保持时应用的中间大小。

您可以通过单击"调试"区域中的"设置状态"按钮来应用和检查每个状态的大小。

自定义外观

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:

创建内置预制件的预制件变体,并进行任何所需的修改。
确保此预制件的名称与原始预制件相同。
将此预制件设置在"Debug Sheet"组件的"单元格预制件"中。

扩展包

显示Unity的系统信息

您可以通过此软件包轻松显示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>("系统信息")来添加页面链接单元格。

游戏内调试控制台

这是一个将Unity Debug Sheet与In-game Debug Console(一个用于在运行时显示控制台的开源软件)相链接的扩展包。通过这个包,您可以轻松地添加一个显示控制台的调试菜单。

使用方法如下:

安装并设置In-game Debug Console。(有多种安装方式)
(仅当不通过程序包管理器安装1时) 添加UDS_INGAMEDEBUGCOSOLE_SUPPORT到脚本定义符号并重启Unity。
(仅当使用自己的程序集时) 将UnityDebugSheet.IngameDebugConsole添加到引用程序集中。
写成DefaultDebugPageBase.AddPageLinkButton<IngameDebugConsoleDebugPage>("游戏内调试控制台", onLoad: x => x.page.Setup(DebugLogManager.Instance))来添加页面链接单元格。

Graphy

这是一个将Unity Debug Sheet与Graphy(一个用于显示FPS、内存等的开源软件)相链接的扩展包。

使用方法如下:

安装并设置 Graphy。(有几种安装方式)
(仅在非通过包管理器安装 1. 时) 添加 UDS_GRAPHY_SUPPORT 到 Scripting Define Symbols 并重启 Unity。
(仅在使用自己的程序集时) 将 UnityDebugSheet.Graphy 添加到引用的程序集中。
编写 DefaultDebugPageBase.AddPageLinkButton<GraphyDebugPage>("Graphy", onLoad: x => x.page.Setup(GraphyManager.Instance)) 以添加页面链接单元格。