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