view release on metacpan or  search on metacpan

lib/Games/Perlwar/Rules.pod  view on Meta::CPAN

=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,