Spring - User contributions [en]

AI:Development:Lang:Java

2014-05-19T18:43:30Z

Meriton: /* Building a metal extractor */

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAI',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

Whenever a unit has been built, the engine sends a unitFinished event. At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method:

<code><pre>
@Override
public int unitFinished(Unit unit) {
if (unit.getDef().getName().equals("armcom")) {
commander = unit;
}

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Commands are issued by invoking the respective method on the <code>Unit</code> (or <code>Group</code>). In our case, that's the <code>build</code> method, which takes the following arguments:

* <code>UnitDef toBuildUnitDef</code>: the kind of unit to build
* <code>AIFLoat3 buildPos</code>: the location the unit should be built at (in our case, we use the commander's current position)
* <code>int facing</code>: the direction the new unit will be facing (mostly matters for buildings, which can not turn after being constructed)
* <code>short options</code>: a set of UnitCommandOptions. 0 means no option.
* <code>int timeout</code>: the number of frames after which the command times out. We don't want a timeout, and therefore specify a suitably high number :-)

Therefore, our command looks like this:

<code>
commander.build(solarDef, commander.getPos(), 0, (short) 0, Integer.MAX_VALUE);
</code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
commander.build(metalExtractor, closestspot, 0, (short) 0, Integer.MAX_VALUE);
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-19T18:42:52Z

Meriton: /* Building a metal extractor */

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAI',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

Whenever a unit has been built, the engine sends a unitFinished event. At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method:

<code><pre>
@Override
public int unitFinished(Unit unit) {
if (unit.getDef().getName().equals("armcom")) {
commander = unit;
}

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Commands are issued by invoking the respective method on the <code>Unit</code> (or <code>Group</code>). In our case, that's the <code>build</code> method, which takes the following arguments:

* <code>UnitDef toBuildUnitDef</code>: the kind of unit to build
* <code>AIFLoat3 buildPos</code>: the location the unit should be built at (in our case, we use the commander's current position)
* <code>int facing</code>: the direction the new unit will be facing (mostly matters for buildings, which can not turn after being constructed)
* <code>short options</code>: a set of UnitCommandOptions. 0 means no option.
* <code>int timeout</code>: the number of frames after which the command times out. We don't want a timeout, and therefore specify a suitably high number :-)

Therefore, our command looks like this:

<code>
commander.build(solarDef, commander.getPos(), 0, (short) 0, Integer.MAX_VALUE);
</code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
commander.build(metalExtractor, closestSpot, 0, (short) 0, Integer.MAX_VALUE);
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T20:44:38Z

Meriton: /* Telling the commander to build the solar plant */

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAI',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

Whenever a unit has been built, the engine sends a unitFinished event. At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method:

<code><pre>
@Override
public int unitFinished(Unit unit) {
if (unit.getDef().getName().equals("armcom")) {
commander = unit;
}

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Commands are issued by invoking the respective method on the <code>Unit</code> (or <code>Group</code>). In our case, that's the <code>build</code> method, which takes the following arguments:

* <code>UnitDef toBuildUnitDef</code>: the kind of unit to build
* <code>AIFLoat3 buildPos</code>: the location the unit should be built at (in our case, we use the commander's current position)
* <code>int facing</code>: the direction the new unit will be facing (mostly matters for buildings, which can not turn after being constructed)
* <code>short options</code>: a set of UnitCommandOptions. 0 means no option.
* <code>int timeout</code>: the number of frames after which the command times out. We don't want a timeout, and therefore specify a suitably high number :-)

Therefore, our command looks like this:

<code>
commander.build(solarDef, commander.getPos(), 0, (short) 0, Integer.MAX_VALUE);
</code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T20:43:46Z

Meriton: /* Getting a reference to the commander */

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAI',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

Whenever a unit has been built, the engine sends a unitFinished event. At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method:

<code><pre>
@Override
public int unitFinished(Unit unit) {
if (unit.getDef().getName().equals("armcom")) {
commander = unit;
}

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Commands are issued by invoking the respective method on the <code>Unit</code>. In our case, that's the <code>build</code> method, which takes the following arguments:

* <code>UnitDef toBuildUnitDef</code>: the kind of unit to build
* <code>AIFLoat3 buildPos</code>: the location the unit should be built at (in our case, we use the commander's current position)
* <code>int facing</code>: the direction the new unit will be facing (mostly matters for buildings, which can not turn after being constructed)
* <code>short options</code>: a set of UnitCommandOptions. 0 means no option.
* <code>int timeout</code>: the number of frames after which the command times out. We don't want a timeout, and therefore specify a suitably high number :-)

Therefore, our command looks like this:

<code>
commander.build(solarDef, commander.getPos(), 0, (short) 0, Integer.MAX_VALUE);
</code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T20:42:58Z

Meriton: Removed the command stuff (commands no longer exist)

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAI',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

Whenever a unit has been built, the engine sends a unitFinished event. At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method:

<code><pre>
@Override
public int unitFinished(Unit unit) {
if (unit.getDef().getName().equals("armcom")) {
Unit commander = unit;

// do something with the commander here
}

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Commands are issued by invoking the respective method on the <code>Unit</code>. In our case, that's the <code>build</code> method, which takes the following arguments:

* <code>UnitDef toBuildUnitDef</code>: the kind of unit to build
* <code>AIFLoat3 buildPos</code>: the location the unit should be built at (in our case, we use the commander's current position)
* <code>int facing</code>: the direction the new unit will be facing (mostly matters for buildings, which can not turn after being constructed)
* <code>short options</code>: a set of UnitCommandOptions. 0 means no option.
* <code>int timeout</code>: the number of frames after which the command times out. We don't want a timeout, and therefore specify a suitably high number :-)

Therefore, our command looks like this:

<code>
commander.build(solarDef, commander.getPos(), 0, (short) 0, Integer.MAX_VALUE);
</code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T20:23:44Z

Meriton: Shorter example (if people don't know what a field is, they won't be having much luck coding an ai, so it's pointless repeating this here)

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAI',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

Whenever a unit has been built, the engine sends a unitFinished event. At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method:

<code><pre>
@Override
public int unitFinished(Unit unit) {
if (unit.getDef().getName().equals("armcom")) {
Unit commander = unit;

// do something with the commander here
}

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Giving a command is straightforward. All we need to do is to create the appropriate command object and pass it through the callback to the engine.

EDIT: the command class is outdated and not included in the current oo wrapper. Commands are now given via the unit class. See: http://spring.abma.de/doc-Interface-JavaOO/com/springrts/ai/oo/clb/Unit.html

The command we need to tell commander to build a solar plant is a <code>BuildUnitAICommand</code>. This command takes a number of arguments:

; Unit unit : the unit we want to give to order to
; int groupId : the group we want to give the order to
; List<AICommand.Option> optionsList : a list addional options. See the values of AICommand.Option for details
; int timeOut : the number of frames after which the command times out
; UnitDef toBuildUnitDef : the UnitDef of the unit we want to build
; AIFloat3 buildPos : the position to build the unit at
; int facing : the direction the new unit should face

As you can see above, we can give a command to either a single unit or a group of units. In this example we only have a single unit. This means that unit should be a reference to our commander, and <code>groupId</code> should be -1.
To keep things simple, we will not use any options, set the timeout to a large number, and set facing to 0.
The value of <code>toBuildUnitDef</code> should be the object reference stored int UnitDef solarPlant.
That only leaves <code>buildPos</code>, for which we will just use the current position of our commander. This means that our <code>BuildUnitAICommand</code> looks like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);
}

return 0;
}
</pre></code>

Next, we should give the command to the engine. We do this through the method <code>callback.getEngine().handleCommand()</code>. This method takes three arguments: the id of the recipient of the command, a <code>commandID</code> and the command itself.
The command should be sent to the engine, and for now we will use a <code>commandID</code> of <code>-1</code>, as this is a feature which is not yet supported by spring (asynchronous command tracking).
Our code will look like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);

this.callback.getEngine().handleCommand(AICommandWrapper.COMMAND_TO_ID_ENGINE,
-1, command);
}

return 0;
}
</pre></code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T19:08:56Z

Meriton: OOAIFactory no longer exists

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAI',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

In order to have your AI build a solar plant, the first thing you need is a reference to your commander. You first need an instance field 'Unit commander' to put the reference in, then we need to get the reference itself.
A UnitFinished event is triggered whenever a unit has been built. (This may sound similar to <code>unitCreated()</code>. For a quick explanation of the difference, see the FAQ below.)
At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method.

To get a reference to the commander, you need to check if the unit is indeed the command, and if so, assign the value of the unit parameter to the commander field:

<code><pre>
@Override
public int unitFinished(Unit unit)
{
if (unit.getDef().getName().equals("armcom"))
this.commander = unit;

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Giving a command is straightforward. All we need to do is to create the appropriate command object and pass it through the callback to the engine.

EDIT: the command class is outdated and not included in the current oo wrapper. Commands are now given via the unit class. See: http://spring.abma.de/doc-Interface-JavaOO/com/springrts/ai/oo/clb/Unit.html

The command we need to tell commander to build a solar plant is a <code>BuildUnitAICommand</code>. This command takes a number of arguments:

; Unit unit : the unit we want to give to order to
; int groupId : the group we want to give the order to
; List<AICommand.Option> optionsList : a list addional options. See the values of AICommand.Option for details
; int timeOut : the number of frames after which the command times out
; UnitDef toBuildUnitDef : the UnitDef of the unit we want to build
; AIFloat3 buildPos : the position to build the unit at
; int facing : the direction the new unit should face

As you can see above, we can give a command to either a single unit or a group of units. In this example we only have a single unit. This means that unit should be a reference to our commander, and <code>groupId</code> should be -1.
To keep things simple, we will not use any options, set the timeout to a large number, and set facing to 0.
The value of <code>toBuildUnitDef</code> should be the object reference stored int UnitDef solarPlant.
That only leaves <code>buildPos</code>, for which we will just use the current position of our commander. This means that our <code>BuildUnitAICommand</code> looks like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);
}

return 0;
}
</pre></code>

Next, we should give the command to the engine. We do this through the method <code>callback.getEngine().handleCommand()</code>. This method takes three arguments: the id of the recipient of the command, a <code>commandID</code> and the command itself.
The command should be sent to the engine, and for now we will use a <code>commandID</code> of <code>-1</code>, as this is a feature which is not yet supported by spring (asynchronous command tracking).
Our code will look like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);

this.callback.getEngine().handleCommand(AICommandWrapper.COMMAND_TO_ID_ENGINE,
-1, command);
}

return 0;
}
</pre></code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T18:48:08Z

Meriton: OOAIFactory no longer exists

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the main class ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAIFactory',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

In order to have your AI build a solar plant, the first thing you need is a reference to your commander. You first need an instance field 'Unit commander' to put the reference in, then we need to get the reference itself.
A UnitFinished event is triggered whenever a unit has been built. (This may sound similar to <code>unitCreated()</code>. For a quick explanation of the difference, see the FAQ below.)
At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method.

To get a reference to the commander, you need to check if the unit is indeed the command, and if so, assign the value of the unit parameter to the commander field:

<code><pre>
@Override
public int unitFinished(Unit unit)
{
if (unit.getDef().getName().equals("armcom"))
this.commander = unit;

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Giving a command is straightforward. All we need to do is to create the appropriate command object and pass it through the callback to the engine.

EDIT: the command class is outdated and not included in the current oo wrapper. Commands are now given via the unit class. See: http://spring.abma.de/doc-Interface-JavaOO/com/springrts/ai/oo/clb/Unit.html

The command we need to tell commander to build a solar plant is a <code>BuildUnitAICommand</code>. This command takes a number of arguments:

; Unit unit : the unit we want to give to order to
; int groupId : the group we want to give the order to
; List<AICommand.Option> optionsList : a list addional options. See the values of AICommand.Option for details
; int timeOut : the number of frames after which the command times out
; UnitDef toBuildUnitDef : the UnitDef of the unit we want to build
; AIFloat3 buildPos : the position to build the unit at
; int facing : the direction the new unit should face

As you can see above, we can give a command to either a single unit or a group of units. In this example we only have a single unit. This means that unit should be a reference to our commander, and <code>groupId</code> should be -1.
To keep things simple, we will not use any options, set the timeout to a large number, and set facing to 0.
The value of <code>toBuildUnitDef</code> should be the object reference stored int UnitDef solarPlant.
That only leaves <code>buildPos</code>, for which we will just use the current position of our commander. This means that our <code>BuildUnitAICommand</code> looks like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);
}

