Debug Recording

From Armagetron
Revision as of 22:30, 22 August 2021 by Cadillac (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)

What is it?

Armagetron Advanced 0.2.8+ has a feature to record a play session. This session can later be used by developers to find and squash bugs.

What is it not?

A tool to record games and make the recording available for others or yourself to watch later. Feel free to use it as such, but be aware that the for the debug recordings to actually be a help in finding bugs, it has to have these limitations:

  • you can't play the recording back in any other version of Armagetron than you recorded it with
  • you can't even reliably play it back with the same version on a different machine (here's why)
  • you can't play the recording back at any framerate your client can manage
  • you can't skip backward
  • you always have to watch a long recording from the beginning, there is no really fast way to skip to the middle
  • the recording contains your configuration and forces it on the one playing it back (apart from some graphics settings)

These restrictions are fundamental and can't be worked around. Other limitations would be technically possible to work around, for example it would be possible to switch the camera to different players or have a fast forward hotkey or to allow "cut" files that automatically play a recording back, skipping the parts that were cut out; in some special cases, it may be possible to get rid of the last limitation. But the first two limitations are so severe that it plainly doesn't make sense to improve the usability of debug recording playback into that direction, and the changes would all make more code aware that a debug recording is running, which is a bad thing for debugging. You don't want code to know it's getting debugged. What you really want is a different kind of recording, which may or may not materialize in the future.

Creating a Debug Recording

All Platforms

Use your shell to pass some command line arguments to armagetron:

To record: armagetronad --record filename
To playback: armagetronad --playback filename [--fastforward SECONDS]

where filename is the name of the file to be recorded to / played back.

(On windows, you can issue shell commands by entering them in startmenu->run. Remember to give the full path to armagetronad.exe if you do that.)

Mac OS X

Use the helper application included with the game to start or playback an Armagetron Advanced recording. The application has a feature to compress a recording using bzip2 after Armagetron Advanced quits, so you can upload to the forums easily. It also will decompress a bzip2 or zip file for playback.


The installer creates links in the start menu to record/playback to/from a file called ArmagetronAdvancedDebugRecording.aarec that is located directly on your desktop. To attach it on the forum, you'll need to either rename it to have an accepted extension (best choice: or, better, really compress it with a zip program like WinZip or WinRar.

As of version and the test versions for that, you can play back a recording simply by doubleclicking on it.

Fast-Forward a Recording (XP)

Fast-forwarding can be tricky for the average user. The first step is to put the recording somewhere, preferably the Desktop. Then you will start ArmagetronAd with the Windows Run command, but with some special instructions. Look at the following template:

armagetronad --playback "C:\Documents and Settings\USERNAME\Desktop\My_Recording.aarec" --fastforward 100

This looks complicated so let's break down what we see. You are going to tell armagetronad to playback the file at "this location" and fast-forward 100 seconds. The image below shows a file named My_Recording.aarec and the Run dialog box. The second image shows the properties of that file with it's location circled in red (right-click the file and select Properties). Your location may be different and you will have your own username. Copy this information and the filename into the template above. Use the template with your modifications and paste it into the Windows Run dialog. When you click OK to run, Armagetron will start and fast-forward 100 seconds, or however many seconds you choose.

Debug ff winxp1.png

Debug ff winxp2.png