Testing

From Unvanquished
Jump to: navigation, search

Saving console output

To capture console output to a single file, you must redirect stderr into stdout.

On Unix systems, this is done as follows:

$ ./daemon options > outputFile 2>&1

Debugging

To create a debug build, change CMAKE_BUILD_TYPE in CMake from Release to Debug, then compile.

You may find it necessary to set in_nograb to 1 to disable pointer grabbing so that you may use your debugger.

Debugging with gdb

Start gdb as follows:

$ gdb --args ./daemon.i386 +set in_nograb 1

The in_nograb argument is not strictly necessary but stops Daemon from grabbing the mouse pointer, which may be necessary for debugging.

If the program segfaults, a backtrace is very useful to the developers in determining the source of the problem. At the debugger prompt, type bt:

(gdb) bt

Debugging with Xcode

With Xcode 4, even if you did not build the game with Xcode, you may still use its facilities for debugging.

  1. Open any project. If necessary, create a new one. It may contain anything.
  2. Click "Product" on the menu bar and navigate to "Attach to Process". Look for "daemon.i386" listed under "Applications".

After a moment, the application will be ready for debugging.

See the Xcode 4 User Guide for more information.

Static Analysis

What is static analysis?

Static code analysis is a technique to identify potential faults and vulnerabilities in software without actually running the code. Static analysis software will examine the code itself to identify possible problem locations, then work backwards to identify how those could be reached. John Carmack, founder of id Software, has written an article detailing the benefits of the technique.

Xcode

To use Xcode 4 to perform static analysis of the code, first follow the Xcode compilation instructions, then in Xcode, select "Analyze". The process will take considerably longer than just compiling the source, so be patient.

Starting a testing session

Start the game, and enter the following commands:

\sv_pure 0
\devmap map name

You may also load a map with the regular \map command. Be aware, however, that devmap enables cheats which can make it easier to test (such as being able to jump directly to stage 2 or 3 if required). Also note that with devmap, the build time for buildables is zero, so the building animation(s) will not play.

Debugging Graphics

GPU PerfStudio 2

PerfStudio 2 is a proprietary GPU debugger created by AMD that runs on Windows 7 or newer.

apitrace

apitrace is an open-source tool that records every graphics API call made by an application. After the application has closed, you can step through individual calls to the graphics API, allowing you to

  • see the result exactly as it would appear following each call,
  • see graphs of API usage, and
  • inspect buffers.

Linux users can compile it from source:

$ git clone git://github.com/apitrace/apitrace.git

As the graphical user interface does not provide a mechanism of selecting which directory to run in, and the Daemon engine requires that you run in the correct directory, you will have to cd into your game directory and run apitrace from there.

Windows users can download a build.

gDEBugger

gDEBugger is a handy tool for debugging graphics problems and profiling available as freeware. While it was formerly available for Mac OS X, Windows, and Linux, the original developer, Graphic Remedy, has since been acquired by AMD, and the download link for Mac OS X is no longer visible on their site. However, the download link still functions.

The 5.8 series of the software is available from Graphic Remedy:

Operating System Architecture Version Download link
Linux 32-bit 5.8 Via download portal (direct link)
64-bit 5.8.1 Via download portal (direct link)
Mac OS X Unsure 5.8 Via download portal (direct link)
Windows Unsure 5.8.1 Via download portal (direct link)

The 32-bit Linux and Mac OS versions of the software (5.8) still require generating a license; version 5.8.1 (only available for Windows and 64-bit Linux) does not. At the time of writing, attempting to generate a license fails with an internal server error.

The newer version, from AMD, is available from their site and does not require a license.

Some users report that 5.8 is in some ways better. Mac users have no choice as to which version they use, unfortunately.

Using the software

Linux users with ATI cards and the proprietary Catalyst driver will have to disable signal blocking before using the application:

$ sudo aticonfig --sb off

Restarting X will also be necessary.

General Tips

Miscellaneous

  • To stress test the engine's ability to display a large number of buildables, set g_humanBuildPoints or g_alienBuildPoints to as high as you wish; this will allow you to build as much as you please.
  • To determine what file was loaded for a particular asset (e.g., to determine if files are being read from a particular .pk3 archive), use the \which command with the relative path to the asset as an argument, such as \which models/buildables/acid_tube/acid_tube.md5mesh. Note that which accepts both forward- and backslashes regardless of platform.

Working with packages

To combine all packages together, at a Bash shell:

$ cd data directory/main; mkdir tmp; for pk3 in pak{{0..9},A}.pk3; do unzip -o $pk3 -d tmp; done

(If there are additional pak* files (e.g., pakB.pk3), edit the pattern accordingly (e.g., to pak{{0..9},{A..B}}.pk3.)

This will place the cumulative contents (i.e., as the engine would see them) of all the pak*.pk3 archives into a new tmp/ directory in your data directory.

Viewing Runtime Information

The engine and game logic provide a number of commands for viewing information about its current state.

Common Engine Functionality

  • developer — Set this to a true value (e.g., 1) to enable displaying debugging information and the like.
  • fs_debug — Set this to a true value (e.g., 1) to enable filesystem debugging.
  • meminfo — Display current memory usage.
  • fs_referencedList
  • fs_openedList — List currently open files.

Renderer

  • fbolist — List all frame buffer objects.
  • vbolist — List all vertex buffer objects.

Gamelogic

  • entityList


Shaders & Textures

Querying loaded data

The command imagelist can be used to output a list of all loaded image files. This command does not support sorting output.

The command shaderlist can be used to output a list of all shaders. shaderlist accepts an optional parameter that will filter results by matching against the shader name, starting from the beginning. An example of output from shaderlist follows:

]\shaderlist texture
-----------------------
1 3D_S                  SS_OPAQUE           IA : textures/arachnid2/e6dmetal
1 3D_S                  SS_OPAQUE           IA : textures/arachnid2/dark_metal
1 3D_S                  SS_OPAQUE           IA : textures/arachnid2/cement_1_gunky
1 3D_S                  SS_OPAQUE           IA : textures/arachnid2/cement_1_clean

