ZeroBrane IDE

Overview

All you need to create Lua-scripts for Pragma is a basic text-editor, however to get access to advanced debugging capabilities, it's recommended to use the ZeroBrane Studio Lua IDE. ZeroBrane is free and allows you to debug Lua code with features like step-by-step code execution and breakpoints, which you can see in action here:

Pragma also ships with an auto-complete script for ZeroBrane to maximize productivity:

You are of course free to use any other editor, in which case you can ignore the rest of this tutorial.

Setup

After downloading and installing ZeroBrane, a few more manual steps are required to set it up for Pragma:

1. Start ZeroBrane, Select "Project -> Project Directory -> Choose..." from the menu bar, navigate to your Pragma installation (Default: "C:/Program Files (x86)/Steam/steamapps/common/Pragma/") and select it. Without this step, the debugger may not be able to locate the Lua files during debugging.
2. Navigate to "Pragma/doc/ZeroBrane" and copy its contents to your ZeroBrane installation (Default: "C:/Program Files (x86)/ZeroBraneStudio").
3. Select "Edit -> Preferences -> System" from the menu bar and append the following lines to the end of the file:

   include "pragma.lua"
   editor.autotabs = true

4. Save the file and restart ZeroBrane.
5. Select "Project -> Lua Interpreter -> Pragma" from the menu bar. This step is required for the auto-complete feature.

This completes the basic setup for ZeroBrane, however to use the debugging capabilities a few more steps are required every time you want to use the debugger. The debugger requires that you add -luaext to the launch parameters in Pragma:

If set up correctly, you should see a red "[D]" next to the version number in the main menu:

This will enable several Lua modules which are required for the debugger. These modules could potentially be used to cause damage to your system by a malicious Lua-script, so it's recommended to remove the launch option again when playing on multiplayer servers, or if you've downloaded custom addons from sources you don't completely trust.

The following steps have to be executed every time you want to use the debugger, after Pragma has been started, but before a map has been loaded (i.e. while you're in the main menu, or before you've run the "map" command on a dedicated server).

1. Start ZeroBrane and select "Project -> Start Debugger Server" from the menu bar.
2. Run the console command sh_lua_remote_debugging 1 if you want to debug a serverside script, or sh_lua_remote_debugging 2 if you want to debug a clientside script.
3. Open a Lua-file from your Pragma installation in ZeroBrane. Any Lua-file will do, but without this step, ZeroBrane may not be able to locate any Lua-files at all.
4. Load a map. The "output" window of ZeroBrane should say something along the lines of "debugging session started", which means it connected successfully to Pragma. In this case Pragma should appear frozen and unresponsive in the background and you should see the following controls in the menu bar of ZeroBrane:
5. Click the green arrow (alternatively press F5) to resume Pragma.

The debugger is now fully set up and initialized. You can find an overview of its features and how to use them here.