Developer mode and diagnostics

Features & systems·Interface & runtime·Tools & diagnostics

Changed in 0.2.0

The debug keys, the benchmark overlay, the monochrome pages and assertions exist only in a Debug build. Both configurations write the debug log, crash reports, out-of-sync reports and the multiplayer statistics file, and both have the main-menu codes and the version dialog. The command reference records which build has each command, control and launch option.

Arming the debug keys

The debug keys are the fixed in-game keys that only a Debug build has, such as the ones that grant money, force a win or spawn an ORCA. The fixed controls list them.

A Debug build arms its debug keys when it is started with at least one command-line argument. A windowed-mode option, a resolution or a data directory arms them, and so does a stray word the game ignores. The playtest option arms the same keys and adds nothing else. The Visual Studio project starts the game under the debugger with -DATADIR=, so a Debug build launched that way has its debug keys armed.

The help option and an -X option with a letter the game does not recognize end the run before the game starts, so they arm nothing.

A Debug build started with no arguments has no debug keys

With no command-line argument, none of the debug keys respond, including the ones that grant money and force a win. No in-game control arms them later.

A debug key acts only while that key is not bound to a keyboard command. A key bound to a command runs the command instead.

The debug special dialog key hangs every game except a campaign

The debug special dialog key opens nothing. In a campaign it has no effect. In any other game it pauses the game and never resumes it, unless the local player’s game is already ending when the key is pressed.

The debug log

Both configurations write the debug log and send every line to an attached debugger.

A Debug build also opens a console window titled Debug Console that shows the same lines as they are written. A Release build opens it only when started with -XC.

Assertions

Assertions are compiled only into a Debug build. A failed assertion shows the C runtime’s assertion dialog, which offers three choices:

• Abort ends the run, and the crash reporter records it as an aborted run.
• Retry breaks into an attached debugger. Without one, the game closes and no crash report is written.
• Ignore continues past the failed assertion.

The benchmark overlay

A Debug build with the debug keys armed shows a frame benchmark window on F6. Dear ImGui draws it over the presented frame and over any screen on show, following the frame’s position and scale. Each time F6 shows or hides it, the renderer’s live texture and buffer counts are written to the debug log. A Release build has no overlay.

The window reports the logic frames and the presents of the last second, the frame number, the present interval, and the frame benchmarks that the events page shows. Each benchmark is a counter that times one step of a frame. Only a Debug build keeps them, and they count processor time-stamp ticks of sixteen cycles each. The window shows each as a share of the frame, and as an average in microseconds where the processor speed could be measured and in ticks otherwise. The five counters the engine never starts read “not instrumented”. A checkbox opens the Dear ImGui demo window, which exercises the renderer.

The window and the events page read the same counters, and at most one of the two resets them on a schedule:

• With Reset every second ticked, as it is when the game starts, and the monochrome display off, the window resets the counters once a second and reports the second just gone.
• While the monochrome display is on, the window leaves the resets to the events page, which resets the counters each time it is drawn. The window reports the averages since the last reset.
• With the box cleared and the display off, nothing resets them, and the window reports the averages since the last reset.

Reset resets the counters at once.

The window takes the mouse while the pointer is over it, even where it covers a screen, and the keyboard only while one of its fields has focus. Everything else reaches the game or the screen.

The monochrome pages

The monochrome pages are four pages of diagnostic text for a secondary monochrome display. They need a monochrome display driver, the \\.\MONO device. Without that device the pages can still be enabled, but nothing is drawn. If the device is present but refuses to clear a page, the pages switch off.

The monochrome launch option enables the pages. The monochrome debug key switches them on and off. Separate debug keys step to the previous and next page.

While the pages are enabled, the page in view is redrawn once a second. The other pages are not drawn, except the stress page, which is updated every second even when another page is in view.

Page	What it draws
Object	The diagnostic dump of the selected object. With nothing selected, it shows the last object selected, for as long as that object exists.
House	The diagnostic dump of the house that owns the selected or last selected object, when that object is infantry, a vehicle, an aircraft or a structure
Stress	The mission timer, the frame rate, and counts of vehicles, infantry, aircraft, structures, terrain objects, projectiles, animations, teams, triggers, trigger types and factories. Scrolling columns log CPU use, cell redraws, route searches, target scans and sidebar redraws once a second.
Events	Timings for the steps of a frame: each step’s share of frame time and its average duration, plus the rules and scenario timings

Each time the events page is drawn, it resets every timing except the rules and scenario timings. While the page stays in view, each refresh therefore covers the second just gone. The first refresh after switching to it covers the whole time since it was last drawn.

