Update AIC Description Text

[Heroesflorian]

Added the current version of the aic description text as a markdown file.

The file can already be viewed; however it is not final yet and contains a number of TODOs.
Feel free to suggest all sorts of improvements (preferably via review comments).

[Krarilotus]

Your english descriptions are on point! I love the grammer, the style and the cleanlyness and easiness to understand the parameters through this work of art! well done! But:

I guess this has been in the making for too long and information got out of date...
Things that are just plainly wrong are in there too :/ I Guess it needs a lot of work still to be viable as a descriptive text!

Things i noticed that could need improving:

• same as setting the max amount parameter to 0 would do. - simply doesn't do it. If set to 0, it will still build one with appropriate population settings. Also some of the buildings are build twice after the first threshhold population is reached, such as stone quarries. So if you set: population per quarry to 12 for example, and max quarries to 4, it will build 2 quarries at 12 population, the third on 24 and the last on 36 population.

• Resource Rebuild Delay might actually be a check how often the AI checks for newly available farm spaces etc. Needs further investigation, but it isn't consistant as of 'how long it waits^^'

• only affects the build steps set up in AIV files, but does not affect placement of resource buildings. - thats wrong. This parameter also affects the placement speed for resource buildings, which are placed in parallel

• The AI will only use the recruitment behavior (see below) defined by the relevant AIC values after its AIV build steps have been completed (or skipped due to a lack of resources); before that, no attack troops will be recruited. Thus, the value of the BuildInterval parameter will impact how soon the AI is able to start recruiting attack troops.
  -> this is wrong (just recently), as NP found out the behavioural switch is tied to matchtime. As soon as matchtime of 4000 ticks (thats 1 minute and 20 seconds on gamespeed 50) is passed, the recruitment behaviour will go into the default. Attacktroops however can be recruited prior to that, if the AI's defence maximum is reached, as defence recruitment probability is then converted into attack recruitment probability.

• under Resource management: Also consider the amount a worker with the usual fearfactor would bring in one go to the stockpile, to be left as headroom, as otherwise resources might be lost/destroyed

• ally interactions seems to be in the perfect spot for the flow. It could however be its own section! Also added could be the value that is responsible for the frequency of AI questions for resources.

• i like the idea of naming it pressure. How the 'Strong, Normal, Weak' states work, is also something we could put in. The appropriate file for the functions that control that behaviour is put up by NP in the discord somewhere, i might dig it up and post a function in here later when we get to it. Fear/pressure tates might be also depending on similar mechanics, but one is for sure: How many strength points of hostage enemies are within the same area as the lord, while a path exists to the lord. Specially knights and swordsmen flip the charts there! (Probably divided by some own numbers within that range?)

• flour and beer are not bought. Beer i am 100% certain of, flour pretty sure. I have had countless scenarios where the AI was not having a mill but many bakeries and couldnt run any of them as it lacks the ability to buy flour. Same for inns. Unless proven otherwise, i would delete those from the 'buying resources' list! But this can be easily tested: Start an AI with 8k gold and give it just some bakers and inns, it will not buy those. But i am happy to be proven wrong!

• Moreover, the AI's recruitment behavior differs while it is still setting up its castle, being more defensive overall and not recruiting attack troops. -> as mentioned above, it can very well recruit attack troops there, but not raiding troops. Attacktroops however would need the AI to have maxed out the defence troops and the actual switch for behavour is at matchtime = 4000.

• NOTE: While it is possible to set recruiting probability values for a power state to not add up to 100, in that case the resulting behavior ingame may happen to not match the provided values. -> actually these values dont need to be percentages at all, and if not set to percentages, it is just a rleative value to the sum of all 3 values. So say you set 1,2,3 in there, then the first value corresponds to 1/6th the second to 1/3rd and the third one to 1/2.
  -> also note: the recruit gold threshhold triggers the buy of units for a short period of time, which will continue for that period of time, or until the gold is depleted. So it doesn't check for thesecond unit to be recruited, if it is still above the recruit gold threshhold. Might be worth noting ^^

