# Formats

Here we describe the various file formats that MTX games and other programs are available in :-

- Sound files (`.wav`, `.mp3`)
- Tape files (`.mtx`)
- RUN files (`.RUN`)
- SDX Basic files (`.BAS`)
- FDX Basic files (`.BAS`)
- CP/M programs (`.COM`)
- MTXL.COM (`.BAF`)
- ZX Spectrum tape (`.tap`)
- ZX Spectrum snapshot (`.sna`)

## Sound files

MEMU does not support loading programs from cassette tape, or from `.wav` or `.mp3` files. There is no plan to change this. A very large part of the Memotech software library already exists in `.mtx` file form (over 100 files). We can thank people like Jim Wills for sampling tapes to `.wav` and Paul Daniels for converting these to `.mtx` files.

## Tape files

`.mtx` files are disk files containing the same bytes, in the same order, as would be found on an MTX cassette tape.

Tape files contain :-

- a `0xff` byte
- 15 byte `tape_name`, padded with spaces
- little endian 16 bit word, defining the `system_variables_base` (often `0xf8f2`)
- `0xfb4b-system_variables_base` bytes of system variables (often `0x0259` bytes)
- the Basic program itself, from `0x4000` onwards...

Files following these rules can be loaded from MEMU, using commands like this :-

    $ memu -vid-win -snd-portaudio UNIVERSE.mtx

Followed by typing `LOAD ""` in MTX BASIC. Most autostart, but you'll need to `RUN` some of them.

Some games have loaders. Usually you'd get MEMU to run the game directly, but if you run the loader, you'll need to ensure the filename of the game matches the `tape_name` stored within it.

Note that I have encountered one `.mtx` file that was actually a RUN file, and I have encountered a number of `.mtx` files that were actually SDX Basic files. In the MEMU distribution, such files have been renamed appropriately.

MEMU includes a selection of tape files in the `tapes` sub-directory.

## RUN files

If you had an MTX with an SDX disc (with the normal SDX ROM), you might have games supplied as `.RUN` files.

RUN files contain :-

- little-endian 16 bit word with the `code_base`
- little-endian 16 bit word with the `code_length`
- `code_length` bytes of machine code, to be loaded at `code_base` in memory, and executed by jumping there

These would be loaded from MTX BASIC using `USER RUN "FILE.RUN"`.

In MEMU, remember to use the `-sdx` command line option to install SDX support before trying to use `USER` commands.

Another way to run `.RUN` files is using commands similar to :-

    $ memu -vid-win -snd-portaudio TOADO.RUN

`RUN.COM` is a CP/M program which can be used to run some `.RUN` files, without having to switch into MTX BASIC, and use the SDX ROM to `USER RUN "FILE.RUN"` them. This program puts the file content directly into memory, switches into the right memory mode, and jumps to the start of the program. This means that MTX BASIC has never been running, and has not set up any of its system variables. As a result, some `.RUN` files don't run properly this way. eg: Comic Bakery and Pacman.

If a program is invoked from the SDX BASIC ROM `USER RUN` command, the IOBYTE will reference the SDX BASIC ROM (eg: ROM 5 or ROM 3). If the file changes the IOBYTE, it must restore it before returning to the caller. In the case of referring to the `.RUN` file on the MEMU command line, the IOBYTE will not reference any particular ROM, and the program should not return to the caller.

MEMU includes a selection of RUN files in the `games` sub-directory.

## SDX Basic files

If you had an MTX with an SDX disc (with the normal SDX ROM) you might have SDX Basic programs as `.BAS` files.

SDX Basic files contain :-

- a little endian 16 bit STKLIM value (often `0xf2f8`)
- a little endian 16 bit length of system variables (often `0x0259`)
- system variables
- the Basic program itself, from `0x4000` onwards...

These would be loaded and saved using `USER LOAD` and `USER SAVE` commands.

In MEMU, remember to use the `-sdx` command line option to install SDX support before trying to use `USER` commands.

The MTXL.COM section below shows another way to load some SDX Basic files even if you don't have real or emulated SDX hardware.

MEMU includes a selection of SDX Basic files in the `basic` sub-directory.

## FDX Basic files

If you had a MTX with FDX, you might have had FDX Basic programs as `.BAS` files.

FDX Basic programs are different to SDX Basic programs. Attempting to load an FDX program from SDX Basic appears to be unreliable.

FDX Basic is started by running the `FDXB.COM` program from CP/M.

Two version of `FDXB.COM` are known to exist. The earlier version was shipped with the FDX and includes FDX FDC drivers and only works on an FDX. The later version includes SDX FDC drivers, and therefore only works on an SDX.

