[Guide] Debugging Mods with FMTK on NixOS

[berserkguard]

Hey everyone,

I had to jump through some hoops to get Lua debugging through the Factorio Modding Tool Kit VSCode extension working on NixOS (this guide assumes the Steam version). Figured I'd write a guide in case it helps anyone else!

I also found information in general on how to set up the extension/Factorio for debugging very sparse, so hopefully this helps in a broader sense.

Install VSCode w/ Factorio Modding Tool Kit extension

1. As I installed VScode with an FHS env, I just installed the FMTK extension from within VSCode directly. If you installed VSCode in pure declarative mode, you'll need to add the extension to your Nix config. Refer to the NixOS VSCode guide
2. Open a VS Code workspace to your Factorio mods folder (~/.factorio/mods/)

   Code: Select all

   code ~/.factorio/mods/

Create a wrapper game launch script

On NixOS, we can't launch factorio directly - we need to use the steam-run command to ensure we launch it within Steam's FHS environment.

To support this, do the following:

1. Open a terminal and navigate to your factorio executable path:

   Code: Select all

   cd ~/.steam/steam/steamapps/common/Factorio/bin/x64/

2. Create a new launch_factorio script (change out bash accordingly if you configured Nix to use a different shell):

   Code: Select all

   cat << EOF > launch_factorio
   #!/run/current-system/sw/bin/bash
   steam-run ~/.steam/steam/steamapps/common/Factorio/bin/x64/factorio $@
   
   EOF

   This launches Factorio using steam-run, passing any arguments directly to the factorio executable. FMTK automatically provides the arguments needed to enable the debug Lua API and set its debugadapter mod as the instrument mod.
   • Without $@, the --enable-unsafe-lua-debug-api arg won't get passed and the debugadapter mod (automatically added by FMTK) will fail to load at boot
   • Without $@, the --instrument-mod debugadapter arg won't get passed and you won't be able to step through the Lua code in VSCode
   • This launcher script has to live alongside factorio executable because the FMTK extension assumes so and builds relative paths from it to other files in the Factorio install location
3. Make the wrapper script writable:

   Code: Select all

   chmod +x launch_factorio

Configure Factorio Modding Tool Kit extension

1. Inside VSCode, on the bottom, click "Factorio" and then "Select another install location..."
2. Browse to and select the launch_factorio wrapper script we created earlier
3. Give the profile whatever name you want

Running

1. Select or create a launch configuration (also from the bottom left) - "Factorio Mod Debug (Settings & Data)" should cover most needs
2. Launch the configuration - it should now launch Factorio with the debugadapter mod enabled and without any errors
3. You can now set breakpoints within any unzipped mod .lua scripts and have them get hit!