XEX Filter, the Swiss-Army Knife for Atari Binaries, Gets a Python Version

Víctor Parada (vitoco), known for his BASIC ten-liners, updated the page for his XEX Filter toolkit on 13 October 2026. The download now contains a Python version alongside the original Perl script. The page credits the conversion to "matosimi/Claude". The tool itself is still at version 1.7 (2 February 2022), but the Python version should be easier to run on Windows, where Perl has to be installed separately.

What it does

An Atari executable (.xex, .com, .exe or .obj) is a series of segments. Each starts with a load address and an end address, and the first is preceded by the $FFFF header. Two special addresses control what happens during loading. A segment that writes INITAD ($02E2) makes the loader call that routine immediately and then carry on, which is how loading screens work. RUNAD ($02E0) gives the address to jump to once everything is loaded.

Parada had written his own tools for this in Atari BASIC in the 1980s, and later rewrote them as separate Perl scripts. In 2020 he merged them into one program. Run with no options, it lists the structure of each file, numbering every block and naming known addresses:

> xex-filter.pl GAME.XEX
 -: 65535 [$FFFF] BINHEAD
 1: 8192-9029 [$2000-$2345] (838) <- CODE/DATA
 2: 16384-32767 [$4000-$7FFF] (16384) BANK <- CODE/DATA
 3: 736-737 [$02E0-$02E1] (2) RUNAD -> 8192 [$2000]

With -o NEW.XEX and one or more filter options it writes a new file:

  • -i / -x: select or exclude blocks by number, in any order, for example to strip a splash screen or reorder segments;
  • -s: split blocks at given addresses, and -z: join adjacent blocks, filling small gaps with zeros;
  • -a: give blocks new load addresses;
  • -e: simulate a load and extract memory ranges as new blocks, and -m: dump a full 64 KB memory map;
  • -v / -w: append byte or word blocks, for example to set a colour register or add an INITAD or RUNAD vector;
  • -r: remove runs of zero bytes to shrink a file (which only works if memory is clean at load time);
  • -d and -b: write raw data without headers, or wrap raw files as blocks;
  • -f: repair common faults such as a missing $FFFF header, a truncated file or trailing garbage.

Addresses can be given in decimal, as $hex, or as one of the built-in labels such as RUNAD, INITAD, PORTB, COLOR2 or CARTA. Concatenating files is as simple as listing several inputs, for example a splash screen followed by the game.

A real use, and a gotcha

In March 2026 the AtariAge member foft used XEX Filter to try to chain two cc65 programs into one file. Each cc65 executable ends with a RUNAD block, and only the last RUNAD in a file is ever used. So the command kept every block of both files except the first program's RUNAD, and added a new word block that writes the same entry address to INITAD (738) instead:

xex-filter.pl -o hellow.xex -i 1,2,3,9,5,6,7,8 -w738=8193 hello.xex world.xex

The loader then calls the first program as an init routine, returns, and carries on loading the second. That worked for a "Hello" + "World" test. With the full application, though, the combined file failed, even though both halves ran correctly one after the other from SpartaDOS X. The replies suggested why. An init routine is called as soon as its segment loads, so it must return cleanly. A program written to be started by RUNAD may assume a fresh start, quit with JMP (DOSVEC), or close files, including the one the loader is still reading. Altirra's .tracecio on was recommended for finding out which. The lesson: XEX Filter rearranges segments exactly as asked, but it can't make code that was written to run alone safe to run as an init routine.

Where to get it

The ZIP with both scripts, and a long manual with eleven worked examples, is at vitoco.cl/atari/xex-filter/. Perl runs it on Linux and macOS (Windows users can use Strawberry Perl or ActivePerl). The Python version runs anywhere Python does; on Windows, prefix the command with py if a console window just flashes and closes. Bug reports go to the "XEX Filter" thread on AtariAge.

Credits