A Guide To settlement_mechanics.xml

[Tsarsies]

A
GUIDE
TO

settlement_mechanics.xml

This file is one of the most important files for any modification. It controls the behaviour of settlements; how order takes effect, population growth, general income, even wages and upkeep among other things. The file itself is only about 6.40 kb in size and has a rather simple set up. The mathematics involved in understanding how it all falls together may be daunting at first, but i will try to keep it as simple as possible. What this file can do is quite amazing.

Throughout the file you find various pips and pip modifiers, which correspond to various factors. There are 3 types of factors;
SPF - Settlement Population Factor
SOF - Settlement Order Factor
SIF - Settlement Income Factor

Referring to Population Growth, the effects of Order, and the amount of Income generated.

These 3 Factor types, Population (growth), Order and Income. Each have a maximum value they can attain in game, Population Growth 12.5%, Order 500%, and Income unkown (or unlimited). For example, your population growth for any settlement can not exceed 12.5% per turn (nor can it fall below -12.5%), Order can not exceed 500% in game (You know that if order is below 100% there is a chance for riots and losing control of a city), I never found a limit to income as i assume its possible to be very high and possibly unlimited.

The most confusing part to understanding this file is the pip itself. Each factor draws a value from another file. More often then not this value is from the EDB (generally in the capabilities section of a building entry). Bonuses such as law_bonus, population_health_bonus, happiness_bonus etc. There are quite a few types of bonuses - Lets call all of them FUN bonuses. In addition, other values in the capabilities section of a building entry are also referred to by a pip, values such as farming_level, mine_resource etc. To properly understand the workings of the pip i highly suggest understanding the workings of the EDB.

This is where it may start to become confusing, so i will try to elaborate as much as i can and use examples where possible.

Each Factors PIP will be effected by the values in the EDB by the following percentages (per 1.0 as set in the factor itself);
SPF - 0.5%
SOF - 5% (for the most part)
SIF - 10% (for the most part)
For example. SPF_FARMS_BUILT with a pip value of 1.0 will give 0.5% increase in population growth to whatever value this factor is referring to - in this case, SPF_FARMS_BUILT refers to the farming_level capability from the EDB. Looking at the EDB you see each tier is set to one more then the previous tier, increasing population growth by 0.5% for each upgrade of that building. Increasing the value in the EDB will likewise increase this effect. This is a prime example of why knowledge of the EDB will greatly help in understanding this xml file.

The general set up for each factor is somthing like the following;

      <factor name="SOF_HEALTH">
     <pip_modifier value="1.0"/>
    <city_modifier value="1.0"/>
 
     <castle_modifier value="1.0"/>

    <pip_min value="0"/>
     <pip_max value="25"/>
  </factor>

PURPLE - This is the name of the pip, and generally gives a hint as to what value it refers to. Some factor names still elude me as to what they actually refer to which i will point out later.

RED - Is a global value, it will effect all settlements. (% of the pip itself) Note: You may be able to use negatives. I have not tested negative values though.

BLUE - Affects cities according to the Pip value (% of the pip modifier)

BLUE BOLD - Affects castles according to the Pip value (% of the pip modifier)

NOTE: It is not neccesary to use both castle and city modifiers. If you set the global value for cities you can simply adjust the castle modifier accordingly. With that said, you don't need to use either modifier and simply use the global value.
GREEN - Minimum value the pip value can attain (generally this will refer to the bonus it gives in the EDB; 1, 2, 3 etc)
GREEN BOLD - Maximum value the pip value can attain (generally this will refer to the bonus it gives in the EDB; 1, 2, 3 etc)
NOTE: The engine calculates and keeps track of all bonuses (FUN or BUILDING CAPABILITY). The maximum value for the pip is simply where you will no longer gain its benefits. As an example, say you have a number of buildings that grant happiness bonuses to your settlement. Every time you construct one of these buildings or upgrade it the happiness in the settlement will increase (dependant on the type of factor ofcourse), once these bonuses equal the pip_max value no additional bonuses will effect the settlement. The same can be said for pip_min value. This could be an interesting way to limit order from distance to capital, once a certain distance has been reached the negative order will not increase beyond the pip_max. In addition, the pip _min and _max are not needed for the file to function properly, they merely set limits.

