XML (Advanced) Guide to Adding Buildings and Wonders to Brave New World

XML (Advanced) Guide to Adding Buildings and Wonders to Brave New World
​

Support Issues Related to the Impending Release of Civ6:

1. Other than to clean up any small whoopses or typos that may exist in the information presented I have no intentions of adding to the information nor of making any great changes to format of how the info is presented
2. I am attempting to wind-down my Civ5 modding in preperation for the release of 6.
3. I am not abandoning the Civ5 modding forum, I am just winding down the stuff I have in the works and that I can reasonably expect to put to bed prior to the release of 6.
4. I intend to move on to 6 modding for the most part (or for the all part), assuming 6 is not a mess or a BE

----------------------------------------------------------------------------------------------------------------------------

I originally posted this as a Mod on the Steam Workshop. It can be found at Buildings Guide on the Steam Workshop. It is also now available here on CivFanatics at Forum Download of Buildings Guide. To give you an idea of the scope and nature of this guide I am including a link to a mediafire holdbox where you can look at and download the core document of my guide. The mediafire link is Buildings_Guide.xml. My intensions with this guide is to add all of the information in the core "Buildings_Guide.xml" file to this tutorial/reference. For now I do not intend to add any information that will be different from that provided in the download or steam versions of the guide, but I will be taking advantage of the much more powerful formatting capabilities of the forum as compared to a text-only file.

Notes on scope and purpose of the guide as it has been packaged in the download link and on my Steam Workshop mod

• Note that the downloadable versions of this tutorial are not as up-to-date so far as new added information is concerned as is the version here on the forum. I have been updating a 'master' version of the tutorial that in the near future I will re-publish to the downloadable versions, but I am also trying to keep the need for numerous small 'updates' to a minimum.

• I built the downloaded versions of the guide so that they could be posted to Steam, or here, and downloaded by potential users without having to worry about needing any program besides notepad to read them.

• I wanted the core part of the guide to be a reference that anyone could easily refer to while adding a new building or wonder to the game. I therefore wanted it to be able to "live on" a user's computer, quick to refer to.

• I wanted to make it at an accessible level to the new modder as well as to the experienced hand. When faced with "what was that darn command, again?", I wanted both sorts of modder to find the Guide a quick, easy, and useful reference.

This is my mod description as it appears on Steam. Except for the bits about downloading from steam, I think it might help give a better idea of how the downloaded version of the guide is intended to be used:



--------------------------------------------------------------------------------------------------------------------------------------------------------------------


Clicking the 'Navigation Links' in this Table of Contents will cause the post # indicated to appear as a pop-up window. Simply close the pop-up window to return to the table of contents.


Post 3 : Navigation Link: Introduction

Post 4 : Navigation Link: Miscellanea

Post 5 : Navigation Link: <GameData> Command

Post 6 : Navigation Link: <Buildings> Game Table Overview

Post 7 : Navigation Link: Opening the <Buildings> game table

Post 8 : Navigation Link: Start of Defining Your Building and XML-Name of Your Building

Post 9 : Navigation Link: Defining the Building Class Your Building Fits Into

Post 10 : Navigation Link: Building is free based on start eras

Post 11 : Navigation Link: Building Hammer Cost

Post 12 : Navigation Link: World congress building projects

Post 13 : Navigation Link: BUILDING GOLD MAINTENANCE COST PER TURN and REQUIRED TECH TO BUILD THE BUILDING

Post 14 : Navigation Link: Building is un-locked or purchasable with faith

Post 15 : Navigation Link: Building civilopedia and help-tip text-look-ups

Post 16 : Navigation Link: Building render art type

Post 17 : Navigation Link: Building is unavailable based on player start eras

Post 18 : Navigation Link: Specialists and great person points

Post 19 : Navigation Link: Specialist extra culture

Post 20 : Navigation Link: Min area size

For subsequent pages of the thread, clicking the 'Navigation Links' in this Table of Contents will cause the post # indicated to appear as a pop-up window. Simply close the pop-up window to return to this table of contents page.



Post 21 : Navigation Link: Walls, castle, arsenal, and military base defintions

Post 22 : Navigation Link: Building Capture probabilities on city conquest

Post 23 : Navigation Link: Specify a tech that enhances building yields

Post 24 : Navigation Link: "global" and "local" commands

Post 25 : Navigation Link: City tile-acquisition-cost modifiers

Post 26 : Navigation Link: Hurrying cost modifier

Post 27 : Navigation Link: Terrain requirements

Post 28 : Navigation Link: Caravan and cargo-ship trade routes

Post 29 : Navigation Link: MUTUALLY EXCLUSIVE GROUP, TOURISM MODIFIERS, and GREAT WORK SLOTS

Post 30 : Navigation Link: Espionage attributes

Post 31 : Navigation Link: Miscellaneous Commands To Allow World Wonder Special Capabilities

Post 32 : Navigation Link: FREE BUILDINGS and FREE PROMOTIONS

Post 33 : Navigation Link: CULTURE RATE MODIFIERS, HAPPINESS AND UNHAPPINESS, and GOLDEN AGES

Post 34 : Navigation Link: PRODUCTION MODIFIERS and GREAT PEOPLE ACQUISITION-RATE MODIFIERS

Post 35 : Navigation Link: WONDER BUILD REQUIREMENTS and SOCIAL POLICY COST COMMANDS

