Debugging with MS Visual Studio

This page is intended to serve as a guide for debugging FSO with MS Visual Studio's debugger. For building in Visual Studio, please refer to Building on Windows.

Setting up for Debugging Freespace

This section sets up Visual Studio so that you can debug Freespace by clicking the play button on the Visual Studio toolbar. You may need to enable the debugger toolbar via the View dropdown menu according to your version of Visual Studio.

1. In the Solution Explorer, right click on the Freespace project and click on "Set Up as Startup Project." The Freespace project name should be bold once you do this.

2. In the Solution Explorer again, right click on the Freespace project and click on "Properties" to bring up the properties pages dialog for the project.

3. Navigate to the Debugging page by using the tree box on the left side of the dialog.

4. Select All Configurations in the Configuration dropdown box. Any saved changes to the properties will be applied to all configurations for convenience. If you only wish to change properties for the Debug configuration, for example, then you can select that configuration in the dropdown box and it will only affect it.

5. Make sure at least the -window and the -res command line options are in the Command Arguments property. You may put all FSO command line options that you wish to use here (don't use commas to seperate them, put them as you would use them on the actual command prompt). IMPORTANT: The -res option should be a resolution lower than your desktop resolution, otherwise FSO may ignore the -window option and not let you tab out of FSO should it freeze during debugging.

6. Set the Working Directory property to a Freespace Open installation directory. For example, if you wish to debug FSO using retail assets, point the Working Directory to where your retail Freespace 2 directory is. IMPORTANT: If this property is not set, the FSO instance run by Visual Studio will crash because it can not find the necassary assets (it usually complains about something like a webcursor).

7. Click Apply To save changes to the Configuration(s), and then click OK to close the property pages dialog. If you change your mind, you may click Cancel to close the dialog and not save changes.

Setting up for debugging FRED

The process is similar to the setup for debugging Freespace, except that you'll be working on the FRED2 or qtFRED project from the Solution Explorer.

Setting up debugging with Mod Assets

Simply add the -mod command to the Command Arguments property and supply the directories to all mod folders you wish to work with as a comma delimited list. For example: -mod mod1root/mod1,mod2root/mod2,. You will have to change this listing every time you wish to work with a different set of mods.

If using Knossos, the mod folders may have a root folder with the actual mod dir as a subdir along with a mod.json and user.json. When debugging from the IDE, you want to give -mod the folder that has data/ as its immediate subdirectory and/or a bunch of .vp files.

You can use the usual directory navigation schemes, such as ./ and ../ to specify higher level directories.

If trying to debug a specific modpack, you should try running the modpack through Knossos or another launcher first and then grab the fs2_open.log from its usual location in C:\Users\<username>\AppData\Roaming\HardLightProductions\FreeSpaceOpen\data. Then, look for "Passed cmdline options:" in the first few lines of the log to see all the options that mod uses. You can put most or all of these options within the Command Arguments property to get an environment as close to normal execution. (Thanks to EatThePath for this suggestion)