Repository files navigation

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

Hierarchical debug menu system for Unity that makes it easy to create intuitive and organized debug menus.

In general, many debug commands are created during game development, and the number of them increases as development progresses.As a result, it becomes difficult to find the desired command, which in turn leads to a decrease in development efficiency.

Unity Debug Sheet allows you to easily create a debug menu with a hierarchical structure.Its GUI can be easily and intuitively controlled by anyone, especially on mobile platforms.

Of course, it also supports vertical layout.

Adding debug commands is also easy.

// LabelAddLabel("Example Label");//　ButtonAddButton("Example Button",clicked:()=>{Debug.Log("Clicked");});// SwitchAddSwitch(false,"Example Switch",valueChanged: x=>Debug.Log($"Changed:{x}"));// SliderAddSlider(0.5f,0.0f,1.0f,"Example Slider",valueChanged: x=>Debug.Log($"Value Changed:{x}"));

You can try the demo by cloningthis repository itself and playing the demo scenes. The following demo scenes are available.

Character Viewer: CharacterViewerDemo.unity

This demo allows you to switch between character models, motions, etc. from the debug menu.It also include samples that integrate with other libraries such asGraphy andIn-Game Debug Console to monitor performance.

Default Cells: DefaultCellsDemo.unity

This demo allows you to check the behavior of all the cells (generic name for items such as button, labels, and sliders, etc.) that are included in this library by default.

Custom Cells: CustomCellsDemo.unity

In addition to the default cells, you can create your own custom cells.This demo shows how to create custom cells.

Entry Scene: DemoEntry.unityThe above three scenes can also be transitioned from the this scene.You can see how the debug sheet placed in each scene behaves as singleton.

This tool is compatible with the following environments.

• Unity 2020.3 or later

You can install this library by the steps below.

1. SelectWindow > Package Manager from the menu bar.
2. Click the+ button in the upper left corner of the window and selectAdd package from git URL....
3. Enter the following URL in the input field and clickAdd.

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

Or, you can also install by adding the following line to thedependencies block ofmanifest.json file in thePackages folder.

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

If you want to specify the version, you can do so by adding the version number to the end of the URL.

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

You can update the version by changing the version number above.
If you do not specify the version, you can update it by opening the filePackages/package-lock.json and rewriting the hash of this library.

{"dependencies": {"com.harumak.unitydebugsheet": {"version":"https://github.com/Haruma-K/UnityDebugSheet.git?path=/Assets/UnityDebugSheet","depth":0,"source":"git","dependencies": {},"hash":"..."    }  }}

This section shows an easy way to set up and use the Unity Debug Sheet.

First, drag and drop the prefab namedDebugSheetCanvas toHierarchy window to place it in the scene.And ifEventSystem not exists, create it.

Next, create a page for debugging.Create the page by inheriting fromDefaultDebugPageBase as shown below.
The following is an example page with a single button that logsClicked when clicked.

