Unity调试表单

日本語ドキュメント(Japanese Documents Available)

用于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 或更高版本

安装

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

1. 从菜单栏选择 Window > Package Manager。
2. 单击左上角的 + 按钮,选择 Add package from git URL...。
3. 在输入框中输入以下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调试表的基本用法。 请先阅读快速开始部分,因为那是先决条件。

可用单元格列表

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

您可以通过播放默认单元格演示场景来检查每个单元格的行为。 您也可以创建自己的单元格。 有关此方面的更多信息,请参阅自定义单元格部分。

可用页面列表

您可以在默认情况下使用以下页面。

更新单元格内容

使用 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:

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

扩展包

显示Unity的系统信息

您可以通过此软件包轻松显示Unity的系统信息。

现在提供以下功能。

使用方法如下:

1. (仅当使用自己的程序集时) 将UnityDebugSheet.Unity添加到引用程序集中。
2. 写成DefaultDebugPageBase.AddPageLinkButton<SystemInfoDebugPage>("系统信息")来添加页面链接单元格。

游戏内调试控制台

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

使用方法如下:

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

Graphy

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

使用方法如下:

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

许可

该软件已发布在 MIT 许可下。您可以在许可范围内使用它,但使用时必须显示以下版权和许可通知。

• LICENSE.md

此外,本文档的目录是使用以下软件创建的

• toc-generator

演示场景中使用了以下软件

• https://github.com/yasirkula/UnityIngameDebugConsole
• https://github.com/Tayx94/graphy

有关这些许可的详细信息,请参见 Third Party Notices.md。