doc/README.agents

   1
   2 Overview
   3 ========
   4
   5 An agent is a piece of code which is responsible for a certain
   6 area. An agent will be given a specification by the user of the agent
   7 and a set of objects which the agent can control (the production
   8 queue of a city, a city, a unit, a set of units or the whole
   9 empire). The user can be a human player or another part of the code
  10 including another agent. There is no extra interaction between the
  11 user and the agent needed after the agent got its task description.
  12
  13 Examples of agents:
  14  - an agent which is responsible for moving a certain unit from A to B
  15  - an agent which is responsible for maximize the food production of a
  16  city
  17  - an agent which is responsible for the production queue of a city
  18  - an agent which is responsible for defending a city
  19  - an agent which is responsible for a city
  20  - an agent which is responsible for all cities
  21
  22 An agent may use other agents to accomplish its goal. Such decencies
  23 form a hierarchy of agents. The position in this hierarchy is denoted
  24 by a level. A higher level means more complexity. So an agent of level
  25 n can only make use of agents of level (n-1) or lower. Level 0 defines
  26 actions which are carried out at the server and are atomic actions
  27 (actions which can't be simulated at the client).
  28
  29 By such a definition an agent doesn't have to be implemented in C and
  30 also doesn't have to make use of client/agents/agents.[ch].
  31
  32 The core of an agent consist of two parts: a part which makes
  33 decisions and a part which carries out the decision. The results of
  34 the first part should be made available. An agent lacking the
  35 execution part is called advisor.
  36
  37 An agent should provide a GUI besides the core.
  38
  39 Implementation
  40 ==============
  41
  42 The received task description and any decision been made can be saved
  43 in attributes. An agent should not assume anything. This includes
  44 especially: _no magic numbers_. Everything should be settable by the
  45 user.
  46
  47 Use client/agents/agents.[ch] to get informed about certain
  48 events. Don't hesitate to add more callbacks. Use
  49 client/agents/agents:wait_for_requests instead of
  50 client/civclient:wait_till_request_got_processed.