Guide » History » Version 18

Version 17 (Squelch, 09/05/2015 08:04 PM) → Version 18/32 (Squelch, 09/06/2015 01:56 PM)

h1. Information on Support and Bug Reporting

The Kerbal Space Program Bugtracker is the place where bugs can be reported for the attention of Squad. There is a team of testers and other interested people who look through these bugs and try to assist people who have issues, as well as helping to identify when bugs need to be raised to the attention of developers.

Please keep in mind that while best endeavors are made to prevent bugs from slipping into released code they are a part of software development that is a reality. While they can be immensely frustrating when they manifest at the wrong time, do try and investigate/report them in a methodical and complete manner. The better the input in a bug report the better the chance that someone can help identify it/fix it and improve the experience for all

h2. A note on Modded Installs

As it is the place for raising issues to the Core Developers, the bugtracker is only targeted at Unmodded installations of KSP. The developers don't run modded installs and are focused on providing the most stable core experience that they can. Modders can then build on this stable foundation. Furthermore, However, Mods can introduce unwanted influences that are sometimes hard to track, even if they outwardly deal with something else unrelated. Please consider the testers and ultimately developers time in getting to the heart of the bug as quickly as possible. We therefore kindly ask that any suspected bugs are reproduced and verified in a clean game before reporting.

If you are experiencing issues with KSP and cannot replicate them in a stock install then there is a really good group on the Forum where many of the testers and modders hang out and try and help with issues on Modded Installs. Here is a link to the "Modded Support Forum":

Issues logged for modded installs that cannot be replicated will be looked at, but will likely be closed if there is not enough compelling information for a non mod induced bug to pass them to the devs for attention. A good example of this exception might be; a fault in the plugin API that can only be demonstrated by mod installation. Please do involve the mod author(s) in this if you are not one of them out of courtesy.

h2. So whats important when looking at a bug?

When investigating strange behavior and reporting a bug there are some key pieces of information that can help pinpoint where a bug may be occurring and also help others to try and replicate the behavior. try and ensure that you have as much of the following information as you can:
* *KSP version* including Windows, Mac, or Linux, 32 or 64-bit, and if it's Steam
* A *detailed explanation* of what happened and what you were trying to accomplish
* A *screenshot* of your craft or any relevant screens (or even a *video* if you are feeling demonstrative or its difficult to describe in text)
* A *.craft file or save files* if relevant
* The *ouput_log.txt or player.log* file KSP creates when it launches and, if applicable, the *crash log* KSP has generated when the program crashed (note that this is not the KSP.log file)
* A detailed list of *system specifications*
* Are you running a *clean installation*, or have you updated and some of your persistence or craft files might be older versions, *if so which version(s)*

To find out how to obtain this information, please see below:

