Struct SavedGame 

pub struct SavedGame {
    pub title: String,
    pub solved_by: String,
    pub notes: String,
    pub current_move_idx: usize,
    /* private fields */
}

Sequence of pusher steps with accompanying metadata (ie. title, author, etc..).

Besides movement direction, SavedGame also represents:

• forward or reverse SolvingMode
• pusher jumps (in reverse solving mode)
• pusher selection steps on boards with multiple pushers (Multiban)

A saved game is tied to the physical board it was recorded against. Mirroring, rotating, resizing, or trimming that board can invalidate movement directions and piece positions. The mismatch is not detected automatically and not enforced anywhere. GameBoard and SavedGame are separate structures, and the client is expected to maintain the relationship between them.

Examples

let saved_game = SavedGame::parsed("llRRddsssSSSnNN", Tessellation::Hexoban)?;
let saved_game = SavedGame::parsed("nlLNrr", Tessellation::Trioban)?;

assert_eq!(saved_game[3].direction(), Direction::NorthEast);
assert_eq!(saved_game[3], Step::PushOrPull(Direction::NorthEast));

Editing

SavedGame is not editable in a sense where Steps can be added, removed, inserted or modified. This is by design. This type is meant for archival purposes, as an input of Sokoban data to writers and as output of Sokoban data readers. Game engines and solvers will need to use their own structures to track movement history. At the end of solving session, they may use SavedGame to archive progress of that session.

Step counts, and the metrics that are not here

moves_count() and pushes_count() are facts about the step sequence, so they live here.

The rest of the standard metric set does not. Box lines and box changes need to know which box each push moved, and no saved game text format encodes box identity, so they can only be had by replaying the steps against a GameBoard. Replaying a game is playing it and that is out of scope for this crate.

Solutions

Whether a SavedGame solves a board, how far it replays on one, and what its SolvingMode::Reverse solution looks like played forwards are all questions about playing rather than about what is recorded, so again - out of scope for this crate. Nothing here plays, validates or edits a game: game engines and solvers keep their own board state, and are expected to track these as they go rather than replay a SavedGame to recover them.

Serde

With the serde feature, SavedGame is a map whose steps are the same text a .sok file would carry:

{
  "tessellation": "Sokoban",
  "moves": "[]LuR",
  "title": "",
  "solved_by": "",
  "notes": "",
  "current_move_idx": 0
}

There is deliberately no solving_mode field. SolvingMode::Reverse is always encoded in the text itself as a leading jump section ([] when the game does not open with a jump), so the moves are the single source of truth and no document can declare a mode contradicting its own steps. A solving_mode key is rejected rather than silently ignored, as are all other unknown fields.

Everything except tessellation and moves may be omitted. current_move_idx is special: the parser reads it from a * marker inside the moves text, so omitting the field keeps whatever the text says, while providing it overrides that. An empty moves string is the empty SolvingMode::Forward game (an empty reverse game prints as "[]").

use sokoban_elements::*;

let saved_game = SavedGame::parsed("lurd", Tessellation::Sokoban)?;

let json = serde_json::to_string(&saved_game)?;
assert_eq!(serde_json::from_str::<SavedGame>(&json)?, saved_game);

Fields

title: String

solved_by: String

notes: String

current_move_idx: usize

Index of currently played move from steps().

This can be found in some sokoban file formats so SavedGame has a place for it. On the other hand, SavedGame doesn’t use it in any way, so it doesn’t validate it against steps() either. SavedGame clients are advised to maintain and validate this value themselves.

Implementations

impl SavedGame

pub fn parsed( data: &str, tessellation: Tessellation, ) -> Result<Self, SavedGameSyntaxError>

Constructs SavedGame from parsed string of moves in context of Tessellation.

Examples

let saved_game: SavedGame = SavedGame::parsed("lurdLurd", Tessellation::Sokoban)?;

Grammar

Save game strings use following characters:

	char
