[freeciv-ai] Re: About agents

[Raimar Falke <i-freeciv-lists@xxxxxxxxxxxxx>]

On Wed, Mar 17, 2004 at 09:14:24PM +0100, Guillermo Lopez Alejos wrote:
> Hi,
> 
> I'm studing the agents; I've read all related files in doc/ directory
> and agents.[ch] in client/agents/, but I cannot guess how agents work.
> 
> What are the purpose of that agents's calls?.
> 
> Can you tell me when the execution of an agent starts?, what functions
> are called?.

I assume you read the basic information (split AI into parts,
calculation part and display part,...).

The agents need a way to execute an request on the server and get the
state after the server executes this request. You may call this a
"synchronized call" (call == request + response). wait_for_requests()
is for this.

Why do you need such "synchronized call" aynway? Because the agent has
to perform calculations at the client (for example calculate a path,
or a city state with a certain worker allocation). Then the server
executes the "plan" at the server. It now has to check if the client
idea how things work matches the one of the server. So the client
sends the request(s), calls wait_for_requests() and than checks if the
new client state is the expected.

The remaining functions of agents.c deal with notifies. The agents as
a whole are event based. The can be wake-up/called
back/notified/evented if either the client state changes or some other
agent wake them. So the agents.c act as a demultiplexer for all client
state change events (either caused by incoming packet or by another
agent). agents.c will callback all agents which want to be informed
about such event type.

Internally it is a bit more complicated since you only want one
callback active at a time. You also don't want to callback is the
client game state is inconsistent (not all new info packets which are
caused by the request have arrived yet). You also don't want to end
the turn if an agent is still busy (calculating or waiting for the
server on an "synchronized call").

And you want to have a certain order of callbacks. Suppose you have
two agents LOW (a low level agent) and HIGH (an higher level agent
which uses LOW). Now the callback of LOW looks like:

  calculate the plan
  execute on the server
  if goal reached detach from object

The callback of the HIGH level looks like:

  if LOW isn't working with object:
     calculate parameter for LOW
     attach LOW to object

Now if LOW is called before HIGH it may turn out that LOW reaches its
goal. HIGH will than attaches LOW again to the object. If however the
callback order is reversed you have a problem.

Hope this helps.

        Raimar

-- 
 email: rf13@xxxxxxxxxxxxxxxxx
 "SIGDANGER - The System is likely to crash soon"