return 0;
}
</pre></code>

Next, we should give the command to the engine. We do this through the method <code>callback.getEngine().handleCommand()</code>. This method takes three arguments: the id of the recipient of the command, a <code>commandID</code> and the command itself.
The command should be sent to the engine, and for now we will use a <code>commandID</code> of <code>-1</code>, as this is a feature which is not yet supported by spring (asynchronous command tracking).
Our code will look like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);

this.callback.getEngine().handleCommand(AICommandWrapper.COMMAND_TO_ID_ENGINE,
-1, command);
}

return 0;
}
</pre></code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T18:16:21Z

Meriton: /* Importing the interface libraries */

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the required classes ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI. After that you'll need another class, named ''MyJavaAIFactory''. This class should extend ''com.springrts.ai.oo.OOAIFactory''.
The class MyJavaAIFactory only has to implement a single method: ''public OOAI createAI(int teamId, OOAICallback callback)''. This is the method that the Java interface calls to get an instance of your AI. If you wanted to, you could create a different AI depending on circumstances, but for now it is probably easiest to simply return a new MyJavaAI(), until you decide you require something more elaborate.
You should now have two classes, ''myjavaai.MyJavaAI'' and ''myjavaai.MyJavaAIFactory''.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAIFactory',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

In order to have your AI build a solar plant, the first thing you need is a reference to your commander. You first need an instance field 'Unit commander' to put the reference in, then we need to get the reference itself.
A UnitFinished event is triggered whenever a unit has been built. (This may sound similar to <code>unitCreated()</code>. For a quick explanation of the difference, see the FAQ below.)
At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method.

