Script debug - offline

The basic concept of the offline debugging is to create a debug log while playing and analyze it afterwards.

Wrong side? Go back to [Script debug].

Record

First, start the game with parameter '-d'. (When you installed the game on a windows system, there should be a Link named 'SpaceCombat Debug' in the start menu.) This starts the game in Debug mode with the debug menu.

You should see this screen.

Now click on the 'Debug' button and enter the script debug screen. Next, exit this screen by pressing 'ESC' or click on 'Exit'. This enables the recording of the debug log file.

Now you can run a mission, load a saved game, start a campaign and so on.
Select the file to run with the 'Browse scenario' button and then click the button for game/Load/Campaign...

Now, the mission runs and all scrip actions are recorded to a file ('debugLog.dat'). You should quickly do the actions, you want to debug, because the file grows rapidly. To finish the record, simply exit the game.

Now you have a record file of all script actions.

Analyze

Again, start the game with parameter '-d' and click on 'Debug' to open the script debug screen.

Here are some basics of the scrip debug screen described: [Script debug basics]

Right click on the script window to open it's context menu. Select 'Load log file' to load the file 'debugLod.dat'. (You may also hit CTRL+L to load the log file.)

Now the windows are filled with data.

Note, you may decode a debug log file to plain text. Then, you are able to check the data in a simple text editor. To do this, open the context menu (when a log file has been loaded), and select 'Decode log file to text'. Then, a text file 'debugLog.txt' is created. Be warned, these files are getting huge. Not all text editor may open them.

Now let's have a look at the debug windows.

Time slider

The time slider is the wide window in the middle. You can move through the log file by moving the slider.

Script window

On the left side is the script window. After loading a log file, it should show a script file.

You see the script file name in the header of the window. There is some high lighting of the script file:

• XML tags are light green
• XML comments are green
• Action and condition functions are blue
• Everythign else is white

When you move the mouse cursor over a action/condition function, the function gets a violett background color. When you now open the context menu (right click), there are some options for the selected function (e.g. set breakpoint). Active breakpoints are shown with a dark red background color of the function. The current step position is indicated by a red background color of the function.

Breakpoints

Right click on a function to open the context menu and select 'Set breakpoint' to create a breakpoint here. (You can remove this breakpoint with the context menu too.) After setting all breakpoints, you can click on the 'Continue' button on the left lower side. Now the debugger scans through the log file (starting at the current position) and stops at the next breakpoint (or at the end of the recording).

Conditional breakpoints

Right click on a function to open the context menu and select 'Set conditional breakpoint' to create a conditional breakpoint here. (You can remove this breakpoint with the context menu too.) This dialog will appear:

Here you can set several options for the breakpoint.

You may restrict the breakpoint to a special object in the mission. This is useful, when several object have the same AI script, but you want to debug only one of them. Set the checkbox and enter the objects name (exact spelling, case sensitive). You may also click the 'Scan' button. Then, the log file is scanned for all object names and you can select one of them (so you avoid spelling errors).

You can also restrict the breakpoint to a section. Assume you have a campaign with several missions. In each of them is an object, that has the same AI script. Now, you want to have the breakpoint active in mission 3 only. So, simply restrict the breakpoint to mission 3. Set the checkbox, click the 'Scan' button and select the section.

Finally, you may also restrict the breakpoint to a defined time span. Set start and/or end time stamp. Leave the boxes empty for no limit.

You may set more than one restriction at the same time. So, you can set a breakpoint, that is restricted to a defined object AND is only active in a defined section.

After setting all breakpoints, you can click on the 'Continue' button on the left lower side. Now the debugger scans through the log file (starting at the current position) and stops at the next breakpoint, that matches the defined condition (or at the end of the recording).

Variable window

The variable window is on the right side of the screen.

All known variables are shown here. Note, the value of most variables is unknown in offline mode.
(This window is more useful in the online mode.)

The debugger checks the last and the next 200 entries from the current position for informations on variables. When there are variables set to a value in the past, these values are shown in the variable window. When variables are set in the future, the windows shows the variable name and '???' as value.

When you step (by clicking on the 'Step' button on the lower right side), old values are shown in white and new values are shown in red.

When you select a variable in the variable window and right click on it to open it's context menu, you can copy it's value to the clipboard. This is useful, when you have a long string in the variable and want to copy it to a text editor. (Hint: This feature is more useful, when you run the game in window mode and not in full screen mode.)

Watchpoints

You may also set a watchpoint in the context menu of the variable window. Watchpoints are like breakpoints (they stop the execution of the script). They work not on a function but on a variable. Open the context menu of the variable window.

In this dialog you can select the options for the watchpoint.

When you created the context menu on a variable, then the name is set in the dialog already. Otherwise you have to enter the variable name. You may also click the 'Scan' button to scan the whole log file and select a variable from the list.

You may select several options for the watchpoint. Should it break on every change of the variable? Or should it break, when the value meets a defined condition. You may also restrict the watchpoint to a defined object. This is useful, when you have several objects with the same AI script (and therefore the same variables).

After setting all watchpoints, you can click on the 'Continue' button on the left lower side. Now the debugger scans through the log file (starting at the current position) and stops at the next watchpoint, that matches the defined condition (or at the end of the recording).

Log window

Finally, there is the log window at the bottom of the screen.

The log window shows the last and the next 200 entries in the log file from the current position. You can change the current position with the time slider or by clicking on a line in the log window. The current position is high lighted in the log window.

Lines to action and condition function are black in the log window. Additional informations are gray. The start and end of a section is red and new time stamps are green.

There are several 'find' options in the context menu of the log file. You can find the next error (e.g. read access to a variable, that has not been set), the next message (output to the player, e.g. Area enter message), the next time stamp or a specified section.

You can set a filter for the log too. A manual filter is defined by a start and an end. Only the log entries between them are shown. You can also filter by a section. In this case, only the log entries of the selected section are show. This is very useful, when you only want to debug game events or a single AI set.