.. _defining_tribe_units:

Defining Units
==============

A tribe can have the following types of units: buildings (militarysites,
partially_finished, productionsites, trainingsites and warehouses; headquarters
are a special case of warehouse), immovables, workers, wares, and a ship.

The definitions for the tribes' units are located in the subdirectories of
``data/tribes``. Each subdirectory needs to have a ``register.lua`` and an ``init.lua``
file.

* ``register.lua`` will inform the engine about the existence of units and their attributes if they have any.
  Attributes are only supported for immovables (and critters).
  This is needed for registering the objects before they are loaded.
* ``init.lua`` will load the units if they are used in the game
* Help texts contained in ``data/tribes/initialization/<tribe_name>/units.lua`` will provide the information
  used by the in-game help ('Tribal Encyclopedia') and by our website's online
  `Encyclopedia <https://wlww.widelands.org/encyclopedia/>`_.

Example for ``init.lua``:

.. code-block:: lua

   push_textdomain("tribes")

   wl.Descriptions():new_immovable_type {
      name = "berry_bush_blueberry_tiny",
      ...
   }

   wl.Descriptions():new_immovable_type {
      name = "berry_bush_blueberry_small",
      ...
   }

   wl.Descriptions():new_immovable_type {
      name = "berry_bush_blueberry_medium",
      ...
   }

   wl.Descriptions():new_immovable_type {
      name = "berry_bush_blueberry_ripe",
      ...
   }

   pop_textdomain()


The matching ``register.lua`` would look like this:

.. code-block:: lua

   return {
      berry_bush_blueberry_tiny = { "seed_berrybush" },
      berry_bush_blueberry_small = {},
      berry_bush_blueberry_medium = { "flowering" },
      berry_bush_blueberry_ripe = { "ripe_bush" },
   }

.. note:: If you are defining multiple unit types that can be enhanced or that will
   transform into each other in the same ``init.lua``, the enhanced/transformed type
   needs to be listed first.
   Also, ``berry_bush_blueberry_small`` in this example has no attributes, so its
   attribute table is empty.

In addition to its normal attributes, every unit defined by an add-on needs to define exactly one of the special attributes ``__skip_if_exists`` or ``__replace_if_exists``. This attribute determines how the engine proceeds if a description of the same name has already been registered. Units not contained in an add-on may not use these attributes.

Available unit types:

.. toctree::
   :maxdepth: 3

   autogen_toc_lua_tribes_buildings
   autogen_toc_lua_tribes_workers
   autogen_immovables_lua_tribes_units_init.rst
   autogen_ships_lua_tribes_units_init.rst
   autogen_wares_lua_tribes_units_init.rst