TITLE=WarpEngine RetroArch Store
ROUTE=/stores/warp-engine-retroarch-store
LOCALE=en
MODIFIED=1792417593
URL=https://wiki.teletypegames.org/stores/warp-engine-retroarch-store
L=1 #22
L=2 #24
L=3 #44
L=4 https://git.teletypegames.org/stores/warp-engine-retroarch-store
L=5 #45
L=6 https://www.retroarch.com
L=7 #57
L=8 #63
L=9 #64


q│ 
cwarp-engine-retroarch-store
q pulls games from a 1WarpEngine catalog into

q│ RetroArch's library: one 
c.lpl
q playlist per platform, with box art in the

q│ thumbnail folders the playlist's name points at. This is the engine only —

q│ the site, the store name and where games land come from a 
cconfig.json
q in a

q│ separate 
bstore repository
q. The shared half is 2warpstore.


p warpstore                     the shared core                                

p     ▲                                                                        

p warp-engine-retroarch-store   this engine — retroarch_store.py, install.sh   

p     ▲                                                                        

p     │ config.json                                                            

p ttg-retroarch-store           store repositories                             

p     ▼                                                                        

p teletypegames.org                                                            

The reference store is 3TTG RetroArch Store.


bRepository:
0 4https://git.teletypegames.org/stores/warp-engine-retroarch-store

bShared core:
0 2warpstore 
bSibling engine:
0 5Batocera store engine 
bRetroArch:
6https://www.retroarch.com


1What you get

1════════════

• 
bEvery machine RetroArch runs on
0 — desktop Linux, Windows, macOS, Android,
  Steam Deck, the console ports. The same cartridges the Batocera store
  installs, a much larger audience.
• 
bNo assumed paths
0 — the four directories it needs come from the user's own
  
cretroarch.cfg
0.
• 
bIt can write for a machine it is not running on
0 (
cexport
0), the only way to
  serve Android, which runs RetroArch but not Python.
• 
bIt never edits 
cretroarch.cfg
0 and never touches display preferences.
• 
bZero dependencies
0 — Python 3 standard library only.


p <store>-retroarch-store sync                                                 

p         │                                                                    

p         ├─ GET /api/software                      the whole catalog          

p         ├─ keep platforms a libretro core boots   c64 → VICE x64, plus4 → VI»

p CE xplus4, tic80 → TIC-80                                                    

p         ├─ pick the newest non-dev release        that carries the cartridge 

p         ├─ GET /api/download?path=<asset>         .prg / .tic into the conte»

p nt folder                                                                    

p         ├─ GET <software.imageUrl>                box art, converted to PNG  

p         └─ write <store> - <label>.lpl            playlist + thumbnails      


r──────────────────────────────────────────────────────────────────────────────


1Why this is not the Batocera store

1══════════════════════════════════

RetroArch is not one machine. Three design points follow.


bIt reads 
cretroarch.cfg
b.
0 The playlist folder is not always inside the RetroArch
directory. On the macOS install this was developed against, 
cplaylist_directory
is 
c~/Documents/RetroArch/playlists
0 while cores and thumbnails live under

c~/Library/Application Support/RetroArch
0. 
c~
0 is expanded, and so is the leading

c:
0 a portable install uses for its own directory.


bIt can write for another machine.
0 Android has no Python, so the only way to
serve it is to render the tree elsewhere and copy it over. The same mechanism
covers an SD card that will be mounted at a different path on the handheld.


bIt refuses to write while RetroArch is running.
0 RetroArch keeps playlists in
memory and writes them back on exit — favourites, last played, sort order — so
a write underneath it can be undone. The Batocera engine defers instead,
because the Ports menu is what launched it; here nothing launches us, so
refusing is simpler and safer.


bWhat is lost compared with Batocera:
0 a 
c.lpl
0 entry has no description or
developer field, so 
cdesc
0 and 
cauthor
0 do not survive — RetroArch takes those
from its own databases. And RetroArch cannot launch scripts, so there is no
in-app trigger: the sync runs from a shell or a scheduler.


r──────────────────────────────────────────────────────────────────────────────


1Installing a store

1══════════════════

The installer takes the store as a parameter, so it works with any config:


p curl -fsSL https://git.teletypegames.org/stores/warp-engine-retroarch-store/»

p raw/branch/master/install.sh |                                               

p   STORE_CONFIG=https://git.example.org/tools/my-store/raw/branch/master/conf»

p ig.json sh                                                                   

