This page gives instructions for reporting and troubleshooting the game's errors and crashes.

= Reporting Errors =

There are currently two ways to file a bug report:
 * The preferred method is to [http://trac.wildfiregames.com/register register] here on Trac and create a [http://trac.wildfiregames.com/newticket new ticket]. You will be notified of replies or status changes on the ticket. Attach any files that might be useful (logs, crash dumps, etc. - see GameDataPaths). '''To avoid duplicate reports, search Trac or the [http://trac.wildfiregames.com/report/3 ticket report].'''
 * Or you can create a [https://wildfiregames.com/forum/index.php?/forum/378-bug-reports/&do=add new topic] in the [https://wildfiregames.com/forum/index.php?/forum/378-bug-reports/ Bug Reports forum].

= Out-Of-Sync (OOS) =
An out-of-sync error occurs when different players of a multiplayer game compute different matchstates.
This typically results in players seeing other players units as idle for the rest of the match.

[[Image(screenshot_oos.jpg, 400px)]]

If you witness such an error, please take the following actions:

1. Ask one of the players that is out-of-sync and one of the players that is not out-of-sync to upload the logfiles.
 * replay of the match: `commands.txt`
 * logfiles `oos_dump.txt`, `oos_dump.dat`, `mainlog.html`

 The paths are mentioned in the error message, alternatively see wiki:GameDataPaths.
2. File a bugreport and attach the files (typically as a zip archive).

= Crashes =

A crash is a serious problem which causes the game to stop, most of the time you can't continue playing after a crash (even if you ''can'' continue, the crash should be reported). The game should notify the user on a crash. There are many potential causes of a crash, some are easy to find and others are more difficult. In any case, we need as much information as possible to troubleshoot it.

The exact procedure to debug and report a crash depends on your OS:

== Windows ==

On Windows the game will display a Program Error window such as the following:

[[Image(Windows-Program-Error.png)]]

and generate crashlog files in the game logs location, see GameDataPaths. The crash dump contains a call stack, which is the state of the program at the time it crashed, this is the most useful info for troubleshooting. There is also a text file with errors that were logged and basic info on the user's system (OS, driver versions, CPU, etc.) Only the most recent crashlog is saved, so it's best to report the crash as soon as it occurs.

Attach the crashlog files to your bug report. If you'd like to try debugging the error yourself, see DebuggingOnWindows.

If the game crashes early (before the main menu is displayed), it may not be able to create crashlog files or error logs. In this case it's useful to read the debug output from the game's startup which is normally not visible, using Microsoft's free [http://technet.microsoft.com/en-us/sysinternals/bb896647 DebugView] utility.

== OS X ==

On OS X a crashing app will produce a problem report, first you will see a window like this:

[[Image(OSX-Quit-Unexpectedly.png)]]

Choose "Report..." to view the report data including call stack:

[[Image(OSX-Problem-Report.png)]]

Copy and paste the full contents of the log into your bug report. Don't send the report to Apple since there is probably nothing they can do about it.

== Linux ==

On Linux and other Unix-like OSes, sometimes you will see a message window like the following after a crash:

[[Image(Ubuntu-Error-Message.png)]]

or if run from the terminal you may see a call stack and the following options:

`(C)ontinue, (S)uppress, (B)reak, Launch (D)ebugger, or (E)xit?`

This call stack is generally not very useful as symbols are not loaded, so choose the "Debugger" option to open GDB. At the `(gdb)` prompt, type `thread apply all bt full` (for a trace of all threads, or `bt full` for only the crashing thread) to get the call stack, then copy-and-paste the results into your bug report.

If you get a "Segmentation fault" instead and no debug options, you'll need to know how to reproduce the crash, then run the game in GDB:
{{{
cd binaries/system
gdb pyrogenesis
(gdb) run
... crash!
(gdb) thread apply all bt full
}}}

= Errors =

An error is when the game notifies the user that something bad happened, they are typically both logged and displayed as messages in the game window:

[[Image(ErrorAndWarning.png)]]

The game will continue after most errors, but they may trigger more errors. Errors are often caught by the developers but sometimes they sneak into the Alpha releases. To report the exact messages, open `interestinglog.html` in your web browser and copy the contents into your bug report. The location of the logs varies by OS, see GameDataPaths.

A screenshot of the message is less desirable as compression and scaling artifacts obscure the text, and you may not see all the errors. It's very useful if you can remember the steps to reproduce the error.

= Freezes =

A freeze is when the game completely stops responding and no feedback is given to the user. This is less common than crashes and errors. Freezes are more difficult to troubleshoot as there may be no error displayed or logged. One thing you can do is start the game in a debugger. The procedure varies by your OS:
 * Windows: Visual Studio or WinDbg (see DebuggingOnWindows)
 * Linux: gdb
 * OS X: gdb or Xcode

When the freeze occurs, use the break command in the debugger and find the call stack. This can provide clues as to what may be happening, also check the logs for errors. Copy all of this info into your bug report.