usingSystem.Collections;usingUnityDebugSheet.Runtime.Core.Scripts;usingUnityEngine;publicsealedclassExampleDebugPage:DefaultDebugPageBase{protectedoverridestringTitle{get;}="Example Debug Page";publicoverrideIEnumeratorInitialize(){// Add a button to this page.AddButton("Example Button",clicked:()=>{Debug.Log("Clicked");});yieldbreak;}}

Next, add a link to transition to the debug page created above.
Get the root page and add a link button to it as shown below.

usingUnityDebugSheet.Runtime.Core.Scripts;usingUnityEngine;publicsealedclassDebugSheetController:MonoBehaviour{privatevoidStart(){// Get or create the root page.varrootPage=DebugSheet.Instance.GetOrCreateInitialPage();// Add a link transition to the ExampleDebugPage.rootPage.AddPageLinkButton<ExampleDebugPage>(nameof(ExampleDebugPage));}}

NOTEIf you want to use your own page as the root page instead of linking as above, useInitialize<ExampleDebugPage>() instead ofGetOrCreateInitialPage().AddPageLinkButton<ExampleDebugPage().

The debug menu can be opened and closed by flicking up and down along the edge of the screen.On the actual device, the area extends from the edge of the screen to approximately 6mm within the safe area.In the demo scene, the red band is displayed in this area to visualize flickable range.

This behavior can be changed from theFlick To Open on theDebug Sheet component.
You can enable only the left or right side of the screen, or disable flick operation.

WarningIn the Unity editor, this range is not necessarily 6mm because it simulate the resolution of the actual device.It is recommended to also use the operation with keyboard shortcuts described below.

You can also open and close the debug menu by pressing the button.To do this, set the click area fromClick To Open on theDebug Sheet component.You can set the number of times you need to click in a row to open it inClick Count To Open.

You can use keyboard shortcuts to open and close the debug menu.In default,Control (Command on Mac) + Shift + D toggles the debug menu.Shortcuts can be freely changed fromKeyboard Shortcut on theDebug Sheet component.

And you can also open/close the debug menu from your script as below.

// These scripts are attached on the GameObject "DebugSheetCanvas > Drawer".StatefulDrawerdrawer;StatefulDrawerControllerdrawerController;// Toggle debug sheet.varisClosed=Mathf.Approximately(drawer.Progress,drawer.MinProgress);vartargetState=isClosed?DrawerState.Max:DrawerState.Min;drawerController.SetStateWithAnimation(targetState);

With the implementation up to this point, you can confirm that the debug menu works as follows.

This section describes the basic usage of the Unity Debug Sheet.The Quick Start section is the prerequisite, so please read it first.

In default, you can use the following cells.

You can check the behavior of each cell by playing theDefault Cells Demo Scene.You can also create your own cells.See the Custom Cells section for more information about this.

You can use the following pages in default.

UsingCellModel, you can update the contents of the cell that has been generated.The following is an example of renaming a generated button each time theSpace key is pressed.Please refer to the comments for details.

usingSystem.Collections;usingUnityDebugSheet.Runtime.Core.Scripts;usingUnityDebugSheet.Runtime.Core.Scripts.DefaultImpl.Cells;usingUnityEngine;publicsealedclassExampleDebugPage:DefaultDebugPageBase{privateint_buttonCellIndex;privateButtonCellModel_buttonCellModel;privateint_counter;protectedoverridestringTitle=>"Example Debug Page";publicoverrideIEnumeratorInitialize(){// Create the CellModel and set data and events.varbuttonCellModel=newButtonCellModel(false);buttonCellModel.CellTexts.Text=GetButtonName();buttonCellModel.Clicked+=()=>{Debug.Log("Clicked");};// Keep the index of the cell and the CellModel._buttonCellIndex=AddButton(buttonCellModel);_buttonCellModel=buttonCellModel;yieldbreak;}privatevoidUpdate(){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();}}privatestringGetButtonName(){return$"Example Button{_counter}";}}

In default,DebugSheetCanvas is used as a singleton.That is, ifDebugSheetCanvas is placed in two scenes, the one instantiated first will be used and the one loaded later will be destroyed.

In this case, initialization should be only be done on the firstDebugSheet.If the order of scene loading is not guaranteed, you can useDebugSheet.GetOrCreateInitializePage() to get a page that has already been initialized, if any, and initialize it.Please refer to theDemoEntry scene for the workflow in multiple scenes.

Note that if you do not want to use it as singleton, you can do it by uncheckingSingleton in theDebugSheet component.

You should excludeGameObject, script files, and resources files related to the debug menu from the release builds.

You can exclude all scripts of theUnity Debug Sheet by addingEXCLUDE_UNITY_DEBUG_SHEET to theScripting Define Symbols in thePlayer Settings.Thus, if you enclose all your own code that accesses theUnity Debug Sheet with#if EXCLUDE_UNITY_DEBUG_SHEET, you can exclude all the code from the release builds.It may also be a good idea to combine your own scripts that accesses theUnity Debug Sheet into a single assembly and setDefine Constraints in theasmdef.

In addition, you can completely exclude the debug menu from your build by doing the following.

• Delete theResources folder containing the debug menu resources if you have created.
• Delete theGameObject containing theDebugSheet component in your scenes.

To create your own cell, first create a component that inherits fromCell and a model that inherits fromCellModel to set data to it.

usingUnityDebugSheet.Runtime.Core.Scripts;usingUnityEngine;usingUnityEngine.UI;publicsealedclassCustomTextCell:Cell<CustomTextCellModel>{[SerializeField]privateText_text;[SerializeField]privateLayoutElement_layoutElement;privateconstintPadding=36;protectedoverridevoidSetModel(CustomTextCellModelmodel){_text.text=model.Text;_text.color=model.Color;_layoutElement.preferredHeight=_text.preferredHeight+Padding;}}publicsealedclassCustomTextCellModel:CellModel{publicstringText{get;set;}publicColorColor{get;set;}=Color.black;}

Then, create a GUI, attach this component to it, and make it a prefab.Due to the implementation of the cell recycling system, the following points should be taken into account when implementing the cell.

• Attach aLayout Element to the rootGameObject and input a height in thePreferred Height property.
• Set the width of the cell to a fixed value.

Next, set this cell toCell Prefabs on theDebug Sheet.

All that remains is to add this cell to the page.Please refer tothe demo scene of the custom cells for the actual implementation.

You can also use asynchronous methods instead of coroutines to define lifecycle events of debug page, as shown below.

usingUnityDebugSheet.Runtime.Core.Scripts;usingSystem.Threading.Tasks;publicclassSomePage:DefaultDebugPageBase{protectedoverridestringTitle=>"Some Page";// Using asynchronous methods to define lifecycle eventspublicoverrideasyncTaskInitialize(){awaitTask.Delay(100);}}

To use asynchronous methods, addScripting Define Symbols in the following steps.

• Player Settings > Other Settings
• AddUDS_USE_ASYNC_METHODS toScripting Define Symbols.

Note thatScripting Define Symbols needs to be set for all platforms.

In default, the black GUI is displayed as the backdrop of the debug menu.You can hide it if you want by deactivating theGameObject ofDebugSheetCanvas > Backdrop.

In default, the debug menu is closed when the backdrop is clicked.You can disable this behavior by uncheckingClose When Backdrop Clicked in theStateful Drawer Backdrop Controller component attached to theDebugSheetCanvas > Drawer.

You can change the Show/Hide animations by changing theAnimationDuration andAnimationCurve properties in theStateful Drawer component attached to theDebugSheetCanvas > Drawer.

By default, the debug menu appears from outside the screen, and is placed outside the screen when it is hidden.You can work it within the safe area by checkingMove Inside Safe Area property in theDebug Sheet Drawer component attached to theDebugSheetCanvas > Drawer.

You can also change the min/max size of the debug menu.If you changed this, it can always be displayed at the bottom of the screen, even when minimized, as shown below, for example.

To change the size of each state, edit the properties of theDebug Sheet Drawer attached toDebug Sheet Canvas > Drawer.Adjust theMin's Progress to change the size shen minimized andSize to change the size when maximized.Middle is the middle size applied when held vertically.

You can apply and check the size of each state by clickingSet State button inDebug area.

Unity Debug Sheet consists of uGUI, so you can freely customize the look by adjusting the properties.

• Color of the back and close buttons
• Color of the backdrop
• Text color of the title

The design of each cell can be freely customized by creating a custom cell.See the Custom Cells section for more information on this.

You can pop multiple pages at once.To do this, specify the number of pages to be popped in the second argument ofDebugSheet.PopPage().

DebugSheetdebugSheet;debugSheet.PopPage(true,2);

You can also specify the destinationPageID.PageID can be obtained using theonLoad callback ofPushPage() as shown below.

DebugSheetdebugSheet;debugSheet.PushPage<DebugPage>(true,onLoad: x=>{varpageId=x.pageId;});

In addition, you can specify any ID by specifying thepageId argument ofPushPage().

DebugSheetdebugSheet;debugSheet.PushPage<DebugPage>(true,pageId:"MyPageId");

In addition, for the pages that are skipped when popping multiple pages, the lifecycle events before and after transition will not be called, only the event before destroying will be called.And the transition animation of the skipping pages will not be played.

You can extend built-in cell prefabs such as LabelCell and ButtonCell by following the steps below:

1. Create a Prefab Variant of the built-in Prefab and make any desired modifications.
2. Ensure the name of this Prefab is the same as the original Prefab.
3. Set this Prefab in theCell Prefabs of theDebug Sheet component.

Yuo can display the system information of Unity easily by this package.

Following features are now available.

Usage is as follows.

1. (Only if you use your own assembly) AddUnityDebugSheet.Unity to the referenced assemblies.
2. Write asDefaultDebugPageBase.AddPageLinkButton<SystemInfoDebugPage>("System Info") to add page link cell.

This is an extension package that links theUnity Debug Sheet withIn-game Debug Console that is the OSS for displaying the console at runtime.
By this package, you can easily add a debug menu to display the console.

Usage is as follows.

1. Install & SetupIn-game Debug Console. (There are several ways to install.)
2. (Only if you install 1. not via Package Manager) AddUDS_INGAMEDEBUGCOSOLE_SUPPORT to Scripting Define Symbols and restart Unity.
3. (Only if you use your own assembly) AddUnityDebugSheet.IngameDebugConsole to the referenced assemblies.
4. Write asDefaultDebugPageBase.AddPageLinkButton<IngameDebugConsoleDebugPage>("In-Game Debug Console", onLoad: x => x.page.Setup(DebugLogManager.Instance)); to add page link cell.

This is an extension package that links theUnity Debug Sheet withGraphy that is the OSS to display FPS, Memory, etc...

Usage is as follows.

1. Install & SetupGraphy. (There are several ways to install.)
2. (Only if you install 1. not via Package Manager) AddUDS_GRAPHY_SUPPORT to Scripting Define Symbols and restart Unity.
3. (Only if you use your own assembly) AddUnityDebugSheet.Graphy to the referenced assemblies.
4. Write asDefaultDebugPageBase.AddPageLinkButton<GraphyDebugPage>("Graphy", onLoad: x => x.page.Setup(GraphyManager.Instance)); to add page link cell.

This software is released under the MIT License.You are free to use it within the scope of the license, but the following copyright and license notices must be displayed when using it.

• LICENSE.md

In addition, the table of contents of this document was created using the following software

• toc-generator

The following software is used in the demo scenes.

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

See Third Party Notices.md for details on these licenses.