Adds ability to export game saves as .cbs codebreaker save files, also adds --version argument

This commit is contained in:
markmental 2026-10-07 16:22:37 -04:00
commit 4c56cda598
5 changed files with 395 additions and 20 deletions

View file

@ -7,6 +7,7 @@ JAPS2ME (Just A PS2 Memory Card Editor) is a Rust CLI and library for managing P
- `list <CARD.ps2>` — list saves as a Unicode table with game titles, file counts, payload sizes, and free space.
- `delete <CARD.ps2> <SAVE-DIRECTORY>` — remove a save directory.
- `add <CARD.ps2> <SAVE.cbs|SAVE.max>` — import a Codebreaker or Datel MAX Drive save.
- `export <CARD.ps2> <SAVE-DIRECTORY> <OUTPUT.cbs>` — export a save as a Codebreaker file.
The project is licensed under GPL-3.0-or-later. `mymcplusplus` is a technical reference for PS2 memory-card filesystem behavior and save formats; see its attribution in `README.md`.
@ -17,9 +18,9 @@ The project is licensed under GPL-3.0-or-later. `mymcplusplus` is a technical re
- `src/memory_card/icon_sys.rs` — `icon.sys` title parsing with Shift-JIS decoding.
- `src/lib.rs` — crate modules and public exports.
- `src/save.rs` — shared imported-save model and format detection.
- `src/codebreaker/format.rs` — Codebreaker RC4/zlib parser.
- `src/codebreaker/format.rs` — Codebreaker RC4/zlib parser and encoder.
- `src/max_drive.rs` — MAX Drive header/CRC parser, LZARI decoder, and file-record parser.
- `src/memory_card/card.rs` — memory-card access, directory operations, allocation, FAT chains, and save insertion/removal.
- `src/memory_card/card.rs` — memory-card access, directory operations, allocation, FAT chains, save insertion/removal, summaries, and save export.
- `src/memory_card/superblock.rs` — superblock parsing and card geometry.
- `src/memory_card/directory.rs` — 512-byte directory-entry encoding and mode bits.
- `src/memory_card/fat.rs` — FAT marker constants and helpers.
@ -61,7 +62,7 @@ After changing code, rebuild the executable being invoked. For example, `cargo b
## Save-format details
- Codebreaker files begin with `CFU\0`. Their body is RC4-decrypted using the fixed Codebreaker state, then zlib-decompressed. Header and per-file lengths must be bounds-checked.
- Codebreaker files begin with `CFU\0`. Their body is RC4-decrypted using the fixed Codebreaker state, then zlib-decompressed. Header and per-file lengths must be bounds-checked. The encoder mirrors this layout: 64-byte file records plus raw data, zlib-compressed and RC4-encrypted, with `stored_len` set to the total file length and overlong headers grown past the 124-byte minimum for long titles.
- MAX Drive files begin with `Ps2PowerSave` and have a 92-byte header. The CRC is computed over the header with its CRC field zeroed followed by the compressed payload. The LZARI output contains `dirlen` records: little-endian data length, 32-byte name, file bytes, and the format's alignment padding.
- The supplied `PES3allunlocked.max` fixture should parse as directory `BESLES-51912PES3OPT`, with `icon.sys` (964 bytes), `icon_view` (33,400 bytes), and `BESLES-51912PES3OPT` (773,120 bytes). Tests use CRCs of the decoded files to catch LZARI regressions.

View file

@ -8,6 +8,7 @@
- List saves as a Unicode table with directory names, game titles, file counts, payload sizes, and free-space footer.
- Delete a save directory.
- Export a save directory as a CodeBreaker `.cbs` file.
- Import a CodeBreaker `.cbs` save, including its files and metadata.
- Import a Datel MAX Drive `.max` save, including LZARI decompression.
- Read and update standard PS2 memory-card images with ECC support.
@ -28,6 +29,7 @@ The executable is created at `target/release/japs2me`.
japs2me list <CARD.ps2>
japs2me delete <CARD.ps2> <SAVE-DIRECTORY>
japs2me add <CARD.ps2> <SAVE.cbs|SAVE.max>
japs2me export <CARD.ps2> <SAVE-DIRECTORY> <OUTPUT.cbs>
```
Examples:
@ -37,9 +39,10 @@ target/release/japs2me list Mcd001.ps2
target/release/japs2me add Mcd001.ps2 my-save.cbs
target/release/japs2me add Mcd001.ps2 PES3allunlocked.max
target/release/japs2me delete Mcd001.ps2 BASLUS-20787SD5
target/release/japs2me export Mcd001.ps2 BESLES-51912PES3OPT pes3.cbs
```
`list` displays saves as a Unicode table with the save directory, game title from `icon.sys` (falling back to the directory name), regular-file count, and total payload size. A footer shows free allocatable space. Game titles are decoded from the Shift-JIS `icon.sys` title field; missing or invalid metadata falls back to the directory name. Listed save sizes are summed file payload bytes, not on-card allocated cluster sizes. Free space is unallocated FAT clusters multiplied by the cluster size. `add` detects CodeBreaker and MAX Drive saves by their file signatures, uses the directory name stored in the save, and reports an error if that save already exists on the card.
`list` displays saves as a Unicode table with the save directory, game title from `icon.sys` (falling back to the directory name), regular-file count, and total payload size. A footer shows free allocatable space. Game titles are decoded from the Shift-JIS `icon.sys` title field; missing or invalid metadata falls back to the directory name. Listed save sizes are summed file payload bytes, not on-card allocated cluster sizes. Free space is unallocated FAT clusters multiplied by the cluster size. `add` detects CodeBreaker and MAX Drive saves by their file signatures, uses the directory name stored in the save, and reports an error if that save already exists on the card. `export` writes the save directory's files, modes, and timestamps to a CodeBreaker `.cbs` file, using the `icon.sys` title when available, and refuses to overwrite an existing output file.
## Tests

View file

@ -20,11 +20,15 @@ const RC4S: [u8; 256] = [
use crate::save::{SaveFile, SaveImport};
use anyhow::{anyhow, bail, ensure, Context, Result};
use flate2::read::ZlibDecoder;
use std::io::{Cursor, Read};
use flate2::write::ZlibEncoder;
use flate2::Compression;
use std::io::{Cursor, Read, Write};
const MAGIC: &[u8; 4] = b"CFU\0";
const HEADER_MIN: usize = 124;
const MAX_DECOMPRESSED_BODY: usize = 64 * 1024 * 1024;
const DIRNAME_LEN: usize = 32;
const FILENAME_LEN: usize = 32;
pub type CodebreakerFileEntry = SaveFile;
pub type CodebreakerSave = SaveImport;
@ -149,9 +153,111 @@ pub fn parse(data: &[u8]) -> Result<SaveImport> {
})
}
fn validate_entry_name(name: &str, what: &str) -> Result<()> {
ensure!(!name.is_empty(), "Codebreaker {what} name cannot be empty");
ensure!(
name.len() <= DIRNAME_LEN,
"Codebreaker {what} name must fit in 32 bytes: {name}"
);
ensure!(
!name.bytes().any(|byte| byte == 0),
"Codebreaker {what} name cannot contain NUL: {name}"
);
Ok(())
}
/// Encode a save as a Codebreaker `.cbs` file.
///
/// Mirrors [`parse`]: a `CFU\0` header with lengths, directory metadata,
/// and title, followed by the RC4-encrypted zlib body of 64-byte file
/// records plus raw file data.
pub fn encode(save: &SaveImport) -> Result<Vec<u8>> {
validate_entry_name(&save.directory, "directory")?;
ensure!(
!save.title.bytes().any(|byte| byte == 0),
"Codebreaker title cannot contain NUL"
);
for file in &save.files {
validate_entry_name(&file.name, "file")?;
ensure!(
file.mode & 0x8030 == 0x8010,
"Codebreaker entry is not a regular file: {}",
file.name
);
u32::try_from(file.data.len()).context("file is too large for Codebreaker save")?;
}
let mut body = Vec::new();
for file in &save.files {
body.extend_from_slice(&file.created);
body.extend_from_slice(&file.modified);
body.extend_from_slice(
&u32::try_from(file.data.len())
.context("file is too large for Codebreaker save")?
.to_le_bytes(),
);
body.extend_from_slice(&file.mode.to_le_bytes());
body.extend_from_slice(&[0u8; 2]); // reserved
body.extend_from_slice(&[0u8; 8]); // reserved
let mut name_field = [0u8; FILENAME_LEN];
name_field[..file.name.len()].copy_from_slice(file.name.as_bytes());
body.extend_from_slice(&name_field);
body.extend_from_slice(&file.data);
}
ensure!(
body.len() <= MAX_DECOMPRESSED_BODY,
"Codebreaker body exceeds size limit"
);
let mut encoder = ZlibEncoder::new(Vec::new(), Compression::default());
encoder
.write_all(&body)
.context("compressing Codebreaker save body")?;
let encrypted = crypt(
encoder
.finish()
.context("compressing Codebreaker save body")?,
);
let title_bytes = save.title.as_bytes();
let header_len = HEADER_MIN.max(
92usize
.checked_add(title_bytes.len())
.and_then(|len| len.checked_add(1))
.ok_or_else(|| anyhow!("Codebreaker title is too long"))?,
);
let stored_len = header_len
.checked_add(encrypted.len())
.ok_or_else(|| anyhow!("Codebreaker save is too large"))?;
let header_len_u32 = u32::try_from(header_len).context("Codebreaker header is too large")?;
let stored_len_u32 = u32::try_from(stored_len).context("Codebreaker save is too large")?;
let body_len_u32 = u32::try_from(body.len()).context("Codebreaker body is too large")?;
let directory_mode = if save.directory_mode & 0x8030 == 0x8020 {
u32::from(save.directory_mode)
} else {
0x8427 // RWX | directory | 0400 | exists
};
let mut header = vec![0u8; header_len];
header[0..4].copy_from_slice(MAGIC);
header[8..12].copy_from_slice(&header_len_u32.to_le_bytes());
header[12..16].copy_from_slice(&body_len_u32.to_le_bytes());
header[16..20].copy_from_slice(&stored_len_u32.to_le_bytes());
header[20..20 + save.directory.len()].copy_from_slice(save.directory.as_bytes());
header[52..60].copy_from_slice(&save.created);
header[60..68].copy_from_slice(&save.modified);
header[76..80].copy_from_slice(&directory_mode.to_le_bytes());
header[92..92 + title_bytes.len()].copy_from_slice(title_bytes);
header.extend_from_slice(&encrypted);
Ok(header)
}
#[cfg(test)]
mod tests {
use super::{crypt, parse};
use super::{crypt, encode, parse};
use crate::save::{SaveFile, SaveImport};
use flate2::write::ZlibEncoder;
use flate2::Compression;
use std::io::Write;
@ -203,4 +309,91 @@ mod tests {
cbs.truncate(100);
assert!(parse(&cbs).is_err());
}
fn sample_save() -> SaveImport {
SaveImport {
directory: "BASLUS-TEST".to_owned(),
directory_mode: 0x8420,
created: [0, 1, 2, 3, 4, 5, 0xe8, 0x07],
modified: [0, 6, 7, 8, 9, 5, 0xe8, 0x07],
title: "Test Save".to_owned(),
files: vec![
SaveFile {
name: "DATA.BIN".to_owned(),
data: vec![0xaa, 0xbb, 0xcc],
mode: 0x8017,
created: [0, 1, 2, 3, 4, 5, 0xe8, 0x07],
modified: [0, 6, 7, 8, 9, 5, 0xe8, 0x07],
},
SaveFile {
name: "EMPTY".to_owned(),
data: vec![],
mode: 0x8417,
created: [0; 8],
modified: [0; 8],
},
],
}
}
fn assert_same_save(expected: &SaveImport, actual: &SaveImport) {
assert_eq!(actual.directory, expected.directory);
assert_eq!(actual.directory_mode, expected.directory_mode);
assert_eq!(actual.created, expected.created);
assert_eq!(actual.modified, expected.modified);
assert_eq!(actual.title, expected.title);
assert_eq!(actual.files.len(), expected.files.len());
for (actual, expected) in actual.files.iter().zip(expected.files.iter()) {
assert_eq!(actual.name, expected.name);
assert_eq!(actual.data, expected.data);
assert_eq!(actual.mode, expected.mode);
assert_eq!(actual.created, expected.created);
assert_eq!(actual.modified, expected.modified);
}
}
#[test]
fn encode_round_trips_through_parse() {
let save = sample_save();
let encoded = encode(&save).unwrap();
let parsed = parse(&encoded).unwrap();
assert_same_save(&save, &parsed);
}
#[test]
fn parsed_save_reencodes_to_equivalent_save() {
let parsed = parse(&sample_cbs()).unwrap();
let reencoded = encode(&parsed).unwrap();
let reparsed = parse(&reencoded).unwrap();
assert_same_save(&parsed, &reparsed);
}
#[test]
fn encode_grows_header_for_long_titles() {
let mut save = sample_save();
save.title = "A".repeat(200);
let encoded = encode(&save).unwrap();
let header_len = u32::from_le_bytes(encoded[8..12].try_into().unwrap()) as usize;
assert_eq!(header_len, 92 + 200 + 1);
assert_eq!(parse(&encoded).unwrap().title, save.title);
}
#[test]
fn encode_rejects_invalid_names_and_modes() {
let mut save = sample_save();
save.directory.clear();
assert!(encode(&save).is_err());
let mut save = sample_save();
save.directory = "X".repeat(33);
assert!(encode(&save).is_err());
let mut save = sample_save();
save.files[0].name = "not-a-file\0name".to_owned();
assert!(encode(&save).is_err());
let mut save = sample_save();
save.files[0].mode = 0x8427; // directory mode, not a regular file
assert!(encode(&save).is_err());
}
}

View file

@ -1,11 +1,13 @@
use anyhow::Result;
use anyhow::{Context, Result};
use clap::{Parser, Subcommand};
use japs2me::codebreaker::format::encode as encode_codebreaker;
use japs2me::memory_card::transaction::add_directory_atomically;
use japs2me::{format_save_table, ImportFile, MemoryCard, SaveImport};
use std::path::Path;
use std::io::Write;
use std::path::{Path, PathBuf};
#[derive(Parser)]
#[command(name = "japs2me", about = "Just A PS2 Memory Card Editor")]
#[command(name = "japs2me", version, about = "Just A PS2 Memory Card Editor")]
struct Cli {
#[command(subcommand)]
command: Command,
@ -13,9 +15,22 @@ struct Cli {
#[derive(Subcommand)]
enum Command {
List { card: String },
Delete { card: String, name: String },
Add { card: String, save: String },
List {
card: String,
},
Delete {
card: String,
name: String,
},
Add {
card: String,
save: String,
},
Export {
card: String,
name: String,
output: String,
},
}
fn main() -> Result<()> {
@ -53,6 +68,29 @@ fn main() -> Result<()> {
&files,
)?;
}
Command::Export { card, name, output } => {
let mut card = MemoryCard::open(card, false)?;
let save = card.export_save(&name)?;
let data = encode_codebreaker(&save)?;
write_output_atomically(&output, &data)?;
}
}
Ok(())
}
fn write_output_atomically(output: &str, data: &[u8]) -> Result<()> {
let output = PathBuf::from(output);
if output.symlink_metadata().is_ok() {
anyhow::bail!("output already exists: {}", output.display());
}
let parent = output
.parent()
.filter(|parent| !parent.as_os_str().is_empty());
let mut temp = tempfile::NamedTempFile::new_in(parent.unwrap_or_else(|| Path::new(".")))
.context("creating temporary export file")?;
temp.write_all(data)
.context("writing temporary export file")?;
temp.persist(&output)
.with_context(|| format!("writing {}", output.display()))?;
Ok(())
}

View file

@ -3,6 +3,7 @@ use super::ecc::page_spare;
use super::fat::{ALLOCATED, CHAIN_END, CHAIN_END_UNALLOC};
use super::icon_sys::parse_title;
use super::superblock::Superblock;
use crate::save::{SaveFile, SaveImport};
use anyhow::{anyhow, bail, ensure, Context, Result};
use std::collections::HashSet;
use std::fs::{File, OpenOptions};
@ -396,14 +397,7 @@ impl MemoryCard {
.checked_add(u64::from(file.length))
.ok_or_else(|| anyhow!("save size overflow"))?;
}
let game_title = files
.iter()
.find(|file| file.name.eq_ignore_ascii_case("icon.sys"))
.filter(|icon| icon.length == 964)
.and_then(|icon| self.read_file(icon).ok())
.as_deref()
.and_then(parse_title)
.unwrap_or_else(|| save.name.clone());
let game_title = self.icon_title(&children, &save.name);
summaries.push(SaveSummary {
directory: save.name.clone(),
game_title,
@ -414,6 +408,65 @@ impl MemoryCard {
Ok(summaries)
}
fn icon_title(&mut self, children: &[DirEntry], fallback: &str) -> String {
children
.iter()
.filter(|entry| entry.is_file())
.find(|file| file.name.eq_ignore_ascii_case("icon.sys"))
.filter(|icon| icon.length == 964)
.and_then(|icon| self.read_file(icon).ok())
.as_deref()
.and_then(parse_title)
.unwrap_or_else(|| fallback.to_owned())
}
/// Read a save directory into the shared save model for exporting.
pub fn export_save(&mut self, name: &str) -> Result<SaveImport> {
let save = self
.entries()?
.into_iter()
.find(|entry| entry.name == name)
.ok_or_else(|| anyhow!("save not found: {name}"))?;
ensure!(save.is_dir(), "not a save directory: {name}");
let children = self.directory_entries(save.first_cluster, save.length)?;
let mut files = Vec::new();
for child in children.iter().skip(2) {
if child.mode & DF_EXISTS == 0 {
continue;
}
if child.is_dir() {
bail!("refusing to export nested directory {}", child.name);
}
ensure!(
child.is_file(),
"unsupported directory entry: {}",
child.name
);
let data = self.read_file(child)?;
ensure!(
data.len() == child.length as usize,
"truncated file data: {}",
child.name
);
files.push(SaveFile {
name: child.name.clone(),
data,
mode: child.mode,
created: child.created,
modified: child.modified,
});
}
let title = self.icon_title(&children, &save.name);
Ok(SaveImport {
directory: save.name.clone(),
directory_mode: save.mode,
created: save.created,
modified: save.modified,
title,
files,
})
}
/// Free allocatable space in bytes.
pub fn available_bytes(&mut self) -> Result<u64> {
let mut free_clusters = 0u64;
@ -917,6 +970,93 @@ mod tests {
Ok(())
}
#[test]
fn export_save_round_trips_card_data() -> Result<()> {
let temp = tempdir()?;
let path = temp.path().join("card.ps2");
create_test_card(&path, false);
let icon = sample_icon_sys(b"Test Game", b"Save 1", 16);
let payload = vec![1, 2, 3, 4, 5];
let files = vec![
sample_file("icon.sys", icon),
sample_file("DATA.BIN", payload.clone()),
];
MemoryCard::open(&path, true)?.add_directory(
"BASLUS-TEST",
0x8420,
[0; 8],
[0; 8],
&files,
)?;
let mut card = MemoryCard::open(&path, false)?;
let save = card.export_save("BASLUS-TEST")?;
assert_eq!(save.directory, "BASLUS-TEST");
assert_eq!(save.title, "Test Game Save 1");
assert_eq!(save.files.len(), 2);
let data = save
.files
.iter()
.find(|file| file.name == "DATA.BIN")
.unwrap();
assert_eq!(data.data, payload);
let encoded = crate::codebreaker::format::encode(&save)?;
let parsed = crate::save::SaveImport::parse(&encoded)?;
assert_eq!(parsed.directory, "BASLUS-TEST");
assert_eq!(parsed.title, "Test Game Save 1");
assert_eq!(parsed.files.len(), 2);
assert_eq!(
parsed
.files
.iter()
.find(|file| file.name == "DATA.BIN")
.unwrap()
.data,
payload
);
Ok(())
}
#[test]
fn export_save_rejects_missing_and_nested_saves() -> Result<()> {
let temp = tempdir()?;
let path = temp.path().join("card.ps2");
create_test_card(&path, false);
let files = vec![sample_file("DATA", vec![1, 2, 3])];
MemoryCard::open(&path, true)?.add_directory(
"BASLUS-TEST",
0x8420,
[0; 8],
[0; 8],
&files,
)?;
let mut card = MemoryCard::open(&path, false)?;
assert!(card.export_save("NO-SUCH-SAVE").is_err());
drop(card);
let mut card = MemoryCard::open(&path, true)?;
let save = card
.entries()?
.into_iter()
.find(|entry| entry.name == "BASLUS-TEST")
.unwrap();
let children = card.directory_entries(save.first_cluster, save.length)?;
let index = children
.iter()
.position(|entry| entry.name == "DATA")
.unwrap();
let mut nested = children[index].clone();
nested.mode = DF_RWX | DF_DIR | DF_EXISTS;
card.write_directory_entry(save.first_cluster, index, &nested)?;
drop(card);
let mut card = MemoryCard::open(&path, false)?;
assert!(card.export_save("BASLUS-TEST").is_err());
Ok(())
}
#[test]
fn available_bytes_shrink_after_import() -> Result<()> {
let temp = tempdir()?;