It reads 
cstore.id
0 from the config, installs the engine, the shared core and
the config into 
c~/.local/share/warp-engine-store/example-retroarch/
0, writes an

cexample-retroarch-store
0 launcher into 
c~/.local/bin
0, prints the resolved paths
and runs the first sync.

The store home is the store id with 
c-retroarch
0 appended, not the bare id: the
desktop store engine shares this root, and a shared home would mean a shared

cconfig.json
0 and 
cstate.json
0. An older install is moved on the next run of the
installer.


t┌──────────────────────┬─────────────────────────────────────────────────────┐

t│
h Environment variable 
t│
h Meaning                                             
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cSTORE_CONFIG
0         
t│
0 
brequired
0 — path or URL of the store's 
cconfig.json
0   
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cSTORE_ROOT
0           
t│
0 where stores live (default                          
t│

t│
0                      
t│
0 
c${XDG_DATA_HOME:-~/.local/share}/warp-engine-store
0) 
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cBIN_DIR
0              
t│
0 where the launcher goes (default 
c~/.local/bin
0)      
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cRETROARCH_DIR
0        
t│
0 RetroArch's directory, if it is somewhere unusual   
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cSTORE_SKIP_SYNC
0      
t│
0 
c1
0 to install without syncing                        
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cENGINE_RAW_BASE
0      
t│
0 where to fetch 
cretroarch_store.py
0 from              
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cWARPSTORE_RAW_BASE
0   
t│
0 where to fetch 
cwarpstore.py
0 from                    
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cWARPSTORE_SRC
0        
t│
0 a local 
cwarpstore.py
0 to install instead of          
t│

t│
0                      
t│
0 downloading                                         
t│

t└──────────────────────┴─────────────────────────────────────────────────────┘

Run from a file, the installer prefers a 
cretroarch_store.py
0 or 
cwarpstore.py
lying next to itself over the downloaded one — that is how a checkout installs
its own code. A wrapper that fetches 
cinstall.sh
0 must therefore save it into a
directory of its own (
cmktemp -d
0), never a bare file in 
c/tmp
0, or whatever stray
copies sit there get installed.


r──────────────────────────────────────────────────────────────────────────────


1Use

1═══


p S=~/.local/bin/example-retroarch-store                                       

p                                                                              

p $S paths                # resolved directories, and whether the cores are th»

p ere                                                                          

p $S list                 # compatible entries; * installed, ^ update availabl»

p e                                                                            

p $S sync                 # download everything new, refresh the playlists     

p $S sync blessingofra    # one title only (never prunes)                      

p $S -n sync              # dry run                                            

p $S remove c64:c64demo   # uninstall (bare name works too)                    

p $S purge                # uninstall everything this store installed          

p $S config               # effective configuration                            

Global flags go 
bbefore
0 the subcommand: 
c$S --retroarch-dir /mnt/ra sync
0.


bRestart RetroArch after a sync
0 — it builds its menu at startup, so a new
playlist does not appear in a running instance.


r──────────────────────────────────────────────────────────────────────────────


1Uninstalling

1════════════


p curl -fsSL https://git.teletypegames.org/stores/warp-engine-retroarch-store/»

p raw/branch/master/uninstall.sh | sh                                          

The engine does the removing, not the shell script: 
cpurge
0 first, then the
launcher and the store home. Only 
cstate.json
0 knows which playlists, thumbnails
and content files were ours — and if the engine cannot finish (RetroArch
running, a directory gone) nothing else is touched, so you are never left with
the files but without the engine that knows them.


t┌──────────────────────┬─────────────────────────────────────────────────────┐

t│
h Environment variable 
t│
h Meaning                                             
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cSTORE_ID
0             
t│
0 which store to remove; only needed with several     
t│

t│
0                      
t│
0 installed                                           
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cSTORE_CONFIG
0         
t│
0 alternative to 
cSTORE_ID
0 — the id is read from the   
t│

t│
0                      
t│
0 config                                              
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cDRY_RUN
0              
t│
0 
c1
0 prints what would go and removes nothing          
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cKEEP_HOME
0            
t│
0 
c1
0 keeps the store home (state, catalog cache, log)  
t│

t│
0                      
t│
0 for a reinstall                                     
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cFORCE
0                
t│
0 
c1
0 purges even while RetroArch is running            
t│

t├──────────────────────┼─────────────────────────────────────────────────────┤

t│
0 
cSTORE_ROOT
0, 
cBIN_DIR
0  
t│
0 as for the installer                                
t│

