/ 
AI-Evolve-Befunge-0.03
River stage zero No dependents
/ AI::Evolve::Befunge::Physics

NAME

AI::Evolve::Befunge::Physics - Physics engine base class

SYNOPSIS

For a rules plugin (game or application):

register_physics(
    name       => "ttt",
    token      => ord('T'),
    decorate   => 0.
    board_size => Language::Befunge::Vector->new(3, 3),
    commands   => { M => \&AI::Evolve::Befunge::Physics::op_board_make_move },
);

For everyone else:

$ttt = Physics->new('ttt');
my $score = $ttt->double_match($blueprint1, $blueprint2);

DESCRIPTION

This module serves a double purpose.

First, it serves as a plugin repository for Physics engines. It allows physics engines to register themselves, and it allows callers to fetch entries from the database (indexed by the name of the Physics engine).

Second, it serves as a base class for Physics engines. It creates class instances to represent a Physics engine, and given a blueprint or two, allows callers to run creatures in a universe which follow the rules of that Physics engine.

STANDALONE FUNCTIONS

register_physics

register_physics(
    name       => "ttt",
    token      => ord('T'),
    decorate   => 0.
    board_size => Language::Befunge::Vector->new(3, 3),
    commands   => { M => \&AI::Evolve::Befunge::Physics::op_board_make_move },
);

Create a new physics plugin, and register it with the Physics plugin database. The "name" passed here can be used later on in ->new() (see below) to fetch an instance of that physics plugin.

The arguments are:

name:       The name of the Physics module.  Used by Physics->new
            to fetch the right plugin.
token:      A unique numeric token representing this Physics
            plugin.  It is possible that a Critter could evolve
            that can function usefully in more than one universe;
            this token is pushed onto its initial stack in order
            to encourage this.
decorate:   Used by graphical frontends.  If non-zero, the
            graphical frontend will use special icons to indicate
            spaces where a player may move.
commands:   A hash of op callback functions, indexed on the
            Befunge character that should call them.
board_size: A Vector denoting the size of a game's board.  This
            field is optional; non-game plugins should leave it
            unspecified.

find_physics

my $physics = find_physics($name);

Find a physics plugin in the database. Note that this is for internal use; external users should use ->new(), below.

CONSTRUCTOR

new

my $physics = Physics->new('ttt');

Fetch a class instance for the given physics engine. The argument passed should be the name of a physics engine... for instance, 'ttt' or 'othello'. The physics plugin should be in a namespace under 'AI::Evolve::Befunge::Physics'... the module will be loaded if necessary.

METHODS

Once you have obtained a class instance by calling ->new(), you may call the following methods on that instance.

run_board_game

my $score = $physics->run_board_game([$critter1,$critter2],$board);

Run the two critters repeatedly, so that they can make moves in a board game.

A score value is returned. If a number greater than 0 is returned, the critter wins. If a number less than 0 is returned, the critter loses.

The score value is derived in one of several ways... first priority is to bias toward a creature which won the game, second is to bias toward a creature who did not die (when the other did), third, the physics plugin is asked to score the creatures based on the moves they made, and finally, a choice is made based on the number of resources each critter consumed.

compare

$rv = $physics->compare($rv1, $rv2);

Given two return values (as loaded up by the "run_board_game" method, above), return a comparison value for the critters they belong to. This is essentially a "$critter1 <=> $critter2" comparison; a return value below 0 indicates that critter1 is the lesser of the two critters, and a return value above 0 indicates that critter1 is the greater of the two critters. The following criteria will be used for comparison, in decreasing order of precedence:

The one that won
The one that didn't die
The one that scored higher
The one that made more moves
The one that had more tokens afterwards
The one with a greater (asciibetical) name

setup_and_run_board_game

my $score = $physics->setup_and_run_board_game($bp1, $bp2);

Creates Critter objects from the given Blueprint objects, creates a game board (with board_size as determined from the physics plugin), and calls run_board_game, above.

double_match

my $relative_score = $physics->double_match($bp1, $bp2);

Runs two board games; one with bp1 starting first, and again with bp2 starting first. The second result is subtracted from the first, and the result is returned. This represents a qualitative comparison between the two creatures. This can be used as a return value for mergesort or qsort.

COMMAND CALLBACKS

These functions are intended for use as Befunge opcode handlers, and are used by the Physics plugin modules.

op_make_board_move

01M

Pops a vector (of the appropriate dimensions for the given board, not necessarily the same as the codesize) from the stack, and attempts to make that "move". This is for Physics engines which represent board games.

op_query_tokens

T

Query the number of remaining tokens.