编辑“Building modding”

{{Version|3.0}}

This page is about modding [[Buildings]] and [[Districts]].

== Overview ==
Buildings require at least two files: a text document containing the building definition in {{Path|common/buildings}} and a language file in {{Path|localisation}}. Additionally, a custom icon for the building can be placed in {{Path|gfx/interface/icons/buildings}}. Districts are similar to buildings, except they are stacked together in the planet view. They are defined at {{Path|common/districts}}. This article will focus on building definitions. 

<pre>
building_sample_monument = { 

}
</pre>

The above is the start of a building definition called sample_monument. To the left of the equal sign is the building's identifier, which will be used to reference this building in other game files. Everything within the curly-brackets sets the behavior of the building, including its cost, upkeep, and prerequisites. The building's actual name and description are not part of this definition, however, but are instead looked up in the relevant localisation file. The keys for this are determined by the building's id, as seen below. See [[Localisation modding]] for more on how text is displayed in game.

<pre>
 building_sample_monument: "Sample Building"
 building_sample_monument_desc: "Description of sample building."
</pre>

In order to display the building in the planetary management window, the game will look for an image in {{Path|gfx/interface/icons/buildings}} folder with a file name matching the building's id and will generate an entry in the error log if it is not found. However, it will not use this image unless the icon attribute is actually set within the building definition, and instead use a generic building icon. See [[Icon modding]] for more on changing icons used by the game.

