Debug a transpiled ActionScript project in Visual Studio Code with Mozilla Firefox

1. Create a new ActionScript project targeting Apache Royale or HTML and JavaScript without a framework.

2. In your project's asconfig.json, specify the source-map compiler option.

   "compilerOptions": {
   	"source-map": true,
   }

   This will allow you to debug using the original ActionScript code.

3. Install the Debugger for Firefox extension for Visual Studio Code.

4. Create a directory named .vscode, if it doesn't already exist.

5. In the .vscode directory, create a file named launch.json.

   • To load from a web server, add the following content to launch.json:

      {
      	"version": "0.2.0",
      	"configurations": [
      		{
      			"name": "Launch Firefox (localhost)",
      			"type": "firefox",
      			"request": "launch",
      			"url": "http://localhost:8080/index.html",
      			"webRoot": "${workspaceRoot}"
      		}
      	]
      }

     Customize the url field to point to the correct URL for your web server.

   • To load a local HTML file, add the following content to launch.json:

      {
      	"version": "0.2.0",
      	"configurations": [
      		{
      			"name": "Launch Firefox (index.html)",
      			"type": "firefox",
      			"request": "launch",
      			"file": "${workspaceRoot}/bin/js-debug/index.html"
      		}
      	]
      }

6. Run the build task with Ctrl+Shift+B (or Command+Shift+B on macOS).

7. Open Visual Studio Code's Debug pane, and press the button with the play ▶️ icon to start debugging. Alternatively, use the F5 keyboard shortcut to start debugging.

Build automatically before debugging

Instead of building manually with Ctrl+Shift+B, you can configure launch.json to build your project automatically when you ask it to start debugging.

If you set the preLaunchTask field in launch.json to the name of one of the built-in tasks provided by the ActionScript & MXML extension, it will automatically run that task before debugging.

You can find the complete list of tasks that are available in your workspace when you go to the Terminal menu and choose Run Task....

For simple projects, the preLaunchTask field in launch.json should be set to ActionScript: compile debug - asconfig.json:

"preLaunchTask": "ActionScript: compile debug - asconfig.json"

If your workspace contains multiple root folders, you may need include the name of the root folder before asconfig.json in the task name:

"preLaunchTask": "ActionScript: compile debug - MyProject/asconfig.json"

Warning: If you're compiling debug builds using the Quick Compile & Debug command, DO NOT use preLaunchTask. It will cause your project to build twice before starting the debugger, which won't be very "quick" at all! 😄

Troubleshooting

Debugger will not stop at breakpoints on startup

In Firefox, the debugger may not stop at certain breakpoints that are added during your app's initialization. However, you will find that breakpoints that are triggered later (such as those added inside mouse event listeners) work correctly.

This is a limitation of the Firefox debug protocol. The JavaScript starts executing before the debugger can connect, so these breakpoints are essentially ignored. However, there is a workaround. You may add a debugger statement before the main class is instantiated in your HTML template file:

<script>
	debugger;
	new MainClass();
</script>

The debugger will automatically pause at this line. Press the green continue button in the debugger controls, or use the F5 keyboard shortcut, to resume debugging and access the breakpoints that previously didn't work.

Note: The debugger statement cannot be used in ActionScript. It must be added inside the JavaScript <script> tag on the HTML page.

Further Reading

• Debugging in Visual Studio Code (visualstudio.com)
• Debugger for Firefox extension (visualstudio.com)