2.9.16
Coherent GT Unity3D Guide
A modern user interface library for games
UI Debugging and Live Editing

Coherent GT supports the whole WebKit Inspector protocol and allows for live editing and debugging of the UI even when the client application is running. This increases the productivity of UI programmers and designers immensely as can directly work on the live interface without stopping the game, recompiling or restarting.

Debugging in Unity Editor

You can launch the Debugger from Unity Editor Coherent GT -> Launch Debugger, then navigate to http://127.0.0.1:19999 (or another port you've selected in the Coherent GT System component)

Debugging remotely

  1. In the "Coherent GT" package you'll find the debugger.zip archive. Extract it to a location of your choosing.
  2. Start the application on Windows or open Safari on Mac OS. Minimum required Safari version is 11.
  3. Run the game on the remote machine.
  4. Navigate to http://w.x.y.z:19999 (or another port you've selected in the Coherent GT System component) where w.x.y.z is the IP of the remote machine.

Debugging on built application

  1. Build your application in Development Mode.
  2. Start your application.
  3. Debug through Unity Editor or remotely.

Debugger in detail

It is advisable to use the debugging functionality only during development. It is automatically enabled when building in Development Mode and in the editor. Leaving it active on a shipped product leaves the UI accessible to users. This might be a desired feature as it aids UI modding but should be something to keep in mind when deploying a final product. The debugger is implemented in the CoherentUIGTDevelopment library.

The Debugger uses the resources located in the WebPlayerTemplates/inspector folder for its user interface.

The Debugger works over the network, so you can attach it either to you local machine or to a remote one. The debugging port is selected in the Coherent GT System component. If you pass -1, debugging will be disabled.

Debugging is done live, so start your application and have Coherent GT running.

You'll be presented with a list of Coherent GT Views that can be explored, debugged and edited.

Using the debugger

The debugger allows live viewing/editing of CSS styles, JavaScript debugging (setting breakpoints, watches, editing variables), resource load inspection, profiling.

The tool uses the WebKit Inspector UI, so for more information please refer to: https://developer.apple.com/library/safari/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/Introduction/Introduction.html

Changing elements live

With the Inspector you can manually change all aspects of the elements within the page as well as adding/removing whole sections of it. This makes prototyping and iterating on the UI very easy. Go to the "Elements" tab. The page with all its current state will be shown. You can hover elements and they will be highlighted in the View in the application. All properties of the elements are editable and changes will be immediately mirrored in the live application.

Debugging JavaScript

A complete JavaScript debugger is included in the Inspector. To use it go to the "Sources" tab, click "Enable Debugging". On the left side a list of the loaded JS sources is given. Users can add breakpoints, watches, step through expressions and catch exceptions.

Checking page performance

It is very important to keep track of the computational resources used by the UI each frame. The time it takes for the interface to update itself (usually through JavaScript triggered by the application), re-layout the content and re-paint it are particularly important. The Inspector provides a Timeline that is fully integrated with Coherent GT. Click on the Timeline tab. Now you can record some frames via the "Record" button (a dot in the low-left corner). Event happening in the UI will be registered along with their duration. Important events include:

  • Event - outside events like mouse over, clicks, keyboard events etc.
  • Timer fired - when a timer in JS fires
  • Request animation frame fired - what a requestAnimationFrame handler is called
  • Recalculate style - a CSS style recalculation caused by some event or JavaScript code
  • Time Start/End - events triggered in native code via the Binding API
  • Paint - parts of the View that get re-painted. Note that only the CPU time is recorded, not the actual time it took the GPU to perform the draw actions.

The Timeline tends to slow the application a bit, especially if many events happen. Numbers thus reported in it are usually somewhat larger than when it is not enabled.

The Timeline is invaluable when profiling the performance in the UI and makes spotting eventual bottlenecks very easy.

Detailed JavaScript profiling

If more detailed JavaScript profiling is required, use the "Profiles" tab and start a JavaScript CPU profile. It will time all JavsScipt code executed and give timing statistics on all functions.

Checking what gets re-drawn

Coherent GT re-draws only parts of the View that have changed between frames. You can check visually check what gets re-drawn by clicking the "Settings" button (the small gear icon in the low-left corner) and checking "Show paint rectanges". It is very important to keep re-drawn regions to the bare minimum. Redundant changes in the DOM like setting CSS styles with tiny differences can cause no visual change but still trigger a re-paint. Users should regularly check the behaviour of the page and make sure that no redundant and avoidable re-draws are triggered.

Checking the UI layers

Some elements in the page will get their own backing layers. A complete guide to the working of UI layers is available in the Performance guide. You can see what layers are currently on-screen and their re-paint counters and sizes clicking the "Settings" button (the small gear icon in the low-left corner) and checking "Show composting layers".

Optimizing performance

For a detailed guide on performance best practices, please refer to the "Performance Best Practices" section of the documentation.