Scripting for Age of Empires III
Help for scripting maps can be pretty scarse. Every so often, I see questions posted or emailed to me that really lack a "findable answer," that is it hasn't exactly been posted anywhere or documented properly. I will update this list as needed. Feel free to send me an email and add on.
Arrays
Unlike what previously thought. RMS Arrays DO exist! By most random chance, I found them in less than a minute skim through the ai files...
Basically here's how it goes:
int VARIABLE = xsArrayCreateVARTYPE(##, VALUE, "STRING NAME");
// This creates the array set. VARIABLE is what you will refer to the array. VARTYPE is such as string, int, or float. VALUE is the initial value such as "", 0, or 0.0. STRING NAME is like a trigger name - just there for identification. ## is the number of items in the array - presumably defined to save memory.
xsArraySetVARTYPE(VARIABLE, KEY, VALUE);
// This sets an item's value in an array. KEY is what you refer to to get VALUE. You will understand when we get to the "get" function for arrays.
xsArrayGetVARTYPE(VARIABLE, KEY);
// This gets an item's value by naming the item's KEY in the array. If the keys are numbers for example, a simple loop will get them all. Actually I've only seen KEYs as integers so that might be a limit.
xsArrayGetSize(VARIABLE);
//This function counts the number of items in an array.
There might be even more array functions than this. I've only just found out there were arrays very recently...
Functions
Currently there is no complete list of all functions you can use (although Hyena Studios covers a great deal of them). Here are some you might find handy:
rmGetPlayerName(integer value) - Returns a string with the player's name. The integer value determines the player number to get the name from. However, there are certain issues with the function when the player's name contains special characters such as Ä or «, as noted at Age of Empires III Heaven Forums. Detection is fine, but just do not output the player's name unless you know it contains no foreign characters.
rmGetNomadStart() - Determines whether or not the map is hosted in Nomad Age. Use in an if function: if(rmGetNomadStart())
General Scripting
Forested Areas - Never place forests in the beginning of your script if you're using triggers or reliant on object ids. Placing forests scrambles the variables/ids of objects placed before it, making it nearly impossible to reference a center unit in a trigger etc.
Triggers
Trigger Locations - In effects such as Army Deploy where one must specify a location for the trigger to take place, you must use this format:
rmSetTriggerEffectParam('Location', rmXFractionToMeters(#)+',1,'+rmZFractionToMeters(#));
The effect uses X, Y, Z coordinates. X and Z are what you use and must be converted to meters as shown (the example converts from a fraction measure to meters). Y is supposedly the height, but doesn't appear to affect anything. I generally leave it at 1. Perhaps units that do not snap to the terrain will benefit, but I've yet to see that.
Feel free to send me an email and add on.