t└──────────────────────┴─────────────────────────────────────────────────────┘

What it leaves behind on purpose:

• 
bcontent the user put in the store's folder
0 — a directory goes only when
  empty, so one stray file keeps it.
• 
ba playlist that still has their entries
0 — only items pointing inside the
  store's content folder are dropped. A playlist left empty is deleted; one
  that is not is rewritten without us.
• 
bthe 
c.lpl
b backups
0 — each named after the playlist plus the store id and
  
c-backup
0, listed at the end of the run. They are the playlists as we first
  found them, so they may hold entries that were never ours.

A dry run lists files but not directory removals: it cannot know which
directories will end up empty.

To take 
bevery
0 store off a machine — both engines, the shared core, the
launchers — use the script in 2warpstore:


p curl -fsSL https://git.teletypegames.org/engines/warpstore/raw/branch/master»

p /uninstall.sh | sh                                                           


r──────────────────────────────────────────────────────────────────────────────


1Where things land

1═════════════════


p ~/.local/share/warp-engine-store/example-retroarch/                          

p ├── retroarch_store.py, warpstore.py, config.json                            

p └── state.json, catalog.json                                                 

p                                                                              

p <content_root>/example/c64/           blessingofra-2.0.0.prg, rabbit-1.0.0.p»

p rg, …                                                                        

p <playlists_dir>/Example Store - Commodore 64.lpl                             

p <thumbnails_dir>/Example Store - Commodore 64/Named_Boxarts/Blessing of Ra.p»

p ng                                                                           

p                                              /Named_Titles/…  /Named_Snaps/… 


ccontent_root
0 defaults to a 
ccontent
0 folder inside the RetroArch directory; the
other two come from 
cretroarch.cfg
0. 
cpaths
0 prints what was resolved and where
each answer came from — run it first when a sync went somewhere unexpected.

Everything lands under the store's own 
cpaths.subfolder
0, which is all a prune
may touch: never the user's content, never another store's. The playlist file
carries the store's name, so it is ours — but an entry 
ithe user
0 added survives
a rewrite, because only items pointing inside the store's content folder are
replaced. The first time a playlist is touched, a 
c-backup
0 copy is made.


r──────────────────────────────────────────────────────────────────────────────


1The playlist

1════════════


p {                                                                            

p   "version": "1.5",                                                          

p   "default_core_path": "/…/cores/vice_x64_libretro.dylib",                   

p   "default_core_name": "VICE x64",                                           

p   "label_display_mode": 0,                                                   

p   "right_thumbnail_mode": 0,                                                 

p   "left_thumbnail_mode": 0,                                                  

p   "thumbnail_match_mode": 0,                                                 

p   "sort_mode": 0,                                                            

p   "items": [                                                                 

p     {                                                                        

p       "path": "/…/content/example/c64/blessingofra-2.0.0.prg",               

p       "entry_slot": -1,                                                      

p       "label": "Blessing of Ra",                                             

p       "core_path": "DETECT",                                                 

p       "core_name": "DETECT",                                                 

p       "crc32": "4253CFC6|crc",                                               

p       "db_name": "Example Store - Commodore 64.lpl"                          

p     }                                                                        

p   ]                                                                          

p }                                                                            

• 
bOne playlist per platform
0, because 
cdefault_core_path
0 is a 
iheader
0 field. That
  is the only way every entry starts with one click and no core prompt.
  Entries stay on 
cDETECT
0, so the file still works where cores live elsewhere —
  worst case one prompt, not a dead entry.
• 
bThe name is the namespace.
0 
c{store} - {label}
0 never writes into RetroArch's
  own 
cCommodore - 64.lpl
0 and never collides with the official thumbnail packs.
  It is also the 
cdb_name
0, which is how RetroArch finds the thumbnails: the
  folder under 
cthumbnails_dir
0 named exactly like the playlist minus 
c.lpl
0, with
  the 
cNamed_*
0 folders inside.
• 
bThe display fields are all 
c0
0 — whatever the user set globally. A store has
  no business overriding that.
• 
ccrc32
b is real
0, computed from the downloaded file, so RetroArch can tie saves
  and thumbnails to the content.


bA missing core is a note, not an error.
0 If the platform's core is not in

clibretro_directory
0, the playlist is still written: 
cdefault_core_path
0 stays
empty, entries stay on 
cDETECT
0, and RetroArch asks once. 
clist
0 and 
cpaths
0 say so,
with the fix:


p c64: core not found: vice_x64_libretro.dylib — entries stay on DETECT        

