Home

libsavesync

A pure C library that manages the precise lifecycle of emulator/game save files: identifying exactly which save belongs to which game, safely versioning it locally, and optionally handing it off to external transports for cross-device sync.

It is not an emulator, launcher, cloud service, process watchdog, or orchestration server. It is a local, passive, embeddable save lifecycle manager — infrastructure other apps link against or shell out to.

Status: Working, tested (364 tests), v0.1.0 released. All three platforms (Linux, macOS, Windows) pass the full test suite.

Quick Links

• Examples — Quick-start code for both the C ABI and IPC binary
• API-Reference — All function signatures
• Testing-Guide — How to test the library (360 tests, 7 suites)
• GitHub — Source code, CI/CD, releases
• CONTRIBUTING.md — Project conventions

Why libsavesync?

Project	What it does	Why it's not this
Syncthing / cloud-mounted folders	Generic folder sync	Zero game-awareness, fuzzy matching, no identity layer
EmuSync, SaveSync, CrossSave-Cloud	Hobbyist folder/extension-based save backup	Extension-guessing, no precision identity, monolithic apps
RomM's save sync engine (4.9+)	Server-orchestrated multi-device sync	Sophisticated, but logic lives in the server backend — not embeddable
Ludusavi	Cross-platform save backup, manifest-driven	Excellent prior art, but Rust/CLI-GUI, not a C-ABI embeddable core
Freegosy	Precise per-emulator save strategies shipped	Logic embedded inside one Flutter app, not extractable/reusable

Two Ways to Use It

1. Link the C ABI — include savesync.h, link libsavesync.a, call functions directly. Best for C, C++, Rust, Zig, or any language with FFI.
2. Run the IPC binary — talk NDJSON over stdin/stdout from any language. Best for Python, JavaScript, shell scripts, or restricted environments.

Supported Platforms

5 of 8 manifests validated against real save data (Dolphin GC, Ryujinx, PPSSPP, RPCS3, PCSX2 folder mode). See Examples for a walkthrough.

Documentation

• Philosophy — Core design principles
• Architecture-Overview — The six layers
• Layer-1-Interface — Dual entry points (C ABI + IPC binary)
• Layer-2-Registration-and-Identity — Registration and identity resolution
• Layer-3-Metadata-Store — Local metadata persistence
• Layer-4-Local-Save-and-Pull — Atomic save/pull operations
• Layer-5-Retention-and-Rotation — Automatic version rotation
• Layer-6-External-Transport — Pluggable transport contract
• API-Reference — All function signatures
• Data-Types-Reference — Enums, typedefs, and structs
• Testing-Guide — How to test the library (360 tests, 7 suites)
• Examples — Quick-start code and walkthroughs
• Roadmap — Known future work