File Annotation Project

[Simetrical]

Quite simply, the annotation in most of the files is haphazard and inadequate. Everyone, I think, would benefit from improved annotation in all files, including hard-coded limits, possible variables, and the like. Even experienced modders will probably not realize many important discoveries. My ultimate goal is to have every major mod and community patch include this annotation for every file it modifies, thus efficiently propagating the information.

So, to start this project off, here're the beginnings of the export_descr_buildings.txt annotation:

;Maximum building trees: 64
;Maximum building levels per tree: 5
;Maximum hidden_resources: 63
;Capabilities list:
;	agent [agentname]  0 (function of 0 is uncertain)
;	armour [#] (upgrades armor by specified amount)
;	construction_cost_bonus_defensive [#] (reduces cost required for walls by how much?)
;	construction_cost_bonus_military [#] (reduces cost required for recruitment buildings? by how much?)
;	construction_cost_bonus_other [#] (reduces cost required for other buildings by how much?)
;	construction_cost_bonus_religious [#] (reduces cost required for temples by how much?)
;	construction_time_bonus_defensive [#] (reduces time required for walls? by how much?)
;	construction_time_bonus_military [#] (reduces time required for recruitment buildings? by how much?)
;	construction_time_bonus_other [#] (reduces time required for other buildings by how much?)
;	construction_time_bonus_religious [#] (reduces time required for temples by how much?)
;	farming_level [#] (each point increases farming level, somewhat complicatedly, see https://forums.totalwar.org/vb/showthread.php?t=44814)
;	fire_risk (probably nonfunctional)
;	gate_defences [#] (untested)
;	gate_strength [#] (untested)
;	happiness_bonus bonus [#] (each point is 5% happiness)
;	mine_resource [#] (how this translates into income is untested)
;	population_growth_bonus bonus [#] (each point is 0.5% growth)
;	population_health_bonus bonus [#] (each point is 5% order and 0.5% growth)
;	population_loyalty_bonus [#] (presumably one point is 5% order)
;	recruit "[dictionary name from EDU.txt]"  [starting XP]
;	recruits_morale_bonus [#] (new recruits get +# morale permanently)
;	recruits_exp_bonus [#] (new recruits start with +# XP)
;	road_level [#] (0 is basic roads, 1 is paved, 2 is highways)
;	stage_games [#] (existing values are 1, 2, and 3, difference untested)
;	stage_races [#] (presumably analogous to stage_games)
;	taxable_income_bonus [#] (increases tax income by 1% per point)
;	trade_base_income_bonus bonus [#] (each point is a 10% bonus)
;	trade_fleet [#] (grants specified number of trade fleets)
;	trade_level_bonus [#] (increases trade income by 1% per point)
;	tower_level [#] (untested)
;	upgrade_bodyguard 1 (untested)
;	wall_level [#] (untested)
;	weapon_bladed [#] (upgrades heavy weapons by specified amount)
;	weapon_missile [#] (upgrades missile weapons by specified amount)
;	weapon_other [#] (presumably upgrades other weapons by specified amount, untested)
;	weapon_siege [#] (presumably upgrades siege weapons by specified amount, untested)
;	weapon_simple [#] (upgrades light weapons by specified amount)
;
;All capabilities and building levels can use the "requires" line.  Logical connections like AND, OR, and NOT can be used, but they function a bit
;unpredictably.  Valid requirements are:
;	building_factions (function unknown)
;	building_present [level name] (untested, seems fairly self-explanatory)
;	building_present_min_level [tree name] [level name]
;	factions { x, y, . . . z, } (unlimited factions/cultures permitted)
;		x, y, z can be from the following list of cultures, or any of the sublists of factions:
;		roman (romans_senate + romans_julii + romans_brutii + romans_scipii)
;		greek (macedon + greek_cities + seleucid + thrace)
;		barbarian (britons + germans + dacia + gauls + scythia + spain)
;		ct_carthage (carthage + numidia)
;		egyptian (egypt)
;		parthia (parthia)
;		slave (possibly non-functional)
;	hidden_resource [resource name] (resources are given to provinces in descr_regions.txt)
;	resource [resource name] (amber, camels, copper, dogs, elephants, furs, incense, iron, glass, gold, grain (grants growth bonus), hides, lead,
;		marble, olive_oil, pigs, pottery, purple_dye, textiles, timber, silk, silver, slaves (special resource, appears when province is enslaved,
;		grants growth bonus), tin, wild_animals, wine

As you can see, there are quite a few gaps in the file. I don't know what benefits some capabilities grant, for instance. What does gate_defences do? Anything? I would test this myself, but I have my hands full right now doing traits, ancillaries, names, and buildings for RTR 6.0, so I could use anyone's help in expanding this annotation and in creating them for more files.

-Simetrical

[Rodion Romanovich]

gate_defences, hasn't that got to do with whether the wall level has reinforced gates or not?

[Yukon Cornelius]

My experience tinkering with building effects led to these conclusions:

Construction time bonuses (and presumably cost as well) are 1% per point. construction_time_bonus_defensive 50 will reduce the building time for defensive buildings (what counts as a defensive, religious, etc building?) by 50%. The game also "always rounds up," so to speak. A 90% decrease on a 4 turn building will result in the building still taking 1 turn to build. You'll notice the same thing occurs with the Halicarnassus wonder and its 20% construction time bonus. Anything that takes fewer than 5 turns to build is unaffected (4 turns - 20% = 3.2, which "rounds up" to 4).

Weapon and armour upgrade bonuses have a maximum of 3. No matter how many buildings add bonuses of whatever size, the end result is a bonus of 3. The unit recruitment screen says otherwise, but when you actually build the unit it'll only have a +3 bonus. Also, I think I read somewhere that you can put negative values but they'll only negate positive ones. For example, a weapon bonus of -1 will have no effect if no other building gives a bonus, but if another building gives a bonus it'll decrease that bonus by 1.

Note that the upgrade maximum also makes the Awesome and Pantheion level Artemis temples useless. They grant a +4 and +5 bonus respectively, but any unit you (re)train will only actually get +3.



I hope that helps a little bit. Feel free to test those effects yourself if you want to be absolutely certain.

[Epistolary Richard]

I'd agree it would be good to have more comprehensive (and accurate) narrative, but would it not be easier to compile into a modding manual which can be regularly updated than amend every single mod's files?

[Dol Guldur]

No,

The reinforcement level of gates is defined in gate_strength; gate_defences would refer to scorched sand/boiling oil which (I think) is 1 and 2 respectively.

tower_level seems to vary from 1 (arrow towers) to ballista towers (2) but one assumes watchtowers must be in their somewhere? I did not test forts - do they have watchtowers rather than arrows towers?

wall_level is

0 - palisade (ram hit = 8% damage)
1 - wooden_wall (ram hit = 4% damage)
2 - stone_wall (not rammable)
3 - large_stone_wall (not rammable)
4 - epic_stone_wall (not rammable)

gate_strength is

0 - wooden (ram hit = 10% damage)
1 - reinforced (6-7% damage)
2 - iron-bound (or Iron Gates?) (5% damage)

However, gate_strength 2 was only 4% damage with a ram when I had epic walls despite still having a value of 2.


I think there's more to it than my simple (and not thoroughly tested) examples above.

But back to annotation....yes, I think it's a great idea!

I've already worked on some values for the well-known export units file if you want them.