=CannerZ45's "quick-'n-dirty" (imperfect) guide for customizing the "HackyAI" of OpenRA.=

--Disclaimer--
I did not made, nor do I have ANY hand in the original creation
of OpenRA's skirmish/multiplay bot. These guide was creatively
guided simply by personal tests, and trials&errors.

Also, I reckon this WILL be outdated in the future as OpenRA
is still an ongoing project. So as a reference;

[this was made on the 20141029-release version.]
--


--Intro--
Now, that said, I just find it a bit of a shame that such technically
impressive (and highly 'maleable'/mod-able) AI is never covered much
in the original OpenRA documents/forums/wikis. Now I understand,
mainly, because it's just suppossed to be a sort of a throwaway feature,
given OpenRA's more focused on multiplay. But still, an AI like this
just sitting around waiting to be mined and very few folks bat an eye, tsk!

--

Now, for the very first step, accessng it. It's common/original name is
"ai.yaml". Usually located in "rules" folder of a given mod directory.
For guide;	'cnc' is the mod directory for Command&Conquer(TD)
		'ra' is the mod directory for RedAlert(RA)
		and 'd2k' is the mod directory for Dune2000(D2K)

Once you've chosen your mod ai of choice...DON'T OPEN IT!
As a precaution, I highly recommend you create a backup of the 'ai.yaml'
file that you're going th edit, lest you want to be burdened of reinstalling
your whole OpenRA should you happen to mess it up.

Now, once you've made a copy of the untouched file(or you REALLY just want to
jump on it right away), you now open the ai file with your text editor of choice.

(Might I recommend "Notepad++", by the way? It's free, it's awesome, and it helps
big time on keeping your work and your flow organized. :))

So okay, you opened it up and now you're frozen at the sight of-what the heck
are you looking at? WHAT THE HELL ARE THESE THINGS?!! Now calm down, we're going
to go through with this nice and slowly together, eh? Hold my imaginary hand...


