| Name | pycallshot JSON |
| Version |
0.1.1
JSON |
| download |
| home_page | https://github.com/dmitry-helios/pycallshot |
| Summary | A simple independent library for rolling dice and managing dice rolls |
| upload_time | 2024-12-13 11:31:06 |
| maintainer | None |
| docs_url | None |
| author | Dmitry Helios |
| requires_python | >=3.7 |
| license | MIT License Copyright (c) 2024 PyCallShot Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
dice
rpg
game
random
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Call Shot to the Nuts
PyCallShot is a simple independent Python library for rolling dice and managing dice rolls in your games and applications.
## Features
- Roll any number and type of dice (d4, d6, d20, d69 etc.)
- Support for complex dice mechanics:
- Advantage/disadvantage rolls
- Exploding dice
- Success thresholds and hit count a-la Shadowrun and WoD
- Dice and result modifiers
- Subtract ones (for specific game systems)
- Roll logging capability
- Reproducible results with seed support
- Save and load frequently used roll configurations
## Installation
```bash
pip install pycallshot
```
## Quick Start
```python
import pycallshot as cs
# Create a dice tower object that holds config data, last roll, and
# provides methods for rolling, loading and saving rolls
# (optional seed for reproducibility)
tower = cs.DiceTower(seed=None, log=False)
# Simple d20 roll with 4 added to result
roll = cs.Roll._from_notation('d20+4') # 1d20+4
result = tower.roll(roll)
# Complex roll with multiple dice
complex_roll = cs.Roll(
pool=8, # Number of dice
d=6, # Six-sided dice
threshold=5, # Count successes for rolls >= 5
explode=6, # On 6s, keep result and roll again
subtractOnes=False, # Don't subtract 1s from success count
diceMod=0, # No modifier to individual dice
resultMod=0, # No modifier to final result
adv=0 # No advantage/disadvantage
)
result = tower.roll(complex_roll)
```
## Detailed Usage
### Creating Rolls
There are two ways to create a roll:
1. Using the constructor:
```python
roll = cs.Roll(
pool=3, # Number of dice
d=4, # Die sides
resultMod=4 # Add 4 to final result
)
```
2. Using notation (similar to standard RPG notation):
```python
roll = cs.Roll._from_notation('d20adv') # d20 with advantage
roll = cs.Roll._from_notation('2d6+4') # 2d6 plus 4
```
### Using the Dice Tower
The DiceTower class handles the execution of rolls:
```python
# Create a tower with logging enabled
tower = cs.DiceTower(seed=None, log=True)
# Roll the dice
result = tower.roll(roll)
# Re-roll the last roll
new_result = tower.reroll()
# Save frequently used rolls
tower.save(roll, 'attack_roll')
# List saved rolls, wait for input to select one of the rolls, and use selected roll
result = tower.from_loaded()
```
### Roll Parameters
- `pool`: Number of dice to roll
- `d`: Number of sides on each die
- `threshold`: Success threshold for counting hits
- `explode`: Value at which dice "explode" (roll again)
- `subtractOnes`: Whether to subtract ones from success count
- `diceMod`: Modifier added to each individual die
- `resultMod`: Modifier added to final result
- `adv`: Advantage (1), Disadvantage (-1), or Normal (0)
### Notation
The notation string takes the following details:
- `dX` - X-sided dice
- `Yd` - the value to the left of `d` is always the the number of dice to roll
- `adv` - roll with advantage
- `dis` - roll with disadvantage
- `!X` - explode values of X or higher
- `tX` - success threshold X
- `s` - subtract ones from success count
- `+X` - add X to the end result of roll
- `-X` - subtract X from the end result of roll
Adding modifiers to each die is not supported in notation. Use the `diceMod` parameter instead.
## Logging
Enable logging to keep track of all rolls:
```python
tower = cs.DiceTower(log=True)
```
Logs will be saved to `log.txt` with timestamps and detailed roll information.
## Storing and Loading Rolls with CSV file
The `to_csv` and `from_csv` methods can be used to save and load rolls to and from a CSV file.
To get the headers to manually set up rolls, run to_csv once. Default path is `saved_rolls.csv`.
Running from_csv will overwrite the rolls currently stored in memory. Writing to_csv will overwrite existing file.
Thought about using Pandas for some fancy exporting and sorting, opted to keep independent for such a small project.
## Contributing
Contributions are welcome! This is a learning project, so please feel free to make changes and submit feedback.
## License
This project is licensed under the MIT License - see the LICENSE file for details.
## Authors
Dmitry Hayday
Raw data
{
"_id": null,
"home_page": "https://github.com/dmitry-helios/pycallshot",
"name": "pycallshot",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "dice, rpg, game, random",
"author": "Dmitry Helios",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/73/49/35f2873b1f47696c2663bcbf9006041891513d1d524f5f8d70093711dea6/pycallshot-0.1.1.tar.gz",
"platform": null,
"description": "# Call Shot to the Nuts\n\nPyCallShot is a simple independent Python library for rolling dice and managing dice rolls in your games and applications.\n\n## Features\n\n- Roll any number and type of dice (d4, d6, d20, d69 etc.)\n- Support for complex dice mechanics:\n - Advantage/disadvantage rolls\n - Exploding dice\n - Success thresholds and hit count a-la Shadowrun and WoD\n - Dice and result modifiers\n - Subtract ones (for specific game systems)\n- Roll logging capability\n- Reproducible results with seed support\n- Save and load frequently used roll configurations\n\n## Installation\n\n```bash\npip install pycallshot\n```\n\n## Quick Start\n\n```python\nimport pycallshot as cs\n\n# Create a dice tower object that holds config data, last roll, and\n# provides methods for rolling, loading and saving rolls\n# (optional seed for reproducibility)\ntower = cs.DiceTower(seed=None, log=False)\n\n# Simple d20 roll with 4 added to result\nroll = cs.Roll._from_notation('d20+4') # 1d20+4\nresult = tower.roll(roll)\n\n# Complex roll with multiple dice\ncomplex_roll = cs.Roll(\n pool=8, # Number of dice\n d=6, # Six-sided dice\n threshold=5, # Count successes for rolls >= 5\n explode=6, # On 6s, keep result and roll again\n subtractOnes=False, # Don't subtract 1s from success count\n diceMod=0, # No modifier to individual dice\n resultMod=0, # No modifier to final result\n adv=0 # No advantage/disadvantage\n)\nresult = tower.roll(complex_roll)\n```\n\n## Detailed Usage\n\n### Creating Rolls\n\nThere are two ways to create a roll:\n\n1. Using the constructor:\n```python\nroll = cs.Roll(\n pool=3, # Number of dice\n d=4, # Die sides\n resultMod=4 # Add 4 to final result\n)\n```\n\n2. Using notation (similar to standard RPG notation):\n```python\nroll = cs.Roll._from_notation('d20adv') # d20 with advantage\nroll = cs.Roll._from_notation('2d6+4') # 2d6 plus 4\n```\n\n### Using the Dice Tower\n\nThe DiceTower class handles the execution of rolls:\n\n```python\n# Create a tower with logging enabled\ntower = cs.DiceTower(seed=None, log=True)\n\n# Roll the dice\nresult = tower.roll(roll)\n\n# Re-roll the last roll\nnew_result = tower.reroll()\n\n# Save frequently used rolls\ntower.save(roll, 'attack_roll')\n\n# List saved rolls, wait for input to select one of the rolls, and use selected roll\nresult = tower.from_loaded()\n\n```\n\n### Roll Parameters\n\n- `pool`: Number of dice to roll\n- `d`: Number of sides on each die\n- `threshold`: Success threshold for counting hits\n- `explode`: Value at which dice \"explode\" (roll again)\n- `subtractOnes`: Whether to subtract ones from success count\n- `diceMod`: Modifier added to each individual die\n- `resultMod`: Modifier added to final result\n- `adv`: Advantage (1), Disadvantage (-1), or Normal (0)\n\n### Notation\nThe notation string takes the following details:\n- `dX` - X-sided dice\n- `Yd` - the value to the left of `d` is always the the number of dice to roll\n- `adv` - roll with advantage\n- `dis` - roll with disadvantage\n- `!X` - explode values of X or higher\n- `tX` - success threshold X\n- `s` - subtract ones from success count\n- `+X` - add X to the end result of roll\n- `-X` - subtract X from the end result of roll\nAdding modifiers to each die is not supported in notation. Use the `diceMod` parameter instead.\n\n## Logging\n\nEnable logging to keep track of all rolls:\n\n```python\ntower = cs.DiceTower(log=True)\n```\n\nLogs will be saved to `log.txt` with timestamps and detailed roll information.\n\n## Storing and Loading Rolls with CSV file\n\nThe `to_csv` and `from_csv` methods can be used to save and load rolls to and from a CSV file.\nTo get the headers to manually set up rolls, run to_csv once. Default path is `saved_rolls.csv`.\nRunning from_csv will overwrite the rolls currently stored in memory. Writing to_csv will overwrite existing file.\nThought about using Pandas for some fancy exporting and sorting, opted to keep independent for such a small project.\n\n## Contributing\n\nContributions are welcome! This is a learning project, so please feel free to make changes and submit feedback.\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Authors\n\nDmitry Hayday\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2024 PyCallShot Contributors Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "A simple independent library for rolling dice and managing dice rolls",
"version": "0.1.1",
"project_urls": {
"Homepage": "https://github.com/dmitry-helios/pycallshot"
},
"split_keywords": [
"dice",
" rpg",
" game",
" random"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "03129f7188ceb7e189e217bb8cb97817f2c0537311c1ef0a30132ce8f538818d",
"md5": "6fd14872046c631f6ee3f5d6258c2120",
"sha256": "51787f885db702dd03aa2264ad88ae40406f5f7312d03b25febea1e9fadf2e7b"
},
"downloads": -1,
"filename": "pycallshot-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "6fd14872046c631f6ee3f5d6258c2120",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9973,
"upload_time": "2024-12-13T11:31:05",
"upload_time_iso_8601": "2024-12-13T11:31:05.263545Z",
"url": "https://files.pythonhosted.org/packages/03/12/9f7188ceb7e189e217bb8cb97817f2c0537311c1ef0a30132ce8f538818d/pycallshot-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "734935f2873b1f47696c2663bcbf9006041891513d1d524f5f8d70093711dea6",
"md5": "3e25eaaf7adcafd4c64d781df0e47301",
"sha256": "2a87e91584c38c7cc4666eacdd041636e9fc41178812d4d08f4b0fb6b0ba1ef3"
},
"downloads": -1,
"filename": "pycallshot-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "3e25eaaf7adcafd4c64d781df0e47301",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 10696,
"upload_time": "2024-12-13T11:31:06",
"upload_time_iso_8601": "2024-12-13T11:31:06.526267Z",
"url": "https://files.pythonhosted.org/packages/73/49/35f2873b1f47696c2663bcbf9006041891513d1d524f5f8d70093711dea6/pycallshot-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-12-13 11:31:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "dmitry-helios",
"github_project": "pycallshot",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pycallshot"
}
