Name

Cosair::AI::Bot - Cosair Bot Superclass


Synopsis

This class is the superclass for every Cosair playing bot. It provides a default bahaviour and allows bot programmers to overwrite any methods they want, in order to implement their own decision logic for certain decisions.


Description

All methods in this class are object methods. To get the reference to your instance, use the implicit first parameter of a method call as the first statement in your method:

        my $self = shift;

Administrative Methods

control()

Returns the control object associated with this bot. The return value is a reference to a Cosair::AI::Control object.

mem($)

Get the memorised value identified by a given key. The only parameter is the key identifier for the value in question. Returns undef if no such key exists in the bot's memory. If this method is called in array context, the memorised value is treated as a "set" as described in the Cosair Bot Programming Manual and the method will return an array of the set's elements.

set_mem($@)

Memorises a given value under a given key. The first parameter is the key identifier for the value. The second parameter is the scalar value to memorise. If you pass more than one value, i.e. an array, the parameters will be automatically transformed to a set as described in the Cosair Bot Programming Manual and then be memorised.

Here's a short example showing handling of arrays with the Bot's memory:

        # scalar usage:
        $self->set_mem('target_id', $target->id());
        ...
        my $target_id = $self->mem('target_id');
        
        # list usage:
        $self->set_mem('target_ids', @ids);
        ...
        @ids = $self->mem('target_ids');
        # or even:
        my %attack_info = (start_id=>5, cruisers=>16, transports=4, target_id=>2);
        $self->set_mem('attack_info', %attack_info);
        ...
        %attack_info = $self->mem('attack_info');

As you can see, this results in a naturally transparent behaviour when memorising arrays or hashes of scalar values.


=cut

sub set_mem { my $self = shift; my $key = shift; my $value; if(@_ == 1) { $value = shift; } else { if(grep {not defined $_} @_) { my($package, $file, $line) = caller; die("raised at $file line $line:\ntrying to memorise undef value in list"); } $value = set_new(@_); } $self->{control}->{memory}->{$key} = $value; }

log_message($;@)

Appends a message to the bots message logfile. The only parameter is the message string to be logged. Optionally, you can pass a format string as first parameter and the substitution values as following parameters, the message is then automatically passed through an sprintf evaluation. The game id and the turn number will be prepended automatically.

Here's a short example of sprint-usage:

        $self->log_message('Found %d targets in range %.1f.', $num_targets, $range);

init()

This method is called once before the game starts and can be overwritten to initialise your bot, if required.

Low-Level Methods

decide_global()

This is the main routine called for each turn. It simply calls the init_turn() and all global problem specific methods in the order given below. This allows to overwrite global low-level decision methods selectively.

init_turn()

Overwrite this method if you need any global initialisation for your bot at the beginning of each turn.

decide_global_researchgoal()

This method calls the high-level method decide_techlist() whenever a nation can choose a new technology to be researched. The next technology of the list is selected and a corresponding action to research it is issued.

decide_global_taxrate()

This method calls the high-level method decide_taxrate(), if the tax rate is not fixed at 100% yet. If the method returns a different tax rate than the prior one, an action to adjust the tax rate accordingly is issued.

decide_global_recruitment()

This method calls the high-level method decide_recruitment() if the nation currently can recruit a new agent. If the method indicates to recruit a new agent, a corresponding action is issued.

decide_global_colonisations()

This method searches all planets of the nation that can start a new colonisation and calls the high-level method decide_planet_colonisation() for them. Depending on the return value an appropriate colonisation action is issued.

decide_global_items()

This method searches all planets of the nation that have 1 or less build items in their queue and calls the high-level method decide_planet_items() for them. For each item returned by the method a corresponding action to enqueue them is issued.

decide_global_rush()

This method calls the high-level method decide_planet_rush() on all planets currently building an item. Depending on the return value an appropriate action is issued.

decide_global_agent_missions()

This method does nothing by default. If you want your agents to go on missions, you have to overwrite this low-level method.

To start a mission, get a Cosair::AI::Agent object via your Cosair::AI::OwnNation and call the start_mission() method on it.

decide_global_fleet_movements()

This method does nothing by default. If you want your fleets to move, you have to overwrite this low-level method.

To move a fleet, get a Cosair::AI::Fleet object via your Cosair::AI::OwnNation or a Cosair::AI::OwnPlanet and call the move_ships() method on it.

High Level Methods

Overwrite these methods in order to implement the decision-specific behaviour of your bot.

decide_techlist()

This method is called whenever a new technology can be researched. It should return an array of technology keywords and the technologies will automatically be researched in the given order.

More concretely, the first technology of the returned list that is not yet researched by the nation, will be chosen as the next research goal.

Check the source code to see the default list. It prefers defensive non-building technologies.

decide_taxrate()

This method is called in regular intervals and should return a tax rate value between 20 and 80 in steps of 10.

The default implementation fixes the tax rate at 80%.

decide_recruitment()

This method is called in regular intervals and should return a boolean value to indicate whether to recruit a new agent or not.

The default implementation always keeps the number of agents equal to the number of planets of the nation.

decide_planet_colonisation($)

This method is called whenever a planet can start a colonisation. It should return a 0 if the colonisation shall not be started, a positive number otherwise. A positive return value is interpreted as the number of cruisers to be sent as escort with this colonisation. These cruisers must be currently stationed on the planet.

The default implementation starts a colonisation if the nation possesses at least the amount of gold the colonisation costs and if the planet has at least 2 cruisers stationed on it. Half of the stationed cruisers are sent as escort with the colonisation.

decide_planet_items($)

This method is called whenever the build list of a planet has only one or no items left. It should return a list of items to build which will be inserted in the given order. Return a scalar value if you want to build only one item. Return an empty list if you want to produce tradegoods. The item keywords are listed in the Cosair Bot Programming Manual. The methods gets the corresponding Cosair::AI::OwnPlanet passed as the first explicit argument.

The default implementation builds a colonyship if the planet is full, packs of 5 cruisers each otherwise.

decide_planet_rush($)

This method is called whenever a planet is currently building an item. It should return a 1 if production rush should be or stay activated and a 0 if it should be or stay deactivated on this planet. The methods gets the corresponding Cosair::AI::OwnPlanet passed as the first explicit argument.

The default implementation always keeps the rush as it is.