To get a reference to the commander, you need to check if the unit is indeed the command, and if so, assign the value of the unit parameter to the commander field:

<code><pre>
@Override
public int unitFinished(Unit unit)
{
if (unit.getDef().getName().equals("armcom"))
this.commander = unit;

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Giving a command is straightforward. All we need to do is to create the appropriate command object and pass it through the callback to the engine.

EDIT: the command class is outdated and not included in the current oo wrapper. Commands are now given via the unit class. See: http://spring.abma.de/doc-Interface-JavaOO/com/springrts/ai/oo/clb/Unit.html

The command we need to tell commander to build a solar plant is a <code>BuildUnitAICommand</code>. This command takes a number of arguments:

; Unit unit : the unit we want to give to order to
; int groupId : the group we want to give the order to
; List<AICommand.Option> optionsList : a list addional options. See the values of AICommand.Option for details
; int timeOut : the number of frames after which the command times out
; UnitDef toBuildUnitDef : the UnitDef of the unit we want to build
; AIFloat3 buildPos : the position to build the unit at
; int facing : the direction the new unit should face

As you can see above, we can give a command to either a single unit or a group of units. In this example we only have a single unit. This means that unit should be a reference to our commander, and <code>groupId</code> should be -1.
To keep things simple, we will not use any options, set the timeout to a large number, and set facing to 0.
The value of <code>toBuildUnitDef</code> should be the object reference stored int UnitDef solarPlant.
That only leaves <code>buildPos</code>, for which we will just use the current position of our commander. This means that our <code>BuildUnitAICommand</code> looks like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);
}

return 0;
}
</pre></code>

Next, we should give the command to the engine. We do this through the method <code>callback.getEngine().handleCommand()</code>. This method takes three arguments: the id of the recipient of the command, a <code>commandID</code> and the command itself.
The command should be sent to the engine, and for now we will use a <code>commandID</code> of <code>-1</code>, as this is a feature which is not yet supported by spring (asynchronous command tracking).
Our code will look like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);

this.callback.getEngine().handleCommand(AICommandWrapper.COMMAND_TO_ID_ENGINE,
-1, command);
}

return 0;
}
</pre></code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T16:35:10Z

Meriton: /* Importing the interface libraries */

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries (optionally, you can attach the sources for for JavaDoc support in your editor)

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code> (sources: jlib/AIInterface-src.jar</code>)
* <code>Spring/AI/Skirmish/NullOOJavaAI/0.1/jlib/vecmath.jar</code> (sources: vecmath-src.jar)
* <code>JavaOO-AIWrapper.jar</code> (sources: TODO)

==== Creating the required classes ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI. After that you'll need another class, named ''MyJavaAIFactory''. This class should extend ''com.springrts.ai.oo.OOAIFactory''.
The class MyJavaAIFactory only has to implement a single method: ''public OOAI createAI(int teamId, OOAICallback callback)''. This is the method that the Java interface calls to get an instance of your AI. If you wanted to, you could create a different AI depending on circumstances, but for now it is probably easiest to simply return a new MyJavaAI(), until you decide you require something more elaborate.
You should now have two classes, ''myjavaai.MyJavaAI'' and ''myjavaai.MyJavaAIFactory''.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAIFactory',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

In order to have your AI build a solar plant, the first thing you need is a reference to your commander. You first need an instance field 'Unit commander' to put the reference in, then we need to get the reference itself.
A UnitFinished event is triggered whenever a unit has been built. (This may sound similar to <code>unitCreated()</code>. For a quick explanation of the difference, see the FAQ below.)
At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method.

