How Object Arrays Work

How Object Arrays Work

I've seen the question asked over and over at various forums, so I figured this should be made common knowledge.

The object arrays ( [InfantryTypes] , [Movies] , [Tiberiums], etc. ) are internally 0-based. That means, the first item listed in such an array will always have index #0 ingame, the second one will be #1, and so on, regardless of what the text on the left of the equals sign says. You can have things like a^2+b^2=CSQUARED and the game would recognize CSQUARED and put it into the array correctly.

These internal indices are a way how the game refers to these objects, widely used by AI scripts and map triggers. So, a map trigger action that says "Play Animation #250 at waypoint 45" will play the animation that has the internal index of #250 in the [Animations] list, which is not necessarily [Animations]250=.

All new entries (from mpmode files and map files) are appended to the end of the appropriate arrays, provided their entries are not in them already.

For example:

rules.ini contains

[AircraftTypes]
4=ORCA
1=ORCAB
0=SCRIN
11=MIG
9500=DUMMYOBJECT
-7=APACHE

and map75.mpr contains

[AircraftTypes]
1=SCRIN
3=ROFLCOPTER
49=B52

So, when you're playing on map75.mpr, the game builds the [AircraftTypes] array as follows:

[AircraftTypes]
0=ORCA
1=ORCAB
2=SCRIN
3=MIG
4=DUMMYOBJECT
5=APACHE
6=ROFLCOPTER
7=B52

And when you're playing on emptymap.mpr, which doesn't define new [AircraftTypes], the array will be

[AircraftTypes]
0=ORCA
1=ORCAB
2=SCRIN
3=MIG
4=DUMMYOBJECT
5=APACHE

Common Questions & Answers

Q. So can I place silly words to the left of the equals sign without any problems?

A: Yes, while you can place almost (except for the = sign itself...) anything to the left of the equals sign, it makes most sense to keep the numbering identical to the one used ingame.

Q: What features break if I break the existing ordering (say, by adding new items to the middle of the list)?

A: No matter whether you added or removed items from the middle of the array, you messed up the internal ordering. The consequences - almost every array of the game has a corresponding map trigger and/or AI script action that calls for an object from that array via index. So, reordering those lists is not advised under any circumstances. Add your new objects to the end of it.

Q: Are Westwood's unmodded arrays correct?

A: Not quite. They have made a lot of little mistakes, which add up and look sloppy. DCoder have fixed some of them (the ugliest ones) and posted them on their corresponding pages, BuildingTypes and Animations. More corrected versions will follow soon.

Manual sorting is a tedious and thankless task, especially when dealing with Flags like FreeUnit that automatically add objects to registration forms of specific types, as described in this article. However, in Ares, you can directly use the Type Data Dumping developer feature to output the actual registration forms read by the program. Refer to the Ares documentation for details.

Tip: The bottom of the documentation page explains how to disable this keyboard command, which you'll likely need when officially releasing your mod.

Q: What about capitalization of the section names?

A: Make sure you capitalize the objects identically everywhere you reference them. If you say [VehicleTypes] 75=AtNk, please be so nice and use [AtNk] as the rules section name. If you say [AtNk] Image=ATnK, use [ATnK] in the art file. Get the pattern?

Q: What about duplicate entries, like 15=FOO and 75=FOO ?

A: The first one is loaded, the second one is discarded as if it was commented out. Removing it will have no effect on the numbering, but replacing it with something else will.