Setting up Debugging

Setting up Build & Run

Install the DreamMaker Language Client extension for Visual Studio Code. The hotkeys are:

• F5 to build & run.
• Ctrl+Shift+B to build.

Setting up debugging

Auxtools (new and shiny)

To enable debugging on your codebase, first add the following code to a new file in your codebase:

/proc/auxtools_stack_trace(msg)
	CRASH(msg)

/proc/auxtools_expr_stub()
	CRASH("auxtools not loaded")

/proc/enable_debugging(mode, port)
	CRASH("auxtools not loaded")

/world/New()
	var/debug_server = world.GetConfig("env", "AUXTOOLS_DEBUG_DLL")
	if (debug_server)
		call_ext(debug_server, "auxtools_init")()
		enable_debugging()
	. = ..()

/world/Del()
	var/debug_server = world.GetConfig("env", "AUXTOOLS_DEBUG_DLL")
	if (debug_server)
		call_ext(debug_server, "auxtools_shutdown")()
	. = ..()

Then add the following block to SpacemanDMM.toml in the same folder as your .dme, or create it if it does not exist:

[debugger]
engine = "auxtools"

The debugging hooks will automatically activate when the project is run with F5. Use Ctrl+F5 to run without debugging. The debugging hooks will not activate when not configured, so this code can be safely committed to source control.

Adding to a non-ss13 codebase

The debugger relies on BYOND constantly running DM code. If e.g. you're trying to debug a newly created project, this may not be the case. If you don't have some sort of main game loop, you can edit /world/New to loop indefinitely to solve that issue:

/world/New()
	var/debug_server = world.GetConfig("env", "AUXTOOLS_DEBUG_DLL")
	if (debug_server)
		call_ext(debug_server, "auxtools_init")()
		enable_debugging()
	. = ..()

    while(1)
        sleep(5)

Extools (being phased out)

To enable debugging on your codebase, add this proc and call it at the top of /world/New():

/world/proc/enable_debugger()
    var/dll = world.GetConfig("env", "EXTOOLS_DLL")
    if (dll)
        call_ext(dll, "debug_initialize")()

The debugging hooks will automatically activate when the project is run with F5. Use Ctrl+F5 to run without debugging. The debugging hooks will not activate when not configured, so this code can be safely committed to source control.

Using the debugger

For a general overview, read Debugging in Visual Studio Code.

Troubleshooting

"Unable to determine offset in proc"

Ensure that debugging information is enabled for your project by adding #define DEBUG after the // BEGIN_PREFERENCES line in your .dme file:

// BEGIN_PREFERENCES
#define DEBUG
// END_PREFERENCES

Alternatively, in DreamMaker's Build > Preferences menu, check this box:

"Could not find task 'dm: build - yourstation.dme'"

There are several possible resolutions:

• Remove "task.autoDetect": "false" from your VSC settings.json.
• Manually add or adjust a custom build task in tasks.json to have the label "dm: build - yourstation.dme".
• Remove "preLaunchTask" in launch.json or change its value to the label of a custom build task.

"convertToDto unexpected type"

If you configured "Dreammaker: Byond Path", ensure at least one entry points to the root directory of a Windows BYOND installation (not bin).

Advanced configuration

Create launch.json

Click the "create a launch.json file" link in the Debug and Run view, or click the gear icon while a debug session is active.

Run without building

Edit launch.json and remove or comment out the "preLaunchTask" line.

Debugging on Linux

DreamSeeker and the debug hooks will work under Wine with no additional configuration. Use an attach configuration if running DreamDaemon under Wine. Debugging the Linux-native DreamDaemon is not currently supported.

Attach configurations

This documentation is not yet updated for Auxtools, but the technique is similar.

Mode and port parameters can be passed to debug_initialize. The default is as if you had written:

var/mode = world.GetConfig("env", "EXTOOLS_MODE") || "NONE"
var/port = world.GetConfig("env", "EXTOOLS_PORT") || "2448"
call_ext(dll, "debug_initialize")(mode, port)

Set EXTOOLS_MODE when running DreamSeeker or DreamDaemon or adjust enable_debuger to pass one of the following modes:

• BACKGROUND: listen for connections on the given port in the background.
• BLOCK: wait for a connection on the given port before resuming.

Edit launch.json, click "Add Configuration", and choose "BYOND: Attach to debugger". Ensure the port numbers match. You will also need to set EXTOOLS_DLL.

Read more about world.GetConfig.

Bundled Extools

To ensure compatibility, debug adapter releases bundle a copy of the extools.dll debugging hooks which they know how to communicate with and set EXTOOLS_DLL accordingly. To use a locally built DLL, set the dreammaker.extoolsDLL key in Visual Studio Code's settings.json. This setting is not currently exposed in the UI.