.. _scenario_units:

Scenario-Specific Units
-----------------------

When writing a scenario, you can create custom tribe objects for it.
At the moment, we support buildings, wares and workers.
If you need support for other types of tribe units, please open a new bug report.

For creating scenario-specific tribe objects, create a subdirectory
``scripting/tribes`` in your map.
In that subdirectory, place a file called ``init.lua``.
This file needs to return a table listing all the objects that the tribes do
not have by default. You can also add helptexts. For example:

.. code-block:: lua

   return {
      empire = {
         buildings = {
            {
               name = "empire_brewery1",
               helptexts = {
                  purpose = pgettext("empire_building", "Produces beer to keep the miners strong and happy.")
               }
            },
            name = "empire_trainingcamp1",
               helptexts = {
                  purpose = {
                     pgettext("empire_building", "Trains soldiers in ‘Attack’ and in ‘Health’."),
                     pgettext("empire_building", "Equips the soldiers with all necessary weapons and armor parts.")
                  },
                  note = pgettext("empire_building", "Imperial soldiers cannot be trained in ‘Defense’ and will remain at the level with which they came.")
               }
            },
            {
               name = "empire_temple_of_vesta",
               helptexts = {
                  purpose = pgettext("empire_building", "In the temple of Vesta, the wares to worship are stored. It is the home of the priestesses and the guards of the goddess.")
               }
            }
         }
         workers_order = {
            {
               {
                  name = "empire_vesta_priestess",
                  default_target_quantity = 1,
                  preciousness = 15
               }
            },
         },
         wares_order = {
            {
               {
                  name = "empire_vesta_wine"
                  default_target_quantity = 10,
                  preciousness = 4
               }
            },
         }
      },
      frisians = {
         buildings = {
            { name = "frisians_warehouse1" }
         }
      }
   }

If you are only replacing already existing objects, you can skip adding the
``init.lua`` file.

Now place your custom tribe objects into subdirectories below ``scripting/tribes``:

* In each subdirectory, there needs to be an ``init.lua`` file that adds all
  objects for that subdirectory.
  If an object has the same name as an already existing tribe object,
  it will replace that tribe object.
* You will also need to add a ``register.lua`` file that lists the names of all
  objects that you are adding or replacing.
* You can also add ``.png`` files to your subdirectories.
* Adding helptexts is optional, but units without a helptext will print a warning on the console.

See :ref:`defining_tribe_units` for further details on these files, and :ref:`lua_tribes_tribes_helptexts` on the helptext format.