First, here is the link to the default/built-in building generator data file. Also, note that customizing the building generation is a pro version feature.

You can edit this file with an xml editor, but a plain text editor will work as long as you are strict about closing quotes and tags and avoid quotes and other xml special characters.  (You may want to do a web search for an article on editing XML.)

With that out of the way, we’ll walk through the file.  It will help to have the linked file open in another window or tab. “<datgen>” is a top level wrapper node.

The first child node in our default file is “buildings” and it has a number of “building” child nodes:

<building type="Academy" sv="15000" size="100" onroad="true" isfarm="false" 
   placement="any" distance="12" densepack="false" />

Each building node has the following properties:

1. type: The key name of the building in the system.  This will match the key name of the building in the other mapitems file.
2. sv: Is short for support value.  How may people need to be in the city to support one building of this type.  For example, if the city has a population to 10000 and sv is 2000, there will be 5 buildings of that type.
3. size: Should the building size be proportionally larger than the default size of the graphic.  The built in graphics are sized so a house is about 250×250 pixels.  That would roughly mean that 10 pixels = 1 foot.  But for larger buildings like the castles we don’t use the same scale (the file sizes would be too high) so those are about half that scale. Which means we set the size to 200.
4. onroad: true or false.  Does this building need to be placed along the road?  If you want a building type where some are on the road and some aren’t, simply make two entries.
5. isfarm: true or false.  This no longer has a specific effect in the system as onroad serves the same purpose.  However, it would help to mark it properly in case a related feature is added.
6. placement: “any” “away” or “near”.  Tells the system if this building type need to be near or away from the city center or does it not matter.
7. distance: a number.  If placement is “near” then how many hexes from the city center should the buildings stay within?  Or if placement is “away” then how close can the closest buildings of that type be to the center?
8. densepack: true or false. Should the buildings of this type be placed more closely to other buildings?

The next section is a parent node “races” with “race” child nodes. These represent the racial makeup of the city and each race node has culture subnodes:

<race name="human" chance="40">
     <culture name="english" chance="80"/>
     <culture name="spanish" chance="20"/>
</race>

The next section lists the possible names for males and females of each culture. The parent node is “person_names” and it has a set of “person_nameset” child nodes:

<person_nameset name="english_male" options="Ackerley, Adney, Aelfraed, ..."/>
<person_nameset name="english_female" options="Abellana, Aelfgifu, Aelflaed, ..."/>

You will need to have male and female entries for each culture you listed above.

After the person_names section are two nodes for backgrounds:

<adventurer_backgrounds options="Off-Duty Mercenary, Guardsman, Adventurer, ..." />
<occupations options="Town Watch Member, Private Guard, Farmer..."/>

Each is a simple list of the possible backgrounds for NPCs generated in many buildings.  If you want to have a higher chance some backgrounds will appear more often, simple list a given background extra times.

The next main tag is “special buildings” and it contains a list of which buildings have more detailed characteristics for the generator to create.

<special_buildings options="academy,alchemist,arena,armorer..."/>

The special buildings tag is follow by info for each of those special buildings.  Let’s look at one of the more complex ones in more detail:

<tavern_tabs>
<tavern_tab name="Staff" type="person">
<person type="Owner" mingroups="1" maxgroups="3" minpergroup="1" maxpergroup="1" chanceadventurer="5" />
...
</tavern_tab>
<tavern_tab name="Patrons" type="person">
<person type="Patron" mingroups="2" maxgroups="10" minpergroup="1" maxpergroup="10" chanceadventurer="10" />
</tavern_tab>
<tavern_tab name="Drink" type="item">
<item type="Brown Ale (lightly hopped, mild flavor, nutty taste)" min="1" max="5" unit="cp" availability="50" />
<item type="Pale Ale (malt dried w/coke)" min="1" max="5" unit="cp" availability="30" />
...

The top tag for the information for the building type will be <building key name>_tabs.  Then each tab that will be shown to the user when they click on it is a “tavern_tab” (singular.)  So in the snippet above we have Staff, Patrons, and Drink tabs.  (The Food tab was left out of the example.)  Each tab can have a type, “person” or “item”.  A person tab will have “person” sub-nodes.  For the person sub-node:

1. type: This value will be shown to the user in a column on the tab when the user click on that tab when viewing the building’s details.  It helps differentiate the owner from other workers in the store.
2. mingroups and maxgroups: How many groups of people of this type should there be. (See the next point for more explanation.) Each group of people generated will be either adventurers or normal occupations.  This helps to have 1 or 2 tables of adventurers in the tavern and 5 or 6 groups of normal people.
3. minpergroup and maxpergroup: How many people in each group would you like?  So to combine this information with mingroups and maxgroups, if mingroups were 2 and maxgroups were 4 and minpergroup was 1 and maxpergroup was 8, there could be between 2 and 32 people of that type.
4. chanceadventurer: From 0 to 100, how likely should each group be an set of adventurers?

Item nodes:

1. type: The name of the product for sale.
2. min and max and unit: The minimum and maximum prices and which unit to use.  (Usually cp, sp, gp for a fantasy game but they can be anything: dollars for modern games, credits for games set in the future, etc.
3. availability: From 0 to 100, how likely is each store of this type to have this item?
4. maxquantity: This isn’t shown in the tavern example above, but in stores where you may want to limit the number of a product available, set this to the most that can be available.  The generator will randomly set the quantity to between 1 and this number.

Finally, we have a section on generated store names.  Currently, this only covers inns and shops.  but if you wanted you could create a new node “tavern_names” (using the building key name) to create a new section for auto-generating tavern names.

<inn_names options="The MATERIAL ANIMAL, The COLOR ANIMAL, The EMOTION ANIMAL, ..."/>

The options value lists possible formulas for names where any word in all capital letters must match another tag ending in “_words”:

<animal_words options="Orc, Ogre, Troll, Bear, Dragon, Goblin, Owl, Wolf, Dog, Fish" />
<emotion_words options="Laughing, Yelling, Squinting, Smoking, Angry, Drunken, 
     Sleeping, Flying, Lost, Sad" />

So the system will randomly pick an inn formula when needed (perhaps “The EMOTION ANIMAL”) then it will randomly pick an animal and emotion such as: The Laughing Troll.

And that’s how it works.