Post 36 : Navigation Link: National Wonder Commands

Post 37 : Navigation Link: Miscellaneous commands

Post 38 : Navigation Link: Game art changes with eras or cultures

Post 39 : Navigation Link: Art definitions for icons used in city screen, civilopedia, and tech tree displays

Post 40 : Navigation Link: Wonder splash screen

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx



Post 41 : Navigation Link: End of defining your building

Post 42 : Navigation Link: Building classes table

Post 43 : Navigation Link: Civilization building class overrides table

Post 44 : Navigation Link: Building PrereqBuildingClasses

Post 45 : Navigation Link: Building classes needed in city table

Post 46 : Navigation Link: Locked Building Classes Table

Post 47 : Navigation Link: Tech and prereqs table

Post 48 : Navigation Link: Modifier Tables

Post 49 : Navigation Link: Yield Changes Tables

Post 50 : Navigation Link: Terrain-Related Yield Changes Tables

Post 51 : Navigation Link: Resource Yield Changes and Resource Building Construction Requirements

Post 52 : Navigation Link: TECH ENHANCED YIELD CHANGES TABLE and FREE UNITS TABLE

Post 53 : Navigation Link: UNIT DOMAINS AND UNITCOMBAT TYPE tables

Post 54 : Navigation Link: Building flavors table

Post 55 : Navigation Link: Theming bonuses table (1)

Post 56 : Navigation Link: Theming Bonuses Table (2)

Post 57 : Navigation Link: Belief tables that affect, control, or reference buildings

Post 58 : Navigation Link: Policy tables that affect, control, or reference buildings

Post 59 : Navigation Link: Non-functional tables

Post 60 : Navigation Link: Guide for Changing Firaxis' XML (1)

xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx



Post 61 : Navigation Link: Guide for Changing Firaxis' XML (2)

Post 62 : Navigation Link: Guide for Changing Firaxis' XML (3)

Post 63 : Navigation Link: Guide for Changing Firaxis' XML (Game Errata)

Post 64 : Navigation Link: Adding audio to world wonders

Post 65 : Navigation Link: Using hidden buildings to create unique civ leader traits

Post 66 : Navigation Link: Building and Wonder Templates

Post 67 : Navigation Link: Files referenced in the Guide

Post 68 : Navigation Link: placeholder 1

Post 69 : Navigation Link: placeholder 2

Post 70 : Navigation Link: placeholder 3

Post 71 : Navigation Link: placeholder 4

Post 72 : Navigation Link: placeholder 5

Post 73 : Navigation Link: placeholder 6

1)If you have not already done so I highly recommend you download and read through Derek "Kael" Paxton's modding guide for Civilization V. It can be found at the following web address:



2) I also highly recommend you look through "ceej12's" guide to mod creation and uploading, located on Steam at:



3) If you are a member of the CivFanatics forum you can contact me at "LeeS" for help or advice.


4) On The Structure of This Tutorial, as it is downloaded either via the Steam Workshop or the CivFanatics download database:



Structure of the Guide as it is here and in the downloadable versions:

I have written the Guide as if everything shown within it is something new that will be added to the game by your mod. Therefore everything is shown as "<Row>" commands instead of "<Update>" commands. The "words" for the various commands shown is the same whether the "<Row>" or the "<Update>" command is used within a mod, but the "syntax" is a little different. I have kept to this convention of using "<Row>" even in the few cases where I am showing an example and in the specific case being discussed I would actually use an "<Update>" command if I were creating a mod I intended to use in the game.

Here is the way a series of commands might look when using the "<Row>" command:



In such a case I would be telling the game that my new building "BUILDING_GIANT_REFRIDGERATOR" will give 1 (one) Gold per turn.

If there were such a building as a "BUILDING_GIANT_REFRIDGERATOR" already in the game as supplied by FIRAXIS, I might want to make a simple mod that boosts its Gold output to "2" Gold per turn instead of only "1" Gold per turn. In such a case I would use the "<Update>" command to give this instruction, instead of the "<Row>" command:



NOTE: For more info and hints on altering existing buildings or wonders, refer to the file called "Changes_2_FIRAXIS.xml" located in the "Suppliments" folder.

"<ROW>" OR "<UPDATE>" GENERAL RULE OF THUMB

It is generally better to adopt the rule of thumb where anything new you add to the game should be presented using the "<Row>" format, and anything THAT ALREADY EXISTS within the game AS SUPPLIED BY FIRAXIS should be changed using the "<Update>" format.

BECAUSE I SUCK AT ARTWORK I will not attempt to discuss how to draw artwork, how to store it correctly in "art atlas files", or anything else directly-connected to the creation of artwork. I will only discuss how to make the game XML use artwork once it is made.

ALL IN CAPS
Many commands are shown ALL IN CAPS. This is the standard convention adopted by FIRAXIS. It is possible to show most commands that are normally shown ALL IN CAPS in smallcase, but this is not a good strategy to adopt. First, it is easier to read the XML-text of your mod when normally all-caps commands are shown in all caps. Second, many of the commands that reference pre-existing FIRAXIS-supplied XML must be presented exactly as supplied by FIRAXIS in order to get your mode to work correctly, and these referenced commands are almost exclusively presented ALL IN CAPS. You never can tell whether the command is hard-coded by the game to look for all caps, so why give yourself troubleshooting headaches ?

Other commands are shown in combinations of CAPS and smallcase. These commands should be presented EXACTLY as shown, as any deviations might be interpreted by the game software as invalid commands. Typos really do matter. In trouble-shooting why your mod does not seem to be working correctly, look for typos first.

FALL 2013 UPDATE PATCH

XML "COMMENT" COMMANDS

The following characters, in the order shown, signal the game that a human-readable comment is about to be inserted within the XML:




The following characters, in the order shown, signal the end of a human-readable comment inserted within the XML:



Anything that appears between these two character groups will be ignored by the game. The following are all considered human-readable comments by the game software:


(1) Short comment



(2) Multi-line comment that also disables an entire game table




(3) In this example the command for "<FreeStartEra>ERA_MEDIEVAL</FreeStartEra>" has been turned into a comment, and would have no effect on the game. Everything else would still be active.

......................................................................................................................................


I have tried to make this guide "all-inclusive". In doing so there may be segments of the guide that seem like information overkill, but I have included the "full value" of the information to make this guide a more useful reference document.

......................................................................................................................................


AUTHOR'S NOTES

You may encounter a few comments presented in the following format:


These are my notes to myself where I intend to add additional commentary, or to redraft, etc. I am not going to promise that I have deleted all such notes to myself back out of this file. The use of "[[" and "]]" denote a note to myself. A single use of these characters "[" and "]" denote the beginning and end of XML in-game-text formatting commands, but as none of those XML commands appear in this guide, I don't think anyone will really mistake the one for the other.

At the beginning of every XML file in your mod you must have the command "<GameData>" at the top of the XML commands you include in your mod. At the very end of every XML file in your mod you must have the command "</GameData>". I have not always shown these two commands in examples I have presented. Remember that you MUST have these commands in order for the game software to "read-in" your MOD's XML commands.


NOTE:

The "<Buildings>" table is the most complex of all the tables used to add buildings to the game primarily because it has so many attributes (or command-lines) that can be included within a single building. I will present a "line-by-line" explanation of everything that CAN be included in this table in an entry for a new building, but not every building SHOULD have an entry for every attribute (command-line).

Any attribute that doesn't really apply to a new building you are creating can be omitted. The structure of XML in CIV5 allows for this, and attributes that are left off a building definition are assumed by the game to have values of "NULL", or "false", or "0", depending on the individual attribute.

I will draw a clear distinction between that which is REQUIRED and that which is OPTIONAL by always specifically telling you when you MUST have a command or attribute included in your building definition.

START OF DEFINING BUILDINGS

You need to tell the XML that you are about to start adding information to the "<Buildings>" table. You must therefore always include this command:




It tells the game to open the <Buildings> table and enter new information under that table. The "new information" part will be the Building or Wonder you are adding to the game.

START OF DEFINING YOUR BUILDING

You need to tell the XML that you are about to start adding A NEW BUILDING to the "<Buildings>" table. You must therefore always include this command:




.....................................................................................................................................................................

NAME OF THE BUILDING

This is the name of the building used in the XML to identify the building. It should be stated ALL IN CAPS. It is not the same thing as the building name that shows up in-game in the city display of buildings built, buildings that can be added to the que, or buildings that can be purchased with gold or faith.

The name of the building SHOULD be made in the format "BUILDING_WHATEVERYOUWANTTOCALLIT" with the "BUILDING_" at the beginning of the building name. Here is a properly formatted command, telling the game that I am going to refer to my new building as "BUILDING_EXAMPLE":




You MUST have an entry for "<Type>".

BUILDING CLASS THE BUILDING IS PART OF

The building class allows for the replacement of a "generic" building that all players can build with a unique building that only one civ can build. Thus, for example, Barracks, Krepost, and Ikanda all belong to the "BUILDINGCLASS_BARRACKS" building class. Here is a properly formatted command, telling the game that I am going to place my new building that I just named "BUILDING_EXAMPLE", into the Barracks Class of Buildings:


You MUST tell the game what CLASS of building your new building belongs to. You can use an existing building class when this is appropriate, but many times you will be creating a whole new buildingclass for your building. To do this you simply make up a new name of buildingclass. When your new building fits within an existing Building-class you must still include the line for "<BuildingClass>" within your building definition, and you MUST state the name of the building-class exactly as FIRAXIS named it, CAPS and all.

The name of the buildingclass SHOULD be made in the format "BUILDINGCLASS_WHATEVERYOUWANTTOCALLIT" with the "BUILDINGCLASS_" at the beginning of the buildingclass name. Here, I have invented a new buildingclass that I have called "BUILDINGCLASS_EXAMPLE":





NOTE:

I must also "register" this new class of building, but as that is done under a different XML table than "<Buildings>" I will explain how to do that elsewhere in this guide. When you are adding a new unique building that fits within a pre-existing class of buildings, you do not need to "register" the CLASS of building with the game, as this has already been done.

Here are the top five lines of XML for my new building "BUILDING_EXAMPLE" showing what they would look like in actual executable code:

The building will be added for free to every city founded by the player when gameplay is started at this era or a later one. Obviously, ERA_ANCIENT is never included.

Wonders should not be assigned a "FreeStartEra"

This is the list you would pick from, shown in properly-formatted code:


Pick ONLY ONE for your building, or none at all. You can omit this command entirely.