To get a reference to the commander, you need to check if the unit is indeed the command, and if so, assign the value of the unit parameter to the commander field:

<code><pre>
@Override
public int unitFinished(Unit unit)
{
if (unit.getDef().getName().equals("armcom"))
this.commander = unit;

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Giving a command is straightforward. All we need to do is to create the appropriate command object and pass it through the callback to the engine.

EDIT: the command class is outdated and not included in the current oo wrapper. Commands are now given via the unit class. See: http://spring.abma.de/doc-Interface-JavaOO/com/springrts/ai/oo/clb/Unit.html

The command we need to tell commander to build a solar plant is a <code>BuildUnitAICommand</code>. This command takes a number of arguments:

; Unit unit : the unit we want to give to order to
; int groupId : the group we want to give the order to
; List<AICommand.Option> optionsList : a list addional options. See the values of AICommand.Option for details
; int timeOut : the number of frames after which the command times out
; UnitDef toBuildUnitDef : the UnitDef of the unit we want to build
; AIFloat3 buildPos : the position to build the unit at
; int facing : the direction the new unit should face

As you can see above, we can give a command to either a single unit or a group of units. In this example we only have a single unit. This means that unit should be a reference to our commander, and <code>groupId</code> should be -1.
To keep things simple, we will not use any options, set the timeout to a large number, and set facing to 0.
The value of <code>toBuildUnitDef</code> should be the object reference stored int UnitDef solarPlant.
That only leaves <code>buildPos</code>, for which we will just use the current position of our commander. This means that our <code>BuildUnitAICommand</code> looks like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);
}

return 0;
}
</pre></code>

Next, we should give the command to the engine. We do this through the method <code>callback.getEngine().handleCommand()</code>. This method takes three arguments: the id of the recipient of the command, a <code>commandID</code> and the command itself.
The command should be sent to the engine, and for now we will use a <code>commandID</code> of <code>-1</code>, as this is a feature which is not yet supported by spring (asynchronous command tracking).
Our code will look like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);

this.callback.getEngine().handleCommand(AICommandWrapper.COMMAND_TO_ID_ENGINE,
-1, command);
}

return 0;
}
</pre></code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

AI:Development:Lang:Java

2014-05-18T16:26:02Z

Meriton: /* Getting Started on your own Java AI */

[[Engine_Development|Development]] < [[AI:Development|AI Development]] < Java AI Development

== Getting Started on your own Java AI ==

''Note:'' This tutorial assumes you have Spring working on your machine. The Spring directory will be referred to as 'Spring' from here on.

You will also need to make sure that Java AI's run properly on your machine. This is most easily done by running a Spring game with the ''NullOOJavaAI'' that comes with the engine. You will need the JRE 1.5 or greater, and to set the ''JAVA_HOME'' environment variable on your system to point to the correct location.

''Note:'' If you're using a ''64 bit'' version of ''Windows'', you will need a 32 bit Java Runtime Environment/Java Development Kit anyway, because Spring is (as of May 2014) not yet available as a 64bit version for Windows.

=== Setting up a Java Project ===

To start working on your own Java AI, you should first set up a project in your favorite Java IDE. You need to import the Spring Java AI Interface libraries, and then create an AI class and an AI Factory.

