SCAR debugging

Contents

Introduction

Debugging SCAR Files

Try and compile using LUA:

Use print to help you debug.

Check the console for errors.

Lua Watcher & Rule Profiler

Introduction

This tutorial will provide you with a set of hints and tips that will help you in debugging any SCAR scripts as well as sequences. This is by no means an exhaustive list of items, but these items should make tracking down bugs, and working with SCAR a lot simpler.

Debugging SCAR Files

When writing scar files, there is no doubt that you will run into bugs and problems. There are several techniques that can help you minimize the quantity of problems and bugs that you'll have to deal with. These techniques are presented here in order to help you out of any tight situations that you may find yourself in.

Try and compile using LUA:

The first thing you should try doing is to compile your scar script using the LUA compiler. This will ensure that any minor syntax errors that you have made will be caught before you even get into the game. This is especially important as, sometimes, if there's an error in the lua script, the game will abort loading of the script without ever warning you.

Use print to help you debug.

The print statement is probably one of the more useful commands in the scar system. As correctly placed print statements will allow you to trace the progress through the scripts, and allow you to determine if they're acting in the way you expected them to. Be careful however, since rules are called on a regular intervals a wrongly placed print statement may mean that the console will get flooded with messages from your print statement.

Check the console for errors.

The console will be your main tool for checking for scar errors as well as debugging purposes. Whenever you are given a “Fatal Scar Error”, the explanation for the error, as well as the function that caused it, the line number and the reason is displayed within the console, which you can bring up using ctrl+alt+.

Lua Watcher & Rule Profiler

The Lua Watcher and the Rules profiler are excellent debugging tools
that have been ported over from Homeworld2 and are outlined as follows.

Lua Watcher

The Lua Watcher allows you to see the variables, and associated values that are defined within the game. (in the current mission?). The Lua Watcher can be used as follows:

LCWatcher_Activate(bool on) : Activates the watcher viewing its current state.
LCWatcher_AddFilter(const char * statename, const char * filter) : Adds a filter to the watcher. Eg. A filter of “g_" will show all variables starting with “g_" and a filter of "" will show all variables.
LCWatcher_RemoveFilter(const char * statename, const char * filter) : Remove a filter previously added to a state.
LCWatcher_SelectState(const char * state) : Sets the state the watcher is currently viewing. In the case of scar, this would be “SCAR” in all capital letters.
LCWatcher_FilterExists(const char * state, const char * filter) : returns true if the filter exists in the given state.
LCWatcher_IsActive( ) : returns true if the watcher is currently being displayed.

Rules Profiler

The rules profiler is an excellent tool that can give you an idea of what rules exist, and are running, when rules that you expect to be running aren't running and if any particular rule is eating up resources, or taking longer to execute then you would expect.

RulesProfiler_Activate(bool on) : Toggles the rules profiler.
RulesProfiler_IsActive( ) : Returns true if the profiler is currently active.

Using these functions, here are several key bindings to quickly toggle these tools:

-- debug key bindings for scar profiler and scar watcher --

-- bind scar watcher --

-- show/hide the watcher.  automatically adds the showall filter for you.
toggle_scar_watcher = "LCWatcher_SelectState('SCAR'); LCWatcher_AddFilter('SCAR',''); LCWatcher_Activate(not LCWatcher_IsActive());";

-- use this to quickly add/remove the showall filter
toggle_all_vars = "if LCWatcher_FilterExists('SCAR', '') then LCWatcher_RemoveFilter('SCAR','') else LCWatcher_AddFilter('SCAR','') end";

bind("Shift+W", toggle_scar_watcher);
bind("Shift+A", toggle_all_vars);


-- bind scar profiler --
toggle_scar_profiler = "RulesProfiler_Activate(not RulesProfiler_IsActive())";

bind("Shift+P", toggle_scar_profiler);


-- nislet debug bindings --
bind("Shift+U", [[Scar_DoString("W40k_UnlockInputOnLetterBox()")]] );

You may wish the place these binding in a specific directory, for instanace Dev/ScarDebugBindings.lua. If you wish to use them you can just add the following line to your localexec.lua file: