Debugging - GimpArm/AntRunner GitHub Wiki

Executing the AntRunner.exe with the argument debug causes the game manager to wait for each ant to finish before continuing so you have time to debug. You can also press F5 while AntRunner.exe is running to toggle debug mode on and off. You will want this due to the multi-threaded nature of the game. Without it your ant will receive multiple Tick() calls per second making debugging difficult.

All AntRunner.exe arguments which are paths to supported files (e.g. dll, js, php, py, rb) will attempt to load as ants at start up.

C#

netstandard2.0 project is recommended.

The Examples\csharp.zip file contained in the release zip has a netstandard2.0 project for C# already configured.

Setting up one click debugging for a .NET Standard project

  1. Right click on your solution file and choose Add -> Exising Project....
  2. Navigate to the AntRunner.exe file and open it.
  3. Right click the AntRunner in solution explorer and choose Properties.
  4. Under Arguments enter debug "C:\path\to\your\AwesomeAnt.dll". Save and close properties.
  5. Right click the AntRunner in solution explorer and choose Set as StartUp Project.
  6. Click Start Debugging and you will see your ant is loaded with the debugger attached. There will also be a red Debug in the upper right corner.

Setting up one click debugging for a .NET Framework project

  1. Right click your project file and go to Properties and open the Debug tab.
  2. Select Start external program.
  3. Navigate to the AntRunner.exe file and open it.
  4. Under Command line arguments enter debug "C:\path\to\your\AwesomeAnt.dll".
  5. Under Workind directory enter the path to the AntRunner.exe.
  6. Save and close properties.
  7. Click Start Debugging and you will see your ant is loaded with the debugger attached. There will also be a red Debug in the upper right corner.

JavaScript (node)

The JavaScript wrapper contains a stripped down node server which means you can use any IDE or debugging tools which you can use to debug node.

Edit the antsettings.json file to turn debugging on and off and to set your node port. If no port is set then a port is randomly selected.

{
    "debug": 1,
    "nodejs.port": 45378
}

Setting up one click debugging for JavaScript with Visual Studio Code

The Examples\js.zip file contained in the release zip has a workspace for debugging already configured.

Simply edit the .vscode\settings.json and set the "antrunner.root" to the folder which contains AntRunner.exe. Then running the Attach Node debug task will start the game, load the Ant.js file, and attach the debugger.

PHP

The PHP wrapper contains a PHP 7.2.14 thread safe executable, the Xdebug extension, and pthreads extension. You can use any IDE or debugging tools which you can use to debug PHP. Due to the nature of PHP and command line execution debugging can be tricky. Xdebug can only work in a sychronous way - meaning that unless it is paused for any reason (start of the script, a breakpoint), you can not issue new commands to it (for example, setting new breakpoints). Alternatively, Xdebug will also get triggered when the PHP function xdebug_break(); is called

Edit the antsettings.json file to turn debugging on and off and to set your xdebug ide key (For Visual Studio Code this should be "VSCODE").

{
    "debug": 1,
    "xdebug.idekey": "VSCODE"
}

Setting up one click debugging for PHP with Visual Studio Code

  1. Install the PHP Debug extension.
  2. Recommended but not required to install the PHP IntelliSense extension.

The Examples\php.zip file contained in the release zip has a workspace for debugging already configured.

Simply edit the .vscode\settings.json and set the "antrunner.root" to the folder which contains AntRunner.exe. Then running the Listen for XDebug debug task will start the game, load the Ant.php file, and attach the debugger.

Python

The Python wrapper contains the Python 3.7.2 executable python.exe, supporting libraries, and the ptvsd module Python Tools for Visual Studio debug server compiled for Windows.

Edit the antsettings.json file to turn debugging on and off and to set your ptvsd port. The ptvsd.port value must match the port in launch.json. Setting debug mode on your ant will cause AntRunner to pause until the debugger is attached. If no debugger is attached then the ant will fail to load. Only set debug to 1 when you intend to connect a debugger

{
    "debug": 1,
    "ptvsd.port": "25494"
}

Setting up one click debugging for Python with Visual Studio Code

  1. Install the Microsoft Python extension.
  2. Install Python and set up the required paths.

The Examples\python.zip file contained in the release zip has a workspace for debugging already configured.

Simply edit the .vscode\settings.json and set the "antrunner.root" to the folder which contains AntRunner.exe. Then running the Attach to Python debug task will start the game, load the Ant.py file, and attach the debugger.

Ruby

The Ruby wrapper contains the Ruby 2.6.1 executable ruby.exe, supporting libraries, and the rdebug-ide gem ruby-debug-ide compiled for Windows.

Edit the antsettings.json file to turn debugging on and off and to set your rdebug-ide port. The rdebug-ide.port value must match the remotePort in launch.json. Setting debug mode on your ant will cause AntRunner to pause until the debugger is attached. If no debugger is attached then the ant will fail to load. Only set debug to 1 when you intend to connect a debugger

{
    "debug": 1,
    "rdebug-ide.port": "25490"
}

Setting up one click debugging for Ruby with Visual Studio Code

  1. Install the Ruby extension.
  2. Install Ruby and set up the required paths.

The Examples\ruby.zip file contained in the release zip has a workspace for debugging already configured.

Simply edit the .vscode\settings.json and set the "antrunner.root" to the folder which contains AntRunner.exe. Then running the Listen for rdebug-ide debug task will start the game, load the Ant.rb file, and attach the debugger.

TypeScript (node)

The TypeScript is run using the JavaScript wrapper which contains a stripped down node server which means you can use any IDE or debugging tools which you can use to debug node.

Edit the antsettings.json file to turn debugging on and off and to set your node port. If no port is set then a port is randomly selected.

{
    "debug": 1,
    "nodejs.port": 45378
}

Setting up one click debugging for JavaScript with Visual Studio Code

The Examples\ts.zip file contained in the release zip has a workspace for debugging already configured.

Simply edit the .vscode\settings.json and set the "antrunner.root" to the folder which contains AntRunner.exe. Then running the Attach Node debug task will start the game, load the resuling Ant.js file, and attach the debugger.