--Guide--
This part, we'll, in a way, 'dissect' this whole thing. 'gonna number them up,
and describe each part(that I know of, with the best of my ability) of an AI
character (which I had no actual hand in it's original creation).

So okay, based on what I have worked with so far, here's what *I* picked up
on regarding the construct of an OpenRA AI player-character...

----Build [with crude definitions]-

1  -	HackyAI@[WHATEVER-NAME]:

2  -		Name: [Name]
3  -		BuildingCommonNames:
 [each one under this tab references on what's in "structures.yaml"]
4  -			ConstructionYard:
5  -			Refinery:
6  -			Power:
7  -			Barracks:
8  -			VehiclesFactory:
9  -			Production:
10 -			Silo:
11 -		UnitsCommonNames:
 [each one under this tab references on what's in "vehicles.yaml"]
12 -			Mcv:
13 -		BuildingLimits:
 [structures as referenced on what's in "structures.yaml" and the amount the AI is allowed to build]
14 -		BuildingFractions:
 [structures as referenced on what's in "structures.yaml" and their 'value' for the AI, in percentages] 
15 -		UnitsToBuild:
 [structures as referenced on what's in "vehicles.yaml" and "infantry.yaml". Their 'usefulness' for the AI, in percentages] 	
16 -		SquadSize: [how many a valid strikeforce is]
17 -		MaxBaseRadius: [measured(by units/cells) from the centerpoint(which is it's Construction Yard) how big an AI base is allowed]
18 -		ShouldRepairBuildings: [true or false]
19 -		IdleBaseUnitsMaximum: [basic base guard count]
20 -		RushInterval: [measured in ticks, length between attacks]
21 -		AssignRolesInterval: [measured in ticks also, length between orders]
22 -		AttackForceInterval: [measured in ticks, again, length between making random 'strikeforce' to available units]
23 -		SupportPowerDecision@[SUPERWEAPON]:

24 -			OrderName: [superweapon name]
25 -			MinimumAttractiveness: [eh?]
26 -			Consideration@[NUMBER]:
				
27 -				Against: [enemy or ally]
28 -				Types: [Ground, Air, Water, Infantry, Vehicle, Tank, Structure]
29 -				Attractiveness: [again...wuh?]
30 -				TargetMetric: [?]	
31 -				CheckRadius: 5c0 [yep, don't know this one either!]

----In-depth Definitions-

1  - This line begins the whole character. Think of this as the very container of the AI character.
2  - The name the AI uses in-game. From "BlizzardFan82", to "Zenz0mbI". Whatever you want!
3  - I guess these are some sort of structure identifiers for the AI, to telling it how it treats some of it's structures, like, the game's 'refinery' won't be automatically recognized by the AI so you have to designate it for them under the "refinery:" tab.
4  - Okay, seems like I'm going to define them all. Alright, first one, this is the designator for a 'construction yard'.
5  - This designates the structure that processes collected 'whatever-resource' in a game mod.
6  - This designates the structure that provides power.
7  - This designates the structure that could train infantry units.
8  - This designates the structure that could build vehicular units.
9  - This designates the structure that could generaly train/build units.
10 - This designates the structure that stores excess collected 'whatever-resource' in a game mod.
11 - Like 'buildingcommonnames', but for units...I think? Welp, only have one unit to identify usually...
12 - ...which is the MCV. This designates what unit is the 'MCV'.
13 - Now this here, is a pretty interesting tab. This part generally tells the AI how many of a given structure is the AI allowed to have. Once it reached it's given quota, it will no longer build anymore of it.
14 - And this seems to go hand-in-hand with "BuildingLimits". As I understand it, the AI checks what it already have built, and based on percentages assigned to a given structures, it will build according to what the AI deems more priority/'important'.
15 - This one works just like 'BuildingFractions', but for it's units. I understand this one checks how much of a given unit (by percentage) should comprise it's army. The larger the percentage, the more  frequent the AI will build/train those.
16 - As I understand. This tells how many units would comprise an AI's random strikeforce.
17 - How big/wide(in unit cells) is the AI allowed to spread out it's base. Bit limiting given by the actual structure-placement mechanic of OpenRA.
18 - 'true' or 'false'...Does the AI know how to repair damaged structures? Tune in on next week's episode on NBC to find out!
19 - As I understand this one. It will prioritize in producing units until it reaches the quota.
20 - (measured in ticks) Interval/delay between an AI's assault/attack.
21 - As I've understood, interval/delay (again, in ticks) between each command given by an AI. Like order rates, larger values means slower to give out commands.
22 - Now this I'm not sure. Maybe interval/delay (as always, measured in ticks) between units after it reaches it's 'squadsize' quota, and making a random 'squad' out of those.
23 - Now these parts...Not wholly clear for me. I mean, sure, yeah, name to call what superweapon this characteristic fall for but most parts? I don't know. Will mark them out appropriately until help is given.
24 - The name of the superweapon?
25 - Yep, don't know how this one works.
26 - I believe this is a container for making calculated 'judgements' when the AI is considering where to use its superweapon...
27 - This references whether it's regarding an enemy, or an ally.
28 - This references on what types of targets will the AI is considering about.
29 - Yep, no clue...
30 - No Idea...
31 - Nuh-uh...

---

Alright, now that we've covered how an AI character is built, it's time to get to
work! As I recommend, you don't have to start one from nothing, simply copy an existing
AI character, rename it, then change that properties of that one. Alright. For guide,
in the "ra" mod, look for an AI named "HackyAI@NormalAI". Once you do, copy it, from
the "HackyAI@NormalAI:" line, to "CheckRadius: 7c0", before the "HackyAI@TurtleAI:"
line. Go to the very bottom, and paste your copy there. It should be indented, lined-
up properly with the other AI character, I mean, "HackyAI@NormalAI:" is on the same
row as "HackyAI@NavalAI:". As it seems, indentation is the one that governs how
they are grouped and read.

From then on, just use my guide above and mod away! Once done, save the text file,
run the game, choose the AI, and run a skirmish test map. If done correctly, you
should get into the game, fighting the very AI you created with no problem!

Of course, there's the matter of refining the AI to suit your preferences, but I think
you can handle that on your own, eh? :)

--A bunch of test-related-AFAIK's and some tips--
I don't know if there's a hard limit on how many AI characters one can build. But so far, alot that I already have made a diverse enough cast of AI's to interact with/against in the battlefield.
-
Want to make an AI of your own? Don't start from a blank/scratch. Copy a whole AI (remember, starts with "HackyAI@[NAME]"), change it's name, then slowly tweak each of it's properties.
-
Often times, the best way to gauge your custom-made AI, is to pit them with other AI characters and see how they fare.
-
Recommended you do not add the "power", "silo", and "defensive" structures in "BuildingLimits:" tab. As the AI must be allowed to be flexible on those. But yes, you can put hard limits on those too with no technical issue.
-
An AI, regardless of "BuildingFractions", WILL prioritize building "Power" and "Refinery" structures before actually following your given prioritizations. (Really wish I could make an AI, even just one AI, that builds a barracks first, before a refinery. :P)
-
As told to me by "umairazfar"...ticks per second is 25. Which means two seconds is worth 50, etc...
-
Yes, you can set whatever number on "BuildingLimits", but it seems the mechanics/calculations on "BuildingFractions" tends to go bonkers once "BuildingLimits" reaches bigger numbers (as I've tested, 4 and above, reading the bot debugs). Ruining the whole building prioritizations. But it'll still follow the 'buildinglimits' quota with no problem.
-
While it would aid the AI in expanding their base (provided, they could be sustained by their credit flow) by allowing them to build MCV's. There seems to be a problem, conflict between being able to build indefinite amount of MCVs and having limited amount of construction yard allowed(due to "buildinglimits"). This tends to 'confuse' the AI, horribly lagging the game.
-
You could force an AI to NOT build or train something by simply not including the structure's or unit's name in "BuildingLimits", "BuildingFractions", and/or "UnitstoBuild".
-
Conversely, as pointed out by "umairazfar" again. If the AI seems to not build a certain unit/structure. It's because they can't. They can't because they're probably not listed in "BuildingLimits"/"BuildingFractions"/"UnitstoBuild". Add them in their respective tabs. (common issue with mod/non-vanilla units/structures)
-
Putting large value in "MaxBaseRadius:" results in a crash after the AI builds its first structure(power plant).
-
An AI having surplus MCVs-where it has already reached it's "BuildingLimits:" quota on construction yard-kind of results with the AI becoming confused as to what to do with it's MCVs. More MCVs results in more serious lag. Which is why it's recommended that you don't allow the AI in building one.
-
Same 'lag' effect as above if the AI has a harvester unit, and no harvestable resources on the map.
-
Will probably update this one more, as I further refine my 'AI Addition' mod, and gain insight/knowledge from my fellow OpenRA modders.