== Data Structure ==
{| class="wikitable"
|-
! width="20%" | Property
! width="40%" | Buildings
! width="40%" | Districts
|-
| '''base_buildtime = <int>'''
| colspan=2 | Determines the number of days it takes to build this Building or District. If Building, this also determines the days it takes for a Building to upgrade into this.
|-
| '''icon = <building_key>'''
| colspan=2 | Optional. The file name (without extension) of the icon to use from {{Path|gfx/interface/icons/buildings}}. By default, the icon <code>gfx/interface/icons/buildings/(key of building).dds</code> will be used for buildings.
|- 
| '''category = <category_key>'''
| Determines the building category. It can be used to filter Buildings in the planet construction GUI. Only one of the following nine can fit here, sorted by their in-game order.
* pop_assembly, government, resource, manufacturing,
* research, trade, amenity, unity, army
| rowspan=11 style="text-align: center;" | {{icon|no}}
|- 
| '''capital = <yes/no>'''
| Default no. Whether this Building is considered a Capital Building. If yes, not even a Fortress with <code>add_to_first_building_slot = yes</code> can be added before this Building.
|- 
| '''branch_office_building = <yes/no>'''
| Default no. If yes, this Building is considered a Branch Office Building.
|- 
| '''can_build = <yes/no>'''
| Default yes. If no, this Building can't be built. Capital buildings and upgraded buildings have "no" for this property.
|- 
| '''can_demolish = <yes/no>'''
| Default yes. If no, this Building can't be demolished. Capital buildings have "no" for this property.
|- 
| '''can_be_ruined = <yes/no>'''
| Default yes. If no, this Building can't be ruined because of the planet having not enough building slots.
|- 
| '''can_be_disabled = <yes/no>'''
| Default yes. If no, this Building can't be manually turned off. Capital buildings have "no" for this property.
|- 
| '''planetary_ftl_inhibitor = <yes/no>'''
| Default no. If yes, this Building will become a planetary FTL inhibitor once relevant technology has been researched. Fortresses use this.
|- 
| '''position_priority = <int>'''
| Default 200. Determines which building slot this Building will be placed in, with lower values closer to the front and Buildings with the same value placed in the order in which they were built.
* 0: Capitals.
* 100: Strongholds, Fortresses, Planetary Shield Generators, and certain civic and origin buildings.
|- 
| '''base_cap_amount = <int>'''
| Default no cap. The max number of Buildings of this type a planet can have.
|- 
| {{Collapse list | type= '''empire_limit = {'''
| body=
:'''base = <int>'''
:'''modifier = {'''
::'''<add/factor> = <int>'''
::'''<trigger>'''
:'''}'''
'''}'''
}}
| Default no limit. The total number of Buildings of this type an empire can have.<br>Multiply by a factor of -1 to remove the limit.
|- 
| '''is_capped_by_modifier = <yes/no>'''
| Default no. If yes, a modifier that increases the max number of this Building will be generated for use. In addition, if this property is yes while the <code>base_cap_amount</code> is unspecified, it will be considered 0.
| Default yes. If yes, a modifier that increases the max number of this District will be generated for use.
|- 
| '''min_for_deposits_on_planet = <int>'''
| rowspan=2 style="text-align: center;" | {{icon|no}}
| rowspan=2 | Unclear. They seem likely to determine the minimum / maximum number of this District a planet should try to have upon galaxy generation before modifiers, but this is actually not respected. When used in vanilla, min is either 1 or 3 and max is always 15.
|- 
| '''max_for_deposits_on_planet = <int>'''
|- 
| '''prerequisites = { "<key>" }'''
| colspan=2 | A list of technology keys to determine the technology prerequisites to construct this Building or District.
|- 
| '''show_tech_unlock_if = { <conditions> }'''
| A block of [[Conditions]]. If evaluated false, this building is hidden from the tooltips of the technologies listed above.
| rowspan=2 style="text-align: center;" | {{icon|no}}
|- 
| '''upgrades = { "<building_key>" }'''
| A list of Buildings that allow this to be upgraded into. Multiple allowed.
|- 
| '''potential = { <conditions> }'''
| A block of [[Conditions]] to determine is this Building buildable on a planet. If evaluated false, it's hidden from the GUI.
| Similar to Buildings, except if this property is evaluated false, the District is not only hidden from the GUI, but will also be removed from the planet, or be replaced by a District in <code>convert_to</code>.

Check the planet type here by <code>uses_district_set</code> rather than <code>is_planet_class</code>.
|- 
| '''show_on_uncolonized = { <conditions> }'''
| style="text-align: center;" | {{icon|no}}
| A block of [[Conditions]] to determine if this District is shown in the GUI while the planet has no owner. For example, a {{iconify|Hive Mind}} will see Hive District on an uncolonized planet while a regular Empire will see City District. (Planet scope, use FROM as a potential owner)

Check the planet type here by <code>uses_district_set</code> rather than <code>is_planet_class</code>.
|- 
| '''allow = { <conditions> }'''
| A block of [[Conditions]] to determine is this Building buildable on a planet. If evaluated false, it's visible from the GUI but is shown disabled. Can also be used in combination with <code>hidden_trigger = { OR = { owner = { is_ai = no } <conditions> } }</code> to set rules specifically for the AI to follow, so it's better at knowing when it should build this Building.
| Similar to Buildings, except if this property is evaluated false, the District is not only prevented from building, but will be replaced by a District in <code>convert_to</code>.
|- 
| '''abort_trigger = { <conditions> }'''
| A block of [[Conditions]]. If it returns true the Building will be removed the construction queue.
| rowspan=3 style="text-align: center;" | {{icon|no}}
|- 
| '''ruined_trigger = { <conditions> }'''
| A block of [[Conditions]]. If it returns true the Building will be set to ruined.

|- 
| '''destroy_trigger = { <conditions> }'''
| A block of [[Conditions]]. If it returns true the Building will be removed from a planet, or be replaced by a Building in <code>convert_to</code>.

|- 
| '''conversion_ratio = <float>'''
| style="text-align: center;" | {{icon|no}}
| If this District will be converted into another type of District, the number of new Districts it can convert into is multiplied by this. For example, if District A can be converted into District B at a <code>conversion_radio = 0.5</code>, once the <code>potential</code> of District A is evaluated false, a planet with 10 District A will lose all of them and gain 5 District B. The number is rounded down.
|- 
| '''convert_to = { building_key }'''
| A list of Buildings that can replace this Building if it would have been removed by fulfilling the <code>destroy_trigger</code>. 
| A list of Districts that can replace this District if it would have been removed by not meeting the <code>potential</code> and <code>allow</code>.
|-
| '''planet_modifier = { <modifiers> }'''
| colspan=2 | A block of [[Modifiers]] to be applied on the Planet.
|-
| {{Collapse list | type= '''triggered_planet_modifier = {'''
| body=
:'''potential = { <triggers> }'''
:'''<modifiers>'''
'''}'''
}}
| colspan=2 | Similar to the above, except it only applies if the <code>potential</code> property evaluates true. Multiple allowed. (Planet scope)
|- 
| '''country_modifier = { <modifiers> }'''
| A block of [[Modifiers]] to be applied to the Empire. Used by Resource Silos, Embassies, and Branch Office Buildings in vanilla.
{{red|Buildings currently do not support "triggered_country_modifier".}}
| style="text-align: center;" | {{icon|no}}
|-
| '''resources = { <economy_unit> }'''
| colspan=2 | An [[Economy_modding#Economy_Units|Economy Unit]] to determine the category, construction cost, resource upkeep, and production of this Building or District.
|- 
| '''triggered_desc = {'''
:'''trigger = <conditions>'''
:'''text = "localisation_key"'''
'''}'''
| colspan=2 | This property adds additional tooltips for this Building or District. Vanilla use this to add brief job descriptions summarizing total output if all jobs are filled. Multiple allowed.
* trigger: (Optional, default true) A block of [[Conditions]] to determine if this text should be in the tooltip. (Planet scope)
* text: A localisation key. Job descriptions are generally in the format "job_<job_key>_effect_desc", e.g. job_culture_worker_effect_desc.
|-
| '''on_queued = { <effects> }'''
| A block of [[Effects]] to be executed when the Building is added to the construction queue. Does not apply if added to the construction queue as an upgrade. (Planet scope)
| rowspan=4 | It's unclear if Districts support these features.
|- 
| '''on_unqueued = { <effects> }'''
| A block of [[Effects]] to be executed when the Building is removed from the construction queue. Does not apply if added to the construction queue as an upgrade. (Planet scope)
|- 
| '''on_built = { <effects> }'''
| A block of [[Effects]] to be executed when the Building is built. (Planet scope)
|- 
| '''on_destroy = { <effects> }'''
| A block of [[Effects]] to be executed when the Building is desroyed or demolished. (Planet scope)
|- 
| {{Collapse list | type= '''ai_weight = {'''
| body=
:'''<factor/weight> = <int>'''
:'''modifier = {'''
::'''<factor/weight> = <float>'''
::'''<conditions>'''
:'''}'''
'''}'''
}}
| colspan=2 | Rules for how likely the AI is to construct this Building or District. Multiple modifiers allowed. Note: As of 2.6, these weights [https://forum.paradoxplaza.com/forum/index.php?threads/stellaris-dev-diary-172-reworking-the-ai.1348837/#post-26324770| only come into play when the AI has no other economic plans]. Only used by Branch Office Buildings in vanilla.
|- 
| {{Collapse list | type= '''ai_resource_production = {'''
| body=
:'''<resource_key> = <int>'''
:'''trigger = { <conditions> }'''
'''}'''
}}
| colspan=2 | Determines what kind of resources the AI should view this Building or District being able to produce. Multiple allowed.
|}

Vanilla Buildings and Districts do not usually produce resources themselves. They provide [[Jobs]]. See [[Pop_Job_modding#Jobs|Pop Job modding]] for details.

== Generated Modifiers ==
The following modifier will be generated for a capped-by-modifier Building / District to be used.
* '''<building / district key>_max_add = <int>''' - Increases the max number of Buildings / Districts of this kind on a planet.

== Examples ==
==== Cost, Upkeep, and Production ====
Buildings usually have a cost and build time for construction, and often have an upkeep that must be paid. The below definition says that "building_sample" is a planet building that requires 100 minerals and 100 energy to build, would take 240 game days to complete, and after that has an upkeep of 2 energy a game month. After its construction it provides 2 minerals and 4 food per month. Other things that can be used include alloys, consumer goods, influence, minor artifacts, research, strategic resources, and unity. Unlike some modifiers, these must be flat values rather than production multipliers.

<pre>
building_sample = { 
    base_buildtime = 240

    resources = {
        category = planet_buildings
        cost = {
            minerals = 100
            energy = 100
        }
        upkeep = {
            energy = 2
        }
        produces = {
            food = 4
            minerals = 2
        }
    }
}
</pre>
==== Conditional Upkeep and Production ====
Production and upkeep brackets also allow for a [[Conditions|triggered condition]] block that will unlock them when the planet has met a specific condition. Each triggered production or upkeep will replace the current production or upkeep values for each resource declared. If there is a production or upkeep value previously established (like a base upkeep), these values will not be altered unless the upkeep/production resource is declared in the triggered block. It should be noted that good practice is to establish a base upkeep first with no triggers.

<pre>
building_sample = { 
    base_buildtime = 240

    resources = {
        category = planet_buildings
        cost = {
            minerals = 100
            energy = 100
        }
        upkeep = {
            energy = 2
        }

        upkeep = {
            trigger = {
                num_districts = {
                    type = district_farming
                    value >= 2
                }
            }
            # The new total building upkeep must be updated with each trigger. This overwrites the energy upkeep
            energy = 4
            # This is not part of base upkeep, and will be tacked on
            minerals = 1
        }

        produces = {
            food = 4
            minerals = 2
        }
        
        produces = {
            trigger = {
                num_districts = {
                    type = district_farming
                    value >= 2
                }
            }
            food = 8
        }
    }
}
</pre>

==== Resources Production via Jobs ====
Most buildings don't directly provide resources, but instead increase the number of planetary jobs. This can be done unconditionally using the ''planet_modifier'' element. However, since jobs often differ by country type (normal, hive minds, machine, etc.), so ''triggered_planet_modifier'' should be used instead. The modifier is applied to the planet only if the trigger defined in the ''potential'' element returns true. Each ''triggered_planet_modifier'' will be checked; a ''break'' statement cannot be used to prevent later checks. The below sample adds two farmer jobs depending on whether the owner country is a hive mind or not.

<pre>
building_sample = { 
    base_buildtime = 240

    resources = {
        category = planet_buildings
        cost = {
            minerals = 100
            energy = 100
        }
        upkeep = {
            energy = 2
        }
    }

    triggered_planet_modifier = {
        potential = {
            exists = owner
            owner = { is_regular_empire = yes }
        }
        modifier = {
            job_farmer_add = 2
        }
    }

    triggered_planet_modifier = {
        potential = {
	    exists = owner
            owner = { is_gestalt = yes }
        }
        modifier = {
            job_agri_drone_add = 2
        }
    }
}
</pre>

You can also use other modifiers to change the growth speed, ethics attraction and much more. See the [[Modifiers]] for more. If you want to apply a country-wide modifier, use ''country_modifier'' or ''triggered_country_modifier'' instead.

==== Upgrades ====
Many buildings can be upgraded to an improved version of itself. To support this you must create one or more additional build definitions. Typically, you would duplicate the first building and simply change the id by 2 or higher number. Also you might want to hide the upgraded building appearing as seperate building in the building list by setting can_build = no. Once the second building has been created and all necessary improvements made, return to the first building and add an ''upgrades'' element. Inside the bracket, you would add the name of the second building which the first building will upgrade to. The build time and resource cost of the second building become the time and cost to upgrade to that building. The below example adds a new building with an improvement to jobs produced and small increase to upkeep. The original building is given an ''update'' element and renamed for consistency.

<pre>
building_sample_1 = { 
    base_buildtime = 240

    resources = {
        category = planet_buildings
        cost = {
            minerals = 100
            energy = 100
        }
        upkeep = {
            energy = 2
        }
    }

    upgrades = {
        building_sample_2
    }

    triggered_planet_modifier = {
        potential = {
            exists = owner
            owner = { is_regular_empire = yes }
        }
        modifier = {
            job_farmer_add = 2
        }
    }

    triggered_planet_modifier = {
        potential = {
	    exists = owner
            owner = { is_gestalt = yes }
        }
        modifier = {
            job_agri_drone_add = 2
        }
    }
}

building_sample_2 = { 
    base_buildtime = 240

    can_build = no	

    resources = {
        category = planet_buildings
        cost = {
            minerals = 100
            energy = 100
        }
        upkeep = {
            energy = 3
        }
    }

    triggered_planet_modifier = {
        potential = {
            exists = owner
            owner = { is_regular_empire = yes }
        }
        modifier = {
            job_farmer_add = 3
        }
    }

    triggered_planet_modifier = {
        potential = {
	    exists = owner
            owner = { is_gestalt = yes }
        }
        modifier = {
            job_agri_drone_add = 3
        }
    }
}
</pre>

Though not used in vanilla Stellaris, a building can have multiple upgrade routes. Clicking the yellow upgrade icon on the building opens the upgrade panel where the defined upgraded buildings are listed. Note as well that upgradable buildings should not have the base_cap_amount set. This should only be set on the first upgrable building, and will be carried over.

{{ModdingNavbox}}
[[Category:模组制作]]