Struct Save 

pub struct Save {
    pub character: Character,
    pub quests: Quests,
    pub waypoints: Waypoints,
    pub npcs: Placeholder,
    pub attributes: Attributes,
    pub skills: SkillPoints,
    pub items: Placeholder,
    /* private fields */
}

Full in-memory save model.

Unknown payloads for unmodeled sections are preserved in placeholder structs. Invariants:

• format() and version() are synchronized through set_format.
• expansion_type() is canonical and must be changed through set_expansion_type.
• Character/attribute level must be changed through set_level.

Fields

character: Character

Character section.

quests: Quests

Quests section.

waypoints: Waypoints

Waypoints section.

npcs: Placeholder

NPC section (placeholder model).

attributes: Attributes

Attributes section.

skills: SkillPoints

Skills section.

items: Placeholder

Items section (placeholder model).

Implementations

impl Save

pub fn new(format: FormatId, class: Class) -> Save

Build a new blank save for a target format/class.

V99 defaults to Expansion; V105 and unknown formats default to RotW. Call set_expansion_type afterward if you need Classic.

pub fn format(&self) -> FormatId

Examples found in repository

examples/inspect_issues.rs (line 11)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Start from a known good file.
    let bytes = std::fs::read("assets/test/Joe.d2s")?;

    // Strict mode fails fast on invalid data.
    let strict = Save::parse(&bytes, Strictness::Strict)?;
    println!(
        "Strict parse OK: format={:?}, name={}",
        strict.save.format(),
        strict.save.character.name
    );

    // Validation is separate from parsing, so check the save on its own.
    let validation = strict.save.validate();
    println!("\nValidation issues: {}", validation.issues.len());
    for (index, issue) in validation.issues.iter().enumerate() {
        println!("#{index} [{:?}] {}", issue.code, issue.message);
    }

    // Break the payload on purpose so we can inspect non-fatal issues.
    // - byte 0 breaks signature
    // - truncation simulates a damaged or incomplete file
    let mut damaged = bytes.clone();
    damaged[0] = 0x00;
    damaged.truncate(220);

    // Lax mode keeps going and collects issues.
    let lax = Save::parse(&damaged, Strictness::Lax)?;
    println!("\nLax parse issues: {}", lax.issues.len());
    for (index, issue) in lax.issues.iter().enumerate() {
        println!(
            "#{index} [{:?}/{:?}] section={:?} offset={:?} expected={:?} found={:?}\n  {}",
            issue.severity,
            issue.kind,
            issue.section,
            issue.offset,
            issue.expected,
            issue.found,
            issue.message
        );
    }

    // Strict mode should reject the damaged payload.
    match Save::parse(&damaged, Strictness::Strict) {
        Ok(_) => println!("\nUnexpected: strict parse accepted damaged payload."),
        Err(error) => println!("\nStrict parse error: {error}"),
    }

    Ok(())
}

