<p align="center">
<img alt="RoyalUr-Python Logo" height="180" src="https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/banner.png" />
</p>
This library provides a Python API for the play and analysis of games of **The Royal Game of Ur**!
### What is The Royal Game of Ur?
The Royal Game of Ur is one of the longest-living games in history, with evidence
of it being enjoyed by people who lived over 5,000 years ago!
This library aims to bring this ancient board game into the modern age by supporting
digital versions of the game, statistical analysis of its rules, and the use
of AI to play the game. A board used to play The Royal Game of Ur is shown below,
which was excavated by Sir Leonard Woolley in the 1930s.
It is currently on display at the British Museum!
<p align="center">
<img alt="British Museum game board excavated by Sir Leonard Woolley" height="300" src="https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/bm_board.png" />
</p>
<p align="center">
Photo of an excavated board of the Royal Game of Ur that is dated to 2500 BC.<br/>
© The Trustees of the British Museum.
</p>
### Resources
* [Read the documentation.](https://royalur.github.io/RoyalUrPython/)
* Prefer Java to Python? [Check out RoyalUr-Java.](https://github.com/RoyalUr/RoyalUr-Java)
* [Play The Royal Game of Ur on RoyalUr.net.](https://royalur.net/)
* If you want to delve deeper, join us to discuss the game by [joining our Discord!](https://discord.gg/HBP83J4qHV)
# 🔧 Installation
The RoyalUr-Python package is available to be installed through pip:
```bash
pip install royalur
```
# 🚀 Example
The following is a small example that shows the basics of creating
a game, autonomously playing through it by making random moves,
and reporting what happens in the game as it progresses.
```python
from royalur import Game
# Create a new game using the Finkel rules.
game = Game.create_finkel()
while not game.is_finished():
turn_player_name = game.get_turn().text_name
if game.is_waiting_for_roll():
# Roll the dice!
roll = game.roll_dice()
print(f"{turn_player_name}: Roll {roll.value}")
else:
# Make a random move.
moves = game.find_available_moves()
move = moves[random.randint(0, len(moves) - 1)]
game.make_move(move)
print(f"{turn_player_name}: {move.describe()}")
# Report the winner!
print(f"{game.get_winner().text_name} won the game!")
```
Here is a snippet from the end of the output from running
the example above:
```
Dark: Score a piece from C7
Light: Roll 2
Light: Score a piece from A8
Dark: Roll 1
Dark: Move C4 to C3
Light: Roll 1
Light: Score a piece from A7
Light won the game!
```
# 📜 Supported Rulesets
This library supports a wide range of rulesets for the
Royal Game of Ur. You may use standard sets of rules that
are commonly played, or create your own custom rulesets.
**Provided Rulesets:**
- Rules proposed by Irving Finkel (simple version).
- Rules proposed by James Masters.
- Rules for Aseb (using a different game board).
# ⚙️ Custom Rulesets
The rulesets are created by selecting several component pieces
that make up the ruleset. This includes selecting the board
shape, the path that pieces take around the board, the
dice that are used, alongside other features such as whether
rosette tiles are safe from capture. The provided values of
these components are given below, but new values can also be
created and used instead (e.g., for a new path around the board).
**Board Shapes:**
- Standard Royal Game of Ur.
- Aseb.
<p align="center">
<img alt="Supported Board Shapes" height="350" src="https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/board_shapes.png" />
</p>
**Paths:**
- Bell's path.
- Masters' path.
- Murray's path.
- Skiriuk's path.
- Aseb path proposed by Murray.
<p align="center">
<img alt="Supported Paths" height="350" src="https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/paths.png" />
</p>
**Dice:**
- Four binary die.
- Three binary die where a roll of zero is treated as a four.
- N binary die.
- N binary die where a roll of zero is treated as a roll of N+1.
**Features:**
- Number of starting pieces for each player.
- Whether rosettes are safe tiles.
- Whether landing on a rosette grants an extra roll.
- Whether capturing a piece grants an extra roll.
# 📝 License
This library is licensed under the MIT license.
[Read the license here.](LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/RoyalUr/RoyalUr-Python",
"name": "RoyalUr",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "game,boardgame",
"author": "Padraig Lamont",
"author_email": "padraiglamont@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/54/b4/72ff34e1325bef7710ecc8fdf75a0ac14954136f2f46d5a6c93340226e0d/RoyalUr-0.0.5.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img alt=\"RoyalUr-Python Logo\" height=\"180\" src=\"https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/banner.png\" />\n</p>\n\nThis library provides a Python API for the play and analysis of games of **The Royal Game of Ur**!\n\n### What is The Royal Game of Ur?\n\nThe Royal Game of Ur is one of the longest-living games in history, with evidence\nof it being enjoyed by people who lived over 5,000 years ago!\nThis library aims to bring this ancient board game into the modern age by supporting\ndigital versions of the game, statistical analysis of its rules, and the use\nof AI to play the game. A board used to play The Royal Game of Ur is shown below,\nwhich was excavated by Sir Leonard Woolley in the 1930s.\nIt is currently on display at the British Museum!\n\n<p align=\"center\">\n <img alt=\"British Museum game board excavated by Sir Leonard Woolley\" height=\"300\" src=\"https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/bm_board.png\" />\n</p>\n<p align=\"center\">\n Photo of an excavated board of the Royal Game of Ur that is dated to 2500 BC.<br/>\n \u00a9 The Trustees of the British Museum.\n</p>\n\n### Resources\n\n* [Read the documentation.](https://royalur.github.io/RoyalUrPython/)\n\n* Prefer Java to Python? [Check out RoyalUr-Java.](https://github.com/RoyalUr/RoyalUr-Java)\n\n* [Play The Royal Game of Ur on RoyalUr.net.](https://royalur.net/)\n\n* If you want to delve deeper, join us to discuss the game by [joining our Discord!](https://discord.gg/HBP83J4qHV)\n\n\n# \ud83d\udd27 Installation\nThe RoyalUr-Python package is available to be installed through pip:\n```bash\npip install royalur\n```\n\n\n# \ud83d\ude80 Example\n\nThe following is a small example that shows the basics of creating\na game, autonomously playing through it by making random moves,\nand reporting what happens in the game as it progresses.\n\n```python\nfrom royalur import Game\n\n# Create a new game using the Finkel rules.\ngame = Game.create_finkel()\n\nwhile not game.is_finished():\n turn_player_name = game.get_turn().text_name\n\n if game.is_waiting_for_roll():\n # Roll the dice!\n roll = game.roll_dice()\n print(f\"{turn_player_name}: Roll {roll.value}\")\n\n else:\n # Make a random move.\n moves = game.find_available_moves()\n move = moves[random.randint(0, len(moves) - 1)]\n game.make_move(move)\n print(f\"{turn_player_name}: {move.describe()}\")\n\n# Report the winner!\nprint(f\"{game.get_winner().text_name} won the game!\")\n```\n\nHere is a snippet from the end of the output from running\nthe example above:\n```\nDark: Score a piece from C7\nLight: Roll 2\nLight: Score a piece from A8\nDark: Roll 1\nDark: Move C4 to C3\nLight: Roll 1\nLight: Score a piece from A7\n\nLight won the game!\n```\n\n\n# \ud83d\udcdc Supported Rulesets\n\nThis library supports a wide range of rulesets for the\nRoyal Game of Ur. You may use standard sets of rules that\nare commonly played, or create your own custom rulesets.\n\n**Provided Rulesets:**\n- Rules proposed by Irving Finkel (simple version).\n- Rules proposed by James Masters.\n- Rules for Aseb (using a different game board).\n\n# \u2699\ufe0f Custom Rulesets\n\nThe rulesets are created by selecting several component pieces\nthat make up the ruleset. This includes selecting the board\nshape, the path that pieces take around the board, the\ndice that are used, alongside other features such as whether\nrosette tiles are safe from capture. The provided values of\nthese components are given below, but new values can also be\ncreated and used instead (e.g., for a new path around the board).\n\n**Board Shapes:**\n- Standard Royal Game of Ur.\n- Aseb.\n\n<p align=\"center\">\n <img alt=\"Supported Board Shapes\" height=\"350\" src=\"https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/board_shapes.png\" />\n</p>\n\n**Paths:**\n- Bell's path.\n- Masters' path.\n- Murray's path.\n- Skiriuk's path.\n- Aseb path proposed by Murray.\n\n<p align=\"center\">\n <img alt=\"Supported Paths\" height=\"350\" src=\"https://raw.githubusercontent.com/RoyalUr/RoyalUr-Python/master/docs/res/paths.png\" />\n</p>\n\n**Dice:**\n- Four binary die.\n- Three binary die where a roll of zero is treated as a four.\n- N binary die.\n- N binary die where a roll of zero is treated as a roll of N+1.\n\n**Features:**\n- Number of starting pieces for each player.\n- Whether rosettes are safe tiles.\n- Whether landing on a rosette grants an extra roll.\n- Whether capturing a piece grants an extra roll.\n\n\n# \ud83d\udcdd License\nThis library is licensed under the MIT license.\n[Read the license here.](LICENSE)\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "An API to support the playing and analysis of games of The Royal Game of Ur.",
"version": "0.0.5",
"project_urls": {
"Homepage": "https://github.com/RoyalUr/RoyalUr-Python"
},
"split_keywords": [
"game",
"boardgame"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "80ceaf224b527ecdd5134da3a85c84328635c50959eddab9892d610b71b9f810",
"md5": "b7629ad8c157f8052a541a215163d19d",
"sha256": "e3c42b89c5768a690e3bfa130b78ea04713a52f26fc5a8a04bcddab65aebcfbc"
},
"downloads": -1,
"filename": "RoyalUr-0.0.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b7629ad8c157f8052a541a215163d19d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 30670,
"upload_time": "2023-10-17T21:41:03",
"upload_time_iso_8601": "2023-10-17T21:41:03.068685Z",
"url": "https://files.pythonhosted.org/packages/80/ce/af224b527ecdd5134da3a85c84328635c50959eddab9892d610b71b9f810/RoyalUr-0.0.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "54b472ff34e1325bef7710ecc8fdf75a0ac14954136f2f46d5a6c93340226e0d",
"md5": "41614e8b49ae5a01b8d4007a296a8c77",
"sha256": "401035bac5d801aada09facbf7b49044ebb999d345c239797e029dc724fb5b15"
},
"downloads": -1,
"filename": "RoyalUr-0.0.5.tar.gz",
"has_sig": false,
"md5_digest": "41614e8b49ae5a01b8d4007a296a8c77",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 23366,
"upload_time": "2023-10-17T21:41:04",
"upload_time_iso_8601": "2023-10-17T21:41:04.998551Z",
"url": "https://files.pythonhosted.org/packages/54/b4/72ff34e1325bef7710ecc8fdf75a0ac14954136f2f46d5a6c93340226e0d/RoyalUr-0.0.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-17 21:41:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "RoyalUr",
"github_project": "RoyalUr-Python",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "overrides",
"specs": [
[
">=",
"7.4.0"
]
]
}
],
"lcname": "royalur"
}
JSON
