To start, the language to write your AI in, is Squirrel. Squirrel is a very simple and C++ like scripting-language. For an introduction in Squirrel check the Squirrel Introduction page. The reason we picked Squirrel, is that it looks very similar to C++.

In this introduction we take you through the process of creating a basic AI. While doing so, we will explain to you the very basics you need to create an AI and an AI in OpenTTD. For advanced AI handling we suggest you to buy a good book. The end-result of this tutorial can be found back in the 'example' directories.

Creating your own AI

There are several ways to get started.

You may wish to download an existing AI and modify it if the license allows (at the time of this writing all known AI's were open source). You can start from "Wright AI" and build up from there.

The guide assumes you wish to start your own AI from scratch. TestAI is an example of the minimal AI with users settings. You can examine or copy that code to see what you must have to get started.

A general programming rule of the thumb is to write good documentation for your AI, so after a few days or even months you can easily remember what the functions are supposed to do. Splitting the AI into smaller, logical files will also help with organization. Some AI writers use Doxygen style comments to allow them to produce high quality documentation automatically.

Required Squirrel Files

1. Locate your openttd installation folder. On Windows, by default it is in C:\Program Files\OpenTTD, or C:\Program Files (x86)\Steam\steamapps\common\OpenTTD for the Steam version, for Linux it's in /usr/share/games/openttd and for mac its (your username)/documents/openttd
2. Create a new directory for your ai under the ai directory. For example you could create the directory MyNewAI
   • You could also create a new directory under the content_download/ai (located in your ~/.openttd folder on Linux while it's in the Documents/OpenTTD folder of the user's directory on Windows), but this method is NOT recommended since you might overwrite your files if you put your AI on Bananas and, since it's located in a user's home, will only work for that particular user.
3. Create a file called info.nut. This is important as the Squirrel loader looks for that and main.nut in all subdirectories. If it doesn't find info.nut, the directory is considered to be something else, and your AI won't be loaded.

Your directory layout should look like this now:

$OpenTTD_Dir/
    | ai/
        | MyNewAI/
            | info.nut 
            | main.nut

Open info.nut and then continue reading the next section.

Register

You want to let OpenTTD know you have an AI that wants to take over a company. For this, you need to add a class that extends AIInfo:

class MyNewAI extends AIInfo {
  function GetAuthor()      { return "Newbie AI Writer"; }
  function GetName()        { return "MyNewAI"; }
  function GetDescription() { return "An example AI by following the tutorial at http://wiki.openttd.org/"; }
  function GetVersion()     { return 1; }
  function GetDate()        { return "2022-10-27"; }
  function CreateInstance() { return "MyNewAI"; }
  function GetShortName()   { return "XXXX"; }
  function GetAPIVersion()  { return "12"; }
}

What this does is tell OpenTTD how your AI is called, its version, and other general information. Note that the short name has to have exactly 4 characters. After this you need to create an instance of the class. Squirrel:

/* Tell the core we are an AI */
RegisterAI(MyNewAI());

This is enough to initialise your AI. But, we are not quite there yet to give it a first run. We don't have a real AI yet, only a piece of code that tells what your AI is, and who wrote it. So, let's make a class that will be our AI.

Your First AI

To do this, create a file main.nut in the same dir, and make a class that extends AIController. See Coding style for formatting recommendations.

class MyNewAI extends AIController 
{
  function Start();
}

function MyNewAI::Start()
{
  while (true) {
    AILog.Info("I am a very new AI with a ticker called MyNewAI and I am at tick " + this.GetTick());
    this.Sleep(50);
  }
}

The first block creates the class extending AIController.The second blocks creates a Start() function, which is called once when your AI is started. If you exit from this function, your AI dies. Therefore we create a while() which never stops. You don't need to worry too much about your AI clogging the game by eating all the CPU of your computer (and thus stopping the game itself from running), the engine itself will sleep every X opcodes which forces fair scheduling and allows the game to run smoothly. You can however put the AI to sleep manually by calling the Sleep() command. You will see when we start this AI in a moment, that you get a print line in your console every 50 ticks.

Start a new game and look on the main game screen for AI Settings. From there select your AI to run. You will only need to restart the game any time you change the info.nut file. Be sure to change the start time on your AI so you don't have to sit around waiting on it.

Hint: On Windows Vista you may need to run openttd.exe as administrator. Either right click and choose "Run as Administrator" each time, or turn off UAC for Administrators ([1]). If OpenTTD is not run as administrator the AI directories will be invisible to the executable, and loading any AI will result in an "The AI named 'XYZ' is unknown or not suitable" error.

If you open the AI Debug Window, which can be found under the QuestionMark icon, you will see a nice line printing we are active. You can also manually start your newly created AI by typing the command

start_ai MyNewAI

into the in-game console (opens with ` key)

If you make code changes to anything other than info.nut you can use the console command restart to start the game over from the beginning. Or you can just use the "Reload AI" button on the AI Debug window.

Any errors that are found, both compile-time and run-time, are send to the AI Debug Window. If your info.nut doesn't load, you won't see the errors unless you enable the debug console from the command line of the game. -d script=5.

You can redirect the output to the in-game console by opening in-game console console and typing

developer 2

Enable output of print and AILog.* statements from your AI by typing

debug_level script=4

You can scroll the console window with SHIFT-PGUP, SHIFT-PGDOWN and SHIFT-(up/down)ARROW keys.

So, there you have your first AI. Of course now we need to add functions. For this we advise you continue to the next chapter Basics. You only have to know that all your code should go in Start(). One more thing you should know: never create global variables. Keep everything in your class instance. But this is just a house-rule and if you don't know what it means, it doesn't really matter at this point.