Skip to content

Roadmap

Jump to bottom
abduznik edited this page Jul 17, 2026 · 8 revisions

Roadmap

Completed

SV_MODE_STRATEGY / Phase 3

Status: Implemented and tested (48 strategy tests + 72 Phase 3 regression/coverage tests).

  • Manifest lifecycle (create, free, load, save) with key-value text format
  • Identity resolution: single explicit method per registration — NOT a runtime cascade
  • sv_register_with_manifest() for auto-detecting game_id at registration time
  • save_path_template with {game_id}, {platform}, {emulator}, {live_path} placeholders for magazine path organization
  • Integration with existing save/pull/retention pipeline
  • Graceful degradation: missing manifest, malformed header, pattern mismatch, hash-DB failure all fall back to DEFAULT behavior without crashing

Identity Methods (5 implemented)

Method Status Platforms
SV_IDENTITY_NONE Done All (caller supplies game_id)
SV_IDENTITY_SERIAL_CNF Done PS1/PS2 SYSTEM.CNF pattern extraction
SV_IDENTITY_CHECKSUM Done Header checksum + file size
SV_IDENTITY_ROM_HEADER Done Dolphin GC (4-byte ASCII at fixed offset)
SV_IDENTITY_TEXT_PATTERN Done PCSX2 SYSTEM.CNF (pattern + normalization)
SV_IDENTITY_PLUGGABLE Done Caller-supplied hash-DB callback

Real-World Manifests (7 ported)

Manifest Platform Identity Validation
pcsx2_folder.cfg PS2 (folder mode) text_pattern (SYSTEM.CNF) Synthetic + real structure check
pcsx2_file.cfg PS2 (file mode) none (shared memcard) Real structure: 12 .ps2 files found
ppsspp.cfg PSP text_pattern (directory basename) Real structure: 13 dirs found, 2 games validated
rpcs3.cfg PS3 text_pattern (directory basename) Real structure: 6 dirs found, 2 games validated
duckstation.cfg PS1 none (stem-based) Real structure: 8 .mcd files found
dolphin_gc.cfg GameCube rom_header (4 bytes at 0x00) Real structure: 7 .gci files found
retroarch_snes.cfg SNES none (stem-based) No real data on this machine
ryujinx.cfg Switch text_pattern (cnmt scan) Real structure: 1825 files, 99 dirs found

Stem-Matching — Decided: Option B

Caller always supplies game_id derived from ROM filename. No library API change. Affected manifests (duckstation.cfg, retroarch_snes.cfg) document this convention in their comments. See docs/stem-matching-proposal.md for the full decision rationale. The library does not implement SV_IDENTITY_STEM_MATCH — Freegosy's real matching uses fuzzy word-token scoring, which a simple stem-compare would not cover.

Next

Fuzzy Title Scoring

Deferred — no known platform currently requires this. PPSSPP and RPCS3 were previously flagged for "fuzzy title scoring" but their real identification mechanisms are directory-name pattern matching, now implemented.

Shared Memcard Per-Game Extraction

PCSX2 file-mode shared memcards (Mcd001.ps2) multiplex many games in one binary file. Per-game extraction from within a memcard image is explicitly out of scope — libsavesync treats the entire memcard as a single opaque unit.

Hash-Database DAT-Format Parser

The pluggable callback API exists (sv_hash_db_lookup_fn) but no concrete DAT-format parser is shipped. The core remains database-free by design.

Tier Fallback Cascade — Considered and Rejected

A runtime cascade (try serial → checksum → hash-DB in sequence) was considered during Phase 3 design and rejected by design review. Real-world tools (RetroArch, RetroAchievements, Playnite) bind identification method to platform/format, not runtime cascading. Cascading produces nondeterministic results across runs. See Layer-2-Registration-and-Identity for the full rationale.

Directory/Archive Sub-file Granularity

Whether SAVE_SHAPE_DIRECTORY/ARCHIVE entries need per-file hash lists for finer diffing, or whether whole-container hashing is sufficient for v1. Current behavior: whole-container hashing.

Metadata Store On-Disk Format

Deliberately left as an implementation detail. The current binary TLV format works but could be optimized for larger datasets.

Relocation Poke-Check

sv_update_register()'s relocation logic for live_path — the poke check against destination path and copy-verify-then-delete-source flow needs more thorough testing.

Pull-External Buffer Model

sv_pull_external() currently uses a fixed 4KB buffer for pulled data. A streaming or callback-based model would handle larger saves.

IPC Binary (Layer 1)

A standalone binary exposing the same operations over an IPC protocol. Not yet implemented — the C ABI is the primary interface.

Thread Safety

No mutexes or thread-local storage. The library is not thread-safe. Callers must serialize access.

Windows Support

Currently uses POSIX APIs (/dev/urandom, mkdir, rename, unlink). A Windows port would need _mktemp_s, MoveFileEx, etc.

See also: Architecture-Overview | Layer-2-Registration-and-Identity

libsavesync Wiki

Clone this wiki locally