The cost in hammers that shows up in-game will be modified somewhat from this number based on player difficulty level, starting era, and game speed. The hammer costs shown in the "<Buildings>" table are those that would apply to the PRINCE difficulty level, Ancient Era Start, and Standard game speed. You should not concern yourself too much with this game-mechanic. Just pick a hammers cost number that seems reasonable based on similar-building hammer costs and for buildings that become available at about the same place in the tech tree.

A building that replaces gardens should have approximately the same hammer cost as gardens. If such a replacement building for gardens has a much more powerful effect than the standard gardens, the hammers cost should probably reflect this greater capabilty. Alternatively, such a building could be given the same hammer cost as gardens, but be given a higher per-turn gold maintenance cost to compensate for its greater effects.

As shown in the following example, the production cost for the building would be 100 hammers:


A building that is only intended to be purchasable with faith uses a "-1" for the building "Cost", as in the following:


Cathedrals, Mosques, Pagodas, and Monasteries all use a "Cost" of "-1".

A building that is only intended to be constructed by the co-operative World Congress construction method also uses "-1" for the building "Cost".

You MUST have a "<Cost>" entry.

.....................................................................................................................................................................


To review the executable code that might be added to my building "definition" so far, if I choose "100" as my construction cost, and if I choose to have my building "free" starting in the MEDIEVAL era, my code would look like this:

Designates that the building can only be built by the co-operative efforts of multiple cities in multiple civilizations, and then only after a favorable World Congress vote. The International Space Station uses this designation. You will not normally include this in your building unless you are attempting to add a World Congress building-type construction project. In which case: "Thou art a better man than I, Gunga Din".

The code to make a building unlocked by the World Congress is:




(I will not be including "UnlockedByLeague" in the EXECUTABLE CODE REVIEWS)

You can omit the "<UnlockedByLeague>" command.

This sets how much a building costs in gold maintenance every turn. You can enter any whole number you want, but too high a number will only make your building a "game-breaker". Too low a number based on the power of your building effects will also tend to break game-balance.

You can set this to "0", but you shouldn't try putting a negative number here.

You can omit the line entirely, as the BUILDING_CARAVANSARY does, and as all national and world wonders do.

Here is a properly-formatted line to make a building cost 4 Gold per turn in maintenance:


You can omit the "<GoldMaintenance>" command, and for World and National Wonders you should generally omit a gold maintenance cost.

Setting Gold Maintenance to "0" (or omitting the column altogether) has the result of making the building unsellable.
.....................................................................................................................................................................



You can set this to any of the techs in the game, or you can make a new tech in your mod and then specify that your building requires this new tech. You can omit the line entirely, as the BUILDING_MONUMENT does. This makes the building available to build from the 1st turn.

Here is a properly-formatted line to make a building require the Mathematics technolgy before the building can be constructed:




You can omit the "<PrereqTech>" entry. When you do so, the building is available from the very start of the game.

.....................................................................................................................................................................



To review the executable code that might be added to my building "definition" so far, if I choose "1" gold per turn as my maintenance cost, and if I select "POTTERY" as the required tech to construct my building, my code would look like this:

[[not satisfied with this section]]
[[seems a little cluttered and confused]]


Pagodas, Mosques, Monasteries and Cathedrals are ONLY purchasable with faith, while Universities, Public School, Research Labs and the like can be built in the normal way, or purchased either with gold in the normal way, or purchased with faith if a player chooses the proper reformation belief.

Unlocked by a Follower, Founder, or Enhancer Belief:

If the building is to be buyable with faith you need to add both a <FaithCost> and the designator <UnlockedByBelief> when the building is only buyable if the player chooses a specific belief for their religion. You also generally will need to set the normal "Cost" to "-1". Setting <Cost>-1</Cost> is not absolutely required, but it is the way it is usually done.

If you want the building to be purchasable with faith after the player selects a belief for their religion, you will also have to create a new belief for the <Beliefs> XML, or you will have to edit an existing belief to allow that. An entry in the <Belief_BuildingClassFaithPurchase> table is required. Pantheon beliefs are not allowed by the game to have entries in the <Belief_BuildingClassFaithPurchase> table. Attempts to place the name of a Pantheon belief into the <Belief_BuildingClassFaithPurchase> table will be ignored by the game.

Unlocked by a Reformation Belief:

If you want the building to be purchasable with faith after the player selects a Reformation for their religion, you will also have to create a new Reformation belief for the <Beliefs> XML, or you will have to edit an existing Reformation belief to allow that. An entry in the <Belief_BuildingClassFaithPurchase> table is required. You will need to include both a <FaithCost> and the designator <UnlockedByBelief> here in the <Buildings> table.

<FaithCost> and <Cost> commands depend on the type of Belief:

• Buildings that are made purchasable with faith upon adopting a REFORMATION belief are also generally available in the "normal" ways, by building them or buying them with gold. For these buildings the "<FaithCost>" is additional to the regular "<Cost>".
• Buildings that are made purchasable with faith upon adopting a FOLLOWER, FOUNDER, or ENHANCER belief are generally ONLY made available to the player by buying them with faith. These types of buildings will have a "<FaithCost>", but will also, as mentioned in the notes on "<Cost>", usually have their regular "<Cost>" value set to "-1".

NOTE:

Regardless of which method you use to make your building available to buy with faith points, you do not specify which belief unlocks which building anywhere in the "Buildings" XML. That is done under the "Beliefs" segment of XML in the "<Belief_BuildingClassFaithPurchase>" table.

