1.3 Debug MagicScript Apps

Use the debugger to pause execution and step through the code that is running on the device or to evaluate expressions in the console. When MagicScript apps run in debug mode, an internal websocket server is started that exposes the JavaScript runtime V8 inspector protocol. Set up port forwarding by default using the magic-script run command in a command line session or manually through Magic Leap Device Bridge (MLDB) to allow remote debugging of apps with any client that uses this protocol. Two common clients are Chrome DevTools and Visual Studio Code.

Pre-requisites

Hello, Cube! MagicScript

Start the Server

The magic-script build command sets the debug flag in the digest file by default. This flag is required to enable runtime debugging. The magic-script run command runs the process on the device with mldb launch and watches the output of mldb log for a line specifying the debug port on the device. Once the debug port is identified, the magic-script run command calls mldb forward <port number> to forward the port to the host computer.

Start with a Fixed Port

The debug port is randomly selected by the operating system on the device. There are three ways to set the port manually in your workspace.

  1. Enter in a command line session: magic-script run -p <port number>

  2. Set the INSPECTOR_PORT environment variable in your workspace and enter in a command line session:

    magic-script run

  3. magic-script run calls mldb launch and mldb forward for you. To do this yourself, enter in a command line session:

    mldb launch -v INSPECTOR_PORT=<port number> --auto-net-privs $APPNAME

    To setup the port forward to the host, enter in the command line session:

    mldb forward tcp:<port number> tcp:<port number>

Connect to an Inspector Client

Connect to an inspector client in order to debug with inspector clients. This guide covers connecting to and debugging with the Google Chrome DevTools and Visual Studio Code inspector clients.

Connect to Chrome DevTools Inspector Client

There are two ways to connect to the Chrome DevTools Inspector Client:

  1. Copy the chrome URL returned by magic-script run and paste it into the address bar. This is the default workflow.

  2. If you started the server with port 9229, you can enter chrome://inspect in the address bar and click Open dedicated DevTools for Node. Only one app can be debugged at a time on this port.

    Inspector Client with Open dedicated DevTools for Node highlighted

Note: Although the DevTools UI displays Node.js, MagicScript is running on the device.

When you are connected to the inspector client in Chrome DevTools, press cmd-P on Mac or ctrl-P on Windows to search for the source code file you want to view and debug. Visit the JavaScript and memory sections of the Chrome DevTools documentation for more information on how to profile your application in this inspector client.

Connect to Visual Studio Code Inspector Client:

Configure debugging for your project by following Visual Studio Code's Debugging guide. When a launch.json file is created, add the following to .vscode/launch.json:

{
"version": "0.2.0",
"configurations": [
{
"type": "node",
"request": "attach",
"name": "Attach to MagicScript",
"address": "localhost",
"port": 9229,
"protocol": "inspector",
"localRoot": "${workspaceFolder}",
"remoteRoot": "/"
}
]
}
  1. Ensure the port number matches the port number either returned from the magic-script run command or the port number you set with MLDB.

  2. With your project open in Visual Studio Code, launch the debugger.

    In VS Code launch the debugger from the debug icon in the right menu, then the Play icon

Debug with Inspector

Console logs

To help debug your code and print out values, you can use console.log(), console.warn(), console.info(), or console.error(). These print their results to the MLDB log as well as the inspector client's console pane.

Live-Edit Code

With Chrome DevTools and other inspector clients, you can live-edit your MagicScript app. The V8 inspector protocol includes limited, built-in support to live-edit your code. To verify if you can live-edit code, change the update handler to log the delta and check if logs print out. The changes made while live-editing are not added to your source files and are only for modifying the state of the current application session.}