examples/edit_character.rs (line 17)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input_path = "assets/test/Warlock_v105.d2s";
    let output_name = "WarlockDemo";
    let output_dir = "target/example-output";
    let output_path = format!("{output_dir}/{output_name}.d2s");

    let bytes = std::fs::read(input_path)?;
    let parsed = Save::parse(&bytes, Strictness::Strict)?;
    if !parsed.issues.is_empty() {
        return Err(format!("fixture parsed with issues: {:?}", parsed.issues).into());
    }

    let mut save = parsed.save;
    let target_format = save.format();

    println!(
        "Loaded {:?} / {} / lvl {}",
        target_format,
        save.character.name,
        save.character.level()
    );

    // Keep the file name and in-game name aligned.
    save.character.name = output_name.to_string();

    // Keep character.level and attributes.level in sync.
    save.set_level(75);

    // Main stats.
    save.attributes.strength.value = 220;
    save.attributes.dexterity.value = 175;
    save.attributes.vitality.value = 260;
    save.attributes.energy.value = 110;
    save.attributes.statpts.value = 25;
    save.attributes.newskills.value = 10;
    save.attributes.gold.value = 200_000;
    save.attributes.goldbank.value = 2_500_000;

    // These stats are fixed-point in the save file (Q8), so the helpers take in-game values.
    save.attributes.set_max_hp(2200);
    save.attributes.set_hp(2200);
    save.attributes.set_max_mana(900);
    save.attributes.set_mana(900);
    save.attributes.set_max_stamina(1200);
    save.attributes.set_stamina(1200);

    // Use the D2R name lookup when it exists.
    // Fall back to raw slot indexes when it does not.
    if save.skills.set_by_name_d2r(save.character.class, "Bash", 20).is_err() {
        save.skills.set(0, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Battle Orders", 20).is_err() {
        save.skills.set(23, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Whirlwind", 20).is_err() {
        save.skills.set(25, 20);
    }

    // Give Act I all waypoints.
    save.waypoints.normal.act1.set_all(true);

    // Edit one quest state.
    save.quests.normal.act1.q1.state.insert(QuestFlag::Started);

    let act1_catacombs = save.waypoints.normal.act1.get_by_index(8)?;
    let quest_started = save.quests.normal.act1.q1.state.contains(&QuestFlag::Started);

    // Write back to the same detected format.
    let output_bytes = save.encode_for(target_format, CompatibilityChecks::Enforce)?;
    std::fs::create_dir_all(output_dir)?;
    std::fs::write(&output_path, output_bytes)?;

    println!("Wrote {output_path}");
    println!("Now: {} / lvl {}", save.character.name, save.character.level());
    println!(
        "Stats: str={} dex={} vit={} ene={}",
        save.attributes.strength.value,
        save.attributes.dexterity.value,
        save.attributes.vitality.value,
        save.attributes.energy.value
    );
    println!(
        "Resources: hp={} mana={} stamina={}",
        save.attributes.get_max_hp(),
        save.attributes.get_max_mana(),
        save.attributes.get_max_stamina()
    );
    println!("Act I / Catacombs waypoint: {act1_catacombs}");
    println!("Quest q1 started: {quest_started}");

    Ok(())
}

pub fn version(&self) -> u32

Header version synchronized with the save format.

pub fn set_format(&mut self, format: FormatId)

Set output format and synchronize the numeric version field.

pub fn game_edition(&self) -> Option<GameEdition>

pub fn set_level(&mut self, level: u8)

Set both character level fields kept in separate sections.

Examples found in repository

examples/edit_character.rs (line 30)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input_path = "assets/test/Warlock_v105.d2s";
    let output_name = "WarlockDemo";
    let output_dir = "target/example-output";
    let output_path = format!("{output_dir}/{output_name}.d2s");

    let bytes = std::fs::read(input_path)?;
    let parsed = Save::parse(&bytes, Strictness::Strict)?;
    if !parsed.issues.is_empty() {
        return Err(format!("fixture parsed with issues: {:?}", parsed.issues).into());
    }

    let mut save = parsed.save;
    let target_format = save.format();

    println!(
        "Loaded {:?} / {} / lvl {}",
        target_format,
        save.character.name,
        save.character.level()
    );

    // Keep the file name and in-game name aligned.
    save.character.name = output_name.to_string();

    // Keep character.level and attributes.level in sync.
    save.set_level(75);

    // Main stats.
    save.attributes.strength.value = 220;
    save.attributes.dexterity.value = 175;
    save.attributes.vitality.value = 260;
    save.attributes.energy.value = 110;
    save.attributes.statpts.value = 25;
    save.attributes.newskills.value = 10;
    save.attributes.gold.value = 200_000;
    save.attributes.goldbank.value = 2_500_000;

    // These stats are fixed-point in the save file (Q8), so the helpers take in-game values.
    save.attributes.set_max_hp(2200);
    save.attributes.set_hp(2200);
    save.attributes.set_max_mana(900);
    save.attributes.set_mana(900);
    save.attributes.set_max_stamina(1200);
    save.attributes.set_stamina(1200);

    // Use the D2R name lookup when it exists.
    // Fall back to raw slot indexes when it does not.
    if save.skills.set_by_name_d2r(save.character.class, "Bash", 20).is_err() {
        save.skills.set(0, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Battle Orders", 20).is_err() {
        save.skills.set(23, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Whirlwind", 20).is_err() {
        save.skills.set(25, 20);
    }

    // Give Act I all waypoints.
    save.waypoints.normal.act1.set_all(true);

    // Edit one quest state.
    save.quests.normal.act1.q1.state.insert(QuestFlag::Started);

    let act1_catacombs = save.waypoints.normal.act1.get_by_index(8)?;
    let quest_started = save.quests.normal.act1.q1.state.contains(&QuestFlag::Started);

    // Write back to the same detected format.
    let output_bytes = save.encode_for(target_format, CompatibilityChecks::Enforce)?;
    std::fs::create_dir_all(output_dir)?;
    std::fs::write(&output_path, output_bytes)?;

    println!("Wrote {output_path}");
    println!("Now: {} / lvl {}", save.character.name, save.character.level());
    println!(
        "Stats: str={} dex={} vit={} ene={}",
        save.attributes.strength.value,
        save.attributes.dexterity.value,
        save.attributes.vitality.value,
        save.attributes.energy.value
    );
    println!(
        "Resources: hp={} mana={} stamina={}",
        save.attributes.get_max_hp(),
        save.attributes.get_max_mana(),
        save.attributes.get_max_stamina()
    );
    println!("Act I / Catacombs waypoint: {act1_catacombs}");
    println!("Quest q1 started: {quest_started}");

    Ok(())
}

pub fn expansion_type(&self) -> ExpansionType

pub fn set_expansion_type(&mut self, expansion_type: ExpansionType)

pub fn parse( byte_slice: &[u8], strictness: Strictness, ) -> Result<ParsedSave, ParseHardError>

Parse a save with explicit strictness.

Examples found in repository

examples/inspect_issues.rs (line 8)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Start from a known good file.
    let bytes = std::fs::read("assets/test/Joe.d2s")?;

    // Strict mode fails fast on invalid data.
    let strict = Save::parse(&bytes, Strictness::Strict)?;
    println!(
        "Strict parse OK: format={:?}, name={}",
        strict.save.format(),
        strict.save.character.name
    );

    // Validation is separate from parsing, so check the save on its own.
    let validation = strict.save.validate();
    println!("\nValidation issues: {}", validation.issues.len());
    for (index, issue) in validation.issues.iter().enumerate() {
        println!("#{index} [{:?}] {}", issue.code, issue.message);
    }

    // Break the payload on purpose so we can inspect non-fatal issues.
    // - byte 0 breaks signature
    // - truncation simulates a damaged or incomplete file
    let mut damaged = bytes.clone();
    damaged[0] = 0x00;
    damaged.truncate(220);

    // Lax mode keeps going and collects issues.
    let lax = Save::parse(&damaged, Strictness::Lax)?;
    println!("\nLax parse issues: {}", lax.issues.len());
    for (index, issue) in lax.issues.iter().enumerate() {
        println!(
            "#{index} [{:?}/{:?}] section={:?} offset={:?} expected={:?} found={:?}\n  {}",
            issue.severity,
            issue.kind,
            issue.section,
            issue.offset,
            issue.expected,
            issue.found,
            issue.message
        );
    }

    // Strict mode should reject the damaged payload.
    match Save::parse(&damaged, Strictness::Strict) {
        Ok(_) => println!("\nUnexpected: strict parse accepted damaged payload."),
        Err(error) => println!("\nStrict parse error: {error}"),
    }

    Ok(())
}

examples/waypoints.rs (line 6)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bytes = std::fs::read("assets/test/Joe.d2s")?;
    let parsed = Save::parse(&bytes, Strictness::Strict)?;
    let mut save = parsed.save;

    // Read by index.
    let catacombs_was_unlocked = save.waypoints.hell.act1.get_by_index(8)?;
    println!("Hell Act I / Catacombs unlocked: {catacombs_was_unlocked}");

    // Set by waypoint id.
    save.waypoints.hell.act1.set(Waypoint::Catacombs, true)?;
    let catacombs_is_unlocked = save.waypoints.hell.act1.get(Waypoint::Catacombs)?;
    println!("Hell Act I / Catacombs now unlocked: {catacombs_is_unlocked}");

    // Set by index.
    save.waypoints.normal.act4.set_by_index(2, true)?;
    println!(
        "Normal Act IV / River of Flames unlocked: {}",
        save.waypoints.normal.act4.get_by_index(2)?
    );

    // Bulk update one difficulty.
    save.waypoints.nightmare.set_all(true);
    println!(
        "Nightmare Act II / Sewers unlocked after set_all: {}",
        save.waypoints.nightmare.act2.get_by_index(1)?
    );

    // Wrong-act usage returns an explicit error.
    match save.waypoints.normal.act1.set(Waypoint::LutGholein, true) {
        Err(WaypointError::WrongAct { waypoint, expected, actual }) => {
            println!("WrongAct: {waypoint:?} belongs to {actual:?}, expected {expected:?}.")
        }
        Ok(_) => println!("Unexpected: wrong-act set was accepted."),
        Err(error) => println!("Unexpected waypoint error: {error}"),
    }

    // Out-of-range reads return an explicit error.
    match save.waypoints.normal.act4.get_by_index(3) {
        Err(WaypointError::IndexOutOfRange { act, index, max_index }) => {
            println!("IndexOutOfRange: {act:?} index {index} (max {max_index}).")
        }
        Ok(_) => println!("Unexpected: out-of-range read was accepted."),
        Err(error) => println!("Unexpected waypoint error: {error}"),
    }

    Ok(())
}