EXAMPLES:

Here are the properly-formatted lines to make a building purchasable with "200" faith points:


If I want my example building to ONLY be purchased with faith, instead of available in the regular way, I would have to alter the code for my example building as follows:



Notice that "Cost" is now set to "-1" to lock the player out of getting the building in the normal way. Notice that the "FreeStartEra", "GoldMaintenance" per turn, and the "PrereqTech" have been eliminated. There is no prerequisite technology because the faith system is the prerequisite for the building. The gold maintenance is gone to stay in line with the other buildings that are available only thru faith. The "FreeStartEra" is also gone because I want the building to be bought by faith, not given out for free when the player starts the game at the MEDIEVAL or later eras.

If I want my example building to be purchased with faith after selection of a particular REFORMATION belief, AND I want it to be available in the regular way, I would have to alter the code for my example building as follows:


Notice that the "GoldMaintenance" per turn, and the "PrereqTech" have been restored, and that "Cost" has been set back to "100". The building will be available thru the same mechanics as any other "non-faith" building, but with the difference that I can set a REFORMATION belief to allow the building to be buyable with faith points. The "FreeStartEra" is not restored in this example because this would make the building free in every city when a player begins play at the specified era, and this would likely conflict with the need during such a game for ever selecting the REFORMATION belief allowing purchase of the building with faith points. Depending on the era a player starts at, of course, religion may be entirely disabled, but in those games where it is not, were the building given free based on the start era, no one would ever want to select a Reformation belief to unlock buying the building with faith.

NOTE:

In case it was not obvious, when your building is not to be buyable with faith, you can (and should) omit the entries for "<FaithCost>" and "<UnlockedByBelief>".

[[still not satisfied with this section]]
[[seems a little cluttered and confused]]



Text look-ups are used by the game to define where the game should look to find the correct civilopedia and in-game tool-tip texts. The "where to look for it" part is determined by the name of the text "section" you define for <Help>, <Description>, <Civilopedia>, <Strategy>, <ThemingBonusHelp>, or <Quote>. Elsewhere in the XML of your mod, you tell the game what text to display for each of the look-ups you have defined.

<Help>

<Description>

<Civilopedia>

<Strategy>

<ThemingBonusHelp>

<Quote>
Direct Addition of Text Under the "<Buildings>" table:

You can add your text directly to the <Buildings> part of the XML and avoid needing to fool around with adding look-up references elsewhere, but this limits the usefulness of your mod by making it a one-language-only mod. In this case you also cannot specify the leading article for your in-game building name. If I wanted to do my tool tip helps this way for a building I want to call a "Flying School" I could do it by adding the following lines to my building:

In that example I would not include a <ThemingBonusHelp> or a <Quote> because they wouldn't apply to my Flying School. Keep in mind that this section of the <Buildings> table doesn't do anything inside the game except handle text displays. I would still have to add the appropriate commands later on to actually make my Flying School add the XPs mentioned above in <Help>.

WHY ALL THE FOL-DER-ALL WITH ALL THESE TEXT LOOKUPS ??

The reason you generally will want to use the text reference look-ups method to add your in-game tool tips and civilopedia helps is that the mod can later be expanded for speakers of languages other than english, or french, or whatever language you originally wrote your tool tips in. All it takes is for someone competent in a second language to translate your text helps into that second language, and adding a section for the second language to the help texts. The rest of the XML remains unchanged.

It is also a bit easier to read your <Buildings> table code should you have to trouble-shoot why your building isn't doing what you thought you told it to.

EXAMPLES USING "FLYING SCHOOL" AS MY BUILDING:

To help make this all a little more clear, take a look at the following example of the <Buildings> table for a building called "FLYING SCHOOL". I've included the same text as shown above for Help, Description, Civilopedia, and Strategy. There are a few entries in my "Flying School" building below "Strategy" that haven't been discussed as yet, but don't worry too much about those.


Now compare to what is directly below. Instead of entering the text I want the game to display in the civilopedia, etc., I've merely entered a "TXT_KEY_" look-up reference:


The game knows when it encounters one of these "TXT_KEY_" look-ups, it should first check which language the player is using, and then go get the text contained in that "TXT_KEY_" look-up for that language. All I as the builder of a mod would have to do is add a section to my XML somewhere that contains the actual text to be displayed in-game. Here is what I would have to include somewhere in my mod for the english language:


NOTE:

You can omit the entries for <Help>, <Civilopedia>, <Strategy>, <ThemingBonusHelp> and <Quote>. You need the entry for <Description> in order for the game to know what to call your building in-game.

NOTE:

Since in this example "TXT_KEY_BUILDING_FLYINGSCHOOL" is the tag for my building <Description> command I can add an additional line to it that controls the english-language grammatical article which will preceed the words "Flying School" when they are used in notification messages, and in certain other places in-game. I do this by including a command for "gender" as part of my text command for the <Description> of my building. Instead of just this:


I can state this, when I specify my in-game building name:


This has the effect of forcing the game to use "the" in front of "Flying School" when generating the text for in-game notifications, when mousing-over a city that is building a Flying School, etc. So, a player would see notifications such as:

"Chicage will build the Flying School in 3 turns"

This is not proper english grammar, so use of "the" in the gender command is not correct for the english language. My other possibilities are:


"Chicage will build an Flying School in 3 turns" isn't correct either, so <Gender>neuter:an</Gender> wouldn't be correct. Neither, really, would <Gender>neuter:no_article</Gender>, since that would result in notifications such as "Chicage will build Flying School in 3 turns".

If I omit the <Gender> command entirely, I will get notifications such as "Chicage will build a Flying School in 3 turns". This is the best grammatically correct preceeding article for "Flying School", so I'd be back at my original commands for the Flying School's description tag:


In case you feel I've just wasted your time, how about if my in-game building name were "Inn" ?


Would result in better in-game messages than


These are the three possible preceeding-article commands that can be used with <Description> tags:

preceeding article "a" is eliminated

preceeding article is forced from "a" to "an"

preceeding article is forced from "a" to "the"

Plurality: you can also specify "plurality" for your in-game building name when that is appropriate. For English, you would in nearly all such cases add the following command:


This command is telling the game that the in-game name for a building or wonder is already in the grammatically "plural" form.

Examples from Firaxis:


Here are a few examples from FIRAXIS-supplied buildings that use <Plurality> and/or <Gender>


.....................................................................................................................................................................



REGULAR BUILDING CIVILOPEDIA AND HELP TIP TEXT LOOK-UPS:

Regular buildings follow a slighly different format for their "TXT_KEY_" references from those used by wonders. Regular buildings usually have "TXT_KEY_BUILDING_" at the start of their look-up reference. Wonders tend to have "TXT_KEY_WONDER_" at the start of their look-up reference. It isn't strictly required to use "WONDER" instead of "BUILDING" in order to make your XML function properly. I've seen very skilled modders do it either way. The format conventions that FIRAXIS mostly followed for regular buildings is as shown below:



WONDER CIVILOPEDIA AND HELP TIP TEXT LOOK-UPS:

The format conventions that FIRAXIS mostly followed for world wonders is as shown below:


For the theming bonus help, I've used the "TXT_KEY_" reference from the Great Library. FIRAXIS didn't include "_WONDER_" in this reference, they just used the wonder's name directly.

The Following only applies when you are adding a "TXT_KEY_" to an existing Firaxis-Supplied World Wonder:

So far as I've been able to determine, I believe "<ArtDefineTag>" is used by the game to render 3D effects on or around cities based on what buildings have been built in a city. Some of these rendering "models" change as the player progresses thru successive eras. Others don't. Still others vary depending on the "cultural group" to which a CIV belongs. Determining whether or not to vary the 3D art with eras or cultures is specified later on in the "<Buildings>" table under the "<ArtInfoEraVariation>" or "<ArtInfoCulturalVariation>" lines.

Keep in mind that "<ArtDefineTag>" has absolutely nothing to do with the icon artwork that appears in the tech tree, the civilopedia, and inside the city-screen built-buildings display or producable-buildings displays.

You can only use the pre-existing "<ArtDefineTag>" names that appear in the XML supplied with the game. You cannot add new ones, at least, not directly thru XML coding in the "<Buildings>" table. Using an "<ArtDefineTag>" name that does not already exist in the game will not "break" your building or wonder mod, but it also will not actually accomplish much of anything.

When you add a new building, you need to decide what IF ANY art definition is required. Generally, you should only include an art definition for "regular" type buildings. You should NOT include one for a new World Wonder.*

If your building is a unique building for a CIV you should use the art define for whatever building it is similar to, or a replacement for. If your new building is a replacement for the standard barracks, you should use the ArtDefineTag for barracks. If your new building is a replacement for the standard colosseum, you should use the ArtDefineTag for colosseum, and you would need to add the "<ArtInfoCulturalVariation>" and "<DisplayPosition>" that appears in the standard BUILDING_COLOSSEUM building since colosseum rendering changes with the CIV's culture type. Using the "<ArtDefineTag>" from a similar building to your new building is safe because FIRAXIS themselves re-used the same "<ArtDefineTag>" for multiple different buildings.

HINT:

If you are adding a unique building to replace a standard building in the game, start by copying the entire definition of that standard building into your MODBUDDY "XML" file for your new building, and then edit only what is required to make your new building. In this case you would keep whatever "<ArtDefineTag>", "<ArtInfoCulturalVariation>", "<ArtInfoEraVariation>", "<ArtInfoRandomVariation>", or "<DisplayPosition>" is used in the standard building.

NOTE: Specifying an AtDefineTag is Optional

specifying an ArtDefineTag is not strictly required. In fact, if you are adding a world wonder to the game you should specify nothing for an ArtDefineTag, or you should specify "NONE". Specifying "nothing" in this sense means not even including a line for "<ArtDefineTag>" in your world wonder "building". This is O.K. since the game defaults to "NULL" when "<ArtDefineTag>" is omitted. You can also state "NONE" for ArtDefineTag with regular buildings, or you can omit the line entirely.

NOTE: Shared ArtDefineTags

Cathedrals, Mosques, and Pagodas all use the same "TEMPLE" ArtDefineTag. Power Plant buildings all use the same "ART_DEF_BUILDING_HYDRO_PLANT" ArtDefineTag. Don't be too terribly concerned with which tag you choose to use so long as it's reasonable for the building you are adding.