{{collapse(KSP Version)
p((. To obtain your version, use any of the following:
* Open the "buildID.txt" file located in your installation folder. The version is listed in the first line of the file.
* Open the "readme.txt" file located in your installation folder. The version is listed just below the ASCII art in the top of the file.
* Start KSP and look in the lower right corner of the main menu screen.

p((. The KSP version will look something like "". Also list whether you're using Windows, Mac, or Linux, if it’s 32 or 64-bit, and if it's Steam. Knowing the version allows us to avoid recommending things that are not applicable to your operating system. Also, there are some issues which only turn up in specific operating systems or specific versions of KSP.

{{collapse(Screenshots / Videos)
p((. KSP is capable of taking screenshots in-game by pressing F1. The screenshots are stored in the KSP installation folder under a folder called [SCREENSHOTS].
You can upload screenshots directly to the issue using the files button, or any image sharing site

p((. Screenshots usually illustrate the problem better than trying to explain with several paragraphs. Feel free to mark up your screenshots with a noticeable colour to highlight important points. Also, avoid excessive drawing since it may end up making your problem less clear.

p((. Please attach these files directly or as a link.

p((. Video's can be very useful when trying to describe visual challenges or hard to describe situations, and sometimes you might be asked to provide one of these if people are having trouble "seeing" it for themselves. Videos can be recorded and uploaded to Youtube or a similar video sharing site, and the link added in an update. Don't worry, you don't have to speak if you don't feel you can. Annotations are generally much easier to do and see.

{{collapse(Craft & Save Files)
p((. In the KSP installation folder, you should be able to find a folder called [SAVES]. Open this folder and select the save folder name that applies. Inside you will find three things: one or more files (usually two) with a .sfs extension and a folder called [SHIPS].
* Craft Files: Any ships that you created will be stored in the [SHIPS] directory under [SPH] for Space Plane Hangar vehicles or [VAB] for Vehicle Assembly Building vehicles. Craft files are named the same as you have titled your ship in KSP and have a .craft extension.
* Save Files: To attach a save file, you need the file called persistent.sfs (or any file ending in .sfs in the [SAVES] folder - generally quicksaves, but also named saves).

p((. CRAFT NOTE: When attaching craft files, please ensure that no mods or parts are used in the creation of the craft. we won't be able to open them - see "Modded Installs":
SAVE NOTE: Using ALT+F5 to quicksave will allow you to give the save file a specific name, which can make it easier to find for uploading.

p((. Please attach these files directly or as a link.

p((. Craft files should be provided whenever you are having an issue with a specific craft, or have found a potential bug that you find easiest to reproduce with that specific craft. Having the craft file to work with will make it much quicker and simpler for us to diagnose and attempt to replicate the issue, and hopefully get it resolved much quicker.

{{collapse(Crash/Output Logs)
p((. When KSP crashes it will generate a folder with files with details surrounding the crash. Usually a window will pop up ingame asking you to send this information to the developers, along with the name of the folder. You can find this folder in the KSP install directory.

p((. If KSP doesn't crash, start KSP and cause the problem. Quit KSP and find the output_log.txt (not the KSP.log) at the location below:
* Windows: KSP_win\KSP_Data\output_log.txt -OR- KSP_win64\KSP_x64_DATA\output_log.txt (depending on which used)
- In case you installed KSP into a Windows protected directory (C:\Users, C:\Program Files or C:\Windows\ and their subfolders) the output log file may be stored in the folder called C:\Users\[Username]\Appdata, this folder is usually hidden so you should enable the view hidden folders option (more information). Note that for the demo you should find the output_log.txt file located in the KSP_Data folder.
- Steam users should right click KSP in Steam, click on Properties, then in the Properties box, click Local Files, then Browse Local Files.
* Mac OSX: Open Console, on the left side of the window there is a menu that says 'files'. Scroll down the list and find the Unity drop down, under Unity there will be Player.log Aka Files>~/Library/Logs>Unity>Player.log
* Linux: The log is written to /home/user/.config/unity3d/Squad/Kerbal Space Program/Player.log

p((. Please attach these files directly or as a link

p((. The output and crash logs are useful because they help us understand exactly what you were doing when the issue happened by providing a "play-by-play reenactment" (in text form) of your KSP session. Anything out of the ordinary will often show up in the log files, and it gives us a good idea of where to start looking for solutions.

{{collapse(System Specifications)
p((. The method to gathering system specifications will vary over different operating systems, choose which one applies to you.
* Windows: open the start menu and select (or type) 'run'. Type in 'dxdiag' and press the [ok] button. A new program will pop up called the DirectX Diagnostic Tool. On the bottom of this screen a [Save All Information] button is located. Press it and save the text file to a location you will remember.
* Mac OSX: use the "System Report" app from the 'About This Mac' menu and hit cmd+s to save the file in .rtf format in a location you will remember.
* Linux: for linux an application called 'hardinfo' will gather all required information. Save the information to a location you will remember.

p((. Please attach these files directly or as a link.

p((. Having detailed system specifications is useful in more ways than one. At a glance, we can tell if your system should be experiencing any performance issues, and whether the system is correctly registering and utilizing an installed video card, sound card, and so forth. All the hardware information for your system is contained within these files (and is extensive). As such, it's a must-have for those of us trying to diagnose and solve certain issues.

h2. Reporting that bug

The key thing about reporting a bug is being able to include enough detail in the report so that the behavior can be replicated by someone else - especially by a dev when they are looking at your submission. Anything we can do to improve the turn around on bugs is a great help in the efficiency of coding the fixes.

Below you will find an example of the format used by the QA and Exp teams to log issues during testing. We've found it a quite effective way to include all the relevant info. You'll see how the report clearly states how the bug was encountered and how it can be reproduced with as few moves as possible. It is as helpful as a bug report can be, and this helps Squad narrow down the problem.

h3. An Ideal Example

{{collapse(Ideal Example image)
{{collapse(Ideal Example Notes)
> *Subject* Controlling all Craft in Physics Range %{color:red}- A short descriptive title works best%
> %{color:red}Set the fields at the top accordingly - some are mandatory. see below for details%
> *Description:* All craft within physics range respond to control inputs. %{color:red}- A brief summary of the issue, This will be seen in the issues list.%
> *Steps to Replicate:*
> 1) Make a Mk1 pod and hold it down with a TT-18A Launch Stability Enhancer (yes, just the two parts), and launch the craft with a kerbal on board.
> 2) Hold ALT-W to push the pitch trim all the way to 7 notches nose down. (Just short of max.)
> 3) Turn on SAS (important)
> 4) Stage to release the pod to the ground, then go EVA
> 5) Walk forward with your EVA kerbal
> *Expected:* Only the Kerbal should be controlled. %{color:red}- this is optional, so no need to include obvious statements.%
> *Result/Observed:* Pod will flip over while controlling kerbal. Pod stops when kerbal stops walking.
> *Fixes/Workarounds:*
> - Zero out trim (ALT+X) on each craft within physics range.
> *Notes:*
> This behaviour may be related to issue number xxx
> Keys for controlling each vessel must be mapped the same (i.e. Walking forward for a kerbal & pitching a pod must both be ‘W’).
> - %{color:red}Files added%
> - Images Link:
> - Craft File %{color:red}if required%
> - Log File %{color:red}if required%

If you wish to format your report to make it easier to read, please refer to the "Redmine formatting page":

h3. Extra Classification

Further to the content in the body of the issue there is some extra information you can provide by categorizing the issue using some of the fields in the bug tracker. Don't be put off if you don't know what to choose, there are always helpful people around who can help triage the issue too

There are two types of Issues for reporting on the tracker that are available to use:

* *Bug*: There is something wrong with the game that you'd like to report.
* *Feedback*: Where we find opinions and balance.

p)). Pretty self-explanatory; this issue type is for behaviour you encounter that appears to be unexpected or not intended by design. If you suspect that the issue is based upon opinion it is more than likely not a bug, but feedback instead. Excessive consumption rates would be feedback, not a bug. But lack of resource consumption or incorrect displaying of consumption would be a bug.

p)). When you encounter behavior that you feel is unexpected, but perhaps not unintended, this is the issue type you would use. Generally, you should try to suggest alternate behavior that you feel would be more suitable or balanced. Well reasoned suggestions on improvements and comments on how the game plays overall are welcome here.

h3. How Priority Helps

Priorities help us to figure out which issues need inspecting, reviewing and fixing first and foremost. Thus, the priority assigned to an issue needs to be as objective as possible; not a result of how much it affected your mission or current gameplay goals, but how much it affected the game itself. If youre unsure the following table should assist you in deciding what priority to assign an issue.

{{collapse(Priority Table)
|_.Priority|_.Description|_.Example Case|
|*%{color:red}Critical%*|A large portion of the game is unplayable.|SPH is non-functional.|
|*%{color:orange}High%*|Game Breaking|Game crashes when transitioning SoI|
|*Normal*|Game Affecting, but not Game Breaking.|SAS is draining electricCharge incorrectly.|
|*Low*|Visual issue that occurs often, or Gameplay issue that can be avoided.|Landing Strip has texture artifacts.|
|*Very Low*|A visual issue that appears rarely and doesn’t affect gameplay.|Audio-related error appears in log on occasion.|
|*Unworthy*|An issue that is slightly bothersome, occurs rarely, is not easily discovered, or is a matter of preference.|Collision mesh of some parts are slightly off.|

h3. Categorizing Issues

Setting a category helps us get things to the right developer when they get to that stage. You can see the list and details on the [[TrackerCategories| Tracker Categories]] page

h2. Some Guidelines on Bug Reporting

Some helpful information and ideas to keep in mind as you are writing things up. feel free to use the headings here as reminders and come back to these for more detail if you need it:

{{collapse(One Bug = One Ticket)
p)). Each bug should have its own Issue ticket. Please try and break down your issue into smaller chunks where possible. Compound issues do arise, but each element may lay in different parts of the game. We much prefer reports for each section so they can be dealt with in isolation, but with knowledge of the connections. We are able to set relationships between issues, so please indicate in your report if you believe those connections exist.

p)). Please be sure to search for existing reports before submitting your own. Using the search button (top right) you can enter keywords separated by a space. This will return all issues that contain all or combinations of those keywords as a list. Please review these to see if they describe your particular issue. If one exists, please feel free to add extra information to it.

Many issues are related to each other, and we are constantly adding links to these so they are easier to find. Any related issues that might also describe what you see can also have pertinent information added if you feel it is missing. We welcome any suggestions on relationships you feel are missing.

If an existing report describes exactly what you see and you have nothing to add, please do add a comment about some aspect so we know how widespread the issue might be. Also check against the platform to see if it matches your own.

Advanced search allows for much finer grained results.

Any duplicate reports will be marked as such, and a link to the original added. Please also feel free to point out any duplicates.

{{collapse(Clean Installations)
p)). It's highly desirable that you can recreate the issue with a Stock Install. We appreciate that there are many game enhancing mods out there, and that you may be using them, so please also consider using a KSP install that has never had mods installed in it (as opposed to deleting mod directories).

We recommend having two KSP installations:
# Completely stock, with no mods ever installed
# Your "main" playing version of KSP with any modifications you desire.

Please note: savegames may not be interchangeable between a stock install and a modded install. Even if there are no extra parts, some game parameters may have been changed that have consequences for a stock game.

This ensures a solid report while preventing accidental damage to your main save games when replicating bugs.

{{collapse(Steps to Replicate)
p)). Try to keep it simple, stating facts in as clean and concise a manner as possible.

p)). For Squad to find a bug, they need a way to consistently cause it to happen in a mod-free, clean install of the game, and using a completely new spacecraft (when possible). If at all possible, try to find the minimal set of actions that will cause a bug to happen. That can be extremely helpful to narrow down the source of the problem. If the bug can only be reproduced with a specific spacecraft design, please include a .craft file of the simplest design where the issue still happens in your report.

p)). Remember, steps to reproduce the issue help the most. Bug reports like "'I've seen this happen, and it ruined my mission attempt" don't help replicate the issue. They just state it happened, but it doesn't help find the source of the problem. On the other hand, extremely detailed reports of what was happening when the bug took place are also a bad idea because it's difficult to dig through a wall of text to figure out what happened.

{{collapse(Fixes / Workarounds)
p)). If you found a way to fix the problem in the short term, please post how. This can help out other people who are having the problem, and also allows the bug squashers to focus their efforts.

{{collapse(File attachments)
p((. You can upload files directly to the issue tracker subject to a maximum file size of 5Mb. If your files (say the crash report folder) exceeds this size, please use any file sharing site (such as Dropbox, Mediafire or File2web). Images can be hosted on imgur which is free to use and allows albums to be built. These sites will give you a link you can include in your posts to share your files.


h2. What Happens Next?

To read a little bit more about what happens after a bug is submitted you can check out the [[WhatHappensNext|How Bug Reports are Managed - i.e. What Happens Next]] page

*Follow ups:* Please check your report for replies as very often you may be asked for more information or clarification. Any new discoveries you make after posting are always welcome.


h1. Other Support Resources

You will also find a lot of good support resources on the Official forum in the sub forums below:
* "Unmodded Support Forum": - interact with other KSP users to work on questions or get help with bugs
* "Modded Support Forum": - a really good group on the Forum where many of the testers and modders hang out and try and help with issues on Modded Installs
* "Known Issues and Self Help": - Forum thread of known items that can save you a lot of time