scalachess

The CanPlay typeclass provides different strategies for handling move sequences depending on whether you want to stop at the first error or process the whole list.

Error Handling Strategies

1. All-or-Nothing (play): Returns Left(ErrorStr) if any move in the sequence is invalid. Use this when the entire sequence must be legal.
2. Stop at Error (playWhileValid): Returns the state reached up to the point of the error, the moves that were successfully played, and the error that occurred. This is useful for analyzing where a move sequence went wrong.
3. Folding (foldLeft / foldRight): Allows you to accumulate a value (like a score, a list of captured pieces, or a move tree) while playing moves. If an error occurs, the fold returns the accumulated value and the error.

The Step Abstraction

When using folding or transformation methods, you interact with a Step, which is a tuple: (next: A, move: MoveOrDrop, ply: Ply). This provides the state after the move, the move itself, and the current ply number.

The Variant class defines the rules and properties for different chess variants. You can identify a variant using its Id, LilaKey, or UciKey. The library provides a list of all supported variants via Variant.list.all.

Common variants include:

• Standard (the default)
• Chess960
• Crazyhouse
• Antichess
• Atomic
• Horde
• KingOfTheHill
• ThreeCheck
• RacingKings
• FromPosition

You can retrieve a variant by its ID or key using Variant(id) or Variant(key). If you want to ensure you always have a valid variant, use orDefault to fall back to Standard if the lookup fails.

// Accessing variants
val standard = Variant.default
val chess960 = Variant.list.all.find(_.chess960).get

// Lookup by ID or Key
val variantById = Variant(someId)
val variantByKey = Variant(LilaKey("crazyhouse"))

// Fallback to default
val safeVariant = Variant(unknownId).orDefault

In scalachess, PGN (Portable Game Notation) metadata is handled using Tag objects and a Tags collection.

• A Tag consists of a TagType (the name) and a String value. Tags are automatically escaped (e.g., quotes and backslashes) when converted to a string.
• Tags is a wrapper around a List[Tag] that provides high-level methods to extract specific chess metadata like player names, ratings, FEN, and results.

Common extraction patterns include:

• tags.names: Returns a ByColor object containing Option[PlayerName] for White and Black.
• tags.ratings: Returns a ByColor object containing Option[IntRating] for White and Black.
• tags.fen: Returns the Option[FullFen] if the [FEN] tag is present.
• tags.outcome: Returns the Option[Outcome] parsed from the [Result] tag.
• tags.variant: Returns the Option[chess.variant.Variant] (e.g., Chess960, ThreeCheck).

The FenWriter trait provides methods to convert chess Position and Game objects into Forsyth-Edwards Notation (FEN) strings. It supports standard FEN, full FEN (including move numbers and clocks), and extensions for variants like Crazyhouse and Three-Check.

Available methods:

• write(position: Position): FullFen: Generates a full FEN string. If no move number is provided, it defaults to FullMoveNumber(1).
• write(position: Position, fullMoveNumber: FullMoveNumber): FullFen: Generates a full FEN string with a specific move number.
• write(parsed: Position.AndFullMoveNumber): FullFen: Generates a full FEN string from a parsed position object.
• write(game: Game): FullFen: Generates a full FEN string based on the current position and move number of a Game.
• writeOpening(position: Position): StandardFen: Generates a standard FEN string (board, active color, castling rights, and en passant target) without move clocks or move numbers.
• writeBoardAndColor(position: Position, turnColor: Color): BoardAndColorFen: Generates a FEN string containing only the board state and the active color.

// Example usage of FenWriter
val fen = fenWriter.write(position)
val openingFen = fenWriter.writeOpening(position)