* NOTE: "Envoy", who is a far more skilled modder than I, used "ART_DEF_BUILDING_OXFORD_UNIVERSITY" from the national wonder Oxford University as the "<ArtDefineTag>" for his "Wonders - Universities of the Ivy League" mod. In his mod, he added 8 new world wonders, each representing a different "school" within the US "Ivy League". Even though he was adding new WORLD wonders, he did not use an "<ArtDefineTag>" from any of the FIRAXIS-supplied World Wonders.

http://steamcommunity.com/sharedfiles/filedetails/?id=160177360&searchtext= is the steam address of Envoy's mod. This was for the Gods & Kings version of the game. I believe Envoy has added a BNW version of the mod to the Steam Workshop, but I don't know the direct address for that.

..............................................................


NO ART TAG

To tell the game not to use anything for "ArtDefineTag", use the following:



This is probably best for beginning modders. By doing this you ensure that no oddball "Art"-y stuff will happen.

..............................................................



ARTDEFINETAG USAGES in FIRAXIS-supplied XML

The following "<ArtDefineTag>" tags are used with "regular" buildings. You can safely choose any one of these for use with your building. The list is shown EXACTLY as they appear within the "<ArtDefineTag>" command. Some of the tags are prefaced with "ART_DEF_BUILDING_", but many are not:





The format for the "<ArtDefineTag>" command using a couple of different examples from the list above:




..............................................................


ART DEFINE TAGS SHARED BY "REGULAR" BUILDINGS

The following "ArtDefineTags" are shared by multiple buildings in the FIRAXIS-supplied XML.



..............................................................

NATIONAL WONDERS "<ArtDefineTag>"

These are included to stay in line with the concept of "completeness" for this guide, but you would not normally pick any of these. You CAN, you just normally wouldn't.


..............................................................


GUILD "ArtDefineTags"

These are included to stay in line with the concept of "completeness" for this guide, but you should not normally pick any of these.


..............................................................

WORLD WONDERS and LEAGUE PROJECTS

These are included to stay in line with the concept of "completeness" for this guide, but you need to be very certain of what you are doing before you pick one of these, even when your building is a new world wonder.






I have experimented with using the standard World Wonder "<ArtDefineTag>", "<ArtInfoCulturalVariation>", "<ArtInfoEraVariation>", "<ArtInfoRandomVariation>", and "<DisplayPosition>" info in a custom World Wonder. I did this by creating a unique replacement for the Great Wall that only Rome could build. I used the same commands for these art rendering attributes as are used by the Great Wall. The game did not crash and burn, but it did have a little trouble rendering the Great Wall main-map artwork. In the three games I experimented with this, the game only rendered the Great Wall "wall" on the main map after the wonder was completed, and then only after I had saved and re-loaded my games.


NOTE IN CASE IT WAS NOT OBVIOUS:

You can omit the entry for "<ArtDefineTag>".

You can also omit the entries for "<ArtInfoCulturalVariation>", "<ArtInfoEraVariation>", "<ArtInfoRandomVariation>", and "<DisplayPosition>"; as a general rule you should omit these entries.

"<MaxStartEra>" disables buildings based on what era the player starts on. If a player decides to start a game in the INDUSTRIAL era, any building that has "<MaxStartEra>" for an era earlier than "INDUSTRIAL" would be unavailable for the duration of that game. This is used with both World Wonders and regular buildings. The Notre Dame world wonder as well as all Temple-class and Shrine-class buildings have a RENAISSANCE era "<MaxStartEra>", so any game started in the RENAISSANCE or EARLIER eras will include them, but any game started in the INDUSTRIAL era or later will not.

A building can have both a "<FreeStartEra>" and a "<MaxStartEra>".

You must pick ONLY ONE of the following as a "<MaxStartEra>", or none at all:


Here is the properly-formatted code to make a building unavailable when the player starts the game LATER THAN the MEDIEVAL ERA. If the player starts the game AT the MEDIEVAL ERA, the building will still be available:


You can omit the entry for "<MaxStartEra>".

.....................................................................................................................................................................





To review the executable code that might be added to my building "definition" so far, if I choose to use the "ArtDefineTag" of the TEMPLE, and that my building will have a "MaxStartEra" of ERA_MEDIEVAL, my code would look like this. It would mean that if I start the game in the Medieval era, the building is free, and can still be available to the player, but if I start later than ERA_MEDIEVAL the building will not show up in that game.

As a general note, from here I will making the new lines I am adding or altering in these code review show as bold red , to make it easier to see the changes or additions.


If I choose to use no "ArtDefineTag", and no "MaxStartEra" limitation, my code would look like this:


In this case I would simply not have an entry for "MaxStartEra". When you don't need or want a particular attribute assigned to your building, in most cases you can simply omit it altogether. Back in the bad old days of CIV4 XML (as well as I can remember), you still had to have an entry for everything, even if you weren't making an attribute active. It made for some difficult reading of XML to see where you had goofed if something wasn't working, or wasn't working the way you wanted it to.

"<SpecialistType>" is used to designate BOTH the type of citizen specialists the building can support as well as the type of great person points the building will add every turn to the generation of the next great person. You must pick ONLY ONE of the following TYPES of SPECIALISTS:




NUMBER OF SPECIALISTS

"<SpecialistCount>" tells the game how many specialist slots the building has. You should limit this to no more than 4, since the in-game city buildings display doesn't have room to properly show more than about that number.

WORLD WONDERS AND NATIONAL WONDERS

