# FifthedSim

This is a gem to simulate a game that you play with dice on a d20 system. It is unfinished, but intends to enable a user to run simulations, or to see the overall probability of things which happen.

## Usage

### Executable

If you just want to roll dice, simply install the gem and type "diceroll". This will bring up a Dice REPL, which has some nice functionality. Just type a dice expression, and you will get a result:

``````> d20 + 3d6
=> 18 + (3 2 6)
=  29
``````

You can also get some info about a roll by typing `info`. Type `help` to see all the commands.

### Dice Expressions

This gem generalizes the use of dice into DiceExpressions, which is an expression representing a calculation done on dice. This expression is lazily evaluated, which means that it does not turn into an actual numerical value until you call `.to_i` or `.value` on it.

DiceExpressions are more powerful than simply rolling dice and doing math on the results, as we can both reuse them and do statistics on them. This allows us to figure out a variety of useful information.

Dice expressions are almost always constructed via the `Fixnum#d` method:

``````1.d(20)
``````

From here, mathematical operations work as normal:

``````result = (1.d(20) + 3 + 2.d(6)) / (1.d(4) * 2 * 1.d(2))
``````

As mentioned earlier, we can get a numeric value from this expression:

``````result.value # -> 2
``````

We can also reroll this expression, to get another DiceExpression with a new value:

``````result.reroll.value # -> 6
``````

More interestingly, we can do statistics on this value. We can obtain a `Distribution` of possible results for a given dice expression easily:

``````distribution = result.distribution
``````

Now, let's see how likely our value of 2 was. Let's also see what percentile our value is in.

``````distribution.percent_exactly(2) # -> 0.199305...
distribution.percentile_of(2) # -> 0.475694...
``````

So our roll wasn't terrible, but it wasn't great as well.

#### Combinations

`DiceExpressions` are a powerful construct, because they allow combinations with arbitrary functions, while still being a `DiceExpression`. To use an example, let's try to model the damage of a kobold's dagger attack against a player character with 12 AC.

The kobold rolls `1d20 + 4` to hit. If he gets a 12 or higher, he does `1d4 + 2` damage to this player. Let's model this attack:

``````attack = (1.d(20) + 4).test_then do |result|
if result < 12
0.to_dice_expression
else
1.d(4) + 2
end
end
``````

This is just a `DiceExpression`, so we can get its value, and reroll it:

``````attack.value # => 0, the poor guy missed
attack.reroll.value # => 3, he hit... and critfailed damage.
``````

Even more interestingly, however, we can do statistics on it. Let's see the chance of him doing at least one damage:

``````attack.distribution.percent_greater(0) # => 0.65, 65% of doing damage
``````

What about the average damage per attack?

``````attack.average # => 2.925
``````

As long as the block passed to `test_then` is pure (IE, the same input maps to the same output, regardless of anything else that happens in the program), then we can do any kind of calculation we want inside of it. This is useful in a variety of situations.

### Simulation

FifthedSim was originally designed to simulate D&D 5e games. Doing this is still under construction, but it's coming along nicely.

Simulation is based on Actors. An Actor represents a character or NPC in the game. Actors are defined with a nice DSL:

``````actor = FifthedSim.define_actor("Bobby") do
base_ac 10
stats do
str 10
dex do
value 18
save_mod_bonus 5
end
wis 8
cha 16
con 14
int 12
end
attack "rapier" do
to_hit 5
damage do
piercing 1.d(6)
end
end
end
``````

Construction based on YAML or JSON is still a work in progress. Actors are intended to be used to simulate battles. This is currently a work in progress, although simulating individual attacks and such does currently work.

## Installation

``````gem 'fifthed_sim'
``````

And then execute:

``````\$ bundle
``````

Or install it yourself as:

``````\$ gem install fifthed_sim
``````

## Development

After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to rubygems.org.

## Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/anthonysuper/fifthedsim. Please see the HelpWanted.md file for specific patches we are looking for.