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 they can directly work on the live interface without stopping the game, recompiling or restarting.

Setting up your game for debugging

Copy the inspector folder from the root of the Coherent GT SDK to the working directory of your application.
Make sure you have the CoherentUIGTDevelopment module in the same folder as the main CoherentUIGT module that your application uses.
Start your application.
Start PackageRootDir/debugger/Win64/Debugger.exe on Windows or open Safari on Mac OS. Minimum required Safari version is 11.
Navigate to http://127.0.0.1:19999 or another ip / port you want to connect to. Our dev server runs in the local network so you can easily connect to other machines in the same network if you know their IP / port.

Using the packaged debugger

The Coherent GT debugger is packaged in every Coherent GT package and can be found in PackageRootDir/Debugger. Prior the first use of the debugger, you need to run the bootstrap script for your OS - e.g. PackageRootDir/bootstrap_win32.bat.

Please note that:

The standalone debugger might not work on virtual machines.
If you would like to debug a game that is running on a VM, you should forward the debugger port.

Debugger in detail

It is advisable to use the debugging functionality only during development. 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. During development you should put the library in the same folder as the main CoherentUIGT module. If the library is missing, the debugging functionality will not be enabled. You can safely remove CoherentUIGTDevelopment from your shipped product.

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 part of the Coherent::UIGT::SystemSettings, which are used to initialize the UI GT system. If you pass -1, debugging will be disabled.

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

Start the Coherent GT Debugger and navigate to http://127.0.0.1:9999 where 127.0.0.1 is the IP of the machine where Coherent GT is running (in this case the local machine) and 9999 is the port selected for debugging.

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

Debugger capabilities

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 Debugger 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 every package. 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 Debugger 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.

Custom Timeline events

You can add your own custom events to the Timeline to better correlate events in the application with what is going on the UI. To register a timed event use the View::InspectorTimelineBeginEvent and View::InspectorTimelineEndEvent methods. The timed event will be displayed in the Timeline with the string passed to those methods.

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 "CoherentUIGT_performance_guide.pdf" available in the bundle.

Source mapping

When a source map is generated the *//# sourceMappingURL=* must be used as a source url. If you are using webpack, configure it to use the cheap-source-map or cheap-module-source-map modes for source maps.

Table of Contents