Here is a list of all the Factors. Where possible i have added the value referred to.

Any factor with no statements are ones i have no idea what-so-ever about. Not even an educated guess.

POPULATION GROWTH

SPF_FARMING_LEVEL - Farming level as per regions.txt. 6 in the regions for base farming would be 3% bonus to population growth at 1.0.

SPF_FARMS_BUILT - The farming_level capability from the EDB

SPF_HEALTH - population_health_bonus from the EDB

SPF_BUILDINGS - any bonus given from EDB (1 per building)
SPF_TAX_RATE_BONUS - Only effects low tax rate in game. 1.0 gives 0.5% population growth when settlement has low taxes
SPF_BUILDINGS_FUN - happiness_bonus from the EDB
SPF_GOVERNORS_INFLUENCE - Grants 0.5% population bonus when set to 1.0 when the settlements Governer is present.
SPF_TRADE - This one may be difficult to grasp. 1.0 grants 0.5% populaiton growth per trade item (check your settlement trade) minus any trade item that region already owns and does not couple with duplicate imports/exports.
SPF_SQUALOUR - Squalor has a negative effect on population growth of -0.5% per 1.0. I am unsure where squalor is actually calculated so i dont know how to properly adjust this value. I assume setting the pip_max to 0 may actually eliminate squalor altogether. I believe squalor increases when no change has taken place in that settlement within a number of turns. I have no idea what that number of turns is though. I also believe squalor comes into play when a settlement reaches its max population.
SPF_PLAGUE - This is another value i am unsure of where it calculated. It also has a negative effect on growth of -0.5% population growth per 1.0.
SPF_TAX_RATE_PENALTY - population growth from higher taxes (opposite effect to Tax Rate bonus). Normal taxes grants no bonus or negatives to population growth. High taxes and Very High have a negative effect of -0.5% opulation growth each per 1.0.

ORDER

SOF_GARRISON - This factor sets the maximum order that a number of units can provide. In all my tests 5 units were sufficient to set order to 100% regardless of the pip_modifier value (1.0 or 0.1 or 4.0). I believe this factor simply grants a percantage to a single unit, 5 being order control of 100% in game. This seems to go against my findings of other SOF factors where 5% is per 1.0. Any additional research into this will be appreciated.

SOF_BUILDINGS_LAW - law_bonus in EDB

SOF_BUILDINGS_FUN - happines_bonus in EDB

SOF_GOVERNORS_INFLUENCE - Governors Title holder in settlement
SOF_TAX_BONUS - Only effects low taxes. (30% at 1.0 on low tax only!)... This is another one that seems to go against my general findings or 5% per 1.0.
SOF_TRIUMPH -
SOF_BOOM -
SOF_ENTERTAINED - Did not test this value, i believe it refers to any building giving a FUN bonus.
SOF_HEALTH - population_health_bonus from the EDB
SOF_FEAR - I believe this is related to a generals Fear rating. Its not called Fear, i know, i just can't think of it off the top of my head.
SOF_GLORY -
SOF_SQUALOUR - Comes into effect when the settlement experiences squalor. Once again i do not know where this value is calculated and am unable to test it.
SOF_DISTANCE_TO_CAPITAL - This one still eludes me. I believe (educated guess only) that it refers to the movement distance as set in the characters.txt file (for all pathfinding calculations). 1.0 refers to this distance. Therefore increasing the pip_modifier would increase order issues when a settlement is at that distance (or part thereof). Decreasing the pip_modifier will solve order problems.
SOF_NO_GOVERNANCE - No Governance only adds when NO unit is in a settlement 5.0 gve 75% (15 per 1.0)...
SOF_TAX_PENALTY - The penalty given on high, very high tax rates. (0.25 = 5%) 1.25 = 25%
SOF_TURMOIL - Not properly tested. You can give turmoil through the campaign_script. I suspect it will then change how turmoil effects order. Other things can also cause turmoil. But elude me at the moment.
SOF_BESIEGED - Not tested properly, obviously only comes into play when a settlement is besieged. Setting the pip_modifier to 0.0 will eliminate any order problems when besieged. Increasing it will cause more order issues.
SOF_BLOCKADED - Same as SOF_BESIEGED, except when a port is blockaded by an enemy fleet.
SOF_RELIGIOUS_UNREST - Lowering the pip_modifier will decrease order issues when a region experiences religious unrest. This is another value i have not tested, and therefore can't say what the exact value is that is being modified.
SOF_EXCOMMUNICATION - Same as religious unrest except for when a settlement belongs to an excommunicated faction. If this value is not balanced expect major issues in game from the pope.

