1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
|
from typing import Dict, List, Any, Union
DiceResult = Dict[str, Any]
RollHistory = List[DiceResult]
ModifierList = List[str]
def roll_dice(expression: str) -> DiceResult:
"""
Analyze and calculate dice expressions
Args:
expression: Dice expression string, supports the following formats:
- Basic dice: "3d6", "1d20", "2d10"
- Mathematical operations: "3d6 + 2", "2d6 * 3", "(2d6 + 3) * 2"
- Modifiers: "2d6!", "4d6kh3", "5d6dl1", "3d6r1", "4d6ro1"
Returns:
A dictionary containing the following keys:
- expression: str - expression string
- total: int - Total points
- rolls: List[List[int]] - List of throw results
- details: str - details
- comment: str - User comment
Raises:
ValueError: When the expression is invalid
Example:
result = roll_dice("3d6 + 2")
print(result["total"]) # output total points
"""
...
def roll_simple(dice_count: int, dice_sides: int) -> int:
"""
Simple dice throw
Args:
dice_count: The number of dice must be greater than 0
dice_sides: The number of dice faces must be greater than 0
Returns:
Total points
Raises:
ValueError: When the parameter is invalid
Example:
total = roll_simple(3, 6) # Roll 3 6-sided dice
"""
...
class OneRoll:
"""
OneRoll dice thrower category
Provides an object-oriented dice throwing interface, supporting complex expressions and various modifiers.
"""
def __init__(self) -> None:
"""
Initialize OneRoll Object
Example:
roller = OneRoll()
"""
...
def roll(self, expression: str) -> DiceResult:
"""
Analyze and calculate dice expressions
Args:
expression: Dice expression string, supports the following formats:
- Basic dice: "3d6", "1d20", "2d10"
- Mathematical operations: "3d6 + 2", "2d6 * 3", "(2d6 + 3) * 2"
- Modifiers: "2d6!", "4d6kh3", "5d6dl1", "3d6r1", "4d6ro1"
Returns:
A dictionary containing the following keys:
- expression: str - expression string
- total: int - Total points
- rolls: List[List[int]] - List of throw results
- details: str - details
- comment: str - User comment
Raises:
ValueError: When the expression is invalid
Example:
roller = OneRoll()
result = roller.roll("3d6 + 2")
print(f"Total points: {result['total']}")
"""
...
def roll_simple(self, dice_count: int, dice_sides: int) -> int:
"""
Simple dice throw
Args:
dice_count: The number of dice must be greater than 0
dice_sides: The number of dice faces must be greater than 0
Returns:
Total points
Raises:
ValueError: When the parameter is invalid
Example:
roller = OneRoll()
total = roller.roll_simple(3, 6) # Throw 3 6-sided dice
"""
...
def roll_with_modifiers(
self, dice_count: int, dice_sides: int, modifiers: ModifierList
) -> DiceResult:
"""
Dice throw with modifier
Args:
dice_count: The number of dice must be greater than 0
dice_sides: The number of dice faces must be greater than 0
modifiers: modifier list, supports the following formats:
- "!" - Explosion dice
- "r<number>" - Re-submit, such as "r1"
- "ro<number>" - Conditional re-submission, such as "ro1"
- "kh<number>" - Take the height, such as "kh3"
- "kl<number>" - Take the low, such as "kl2"
- "dh<number>" - discard the height, such as "dh1"
- "dl<number>" - discard low, such as "dl1"
Returns:
A dictionary containing the following keys:
- total: int - Total points
- rolls: List[List[int]] - List of throw results
- details: str - details
Raises:
ValueError: When the parameter or modifier is invalid
Example:
roller = OneRoll()
result = roller.roll_with_modifiers(4, 6, ["kh3"]) # 4d6kh3
print(f"Total points: {result['total']}")
"""
...
def is_valid_expression(expression: str) -> bool:
"""
Check if the expression is valid
Args:
expression: The expression string to check
Returns:
Return True if the expression is valid, otherwise return False
Example:
if is_valid_expression("3d6 + 2"):
result = roll_dice("3d6 + 2")
"""
...
def parse_expression(expression: str) -> Dict[str, Any]:
"""
Parses expressions but not throwing
Args:
expression: The expression string to parse
Returns:
Analytical results dictionary
Raises:
ValueError: When the expression is invalid
"""
...
class RollStatistics:
"""Throw statistics"""
min: int
max: int
mean: float
total: int
count: int
results: List[int]
def roll_multiple(expression: str, times: int) -> RollHistory:
"""
Throw the same expression multiple times
Args:
expression: dice expression string
times: The number of throws must be greater than 0
Returns:
Throw result list
Raises:
ValueError: When the parameter is invalid
Example:
results = roll_multiple("3d6", 10)
totals = [r["total"] for r in results]
"""
...
def roll_statistics(expression: str, times: int) -> RollStatistics:
"""
Statistics of multiple throws
Args:
expression: dice expression string
times: The number of throws must be greater than 0
Returns:
Object containing statistics
Raises:
ValueError: When the parameter is invalid
Example:
stats = roll_statistics("3d6", 100)
print(f"Average: {stats.mean:.2f}")
"""
...
class CommonRolls:
"""Commonly used dice expression constants"""
D20: str
D20_ADVANTAGE: str
D20_DISADVANTAGE: str
ATTRIBUTE_ROLL: str
D6_DAMAGE: str
D8_DAMAGE: str
D10_DAMAGE: str
D12_DAMAGE: str
HIT_POINTS_D6: str
HIT_POINTS_D8: str
HIT_POINTS_D10: str
HIT_POINTS_D12: str
|