.. _lua_tribes_tribes_init: Bootstrapping a Tribe --------------------- Each tribe needs to have some basic information defined for displaying it in menus and for loading its game starting conditions. The file **has to be located in** ``tribes/initialization//init.lua`` so that the engine can find it. This file returns a table with the basic information for a tribe that is needed before a game is loaded or the editor has been started. The table has the following entries: * **name**: A string containing the internal name of the tribe * **author**: The creator(s) of the tribe * **descname**: In-game display name of the tribe * **tooltip**: A description of the tribe to be shown in tooltips * **icon**: File path to a png file to be used as button image * **script**: File path to the :ref:`units.lua ` file that configures which units the tribe is using * **starting_conditions**: A table of file paths to starting condition Lua scripts * **suited_for_ai** (optional, defaults to ``true``): Whether it is allowed to assign this tribe to AI players. .. _lua_tribes_tribes_units: Configuring a Tribe's Units Usage --------------------------------- The ``tribes/initialization//units.lua`` file configures the units that a tribe can use. .. function:: new_tribe{table} This function adds all units to a tribe. :arg table: This table contains all the data that the game engine will add to the tribe. It contains the following entries: **name**: A string containing the internal name of the tribe. **animations**: Global animations. Contains subtables for ``frontier``, ``flag``, and ``pinned_note``. Each animation needs the parameter ``hotspot`` (2 integer coordinates), and may also define ``fps`` (integer frames per second). **animation_directory**: The location of the animation png files. **bridges**: Contains animations for ``normal_e``, ``normal_se``, ``normal_sw``, ``busy_e``, ``busy_se`` and ``busy_sw``. **bridge_height**: The height in pixels of each bridge at it's summit at 1x scale. **collectors_points_table**: An array of tables of warename-integer pairs used by the Collectors win condition. This table shall contain gold and all weapons and armor needed for soldier training. **warehouse_names**: A list of strings with warehouse names presented to the user - be creative. Example: .. code-block:: lua warehouse_names = { pgettext("warehousename", "Kos"), pgettext("warehousename", "Patmos"), } **roads**: The file paths for the tribe's road textures in 3 subtables ``busy``, ``normal`` and ``waterway``. **resource_indicators**: The names for the resource indicators. This table contains a subtable for each resource name plus a subtable named ``""`` for no resources. Each subtable is an array, in which the index of each entry is the highest amount of resources the indicator may indicate. **wares_order**: This defines all the wares that this tribe uses and their display order in the user interface. Each subtable defines a column in the user interface, and in a current development version it contains subtables in turn for each ware referenced. The subtables define the ware's ``name``, ``default_target_quantity``, ``preciousness``, and :ref:`lua_tribes_tribes_helptexts`, like this: .. code-block:: lua wares_order = { { -- Building Materials { name = "granite", default_target_quantity = 20, preciousness = 5, helptexts = { purpose = pgettext("ware", "Granite is a basic building material.") } }, { ... The meaning of the ware parameters is as follows: **name**: A string containing the internal name of this ware. **default_target_quantity**: *Optional* The default target quantity for the tribe's economy. If not set, the economy will always demand this ware. If set to zero, the economy will not demand this ware unless it is required in a production building. If not set or set to zero, the actual target quantity will not be available in the economy settings window. **preciousness**: How precious this ware is to this tribe. We recommend not going higher than ``50``. **workers_order**: This defines all the workers that this tribe uses and their display order in the user interface. Each subtable defines a column in the user interface, and in a current development version it contains subtables in turn for each worker referenced. The subtables define the worker's ``name``, ``default_target_quantity``, ``preciousness`` and :ref:`lua_tribes_tribes_helptexts`, like this: .. code-block:: lua workers_order = { { -- Carriers { name = "atlanteans_carrier", helptexts = { purpose = pgettext("atlanteans_worker", "Carries items along your roads.") } }, { name = "atlanteans_ferry" }, { name = "atlanteans_horse", default_target_quantity = 10, preciousness = 2 }, { name = "atlanteans_horsebreeder" } }, { ... The meaning of the worker parameters is the same as for the wares, but both ``default_target_quantity`` and ``preciousness`` are optional. However, when ``default_target_quantity`` has been set, you will also need to set ``preciousness``. **immovables**: This defines the name and :ref:`lua_tribes_tribes_helptexts` for all the immovables that this tribe uses, like this: .. code-block:: lua immovables = { { name = "ashes", helptexts = { purpose = _("The remains of a destroyed building.") } }, { ... } **buildings**: This defines the name and :ref:`lua_tribes_tribes_helptexts` for all the buildings that this tribe uses and their display order in the user interface, like this: .. code-block:: lua buildings = { { name = "atlanteans_shipyard", helptexts = { purpose = pgettext("building", "Constructs ships that are used for overseas colonization and for trading between ports.") } }, } **builder**: The internal name of the tribe's builder. This unit needs to be defined in the ``workers_order`` table too. **carriers**: An :class:`array` with the internal names of the tribe's carrier and beasts of burden. Must have at least two entries, the first of which is used as the tribe's primary carrier and the second of which as the tribe's secondary carrier. These units need to be defined in the ``workers_order`` table too. **carrier**: **Deprecated**. Replaced by **carriers**. **carrier2**: **Deprecated**. Replaced by **carriers**. **geologist**: The internal name of the tribe's geologist. This unit needs to be defined in the ``workers_order`` table too. **soldier**: The internal name of the tribe's soldier. This unit needs to be defined in the ``workers_order`` table too. **ship**: The internal name of the tribe's ship. **ferry**: The internal name of the tribe's ferry. **port**: The internal name of the tribe's port building. This unit needs to be defined in the ``buildings`` table too. **scouts_house**: The internal name of the tribe's scout's hut or house. This unit needs to be defined in the ``buildings`` table too. **productionsite_worker_missing**: The string to display over this tribe's productionsites when 1 worker is missing. **productionsite_worker_coming**: The string to display over this tribe's productionsites when 1 worker is coming. **productionsite_workers_missing**: The string to display over this tribe's productionsites when more than 1 worker is missing. **productionsite_workers_coming**: The string to display over this tribe's productionsites when more than 1 worker is coming. **productionsite_experienced_worker_missing**: The string to display over this tribe's productionsites when 1 experienced worker is missing. **productionsite_experienced_workers_missing**: The string to display over this tribe's productionsites when more than 1 experienced worker is missing. **soldier_context**, **soldier_0_sg**, **soldier_0_pl**, **soldier_1_sg**, **soldier_1_pl**, **soldier_2_sg**, **soldier_2_pl**, **soldier_3_sg**, **soldier_3_pl**: The pgettext context for militarysites' soldier strings, and the corresponding **unlocalized** singular and plural strings. Additionally, it is necessary to specify an ``npgettext`` call for all four types of soldier strings so as to ensure that all keys appear in the PO files. The ``npgettext`` results (i.e. the translated pluralized strings for an arbitrary constant) are unused; the actual use is performed later in C++. Their table keys must be prefixed with ``UNUSED_``; the rest of the name is irrelevant. The strings themselves **must not** derivate from the template below in anything other than the name of the soldier. Make sure that the unlocalized string constants are exactly identical to the strings in the ``npgettext`` dummy calls. Example: .. code-block:: lua soldier_context = "atlanteans_soldier", soldier_0_sg = "%1% soldier (+%2%)", soldier_0_pl = "%1% soldiers (+%2%)", soldier_1_sg = "%1% soldier", soldier_1_pl = "%1% soldiers", soldier_2_sg = "%1%(+%2%) soldier (+%3%)", soldier_2_pl = "%1%(+%2%) soldiers (+%3%)", soldier_3_sg = "%1%(+%2%) soldier", soldier_3_pl = "%1%(+%2%) soldiers", -- TRANSLATORS: %1% is the number of Atlantean soldiers the plural refers to. %2% is the maximum number of soldier slots in the building. UNUSED_soldier_0 = npgettext("atlanteans_soldier", "%1% soldier (+%2%)", "%1% soldiers (+%2%)", 0), -- TRANSLATORS: Number of Atlantean soldiers stationed at a militarysite. UNUSED_soldier_1 = npgettext("atlanteans_soldier", "%1% soldier", "%1% soldiers", 0), -- TRANSLATORS: %1% is the number of Atlantean soldiers the plural refers to. %2% are currently open soldier slots in the building. %3% is the maximum number of soldier slots in the building UNUSED_soldier_2 = npgettext("atlanteans_soldier", "%1%(+%2%) soldier (+%3%)", "%1%(+%2%) soldiers (+%3%)", 0), -- TRANSLATORS: %1% is the number of Atlantean soldiers the plural refers to. %2% are currently open soldier slots in the building. UNUSED_soldier_3 = npgettext("atlanteans_soldier", "%1%(+%2%) soldier", "%1%(+%2%) soldiers", 0), **toolbar**: *Optional*. Replace the default toolbar images with these custom images. Example: .. code-block:: lua toolbar = { left_corner = dirname .. "images/atlanteans/toolbar_left_corner.png", left = dirname .. "images/atlanteans/toolbar_left.png", -- Will be tiled center = dirname .. "images/atlanteans/toolbar_center.png", right = dirname .. "images/atlanteans/toolbar_right.png", -- Will be tiled right_corner = dirname .. "images/atlanteans/toolbar_right_corner.png" } **fastplace**: *Optional*. Assigns some of the tribe's buildings to the default fastplace shortcut groups. Valid groups are: ``warehouse port training_small training_large military_small_primary military_small_secondary military_medium_primary military_medium_secondary military_tower military_fortress woodcutter forester quarry building_materials_primary building_materials_secondary building_materials_tertiary fisher hunter fish_meat_replenisher well farm_primary farm_secondary mill bakery brewery smokery tavern smelting tool_smithy weapon_smithy armor_smithy weaving_mill shipyard ferry_yard scout barracks second_carrier charcoal mine_stone mine_coal mine_iron mine_gold agriculture_producer agriculture_consumer_primary agriculture_consumer_secondary industry_alternative industry_supporter terraforming``. Example: .. code-block:: lua fastplace = { warehouse = "atlanteans_warehouse", port = "atlanteans_port", } .. _lua_tribes_tribes_helptexts: Helptexts --------- Helptexts are used in the Tribal Encyclopedia to give the users some basic information and lore about units. They are optional and defined in a ``helptexts`` subtable in the unit's listing. Example for a building: .. code-block:: lua buildings = { { name = "barbarians_ax_workshop", helptexts = { -- Lore helptext for a Barbarian production site: Ax Workshop lore = pgettext("barbarians_building", "‘A new warrior’s ax brings forth the best in its wielder – or the worst in its maker.’"), -- Lore author helptext for a Barbarian production site: Ax Workshop lore_author = pgettext("barbarians_building", "An old Barbarian proverb
meaning that you need to take some risks sometimes."), -- Purpose helptext for a Barbarian production site: Ax Workshop purpose = pgettext("barbarians_building", "Produces axes, sharp axes and broad axes."), -- Note helptext for a Barbarian production site: Ax Workshop note = pgettext("barbarians_building", "The Barbarian ax workshop is the intermediate production site in a series of three buildings. It is enhanced from the metal workshop but doesn’t require additional qualification for the worker."), performance = { -- Performance helptext for a Barbarian production site: Ax Workshop, part 1 pgettext("barbarians_building", "If all needed wares are delivered in time, this building can produce each type of ax in about %s on average."):bformat(format_seconds(57)), -- Performance helptext for a Barbarian production site: Ax Workshop, part 2 pgettext("barbarians_building", "All three weapons take the same time for making, but the required raw materials vary.") } }, ... }, immovables { ... }, wares { ... }, workers { ... } } * All units should have a ``purpose`` helptext, but this is not enforced by the engine. * Empty helptexts are allowed, although they will log a warning to the console to help you find missing helptexts. * ``lore``, ``lore_author`` and ``note`` are only used by buildings, ``performance`` is only used by training site and production site buildings. * The tribe’s scouting building should additionally define a ``no_scouting_building_connected`` text which will be shown in the UI when the Send Scout To Flag button is disabled for lack of a connected scout’s house/hut. * We recommend that you use ``pgettext`` to disambiguate the strings for the different tribes. * To make life easier for our translators, you can split long helptexts into multiple entries as with the ``performance`` example above. The helptexts are then joined by the engine. In our example, we will get *"If all needed wares are delivered in time, this building can produce each type of ax in about 57 seconds on average. All three weapons take the same time for making, but the required raw materials vary."*