Error messages in a log file are helpful for fixing simple problems like syntax errors, but if you've done any programming before - even simple scripting work - you know that a log file isn't enough for diagnosing more complex problems with a program's logic. For that, you need an interactive debugger. A debugger is a tool that lets you get inside your program and watch it as it runs, step by step, observing the values of variables and which branches are taken.
PinballY currently works with the following third-party debuggers:
If you run into any problems with debugging, feel free to report them as issues, but be aware that it might not be practical for me to add any substantial missing features until Microsoft makes more progress on this. Hopefully they'll continue developing it and it'll become more complete over time.
For very simple debugging tasks, you can sometimes get enough information by instrumenting your code with debugging messages. One way to do that is to display messages through the user interface, such as via the message() and alert() functions. Another way that's less intrusive in the UI is to use logfile.log(), which writes messages to the log file for review after the session ends.
One of the main functions of any debugger is the ability to pause execution at any arbitrary point in the program, so that you can inspect the current values of all variables and step through sections of code one line at a time. The exact command to pause execution varies by debugger, but the VS Code and the Chrome debugger have similar UI features, with buttons to pause execution of the running program, step one line at a time, and set breakpoints at source locations.
At program startup, the debugger will normally pause execution at the first line of your main.js script. You can override the initial stop location using the /jsdebug:break=xxx command-line option when starting PinballY.
Full documentation for VS Code is available on the VS Code docs site.
Note that you don't have to install the traditional Visual Studio (Microsoft's large-scale IDE for system programming languages like C++ and C#) to use VS Code. VS Code is a completely independent, standalone program that doesn't depend upon Visual Studio in any way, despite the similar name.
Here's the full setup procedure, starting from scratch. If you already have VS Code installed, just skip the download-and-install step.
VS Code will now be set up to connect to PinballY. You can return to this configuration in future sessions by using File > Select Folder to return to the same PinballY Scripts folder, since VS Code keeps its configuration data with the folder.
You can go back and manually edit that launch.json file at any time, or create it manually yourself. You'll find it in the .vscode folder within your PinballY Scripts folder (or whichever folder you selected in the "navigate to your Scripts folder" step above).
This procedure launches PinballY as a child process of the VS Code debugger, so you should close any running instance of PinballY first.
You'll probably find it most convenient to launch PinballY directly from VS Code as described above, but there's another way to do it. You can alternatively launch PinballY yourself, and then "attach" VS Code later.
The launching procedure with the Chrome debugger is a little different from VS Code. Chrome won't launch PinballY for you the way that VS Code does. Instead, you have to launch each program (Chrome and PinballY) separately, and then tell Chrome to connect to the running PinballY instance. PinballY accommodates this by pausing in a "Waiting for debugger" dialog until a debugger connects, giving you a chance to intercept the startup scripts without any super-human feats of timing.
Here's the setup procedure:
Warning: As mentioned earlier, ChakraCore's debugger interface is only designed to work with VS Code. It might work in a limited way with other debuggers that implement the Chrome DevTools protocol, but many functions are likely to be broken. Even so, I'm documenting the basic setup procedure here for reference, in the hope that support for other tools improves in the future.
If you want to try an alternative debugger, here's the generic setup procedure. You'll have to adapt the steps to your debugger's particular settings dialogs or configuration file setup, of course.
The "port number" we've referred to a number of times is a local TCP port number. This is a type of network port, but in this case it doesn't actually access your LAN or Internet connection; it's just for local connections between programs running on your computer. The port number simply identifies the port so that the applications can connect to each other.
Any port from 1024 to 49151 is valid, as long as the port isn't already in use by some other program. The default port is 9228, which isn't used by any common software that I know of. PinballY will show an error at startup if you choose a port that's already in use; if you see such an error, simply choose a different number in the valid range.
The range of valid ports is so large that it's usually easy to find a free port by just choosing one randomly. However, if you want to see a list of exactly which ports are in use on your computer, type netstat /an into a CMD prompt window. Look for entries in the "Local address" column with address 127.0.0.1: the number after the ":" is the port number.
How to tell PinballY which port to use: On the PinballY command line, enter the port number like this (substituting the port number of your choice for the default 9228):
How to tell your debugger which port to use: That's different for each debugger. For VS Code, you enter it in the launch.json file under the "port" setting. For Chrome, you add it to the "network targets" list as localhost:port.
/jsdebug by itself enables debugging and selects a number of default settings. You can change the defaults by adding some extra sub-options to the /jsdebug parameter. Append sub-options to /jsdebug after a colon (":"). To use more than one sub-option, separate them with commas:
The sub-options are: