one-saves-cli 0.10.4

The 1saves command-line tool: convert emulator saves and memory cards to and from the Universal Saves Format
one-saves-cli-0.10.4 is not a library.

one-saves-cli

The 1saves command-line tool: move retro saves and memory cards in and out of the Universal Saves Format.

$ cargo install one-saves-cli

Commands

$ 1saves convert card.mcr --from duckstation
card.mcr -> card.1saves (PS1 memory card, 3 save(s), 25525 bytes)

$ 1saves convert pokemon.srm --from mgba --rom pokemon_red.gb --dat No-Intro_GB.dat
identified as "Pokemon - Red Version (USA, Europe)"

$ 1saves inspect card.1saves     # everything it says, down to each save on a card
$ 1saves verify card.1saves      # structure, every digest, and the encoding
$ 1saves hash card.1saves        # content hash, which is the hash of the file
$ 1saves extract card.1saves     # write it back out as the card it came from
$ 1saves extract card.1saves --part 1   # pull one save out as its own bundle
$ 1saves profiles                # what --from accepts

A bundle is whatever file someone handed over, so extract checks it before writing any of it: every digest, down to each save on a card, and nothing at all is written from a bundle that does not match itself — verify says which part. An output is never written over an existing file without --force, and never through a link: with --force a link at the output is replaced, not followed. A clock or a thumbnail picked up from beside the input is read only when it is a plain file, since the user named the input and not it.

A Saturn's internal memory brings the rest of its set along. Mednafen and Beetle Saturn keep a game's cart in a .bcr and the console's clock in a .smpc beside it, and convert makes the three one device, which extract writes back as the same three files:

$ 1saves convert "NiGHTS.bkr"
read NiGHTS.bcr beside it
read NiGHTS.smpc beside it
NiGHTS.bkr -> NiGHTS.1saves (Saturn backup RAM, 2 component(s), 18454 bytes)

A 64DD disk's save is its RAM area. convert takes it as the .ram mupen64plus, Project64 and MiSTer keep, or out of a whole copy of the disk, as another emulator keeps one, in the retail layout or MAME's. Where ares's drive clock is beside it, as Nintendo 64DD.rtc in a saves folder, the two make an N64 device. extract writes the .ram back, or with --onto and the disk's image, a copy of the disk holding the save:

$ 1saves convert "Mario Artist.ram" --rom "Mario Artist.ndd" --dat No-Intro_64DD.dat
$ 1saves extract "Mario Artist.1saves" --onto "Mario Artist.ndd" -o "Mario Artist.ndr"

new makes an empty, formatted card, written as the file an emulator or a flash cart loads:

$ 1saves new gc MemoryCardA.USA.raw --size 1019
empty GameCube memory card -> MemoryCardA.USA.raw (1019 blocks, 64 Mbit, 8388608 bytes)

$ 1saves new ps2 Mcd002.ps2              # Sony's 8 MB card, spare areas and all
$ 1saves new gc MemoryCardA.JAP.raw --shift-jis   # for a Japanese console
$ 1saves new saturn cart.bcr --size 512K --layout wide   # as Yabause keeps a cart
$ 1saves new neogeo game.sav --layout mister   # as the MiSTer core keeps a card
$ 1saves new vmu blank.1saves            # a bundle holding the card, rather than the card

--from names either a producer (mgba, duckstation, pcsx2, or any of the apps and 200 cores in the registry) or an input format (ps1, raw). A producer says who wrote the bytes; the format is still detected from the bytes themselves.

A bundle's source names three layers: the app, the core it ran, and the platform under it. --from retroarch names only the app, so add the rest when you know them:

$ 1saves convert crystal.srm --from retroarch --core gambatte --platform muos

Each is written as its registry slug, whatever it was called on the command line, and checked: a core the app cannot run is refused. A producer neither registry lists — a flash cartridge, a cartridge reader — is left out of source rather than given a reverse-DNS name 1saves does not own, so its profile settles only the device kind and the system. 1saves profiles shows which is which.

--rom reads a ROM's header for a title and product code and hashes it; --dat resolves that digest against a No-Intro, Redump or TOSEC catalog to get a canonical name.

Features

All on by default. Turning one off drops what it carries, and the dependencies under it, from the binary.

Feature What it carries What comes off
cards all seven card formats the seven crates below
ps1 n64 gc vmu ps2 neogeo saturn one card format each that format's crate, and nothing else
saturn-gzip a Saturn cart standalone Mednafen gzipped flate2 and zlib-rs
archive a card, or loose saves, read straight out of a .zip zip
states RetroArch's, mGBA's and DuckStation's save states flate2 and png
dat --dat FILE datary and the XML reader, derive macro and proc-macro chain under it
dat-cmpro the ClrMamePro syntax for --dat winnow
rom --rom FILE crc32fast, md-5, sha1
zstd reading an emulator state zstd compresses zstd and the C library it compiles

dat implies rom: a catalog is looked up by the ROM's digest, so --dat has nothing to resolve without --rom. A bundle compresses nothing, so zstd is about emulator states alone.

A card format that is off is still named. inspect, verify and hash read a bundle of it unchanged, and convert and extract refuse in these words rather than guessing:

$ 1saves convert card.mcr
1saves: this is a PS1 memory card, and this build has the `ps1` feature off, so it can
        name the format and not read or write it

What such a build cannot do is tell that format's dump from a flat save when the extension is ambiguous — .bin, .srm — because the reader that knows the signature is what came off.

$ cargo install one-saves-cli --no-default-features --features ps1,zstd