'''OUTDATED''' If you are using '''Netbeans IDE''', you can find a detailed tutorial [http://springrts.com/phpbb/download/file.php?id=4970 here] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread]). Otherwise, please continue reading this page.

==== Importing the interface libraries ====

In order to use the Java Interface, you will need to import the Java Interface libraries, located in ''Spring/AI/Interfaces/Java/[version]/''. Replace ''[version]'' with the number of the latest Java Interface version. As of this writing, only ''0.1'' is available.

The file you need is ''AIInterface.jar''. You also need the additional library ''vecmath.jar'', located in the ''jlib/'' subfolder. Optionally, you can attach the file ''AIInterface-src.jar'' as source to the ''AIInterface.jar'' file for JavaDoc support in your editor.

Your project should now contain the following libraries:

* <code>Spring/AI/Interfaces/Java/[version]/AIInterface.jar</code>
* <code>Spring/AI/Interfaces/Java/[version]/jlib/AIInterface-src.jar</code> (optional)
* <code>Spring/AI/Interfaces/Java/[version]/jlib/vecmath.jar</code>

==== Creating the required classes ====

Now that you have the libraries, the next step is to create your AI's main class. Firstly, you may want to create a package to put your classes in, for example, ''myjavaai''. Create a new class, named MyJavaAI (or whatever you would like your AI to be called). MyJavaAI should extend com.springrts.ai.oo.AbstractOOAI. After that you'll need another class, named ''MyJavaAIFactory''. This class should extend ''com.springrts.ai.oo.OOAIFactory''.
The class MyJavaAIFactory only has to implement a single method: ''public OOAI createAI(int teamId, OOAICallback callback)''. This is the method that the Java interface calls to get an instance of your AI. If you wanted to, you could create a different AI depending on circumstances, but for now it is probably easiest to simply return a new MyJavaAI(), until you decide you require something more elaborate.
You should now have two classes, ''myjavaai.MyJavaAI'' and ''myjavaai.MyJavaAIFactory''.

=== Adding your AI to Spring ===

Your AI needs to have its own folder, and the engine will need to know your AI's attributes.

==== Creating an AI folder ====

Every Spring AI is stored in ''Spring/AI/Skirmish''. You will have to create a folder for your AI as well. It is easiest to go to the directory ''Spring/AI/Skirmish'', make a copy of the folder ''NullOOJavaAI'', and rename the copy to ''MyJavaAI''.

==== Telling the Engine about your AI ====

The ''MyJavaAI'' folder you created contains the different versions of your AI. As of this writing, the ''NullOOJavaAI'' only has a version ''0.1'', so there should be a folder ''0.1'' inside the ''MyJavaAI'' folder. Inside you will find a number of files.
These files are:
* ''SkirmishAI.jar'': the jar file that contains the AI code.
* ''AIInfo.lua'': contains information about the AI.
* ''AIOptions.lua'': you can specify your AI's options in here.
* Possibly some text files: these are log files generated by the ''NullOOJavaAI''. If you don't plan on using the same files, you may as well delete these.

Additionally, there is a folder named ''jlib''. This is where you should place any additional libraries you use in your AI.

In order to let Spring recognize your AI, you will have to edit ''AIInfo.lua''. You can do this with any regular text editor.
When you open it, the file will look something like this:

<code><pre>
local infos = {
{
key = 'shortName',
value = 'NullOOJavaAI',
desc = 'machine conform name.',
},
{
key = 'version',
value = '0.1', -- AI version - !This comment is used for parsing!
},
{
key = 'className',
value = 'nulloojavaai.NullOOJavaAIFactory',
desc = 'fully qualified name of a class that implements interface com.springrts.ai.AI',
},
{
key = 'name',
value = 'high-level Java stub Skirmish AI',
desc = 'human readable name.',
},
{
key = 'loadSupported',
value = 'no',
desc = 'whether this AI supports loading or not',
},
{
key = 'interfaceShortName',
value = 'Java', -- AI Interface name - !This comment is used for parsing!
desc = 'the shortName of the AI interface this AI needs',
},
{
key = 'interfaceVersion',
value = '0.1', -- AI Interface version - !This comment is used for parsing!
desc = 'the minimum version of the AI interface required by this AI',
},
}

return infos
</pre></code>

The file describes a number of attributes. Each attribute has a key, a value and a desc(ription). The key is the name of the attribute, the description tells you what the attribute is used for, and the value is what you will want to edit.

The shortName attribute is the name used for your AI internally. It's most logical to change this into to the same name you gave your AI class. (MyJavaAI.)

'version' tells the engine which version of your AI this is. If you're in the 0.1 folder, make this 0.1. Your AI should be located at AI/Skirmish/''shortName''/''version''/.

'classname' tells the interface which class is your AIFactory class. Take care that you use the fully qualified class name, or it won't work. In this example, this should be myjavaai.MyJavaAIFactory.

'name' describes your AI to the user. In this example, you might put 'A simple Java AI to learn about AI programming in Spring.'

'loadSupported' is rather self-explanatory. Since you have just started working on your AI, you may not get around to implementing loading support for some time, so it's best to put 'no,' for now.

'interfaceShortName' and 'interfaceversion' tell the engine about the interface your AI uses. Since MyJavaAI uses the same interface as the NullOOJavaAI, leave these as they are.

Finally, the last thing you should do is exporting your AI to SkirmishAI.jar. The way to do this varies depending on your Java editor.

=== Test your AI ===

After following all the above steps, you should be able to run your AI. Either use SpringLobby to start a new game and see if you can add your AI as a bot, or run ''spring.exe'' to see if you can start the script MyJavaAI Test.
Of course, since you haven't told the AI what to do, your starting unit(s) will sit there doing nothing.

== Getting your AI to Do Something ==

After getting your AI running, you will want to make it do something. Traditionally, the first thing to get your AI to is to build a solar plant, assuming you want it to play BA. If not, it is quite straightforward to build other units once you have the general idea.
You will need four things to get your AI to build a solar plant:
* A reference to the callback
* A reference to the commander (your starting unit in BA)
* A reference to the solar plant definition object
* To tell the commander to build the solar plant

However, before we go about building solar plants, first you should know about events. We will use these to get the required object references.

=== Events ===

Nearly everything that happens in the game is an event. When a unit is created, this is an event. Enemy spotted? Also an event. A player sends your AI a message? You got it, this is an event as well.

Every event is made known to your AI. Have a look at the <code>MyJavaAI</code> class again. <code>MyJavaAI</code> extends <code>AbstractOOA</code>. <code>AbstractOOAI</code> implements a number of methods like <code>unitCreated()</code>, <code>enemyEnterRadar()</code> and <code>message()</code>.
Sound familiar? The method <code>unitCreated(Unit unit, Unit builder)</code> is called every time a unit is created, and tells you the unit that was created and the unit that built it. Similarly, enemyEnterRadar(Unit enemy) and message(int player, String message) tell you about an enemy unit entering radar range and receiving a message from another player respectively.
There are many other events that all have corresponding methods. To have your AI respond to these events, simply override the method in your <code>MyJavaAI</code> class.
The return type of these methods is an integer. The return value can be used for debugging. 0 means that no errors occurred, while any other value is threated as an error. This system can be used for debugging, but is it much easier to implement proper logging.

In the sections below you will see an example of the use of these events.

=== Getting a reference to the callback ===

The callback is the object through which the AI communicates with the engine. All information that does not change the state of the engine can be retrieved through individual methods in the callback, and state changing commands (eg to units) will go through a single, specialized method, which is in the callback as well.
Getting a reference to the callback is easy.
First create a class field <code>OOAICallback callback</code> to put the reference in, then overwrite the method <code>init(int teamId, OOAICallback callback)</code>. The init method is called at the start of every game (right at the end of the countdown).
As you can see, all that you need to do is set the parameter value callback to the field callback:

<code><pre>
@Override
public int init(int teamId, OOAICallback callback)
{
this.callback = callback;
return 0;
}
</pre></code>

=== Getting a reference to the commander ===

In order to have your AI build a solar plant, the first thing you need is a reference to your commander. You first need an instance field 'Unit commander' to put the reference in, then we need to get the reference itself.
A UnitFinished event is triggered whenever a unit has been built. (This may sound similar to <code>unitCreated()</code>. For a quick explanation of the difference, see the FAQ below.)
At the start of the game, the engine will send a UnitFinished event for every starting unit. When playing BA, this means you will get a UnitFinished event for the commander. Therefore, the most straightforward way of finding the reference to the commander is overriding the <code>unitFinished()</code> method.

To get a reference to the commander, you need to check if the unit is indeed the command, and if so, assign the value of the unit parameter to the commander field:

<code><pre>
@Override
public int unitFinished(Unit unit)
{
if (unit.getDef().getName().equals("armcom"))
this.commander = unit;

return 0;
}
</pre></code>

=== Getting a reference to the solar plant definition ===

Every unit in Spring has a UnitDef (a 'unit defintion'). This object tells you all there is to know about the properties of the unit type, such as maximum speed, turn rate and what weapons it carries.
One way to get the reference to the definition of a solar plant is to use <code>callback.getUnitDefs()</code>. This will give you a list of all the available unit types in the game that is currently being played.
The name of the unit def we are looking for is 'armsolar', so we can just iterate through the list and find the one named armsolar, like this:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs();
UnitDef solarPlant = null;
for (UnitDef def : unitDefs)
if (def.getName().equals("armsolar"))
{
solarPlant = def;
break;
}
</pre></code>

=== Telling the commander to build the solar plant ===

Now, the only thing left to do is to tell the commander that we want it to build the solar plant, and where to place it. In short, we need to give the commander a build command.

We want to give this command only once at the first frame of the game. For this we can use the <code>update()</code> method, which is called at every frame of the game. All we need to do is overwrite the <code>update(int frame)</code> method and give the command if the frame is 1. This results in the following code:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
// give command here
}