p      (Online Updater ▸ Core Downloader ▸ VICE x64)                           


bBox art must be PNG.
0 RetroArch looks for the label with 
c.png
0 and nothing else.
The catalog serves whatever was uploaded — one of our covers is a GIF — and
the standard library cannot re-encode an image, so the engine shells out to

csips
0 (built into macOS), 
cmagick
0, 
cconvert
0 or 
cffmpeg
0, first one found. With none
of them the entry has no box art, which beats a failed sync. The honest fix is
upstream: WarpEngine could serve a PNG variant.

The cover is downloaded once and placed in all three 
cNamed_*
0 folders,
hardlinked where the filesystem allows.


r──────────────────────────────────────────────────────────────────────────────


1Another machine: export

1═══════════════════════


csync
0 installs into this machine's RetroArch. 
cexport
0 renders the whole store
into a canonical tree for somewhere else.


p # Android over adb                                                           

p $S export /tmp/ra-example \                                                  

p     --target-prefix /storage/emulated/0/RetroArch \                          

p     --target-libretro-dir /data/data/com.retroarch.aarch64/cores \           

p     --core-suffix _android.so                                                

p adb push /tmp/ra-example/. /storage/emulated/0/RetroArch/                    

p                                                                              

p # An SD card mounted here, but at /mnt/sdcard on the handheld                

p $S export /Volumes/SDCARD/RetroArch --target-prefix /mnt/sdcard/RetroArch    

The tree is always 
cplaylists
0, 
cthumbnails
0 and 
ccontent
0 inside the given
directory. 
c--target-prefix
0 is what the playlists say the content is called on
the machine that will run it; without it, the export directory's own path is
used. Target paths are written the way the target spells them — POSIX unless
the prefix looks like Windows.


cexport
0 is 
bstateless on purpose
0: it is a complete picture of the catalog, not
an incremental update, and it must not disturb a local install in the same
store home.


r──────────────────────────────────────────────────────────────────────────────


1Platform mapping

1════════════════

A catalog platform is installable when a libretro core boots its asset
directly:


t┌──────────────────┬────────────┬────────────────────────────────┬───────────┐

t│
h Catalog platform 
t│
h Asset kind 
t│
h Core                           
t│
h Extension 
t│

t├──────────────────┼────────────┼────────────────────────────────┼───────────┤

t│
0 7
cc64
0              
t│
0 
ccartridge
0  
t│
0 
cvice_x64_libretro
0 (VICE x64)   
t│
0 
c.prg
0      
t│

t├──────────────────┼────────────┼────────────────────────────────┼───────────┤

t│
0 8
cplus4
0            
t│
0 
ccartridge
0  
t│
0 
cvice_xplus4_libretro
0 (VICE     
t│
0 
c.prg
0      
t│

t│
0                  
t│
0            
t│
0 xplus4)                        
t│
0           
t│

t├──────────────────┼────────────┼────────────────────────────────┼───────────┤

t│
0 9
ctic80
0            
t│
0 
ccartridge
0  
t│
0 
ctic80_libretro
0 (TIC-80)        
t│
0 
c.tic
0      
t│

t└──────────────────┴────────────┴────────────────────────────────┴───────────┘

All three cores are built for every relevant target — macOS x86_64/arm64,
Linux x86_64/aarch64/armhf, Windows x86_64, Android arm64-v8a/armeabi-v7a — so
the cartridges run everywhere RetroArch does.

The other WarpEngine platforms (
cebitengine
0, 
clove
0, 
cgodot
0, 
cbevy
0, 
cphaser
0) ship
web builds and per-OS native archives. No libretro core runs those, so this
engine cannot serve them; on a Batocera box they install as 5Ports instead.


r──────────────────────────────────────────────────────────────────────────────


1Not yet verified on real hardware

1═════════════════════════════════

The engine has been exercised end to end against the live catalog: download,
playlists, thumbnails, GIF conversion, foreign-entry preservation, prune,
uninstall, Android export, and a full install from the forge. Two things need
a real run:

• 
bDoes the VICE core auto-start a raw 
c.prg
0, or load and wait for 
cRUN
0? If it
  waits, the fix is a core option or shipping 
c.d64
0.
• 
bThe Android push
0 — the paths above are documented defaults, not
  measurements, and whether scoped storage lets RetroArch read what 
cadb push
  wrote is untested.

The design notes and the measurements this engine was built from are in

cdevarea/RETROARCH_STORE.md
0.