INCOME

SIF_FARMS - harvest where 1.0 is 100% collected. From regions.txt

SIF_TAXES - taxes collected Approx. 33% per 1.0.

SIF_MINING - mining_resource capability in the EDB by 10% per 1.0 bonus.

SIF_TRADE - trade_base_income_bonus in the EDB by 100% per 1 bonus. So 0.5 would give 50% trade bonus
SIF_BUILDINGS - any bonus given from EDB (1 per building)
SIF_ADMIN - Alters the admin costs as found in your balance sheet.
SIF_WAGES - Alters wages as per the balance sheet
SIF_UPKEEP - increase/decrease upkeep costs
SIF_CORRUPTION - Not tested, but alters the corruption within your cities. Increasing the pip_modifier will increase corruption.
SIF_ENTERTAINMENT - Not tested, but i believe is is buildings that provide entertainment (FUN)
SIF_DEVASTATION -

As you can see, there are a few Factors i am not 100% sure on (there is a ridiculous amount of time needed to thoroughly test one factor) and some factors im totally at a loss for.

At the bottom of this file you will find the population levels. This dictates when a settlement can upgrade and what its maximum population can be for any given settlement upgrade.

<population_levels>
   <!-- city -->
   <level name="village" base="400" upgrade="1500" min="400" max="5999"/>
   <level name="town" base="1500" upgrade="6000" min="400" max="11999"/>
   <level name="large_town" base="6000" upgrade="12000" min="400" max="23999"/>
   <level name="city" base="12000" upgrade="24000" min="400" max="47999"/>
   <level name="large_city" base="24000" upgrade="48000" min="400" max="120000"/>
   <level name="huge_city" base="48000" min="400" max="240000"/>
   <!-- castle -->
   <level name="moot_and_bailey" base="400" upgrade="0" min="400" max="5999"/>
   <level name="wooden_castle" base="400" upgrade="6000" min="400" max="11999"/>
   <level name="castle" base="6000" upgrade="12000" min="400" max="23999"/>
   <level name="fortress" base="12000" upgrade="24000" min="400" max="47999"/>
   <level name="citadel" base="24000" upgrade="48000" min="400" max="80000"/>
</population_levels>

RED - Minimum population needed to be classed as this level of settlement. It should be equal to the previous levels upgrade value.
BLUE - Required population for this settlement size can be offered to upgrade to the next tier.
GREEN - Minimum population for this settlement size. Population levels will not decrease below this value.
PURPLE- Max population this settlement can hold. Settlement MUST upgrade to increase beyond this point.

I hope this thread is helpful to anyone wishing to modify this file. Any further suggestions to improve this guide is welcome. Feel free to PM regarding issues or questions.

[Augustus Lucifer]

Great guide Tsarsies, will get around to reading all of it tomorrow. Just missed this month's ES segment, but I'll make sure to include it in the next one.

[Azim]

+rep. I'd been looking for a tutorial on settlement mechanics for some time.

You might want to have a mod move this to the tutorials section.

[Nakharar]

great will get around to this

[Aradan]

Moved to Tutorials.



Good stuff there.

[SigniferOne]

+rep Tsasies! Excellent stuff.

[Gorrrrrn]

I put these here as guesses to be shot down or confirmed.

