widelands-dev team mailing list archive

[GunChleoc <fios@xxxxxxxxxxxxxxxxxxx>]

GunChleoc has proposed merging lp:~widelands-dev/widelands/bug-1730169-document-ai-hints into lp:widelands.

Commit message:
Added scripting documentation for the AI.

Requested reviews:
  Widelands Developers (widelands-dev)
Related bugs:
  Bug #1730169 in widelands: "Document AI Hints"
  https://bugs.launchpad.net/widelands/+bug/1730169

For more details, see:
https://code.launchpad.net/~widelands-dev/widelands/bug-1730169-document-ai-hints/+merge/333531
-- 
Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands/bug-1730169-document-ai-hints into lp:widelands.

=== modified file 'doc/sphinx/extract_rst.py'
--- doc/sphinx/extract_rst.py	2017-09-15 19:53:28 +0000
+++ doc/sphinx/extract_rst.py	2017-11-10 10:03:29 +0000
@@ -13,6 +13,7 @@
 # These files are known to have rst comments; cpp files
 # Meaning: (src_file, file_name_to_generate_rst)
 cpp_pairs = (
+    ('src/ai/ai_hints.cc', 'autogen_ai_hints.rst'),
     ('src/scripting/lua_root.cc', 'autogen_wl.rst'),
     ('src/scripting/lua_bases.cc', 'autogen_wl_bases.rst'),
     ('src/scripting/lua_editor.cc', 'autogen_wl_editor.rst'),

=== modified file 'doc/sphinx/source/lua_tribes_buildings.rst.org'
--- doc/sphinx/source/lua_tribes_buildings.rst.org	2016-11-13 15:23:06 +0000
+++ doc/sphinx/source/lua_tribes_buildings.rst.org	2017-11-10 10:03:29 +0000
@@ -102,6 +102,12 @@
     *Mandatory*. A list of name - value pairs with hints for the AI. Can be empty.
 
 
+.. toctree::
+   :maxdepth: 2
+
+   autogen_ai_hints
+
+
 Help Texts
 ----------
 

=== modified file 'src/ai/ai_hints.cc'
--- src/ai/ai_hints.cc	2017-08-26 11:08:00 +0000
+++ src/ai/ai_hints.cc	2017-11-10 10:03:29 +0000
@@ -21,6 +21,200 @@
 
 #include <memory>
 
+/* RST
+AI Hints and Restrictions
+=========================
+
+Every :doc:`building <autogen_toc_lua_tribes_buildings>`'s ``init.lua`` file has an ``aihints`` table in its ``new_<building_type>_type{table}``
+function. This ``aihints`` table can contain any number of entries, which will help the AI decide
+when and where to build or dismantle a building of that type and/or how to treat it.
+
+All entries in ``aihints`` are optional.
+
+- :ref:`ai_hints_introduction`
+- :ref:`ai_hints_common`
+- :ref:`ai_hints_military`
+- :ref:`ai_hints_production`
+
+.. _ai_hints_introduction:
+
+Introduction
+------------
+
+The AI has separate code paths for various building categories. Many of them are
+categories that contain one unique building (ranger, well, port, fish breeder,
+barracks and so on), and these cannot be combined with other types of buildings
+and are mostly mandatory.
+
+The main categories where you can freely modify and add buildings are:
+
+- Military sites
+- Training sites
+- Pure production sites (they have outputs, and optionally inputs, but no production hints)
+- Pure supporters (they have production hints, but neither inputs nor outputs)
+- A combination of supporter and production site is possible, but suboptimal
+
+You can create as many building types as you want in these main categories, but
+make sure that you don't combine any incompatible features (for example,
+``shipyard`` and ``mines`` don't combine).
+
+With the exception of the barracks and the building that produces carrier2
+(see: :ref:`lua_tribes_<tribename>.lua`), production of workers in production sites
+is not supported at this time.
+
+.. _ai_hints_common:
+
+Common Building Hints
+---------------------
+
+**basic_amount**
+    The amount of this building to be built while establishing a basic economy, e.g.::
+
+        basic_amount = 1,
+
+**forced_after**
+    If a building of this type hasn't been built already, force that a building
+    of this type will be constructed after the given time (in seconds) has elapsed,
+    e.g.::
+
+        forced_after = 890,
+
+    **Note:** ``forced after`` can interfere with setting up the basic economy
+    defined by ``basic_amount``: if we don't want the building to be part of the
+    basic economy but it is forced before all the buildings for the basic economy
+    have been built, this can lead to unobvious behavior. Part of this ambiguity
+    is due to the genetic algorithm.
+
+**prohibited_till**
+    Do not build this building before the given time (in seconds) has elapsed, e.g.::
+
+        prohibited_till = 1500,
+
+    This takes precedence over ``basic_amount``, so it means it can delay achieving
+    the basic economy.
+
+**very_weak_ai_limit**
+    The maximum number of this building type that the very weak AI is allowed to build, e.g.::
+
+        very_weak_ai_limit = 1,
+
+**weak_ai_limit_**
+    The maximum number of this building type that the weak AI is allowed to build, e.g.::
+
+        weak_ai_limit_ = 2,
+
+.. _ai_hints_military:
+
+Military Sites
+--------------
+
+**expansion**
+    The building will be used by the AI for expanding the territory, e.g.::
+
+        expansion = true,
+
+    **Note:** It is recommended to have at least one building has this feature.
+
+**fighting**
+    The building is suitable for military conflicts, e.g.::
+
+        fighting = true,
+
+    **Note:** It is recommended to have at least one building has this feature.
+
+**mountain_conqueror**
+    Prefer this type of military site near mountains, e.g.::
+
+        mountain_conqueror = true,
+
+    **Note:** It is recommended to have at least one building has this feature.
+
+.. _ai_hints_production:
+
+Production Sites
+----------------
+
+**graniteproducer**
+    The building will produce the ``granite`` ware, e.g.::
+
+        graniteproducer = true,
+
+    The AI expects exactly one such building type.
+
+**logproducer**
+    The building will produce the ``log`` ware, e.g.::
+
+        logproducer = true,
+
+    The AI expects exactly one such building type.
+
+**mines**
+    The building will mine to obtain the given ware, e.g.::
+
+        mines = "gold",
+
+**mines_percent**
+    The percentage that a mine will mine of its resource before it needs enhancing, e.g.::
+
+        mines_percent = 60,
+
+**mines_water**
+    The building will mine to obtain the ``water`` ware, e.g.::
+
+        mines_water = true,
+
+    **Note:** The AI expects exactly one such building type.
+
+**needs_water**
+    The building needs to be placed near a body of water, e.g.::
+
+        needs_water = true,
+
+    **Note:** The AI expects exactly one such building type.
+
+**recruitment**
+    The building will recruit the tribe's carrier2, for example oxen or horses, e.g.::
+
+        recruitment = true,
+
+**shipyard**
+    This building will construct ships, e.g.::
+
+        shipyard = true,
+
+    **Note:** The AI expects exactly one such building type.
+
+**space_consumer**
+    The building needs a lot of space around it, for example a farm needs space for
+    its fields, e.g.::
+
+        space_consumer = true,
+
+**supports_production_of**
+    This building will support the production of the given wares without producing
+    it directly, e.g.::
+
+        supports_production_of = { "fish" },
+
+    For example, if a building supports the production of fish, it should be placed
+    near a building that has fish in its output.
+
+    **Note:** The AI expects that supporters will have no inputs and no outputs. Although
+    the AI can tolerate such buildings, they will be primarily treated as normal
+    production sites when deciding on the building's location.
+
+**trainingsites_max_percent**
+    The maximum percengate this training site will have among all training sites, e.g.::
+
+        trainingsites_max_percent = 20,
+
+    In this example, if an AI has built 5 training sites, it will have a maximum of
+    1 site of this type. If it has built 10 training sites, the maximum is 2.
+    For training sites that don't have this value set, their percentage will be
+    distributed evenly.
+
+*/
+
 BuildingHints::BuildingHints(std::unique_ptr<LuaTable> table)
    : mines_(table->has_key("mines") ? table->get_string("mines") : ""),
      log_producer_(table->has_key("logproducer") ? table->get_bool("logproducer") : false),