AI:Development:Lang:Java

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 out.

Setting up a Java Project

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

Importing the interface libraries

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 libraries vecmath.jar, located in the 'jlib' subfolder, as well as the various libraries int 'jlib\jna'. Optionally, you can attach the file 'AIInterface-src.jar' as source to the AIInterface.jar file.

Your project should now contain the following libraries:

• Spring\AI\Interfaces\Java\[version]\AIInterface.jar
• Spring\AI\Interfaces\Java\[version]\jlib\vecmath.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\freebsd-amd64.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\freebsd-i386.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\jna.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\linux-amd64.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\linux-i386.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\mac-darwin.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\win32-amd64.jar
• Spring\AI\Interfaces\Java\[version]\jlib\jna\win32-x86.jar

Creating the required classes

The next step is to create your AI's main class. Create a new class, named MyJavaAI (or whatever you would like your AI to be called.). MyJavaAI should extend com.clan_sy.spring.ai.oo.AbstractOOAI. After that you need another class, named MyJavaAIFactory. This class should extend com.clan_sy.spring.ai.oo.OOAIFactory. The class MyJavaAIFactory needs 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().

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

Now you have to create folder for your AI. It is easiest to go to the directory 'Spring/AI/Skirmish' and make a copy of the folder NullOOJavaAI. Rename the copy to MyJavaAI. (Or you might want to give it a more original name.)

Telling the Engine about your AI

The MyJavaAI folder 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 currently 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:

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.clan_sy.spring.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

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.

'classname' tells the interface which class is your AIFactory class. In this example, this should be 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.'

'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

Then, 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.