Information 48x48.png

Developer Note

This information may be safely disregarded by mappers and artists.
The output of shaderlist is generated by R_ShaderList_f(), which may be found in src/engine/rendererGL/tr_shader.c.

The columns output by shaderlist are as follows:

  1. The number of stages the shader has.
  2. One of the following:
    • 2D
    • 3D_D
    • 3D_S
    • ATTN
  3. One of the following:
    • An empty space.
    • lighting_DB
    • lighting_DBS
    • reflection_CB
  4. One of the following:
    • An empty space.
    • G
    • E
  5. One of the following:
    • An empty space.
    • SS_ALMOST_NEAREST
    • SS_BAD
    • SS_BANNER
    • SS_BLEND0
    • SS_BLEND1
    • SS_BLEND2
    • SS_BLEND3
    • SS_BLEND6
    • SS_CLOSE
    • SS_DECAL
    • SS_ENVIRONMENT_FOG
    • SS_ENVIRONMENT_NOFOG
    • SS_FAR
    • SS_FOG
    • SS_MEDIUM
    • SS_NEAREST
    • SS_OPAQUE
    • SS_PORTAL
    • SS_POST_PROCESS
    • SS_SEE_THROUGH
    • SS_UNDERWATER
    • SS_WATER
  6. One of the following:
    • An empty space.
    • IA
  7. The shader name. The text "(DEFAULTED)" will be appended to the shader name if it cannot be found.

Testing maps

  • To fly around the map, use the \noclip command. If you find that you are moving too slowly (or too fast), you may change the speed with cg_flySpeed.
  • To make yourself invincible, use the \god command.
  • To stop buildables from attacking, use the \notarget command.
  • To publicly test your maps, make a thread on forums to share your work-in-progress work and some server admins will probably host it ;-).
  • To lock the state of PVS, set r_lockpvs to 1. Be aware of the difference between this and r_novis: this disables any updates to the state of the PVS buffer but PVS is still in effect; this can make flying outside of a map difficult.
  • To disable PVS entirely, set r_novis to 1.
  • To disable PVS for entities, set sv_novis to 1.

Information 48x48.png

Developer Note

The reason that enabling/disabling PVS for entities is controlled with a separate cvar from the world is that the server is responsible for determining when to send information about entities to the client. The server considers two things:

  • if the entity is within radar range of the player, and
  • if the entity is potentially visible to the player.

The server will send the position of an entity if it meets one or both of these conditions.

Testing models

You may test models one of two ways: either by using the gameplay code to cause that model to appear (i.e., by playing the game), or by commanding the game to load an arbitrary model.

Using testmodel

The testmodel command accepts a single parameter, which is the path to the model that you would like to test. Provided that it can locate the model, it will spawn it 100 units in front of whichever direction you are currently facing.

Using testgun

The testgun command will replace the currently held weapon with the requested model. The model may be positioned on screen as follows:

  • cg_gunX — The x-position of the weapon. The positive x-axis extends away from the view.
  • cg_gunY — The y-position of the weapon. The positive y-axis extends to the left.
  • cg_gunZ — The z-position of the weapon. The positive z-axis extends upward.

The model will not be animated, but the current frame of animation may be controlled with nextframe and prevframe.

Weapon skins may be tested using nextskin and prevskin.

Testing with gameplay code

  • If the model is a buildable, weapon, or player model that is not immediately available (i.e., not available until a later stage), you can change the stage with g_alienStage or g_humanStage. Both of these cvars accept a single parameter, which is the zero-based index of the stage; to skip to stage 2, use 1 as a parameter, and to skip to stage 2, use 2 as a parameter (stage 1 is 0).
  • If you do not have sufficient credits to purchase an item model you wish to test, or evos to evolve to the desired class, you may give yourself the maximum amount that you can carry with \give all.

Tips

  • To visually inpsect a model's bounding box, which is set by its configuration file, set cg_drawBBox to 1.
  • To visually inspect the bone structure of a MD5 model, set r_showSkeleton to 1. Note: at present there is a bug that causes bones to be displayed incorrectly. See Issue #2 on GitHub for more information.
  • To hide map geometry, set r_drawworld to 0. Note that with this set to 0, PVS will still be in effect, so it might still be difficult to view your model.

Preparing for a release

As a release date approaches, please remember to test the following:

Renderers

XReal ("GL3") renderer

  • Test MD5 animation blending.

Vanilla ("GL") renderer

Both

  • Ensure that gamma control (r_gamma) functions correctly.

Gameplay/UI

  • Purchase weapons and ensure that HUD icons appear correct.

Reporting bugs

Please see the bug reporting page.