# hagadias
Python package to extract game data from the [Caves of Qud](http://www.cavesofqud.com/) roguelike.
This library forms the base for several projects:
- the Caves of Qud wiki bot that builds and updates the [Caves of Qud wiki](https://wiki.cavesofqud.com/)
- the Discord bot that operates on the [Caves of Qud discord server](https://discordapp.com/invite/cavesofqud) (invite
link)
## What does it do?
hagadias allows a user to read game data in the raw format used by the
[Caves of Qud](http://www.cavesofqud.com/) roguelike RPG, including the object tree, fully colored tiles, and character
data. It needs to be passed a path to a local installation of the game in order to do anything.
## Installation
hagadias requires Python 3.10.
To install the package from this GitHub repository without a package manager, run
`pip install git+https://github.com/trashmonks/hagadias@main#egg=hagadias`
If you're using pipenv to manage dependencies,
`pipenv install -e git+https://github.com/trashmonks/hagadias.git@main#egg=hagadias`
If you're using Poetry to manage dependencies,
`poetry add git+https://github.com/trashmonks/hagadias#main`
## Tile support
Tile support requires the texture files from Caves of Qud to be unpacked into a "Textures" directory under the working
directory of your project that is importing hagadias. You can use the
[Brinedump](https://github.com/TrashMonks/brinedump)
game mod to export these textures from within the game.
## Example usage
### Startup
```python
import hagadias
from pprint import pprint
GAMEPATH = 'C:\\Steam\\steamapps\\common\\Caves of Qud' # Windows
# GAMEPATH = '~/.local/share/Steam/steamapps/common/Caves of Qud' # Linux
# GAMEPATH = '~/Library/Application Support/Steam/steamapps/common/Caves of Qud' # macOS
root = hagadias.gameroot.GameRoot(GAMEPATH)
print(root.gamever) # output version of the game
```
```
2.0.203.56
```
### Objects (Blueprints)
```
qud_object_root, qindex = root.get_object_tree()
# The above gives you two items:
# - a `qud_object_root` object of type `QudObjectProps` that is the root of the CoQ object hierarchy, allowing you to traverse the entire object tree and retrieve information about the items, characters, tiles, etc.
# - a `qindex` which is a dictionary that simply maps the Name (ingame object ID or wish ID) of each ingame object, as a string, to the Python object representing it.
# Example use of qud_object_root:
>>> qud_object_root.source
'<object Name="Object">\n <part Name="Physics" Conductivity="0" IsReal="true" Solid="false" Weight="0"></part>\n </object>'
# But what you really want is the qindex:
>>> snapjaw = qindex['Snapjaw']
>>> snapjaw.desc
'Tussocks of fur dress skin stretched over taut muscle. Upright =pronouns.subjective= =verb:stand:afterpronoun=, but =pronouns.subjective= =verb:look:afterpronoun= ready to drop onto fours. =pronouns.Possessive= snout snarls and =pronouns.possessive= ears twitch. =pronouns.Subjective= =verb:bark:afterpronoun=, and =pronouns.possessive= hyena tribesmen answer.'
>>> snapjaw.dv
6
>>> help(snapjaw)
# will give detailed help on all properties and methods, including a long list of properties that objects can have, like below:
...
| butcheredinto
| What a corpse item can be butchered into.
|
| canbuild
| Whether or not the player can tinker up this item.
|
| candisassemble
| Whether or not the player can disassemble this item.
|
| carrybonus
| The carry weight bonus.
# and so on.
# Tile support requires you to download the modding tile toolkit, described in the section above. But with it, you can do:
>>> youngivory = qindex['Young Ivory']
>>> youngivory.tile
<hagadias.qudtile.QudTile object at 0x0000018F898C3BA8>
>>> youngivory.tile.image
<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=16x24 at 0x18F890B3320>
# for a PIL library format PNG image. There are other methods for retrieving BytesIO PNG binary data, see
>>> help(youngivory.tile)
# for details.
```
### Character codes
```python
gamecodes = root.get_character_codes()
# A dictionary containing some helpful information used to calculate the results of character builds.
# `gamecodes` contains the following items:
# 'class_bonuses': a dictionary mapping castes+callings to lists of stat bonuses
# 'class_skills': a dictionary mapping castes+callings to lists of skills (e.g. 'Horticulturalist': ['Meal Preparation', ...]
# 'class_tiles': a dictionary mapping castes+callings to tuples of (tile path, detail color) for that caste/calling's art
print(hagadias.character_codes.STAT_NAMES)
print(gamecodes["class_bonuses"]["Horticulturist"]) # 3-point Intelligence bonus
print(gamecodes["class_skills"]["Horticulturist"])
print(gamecodes["class_tiles"]["Horticulturist"])
```
```
('Strength', 'Agility', 'Toughness', 'Intelligence', 'Willpower', 'Ego')
[0, 0, 0, 3, 0, 0]
['Meal Preparation', 'Harvestry', '(Axe)', '(Bow and Rifle)', 'Wilderness Lore: Jungles']
('creatures/caste_1.bmp', 'g')
```
## License
hagadias is licensed under the terms of the GNU Affero General Public License Version 3.
The included font Source Code Pro is used under the terms of the SIL Open Font License 1.1.
The included file `IBMGRAPH.TXT` is provided by the Unicode Consortium under the terms of the license contained therein.
## Contributing
See `CONTRIBUTING.md`.
## Contributors
Thank you to the following people who have contributed code to this project:
- egocarib
- Wreckstation
- librarianmage
- HeladoDeBrownie
- elvres
- robbyblum
Raw data
{
"_id": null,
"home_page": "https://github.com/TrashMonks/hagadias",
"name": "hagadias",
"maintainer": "syntaxaire",
"docs_url": null,
"requires_python": ">=3.10,<4.0",
"maintainer_email": "syntaxaire@gmail.com",
"keywords": "Caves,Qud",
"author": "syntaxaire",
"author_email": "syntaxaire@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/f0/a3/beb58c2cac6744c5f4df9d3a46436e10bc075c35e62481961d8f0babe5ca/hagadias-1.2.1.tar.gz",
"platform": null,
"description": "# hagadias\n\nPython package to extract game data from the [Caves of Qud](http://www.cavesofqud.com/) roguelike.\n\nThis library forms the base for several projects:\n\n- the Caves of Qud wiki bot that builds and updates the [Caves of Qud wiki](https://wiki.cavesofqud.com/)\n- the Discord bot that operates on the [Caves of Qud discord server](https://discordapp.com/invite/cavesofqud) (invite\n link)\n\n## What does it do?\n\nhagadias allows a user to read game data in the raw format used by the\n[Caves of Qud](http://www.cavesofqud.com/) roguelike RPG, including the object tree, fully colored tiles, and character\ndata. It needs to be passed a path to a local installation of the game in order to do anything.\n\n## Installation\n\nhagadias requires Python 3.10.\n\nTo install the package from this GitHub repository without a package manager, run \n`pip install git+https://github.com/trashmonks/hagadias@main#egg=hagadias` \nIf you're using pipenv to manage dependencies, \n`pipenv install -e git+https://github.com/trashmonks/hagadias.git@main#egg=hagadias`\nIf you're using Poetry to manage dependencies,\n`poetry add git+https://github.com/trashmonks/hagadias#main`\n\n## Tile support\n\nTile support requires the texture files from Caves of Qud to be unpacked into a \"Textures\" directory under the working\ndirectory of your project that is importing hagadias. You can use the\n[Brinedump](https://github.com/TrashMonks/brinedump)\ngame mod to export these textures from within the game.\n\n## Example usage\n### Startup\n```python\nimport hagadias\nfrom pprint import pprint\nGAMEPATH = 'C:\\\\Steam\\\\steamapps\\\\common\\\\Caves of Qud' # Windows\n# GAMEPATH = '~/.local/share/Steam/steamapps/common/Caves of Qud' # Linux\n# GAMEPATH = '~/Library/Application Support/Steam/steamapps/common/Caves of Qud' # macOS\nroot = hagadias.gameroot.GameRoot(GAMEPATH)\nprint(root.gamever) # output version of the game\n```\n```\n2.0.203.56\n```\n\n### Objects (Blueprints)\n```\nqud_object_root, qindex = root.get_object_tree()\n\n# The above gives you two items:\n# - a `qud_object_root` object of type `QudObjectProps` that is the root of the CoQ object hierarchy, allowing you to traverse the entire object tree and retrieve information about the items, characters, tiles, etc.\n# - a `qindex` which is a dictionary that simply maps the Name (ingame object ID or wish ID) of each ingame object, as a string, to the Python object representing it.\n\n# Example use of qud_object_root:\n>>> qud_object_root.source\n'<object Name=\"Object\">\\n <part Name=\"Physics\" Conductivity=\"0\" IsReal=\"true\" Solid=\"false\" Weight=\"0\"></part>\\n </object>'\n\n# But what you really want is the qindex:\n>>> snapjaw = qindex['Snapjaw']\n>>> snapjaw.desc\n'Tussocks of fur dress skin stretched over taut muscle. Upright =pronouns.subjective= =verb:stand:afterpronoun=, but =pronouns.subjective= =verb:look:afterpronoun= ready to drop onto fours. =pronouns.Possessive= snout snarls and =pronouns.possessive= ears twitch. =pronouns.Subjective= =verb:bark:afterpronoun=, and =pronouns.possessive= hyena tribesmen answer.'\n\n>>> snapjaw.dv\n6\n\n>>> help(snapjaw)\n# will give detailed help on all properties and methods, including a long list of properties that objects can have, like below:\n...\n\n | butcheredinto\n | What a corpse item can be butchered into.\n | \n | canbuild\n | Whether or not the player can tinker up this item.\n | \n | candisassemble\n | Whether or not the player can disassemble this item.\n | \n | carrybonus\n | The carry weight bonus.\n\n# and so on.\n\n# Tile support requires you to download the modding tile toolkit, described in the section above. But with it, you can do:\n\n>>> youngivory = qindex['Young Ivory']\n\n>>> youngivory.tile\n<hagadias.qudtile.QudTile object at 0x0000018F898C3BA8>\n\n>>> youngivory.tile.image\n<PIL.PngImagePlugin.PngImageFile image mode=RGBA size=16x24 at 0x18F890B3320>\n\n# for a PIL library format PNG image. There are other methods for retrieving BytesIO PNG binary data, see\n>>> help(youngivory.tile)\n# for details.\n```\n\n### Character codes\n```python\ngamecodes = root.get_character_codes()\n# A dictionary containing some helpful information used to calculate the results of character builds.\n# `gamecodes` contains the following items:\n# 'class_bonuses': a dictionary mapping castes+callings to lists of stat bonuses\n# 'class_skills': a dictionary mapping castes+callings to lists of skills (e.g. 'Horticulturalist': ['Meal Preparation', ...]\n# 'class_tiles': a dictionary mapping castes+callings to tuples of (tile path, detail color) for that caste/calling's art\nprint(hagadias.character_codes.STAT_NAMES)\nprint(gamecodes[\"class_bonuses\"][\"Horticulturist\"]) # 3-point Intelligence bonus\nprint(gamecodes[\"class_skills\"][\"Horticulturist\"])\nprint(gamecodes[\"class_tiles\"][\"Horticulturist\"])\n```\n```\n('Strength', 'Agility', 'Toughness', 'Intelligence', 'Willpower', 'Ego')\n[0, 0, 0, 3, 0, 0]\n['Meal Preparation', 'Harvestry', '(Axe)', '(Bow and Rifle)', 'Wilderness Lore: Jungles']\n('creatures/caste_1.bmp', 'g')\n```\n\n## License\n\nhagadias is licensed under the terms of the GNU Affero General Public License Version 3.\n\nThe included font Source Code Pro is used under the terms of the SIL Open Font License 1.1.\n\nThe included file `IBMGRAPH.TXT` is provided by the Unicode Consortium under the terms of the license contained therein.\n\n## Contributing\n\nSee `CONTRIBUTING.md`.\n\n## Contributors\n\nThank you to the following people who have contributed code to this project:\n\n- egocarib\n- Wreckstation\n- librarianmage\n- HeladoDeBrownie\n- elvres\n- robbyblum\n",
"bugtrack_url": null,
"license": "AGPL-3.0",
"summary": "Extract game data from the Caves of Qud roguelike",
"version": "1.2.1",
"split_keywords": [
"caves",
"qud"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3b966f2234bd0ceb312b24eb5b520d4ba6943514612aa3416a01b274652088db",
"md5": "a1a8885f1892a8af5d58249a1d5837eb",
"sha256": "deac289a884ec1e35ec01c572080cd6825c6357981f208e39c851f3403d18136"
},
"downloads": -1,
"filename": "hagadias-1.2.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a1a8885f1892a8af5d58249a1d5837eb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10,<4.0",
"size": 309076,
"upload_time": "2023-03-19T17:47:31",
"upload_time_iso_8601": "2023-03-19T17:47:31.057706Z",
"url": "https://files.pythonhosted.org/packages/3b/96/6f2234bd0ceb312b24eb5b520d4ba6943514612aa3416a01b274652088db/hagadias-1.2.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f0a3beb58c2cac6744c5f4df9d3a46436e10bc075c35e62481961d8f0babe5ca",
"md5": "985529ef4b5175359d0b9c251cb96339",
"sha256": "63a9ba654f1ee7fa4c3d4d883deaa5db51e384aad37bce54c28dcee6f9b2d22a"
},
"downloads": -1,
"filename": "hagadias-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "985529ef4b5175359d0b9c251cb96339",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10,<4.0",
"size": 303344,
"upload_time": "2023-03-19T17:47:32",
"upload_time_iso_8601": "2023-03-19T17:47:32.952939Z",
"url": "https://files.pythonhosted.org/packages/f0/a3/beb58c2cac6744c5f4df9d3a46436e10bc075c35e62481961d8f0babe5ca/hagadias-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-19 17:47:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "TrashMonks",
"github_project": "hagadias",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "hagadias"
}
JSON