examples/edit_character.rs (line 11)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input_path = "assets/test/Warlock_v105.d2s";
    let output_name = "WarlockDemo";
    let output_dir = "target/example-output";
    let output_path = format!("{output_dir}/{output_name}.d2s");

    let bytes = std::fs::read(input_path)?;
    let parsed = Save::parse(&bytes, Strictness::Strict)?;
    if !parsed.issues.is_empty() {
        return Err(format!("fixture parsed with issues: {:?}", parsed.issues).into());
    }

    let mut save = parsed.save;
    let target_format = save.format();

    println!(
        "Loaded {:?} / {} / lvl {}",
        target_format,
        save.character.name,
        save.character.level()
    );

    // Keep the file name and in-game name aligned.
    save.character.name = output_name.to_string();

    // Keep character.level and attributes.level in sync.
    save.set_level(75);

    // Main stats.
    save.attributes.strength.value = 220;
    save.attributes.dexterity.value = 175;
    save.attributes.vitality.value = 260;
    save.attributes.energy.value = 110;
    save.attributes.statpts.value = 25;
    save.attributes.newskills.value = 10;
    save.attributes.gold.value = 200_000;
    save.attributes.goldbank.value = 2_500_000;

    // These stats are fixed-point in the save file (Q8), so the helpers take in-game values.
    save.attributes.set_max_hp(2200);
    save.attributes.set_hp(2200);
    save.attributes.set_max_mana(900);
    save.attributes.set_mana(900);
    save.attributes.set_max_stamina(1200);
    save.attributes.set_stamina(1200);

    // Use the D2R name lookup when it exists.
    // Fall back to raw slot indexes when it does not.
    if save.skills.set_by_name_d2r(save.character.class, "Bash", 20).is_err() {
        save.skills.set(0, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Battle Orders", 20).is_err() {
        save.skills.set(23, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Whirlwind", 20).is_err() {
        save.skills.set(25, 20);
    }

    // Give Act I all waypoints.
    save.waypoints.normal.act1.set_all(true);

    // Edit one quest state.
    save.quests.normal.act1.q1.state.insert(QuestFlag::Started);

    let act1_catacombs = save.waypoints.normal.act1.get_by_index(8)?;
    let quest_started = save.quests.normal.act1.q1.state.contains(&QuestFlag::Started);

    // Write back to the same detected format.
    let output_bytes = save.encode_for(target_format, CompatibilityChecks::Enforce)?;
    std::fs::create_dir_all(output_dir)?;
    std::fs::write(&output_path, output_bytes)?;

    println!("Wrote {output_path}");
    println!("Now: {} / lvl {}", save.character.name, save.character.level());
    println!(
        "Stats: str={} dex={} vit={} ene={}",
        save.attributes.strength.value,
        save.attributes.dexterity.value,
        save.attributes.vitality.value,
        save.attributes.energy.value
    );
    println!(
        "Resources: hp={} mana={} stamina={}",
        save.attributes.get_max_hp(),
        save.attributes.get_max_mana(),
        save.attributes.get_max_stamina()
    );
    println!("Act I / Catacombs waypoint: {act1_catacombs}");
    println!("Quest q1 started: {quest_started}");

    Ok(())
}

pub fn summarize( byte_slice: &[u8], strictness: Strictness, ) -> Result<SaveSummary, ParseHardError>

Summarize only top-level header + character fields.

pub fn encode_for( &self, format: FormatId, compatibility_checks: CompatibilityChecks, ) -> Result<Vec<u8>, EncodeError>

Encode to a specific output format with an explicit compatibility policy.

Examples found in repository

examples/edit_character.rs (line 72)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let input_path = "assets/test/Warlock_v105.d2s";
    let output_name = "WarlockDemo";
    let output_dir = "target/example-output";
    let output_path = format!("{output_dir}/{output_name}.d2s");

    let bytes = std::fs::read(input_path)?;
    let parsed = Save::parse(&bytes, Strictness::Strict)?;
    if !parsed.issues.is_empty() {
        return Err(format!("fixture parsed with issues: {:?}", parsed.issues).into());
    }

    let mut save = parsed.save;
    let target_format = save.format();

    println!(
        "Loaded {:?} / {} / lvl {}",
        target_format,
        save.character.name,
        save.character.level()
    );

    // Keep the file name and in-game name aligned.
    save.character.name = output_name.to_string();

    // Keep character.level and attributes.level in sync.
    save.set_level(75);

    // Main stats.
    save.attributes.strength.value = 220;
    save.attributes.dexterity.value = 175;
    save.attributes.vitality.value = 260;
    save.attributes.energy.value = 110;
    save.attributes.statpts.value = 25;
    save.attributes.newskills.value = 10;
    save.attributes.gold.value = 200_000;
    save.attributes.goldbank.value = 2_500_000;

    // These stats are fixed-point in the save file (Q8), so the helpers take in-game values.
    save.attributes.set_max_hp(2200);
    save.attributes.set_hp(2200);
    save.attributes.set_max_mana(900);
    save.attributes.set_mana(900);
    save.attributes.set_max_stamina(1200);
    save.attributes.set_stamina(1200);

    // Use the D2R name lookup when it exists.
    // Fall back to raw slot indexes when it does not.
    if save.skills.set_by_name_d2r(save.character.class, "Bash", 20).is_err() {
        save.skills.set(0, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Battle Orders", 20).is_err() {
        save.skills.set(23, 20);
    }
    if save.skills.set_by_name_d2r(save.character.class, "Whirlwind", 20).is_err() {
        save.skills.set(25, 20);
    }

    // Give Act I all waypoints.
    save.waypoints.normal.act1.set_all(true);

    // Edit one quest state.
    save.quests.normal.act1.q1.state.insert(QuestFlag::Started);

    let act1_catacombs = save.waypoints.normal.act1.get_by_index(8)?;
    let quest_started = save.quests.normal.act1.q1.state.contains(&QuestFlag::Started);

    // Write back to the same detected format.
    let output_bytes = save.encode_for(target_format, CompatibilityChecks::Enforce)?;
    std::fs::create_dir_all(output_dir)?;
    std::fs::write(&output_path, output_bytes)?;

    println!("Wrote {output_path}");
    println!("Now: {} / lvl {}", save.character.name, save.character.level());
    println!(
        "Stats: str={} dex={} vit={} ene={}",
        save.attributes.strength.value,
        save.attributes.dexterity.value,
        save.attributes.vitality.value,
        save.attributes.energy.value
    );
    println!(
        "Resources: hp={} mana={} stamina={}",
        save.attributes.get_max_hp(),
        save.attributes.get_max_mana(),
        save.attributes.get_max_stamina()
    );
    println!("Act I / Catacombs waypoint: {act1_catacombs}");
    println!("Quest q1 started: {quest_started}");

    Ok(())
}

pub fn check_compatibility(&self, target: FormatId) -> Vec<CompatibilityIssue>

Return compatibility findings for encoding this save to target.

pub fn title_d2r(&self) -> Option<&'static str>

Return the default D2R title for this save using the canonical expansion mode.

pub fn validate(&self) -> ValidationReport

Validate the current save using backend-owned canonical rules.

Examples found in repository

examples/inspect_issues.rs (line 16)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Start from a known good file.
    let bytes = std::fs::read("assets/test/Joe.d2s")?;

    // Strict mode fails fast on invalid data.
    let strict = Save::parse(&bytes, Strictness::Strict)?;
    println!(
        "Strict parse OK: format={:?}, name={}",
        strict.save.format(),
        strict.save.character.name
    );

    // Validation is separate from parsing, so check the save on its own.
    let validation = strict.save.validate();
    println!("\nValidation issues: {}", validation.issues.len());
    for (index, issue) in validation.issues.iter().enumerate() {
        println!("#{index} [{:?}] {}", issue.code, issue.message);
    }

    // Break the payload on purpose so we can inspect non-fatal issues.
    // - byte 0 breaks signature
    // - truncation simulates a damaged or incomplete file
    let mut damaged = bytes.clone();
    damaged[0] = 0x00;
    damaged.truncate(220);

    // Lax mode keeps going and collects issues.
    let lax = Save::parse(&damaged, Strictness::Lax)?;
    println!("\nLax parse issues: {}", lax.issues.len());
    for (index, issue) in lax.issues.iter().enumerate() {
        println!(
            "#{index} [{:?}/{:?}] section={:?} offset={:?} expected={:?} found={:?}\n  {}",
            issue.severity,
            issue.kind,
            issue.section,
            issue.offset,
            issue.expected,
            issue.found,
            issue.message
        );
    }

    // Strict mode should reject the damaged payload.
    match Save::parse(&damaged, Strictness::Strict) {
        Ok(_) => println!("\nUnexpected: strict parse accepted damaged payload."),
        Err(error) => println!("\nStrict parse error: {error}"),
    }

    Ok(())
}

Trait Implementations

impl Clone for Save

fn clone(&self) -> Save

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Save

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Save

fn default() -> Self

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Save

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Display for Save

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for Save

fn eq(&self, other: &Save) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Serialize for Save

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl Eq for Save

impl StructuralPartialEq for Save