.. _lua_world_defining_units:

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

A world can have the following types of units:

* **Critters**: Animals that will move around the map at random
* **Immovables**: Trees, rocks, artifacts and eye candy
* **Resources**: Mineable map resources like fish, water, coal, ...
* **Terrains**: The base of the landscape. Meadows, mountains, water...

The definitions for the world's units are located in the subdirectories of
``data/world``. Each unit needs to have an ``init.lua`` file, which will load the unit to be used in the game.

Each ``init.lua`` file needs to have a matching ``register.lua`` file that
will list the names of all units defined in the ``init.lua``, 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. For a given ``init.lua``:

.. code-block:: lua

   push_textdomain("world")

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

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

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

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

   pop_textdomain()

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

.. code-block:: lua

   return {
      alder_summer_sapling = { "tree_sapling" },
      alder_summer_pole = {},
      alder_summer_mature = {},
      alder_summer_old = { "tree" }
   }


Note that ``alder_summer_pole`` and ``alder_summer_mature`` in this example have no attributes, so their
attribute tables are 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.

.. toctree::
   :maxdepth: 3

   autogen_critters_lua_world_units_init.rst
   autogen_immovables_lua_world_units_init.rst
   autogen_resources_lua_world_units_init.rst
   autogen_terrains_lua_world_units_init.rst