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 Energy 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 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.
2. Automated cache management for the random_org entropy source
3. Tests for entropy sources
4. 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