Metadata-Version: 2.4
Name: recarted
Version: 0.3.0
Summary: Convert Atari 8-bit tape, disk and standard cartridge ROM images for A8PicoCart
Author: Christopher Patti
License-Expression: MIT
License-File: LICENSE
Classifier: Environment :: Console
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: System :: Emulators
Requires-Dist: cyclopts>=4,<5
Requires-Python: >=3.11
Project-URL: Homepage, https://github.com/feoh/recarted
Project-URL: Repository, https://github.com/feoh/recarted
Project-URL: Issues, https://github.com/feoh/recarted/issues
Description-Content-Type: text/markdown

# ReCarted!

![Vintage Atari cartridge illustration labelled ReCarted](assets/github-social.jpg)

Give an Atari cassette or floppy a second life in the cartridge slot. ReCarted is a **Linux command-line converter for the Atari 8-bit XL/XE and A8PicoCart**. Give it a supported `.cas` cassette, `.atr` floppy, `.atx` track image, or standard cartridge `.rom` dump and it writes a new cartridge file. It never overwrites your original.

## Try it in a minute (no game images needed)

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and Git on Linux, then:

```sh
uv tool install recarted
recarted example rainbow.cas
recarted inspect rainbow.cas
recarted convert rainbow.cas
recarted inspect rainbow.car
```

To update later, run `uv tool upgrade recarted`. If the shell can't find `recarted`, run `uv tool update-shell` and open a new terminal. Python 3.11 or newer is required; uv can supply it. No assembler is needed. Only the two emulator-assisted ATX recipes require Atari800 and an Atari OS ROM.

The example is an original Atari program that displays colour bars. Try `recarted example rainbow-disk.atr` for the floppy equivalent, or `recarted example rainbow-track.atx` to try the ATX workflow without an emulator or ROM. Use distinct names: both `rainbow.cas` and `rainbow.atr` would otherwise want to write `rainbow.car`.

## Convert your own image

```sh
recarted recipes
recarted inspect 'Gridrunner.cas'
recarted convert 'Gridrunner.cas'
recarted convert 'Bruce Lee.atr' --output 'Bruce Lee.xex'
```

`inspect` checks file signatures first. For a headerless cartridge dump, use the `.rom` extension. `convert` writes a `.car` beside the source unless you choose `--output`. If the output already exists, choose a new name. For one-load games you can request `.xex` instead: the A8PicoCart loads that directly into RAM. For games that still need disk sectors, use `.car`.

| Source | Recognized disk and tape releases | Output |
| --- | --- | --- |
| Cassette (`.cas`) | Attack of the Mutant Camels, Gridrunner, Hover Bovver | CAR or XEX |
| Disk (`.atr`) | Bruce Lee (Datasoft, US a2) | CAR or XEX |
| Disk (`.atr`) | Jumpman (Epyx, US), Pinball Construction Set | CAR with a **read-only** virtual disk |
| Track disk (`.atx`) | Jumpman (Epyx, US) | CAR with a **read-only** virtual disk |
| Track disk (`.atx`) | The Tail of Beta Lyrae (Datamost), Bruce Lee | CAR; Atari800 + stock XL/XE OS revision 2 required |

These are **specific releases**, not every dump of each title. If `inspect` says “No matching recipe,” changing the name won't help. No commercial games, game data, or Atari OS ROMs are distributed with ReCarted. Use images you have the right to convert.

## Wrap a cartridge ROM

A raw `.rom` already contains the cartridge program. ReCarted can add a CAR header without changing a single ROM byte:

```sh
recarted inspect Kangaroo.rom
recarted convert Kangaroo.rom
```

Recognized dumps of Kangaroo, Dig Dug, Journey to the Planets, Pitfall! II, Popeye and Qix need no options. For an unknown dump **you know is a standard Atari 8-bit computer cartridge**, specify `--rom-type 1` for 8 KiB or `--rom-type 2` for 16 KiB. Size alone cannot identify the layout. Bank-switched ROMs, system ROMs and Atari 5200 ROMs aren't supported by this wrapper.