return 0;
}
</pre></code>

Giving a command is straightforward. All we need to do is to create the appropriate command object and pass it through the callback to the engine.

EDIT: the command class is outdated and not included in the current oo wrapper. Commands are now given via the unit class. See: http://spring.abma.de/doc-Interface-JavaOO/com/springrts/ai/oo/clb/Unit.html

The command we need to tell commander to build a solar plant is a <code>BuildUnitAICommand</code>. This command takes a number of arguments:

; Unit unit : the unit we want to give to order to
; int groupId : the group we want to give the order to
; List<AICommand.Option> optionsList : a list addional options. See the values of AICommand.Option for details
; int timeOut : the number of frames after which the command times out
; UnitDef toBuildUnitDef : the UnitDef of the unit we want to build
; AIFloat3 buildPos : the position to build the unit at
; int facing : the direction the new unit should face

As you can see above, we can give a command to either a single unit or a group of units. In this example we only have a single unit. This means that unit should be a reference to our commander, and <code>groupId</code> should be -1.
To keep things simple, we will not use any options, set the timeout to a large number, and set facing to 0.
The value of <code>toBuildUnitDef</code> should be the object reference stored int UnitDef solarPlant.
That only leaves <code>buildPos</code>, for which we will just use the current position of our commander. This means that our <code>BuildUnitAICommand</code> looks like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);
}

return 0;
}
</pre></code>

Next, we should give the command to the engine. We do this through the method <code>callback.getEngine().handleCommand()</code>. This method takes three arguments: the id of the recipient of the command, a <code>commandID</code> and the command itself.
The command should be sent to the engine, and for now we will use a <code>commandID</code> of <code>-1</code>, as this is a feature which is not yet supported by spring (asynchronous command tracking).
Our code will look like this:

<code><pre>
@Override
public int update(int frame)
{
if (frame == 0)
{
AICommand command = new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000, solarPlant,
this.commander.getPos(), 0);

this.callback.getEngine().handleCommand(AICommandWrapper.COMMAND_TO_ID_ENGINE,
-1, command);
}

return 0;
}
</pre></code>

At this point you will want to see if your AI actually works. Export your code to ''Spring/AI/Skirmish/MyJavaAI/SkirmishAI.jar'' and start up a game. Your AI should now build a solar plant at its start position.

===Building a metal extractor===
Building a metal extractor is slightly more complicated. Assuming you're not on a metal map, you will need to find a suitable site to place the extractor. Generally, it's preferable to select a site closest to wherever your construction unit (commander) is located.

Modify your code that got a reference to the solar plant by making the following changes:

<code><pre>
List<UnitDef> unitDefs = this.callback.getUnitDefs(); UnitDef solarPlant = null; for (UnitDef def : unitDefs)

if (def.getName().equals("armsolar"))
{
solarPlant = def;
}
else if (def.getName().equals("armmex"))
{
metalExtractor=def;
}
</pre></code>

Again, you will need to create a Unitdef metalExtractor field by where you declared your solarPlant field.

Next, you need a method for determining the distance between two 3D coordinates (since Spring locations are three dimensional). A slightly modified version of a distance function is found below.

<code><pre>
public float calculateDistance(AIFloat3 a, AIFloat3 b)
{
float xDistance = a.x - b.x;
float yDistance = a.y - b.y;
float zDistance = a.z - b.z;
float totalDistanceSquared = xDistance*xDistance + yDistance*yDistance + zDistance*zDistance;
return totalDistanceSquared;
}
</pre></code>

The above code actually returns the distance squared, but it will work for our purposes. In your init function, you will want to add the following code above the return statement but below the line defining the callback:

<code><pre>
checkForMetal();
</pre></code>

This will call the following function you need to place in your code:

<code><pre>
public void checkForMetal()
{
Resource metal=Resource.getInstance(clb, 0);
availablemetalspots=clb.getMap().getResourceMapSpotsPositions(metal);
if(availablemetalspots.isEmpty())
{
sendTextMsg("This is a map with no metal spots");
metalmap=false;
}
else
{metalmap=true;
sendTextMsg("This is a map with metal spots. Listing Values...");
for (AIFloat3 metalspot : availablemetalspots) {
sendTextMsg("Metal Spot at X: "+metalspot.x + ", Y: "+metalspot.y +", Z: "+metalspot.z);
}
}
}
</pre></code>

For the above code to function properly, you will need to create a Boolean named metalmap and a List<AIFloat3> availablemetalspots. You will now have a function set up for calculating distance between two points, and a data structure holding a list of positions of metal spots. The next step is to tie these two together:

<code><pre>
public AIFloat3 closestMetalSpot(AIFloat3 unitposition)
{
AIFloat3 closestspot=null;
for (AIFloat3 metalspot : availablemetalspots) {
if (closestspot==null)
{
closestspot=metalspot;
}
else if(calculateDistance(metalspot, unitposition) < calculateDistance(closestspot, unitposition) && metalspot.hashCode()!=unitposition.hashCode())
{
closestspot=metalspot;
}
}
availablemetalspots.remove(closestspot);
return closestspot;

}
</pre></code>

The above function accepts an AIFloat3 containing the location of your construction unit (commander). It will then find the closest metal spot and return that location. The next step is to have your commander make use of this.

<code><pre>
if (frame == 600)
{
if(metalmap){ sendTextMsg("About to build mex at frame " + frame);
AIFloat3 closestspot=closestMetalSpot(commander.getPos());
BuildUnitAICommand command2=new BuildUnitAICommand(this.commander, -1,
new ArrayList<AICommand.Option>(), 10000,
metalExtractor,closestspot, 0);
handleEngineCommand(command2);}
}
</pre></code>

Place the above code in your update() method. When the frame count reaches 600, your commander will start to build a metal extractor at the closest metal spot. The extractor may not be right on top of where the metal spot appears to be, but you can mouse over the extractor to make sure it's drawing the metal properly.

== Frequently Asked Questions ==

'''Q:''' What is the difference between <code>unitCreated()</code> and <code>unitFinished()</code>?

'''A:''' The difference is that <code>unitCreated()</code> is called when construction of a unit starts, while <code>unitFinished()</code> when construction on the unit has been completed. Any number of things may happen in-between, including the unit under construction being destroyed, so it is important to remember this distinction.

'''Q:''' Do I have to copy and paste my jar file to the directory in Spring/AI/Skirmish/MyAI/0.1 each time I want to test my AI out?

'''A:''' Yes, but it is much easier if you automate the process. In Windows, a simple batch file can be created to move the files over for you. For example

<code><pre>
copy C:\Users\msm8bball\Documents\NetBeansProjects\MyAI\dist\MyAI.jar "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1"

del "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\SkirmishAI.jar"
rename "C:\Program Files (x86)\Spring\AI\Skirmish\MyAI\0.1\MyAI.jar" SkirmishAI.jar
</pre></code>

Modify the above code to match your computer's directories. Place it in a text file and save it as MoveAI.bat. This will create a batch file that you can double click and it will automatically move your AI to the proper location and rename it. You might wish to put a shortcut to this in your Start menu or taskbar.

'''Q:''' I have problems with the class-loader in my AI, any idea?

'''A:''' Each Java AI implementation is loaded by a separate class loader. This is used to load all the AI's class files and dependency libraries (in the ''jlib'' dir). Some libraries though, use the Thread contexts class loader, instead of the one of the current class. Therefore, if you want to load something from the AI's own class-path, make sure to let these libraries use the class-path of your AI classes, eg:
<code><pre>
ClassLoader myClassLoader = AIFactory.class.getClassLoader();
MySpecialUtil msp = new MySpecialUtil();
msp.setClassLoader(myClassLoader);
</pre></code>
Please do not set this class-loader on the thread with <code>Thread.currentThread().setContextClassLoader(myClassLoader)</code>, because all AI's are run in the same Java thread, and therefore this will cause problems.

