Sage is a cross-platform chess library for Swift.
Development happens in the develop
branch.
- Chess game management
- Chess board structuring
- Move generation / validation
- En passant and castling
- Pawn promotions
- FEN for games and boards
- PGN parsing and exporting
- Documentation
- Platforms:
- macOS 10.9+
- iOS 8.0+
- watchOS 2.0+
- tvOS 9.0+
- Linux
- Xcode 10.2.1
- Swift 4.2 (Swift 5 compatibility coming soon)
The Swift Package Manager is a decentralized dependency manager for Swift.
-
Add the project to your
Package.swift
.import PackageDescription let package = Package( name: "MyAwesomeProject", dependencies: [ .Package(url: "https://github.com/SuperGeroy/Sage.git", majorVersion: 2) ] )
-
Import the Sage module.
import Sage
-
Download and drop the
/Sources
folder into your project. -
Congratulations!
Running a chess game can be as simple as setting up a loop.
import Sage
let game = Game()
while !game.isFinished {
let move = ...
try game.execute(move: move)
}
Moves for a Game
instance can be executed with execute(move:)
and its unsafe
(yet faster) sibling, execute(uncheckedMove:)
.
The execute(uncheckedMove:)
method assumes that the passed move is legal. It
should only be called if you absolutely know this is true. Such a case is when
using a move returned by availableMoves()
. Otherwise use execute(move:)
,
which checks the legality of the passed move.
Sage is capable of generating legal moves for the current player with full support for special moves such as en passant and castling.
-
availableMoves()
will return all moves currently available. -
movesForPiece(at:)
will return all moves for a piece at a square. -
movesBitboardForPiece(at:)
will return aBitboard
containing all of the squares a piece at a square can move to.
Sage can also validate whether a move is legal with the isLegal(move:)
method for a Game
state.
The execute(move:)
family of methods calls this method, so it would be faster
to execute the move directly and catch any error from an illegal move.
Move undo and redo operations are done with the undoMove()
and redoMove()
methods. The undone or redone move is returned.
To just check what moves are to be undone or redone, the moveToUndo()
and
moveToRedo()
methods are available.
The execute(move:promotion:)
method takes a closure that returns a promotion
piece kind. This allows for the app to prompt the user for a promotion piece or
perform any other operations before choosing a promotion piece kind.
try game.execute(move: move) {
...
return .queen
}
The closure is only executed if the move is a pawn promotion. An error is thrown if the promotion piece kind cannot promote a pawn, such as with a king or pawn.
A piece kind can also be given without a closure. The default is a queen.
try game.execute(move: move, promotion: .queen)
The Board
and Bitboard
types both have an ascii
property that can be used
to print a visual board.
let board = Board()
board.ascii
// +-----------------+
// 8 | r n b q k b n r |
// 7 | p p p p p p p p |
// 6 | . . . . . . . . |
// 5 | . . . . . . . . |
// 4 | . . . . . . . . |
// 3 | . . . . . . . . |
// 2 | P P P P P P P P |
// 1 | R N B Q K B N R |
// +-----------------+
// a b c d e f g h
board.occupiedSpaces.ascii
// +-----------------+
// 8 | 1 1 1 1 1 1 1 1 |
// 7 | 1 1 1 1 1 1 1 1 |
// 6 | . . . . . . . . |
// 5 | . . . . . . . . |
// 4 | . . . . . . . . |
// 3 | . . . . . . . . |
// 2 | 1 1 1 1 1 1 1 1 |
// 1 | 1 1 1 1 1 1 1 1 |
// +-----------------+
// a b c d e f g h
The Game.Position
and Board
types can both generate a FEN string.
let game = Game()
game.position.fen()
// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1
game.board.fen()
// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR
They can also be initialized from a FEN string.
assert(Board(fen: game.board.fen()) == game.board)
assert(Game.Position(fen: game.position.fen()) == game.position)
The Board
type conforms to Sequence
, making iterating through its spaces
seamless.
for space in Board() {
if let piece = space.piece {
print("\(piece) at \(space.square)")
}
}
Sequence
and Square
have two methods that return an array of moves that go
from/to self
to/from the parameter.
[.a1, .h3, .b5].moves(from: .b4)
// [b4 >>> a1, b4 >>> h3, b4 >>> b5]
[.c3, .d2, .f1].moves(to: .a6)
// [c3 >>> a6, d2 >>> a6, f1 >>> a6]
Square.d4.moves(from: [.c2, .f8, .h2])
// [c2 >>> d4, f8 >>> d4, h2 >>> d4]
Square.a4.moves(to: [.c3, .d4, .f6])
// [a4 >>> c3, a4 >>> d4, a4 >>> f6]
To use Sage.playground
, first open Sage.xcodeproj
and build the OS X target.
You can then use the playground from within the project.
Board
conforms to the CustomPlaygroundDisplayConvertible
protocol.
I work on this in my free time and do my best to make it as great as it can be. If you want to help me keep pushing out awesome libraries like this, a donation would be greatly appreciated. 😄
Sage and its modifications are published under version 2.0 of the Apache License.