ProsperoEden/docs/DOWNLOADS.md

Download sources and RomM

Games on a server in your network, shown in the Library and downloaded to the console to play.

Quick start with RomM

Download sources and save sync both work with a RomM server in your network (5.0.0 or newer for the save sync). In short:

1. Put the games on the server. Games go to RomM's library under roms/switch/: a game as one .nsp or .xci file, or as a folder with the game's file, its updates in update/ and its DLC in dlc/. Then start a scan in RomM (its Scan page) so it lists them.
2. One RomM user per person. Each person who plays on the console gets a user of their own in RomM; their save data stays apart on the server.
3. Downloads. In RomM, create a client API token (your profile, Client API tokens) with the scopes platforms.read and roms.read. Write /data/prosperoeden/config/remote/sources.json over FTP with the server's address and that token (see Download sources), start an FTP server on the console on port 2121 (ftpsrv), and open Settings > Downloads: the server and its games show up, and the Library lists them.
4. Save sync. Open Settings > Save sync, Cross on a profile and choose the server. Scan the QR code with your phone, sign in to RomM as that profile's user and approve the code. From then on the profile's save data is synced before and after each game (see Save sync). Pairing uses the server from sources.json; without download sources, fill in save-sync.json over FTP instead. The save sync does not need the FTP server.

Download sources

A download source is a server in your network that has games, such as a RomM server. Its games show up in the Library without taking any space on the console. A game is downloaded to the game files folder when you want it; from then on it is a game on the console like one you copied there. Nothing is streamed. Downloads need an FTP server running on the console (port 2121, see below): it writes the downloaded files.

• Set them up. Make sure an FTP server runs on the console, then save /data/prosperoeden/config/remote/sources.json on the console (over FTP, like the keys) and open Settings > Downloads, or reopen ProsperoEden. It lists the sources, each with its "type", a "name" for the menu and what that type needs (see RomM for a RomM server):

  { "sources": [
      { "type": "romm", "name": "Home", "url": "http://192.168.1.20:3000", "token": "rmm_..." },
      { "type": "romm", "name": "Office", "url": "https://games.example.org", "token": "rmm_..." }
  ] }
  

  Settings > Downloads shows each source, whether it answered, and why not when it did not, and the FTP server's port. Without a source it shows what the file is called, with an example for a RomM server. When you ask it to read the lists again (Cross on a source), it says when they are in.

• The Library. The sources' games are listed with the console's own, by name, with their cover. A game that is not on the console has a darker cover with a cloud, and instead of NSP or XCI the line under it names its source (or how many have it), or says Queued, how far its download is, or Download failed. Its details name its sources. The same game on several sources is listed once, and a game that is on the console already is not listed again. Its settings, mods and console mode are there once it is downloaded.

• Which game is which. Each source says what it knows of a game: its title ID, its ids at metadata providers (IGDB, ScreenScraper and the like) and whether its name comes from such metadata. Two sources' games are the same game when the first of these that both know agrees: the title ID, then an id at a provider both have one of, then the name (when both names come from metadata; case, accents and punctuation do not count), else the file name. A game on the console is the source's game when it has the file name the source gives it (a downloaded one does), else when their title IDs agree (when the source knows one), else by its name.

• Play. Cross on a game that is not on the console downloads it first. A ring shows how far it is and the time left, and the game starts once all of it is there. Circle lets it download in the background without starting it; Square cancels it. When several sources have the game, ProsperoEden asks which one first.

• Download ahead. Square on such a game puts it in the download queue, and Square again takes it out. The queue downloads one game at a time while the menu is open, also after ProsperoEden was closed and opened again. Settings > Downloads lists it: Square cancels a download, Cross tries a failed one again, and Cross on a source reads the sources' game lists again (also done by itself when the menu opens after more than 15 minutes).

• Where the files go. A downloaded game gets a folder of its own in roms/, roms/<game>/, with the game's file and its updates and DLC in it, as a game you copy to the console in a folder. The folder is named after the game's file, without its extension and the tags dumps carry ([0100...], [v0], (USA)): My Game [0100...][v0].nsp goes to roms/My Game/. What a source counts as the game, an update or DLC is up to it (a RomM server: its file categories). A game downloaded from a source keeps the file name it has there. Only .nsp and .xci files are downloaded, and an entry without a game file (an update or DLC on its own) is not listed.

• An FTP server on the console. Downloads are written by an FTP server running on the console (such as ftpsrv, which most setups have for copying the keys), on port 2121: ProsperoEden hands it the bytes over loopback. Written by the app itself, a game of several gigabytes slowed the drive down to a few MB/s and stopped the menu; from a payload the drive keeps its speed. Without such a server a download fails and says so. "ftp_port" next to "sources" names another port (etaHEN's own FTP server, for example), and "ftp_user" and "ftp_password" a sign-in when the server asks for one (else anonymous). The server must support REST with STOR, to go on with a download.

• Interrupted downloads. A download is written to .remote-downloads/ in the game files folder, and once all of the game's files are complete they are moved to the game's folder in roms/, so roms/ only ever holds whole files of whole games. It stops while a game runs and when ProsperoEden closes, and goes on from where it was the next time the menu is open; the last 4 MB are downloaded again then, in case the console lost power while they were written. A cancel deletes what was downloaded (and never touches roms/), and what .remote-downloads/ holds for a game that is not in the queue is deleted when the menu opens, so nothing is left behind. When the drive is full, the download stops and says so, as the FTP server reports it ("No space left on device"); nothing reaches roms/, what was downloaded stays in .remote-downloads/, and once there is room, Cross on it in Settings > Downloads goes on from there (Square cancels it and deletes it). The drive's free space is not checked before a download starts: an app on the console cannot ask for it.

• Checked as it comes. RomM does not hash these files, so a download is checked on its way in, as Eden's integrity check checks a game: each NCA of an NSP or XCI against the SHA-256 it is named after, with no keys needed. A file found damaged is deleted and the download fails saying so; trying again downloads it again. A download that goes on reads what it had from the drive first (Checking in the queue). What the console's FTP server writes is not read back, and files that are no NSP or XCI are taken as they are.

• Making room. A game that a source has can be deleted from the console again: Triangle in the Library, then Delete from console (Cross twice). Its file and all of its updates and DLC are deleted, also ones put in its folder by hand, and then its folder in roms/ once it is empty; its save data, its settings and its mods stay. The Library then lists it as on its sources again, and it can be downloaded any time.

Sign-ins are kept in sources.json only, and each is sent to its own source only. They are stored there as plain text, and whoever can reach the console's FTP server can read the file: give a source a token made for it, with only the scopes it needs, rather than your password. A file that is on the console already is never replaced by a download of the same name. Download sources need filesystem access (the payload loader on port 9021), as the game files folder does, and an FTP server on the console (see above). Save data is synced apart from the sources; see Save sync.

RomM

"type": "romm" is a RomM server (a current version); as with any source, its games are written by the console's FTP server, which has to run. Its entry in sources.json has the server's "url" and a "token": in RomM, create a client API token (your profile, Client API tokens) with the scopes platforms.read and roms.read. "username" and "password" work instead of "token", and "platform" names the platform's slug when the server does not call it switch. RomM's file categories decide what is the game and what are its updates and DLC; manuals, mods, soundtracks and the like stay on the server. In RomM a game is a folder, with its updates in update/ and its DLC in dlc/. What RomM matched a game to tells it apart: its ids at the metadata providers RomM uses, its name when RomM identified it, and its title ID when the RomM server has the keys to read it.