SOF Triumph - is it the boost given to order when you successfully complete a crusade and capture the target? (across all faction settlements)
SOF Boom - boom is for good harvests? (I notice there's no direct correlation between harvests and population)
SOF Glory - again guessing but related to benefit of having a successful crusader as govenor?

(these all seem familiar from RTW?)

SIF devastation - the damage done by besieging armies outside your walls to your economy?

[SigniferOne]

SOF Triumph - is it the boost given to order when you successfully complete a crusade and capture the target? (across all faction settlements)
SOF Boom - boom is for good harvests? (I notice there's no direct correlation between harvests and population)
SOF Glory - again guessing but related to benefit of having a successful crusader as govenor?

Almost certainly disabled.

SIF devastation - the damage done by besieging armies outside your walls to your economy?

Or possibly, the amount of money you the attacker get from it? (I hope it's your alternative though)

[Tsarsies]

I have seen BOOM appear on the settlements overview page, so it does exist and must be calculated somewhere. It could very well be based on a good harvest. I am not sure what determines a good harvest though and would it in turn affect the regions farming level for the turn? (maybe not turn, but for the whole cycle of seasons - Summer and Winter... In which case it would have greater value for 2tpy, 4tpy and 12tpy etc). Knowing that would be helpful. I would assume that 1.0 would increase order by 5% when a BOOM is experienced. I am not totaly sure why it would not affect population growth, as i would think a boom would. Being SOF it effects order. But the question remains, What does a good harvest actually do. Does it change the value of farming in descr_regions for that period?

I would guess that SIF_DEVESTATION would decrease tax revenues by 10% per 1.0. Meaning allowing an army to camp outside your walls is a bad thing. Not only do they block trade routes from and to the settlement, they also decrease the value of any other income you may be getting. Devestaion on the map is represented by those black scarring marks around the camped army. If this is the case, and its my best guess, then that should change how supply mods work, because if an army is unable to camp for the period of time needed to cause devestation, this factor will never be used and therefore not an issue for any mod. then the question arises, what file determines the length of time an army must camp to cause devestation?

[Gorrrrrn]

RE: Glory and Triumph.

I've seen major increases in public order after a successful crusade for that faction

Also having the crusading general does give a boost to order as well.

(HOWEVER - this MAY be because of other factors such as ancilliaries, traits etc.
Oh and being more popular with the Pope.)

Would the SOF/SIF/SPF show up in a trace?

Good harvest increases your farming income?
I can understand that a bad harvest might lead to a decrease in order - food riots etc.
Which might negatively impact population growth.

(The connection between good harvests and population might be indirect
- ie more money might allow lower taxes which would allow an increase in population?)

Devastation destroys the land available for agriculture, takes time to recover and lowers your income. As the land recovers so does your income.

(I really should spend more time analysing the settlement stats pages when playing - I usually ignore them unless there is something going horribly wrong.)

[konny]

then the question arises, what file determines the length of time an army must camp to cause devestation?

I have seen devestation ammounts defined in one of the mechanics files. I cannot remember which one, but this should not be difficult to be found (I can't now because I have M2TW on the other PC).

[SigniferOne]

I have seen devestation ammounts defined in one of the mechanics files. I cannot remember which one, but this should not be difficult to be found (I can't now because I have M2TW on the other PC).

Could you make sure to post it here when you get access to it?

[Gigantus]

It is in descr_campaign_db:

<misc>
<allow_resource_forts bool = "false"/><!--do we allow forts and watchtowers to be built on resource locations -->
<fort_devastation_distance uint = "20"/><!--maximum movement point extents for determining devastation tile targets for forts -->
<army_devastation_distance uint = "20"/><!--maximum movement point extents for determining devastation tile targets for field armies -->
<fort_devastation_modifier float = "1.0"/><!--num devastated tiles modifier for forts -->
<army_devastation_modifier float = "1.0"/><!--num devastated tiles modifier for field armies -->
<enable_hotseat_messages bool = "true"/><!--do we allow hotseat messages to be send between human players -->
<enable_unit_accent_overrides bool = "true"/><!--do we use unit db accent overrides for campaign unit selection -->
</misc>

[Tsarsies]

Excellent.

So the campaign_db xml file sets the distance that devestation will take affect based on whetehr its a fort or army. Then the SIF_DEVESTATION would simply increase/decrease the income gained/lost. Most likely by 10% per 1.0. There must be another file that sets the value of devestation (the base income lost), unless devestation is just considered 100% when in effect and therefore effects total income at +/-10%.

Whatever the case may be, Increasing the pip will increase the income loss while decreasing will lessen the income loss. It would be interesting to know if devestation also affects other modifiers, such as base farming level.

[SigniferOne]

What I also wonder about is whether the number of devastation tiles the army stack creates affect any variables here. What if it's 10% of tax income per tile, and you set <army_devastation_modifier float = "1.0"/> to 5.0?

[Gorrrrrn]

Did some testing last night on a SS6.2 RC4 with 1100AD mod campaign.
(I'll post the relevant sett-mech, descr-reg, edb files later with spreadsheet showing farming income over 25 turns for 5 settlements.)

Watched the 5 mainland English towns / castles settlement stats pages and recorded data.
Kept an eye on others for particular factors.

SOF-Boom - for some reason this sometimes greyed out suggesting that work in progress in settlement will give a boom when completed.

Otherwise, max I saw was 15% in London (1 turn), decreasing by 5% next for a few turns, then 5% then disappeared.
Other regions only had 10& or 5% SOF due to population boom.
Seems to last 8 turns.

Haven't worked out what triggers it though. seems random or possibly due to building something that gives boost to population.

SOF- Fear. Only had this once in Alexandria when I sacked it when conquering crusade target. Only lasted 1 turn immediately on sacking.
Don't remember seeing it other times I sacked somewhere when taking it.
Possibly due to religious difference between faction conquering and previous owners?

SOF - Triumph. This occurs when you capture a crusade target (presume also jihad but not tested that)
It applies to all settlements of faction. Starts at 30% for the turn the capture happens then declines by 5% per turn until it disappears.

SOF- Glory - not seen yet, name suggests something even more glorious than capture of crusade target.

SIF-Devastation. After calculating harvest income, % of it is deducted for devastation as per discussion above.
It seems only to happen by a having a stationary enemy army in region.
e.g. Caen had 1 rebel army outside for 1 turn and got devastation of 15% for about 8 turns, even after the rebel army was destroyed the turn after it appeared.
whereas Winchester had a rebel army roaming around for 4 turns without devastation before it stopped and then it kicked in.
I let this run for a couple of turns then destroyed the rebel army. Devastation remained at 15% for at least 8 turns.
(NB no sign of this on strat map.)

Devasation can be crippling if you get repeatedly besieged (as happened in Alexandria after I took it.)
You get multiple devastation areas in one region and the farm income can be cut by 60% or more.
I presume each area lasts for 8 turns for each stationary army.

SIF- Farming income - harvest appear sort of random and are different for each region each turn - although they start off the same.
You often a get a run of the same level of harvest for one settlement.
Suggets that the randomisation is based on previous turn level for each settlement.
They go from poor, average, good, excellent. (Didn't get a bad harvest.)
The increments are the same for level of harvest for a particular region but (and I'll need to check the maths again)
it seems some regions have 4%, some 5% and some 8% increments.
(will need to check to see what that relates to.)

For every farming upgrade you get a 0.5% population growth factor (irrespective of govenor or harvest.)
This is on top of the base level farming for that region as per descr-reg.

[Nakharar]

ive seen glory, basicly i was modding no settlements had anything all plain villages and the one which was capital and had faction ledaer next to it was had like 80% glory

[SigniferOne]

Rozanov, then what does this do?

<army_devastation_modifier float = "1.0"/><!--num devastated tiles modifier for field armies -->

[Gorrrrrn]

Sig1 - sorry I've no idea what that individual line does.

I'm doing an empirical test run to see what data I can find in game.

Herewith spreadsheet of farming income as promised with 5 settlements over 24 turns (incl start turn)
spreadsheet also includes the sett-mech file and descr-regions info for settlements listed all on one sheet.
farms in EDB merely give farming level increments, no other benefits.

Solved the harvest percentages: taking average as baseline, poor = -5%; good = +4.00%; excellent = +8.00%

Attachment 40930

[Gigantus]

<army_devastation_modifier float = "1.0"/><!--num devastated tiles modifier for field armies -->

Might have to do with the max radius of devastation.

SOF- Glory - not seen yet, name suggests something even more glorious than capture of crusade target.

Could be related to the triumph value (leftover from RTW?)