The latter version should probably have been called `SDXB.COM` to avoid confusion, and so I name my copy that way.

FDX Basic files will have been loaded and saved using using `DISC LOAD` and `DISC SAVE` commands. It is recommended that you `DISC DIR ""` before using `DISC SAVE`, to avoid a known bug which would otherwise result in corrupted files.

To use MEMUs CP/M emulation, you must pass the `-fdxb` command line flag. Alternatively use the Full CP/M approach described on the Usage page.

## CP/M programs

CP/M programs are delivered as `.COM` files. Sometimes they are entirely self-contained in one file, and sometimes they load other related files.

A `.COM` file is the raw program code and data. It is loaded to address `0x0100` in memory, and execution starts from there.

MEMU includes a selection of CP/M files in the `cpm` sub-directory, and games loadable from CP/M in the `games` sub-directory.

## MTXL.COM

`MTXL.COM` appears to be a bit of a hack. It is a CP/M program which switches to MTX Basic (like `MTX.COM` does), but it can also load code from a file into memory, starting at address 0x4000. It doesn't seem to properly set up variables or system variables, so only certain programs survive the process intact. Also, programs that are supposed to autorun, often don't.

If we have tape file `AGROVATA.mtx`, and given that it is just a single basic program (ie: no special loader and or raw blocks of data on the tape) and given it has `0x0259` bytes of system variables, and that 1+15+2+0x0259=619, we can do the following :-

    $ dd if=AGROVATA.mtx of=AGROVATA.BAF bs=1 skip=619
    $ memu -vid-win -snd-portaudio MTXL.COM AGROVATA.BAF

If we have SDX Basic program `BANANA.BAS`, and given the first 4 bytes of `BANANA.BAS` are `0xf2 0xf8 0x59 0x02`, and that 2+2+0x0259=605, we can do the following :-

    $ dd if=BANANA.BAS of=BANANA.BAF bs=1 skip=605
    $ memu -vid-win -snd-portaudio MTXL.COM BANANA.BAF

Because `MTXL.COM` is a CP/M program, which loads a file, the filename must be in the 8.3 naming convention.

Because autorun won't work, you'll probably need to `LIST` the program, and then work out whether you can simply `RUN` the program, or where to you need to `GOTO` to.

Although this trick only seems to work on certain programs, it does help reduce the dependency on cassette tapes and SDX hardware.

MEMU includes a selection of `.BAF` files in the `mtxl` sub-directory.

`.BAF` is an convention I made up to refer to files, containing Basic programs, from 0x4000 in memory.

I had originally thought this was the format of an FDX Basic program, but now I'm not so sure.

## ZX Spectrum tape

ZX Spectrum tapes are typically stored in `.tap` files.

Spectrums save data to tape in short "headers" (with a long lead-in tone) and longer "blocks" (with shorter lead-in tones).

A `.tap` file contains zero or more records, where each record is a header or block wrapped in an envelope. Each record comprises :-

- 2 byte little-endian length of the rest of the record (ie: N+2)
- 1 byte indicating whether its a header or a block
- N bytes of actual header of block data from Spectrum memory
- 1 byte xor checksum of the previous 1+N bytes

Various ZX Spectrum emulators (and MEMU) support the ability to spot when the Spectrum ROM (or Z or Speculator) code wants to read or write a header or block, and then read from or append to a `.tap` file instead.

Because the file format is so simple, you can do things like combine two `.tap` files together to make a tape with one program followed by another.

They are described in detail here.

This format is mentioned here, as under certain conditions a Memotech can emulate a Spectrum.

Another common tape format is `.tzx`, but MEMU does not support this.

## ZX Spectrum snapshot

ZX Spectrum snapshots files typically have `.sna` file extension.

The 48KB Spectrum variety is comprised of a 27 byte header containing registers, followed by a copy of the 48KB of RAM.

Various ZX Spectrum emulators (and MEMU) support the ability to snapshot current state to a file, and then reload it again later.

They are described in detail on the World of Spectrum website.

This format is mentioned here, as under certain conditions a Memotech can emulate a Spectrum.

MEMU will only take snapshots when PC >= 0x4000 and SP >= 0x4002 and restore snapshots taken when the PC >= 0x4000. As a special case, snapshots with PC = 0x0038 are allowed, primarily because snapshots taken with the fuse emulator tend to have this. This is a safety feature to stop snapshotting happening whilst in Speculator code.

Another common snapshot format is `.z80`, but MEMU does not support this.