1 files changed, 74 insertions, 0 deletions
diff --git a/doc/devel/debug b/doc/devel/debug
new file mode 100644
index 0000000..22be628
--- /dev/null
+++ b/doc/devel/debug
@@ -0,0 +1,74 @@
+The file src/sc2code/uqmdebug.c and src/sc2code/uqmdebug.h contain various
+debugging functions, which are included in the binary when the game
+is built in debug mode.
+These functions can be called from anywhere in the code, though some
+require the game to be in a specific state.
+The function debugKeyPressed() in uqmdebug.c is called when the debug key
+is pressed. This function is a suitable place to put various debugging
+calls.
+There are also global variables 'debugHook' and 'doInputDebugHook',
+which can be set to a function to be called from the Starcon2Main thread.
+If if is set, 'debugHook' is called the next iteration of the main game loop
+(which will occur when the current activity (IP, HyperSpace, Communication,
+Battle) changes. The game will be in a well defined state here.
+If 'doInputDebugHook' is set, the function it is set to is called from
+doInput(), which is called all throughout the game.
+By setting one of these hooks, a function can be called from the Starcon2Main
+thread, thereby eliminating threading issues that may otherwise arrise.
+The debug key can be specified in user's override.cfg by adding a line
+with a text similar to "debug.1 = STRING:key F12".
+An interactive way to access various debugging code, similar to
+the uio debug mode (see below) is in the works.
+
+The most interesting debugging functionality available at the moment is
+listed below:
+- the function equipShip()
+  When this function is called, the SIS is equiped with various useful
+  modules (a possible Precursor Bomb is left in place), all
+  fuel tanks and crew pods are filled to the maximum, you are given
+  the maximum number of landers, and all possible lander shields are
+  installed.
+- the boolean variable instantMove
+  When this variable is set to TRUE, you can select a location on the
+  star map, and your HyperSpace/Quasispace coordinates will immediately
+  be set to them. Your realspace coordinates are not changed, so if you
+  are exploring a solar system, you'll only notice it when you leave to
+  HyperSpace.
+- the function showSpheres()
+  When this function is called, all spheres of influence of the active
+  races will be shown.
+- the function activateAllShips()
+  When this function is called, it will make all ships available for
+  purchase in the shipyard.
+- the function forwardToNextEvent()
+  Fast forwards the clock until the next event. If TRUE is given as an
+  argument, the HYPERSPACE_ENCOUNTER_EVENTs, which normally happen every
+  day, are skipped.
+- the function dumpEvents()
+  Outputs information on all scheduled events to a FILE.
+- the function dumpPlanetTypes()
+  Outputs information on all planet types to a FILE.
+- the function dumpUniverseToFile()
+  Outputs information on the universe to "./PlanetInfo". This function
+  should only be called from debugHook, as threading issues would otherwise
+  arrise.
+- the functions resetCrewBattle() and resetEnergyBattle()
+  This function, when called in melee, sets the current crew or energy
+  level of the bottom player's ship to its maximum. This works both in
+  Supermelee and in the full game.
+- the function uio_debugInteractive()
+  This function is not defined in sc2code/uqmdebug.h, but in libs/uio.h.
+  This function can interactively (tty-based) display information on
+  the state of the uio file system, and modifications can be made.
+- the function dumpStrings()
+  This function prints all the game strings, and is useful to check whether
+  the various string bases, as defined in gamestr.h, are correct.
+- the function debugContexts()
+  Prints and visually displays the various graphics contexts.
+  This function should only be called from doInputDebugHook(), as threading
+  issues would otherwise arrise.
+
+
+The first version of this document was created by Serge van den Boom,
+on 2004-05-15.
+