The Lua debug library

[Thalassicus]

I've got us access to the Lua debug library in the latest patch. The main useful thing for modders is debug.traceback. Set this value in config.ini to use the debug library:

\Documents\My Games\Sid Meier's Civilization 5\config.ini
EnableLuaDebugLibrary = 1

Traceback helps track bugs. Look at the "Fatal" error level of the Lua logger in the unofficial patch (/ModTools/MT_LuaLogger.lua) for a practical example of how to use it. Say functions RootA and RootB call function SomeHelper. Error reports show one calls SomeHelper incorrectly, but it's not clear which. You can identify the culprit with a traceback:

if debug then print(debug.traceback()) end

stack traceback:
[string "D:\Thalassicus\Documents\My Ga..."]:1111: in function '[B]SomeHelper[/B]'
[string "D:\Thalassicus\Documents\My Ga..."]:1119: in function '[B]RootB[/B]'
[string "D:\Thalassicus\Documents\My Ga..."]:115: in function ...

The main lua process (3) called RootB (2), which called SomeHelper (1), which had the print statement.​

NOTE: If the user does not have the debug library enabled, debug is nil and calling debug functions results in an error. Use "if debug then" before such calls. The debug library is not efficient and should be used sparingly.

The function debug.getlocal can access local variables of any active function in the stack. This can be useful to identify parameters of under-documented Event/LuaEvent functions in the API.

 

[DonQuiche]

Oh ! Thank you! Thank you so much!

 

[DonQuiche]

One question please: you mentioned the last patch... So it's not Gods and Kings specifics, we can use it with vanilla version of the game, is it correct?

Now, regarding GetLocals, I don't think we can use it to get the parameters of the civ5 API since those calls are typically on the top of stack while GetLocals will only possibly report anything below the current call:
Entry point
Func A
Func B
Func C calling GetLocals
Some API function.

However traceback will be very useful.

 

[whoward69]

You also can't use debug.getupvalue(Cfunc, index) to get the parameters - see http://lua-users.org/lists/lua-l/2008-05/msg00682.html

 

[Thalassicus]

@DonQuiche
It should be possible to use this without G&K, but I haven't tested that.

@whoward69
Thanks for pointing that out. I wasn't aware it isn't possible to access C++ parameters from lua.

 

[DonQuiche]

Thank you Thalassicus.

 

[DonQuiche]

An interesting thing: when you set "EnableLuaDebugLibrary = 1" in config.ini, civ5 automatically displays stack traces on lua errors in FireTuner (and probably lua.log). Very helpful.

 

[Thalassicus]

I noticed that too. It makes sense as traceback is only available with the debug library. It's so much easier to find errors now!

 

[Pazyryk]

And now we can see the function name! (No more guessing due to the stupid truncated path name.) I've never been so excited to see a Lua bug!