1Buildings
2=========
3
4Buildings are defined in their ``init.lua`` file. They also have a corresponding ``helptexts.lua`` file that contains their help texts.
5
6Types of Buildings
7------------------
8
9Widelands knows about the following types of buildings:
10
11.. toctree::
12   :maxdepth: 3
13
14REPLACE_ME
15
16.. _lua_tribes_buildings_common:
17
18Common Building Properties
19--------------------------
20
21Buildings are defined with Lua functions called ``new_<building_type>_type{table}``. The contents of ``table`` depend on the type of building that you are defining. The common properties shared by all buildings are:
22
23
24**msgctxt**
25    *Mandatory*. The context that Gettext will use to disambiguate the translations for
26    strings in this table, e.g.::
27
28        msgctxt = "atlanteans_building",
29
30**name**
31    *Mandatory*. A string containing the internal name of this building, e.g.::
32
33        name = "atlanteans_fortress",
34
35**descname**
36    *Mandatory*. The translatable display name. Use ``pgettext`` with the ``msgctxt``
37    above to fetch the string, e.g.::
38
39        descname = pgettext("atlanteans_building", "Fortress"),
40
41**helptext_script**
42    *Mandatory*. The full path to the ``helptexts.lua`` script for this building.
43
44**icon**
45    *Mandatory*. The full path to the menu icon for this building.
46
47**representative_image**
48    *Optional*. The full path to a representative image for this building.
49    This is needed if the building has a scaled "idle" animation.
50
51**size**
52    *Mandatory*. The size of this building: ``"small"``, ``"medium"``, or ``"big"``.
53
54**vision_range**
55    *Optional. Default:* ``0``. The size of the radius that the building sees.
56
57**buildcost**
58    *Optional*. A table with the wares used to build this building, containing
59    warename - amount pairs, e.g.::
60
61        buildcost = { log = 4, granite = 2 }
62
63    When ``buildcost`` is defined, you also need to define ``return_on_dismantle``.
64
65**return_on_dismantle**
66    *Optional*. The wares that this building will give back to the player when it is
67    dismantled, e.g.::
68
69        buildcost = { log = 2, granite = 1 }
70
71**enhancement**
72    *Optional*. The name of a building that this building can be enhanced to, e.g.::
73
74        enhancement = "atlanteans_fancy_building",
75
76    If ``enhancement`` is defined, the building that this building enhances
77    to will need to define ``enhancement_cost`` and
78    ``return_on_dismantle_on_enhanced``.
79
80**enhancement_cost**
81    *Optional*. The wares needed to upgrade this building, e.g.::
82
83        enhancement_cost = { log = 1, granite = 1 }
84
85**return_on_dismantle_on_enhanced**
86    *Optional*. The wares that this enhanced building will give back to the player
87    when it is dismantled, e.g.::
88
89        return_on_dismantle_on_enhanced = { granite = 1 }
90
91**animation_directory**
92    *Mandatory*. The location of the animation png files.
93
94**animations**
95    *Mandatory*. A table containing all animations for this building. Every building
96    needs to have an ``idle`` animation. Other animations that a building
97    can have are ``build``, ``working``, ``unoccupied``. Mines also have
98    an ``unoccupied`` animation.
99    See :doc:`animations` for a detailed description of the animation format.
100
101**needs_seafaring**
102    *Optional. Default:* ``false``. Set to ``true`` if this building will only be available on seafaring maps.
103
104**aihints**
105    *Mandatory*. A list of name - value pairs with hints for the AI. Can be empty.
106
107
108.. toctree::
109   :maxdepth: 2
110
111   autogen_ai_hints
112
113
114Help Texts
115----------
116
117Each building has a ``helptexts.lua`` script, which is located in the same directory as its ``init.lua`` script.
118The functions in this file return texts that are used for buildings by the Tribal Encyclopedia.
119
120See also the helper functions in :ref:`lua_tribes_global_helptexts.lua`.
121
122
123.. function:: building_helptext_lore()
124
125   Returns a localized string with a lore helptext for this building.
126   If you don't have a lore text yet, use ``no_lore_text_yet()`` from the ``lua_tribes_global_helptexts.lua`` script.
127
128
129.. function:: building_helptext_lore_author()
130
131   Returns a localized string with a fictional author for the lore helptext for this building. The returned string can be empty.
132   If you don't have an author yet, use ``no_lore_author_text_yet()`` from the :ref:`lua_tribes_global_helptexts.lua` script.
133
134   :returns: Localized lore text
135
136
137.. function:: building_helptext_purpose()
138
139   Returns a localized string with a purpose helptext for this building. This should be individually defined for all buildings. You can use ``no_purpose_text_yet()`` from the :ref:`lua_tribes_global_helptexts.lua` script if you're not ready to define this yet.
140
141   :returns: Localized purpose text
142
143
144.. function:: building_helptext_note()
145
146   Returns a localized string with a note that is added to the purpose. This can be empty.
147
148   :returns: Localized note text or empty string.
149
150
151.. function:: building_helptext_performance()
152
153   Returns a localized string with a performance helptext for this building. You can use ``no_purpose_text_yet()`` from the :ref:`lua_tribes_global_helptexts.lua` script if the performance hasn't been calculated yet. Leave empty when this isn't applicable (e.g. for militarysites or warehouses).
154
155   :returns: Localized performance text or empty string.
156