=head1 NAME

Games::Perlwar - A Perl variant of the classic Corewar game


=head1 DESCRIPTION

	This is a sparring program, similar to the programmed reality of the Matrix. 
	It has the same basic rules, rules like gravity. What you must learn is that 
	these rules are no different than the rules of a computer system. Some of 
	them can be bent, others can be broken.  - Morpheus

Perlwar is inspired by the classic L<http://www.corewar.info/|Corewar> game.
In this game, players pit snippets of Perl code (called 'agents') against each other in order to
gain control of the vicious virtual battlefield known as... the Array.

=head1 GAME PARAMETERS

=over 

=item Size of the Array

The number of cells that the Array possesses. Each cell can hold one agent.

=item Agent Maximal Size 

The maximal length, in characters, of an agent. If an agent is or becomes larger than this limit, it automatically segfaults upon execution.

=item Game Maximal Number of Iterations

The maximal number of rounds that can be played before a game is declared over.

=back


=head1 DESCRIPTION OF A TURN

A turn of the game is made up of the following steps:

=head2 Introduction of New Agents

Each player has the opportunity to submit a new agent to be introduced into the Array. 
Insertions are treated in order of submission time. The cell into which an entrant agent
lands is picked randomly amongst the empty positions of the Array. 

If there are no empty
positions left, an entrant agent replaces one of the already-present agents owned
by the player, chosen randomly. If the player doesn't have any agents already
present in the Array, the new agent is  discarded.


=head2 Elimination of Players

A player is eliminated from the game if he doesn't have any agents present in the 
Array at the end of the introduction of new agents.


=head2 Running the Array

Each cell of the Array is visited sequentially. If a cell contains an agent, it is executed 
(agents exceeding the permitted length segfault on initialization). 

=head3 Variables accessibles to the agents

Variables which, if modified, affect the Array are marked by a (M).

=over

=item (M) $_  

the code of the agent. Changes brought to C<$_> are reflected in the Array
(that is, once executed, the agent's code is updated to the new value of C<$_>).

=item @_

the whole Array, positioned relatively to the current agent. (i.e., $_[0] eq $_ )

=item (M) $o (small oh)

the agent's facade (that is, the player it pretends to own allegiance to).
Modifications to this affect the Array.

=item @o (small oh)

Array holding the facade of all agents, positioned relatively to the current
agent.

=item $O  (big oh)

The agent's true master.

=item $S, $I, $i

the game's parameters $S (max agent's size) and $I (max # of iterations), plus the current iteration $i. 
Those are local variables and can't be used to modified the game parameters, obviously.

=back

=head3 Outcomes

If the agent segfaults, it is erased and the cell ownership is cleared. 

If the agent executes without segfault'ing, the changes made to $_ (that is, on the snippet itself)
are brought to the Array.
E.g., the snippet 

	$turn = 13; s/\d+/$&+1/e;

once executed, will become

	$turn = 14; s/\d+/$&+1/e;

In addition, the agent can return an instruction (see below). If it returns
a value that does not match any valid instruction, it is treated as a no-op.


=head1 Agent Return Instructions

An agent can return one instruction of the set below. All positions are are 
relative to the position of the executing agent.

=over

=item $x:$y

Copy the code of cell $x of @_ (as defined after execution of the agent) into position
$y of the Array (relative to the position of the current agent). $x and $y must be 
integers with an absolute value between 0 and $#_. 
If either $x or $y are not explicitly given, they default to 
the position 0. If the destination position is already occupied by an agent belonging to
a different player, the copy fails. If the copy succeed, the newly copied agent will only become operational during the next iteration (i.e., it will not be executed during
the current iteration). 

Example:

	# crawler - copy itself to the next position
	return ":1"
	


=item !$x

Nuke the agent presents in position $x. The cell then 
returns to its empty and unowned state. If $x is not given, defaults to 0.

Example:

	# berserker
	return '!'.1+int(rand(@_))

=item ~$x

Update the agent in position $x of the Array by its counterpart in @_. If $x is not explicitly given,
defaults to 0. Ownership of the modified agent isn't modified. If an agent isn't present,
nothing happens.

Example:

	# drive neighbor to suicide
	$_[1] =~ s//return "!"/;
	return "~1";

=item ^$x

Claim ownership of the agent in position $x of the Array. If there is no agent at that 
position, nothing happens.

Example:

	# crawling borg
	$pos = 1; 
	s/\d+/$&+1/e; 
	return "^$pos";

=back


=head1 END OF GAME

The game ends once the final round is played, or until all but one player have been eliminated. 
The winner of the game is the player with the most agents still alive
in the Array.

=head1 GAME VARIANTS

=over

=item Mambo War

In this variant, the agent maximal size is decremented after each turn. 

=back

=head1 VERSION

This document describes the rules of Perlwar as implemented 
in Games::Perlwar v0.03.


=cut

'end of Games::Perlwar::Rules';