A CAR header doesn't fix OS compatibility. The recognized Kangaroo dump reached the playfield in Atari800's Atari 800 mode with OS-B, but showed a blank screen with the stock 800XL OS. This matters on a real XL/XE even if the cartridge accepts the file.

## Convert an ATX disk

Run `recarted inspect` first. If the disk is the recognized Jumpman release, `recarted convert 'Jumpman (1983)(Epyx)(US)[!].atx'` works directly. For *The Tail of Beta Lyrae* and *Bruce Lee*, install Atari800 with its text monitor (tested with 5.2.0) and supply your own stock 16 KiB XL/XE OS revision 2 ROM. For example, from the directory containing the game and `ATARIXL.ROM`:

```sh
recarted inspect 'Tail of Beta Lyrae (The) _ Datamost.atx'
recarted convert 'Tail of Beta Lyrae (The) _ Datamost.atx' --os-rom ATARIXL.ROM
```

ReCarted boots a temporary copy of the original track image in the background. The resulting `.car` needs neither the disk nor that ROM file on the cartridge. An unknown dump isn't flattened into an ATR; it may need the disk's duplicate sectors, timing or error status. If you're upgrading the Git-based install, run `uv tool upgrade recarted`.

## Play it

- **A8PicoCart:** With the cartridge **removed from the Atari**, connect it to the computer over USB. Copy the resulting `.car` or `.xex` to it, eject it, and **disconnect USB before inserting it into the powered-off Atari**. Power on, select the file normally, and it boots straight into the program. No DiskCart menu or disk in D1: is needed.
- **Linux emulator:** Install `atari800` separately and run `recarted test rainbow.car`. For the disk-reader games, use a stock XL/XE OS: `recarted test 'Jumpman.car' --os-rom ATARIXL.ROM` (supply the path to your own ROM). The command opens Atari800 so **you** can check the screen and controls; it does not claim the game passed just because the emulator started. For XEX, use `atari800 -xl -nobasic -run 'Bruce Lee.xex'`.

**Can I save a pinball table?** Not to the embedded cartridge disk. Use your original ATR in a writable disk setup for authoring and saving.

**“Unsupported Cartridge Type”?** Run `recarted inspect` on the file you actually copied. ReCarted wraps standard ROM dumps as **type 1 (8 KiB)** or **type 2 (16 KiB)**. Disk and tape recipes generate **type 41, 128 KiB** (Atarimax **1 Mbit**). The older type 42 is **1 MiB / 8 Mbit** and is not supported by stock A8PicoCart. Renaming a ROM or editing that header byte doesn't fix it. If type 41 is rejected, tell us your cartridge model and firmware version.

## What's next?

More **cassette** recipes are a priority, especially multi-stage tapes such as Preppie! and the two sides of International Karate. Additional ATX releases, more floppy layouts, and tested **macOS and Windows** installations are also on the roadmap. WAV recordings, arbitrary bank-switched ROM dumps, and arbitrary disk/tape ports are not supported.

## Contribute a recipe

Got another Atari disk or tape running from a cartridge? [Send a pull request](https://github.com/feoh/recarted/compare) with your recipe. ATX, ATR, and CAS recipes are all welcome, including ones for a different release of a game we already support. Tell us which release you converted and what you saw when you booted it in Atari800 or on hardware. Share the recipe and the image’s SHA-256, not the commercial image or OS ROM. See [how to add and verify a recipe](docs/TECHNICAL.md#verification-and-adding-recipes) for the testing details.

[Request a recipe or report a hardware result](https://github.com/feoh/recarted/issues): include the title and release, `recarted inspect` output, the source's `sha256sum`, your Atari/cart model and firmware, and what you saw. Please **don't attach commercial images or OS ROMs**.

For how recognition works, emulator evidence, limitations, or building and testing the loaders, see [Technical notes](docs/TECHNICAL.md). [MIT license](LICENSE).
