DiceKit is a Swift framework for expressing and evaluating dice notation (e.g., d20, 4d6-4, 3d8×10+2), which is commonly used in tabletop role-playing games.
- Roll dice with arbitrary number of sides (e.g.,
d2,d7,d6538) - Evaluate simple dice expressions, including addition, subtraction, multiplication, and negation operations (e.g.
2d20 + 6(1d5 + 8)) - Evaluate complicated dice expressions, including division, dropping dice, and exploding dice – #27, #28, #33
- Determine the probability distribution of an expression
- Determine if an expression result meets success criteria – #59
- Determine the probability distribution of meeting a success criteria (e.g. chance of rolling higher than 16 on
1d20 + 8, but a natural1being an auto failure and a natural20being an auto success) – #4 - Parse expressions from strings – #8
- Detect expressions in strings – #9
- Comprehensive unit test coverage
- iOS 8.0+ / Mac OS X 10.9+ / tvOS 9.0+ / watchOS 2.0+
- Xcode 7.1
// Create dice with an arbitrary number of sides
let d6 = d()
let d11 = d(11)
// Roll them to get results
let result = d11.roll()
let value = result.value
// The rolls are `Die.Roll` instead of just a value
// They store which die the value is associated with
let rollWasFromD11 = result.die == d(11) // true// Create expressions such as `2d20 + 8`
let expression = 2 * d(20) + 8
// Evaluate to get results
let result = expression.evaluate()
let value = result.value// With any expression...
let expression = 2 * d(6)
// you can get the probability mass
let probabilityMass = expression.probabilityMass
// [2: 0.0277777777777778,
// 3: 0.0555555555555556,
// 4: 0.0833333333333333,
// 5: 0.111111111111111,
// 6: 0.138888888888889,
// 7: 0.166666666666667,
// 8: 0.138888888888889,
// 9: 0.111111111111111,
// 10: 0.0833333333333333,
// 11: 0.0555555555555556,
// 12: 0.0277777777777778]See the Tome of Knowledge (playground) for in-depth usage.
Add the following line to your Cartfile:
github "TabletopAssistant/DiceKit"Then run carthage update.
Follow the current instructions in Carthage's README for up to date installation instructions.
- Add DiceKit.xcodeproj to your project's workspace.
- Build the DiceKit scheme. This is needed to get the proper path for the next steps.
- Link your target with DiceKit.framework:
-
iOS: Drag DiceKit.framework from the DiceKit/Products group to the “Linked Frameworks and Libraries” section of your target’s “General” settings.
-
OS X: Drag DiceKit.framework from the DiceKit/Products group to the “Embedded Binaries” section of your target’s “General” settings.
- Select the DiceKit.framework that is now in your project (most likely in your Frameworks group). In the “File Inspector” change the “Location” to “Relative to Build Products”.
See CONTRIBUTING.md for more details. Thank you, contributors!
This project adheres to the [Open Code of Conduct][code-of-conduct]. By participating, you are expected to honor this code. [code-of-conduct]: http://todogroup.org/opencodeofconduct/#DiceKit/[email protected]
Brentley Jones, @brentleyjones
DiceKit is published under the Apache 2.0 license.