ttg-batocera-store/README.md

ttg-batocera-store — the Teletype Games store for Batocera

Puts the https://teletypegames.org catalog into a Batocera box's ROM folders, with EmulationStation metadata and box art. Triggered from the Ports menu on the device, or from the CLI over SSH.

This repository is only the store definition — config.json plus a wrapper installer. All the logic lives in the shared engine, warp-engine-batocera-store, which works with any WarpEngine-based site; this is just the Teletype Games configuration of it.

Install

Straight onto the device:

curl -fsSL https://git.teletypegames.org/tools/ttg-batocera-store/raw/branch/master/install.sh | bash

Or from a checkout of this repo:

scp -r ttg-batocera-store root@batocera:/tmp/
ssh root@batocera /tmp/ttg-batocera-store/install.sh

The installer fetches the engine, drops it and this config in /userdata/system/batocera-store/ttg/, writes the ttg-store launcher and the Teletype Games Store Ports entry, and runs the first sync. Restart EmulationStation (batocera-es-swissknife --restart) to see the games.

Use

On the device. Ports ▸ Teletype Games Store. It downloads anything new, then restarts EmulationStation. Ports scripts get no console in Batocera, so the output goes to /userdata/system/batocera-store/ttg/store.log.

Over SSH.

S=/userdata/system/batocera-store/ttg-store

$S list                 # compatible catalog entries; * installed, ^ update available
$S sync                 # download everything new, refresh gamelists
$S sync blessingofra    # just one title (never prunes)
$S -n sync              # dry run
$S remove c64demo       # uninstall
$S config               # effective configuration

Global flags go before the subcommand: $S --roms-root /tmp/roms sync.

What this store installs

Catalog platform	Asset kind	Batocera system	Extension
c64	cartridge	c64 (VICE)	.prg
tic80	cartridge	tic80	.tic

Statuses released and archived, whole catalog, no owner filter. Everything lands under the teletypegames/ subfolder of each system, so a prune can never reach ROMs you put there yourself. To change any of it, edit /userdata/system/batocera-store/ttg/config.json on the box — the full key reference is in the engine's README.

Native games as Ports — experimental

Cartridges are all this store installs by default, which is a little under half the catalog: the rest of our games are native builds, and an emulator cannot boot those. The engine can install them through Batocera's Ports system instead, but it is off here on purpose — nobody has yet confirmed on real hardware that the games start, and each one is a 30–100 MB download rather than a few kilobytes.

To try it, add platform entries to /userdata/system/batocera-store/ttg/config.json on the box:

"platforms": {
  "ebitengine": {
    "system": "ports",
    "install": "port",
    "kind": { "x86_64": "linux_x64", "aarch64": "linux_arm64" },
    "ext": ".zip",
    "enabled": true
  },
  "godot": { "system": "ports", "install": "port",
             "kind": { "x86_64": "linux_x64" }, "ext": ".zip", "enabled": true },
  "love":  { "system": "ports", "install": "port",
             "kind": { "x86_64": "linux_x64" }, "ext": ".zip", "enabled": true },
  "bevy":  { "system": "ports", "install": "port",
             "kind": { "x86_64": "linux_x64", "aarch64": "linux_arm64" },
             "ext": ".zip", "enabled": true }
}

Then /userdata/system/batocera-store/ttg-store sync. The games appear under Ports ▸ Teletype Games; remove takes the unpacked program with it.

Mind the architecture. Only the platforms listed with an aarch64 entry above have ARM builds today — on a Raspberry Pi or a handheld the others are skipped with a message naming the architecture, rather than installing something that cannot start. godot, love and tic80 have no ARM build at all yet: a Godot ARM export needs a preset in the game repo, LÖVE has no upstream ARM runtime, and TIC-80's exporter has no ARM target.

With everything that can be enabled turned on, the coverage measured on 2026-08-17 was 13 of 15 titles on x86_64 and 9 of 15 on ARM. The two that stay out either way are phaserdemo and trickster-tiles: they ship only a web build.

Report back what happens on a real box — that is the missing piece before this becomes the default.

Where things land

/userdata/system/batocera-store/
├── ttg-store                            launcher
└── ttg/
    ├── store.py, config.json
    └── state.json, catalog.json, store.log

/userdata/roms/c64/teletypegames/        blessingofra-2.0.0.prg, rabbit-1.0.0.prg, …
/userdata/roms/c64/teletypegames/images/ blessingofra.png, …
/userdata/roms/c64/gamelist.xml          our entries merged in
/userdata/roms/ports/Teletype Games Store.sh

Upgrading from the pre-split batocera-store

The old repo installed everything into /userdata/system/ttg-store. Re-running the install command above migrates it: state.json is carried over, the old directory is renamed to ttg-store.pre-split, and the Ports entry is replaced in place. The ROMs themselves never move, so nothing is re-downloaded. Delete /userdata/system/ttg-store.pre-split once the new install looks right.