Using Dev Tools

Gameface’s DevTools (also referred to as the Inspector) are based on Google Chrome’s DevTools, enabling developers to work in a familiar environment supporting standard features such as remote debugging and performance monitoring.

Gameface’s remote debugging support is currently a task in active development. The Google Chrome browser is required.

Supported Platforms #

• Windows
• Android
• UWP [partial]
• Xbox One
• Xbox Series X
• PlayStation 4
• PlayStation 5
• Nintendo Switch
• Mac OS X
• iOS [planned]

Refer to the Supported Panels below for more info.

Accessing DevTools #

Windows #

• Once the application is started if everything is configured correctly Cohtml will listen for HTTP requests on the opened port on the PC. This means that a browser can send requests and the UI debugger is going to handle and respond to them. Make sure the chosen browser is Google Chrome.
• Connect to the PC and port provided in the backend from Google Chrome. This could be localhost:port. if Google Chrome is run on the same PC as Cohtml. All available Views are listed upon connection.

• Choose the view to debug and proceed with troubleshooting.

Android #

Workflow is similar to Windows with one difference:

• Connection is remote - from the Google Chrome browser running on a PC to the application running on a device.
• To debug the application determine its IP address by connecting it to the Wi-Fi and checking the WLAN IP address from Settings (different per device).
• Connect using that IP and the port provided in the backend from Google Chrome, instead of localhost.

Nintendo Switch #

The Switch platform has two network interfaces, one for running the application and another one for debugging. The IP address used for debugging can be found in the Network panel of the Switch SDK.

Supported panels #

• Elements panel

  • DOM tree view - view and modify the DOM tree.
  • Element styles view (accessed through the Styles sidebar tab) - view of the element’s inline and attribute styles.
  • Element computed style (accessed through the Computed sidebar tab) - List of all computed styles including rendered fonts information. Styles and font info are refreshed when another element is selected.

• Debugging JavaScript (accessed through the Sources tab) is not supported on iOS and UWP.

• Console (accessed through the Console tab) is not supported on iOS and UWP.

• Sources

  • The panel is supported on all compatible platforms
  • Known issues: When navigating between pages (or dynamically re-loading the same page) while connected with the DevTools, the Sources panel is not updated correctly. Please refresh the browser window with DevTools to see the correct loaded sources.

• Performance profiling (accessed through the Performance tab). Partial support on all supported platforms:

  • Recording
  • Timeline - see how much time different components take - this includes:
    • Style Recalculations - shows also style match cache misses
    • Script Execution
    • V8 Tracing Events - shows where V8 is spending time
    • Layout
    • GPU time.
    • Paint
    • Match Elements - how much time is spent matching nodes
    • Build DOM - how much time is spent building nodes
    • Record Rendering - shows also resource cache misses
    • Schedule Style Recalculation - has a run-time option for maximum schedules
    • Invalidate Layout - has a run-time option for maximum invalidations
    • Events that happen in the rendering library
  • GPU metrics are only supported with DirectX 11
  • Screenshot capturing - enabling the “Screenshots” checkbox before recording will capture screenshots of the UI texture after every frame and display them in the timeline
  • Tracking of GPU memory - enabling the “Memory” checkbox will display info about the types of memory that the rendering library uses
  • Tracking of different object counts - enabling the “Counters” checkbox will display info about the count of different GPU objects that the rendering library has created Initiators
    • To specify the number of maximum initiators shown for a single Recalculate Styles and Layout event, the JavaScript function engine.setInspectorInitatorsUpperBound(count) can be used. By default, the count is 0 and no initiators are shown. Based on the profiled UI, showing all the initiators for a given event might affect the performance, but will give more information about the causes for the event and the costs of the JavaScript functions can be analyzed.

• Network activity inspection (accessed through the Network tab). Partial support on all supported platforms:

  • Inspecting request-response times, headers, and URLs is supported for all cohtml resources except Fonts.
  • Partial media requests are accumulated into a single network panel entry. The time and size for that request are accumulated as well.
  • Requests for resources that were cached before are marked as (memory cached) and contain 304 Status Code and Coherent-Cached header.
  • User image responses are marked with the Coherent-UserImage: true header. User image responses body is never exposed.
  • Messages viewer for WebSocket connections is supported with the following limitations:
    • request/response headers and statuses are not exposed and hardcoded to the default ones
    • binary payload viewer is not supported
  • Because in Gameface normal requests have a single state of loading, the time spent for a request falls into the Stalled category, which is expected.
  • The time visible in the Network tab for a request is the time from issuing the request on the Main (UI) thread to receiving the response on the Main thread. Hence both main and worker thread tasks scheduling and execution affect the times shown in the network tab.
  • Response body inspection is supported for all requests except requests for resources that were cached previously
    • e.g. The first request for an image will be shown in Inspector and the response can be viewed for that response. But the next request for the same image won’t contain the original response body and headers because no requests were performed.
  • By default, the data for Network Panel will be collected only when the Inspector Network Panel is connected to the cohtml server. It means that if you load a page, open the Inspector URL, and open the Network Panel, the requests performed before opening the Network Panel won’t be visible. Only subsequent requests will be shown. To see the requests performed before opening the Network Panel, cohtml::ViewSettings can be used. Gameface provides a cohtml::ViewSettings::InspectorNetworkTabMode setting in cohtml::ViewSettings. This setting can be changed to cohtml::InspectorNetworkTabSettings::Mode::AlwaysEnabled, which should lead to the desired behavior: requests data will be collected regardless of the state of the Inspector frontend. Refer to cohtml::InspectorNetworkTabSettings::Mode for more information.

Source maps #

Since the inspector loads source maps by itself and doesn’t understand the coui:// protocol, the only way to use source maps is if they are embedded. How to do that https://github.com/CoherentLabs/InlineSourceMaps

Troubleshooting #

• If you receive an error like the following Error: Inspector failed to parse HTTP data on connection 1968. Reason: CR doesn't follow LF after value at where the connection will most probably be a different number delete your browser cookies and retry the connection.

Further Resources #

For more information on DevTools usage consult the documentation here.