Spring - User contributions [en]

Gamedev:PublicRepos

2016-06-21T07:06:46Z

Bla: /* Known Repos */

==What Is This?==
This is a small collection of publicly known and readable code repositories for established Spring games. The intention being to provide a wealth of examples to all game developers from noob to pro.

Most of these repositories can be downloaded with one of the [[Rapid_Tags]].

== Known Repos ==
[https://github.com/KingRaptor/air-raid-spring Air Raid]

[http://imolarpg.dyndns.org/trac/balatest/browser/trunk/ Balanced Annihilation]

[https://github.com/spring-archive/basically-ota BOTA]

[https://github.com/spring-archive/conflictterra Conflict Terra]

[http://www.petro.darkstars.co.uk/damned/ Damned]

[https://github.com/EvolutionRTS/Evolution-RTS Evolution RTS]

[https://github.com/SpringCabal/Gravitas Gravitas]

[https://github.com/n3wm1nd/TA Tech Annihilation]

[https://github.com/imperialwinter/swiw.sdd Imperial Winter]

[https://bitbucket.org/PicassoCT/journeywar Journeywar]

[https://github.com/jk3064?tab=repositories jK]
* [[Chili]]
* [[LUPS]]
* Custom-Unit-Shader-Framework
* [[Mapdev:Main#Blueprint | Map-Blueprint]]

[https://github.com/David-Becker/mods KDR_11k]
* Cuberors' Finest
* CvC
* Doserz
* Fibre
* GINTA
* Gun Wings Test
* Light Side of Spring
* MicroModules
* Pong

[https://github.com/SpringMCLegacy/SpringMCLegacy MechCommander: Legacy]

[https://github.com/spring1944/spring1944 Spring: 1944]

[https://github.com/spring-archive/springtanks Spring Tanks]

[https://github.com/spring-archive/springtutorialgame/tree/master/SpringTutorialGame.sdd Spring Tutorial Game]

[https://github.com/KingRaptor/THIS THIS]

[http://code.google.com/p/xta-springrts/ XTA]

[https://github.com/ZeroK-RTS/Zero-K/ Zero-K]

[[Category:Game Dev]]
[[Category:Download Systems]]

Kernel Panic

2014-05-15T16:06:34Z

Bla: /* Playing Guide for System: */

http://img390.imageshack.us/img390/6289/kernelhd0.png

==Overview:==

''For the latest news and/or assistance, try the [http://springrts.com/phpbb/viewforum.php?f=43'''KP forum'''] or go to #kp when you log onto the lobby.''

'''Kernel Panic''' is a game about computers. Systems, Hackers and Networks wage war in a matrix of DOOM! The only constraints are time and space; unlike other real time strategy games, no resource economy exists in KP.

All units are free in this game, every factory built will be spamming units at all times. You can build more factories, but only on pre-defined areas (geothermal vents). All that remains is pure strategy and tactics.

KP makes for a frantically fast-paced, action-oriented game, with a very unique graphical style.

----

==Download links:==

Current Version of Kernel Panic is 4.6

* <u>Newcomers:</u>
** If you run '''Windows''' (2000,XP,Vista,7):
*** Here you can get a complete installer:
*** http://springfiles.com/spring/game-installers/kernel-panic-installer
*** Use it to install both Spring and Kernel Panic in one go.
*** Then use the shortcuts created in your Start Menu or Desktop.
** If you run '''Linux''':
*** Read the [[SetupGuide]] how to install the Spring engine on Linux systems
*** Get and unzip that file: http://springfiles.com/spring/game-installers/kernel-panic-zip
*** Put the content of /games/ into ~/.spring/games
*** Put the content of /maps/ into ~/.spring/maps
*** Discard the rest.
*** Run Spring directly, a greenish menu should pop up.
*** Click skirmish, duel, easy, run.
*** For multiplayer or advanced options, run SpringLobby

* <u>Experienced Users:</u>
** If you have already the Spring engine (or prefer to install it yourself): Here you can get a zip with the mod file, the maps, and a tiny exe for single player frontend. Unzip into your Spring root folder: http://springfiles.com/spring/game-installers/kernel-panic-zip
** If you are certain you have all the maps and just need a quick link to the mod file itself: http://springfiles.com/spring/games/kernel-panic-mod

----

==Media:==

===Youtube Videos:===

[http://youtube.com/watch?v=doF7owZ0blk&fmt=18 http://i.ytimg.com/vi/doF7owZ0blk/default.jpg]
[http://youtube.com/watch?v=Ug1c19yaZac http://i.ytimg.com/vi/Ug1c19yaZac/default.jpg] [http://youtube.com/watch?v=GAZQhRlt5bU http://i.ytimg.com/vi/GAZQhRlt5bU/default.jpg]
[http://www.youtube.com/watch?v=3q48ys5hFtI&fmt=18 http://i.ytimg.com/vi/3q48ys5hFtI/default.jpg]

----
===Still shots:===

[http://img228.imageshack.us/img228/6554/kernelpanicdirectmemoryoe1.jpg http://img228.imageshack.us/img228/6554/kernelpanicdirectmemoryoe1.th.jpg] [http://img231.imageshack.us/img231/1598/kernelpanicdirectmemoryob8.jpg http://img231.imageshack.us/img231/1598/kernelpanicdirectmemoryob8.th.jpg] [http://img223.imageshack.us/img223/3379/kernelpanicmajormadnesswn6.jpg http://img223.imageshack.us/img223/3379/kernelpanicmajormadnesswn6.th.jpg] [http://img223.imageshack.us/img223/3757/kernelpanicspeedballs16tm1.jpg http://img223.imageshack.us/img223/3757/kernelpanicspeedballs16tm1.th.jpg] [http://img231.imageshack.us/img231/5962/kernelpanickdr8z1scr6nn7.jpg http://img231.imageshack.us/img231/5962/kernelpanickdr8z1scr6nn7.th.jpg] [http://img143.imageshack.us/img143/2093/kernelpanicdigitaldividhq1.jpg http://img143.imageshack.us/img143/2093/kernelpanicdigitaldividhq1.th.jpg]
----

==License:==
Extracted from the <code>Kernel_Panic_readme.txt</code> file:

<pre>
========--------------------------------------------
License:
--------
- The content of the /games/Kernel*.sd7 is Public Domain, save:
/LuaUI/Widgets/kp_buildbar.lua
/LuaRules/Gadgets/autohold.lua
/LuaRules/Gadgets/Burrow.lua
/LuaRules/Gadgets/game_spawn.lua
which are GPL, taken from http://www.caspring.org or http://springrts.com
- The maps Marble Madness and Direct Memory Access are Public Domain
- The maps Major Madness and Speed Balls 16 Way status are unknown
- The maps Central Hub, Corrupted Core, Dual Core, Quad Core were initially CC BY-NC-SA.
Then the author removed the CC cause ( http://cpc.cx/4u3 )
- The Spring engine is GPL, available from http://spring.clan-sy.com
</pre>

== AIs and Game Modes:==
You can read a description of what they do here: http://www.springinfo.info/?p=681
----
==Units and Buildings:==

===System units:===

<table><td>http://img256.imageshack.us/img256/1126/96x96kernelzu8.png</td><td>'''The Kernel:''' You start with one of these. It can build all mobile units in the game. Has rapid auto-heal and lots of health.</td></table>

<table><td>http://img209.imageshack.us/img209/1599/96x96socketnl5.png</td><td>'''The Socket:''' The socket is a factory which can only be built on a geothermal vent. It can solely build bits, and slower than the kernel can. It autoheals, and has a decent amount of health.</td></table>

<table><td>http://img88.imageshack.us/img88/9685/96x96terminalab6.png</td><td>'''The Terminal:'''(only available in Division Zero) This is a new structure that gets placed on geovents. It can dispatch a nuclear bomber once every 90 seconds that will deal about 16000 damage to a large target area, i.e. it destroys everything except factories. It does much less damage to the kernel and hole. The bomber can strike any position on the map, there is no defense.</td></table>

<table><td>http://img267.imageshack.us/img267/3489/96x96assemblerdt2.png</td><td>'''The Assembler:''' The assembler is a construction unit. It can build sockets, but it cannot assist-build. Slow, little health. Equipped with a radar to detect mines and other cloacked units.</td></table>

<table><td>http://img214.imageshack.us/img214/5237/96x96bitsn1.png</td><td>'''The Bit:''' Your basic attacking unit. Cheap, fast, small, not very much health. Is armed with a SPARCling laser. Can be built by a kernel or a socket.</td></table>

<table><td>http://img214.imageshack.us/img214/1451/96x96byteum3.png</td><td>'''The Byte:''' A large, strong, and slow attacking unit. Can holds it's own against many bits, as it has lots of health and a powerful gun. More armored when closed. Can plow through bad blocks. The byte has an alternate firing mode, the mine launcher, which throws 5 mines at the cost of much health.</td></table>

<table><td>http://img256.imageshack.us/img256/9260/96x96pointerfk5.png</td><td>'''The Pointer:''' An artillery unit. Its normal shot is not so useful against moving units, but can kill kernels and sockets pretty quickly. Is slow and has little health, so it needs protection. The pointer has an alternate firing mode, the NX Flag, which set a wide area ablaze for a minute, causing constant damage to all units, or buildings within it's range.</td></table>

----

===Hacker units:===
<table><td>http://img222.imageshack.us/img222/2233/96x96newholelowvp3.png</td><td>'''Security Hole:''' The Hacker kernel equivalent.</td></table>

<table><td>http://img220.imageshack.us/img220/2663/96x96windowxr7.png</td><td>'''Window:''' The Hacker socket equivalent.</td></table>

<table><td>http://img90.imageshack.us/img90/1047/96x96obeliskze5.png</td><td>'''Obelisk:''' This building is a stationary artillery weapon, it can fire an infection shot every 40 seconds (the obelisk has a pink fire on top when it's ready to shoot) that will cover a large area in poison. The poison does a bit of damage (about 1000) and turns any enemy that dies inside the cloud into a Virus. The weapon's range is fairly limited. Best used against stationnary herds of Bits/Bugs.</td></table>

<table><td>http://img222.imageshack.us/img222/7033/96x96newtrojanlt6.png</td><td>'''Trojan:''' This unit is your constructor as well as radar platform (needed for detecting mines and cloaked units), just like the assembler. It builds all the same stuff as the assembler, except it has the window instead of the socket and the obelisk instead of the terminal.</td></table>

<table><td>http://img88.imageshack.us/img88/3961/96x96viruslg6.png</td><td>'''Virus:''' A crappy little swarm unit. It cannot be built but is produced when killing enemy units with certain weapons. Namely, the Virus, the Worm, and the Obelisk.</td></table>

<table><td>http://img230.imageshack.us/img230/1895/96x96newbugjw5.png</td><td>'''Bug:''' The Hacker spam unit. The Bug is weaker than the Bit but can sense movement outside of its LOS. It has a stronger weapon and more range but cannot shoot at things behind it or through friendly units and won't take much damage before dying. The mine ability of the old bug has been removed. Instead it can now morph into the Exploit with the deploy button, or the bombard button.</td></table>

<table><td>http://img222.imageshack.us/img222/2277/96x96exploitjb7.png</td><td>'''Exploit:''' This is the new name for the bug cannon. It's a building the Bug morphs into with the deploy or bombard command. The Exploit is a stationary artillery emplacement that does more damage the further the target is away. Even more frail than the Bug, so don't let any foe come near.</td></table>

<table><td>http://img220.imageshack.us/img220/3277/96x96newwormpv5.png</td><td>'''Worm:''' The worm is a sneaky assassin, travelling cloacked, then surfacing only to kill many bits at once with its large area of effect weapon, which turn any slain units into virus. The worm large splash damage will damage your own units. However, it does practicaly no damage against other worms or virus. When cloacked, the worm does not automatically attack, you have to give attack orders manually. If you'd rather have your worms auto-attack even when cloacked, set autohold to off. The autohold setting of new worms is inherited from the Security Hole.</td></table>

<table><td>http://img86.imageshack.us/img86/6420/96x96dosxp1.png</td><td>'''Denial of Service:''' Not an artillery, but close: fire a beam that stun units. For bigger targets it'll take longer to stun them so perform a DDoS (use multiple) to stun them fast. Once the DoS stops firing the target will quickly unfreeze. It moves faster than the pointer but causes a particle trail that can be seen from far away.</td></table>

----

===Network units:===
The network faction is built around mobility, its small factories (Ports) don't produce units openly but instead increment a virtual counter (the Buffer). Packets in the Buffer can be materialized at any teleporter unit (currently that means the Port and the Connection), it's also possible to dematerialize the Packets back into the Buffer by making them enter a teleport.

<table><td>http://img146.imageshack.us/img146/2470/96x96carrierll0.png</td><td>'''Carrier:''' The base building, like a Kernel or Security Hole.</td></table>

<table><td>http://img292.imageshack.us/img292/6262/96x96portto5.png</td><td>'''Port:''' The production building. It puts Packets into the Buffer, to materialize them select the Dispatch command. Dispatch will send 12 Packets if available, you can hold ALT when giving the order to make the Port dispatch until the Buffer is empty.</td></table>

<table><td>http://img167.imageshack.us/img167/5972/96x96firewallqj4.png</td><td>'''Firewall:''' This building can cover units (affects friendly units in a certain radius around the target location) in a protective shield for 20 seconds. The shield halves all damage the unit receives and throws the other half back at the attacker.</td></table>

<table><td>http://img30.imageshack.us/img30/9761/96x96gateway.png</td><td>'''Gateway:''' The constructor. It is lightly armed to help against enemy raids.</td></table>

<table><td>http://img233.imageshack.us/img233/3282/96x96packetnn1.png</td><td>'''Packet:''' The basic light spam unit, it's weaker in combat than both competitors but much faster.</td></table>

<table><td>http://img233.imageshack.us/img233/7595/96x96connectionfz5.png</td><td>'''Connection:''' Mostly a mobile teleporter (i.e. can dispatch Packets and let them enter like a Port). The Connection has decent armor and an arc beam that can do a lot of damage to single targets and has good range. It can defeat most large units one on one but engaging Bytes will probably result in pointer fire which the Connection cannot withstand and the arc beam is not optimal for engaging swarms.</td></table>

<table><td>http://img233.imageshack.us/img233/598/96x96flowml4.png</td><td>'''Flow:''' An air unit. The Flow moves fairly slowly but can of course cross any terrain. It's equipped to attack light targets (spam units and fire support) but it's highly vulnerable to return fire. If you want to use them in open combat give them a meatshield and hope the enemy doesn't field long range units, Pointers, DoSes and Connections make short work of Flows if they hit.</td></table>

----

===All side Units:===

<table><td>http://img266.imageshack.us/img266/7149/96x96badblockee7.png</td><td>'''The Bad Block:''' A tiny wall, built by Assembler/Trojan/Gateway. Blocks small units movement. Do not block shots however. Easily removed by the Debug or simply crushing them with a Byte or Connection.</td></table>

<table><td>http://img516.imageshack.us/img516/3648/96x96minelk9.png</td><td>'''The Logic Bomb:''' A mine that can be built by the Assembler/Trojan/Gateway. And also launched by Bytes since Div0 2.2. It takes out Bits & Bugs in a single blow, has a decent damage radius, and doesn't chain explode. Use with care, as the blast hurts your own units too. Limited to 32.</td></table>

<table><td>http://img37.imageshack.us/img37/9901/96x96mineblaster.png</td><td>'''The Debug:''' An easy way to clear an area of all mines and walls, this is a one shot weapon built by the Assembler/Trojan/Gateway.</td></table>

----

==Playing Guide for System:==


Playing Kernel Panic is fairly simple and quickly learned, but can be hard to master and can be very complex. It is recommended that beginners start with play the System faction, as they can be considered the least "gimmicky" of the factions.


One rather effective general strategy for a duel on small maps is to send three to five bits to destroy your enemy's early game units, and, to a lesser degree, for scouting purposes. This is most effective if they started with construction units, as this will likely cripple their plans for an early expansion, and gives you a slight head start. After the initial attack, if your scouting shows that your enemy started with offensive units, build a byte for defense, and place it between your Kernel and the hill. After that, build an assembler and use it to build a socket on one the three closest building locations, which should automatically start producing bits. After this, you should order your assembler to build more sockets on free spots close to it. It is crucial that all sockets' rally points are below them, as bits turning inside a socket will stall production until it is able to exit the factory. It is sometimes wise to repeat the prior process with one or two other assemblers. After this is done, construct about ten bits from your factor, and set your kernel to alternate between building bytes and pointers.


What units you build at your kernel, and what you use them for, is an important factor in winning. As buildings can't be resumed, sending in groups of bits to kill construction units creating buildings can be very effective at stopping expansion attempts. Building too many pointers, will result in them being destroyed by connections, bits and especially worms, due to their stealth. Also, bytes are easily destroyer by and pointers, and exploits. A good general purpose ratio seems to be to queue one byte and one pointer, but this will need adapting as the game develops, and depending on the enemy's play style.

Scouting is important too, as many enemies will leave their factories undefended, and knowing their build, and general unit use can help you in adapting the units you use to better fight them. Note that the Network can instantly spawn packets at any of their ports, or connections with their buffer system, meaning that all their factories should be considered defended. Single bits can be used to scout to find the enemy's current expansion attempts.

When attacking a Byte or Connection with bits, it is important to overwhelm it with large numbers of bits. For bytes, try to exploit a byte's blind spot directly under it, by moving bits into that area. If your byte is under attack, moving it backwards to keep the attacking units in it's shooting arc can help repel the attack. It is not recommended to engage a worm with bits, as it's attack will convert your bits to viruses on the worm's owner's side.


On Marble Madness, there are two main ways paths to victory. The simplest one is to control the hill and use pointers stationed on the hill to destroy the enemy's factories, and kernel. Gaining control of the hilltop will likely not be without resistance, because it requires a decent amount of time for units to reach the top of the hill, meaning most units involved will be spam units from your factories on it, and the fact that it will likely be highly contended. However, if you control it, you have a large advantage over the enemy as you can shell your opponents home base with ease. The other way is around the hill, which can be very effective if you control terrain you can use pointers to great effect. In both strategies, using pointers is the crucial factor. While they are hard to use correctly, they are game-winners as they destroy home bases and enemy units with ease.

----

==Credits:==
- Original concept by Boirunner<br>
- About all the work done by KDR_11k<br>
- Sounds by Noruas<br>
- Minor edits by zwzsg<br>
- Maps by Boirunner, Runecrafter, zwzsg, and TradeMark<br>
- Some LUA interface upgrade based of jK and trepan code<br>

----
Back to [[Games]]
[[Category:Games]]

AI:Development:Lang:Java

2014-05-15T16:03:06Z

Bla: /* 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 July 2012) 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]]

AI:Development:Lang:Java

2014-05-15T16:02:21Z

Bla: /* 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 July 2012) 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 not 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]]