{"id":1143,"url":"https://github.com/nvzqz/Sage","last_synced_at":"2025-08-06T13:32:36.791Z","repository":{"id":62454861,"uuid":"59545562","full_name":"nvzqz/Sage","owner":"nvzqz","description":"A cross-platform chess library for Swift","archived":false,"fork":false,"pushed_at":"2018-10-08T12:58:00.000Z","size":2458,"stargazers_count":375,"open_issues_count":9,"forks_count":44,"subscribers_count":17,"default_branch":"develop","last_synced_at":"2024-07-10T22:59:53.060Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nvzqz.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-05-24T06:14:06.000Z","updated_at":"2024-05-13T13:21:26.000Z","dependencies_parsed_at":"2022-11-02T00:01:32.785Z","dependency_job_id":null,"html_url":"https://github.com/nvzqz/Sage","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvzqz%2FSage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvzqz%2FSage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvzqz%2FSage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nvzqz%2FSage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nvzqz","download_url":"https://codeload.github.com/nvzqz/Sage/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":215780271,"owners_count":15929791,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-01-05T20:15:39.823Z","updated_at":"2024-08-17T16:30:51.163Z","avatar_url":"https://github.com/nvzqz.png","language":"Swift","funding_links":["https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=GZXUDALB3MQRC\u0026lc=US\u0026item_name=Nikolai%20Vazquez\u0026currency_code=USD\u0026bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted"],"categories":["Games","Libs","Games [🔝](#readme)"],"sub_categories":["Getting Started","Games","Other free courses","Linter"],"readme":"### Deprecated\n\nThis project is no longer in development. I am currently developing a chess\nengine, [Hexe]. It is written in Rust, which is very similar to Swift in many\nways. There also exists [Hexe.swift](https://github.com/hexe-rs/Hexe.swift/), a\nSwift wrapper for Hexe.\n\nSage is _not_ a chess engine; it's a move generator. [Hexe], on the other hand,\nis able to both generate moves and evaluate them.\n\n---\n\n[![Sage](https://raw.githubusercontent.com/nvzqz/Sage/assets/Banner.png)](https://github.com/nvzqz/Sage)\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://developer.apple.com/swift/\"\u003e\u003cimg alt=\"Swift 2.2 | 3.0\" src=\"https://img.shields.io/badge/swift-2.2%20%7C%203.0-orange.svg\"\u003e\u003c/a\u003e\n\u003cimg alt=\"Platforms\" src=\"https://img.shields.io/badge/platform-ios%20%7C%20macos%20%7C%20watchos%20%7C%20tvos%20%7C%20linux-lightgrey.svg\"\u003e\n\u003ca href=\"https://gitter.im/nvzqz/Sage?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge\"\u003e\u003cimg alt=\"Gitter\" src=\"https://badges.gitter.im/nvzqz/Sage.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://www.apache.org/licenses/LICENSE-2.0\"\u003e\u003cimg alt=\"Apache 2.0 License\" src=\"https://img.shields.io/badge/license-Apache%202.0-000000.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://cocoapods.org/pods/Sage\"\u003e\u003cimg alt=\"CocoaPods\" src=\"https://img.shields.io/cocoapods/v/Sage.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/Carthage/Carthage\"\u003e\u003cimg alt=\"Carthage\" src=\"https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat\"\u003e\u003c/a\u003e\n\u003ca href=\"https://swift.org/package-manager/\"\u003e\u003cimg alt=\"Swift Package Manager\" src=\"https://img.shields.io/badge/SPM-compatible-orange.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://nvzqz.github.io/Sage/docs/\"\u003e\u003cimg alt=\"Documented\" src=\"https://img.shields.io/badge/documented-%E2%9C%93-brightgreen.svg\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\nSage is a cross-platform chess library for Swift.\n\nDevelopment happens in the [`develop`](https://github.com/nvzqz/Sage/tree/develop) branch.\n\n- [Build Status](#build-status)\n- [Features](#features)\n- [Installation](#installation)\n    - [Compatibility](#compatibility)\n    - [Swift Package Manager](#install-using-swift-package-manager)\n    - [CocoaPods](#install-using-cocoapods)\n    - [Carthage](#install-using-carthage)\n    - [Manually](#install-manually)\n- [Usage](#usage)\n    - [Game Management](#game-management)\n    - [Move Execution](#move-execution)\n    - [Move Generation](#move-generation)\n    - [Move Validation](#move-validation)\n    - [Undo and Redo Moves](#undo-and-redo-moves)\n    - [Promotion Handling](#promotion-handling)\n    - [Pretty Printing](#pretty-printing)\n    - [Forsyth–Edwards Notation](#forsythedwards-notation)\n    - [Iterating Through a Board](#iterating-through-a-board)\n    - [Squares to Moves](#squares-to-moves)\n    - [Playground Usage](#playground-usage)\n        - [Board Quick Look](#board-quick-look)\n- [Donation](#donation)\n- [License](#license)\n\n## Build Status\n\n| Branch    | Status |\n| :-------: | :----: |\n| `master`  | \u003ca href=\"https://travis-ci.org/nvzqz/Sage\"\u003e\u003cimg alt=\"Build Status\" src=\"https://travis-ci.org/nvzqz/Sage.svg?branch=master\"\u003e\u003c/a\u003e  |\n| `develop` | \u003ca href=\"https://travis-ci.org/nvzqz/Sage\"\u003e\u003cimg alt=\"Build Status\" src=\"https://travis-ci.org/nvzqz/Sage.svg?branch=develop\"\u003e\u003c/a\u003e |\n\n## Features\n\n- [x] Chess game management\n- [x] Chess board structuring\n- [x] Move generation / validation\n- [x] En passant and castling\n- [x] Pawn promotions\n- [x] FEN for games and boards\n- [x] PGN parsing and exporting\n- [x] [Documentation](https://nvzqz.github.io/Sage/docs/)\n\n## Installation\n\n### Compatibility\n\n- Platforms:\n    - macOS 10.9+\n    - iOS 8.0+\n    - watchOS 2.0+\n    - tvOS 9.0+\n    - Linux\n- Xcode 7.3 and 8.0\n- Swift 2.2 and 3.0\n\n### Install Using Swift Package Manager\nThe [Swift Package Manager](https://swift.org/package-manager/) is a\ndecentralized dependency manager for Swift.\n\n1. Add the project to your `Package.swift`.\n\n    ```swift\n    import PackageDescription\n\n    let package = Package(\n        name: \"MyAwesomeProject\",\n        dependencies: [\n            .Package(url: \"https://github.com/nvzqz/Sage.git\",\n                     majorVersion: 2)\n        ]\n    )\n    ```\n\n2. Import the Sage module.\n\n    ```swift\n    import Sage\n    ```\n\n### Install Using CocoaPods\n[CocoaPods](https://cocoapods.org/) is a centralized dependency manager for\nObjective-C and Swift. Go [here](https://guides.cocoapods.org/using/index.html)\nto learn more.\n\n1. Add the project to your [Podfile](https://guides.cocoapods.org/using/the-podfile.html).\n\n    ```ruby\n    use_frameworks!\n\n    pod 'Sage', '~\u003e 2.0.0'\n    ```\n\n    If you want to be on the bleeding edge, replace the last line with:\n\n    ```ruby\n    pod 'Sage', :git =\u003e 'https://github.com/nvzqz/Sage.git'\n    ```\n\n2. Run `pod install` and open the `.xcworkspace` file to launch Xcode.\n\n3. Import the Sage framework.\n\n    ```swift\n    import Sage\n    ```\n\n### Install Using Carthage\n[Carthage](https://github.com/Carthage/Carthage) is a decentralized dependency\nmanager for Objective-C and Swift.\n\n1. Add the project to your [Cartfile](https://github.com/Carthage/Carthage/blob/master/Documentation/Artifacts.md#cartfile).\n\n    ```\n    github \"nvzqz/Sage\"\n    ```\n\n2. Run `carthage update` and follow [the additional steps](https://github.com/Carthage/Carthage#getting-started)\n   in order to add Sage to your project.\n\n3. Import the Sage framework.\n\n    ```swift\n    import Sage\n    ```\n\n### Install Manually\n\n1. Download and drop the `/Sources` folder into your project.\n\n2. Congratulations!\n\n## Usage\n\n### Game Management\n\nRunning a chess game can be as simple as setting up a loop.\n\n```swift\nimport Sage\n\nlet game = Game()\n\nwhile !game.isFinished {\n    let move = ...\n    try game.execute(move: move)\n}\n```\n\n### Move Execution\n\nMoves for a `Game` instance can be executed with `execute(move:)` and its unsafe\n(yet faster) sibling, `execute(uncheckedMove:)`.\n\nThe `execute(uncheckedMove:)` method assumes that the passed move is legal. It\nshould only be called if you *absolutely* know this is true. Such a case is when\nusing a move returned by `availableMoves()`. Otherwise use `execute(move:)`,\nwhich checks the legality of the passed move.\n\n### Move Generation\n\nSage is capable of generating legal moves for the current player with full\nsupport for special moves such as en passant and castling.\n\n- `availableMoves()` will return all moves currently available.\n\n- `movesForPiece(at:)` will return all moves for a piece at a square.\n\n- `movesBitboardForPiece(at:)` will return a `Bitboard` containing all of the\n  squares a piece at a square can move to.\n\n### Move Validation\n\nSage can also validate whether a move is legal with the `isLegal(move:)`\nmethod for a `Game` state.\n\nThe `execute(move:)` family of methods calls this method, so it would be faster\nto execute the move directly and catch any error from an illegal move.\n\n### Undo and Redo Moves\n\nMove undo and redo operations are done with the `undoMove()` and `redoMove()`\nmethods. The undone or redone move is returned.\n\nTo just check what moves are to be undone or redone, the `moveToUndo()` and\n`moveToRedo()` methods are available.\n\n### Promotion Handling\n\nThe `execute(move:promotion:)` method takes a closure that returns a promotion\npiece kind. This allows for the app to prompt the user for a promotion piece or\nperform any other operations before choosing a promotion piece kind.\n\n```swift\ntry game.execute(move: move) {\n    ...\n    return .queen\n}\n```\n\nThe closure is only executed if the move is a pawn promotion. An error is thrown\nif the promotion piece kind cannot promote a pawn, such as with a king or pawn.\n\nA piece kind can also be given without a closure. The default is a queen.\n\n```swift\ntry game.execute(move: move, promotion: .queen)\n```\n\n### Pretty Printing\n\nThe `Board` and `Bitboard` types both have an `ascii` property that can be used\nto print a visual board.\n\n```swift\nlet board = Board()\n\nboard.ascii\n//   +-----------------+\n// 8 | r n b q k b n r |\n// 7 | p p p p p p p p |\n// 6 | . . . . . . . . |\n// 5 | . . . . . . . . |\n// 4 | . . . . . . . . |\n// 3 | . . . . . . . . |\n// 2 | P P P P P P P P |\n// 1 | R N B Q K B N R |\n//   +-----------------+\n//     a b c d e f g h\n\nboard.occupiedSpaces.ascii\n//   +-----------------+\n// 8 | 1 1 1 1 1 1 1 1 |\n// 7 | 1 1 1 1 1 1 1 1 |\n// 6 | . . . . . . . . |\n// 5 | . . . . . . . . |\n// 4 | . . . . . . . . |\n// 3 | . . . . . . . . |\n// 2 | 1 1 1 1 1 1 1 1 |\n// 1 | 1 1 1 1 1 1 1 1 |\n//   +-----------------+\n//     a b c d e f g h\n```\n\n### Forsyth–Edwards Notation\n\nThe `Game.Position` and `Board` types can both generate a FEN string.\n\n```swift\nlet game = Game()\n\ngame.position.fen()\n// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1\n\ngame.board.fen()\n// rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR\n```\n\nThey can also be initialized from a FEN string.\n\n```swift\nassert(Board(fen: game.board.fen()) == game.board)\n\nassert(Game.Position(fen: game.position.fen()) == game.position)\n```\n\n### Iterating Through a Board\n\nThe `Board` type conforms to `Sequence`, making iterating through its spaces\nseamless.\n\n```swift\nfor space in Board() {\n    if let piece = space.piece {\n        print(\"\\(piece) at \\(space.square)\")\n    }\n}\n```\n\n### Squares to Moves\n\n`Sequence` and `Square` have two methods that return an array of moves that go\nfrom/to `self` to/from the parameter.\n\n```swift\n[.a1, .h3, .b5].moves(from: .b4)\n// [b4 \u003e\u003e\u003e a1, b4 \u003e\u003e\u003e h3, b4 \u003e\u003e\u003e b5]\n\n[.c3, .d2, .f1].moves(to: .a6)\n// [c3 \u003e\u003e\u003e a6, d2 \u003e\u003e\u003e a6, f1 \u003e\u003e\u003e a6]\n\nSquare.d4.moves(from: [.c2, .f8, .h2])\n// [c2 \u003e\u003e\u003e d4, f8 \u003e\u003e\u003e d4, h2 \u003e\u003e\u003e d4]\n\nSquare.a4.moves(to: [.c3, .d4, .f6])\n// [a4 \u003e\u003e\u003e c3, a4 \u003e\u003e\u003e d4, a4 \u003e\u003e\u003e f6]\n```\n\n### Playground Usage\n\nTo use `Sage.playground`, first open `Sage.xcodeproj` and build the OS X target.\nYou can then use the playground from within the project.\n\n#### Board Quick Look\n\n`Board` conforms to the `CustomPlaygroundQuickLookable` protocol.\n\n![Playground quick look](https://raw.githubusercontent.com/nvzqz/Sage/assets/BoardPlaygroundView.png)\n\n## Donation\n\nI work on this in my free time and do my best to make it as great as it can be.\nIf you want to help me keep pushing out awesome libraries like this, a donation\nwould be greatly appreciated. :smile:\n\n[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_donations\u0026business=GZXUDALB3MQRC\u0026lc=US\u0026item_name=Nikolai%20Vazquez\u0026currency_code=USD\u0026bn=PP%2dDonationsBF%3abtn_donateCC_LG%2egif%3aNonHosted)\n\n## License\n\nSage is published under [version 2.0 of the Apache License](https://www.apache.org/licenses/LICENSE-2.0).\n\n[Hexe]: https://github.com/hexe-rs/Hexe\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvzqz%2FSage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnvzqz%2FSage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnvzqz%2FSage/lists"}