• SortieUnitMelee will run into the attacking enemies -> also shooting on the way there, if line of sight allows for it and the unit is ranged. SortieUnitMelee also will move back to the keep, as soon as their target enemy is dead, while sortieunit ranged will stay in the field at the spot, that the last worker has died at, until another worker has died at another spot on the map (really dumb behaviour btw^^)

• also note: slingers are very good at sortie unit melee, crossbowmen suck at sortie unit ranged. And also important:
  -> Sortie Unit ranged get recruited more than their specified number, if the AI feels 'strong' (triggers hasn't been identified explicitly yet, but happens mostly in longer games and with more build up AI's) This can exceed the initial amount by even 25 or 30 units at times.

• is it called defense or defence btw? I never knew what was wrong/right there

• The overrecruiting only happens in cases that the AI has a lot of gold.
  TODO: clarify that hint text!
  -> this happens mostly with weaker AI's that detect danger nearby. So Sultan for example with a lot of gold, recruits and extraordinary amount of more units than specified in DefenseUnitsMax or however its called

• regarding defDiggingUnits: if allies have moats, it might recruit them? I don't know! needs testing!

• DefSiegeEngineBuildDelay is likely also just a regular check by gameticks passed...

• TODO: still true if keeps were moved in the AIV? Yes still true. This means, if the keep is moved, the attack distance is also changed :D

• regarding 'balanced' target choice, do we have exact info on how the distance matters? It might be brought up in an issue somewhere, maybe someone dug up the code?

• TODO: btw what happens if RaidUnitsRandom is set to a negative value in the AIC? will the AI behave as one would expect based on the regular formulas for all those circumstances?
  -> actually i think this is true, tho i have not tested it enough. Also the equation doesn't match all the time, as sometimes the AI just attacks with less than the units it should recruit for the attack, and sometimes it attacks with all only after the maximum has been reached. Its wierd, and should be inspected. Especially if more than one field of the RaidUnitTypes is populated!

• the AI might attack before gathering its full attack force, to a minimum of the AttForceRallyPercentage from the full attack force. -> actually might not be affected by this percentage value, must be inspected again. But i think i tested this in the pastand that was my conclusion. I would tho prefer if someone counterchecks this!

• gathering in some place closer to the target enemy’s castle walls
  -> might not be the case, it can also move further away if the castle is withhin short distance. The attacking gathering spot is based on the attack path to enclosed structures or army spots of the enemy. Sometimes this works well, sometimes it bugs out, as moat lengthens the attack path to the building, leading to the AI think it would need to walk further, as in walking around the moat, thus setting up right in front of the enemy castle. It can also happen that the AI doesn't detect the enemy main defence right, and misses out on a frontal tower, manned with lots of troops, as these are counted as 'sorte/field' defence troops.

• siege tends -> tents*

• However, how exactly this composition works and how the proportions of each attacking unit that can be defined are truly set, hasn’t yet been discovered.
  -> i got an update onthat: The predefined roles will be all recruited if available to their maximum amount, while also the total of attack units main will be only recruited up to the AttackMaxDefault (or however this is called) thing right after them. If troops can't be recruited due to limitations, the recruitment interval will be skipped and the next troop will be recruited. This process is repeated until attackforce base is reached, where missing slots, because of unavailable units, or because of otherwise maxed out unit slots, will be filled up with attackUnitMain units.

• As soon as a free path is opened towards the enemy keep, every unit that can move up on the keep will be rallied onto the keep automatically. Horse archers and knights can not climb the keep, which leads to them hanging around the keep in aggressive stance.
  -> is especially bad for the AI, as it is incapable of targetting down economic strctures, which would usually increase the harm done by its troops!

• (regarding attacking differs) and will only be recruited if the enemy has a moat to dig through -> will also be recruited, if the enemy has just setup a moat, but doesn't actually have a moat dug out.

• regarding laddermen: from the walls to the keep, -> to the AI's own keep. The other way is not fixed at all!
  -> so the AI needs to see a path from its own keep to the walls + a path from the walls down into the keep area of the enemy
  -> with the bugfix the first requirement can be dropped

I hope this helps, and i hope to see an updated description text soon @Heroesflorian

[Krarilotus]

i just saw an AI buy 2 flour, when it had no workers for its mill and it had 8 bakeries, for which it had only 2 running, as the other 6 were also out of workers. Lol...

