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/<tribename>/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 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.

Configuring a Tribe’s Units Usage¶

The tribes/initialization/<tribename>/units.lua file configures the units that a tribe can use.

new_tribe{table}

This function adds all units to a tribe.

Parameters: 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:

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 Helptexts, like this:

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 Helptexts, like this:

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 Helptexts for all the immovables that this tribe uses, like this:

immovables = {
   {
      name = "ashes",
      helptexts = {
         purpose = _("The remains of a destroyed building.")
      }
   },
   {
      ...
}

buildings: This defines the name and Helptexts for all the buildings that this tribe uses and their display order in the user interface, like this:

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 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:

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:

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:

fastplace = {
   warehouse = "atlanteans_warehouse",
   port = "atlanteans_port",
}

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:

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<br> 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.”

Bootstrapping a Tribe¶

Configuring a Tribe’s Units Usage¶

Helptexts¶

Table of Contents

Previous topic

Next topic

This Page