Lists are a basic part of the NoAI API. They allow fast and easy manipulation of all kinds of data. This page will explain in a simple matter how to use them and what you can expect from them.

Items / Values

An AIList is a set of item-value pairs. The item is usually the data you want to store in the list. For example town ids. The value is some information that is related to the item. For example you could have the town population as value.

Valuators

To filter, you can apply valuators on the list using <list>.Valuate(<valuator>), they change the value of the list entry accordingly. The first parameter for this function is the function you want to use to valuate the items in the list. It should accept at least one integer which will be set to the item, and should return an integer, which will become the value of the item. Additional parameters are possible, then you need to add them to the Valuator too. Example:

list.Valuate(AIBridge.GetPrice, 5);
list.Valuate(AIBridge.GetMaxLength);
function MyVal(bridge_id, myparam)
{
   return myparam * bridge_id; // This is silly
}
list.Valuate(MyVal, 12);

After you have applied a valuator, you can modify (remove items, sort, etc.) the list using the functions found in the API docs.

Examples of lists

AIList()

To start, AIList() is the most primary list we have. It doesn't depend in any way on the OpenTTD core. It is a simple list you can fill with items and make valuators for them. As AITownList() is a good example of a bit more complex AIList(), we will discuss that one rather then AIList().

AICargoList()

Despite only having one value, the Cargo ID, you still need to call foreach with two parameters:

local allCargo = AICargoList()
foreach(cargo, unused in allCargo) {
 AILog.Info("Evaluating " + AICargo.GetName(cargo))
}

AITownList()

Of course you want to know which towns are in the map, and most likely: which town has to most population, and what the location is. For that we have AITownList(). If you create an instance of it, it immediately fills itself with all towns. You can walk them like this:

foreach (town, value in townlist) { }

This walks all the towns inside the list. Of course knowing the towns is only part of AITownList(), you can also make it find data for you. For example, we want to know all towns with population higher than 500. First we call a valuator that gets the population per town for us, and then we filter all the towns with a lower population than 500 out of the list. What is left, is a list of towns that have more than 500 people in them.

townlist.Valuate(AITown.GetPopulation);
townlist.KeepAboveValue(500);

If you now would print the list, you will see only towns with population higher than 500. Of course you can now get the position of those towns by doing:

townlist.Valuate(AITown.GetLocation);

The only thing this means, is that the population per town is lost, and replaced by the location.

AIList()s are automatically sorted. Normally this is down by value, descending (so highest first). You can change the sort order with the Sort() functions (see API documentation). You can see if a list is empty with Empty(), or find the amount of towns with Count(). For more details, see API documentation.

AITileList()

Besides townlist, industrylist, and more of that, we also have a AITileList(). This is in fact the same as AITownList(), but it keeps track of tiles. You can add tiles to the list, and then, for example, see what the acceptance is for a certain cargo. Or filter away the non-buildable tiles. This means you can quickly find a good spot for a station of which you know will get a good amount of goods. Also you can ensure it connects to the town-road for example, with the AIRoad.GetNeighbourRoadCount() valuator.