Motion capture

The motion-capture debug key raises a flag that nothing acts on, so no frame is ever captured. MovieTime would have set the length of the capture, so no value of it changes anything.

Multiplayer statistics

A multiplayer game started through the client launch writes mpstats.txt when it ends, in either configuration. LAN, skirmish and campaign games do not write the file.

The file opens with the frame count, the average frame rate, the largest look-ahead the game reached, the latency and game-speed settings, and each local address. A block for each connected player follows. It gives the player’s name and address, maximum and maximum-average round trip, resend count, frame-sync and command-count stalls, and packet loss as a count and as a percentage.

The sync dump

A network game that goes out of sync writes an out-of-sync report into the Debug folder beside the executable, in either configuration. The PrintCRC playback trap writes the same report at a chosen frame and then exits. The report page describes what the report holds.

Seven sun.ini settings exist for tracking down a desynchronized game, and only PrintCRC has an effect:

• Frame, Type, Coord, Target and Cell describe an object to watch frame by frame. The code that would watch it is compiled into neither configuration.
• CheckHeap raises a flag that nothing reads.

CheckHeap belongs in [MultiPlayer] and the other six in [SyncBug]. Both sections are read only when a skirmish or network game is chosen from the main menu, and [SyncBug] only while recording playback is armed. A campaign reads none of the seven. PrintCRC describes the one launch in which its value takes effect.

Crash reporting

Both configurations report crashes. A crash writes a folder under Exceptions beside the executable, holding a minidump, a readable report and the end of that run’s debug log. Crash reports describes the folder and what the report holds.

While a debugger is attached, the debugger receives the crash instead, and no crash folder is written.

Main-menu tools

The main-menu code recognizer

The classic main menu, the plain menu shown when the graphical main menu cannot be built, recognizes two typed codes.

Code	What it switches
PENGO	Replaces the visceroid art. While it is on, the version number on the title screen ends in PG.
THETEAM	In a skirmish game, reads TMCJ4F.INI over the rules when the game starts

Typing a code switches its effect on, and typing it again switches it off. Each switch plays the OptionsChanged sound.

The menu matches a code anywhere in the typed letters and digits, so XPENGO also switches PENGO. Any other key clears what has been typed, and so does a match. After 31 characters without a match, the typed text starts over. Each letter and digit typed on this menu is also written to the debug log.

Starting a LAN game switches both codes off. A skirmish game keeps them. No setting reads or saves either code, so both are off each time OpenTS is launched.

The version dialog

The version dialog opens from the graphical main menu’s version entry and from Ctrl+V on the classic main menu, and closes on OK, Enter or Escape. It shows the title, the game and internal version names, the CPU vendor, the version of the language resource library, and a build line. The build line says whether the build is Debug or Release, and names the commit the build was made from, the branch it was on and that commit’s date.

Toggles that reach nothing

These Debug controls change nothing beyond what each entry says:

• The debug icon overlay key forces the whole screen to redraw. The overlay it switches is never drawn.
• The map-checking launch option runs a check every frame, but the check examines nothing and always passes.

Related settings

Filter keys

9 of 9

Key	Description	Value	When omitted
CellNo effectmultiplayer settings	Parsed trap cell that nothing ever reads back.	string	0,0
CheckHeapNo effectmultiplayer settings	Parsed heap check switch that the engine never acts on.	integer	0
CoordNo effectmultiplayer settings	Parsed trap coordinate that is thrown away as soon as it is read.	string	0
FrameNo effectmultiplayer settings	Parsed trap frame that reaches a routine with nothing in it.	integer	2147483647
Inertscenarios	Stops ordinary weapon hits in the scenario from doing damage.	boolean	no
MovieTimeNo effectglobal rules	Length, in minutes, intended for a debug screen capture sequence.	floating point	.25
PrintCRCmultiplayer settings	Meant to name the playback frame at which the game writes an out-of-sync report and quits, though no launch honors a chosen frame.	integer	2147483647
TargetNo effectmultiplayer settings	Parsed trap target that reaches a routine with nothing in it.	integer	-1
TypeNo effect in some scopesSuperWeaponType, multiplayer settings, Sounds	A superweapon's hard-coded behavior, the object kind named for the playback trap under the sync-bug settings, or where a sound is heard from.	string	Varies by type

Related resources

• Project statusUsing OpenTS

History

1. Changed0.2.0In development

   Write an out-of-sync report with bounded histories

Page feedback

Report an error or missing detail. The issue includes this page and revision.

Open issueSource revision 51b52aa38392