Reporting Problem: Difference between revisions

From The DarkMod Wiki
Jump to navigationJump to search
(Added some new ways to get viewpos coordinates.)
 
(14 intermediate revisions by 2 users not shown)
Line 1: Line 1:
== Introduction ==
If TDM does not work properly for you, the best thing to do would be to report the problem.
Doesnt run TDM on your system, when your start TDM and get errors.
There are several ways to analyse these problems.


== Creating Logs ==
You are welcome to post in Tech Support section of the [[The_Dark_Mod#Dark_Mod_Forums|forums]], even if you suspect the problem is with your machine or you want to get some help/clarifications.
one of the ways are creating Logs.
When there is clearly a problem with TDM itself, an issue is usually created in the [[The_Dark_Mod#Bugtracker|bugtracker]].
TDM places a logfile in his application folder, named darkmod.log.
But since the bugtracker is a rather technical place, it is more advised to report problems in the forum.
This plaintext textfile can be opened with your favorite texteditor.
Sooner or later someone will create the issue anyway if it is really needed.


To create a log, open your command prompt (terminal, etc) and navigate to your darkmod folder.
This article describes some general information typically requested from everyone who reports a problem.
From there, call your call tdm executable with several arguments.
    tdmexecutable +<argument>
(for the following examples, we use the tdm-executable for windows)


To start tdm, create a log named, mylog.txt, and quit tdm.
== Baseline ==
    tdm.exe +condump mylog.txt +quit


For videoproblems: start tdm, ask for grapicsinfo, save to log and quit
This pieces of information are almost mandatory:
    tdm.exe +gfxinfo +condump mylog.txt +quit


For starting a mission:
# Contents of <tt>darkmod.cfg</tt>.
start tdm, install a mission (for example trainingsmission and quit.  
# Contents of game console at some moment (known as "condump").
    tdm.exe +map training_mission +condump mylog2.txt +quit
# In case of graphical issue, a screenshot showing the problem is often needed.
 
You can omit this information when writing a post on the forums: maybe your issue is trivial and someone will quickly explain what's wrong.
If it is not obvious, then you will soon be asked for it anyway =)
 
However, when creating an issue on the bugtracker, it is highly desirable to include all of these things, as well as the steps to reproduce.
 
=== darkmod.cfg ===
 
The file named <tt>darkmod.cfg</tt> should be located in the root directory of TDM installation.
If in doubt, you can locate this directory by checking what executable is run when you start the game: it is in the same directory.
Let's assume for the rest of the article that root directory is <tt>C:\games\thedarkmod</tt>
 
This file stores the values of all switches and tweaks that player can change.
The game may work in completely different ways depending on these values, thus they are very important for reproducing the problem.
 
When reporting the problem on forums, you can do one of:
* Attach it to a forum post. In this case rename it to something like <tt>darkmod_cfg.txt</tt>, the forum forbids anything except txt files.
* Copy/paste the full contents of the file into the post. In this case, please wrap it into "spoiler" tag, so that readers don't have to always scroll across the 5 pages of it.
 
When reporting on bugtracker, just attach the <tt>darkmod.cfg</tt> file to the issue.
 
=== condump ===
 
The term "condump" means all the text written to the game console.
You can usually open game console by pressing either Tilde(~) key or Ctrl+Alt+Tilde combo.
 
There are two ways to save the contents of game console into a file:
 
:'''1) condump.''' Open game console, type the following and hit Enter: <tt>condump unwrap my_nasty_issue</tt>
:Then find file named <tt>my_nasty_issue.txt</tt> in <tt>C:\games\thedarkmod</tt> (root TDM directory).
:Note: execute the command soon after the issue manifests itself.
 
:'''2) logfile.''' Open file <tt>darkmod.cfg</tt> in text editor.
:Find or create new line containing: <tt>seta logFile "?"</tt>
:Instead of the question mark, set digit 2 if you experience a crash. Otherwise digit 1 is also OK.
:Save the file, start TDM and reproduce the issue.
:Now find the file named <tt>qconsole.log</tt> in the directory of the currently installed FM, for instance in <tt>C:\games\thedarkmod\fms\newjob</tt>.
 
The first approach is better, but it is useless if TDM crashes or you cannot even get into game console.
In any of these cases, use the second approach.
 
When you have got the file, add it to your report just as you did with <tt>darkmod.cfg</tt>.
 
=== Screenshot ===
 
If something looks wrong for you, posting screenshot is a good thing to do.
Otherwise, the guy who tries to reproduce your issue and fails will have hard time guessing if he sees the same picture as you.
You can of course try to explain what you see with words, but it is vague and subjective.
 
There are two ways to get a screenshot:
# Press a key in-game (F12 by default). Then find the screenshot in <tt>C:\games\thedarkmod\screenshots</tt>
# Ensure that you run game in Windowed mode. Press Print-Screen key to copy screen to clipboard. Start Paint and paste (Ctrl+V) it there. Trim the TDM window in it and save.
The first approach is preferred, but sometimes it fails to capture the glitch.
 
When you want to share a picture on the forums, you can do one of:
* Add it as attachment to your forum post.
* Upload it to some free image hosting, and insert a link to it (click on Image icon) into the post. Surround the link/picture in spoiler tag (unless it is low-resolution) !
 
When reporting on bugtracker, simply attach the file to the issue and mention it somewhere in the text.
 
=== Coordinates ===
 
Typically, a problem happens in-game on at least one of the released fan missions. In such case, please write the name of the FM and the world coordinates where the problem happens.
 
In order to find world coordinates, execute <tt>getviewpos</tt> in the game console.
The coordinates will be printed in response: the first three are the coordinates, and the last three are the viewing angles. Copy them all to your report.
Since you cannot copy text directly from the game console, use [[Reporting Problem#condump|one of the methods described above to get a condump]].
In fact, it is a good idea to run <tt>getviewpos</tt> just before creating a condump.
By the way, you can execute <tt>setviewpos</tt> with these six arguments to teleport yourself to this specific location, e.g. to ensure that you have copied coords correctly.
 
Alternatively, you can set <tt>tdm_show_viewpos 1</tt> to display current coordinates on screen, so that they can be captured in screenshot.
Or you can call command <tt>screenshot_viewpos</tt> to make a special screenshot with coordinates visible on it.
 
== Advanced ==
 
Here are few more advanced tricks which may help debugging issues.
 
=== Crashdump ===
 
When TDM crashes, you can record a "memory dump" or "crash dump" of it.
It often contains information invaluable for coders, but it is only useful for debugging crashes.
 
The article [[Save a Memory Dump for debugging Crashes]] explains in detail how to record it.
 
=== Video ===
 
Some graphical issues are very obvious in dynamics, but when you take a still screenshot, it does not capture the tragedy well enough.
 
In such case you can record a video of the problem.
[https://obsproject.com/ Open Broadcast Software] is a free program which can easily record a high-quality and high-FPS game footage.
The program is quite complicated, but the main thing you need is to add a "source": either "Game Capture", or "Window Capture", or "Screen Capture".
 
When you have a video, you can either upload it to video hosting (like YouTube) and post a link, or upload it to cloud storage (like Google Drive) and post a shared link.
If you copy/paste a link to YouTube video into a forum post, the forum will show embedded player automatically.
 
=== Installation state ===
 
Sometimes there is a chance that your TDM installation is corrupt.
In such case it is great to give people a brief overview of it.<br>
Like generating a filelist of the gamefolder.<br>
<br>
To create a filelisting of the TDM gamefolder, in windows 10<br>
 
# Open file explorer, navigate to the tdm gamefolder.
# click "file" (menu) > "open in powershell" and a blue window will appear.
# Fill in the following command line in that window and hit the enter-key: dir /s > mytmdfolderandfiles.txt<br>This command generate a textfile in your gamefolder.
# the content of this file mytmdfolderandfiles.txt you can give to people for research.
After this, just run the TDM installer to download the original files.
 
'''TODO''': write some simple way to get good textual representation of TDM installation directory.

Latest revision as of 19:14, 29 January 2024

If TDM does not work properly for you, the best thing to do would be to report the problem.

You are welcome to post in Tech Support section of the forums, even if you suspect the problem is with your machine or you want to get some help/clarifications. When there is clearly a problem with TDM itself, an issue is usually created in the bugtracker. But since the bugtracker is a rather technical place, it is more advised to report problems in the forum. Sooner or later someone will create the issue anyway if it is really needed.

This article describes some general information typically requested from everyone who reports a problem.

Baseline

This pieces of information are almost mandatory:

  1. Contents of darkmod.cfg.
  2. Contents of game console at some moment (known as "condump").
  3. In case of graphical issue, a screenshot showing the problem is often needed.

You can omit this information when writing a post on the forums: maybe your issue is trivial and someone will quickly explain what's wrong. If it is not obvious, then you will soon be asked for it anyway =)

However, when creating an issue on the bugtracker, it is highly desirable to include all of these things, as well as the steps to reproduce.

darkmod.cfg

The file named darkmod.cfg should be located in the root directory of TDM installation. If in doubt, you can locate this directory by checking what executable is run when you start the game: it is in the same directory. Let's assume for the rest of the article that root directory is C:\games\thedarkmod

This file stores the values of all switches and tweaks that player can change. The game may work in completely different ways depending on these values, thus they are very important for reproducing the problem.

When reporting the problem on forums, you can do one of:

  • Attach it to a forum post. In this case rename it to something like darkmod_cfg.txt, the forum forbids anything except txt files.
  • Copy/paste the full contents of the file into the post. In this case, please wrap it into "spoiler" tag, so that readers don't have to always scroll across the 5 pages of it.

When reporting on bugtracker, just attach the darkmod.cfg file to the issue.

condump

The term "condump" means all the text written to the game console. You can usually open game console by pressing either Tilde(~) key or Ctrl+Alt+Tilde combo.

There are two ways to save the contents of game console into a file:

1) condump. Open game console, type the following and hit Enter: condump unwrap my_nasty_issue
Then find file named my_nasty_issue.txt in C:\games\thedarkmod (root TDM directory).
Note: execute the command soon after the issue manifests itself.
2) logfile. Open file darkmod.cfg in text editor.
Find or create new line containing: seta logFile "?"
Instead of the question mark, set digit 2 if you experience a crash. Otherwise digit 1 is also OK.
Save the file, start TDM and reproduce the issue.
Now find the file named qconsole.log in the directory of the currently installed FM, for instance in C:\games\thedarkmod\fms\newjob.

The first approach is better, but it is useless if TDM crashes or you cannot even get into game console. In any of these cases, use the second approach.

When you have got the file, add it to your report just as you did with darkmod.cfg.

Screenshot

If something looks wrong for you, posting screenshot is a good thing to do. Otherwise, the guy who tries to reproduce your issue and fails will have hard time guessing if he sees the same picture as you. You can of course try to explain what you see with words, but it is vague and subjective.

There are two ways to get a screenshot:

  1. Press a key in-game (F12 by default). Then find the screenshot in C:\games\thedarkmod\screenshots
  2. Ensure that you run game in Windowed mode. Press Print-Screen key to copy screen to clipboard. Start Paint and paste (Ctrl+V) it there. Trim the TDM window in it and save.

The first approach is preferred, but sometimes it fails to capture the glitch.

When you want to share a picture on the forums, you can do one of:

  • Add it as attachment to your forum post.
  • Upload it to some free image hosting, and insert a link to it (click on Image icon) into the post. Surround the link/picture in spoiler tag (unless it is low-resolution) !

When reporting on bugtracker, simply attach the file to the issue and mention it somewhere in the text.

Coordinates

Typically, a problem happens in-game on at least one of the released fan missions. In such case, please write the name of the FM and the world coordinates where the problem happens.

In order to find world coordinates, execute getviewpos in the game console. The coordinates will be printed in response: the first three are the coordinates, and the last three are the viewing angles. Copy them all to your report. Since you cannot copy text directly from the game console, use one of the methods described above to get a condump. In fact, it is a good idea to run getviewpos just before creating a condump. By the way, you can execute setviewpos with these six arguments to teleport yourself to this specific location, e.g. to ensure that you have copied coords correctly.

Alternatively, you can set tdm_show_viewpos 1 to display current coordinates on screen, so that they can be captured in screenshot. Or you can call command screenshot_viewpos to make a special screenshot with coordinates visible on it.

Advanced

Here are few more advanced tricks which may help debugging issues.

Crashdump

When TDM crashes, you can record a "memory dump" or "crash dump" of it. It often contains information invaluable for coders, but it is only useful for debugging crashes.

The article Save a Memory Dump for debugging Crashes explains in detail how to record it.

Video

Some graphical issues are very obvious in dynamics, but when you take a still screenshot, it does not capture the tragedy well enough.

In such case you can record a video of the problem. Open Broadcast Software is a free program which can easily record a high-quality and high-FPS game footage. The program is quite complicated, but the main thing you need is to add a "source": either "Game Capture", or "Window Capture", or "Screen Capture".

When you have a video, you can either upload it to video hosting (like YouTube) and post a link, or upload it to cloud storage (like Google Drive) and post a shared link. If you copy/paste a link to YouTube video into a forum post, the forum will show embedded player automatically.

Installation state

Sometimes there is a chance that your TDM installation is corrupt. In such case it is great to give people a brief overview of it.
Like generating a filelist of the gamefolder.

To create a filelisting of the TDM gamefolder, in windows 10

  1. Open file explorer, navigate to the tdm gamefolder.
  2. click "file" (menu) > "open in powershell" and a blue window will appear.
  3. Fill in the following command line in that window and hit the enter-key: dir /s > mytmdfolderandfiles.txt
    This command generate a textfile in your gamefolder.
  4. the content of this file mytmdfolderandfiles.txt you can give to people for research.

After this, just run the TDM installer to download the original files.

TODO: write some simple way to get good textual representation of TDM installation directory.