== Links ==
* [[AIInterface:Java|Java AI Interface]]
* [http://spring.abma.de/doc-Interface-JavaOO/ Javadoc of the Java AI OO Wrapper] (generated daily from source by [[User:Abma|abma]])
* '''OUTDATED''' [http://springrts.com/phpbb/download/file.php?id=4970 Netbeans Java Skirmish AI Tutorial] (from [http://springrts.com/phpbb/viewtopic.php?p=448743#p448743 this forum thread])
* [http://modinfo.adune.nl/index.php?MOD=ba712 ModInfo] (contains a list of units and their short names)

[[Category: AI Dev]]

Keyboard

2011-01-09T02:52:10Z

Meriton: manually change keyboad bindings by editing uikeys

[[category:FAQ]]

==Default Keyboard Layout in Spring==

Note: this page is currently incomplete

[http://springrts.com/mediawiki/images/a/a5/KeyboardLayout.jpg Spring Keyboard Layout Image]

{|
|-
!Mouse Button 1 (left)
|Select unit/s (also perform selected order, eg: build selected building)
|-
!Mouse Button 2 (right)
|Default order. Depending on target: - Move. (drag mouse for line formation) - Attack / Repair / Reclaim. (drag to target an area) - Build incomplete building or unit. - Guard. - If an order has been manually selected/hotkeyed, click to cancel.
|-
!Scroll Wheel
|Zoom in/out
|-
!Mouse Button 3 (click scroll wheel)
|Move to point on minimap
 (Mouse 1 & 2 are used to select units and give orders on minimap)
|-
!L
|(Duplicates middle click functionality)
|-
!SHIFT + (Mouse 1 or 2)
| - Queue order. Queue as many as you like.
(shift+drag to queue a line of buildings) - Add unit/s to group
|-
!CTRL + Mouse 1
|Remove unit/s from group
|-
![ and ]
|Rotate building (first select something to build and then rotate)
|-
!A
|Attack (attack unit/ground)
|-
|-
!M
|Move
|-
!F
|Fight (as move, but units will stop to kill enemies along the way)
|-
!G
|Guard
|-
!P
|Patrol. (Moves back and forth between current position and patrol position)
|-
!S
|Stop
|-
!E
|Reclaim
|-
!R
|Repair
|-
!D
|D-Gun
|-
!X
|On/Off. (as the unit on/off button)
|-
!K
|Cloak on/off
|-
!CTRL + D
|Self Destruct
|-
!SHIFT + W
|Queue 'wait' command
|-
!W
|Stop waiting
|-
!CTRL + number (1-0)
|Assign group
|-
!number (1-0)
|Select group
|-
!Double Click
|Select all units of targetted type in view
|-
!CTRL + Z
|Select all units of selected type on map.
|-
!CTRL + A
|Select all units on map.
|-
!ALT + SHIFT (+ mouse click & drag)
|Build a rectangular area of buildings.
|-
!SHIFT (+ mouse click & drag)
|Build a line of buildings.
|-
!SHIFT + CTRL (+ mouse click & drag)
|Build a line of buildings with fixed angles of 90 degrees.
|-
!CTRL + SHIFT (+ mouse click)
|Build a circular area of buildings around some other building (must point on the building with mouse cursor).
|-
!TAB
|Zooms out to see the whole map.
|-
!F1
|Shows heightmap
|-
!F2
|Shows areas where you can build (if the building what you want to build is selected)
|-
!F3
|Goes to the latest spot of action (also goes to the latest markers)
|-
!F4
|Shows metalmap
|-
!F5
|Hides User Interface
|-
!CTRL+F5
|Changes to a cooler camera mode
|-
!F6
|Turns sounds off (currently a bug causes sounds be on when zoomed in the spot where sound comes from (for example an explosion))
|-
|colspan="2"| <h4>Multiplayer Communication</h4>
|-
!ENTER
|Chat
|-
!ALT + ENTER
|Allied chat
|-
!SHIFT + ENTER
|Spectator chat
|-
!CTRL + ENTER
|Return to global chat
|-
!` + Mouse Button 1
|Draw on map. (On a UK/US keyboard ` is to the key left of 1. The same functionality is mapped to the \ key)
|-
!` + Mouse Button 2
|Erase markers and drawings
|-
!` + Mouse Button 3
|Place marker
|-
!` + Double Click
|Place marker with annotation
|}

=== Changing bindings ===

Many keyboard bindings can be changed in springsettings.exe (hotkeys tab). In case that doesn't work, [http://springrts.com/phpbb/viewtopic.php?f=11&t=25043 this] forum thread might be helpful.

Keyboard

2011-01-08T17:20:31Z

Meriton: how to change bindings

Keyboard

2011-01-08T15:35:09Z

Meriton: referenced uikeys.txt

[[category:FAQ]]

==Default Keyboard Layout in Spring==

Note: this page is currently incomplete

[http://springrts.com/mediawiki/images/a/a5/KeyboardLayout.jpg Spring Keyboard Layout Image]

{|
|-
!Mouse Button 1 (left)
|Select unit/s (also perform selected order, eg: build selected building)
|-
!Mouse Button 2 (right)
|Default order. Depending on target: - Move. (drag mouse for line formation) - Attack / Repair / Reclaim. (drag to target an area) - Build incomplete building or unit. - Guard. - If an order has been manually selected/hotkeyed, click to cancel.
|-
!Scroll Wheel
|Zoom in/out
|-
!Mouse Button 3 (click scroll wheel)
|Move to point on minimap
 (Mouse 1 & 2 are used to select units and give orders on minimap)
|-
!L
|(Duplicates middle click functionality)
|-
!SHIFT + (Mouse 1 or 2)
| - Queue order. Queue as many as you like.
(shift+drag to queue a line of buildings) - Add unit/s to group
|-
!CTRL + Mouse 1
|Remove unit/s from group
|-
![ and ]
|Rotate building (first select something to build and then rotate)
|-
!A
|Attack (attack unit/ground)
|-
|-
!M
|Move
|-
!F
|Fight (as move, but units will stop to kill enemies along the way)
|-
!G
|Guard
|-
!P
|Patrol. (Moves back and forth between current position and patrol position)
|-
!S
|Stop
|-
!E
|Reclaim
|-
!R
|Repair
|-
!D
|D-Gun
|-
!X
|On/Off. (as the unit on/off button)
|-
!K
|Cloak on/off
|-
!CTRL + D
|Self Destruct
|-
!SHIFT + W
|Queue 'wait' command
|-
!W
|Stop waiting
|-
!CTRL + number (1-0)
|Assign group
|-
!number (1-0)
|Select group
|-
!Double Click
|Select all units of targetted type in view
|-
!CTRL + Z
|Select all units of selected type on map.
|-
!CTRL + A
|Select all units on map.
|-
!ALT + SHIFT (+ mouse click & drag)
|Build a rectangular area of buildings.
|-
!SHIFT (+ mouse click & drag)
|Build a line of buildings.
|-
!SHIFT + CTRL (+ mouse click & drag)
|Build a line of buildings with fixed angles of 90 degrees.
|-
!CTRL + SHIFT (+ mouse click)
|Build a circular area of buildings around some other building (must point on the building with mouse cursor).
|-
!TAB
|Zooms out to see the whole map.
|-
!F1
|Shows heightmap
|-
!F2
|Shows areas where you can build (if the building what you want to build is selected)
|-
!F3
|Goes to the latest spot of action (also goes to the latest markers)
|-
!F4
|Shows metalmap
|-
!F5
|Hides User Interface
|-
!CTRL+F5
|Changes to a cooler camera mode
|-
!F6
|Turns sounds off (currently a bug causes sounds be on when zoomed in the spot where sound comes from (for example an explosion))
|-
|colspan="2"| <h4>Multiplayer Communication</h4>
|-
!ENTER
|Chat
|-
!ALT + ENTER
|Allied chat
|-
!SHIFT + ENTER
|Spectator chat
|-
!CTRL + ENTER
|Return to global chat
|-
!` + Mouse Button 1
|Draw on map. (On a UK/US keyboard ` is to the key left of 1. The same functionality is mapped to the \ key)
|-
!` + Mouse Button 2
|Erase markers and drawings
|-
!` + Mouse Button 3
|Place marker
|-
!` + Double Click
|Place marker with annotation
|}

=== More ===

The keyboad binding configuration is stored in the file uikeys.txt in the Spring installation directory. That file also contains a more complete list of default keyboad bindings.