The Lua Development Tools in the Eclipse suite has a possibility to “attach a lua debugger” to your LDT environment. Read this section to setup a debugger in our DCS World environment.
The people who have used debuggers before, will recognize a lot in this explanation!
How it works:
This capability will give you a new experience in DCS World mission design!
Note: The assets that are used in this description, were modified to accomodate the debugging, so the LDT off-the-shelf assets aren’t working. So use the assets as listed here, or your debugger won’t work!
The following pictures outline some of the interesting places in LDT to debug your lua code… A quick manual.
This picture shows a debug view of the LDT environment. You can activate the debug view through the debug icon that is located in the upper right corner of the LDT.
Various windows exist to track the content of:
This window lists the sources active in Eclipse. During a debug sessions, the sources where the process is at the moment of debugging, should be loaded automatically. If not, something is wrong. All the other sources that are currently open in the LDT are also listed.
This window shows the status of the “attach debug engine”. If this process is running, it will listen to the IP 127.0.0.1 or localhost if setup on your PC.
To use the debug enviornment in LDT, you’ll need to setup within LDT a “ Lua Attach to Application” debug listener.
You can access this screen through the LDT editor menu Run->Debug Configurations….
This is the meaning of each field:
For the IDE key, this key will be the “link” to the debug connection on the client side!
As will be explained a bit further,
initconnection( "127.0.0.1", 10000, "dcsserver", nil, "win", "" ) will make a connection on the debug client.
Ensure that the IDE key specified matches up in the debug listener and the debug client.
So in this example,
"dcsserver" is the IDE key and should match in the debug Configuration panel and the
This process is essential.
Within the MOOSE repository, there are two important files that you need to consider. These files are located in the MOOSE repository here.
Download the MOOSE repository or the files on your disk, and read further …
You should have at least on your disk:
This is the debug client. The source is part of the LDT debug suite, but has been modified to work together with the DCS World scripting engine. You need to copy this file to the root directory of your DCS World installation in Program Files.
By example, the location of debugger.lua is here on my DCS World installation PC.
The READ.ME file is a file that contains an explanation of how to modify the MissionScripting.lua.
But for clarity reasons, I’ve also attached my version of the MissionScripting.lua.
Take the MissionScripting.lua from the folder, and copy / paste (overwrite) the version in your DCS World installation directory under the Scripts folder. If you want, you can first rename the existing MissionScripting.lua file to MissionScripting_old.lua Don’t mistake yourself, a lot of mods/tools modify this file during installation.
Tools like slmod etc also change the MissionScripting.lua file (during installation). So beware that when copying over the file there may be unwanted changes. If you are using a mod, it is better to do the change manually according the direction in the READ.ME file!
And a validation needs to be done. Once you’ve modified/overwritten the MissionScripting.lua file, check if the contents are indeed changed! Sometimes it seems that the file is saved, but the contents aren’t updated due to lack of administration rights and extra security done by windows.
MissionScripting.lua should contain (at least) the following:
--Initialization script for the Mission lua Environment (SSE) dofile('Scripts/ScriptingSystem.lua') -- Add LuaSocket to the LUAPATH, so that it can be found. package.path = package.path..";.\\LuaSocket\\?.lua;" -- Connect to the debugger, first require it. local initconnection = require("debugger") -- Now make the connection.. -- "127.0.0.1" is the localhost. -- 1000 is the timeout in ms on IP level. -- "dcsserver" is the name of the server. Ensure the same name is used at the Debug Configuration panel! -- nil (is for transport protocol, but not using this) -- "win" don't touch. But is important to indicate that we are in a windows environment to the debugger script. initconnection( "127.0.0.1", 10000, "dcsserver", nil, "win", "" ) --Sanitize Mission Scripting environment --This makes unavailable some unsecure functions. --Mission downloaded from server to client may contain potentialy harmful lua code that may use these functions. --You can remove the code below and make availble these functions at your own risk. local function sanitizeModule(name) _G[name] = nil package.loaded[name] = nil end do sanitizeModule('os') --sanitizeModule('io') sanitizeModule('lfs') require = nil loadlib = nil end
Please read through the comment lines for a detailed description what it does. The io module has been de-sanitized because the debugger.lua needs to use the io module while debugging.
When you run a mission in single player in DCS World, a couple of things are happening.
So we need to do something special. The trick is dynamic loading. And believe me, it is the only way to be able to debug your sources. So this is a little task that you need to learn how to do, but once you understand it, it will become very easy to do.
Instead of executing a DO SCRIPT FILE, you need to add a couple of things in your .miz file.
Keep the DO SCRIPT FILE line in your mission. Why? Because if you would remove it, and you woudn’t debug your code, your mission file would be deleted. Instead, we are going to put a flag before this part of the execution. A debug flag. For example, in my mission I put a debug flag 999. When 999 is ON, I would NOT execute the mission file…
Follow this process how to do that… As my recommendation…
Setup a debug flag… If you wanna debug, set flag 999 to ON.
Conditionalize the DO SCRIPT FILE execution by evaluating if the 999 is OFF.
Now we are adding a little line. We are now going to ADD a dynamic loader of your mission source.
This loads the file dynamically. Instead of a DO SCRIPT FILE, we execute here a DO SCRIPT. The DO SCRIPT contains a little piece of code that loads your source file from a location on your disk.
This is how my piece of code looks like. I am using a stub of the MOOSE framework to load the file.
MOOSE.Include( full_path_name, file_name )
full_path_nameneeds to be between quotes, follows unix folder notation and needs to end with a /
file nameis the full file name, including the .lua extension!
If you don’t wanna use __Moose.Include, no worries, there is another method.
_G.loadfile( full_path_name .. file_name )
The MOOSE.Include loader uses _G.loadfile to load the sources. But it does a bit more checking and logs in dcs.log which files were dynamically loaded, and from which location!
Now we are all setup! You’ve got your debug listener setup in LDT, you got your debug client setup and connected to your DCS World environment, and you got your mission file ready for debug!
Now we are going to run a debug. To have a successful debug run, you need to start the listener in LDT.
First we setup the Debug as your “favorite”, so that it is easy for your to repeat the run easily.
Click on the “Bug” icon that you’ll find in the task bar. The “Bug” icon is the place where you will start your debug listener. However, first, click on Organize Favorites. You need to do this one time only.
Just click on the Debug Name that you entered (for me DCS 1.5) in the Debug Configuration window and it will be added ot your favorites. I did already that, so it was already added as an example in the previous picture.
Now you can easily activate the debug listener.
Just click the “Bug” again, and select the debug listener that you configured.
When done, you’ll see that the debug listener is running!
It will be listening quietly to IP 127.0.0.1 on port 100000.
Open your source file from the exact location from where you have specified it to be loaded as part of the dynamic loading. Once it is loaded, you can attach breakpoints within the editor.
How? Right click on the source line number or the grey area before the line, and a pop-up window will appear. Select “Toggle Breakpoint”.
As a result, the breakpoint will be listed in the “Breakpoints” list at the debug view, and it will show also the line number where the breakpoint is set. When your mission runs, the logic will stop at this line!!!
Now it is time to start your DCS World mission. Just run it as you would like have it.
There is a lot to say about debugging and the techniques that you can use how to track the code. For this, videos will be made in the MOOSE For Dummies video series.
Please consult the youtube channel for more info on debugging.
When I started to use DCS World (discovered it by accident), I was sold. After a while I started to discover the SSE capabilities of DCS World and started to code lua. But a very important piece was missing while developing the MOOSE framework.
I’ve been searching for about 4 years to get this working. There was a huge learning curve. I had to “hack” myself into the LDT environment and modify the LDT assets to make this work. There were moments of “clarity” that made me understand how it all fits together. And now it is there. Wanted to share this for all users of DCS World.
It does require a bit of effort to use this in the DCS World environment, but the little effort is a small trade against the huge advantages here!
I also encourage you to use the MOOSE Framework, as it brings you a lot of great capabilities you will never have in any editor. Being able to debug your code, will solve a lot of your questions now!
I hope you will all have fun with the new debug capability and that it may result in greater missions.
kind regards, FC