When developing your simulation, you will need to inspect and debug your application. To aid this, the Aether Engine SDK provides debugging support, which you can work with inside Visual Studio. Currently we support debugging a single process within your simulation code on the local VM.

Preparing the simulation


In order to debug an Aether Engine simulation within Visual Studio 2019, ensure you have installed the "Linux Development with C++" component, including the "C++ CMake tools for Linux" optional component. You can add these components by launching the Visual Studio Installer from the start menu and choosing 'Modify' for your Visual Studio installation. You will also need to have installed the Aether Engine CLI and virtual machine to debug simulations locally, along with the Visual Studio extension.

When installing the Visual Studio extension, you will be asked to choose a location to install to. After installation this location will contain the .vsix file that contains the extension, double click this to install the extension into Visual Studio.

Required CMake setup

In order for debugging to work well, you must ensure that your CMake build includes debug information, and it is strongly suggested that you disable optimisations. To ensure a good experience, include the --debug, -O0 and -fno-omit-frame-pointer in your CMAKE_CXX_FLAGS for your project.

Debugging a simulation

Please review the Important Irregularities and Limitations section before debugging or if you have any issues whilst debugging.

If you do not have an existing simulation you wish to debug, you can use the aether new command to create a template simulation. In order to debug a simulation, you first must declare the code-paths at which you wish to pause the running simulation, before starting it. This is done by adding a call to hadean::stop("reason") in your simulation code, which will cause that process to pause at that call, allowing a debugger to be attached. The reason provided is an arbitrary string of your choosing so you can identify the point and process that has been paused.

You can start your simulation with the appropriate debugging infrastructure by adding the --debug flag to aether run. By using aether run --debug you will enable the hadean::stop() calls to be respected, and Hadean OS will also launch the appropriate additional tooling required to enable a debugger to be attached to your simulation.

Note that for an Aether Engine simulation, if a single process is paused during a call to hadean::stop(), other processes will pause at the end of the current tick. This avoids the issue of the other processes in the simulation from continuing to simulate whilst you are trying to debugging a specific process.

To attach the Visual Studio debugger, first identify the process you wish to debug. This can be done with aether list-paused-processes, which will present the Hadean PID and the reason that process paused. For example, if you add the line hadean::stop("A collision occurred"); to the physics demo collision callback, then the output of aether list-paused-processes may look like this:

$ aether list-paused-processes
ID | Reason
----------------- | -------------------- | A collision occurred

Copy the ID of the process you wish to debug, and open Visual Studio. On your toolbar you can see "Connect to Local VM" and "Detach from Hadean Process" buttons. Note that the ID should be treated as an opaque string, and is subject to change.

Hadean Toolbar showing Connect to Local VM and Detach from Hadean Process

If you are unable to see these, ensure you have activated the Hadean Toolbar by right clicking on a blank space in the Visual Studio toolbar docking area, and select "Hadean Toolbar".

Menu allowing activation of Hadean Toolbar

A message box will be presented that allows you to input the ID of the process to connect to. Type or paste the ID of the process you wish to debug and click "Connect". Note that occassionally this Window can start behind the Visual Studio window, in which case you can use the Windows Taskbar to activate it.

Message box allowing input of the Hadean process ID to connect to

Visual Studio then connects to that process, allowing you to inspect the running process, modify variable values, step through or continue execution of your simulation code and set breakpoints, using the normal Visual Studio shortcuts and buttons.

Note that any breakpoints you set in Visual Studio will be hit whilst the debugger is connected, although once you detach from the simulation they will stop having any effect, and only your original hadean::stop() calls will then re-pause the simulation. Also note that if you set breakpoints inside Visual Studio these will not work until you connect the debugger to a specific process.

When you have finished debugging, you can detach from the process being debugged by using the "Detach from Hadean Process" button. This will cause the simulation to continue to run, at least as far as the next hadean::stop() call.

Continuing processes

If your simulation stops on a hadean::stop() call, but you wish to continue the simulation without attaching a debugger, then you can run aether continue-all to continue any processes that have stopped. If you run this whilst debugging a specific process, then all the other processes will continue.

Important Irregularities and Limitations

When opening Visual Studio, you should open the simulation directory for the simulation you wish to debug, rather than just a single file, in particular you should have the root CMakeLists.txt of your simulation be at the root of the Visual Studio open folder.

You must not press stop in Visual Studio when debugging a simulation.

Due to the nature of our internal implementation, visual studio will stop twice on each hadean::stop call.

While a simulation is paused, care should be taken to avoid clients continuing to send interaction input. Large amounts of buffered input may be processed in a single tick if clients continue to send during a debugging pause and may have a negative impact on the simulation.

Currently you can only debug a single process at a time, if you need to debug more than one process you will need to detach from the first process and connect to the second.

If the simulation becomes "stuck", for example if the simulation starts but produces no logs, it may be necessary to restart the VM.