[Heroesflorian]

Implemented some feedback now; remaining points that are not resolved or marked by todos in the text itself yet are listed below (reference for future me):

i like the idea of naming it pressure. How the 'Strong, Normal, Weak' states work, is also something we could put in. The appropriate file for the functions that control that behaviour is put up by NP in the discord somewhere, i might dig it up and post a function in here later when we get to it. Fear/pressure states might be also depending on similar mechanics, but one is for sure: How many strength points of hostile enemies are within the same area as the lord, while a path exists to the lord. Specially knights and swordsmen flip the charts there! (Probably divided by some own numbers within that range?)

The overrecruiting only happens in cases that the AI has a lot of gold.
TODO: clarify that hint text!
-> this happens mostly with weaker AI's that detect danger nearby. So Sultan for example with a lot of gold, recruits an extraordinary amount of more units than specified in DefenseUnitsMax or however its called

DefSiegeEngineBuildDelay is likely also just a regular check by gameticks passed...

regarding 'balanced' target choice, do we have exact info on how the distance matters? It might be brought up in an issue somewhere, maybe someone dug up the code?

TODO: btw what happens if RaidUnitsRandom is set to a negative value in the AIC? will the AI behave as one would expect based on the regular formulas for all those circumstances?
-> actually i think this is true, tho i have not tested it enough. Also the equation doesn't match all the time, as sometimes the AI just attacks with less than the units it should recruit for the attack, and sometimes it attacks with all only after the maximum has been reached. Its wierd, and should be inspected. Especially if more than one field of the RaidUnitTypes is populated!

the AI might attack before gathering its full attack force, to a minimum of the AttForceRallyPercentage from the full attack force. -> actually might not be affected by this percentage value, must be inspected again. But i think i tested this in the pastand that was my conclusion. I would tho prefer if someone counterchecks this!

gathering in some place closer to the target enemy’s castle walls
-> might not be the case, it can also move further away if the castle is withhin short distance. The attacking gathering spot is based on the attack path to enclosed structures or army spots of the enemy. Sometimes this works well, sometimes it bugs out, as moat lengthens the attack path to the building, leading to the AI think it would need to walk further, as in walking around the moat, thus setting up right in front of the enemy castle. It can also happen that the AI doesn't detect the enemy main defence right, and misses out on a frontal tower, manned with lots of troops, as these are counted as 'sorte/field' defence troops.

However, how exactly this composition works and how the proportions of each attacking unit that can be defined are truly set, hasn’t yet been discovered.
-> i got an update onthat: The predefined roles will be all recruited if available to their maximum amount, while also the total of attack units main will be only recruited up to the AttackMaxDefault (or however this is called) thing right after them. If troops can't be recruited due to limitations, the recruitment interval will be skipped and the next troop will be recruited. This process is repeated until attackforce base is reached, where missing slots, because of unavailable units, or because of otherwise maxed out unit slots, will be filled up with attackUnitMain units.

As soon as a free path is opened towards the enemy keep, every unit that can move up on the keep will be rallied onto the keep automatically. Horse archers and knights can not climb the keep, which leads to them hanging around the keep in aggressive stance.
-> is especially bad for the AI, as it is incapable of targetting down economic strctures, which would usually increase the harm done by its troops!

(regarding attacking differs) and will only be recruited if the enemy has a moat to dig through -> will also be recruited, if the enemy has just setup a moat, but doesn't actually have a moat dug out.

regarding laddermen: from the walls to the keep, -> to the AI's own keep. The other way is not fixed at all!
-> so the AI needs to see a path from its own keep to the walls + a path from the walls down into the keep area of the enemy
-> with the bugfix the first requirement can be dropped

[patel-nikhil]

I like the change, and adding more and updated documentation is great.

I’d suggest using a section-by-section (topic-by-topic?) approach. Update a section, proofread, apply the change, and repeat. That will help avoid going through numerous revisions and also to start updating the information that is confirmed - instead of trying to update it all at once and having to wait for everything to be complete and confirmed

[Krarilotus]

what woudl be necessary to get this section by section into the wiki and the website?