:title:Game DSL Rails Plugin

=Game DSL Rails Plugin

== Introduction
The Game DSL is designed to provide a Rails syntax for introducing randomness (entropy)
into your application. The actual syntax resembles that used in role-playing games and
card games. Different sources of entropy can be used in a method similar to database
adapters in rails.

== Installation

Installation follows the normal process for rails plugins.

    ruby script/plugin install http://svn.northpub.com/plugins/game_dsl

If you have svn.northpub.com on your list of plugin sources you can simply use

    ruby script/plugin install game_dsl
	
After installation  you need to set up an entropy.yml file. For starters it can
look like this.

    development:
	  source: kernel

See Sources of Entropy below for more information on your options in entropy.yml.

== Tutorial

Using the dsl is pretty simple.

=== Die Rolling

Die rolling uses a syntax that should be familiar to anybody who plays adventure
games.

    hit_roll = 1.d20 # return a random number between 1 and 20
    strength = 3.d6 # return the sum of 3 six sided-dice

The usual dice are supported: 2,4,6,8,10,12,20,30, and 100. Fudge(www.fudgerpg.com)
dice are also supported as dF. You can roll multiple dice and keep the best
results, as follows:

    strength - 4.d6 :keep_best => 3 # rolls 4 dice and returns the sum of the best three.
	
=== Card Shuffling and Dealing

The game_dsl can also be used to randomize arrays like decks of cards. You can
do this by using acts_as_deck in you model. Then you can use the shuffle and
draw commands on arrays of that model.

    class Card < ActiveRecord::Base
		acts_as_deck
	end

In the controller
	
	def start_game
		@deck = Cards.find :all
		@deck.shuffle!
	end
	
	def play_hand
		@card = @deck.draw!
	end
	
Note that shuffle comes in a destructive (shuffle!) and non-destructive (shuffle)
version, like Array.sort. The draw! method is only destructive to the array.

== Sources of Entropy
Right now only two sources of entropy are supported, kernel and random_org.

=== kernel
This is the simplest source of entropy. It uses Ruby's built-in rand function and takes
an option seed parameter. Configuration for it in entropy.yml looks like this.

		# development uses default seed value -- which is actually time and pid
		development:
			source: kernel

		# test uses a fixed seed for repeatability
		test:
			source: kernel
			seed: 42

		# production used the time (and pid) for the seed value
		production:
			source: kernel
			seed: time
			
=== random_org
This source of entropy uses random data from http://www.random.org and caches it
as 8-byte integers in the database. In order to use this option you need to do a couple
of things first. You need to install the mysql_bigint plugin using one of the two
following commands.

    ruby script/plugin install mysql_bigint
    ruby script/plugin install http://svn.northpub.com/plugins/mysql_bigint

Create a entropy.yml file with entries like the following.

		development:
			source: random_org
			
Now you need to create a migration to set up the database cache. Run the following
commands.

    script/generate game_dsl
    rake migrate
	
Finally you need to preload the database cache. This command will load 10,000 numbers
from random.org and store them in the database. This command can be run a few times
to load additional groups of 10,000 numbers.

	rake game_dsl:load_random_numbers

Note, per the sites rules, it won't drag the site's entropy pool below 20%. so if the
site is busy the process will suspend and wait for entropy to rise above 20% before
continuing. 

== Testing

Tests of the DSL can be executed with 

    rake test:plugins
	
I have tests written to test the functionality and randomness of the entropy
sources. However, at the moment these use code that came from my Numerical Recipes
book and I can't release it to Open Source. New version should be available soon
that will help anybody who wants to create additional entropy sources.

== Issues

* No automated cache management for the random_org entropy source. Currently it is your job to make sure that you don't run out of random numbers.

== Future Work

1. A dev_random and a dev_urandom entropy source for linux and unix machines. These should give better randomness than the kernel source without the cache management issues of random_org.

1. Automated cache management for the random_org entropy source

1. Tests for entropy sources

1. More die rolling options, including returning the values of the individual rolls.

== Feedback and Bug Reports

Send any feedback, bugs or patches to 

    shammond at northpub.com