Move pusher	‘l’, ‘u’, ‘r’, ‘d’, ‘w’, ‘e’, ‘n’, ‘s’
Push/pull box	‘L’, ‘U’, ‘R’, ‘D’, ‘W’, ‘E’, ‘N’, ‘S’
Begin jump	‘[’
End jump	‘]’
Begin pusher change	‘{’
End pusher change	‘{’
Current position	‘*’

Mapping between characters and movement direction depends on Tessellation context and is not the same in every Tessellation. Also, not all Tessellations use all movement characters, so this method may return error if it finds legal movement character but in wrong game tessellation context. Ie. Sokoban will return error for character 'W'.

SavedGame strings mostly follow SokobanYASC specification:

::::::::::::::::::::::::::: Moves ::::::::::::::::::::::::::
::                                                        ::
:: Remarks:                                               ::
::                                                        ::
::   Moves may be run-length encoded, e.g., "3r4U" means  ::
::   "rrrUUUU", and "2(3(dr)R)" means "drdrdrRdrdrdrR".   ::
::   Each line must, however, have at least one proper    ::
::   non-digit character. Spaces between moves are        ::
::   allowed.                                             ::
::                                                        ::
::   Jumps and pulls: Only in reverse mode saved games    ::
::   and solutions.                                       ::
::                                                        ::
::   Reverse mode saved games and solutions must begin    ::
::   with a jump, even if it is empty. An example:        ::
::   "[]U[rr]d".                                          ::
::                                                        ::
::   Pusher changes: Only in puzzles with multiple        ::
::   pushers, e.g., Multiban. Moves inside the braces     ::
::   depict the relative movement to get from the         ::
::   currently active pusher to the next active pusher.   ::
::   At game start, a "{...}" sequence activates the      ::
::   pusher relative to the top-left pusher. An example:  ::
::   "{rddd}Urr{uul}uLU". If the top-left pusher is the   ::
::   first active pusher, then the empty "{}" can be      ::
::   omitted.                                             ::
::                                                        ::
::   The current position is optional and defaults to the ::
::   position after the last move.                        ::
::                                                        ::
::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

• Moves grammar
• RLE grammar

pub fn from_steps( data: &[Step], tessellation: Tessellation, solving_mode: Option<SolvingMode>, ) -> Result<Self, SavedGameSyntaxError>

Constructs new SavedGame from sequence of Step, validating each of them in context of given game tessellation.

• if data contains Step::Jump, marks created SavedGame as SolvingMode::Reverse
• if data doesn’t contain Step::Jump uses value of solving_mode argument

Examples

use sokoban_elements::*;

let moves = vec![
    Step::Move(Direction::Down),
    Step::PushOrPull(Direction::Down),
    Step::PushOrPull(Direction::Down),
    Step::Jump(Direction::Down),
    Step::Jump(Direction::Down),
    Step::Move(Direction::Down),
];

let saved_game: SavedGame =
    SavedGame::from_steps(&moves, Tessellation::Sokoban, Some(SolvingMode::Forward))?;

assert_eq!(saved_game.solving_mode(), SolvingMode::Reverse);

pub fn printed_steps(&self) -> String

Serializes steps() into saved game string.

pub fn solving_mode(&self) -> SolvingMode

SolvingMode this SavedGame was recorded in.

pub fn tessellation(&self) -> Tessellation

Tessellation this SavedGame was recorded against.

pub fn steps(&self) -> &[Step]

Slice of Steps in this SavedGame.

pub fn len(&self) -> usize

Total number of steps in this SavedGame.

pub fn is_empty(&self) -> bool

True if this SavedGame has no steps.

pub fn moves_count(&self) -> usize

Total number of Step::Move steps in this SavedGame.

pub fn pushes_count(&self) -> usize

Total number of Step::PushOrPull steps in this SavedGame.

Trait Implementations

impl Clone for SavedGame

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SavedGame

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for SavedGame

fn deserialize<D: Deserializer<'de>>(deserializer: D) -> Result<Self, D::Error>

Deserialize this value from the given Serde deserializer.

impl Index<usize> for SavedGame

type Output = Step

The returned type after indexing.

fn index(&self, index: usize) -> &Self::Output

Performs the indexing (container[index]) operation.

impl PartialEq for SavedGame

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

Equality operator ==.

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

Inequality operator !=.

impl Serialize for SavedGame

fn serialize<S: Serializer>(&self, serializer: S) -> Result<S::Ok, S::Error>

Serialize this value into the given Serde serializer.

impl StructuralPartialEq for SavedGame