You CAN add citizen-specialist slots to Wonders. You should avoid having a Wonder contain BOTH citizen-specialist slots AND Great Works slots since the game does not know how to "display" such a building in the city buildings list -- it sometimes places them in sections of the list where you would not expect in the same sort of wierd way that National Wonders are usually displayed in the wonders section of the city display but depending on how the National Wonder is defined it can sometimes be displayed in the 'regular' buildings section where one would not usually expect to find it. You CANNOT have a World Wonder contain BOTH citizen-specialist slots AND the command for "<SpecialistExtraCulture>". I will explain why you cannot do this later on in the segment of this guide devoted to "<SpecialistExtraCulture>".




GREAT PERSON POINTS

"<GreatPeopleRateChange>" specifies the number of great person POINTS added each turn to the city's cumulative count for spawning a particular type of great person. You can put pretty much any number you want for your building, but remember that ridiculously high numbers won't do much more than break the balance of the game. Properly-formatted line to add 1 Great Person Point per turn;


......................................................


SPECIALISTS and GREAT PERSON POINTS examples


If I want my building to have two engineer specialist slots but no great person points I would add this to my building:


If I want my building to have two great-engineer great-person points per turn, but no citizen-specialists slots of any kind I would add this to my building:


You can specify both "<SpecialistCount>" and "<GreatPeopleRateChange>", but both will apply to the type Specialist you choose. And, as already mentioned, you can only choose one type of Specialist to apply to any one building. As example, the following would add two (2) MERCHANT citizen-specialist slots to a building, as well as adding one (1) point per turn towards the next spawn of a GREAT MERCHANT:


NOTE:

The great person points discussed affect only the count towards generation of great persons in the individual city where a building is constructed.


You can omit the commands for "<SpecialistType>", "<SpecialistCount>", and "<GreatPeopleRateChange>".

!! GAME BUG WARNING !! GAME BUG WARNING !! --> SPECIALIST EXTRA CULTURE

I CANNOT RECOMMEND USING THE FOLLOWING COMMAND SINCE TOO MANY CONDITIONS ASSOCIATED WITH INCLUDING IT CAUSE THE CULTURE AND SOCIAL POLICIES SYSTEMS TO "BREAK" MID-GAME

"<SpecialistExtraCulture>" adds EXTRA Culture to every specialist in the empire. Since this command has a global effect the command should only be used with national or world wonders. The format to make every specialist in the empire generate one (1) more Culture per turn than normal is:



STACKING:

"<SpecialistExtraCulture>" commands can NOT be "stacked" across multiple buildings, as attempts to do so result in the creation of mystery extra culture coming from "specialists", even in cities that have no buildings yet that contain specialist slots.

SPECIALIST EXTRA CULTURE combined with SPECIALIST COUNTS in THE SAME WONDER:

A serious bug exists in the game whereby a wonder (or regular building) that has the "<SpecialistExtraCulture>" attribute AND ALSO HAS citizen-specialist slots will cause the game to begin generating odd amounts of "mystery specialist culture" in EVERY CITY of the player that constructs such a wonder. The bug also manifests itself if more than one wonder or regular building containing a "<SpecialistExtraCulture>" command is constructed in the same empire. I have seen two or more World Wonder buildings that contain the "<SpecialistExtraCulture>" command causing the game to create as much as +25 per turn "mystery" culture added to city yields IN EVERY CITY IN THE EMPIRE, even where individual cities have not constructed a building yet that has any specialist slots. The mystery culture generated is shown in the city yields box as coming from "specialists".

I use the term "wonder" since most buildings that would have the specialist extra culture command would tend to be national or world wonders, but in fact ANY building that has BOTH specialist extra culture stated and has citizen-specialist slots will cause this odd bug to manifest, and ANY building-type that has the "<SpecialistExtraCulture>" command will cause the bug to manifest once the 2nd city builds such a "regular" building.

I've played around with this command, created all the conditions noted, and found the way the game treats this command to be seriously erratic. JUST --- DON'T !!!

1. Specifies for buildings that must be in cities located adjacent to lakes or oceans the minimum number of water tiles that must exist in the lake or sea. "-1" means there are no restrictions. So,
   Code:

   <MinAreaSize>-1</MinAreaSize>

   tells the game that no additional restrictions are in effect beyond whether or not the city must be located on a coast, or adjacent to a lake or other "freshwater" source.
2. For coastal buildings, you should set <MinAreaSize> to "10" because "10" is one tile larger than the largest size a lake can be. Any "lake" larger than 9 tiles is considered by the game not to be a lake, but rather a small sea.
3. For buildings that need to be located next to a lake, you should set this value to "1".
4. All other buildings should use "-1".

USAGE BY FIRAXIS:

1. Floating Gardens uses:
   Code:

   <FreshWater>true</FreshWater>
   <MinAreaSize>1</MinAreaSize>

   to ensure that if the city is next to a lake, the lake has at least one water tile. <FreshWater>true</FreshWater> requires the city be next to a lake, oasis, or river.
2. Lighthouse uses:
   Code:

   <Water>true</Water>
   <MinAreaSize>10</MinAreaSize>

   to ensure that the city must be both coastal (<Water>true</Water>) and that the body of water the city is adjacent to contains at least 10 water tiles. This same method is used by all other buildings and all World Wonders that must be built in coastal cities:
   • Harbors
   • Seaports
   • Great Lighthouse
   • Colossus
   • Sydney Opera House