ttg-retroarch-store/README.md

# ttg-retroarch-store — the Teletype Games store for RetroArch

Puts the <https://teletypegames.org> catalog into RetroArch's library: two
playlists — *Teletype Games - Commodore 64* and *Teletype Games - TIC-80* — with
box art, on any machine RetroArch runs on.

This repository is only the store definition — `config.json` plus the two wrapper
scripts. All the logic lives in the shared engine,
[`warp-engine-retroarch-store`](https://git.teletypegames.org/stores/warp-engine-retroarch-store),
which works with any WarpEngine-based site; this is just the Teletype Games
configuration of it.

## Install

```sh
curl -fsSL https://git.teletypegames.org/stores/ttg-retroarch-store/raw/branch/master/install.sh | sh
```

Or from a checkout of this repo:

```sh
./install.sh
```

The installer fetches the engine, drops it and this config in
`~/.local/share/warp-engine-store/ttg-retroarch/`, writes the `ttg-retroarch-store`
launcher into `~/.local/bin`, prints the directories it resolved from your
`retroarch.cfg`, and runs the first sync. **Restart RetroArch** to see the
playlists — it builds its menu at startup.

If the two cores are not installed, the playlists still work and RetroArch asks
which core to use the first time. To be rid of the prompt:
*Online Updater ▸ Core Downloader ▸ **VICE x64** and **TIC-80***, then sync again.

## Use

```sh
S=~/.local/bin/ttg-retroarch-store

$S paths                # where things go, and whether the cores are there
$S list                 # compatible catalog entries; * installed, ^ update available
$S sync                 # download everything new, refresh the playlists
$S sync blessingofra    # just one title (never prunes)
$S -n sync              # dry run
$S remove c64demo       # uninstall
```

Close RetroArch before syncing: it writes its playlists back when it exits, so a
sync underneath a running instance can be undone. The store refuses rather than
lose the work.

Keep it current from `crontab`:

```
0 * * * * ~/.local/bin/ttg-retroarch-store sync >>~/.local/share/warp-engine-store/ttg-retroarch/store.log 2>&1
```

## Uninstall

```sh
curl -fsSL https://git.teletypegames.org/stores/ttg-retroarch-store/raw/branch/master/uninstall.sh | sh
```

Or `./uninstall.sh` from a checkout. It takes out the six games, the two
playlists and their thumbnails, then the launcher and the store home. Close
RetroArch first, for the same reason as for a sync.

```sh
DRY_RUN=1 ./uninstall.sh     # show what would go, remove nothing
KEEP_HOME=1 ./uninstall.sh   # keep state.json and the log, for a reinstall
```

Nothing of yours goes with it: content you put in the `teletypegames/` folder
keeps its directory, a playlist that still has an entry of yours is rewritten
rather than deleted, and any `*.lpl.ttg-backup` is listed and left alone.

## What this store installs

| Catalog platform | Playlist | Core | Extension |
| --- | --- | --- | --- |
| `c64` | Teletype Games - Commodore 64 | `vice_x64_libretro` (VICE x64) | `.prg` |
| `tic80` | Teletype Games - TIC-80 | `tic80_libretro` (TIC-80) | `.tic` |

Statuses `released` and `archived`, whole catalog, no owner filter — **six titles,
233 KB in total** as measured on 2026-08-17:

| Playlist | Titles |
|---|---|
| Commodore 64 | Blessing of Ra, Rabbit Scooter, C64 Demo for Arok Party 2026 |
| TIC-80 | Definitely not an Impostor, BombExpert, Mr Anderson's Adventure |

That is the cartridge half of the catalog. Our other games are native builds and
web builds, and no libretro core runs those — on a Batocera box they install as
Ports instead, see
[`ttg-batocera-store`](https://git.teletypegames.org/stores/ttg-batocera-store).

Everything lands under the `teletypegames/` subfolder of RetroArch's content
directory, so a prune can never reach content you put there yourself. To change
any of it, edit `~/.local/share/warp-engine-store/ttg-retroarch/config.json` — the full key
reference is in the engine's README.

## Onto an Android phone or a handheld

RetroArch on Android reads the same playlists, but Android cannot run Python, so
the tree is rendered here and copied over:

```sh
$S export /tmp/ra-ttg \
    --target-prefix /storage/emulated/0/RetroArch \
    --target-libretro-dir /data/data/com.retroarch.aarch64/cores \
    --core-suffix _android.so
adb push /tmp/ra-ttg/. /storage/emulated/0/RetroArch/
```

Both cores are published for Android arm64-v8a and armeabi-v7a, so the games do
run there — but **this path has not been tried on a device yet.** If the playlists
do not show up, check the phone's own paths:

```sh
adb shell cat /storage/emulated/0/RetroArch/retroarch.cfg | grep _directory
```

## Where things land

```
~/.local/share/warp-engine-store/
├── ttg/
│   ├── retroarch_store.py, warpstore.py, config.json
│   └── state.json, catalog.json
└── (launcher: ~/.local/bin/ttg-retroarch-store)

<content_root>/teletypegames/c64/     blessingofra-2.0.0.prg, rabbit-1.0.0.prg, …
<content_root>/teletypegames/tic80/   impostor-1.0.tic, …
<playlists_dir>/Teletype Games - Commodore 64.lpl
<playlists_dir>/Teletype Games - TIC-80.lpl
<thumbnails_dir>/Teletype Games - Commodore 64/Named_Boxarts/Blessing of Ra.png
```

`playlists_dir`, `thumbnails_dir` and the cores folder come from your
`retroarch.cfg` — they are not always where you would guess, so `paths` prints
what was resolved and where each answer came from.

## Not yet verified on real hardware

The engine has been exercised end to end (download, playlists, thumbnails, prune,
uninstall, Android export), but two things need a real run:

- **Does the VICE core auto-start a raw `.prg`**, or does it load and wait? If it
  waits, the fix is a core option or shipping `.d64` instead.
- **The Android push**: the paths above, and whether scoped storage lets RetroArch
  read what `adb push` wrote.

Report back what happens — the design notes are in `devarea/RETROARCH_STORE.md`.