Spring RTS Engine

Hoijui, are you sure that svn path is correct? I cannot seem to checkout that repository. Though it could very well be that I'm doing something wrong.
I'm trying to checkout the repository to a new folder on my system, using TortoiseSVN on windows. It gives me an error saying, 'URL 'https://taspring.clan-sy.com/svn/spring/caiinterface' doesn't exist.'

i dont know how i got to that...
this should be the correct one:
https://spring.clan-sy.com/svn/spring/b ... iinterface

with this installer, you should get everythign you need for testing the java stuff:
http://planetspring.free.fr/spring/inst ... vn7180.exe
debug symbols, if you want:
http://planetspring.free.fr/spring/debu ... g_R7180.7z

just run spring.exe, and choose the NullOOJavaAI.
i dont have time right now to explain how it works, but it should work as long as you have java.exe in your path. if not, report back.
more info later

Just want to say that I got the NullOOJavaAI to work on my machine. The OOAI interface interface looks good, although it would be great if there was some Javadoc present to spice things up.
If you want to attract new AI developers, as I believe was the idea behind creating the different language bindings, documentation is a good way to get people started.

Main things I would be interested in:

- exactly when / on what event is each method called? I can make a good guess for the 'unitDestroyed' method, but the meaning of for example 'onRelease()' or 'seismicPing()' is lost to me. What is a release event? Is a seismic ping some kind of earthquake event in game, or a reaction to a server ping? I have no idea.
- what do the different return values mean? The return code 0 is commented, saying it means the method exited successfully. But what would I return to indicate some kind of error?

I am new to Spring programming, and I'm hoping to build my first AI. However, I have been working to adapt a C++ Spring AI for a while now, and I have also seen a tiny bit of the engine code. I hope that means I'm in a position to offer a useful perspective.

cool LoidThanead
am happy to hear someone finally messes around with it. thanks.

yeah, about documentation.. you are right :/
it would make no sense, to document the java interface, but the C interface had to be documented. then i could wrap the documentation automatically, and it could be done for all other languages aswell then.
There are few events (i think, about 20), and they are the most vital part of the interface, and the first thing an AI dev comes in contact with. so i should start there i guess. with the rest...
there are already quite a few more Commands, and the callback functions are uncountable. there is one function for each unitDef value eg. (this alone are a few hundred functions i think). we may never see all this commented.
you are right of course, docu is important.. thanks!

about your specific questions:
there is no OnRelease event. it is only release, which is the opposite of the init event. this event is transmitted when the game ends, so you will call the destructor of your AI instance when receiving it, eg (in java, you may not need this event at all).
a seismic ping occurs, when a seismic detector encounters a unit. there is a seismic detector in BA eg, it is meant for detecting units that are radar invisible and/or clocked. seismic detection means, sensing small earthquakes, cuased by moving units.

every return value that is not 0, indicates an error. the engine does not care about the actual value, but it may be written to a config file, so you may use different return values!=0 for reporting different errors. you can also return -1 all the time. its the same paradigm like with application return values.

if you actually knew these things already, then forget what i just wrote. i still can use this text for the docu

Thanks, hoijui,

I typed the function names off the top of my head. I did indeed mean 'release().' And no, I did not know the things you mentioned, though I guessed the meaning of 'release,' having seen a similar function in the C++ AI.

The reason I mention Javadoc is because most Java editors can integrate this readily into the editing environment, which would make working with the interface much easier. (At least, the one I use does.)
If, as you say, there a hundreds of similar functions, just for different units, would it not make sense to only document the group of functions as a whole? I have no idea why you would need to have a separate function for each UnitDef value, so this example is completely unrelated:

getHeight()
getWidth()
getDepth()
[more silly functions to do with measurements...]

You could just say 'get object dimension,' and trust the programmer to figure out that 'getHeight()' retreives the height dimension.
Otherwise, write one generic description and do a lot of copy pasting? Just a thought.
I wouldn't say it makes no sense to document the interface in all the different languages. However, I agree that just documenting the C interface and then automatically generating the documentation for the other languages is a much, much better idea than doing it all by hand. Especially because it would never get done if we were to ask that.


Your Java interface has my great interest. Since the first time I came in contact with Spring, I've been toying with the idea of writing my own AI. However, I could never find the time (or motivation) to learn C++.
Now with a Java interface available, I would like to mess around some more. I've tried to get my own code running instead of the NullOOJavaAI, but so far no luck. As far as I can see, not all the interface source code is in the repository yet, so I've been using the jar files that came with the installer. I made my own project containing the ai factory and a copy of the NullOOJavaAI (printing just one extra message so that I can see it's actually running my code) but the game crashes without any error.

What you say is basically, that not all functions need documentation, or most maybe would not need any.
But even with UnitDef.getHeight(), it could be usefull maybe... which height of the unit is it (eg, is it the hitvolume height or the visible height, ...)? is it possible that the unit changes its height?
well, it does not really make sense to discuss about that
we agree that docu would be good, it would have to be a lot, and it would be best done at the C interface. wrapping the documentation should be trivial. and of course.. i know what benefits a javadoc has, i am a Java Dev too, in the first place. most other languages have a similar mechanism (Doxygen for C/C++ eg).
if you look at UnitDef, you will most likely find a lot of properties which you dont know what they mean (neither do i) and it is quite hard to find anything documented about them in the engines code.

Nice that you fiddle around with NullOOJavaAI
All code that is needed should be on SVN. The latest installer even comes with the sources of the Java Interface and the Java AIs packaged in a jar (in their jlib dirs). though, i first have to create it with the buildbot.
will post again in a few minutes.
as most Java code of the interface is generated, it is not on SVN, but you have to generate it yourself. this is done automatically when you run Scons or CMake, or you can do it manually with the script:
AI/Interfaces/Java/bin/java_generateWrappers.(sh|bat)

about the crash:
- if there is a stacktrace in infolog.txt, you can go to channel #buildserv in the lobby, upload your infolog.txt somewhere, and then issue: - have a look at the Java Interfaces log file under:
AI/Interface/0.1/log.txt
- have a look at your own AIs logfile

if all this gives no hints, then you may ask again here, or you may need to debug. i guess you have not yet debugged a native application... we will tlak about this only if needed

have you adjusted all the values in your AIInfo.lua?

installer: http://planetspring.free.fr/spring/inst ... vn7213.exe
debug-symbols:
http://planetspring.free.fr/spring/debu ... g_R7205.7z

.. do not ask me why they are of dirrent revisions. they resulted from a single build run.

hoijui wrote:.. do not ask me why they are of dirrent revisions. they resulted from a single build run.

The installer name is built by the make_test_installer.sh script, which uses svnversion to retrieve the latest version the current repository has been updated to.
Alll the other names are built by BuildServ which uses svn info to get the latest "effective revision" (i.e., the last one for which current repository has been changed). This is useful to prevent multiple uploads of the same files when nothing has changed in a branch for instance.

In your case, I guess r7213 was the latest SVN revision, and r7205 was the latest revision containing changes for the caiinterface branch.

thanks
yeah, it is how you said.
well... i guess that is because of the way SVN works (trunk and branches are the same repos, just different dirs), but logically, to me, 7205 is the latest real revision of the branch. this confused me.

if you have not come around this site, you may want to have a look at it:
http://spring.clan-sy.com/wiki/AIs
(Wiki page for devs about the AI interface in spring, already explaining the new interface stuff)

again, please tell me what is unclear, or change things yourself.

What does the phase, "[wrappers] are compiled directly into the AI library" mean? I suppose it means that the additional functionality is a seperate library that will need to be included/imported into the AI library?

As for the interface itself, I managed to run my own code. Still not sure what exactly I did wrong. It worked after I copied to NullOOJavaAI and simply modified class and package names to suit my own style.
Even though I couldn't find the mistake, the Java Interface log file was a big help while searching. It said it could not find the appropriate classes, even though I'm quite sure that I included them in the jar file, and put the right class name in the AIinfo.lua file.

I did get some odd behaviour when running Java code that should have thrown a nullpointer exception (as I discovered eventually).
There was no indication of an error of any kind, neither an error pop-up nor anything in any log file. Rather, the AI seemed to simply stop at the faulty line of code (not executing anything below the line), then just start over from the top at the next call to update().
Could it be the thrown exception is lost somewhere?


Since I got the code running, right now I'm working on some padding to the bare interface. I hope to build something of a framework around the interface that allows an AI to be more modular by providing interfaces and default implementations for different components. I just finished an EconomyManager that monitors resource levels, usage, income and such (simply by using the methods of the Economy object I get from the callback), but also lets component register listeners and be notified when resource levels etc. reach specified values.
In the end, I hope to have a framework that lets the developer worry about the big picture, or about specific parts in detail. This might even make an interesting wrapper for the Java AI?
Though I suppose any discussion about further work on my AI shouldn't go in this thread, though I can still give feedback on the interface itself, should I run into anything that's worth mentioning.

LoidThanead wrote:What does the phase, "[wrappers] are compiled directly into the AI library" mean? I suppose it means that the additional functionality is a seperate library that will need to be included/imported into the AI library?

That is actually up to the Interface/Wrapper Dev, or to the AI dev.
For the LegacyCpp Wrapper, the Wrapper files are handled as if they were source files of the AI itsself, and compiled like the AI specific files to .o files, and then to a .so or .dll. So they are comiled once for each legacy Cpp AI. But it would also be possible to compile them just once, into a static library (.a) and then link this library into each legacy Cpp AI .dll (would save some compile time). As it is now, we would need two versions of the .a, one with, and one without creg support.
in Java, a wrapper would possibly be shipped as a jar to each AI that uses it, or as lots of class files into the individual ai.jar's.
does not make a difference, really.
But this made me think about a possible problem:
If we have two (Java) AIs using the same library, lets say apache-commons. And one of the AIs needs version 3, the otherone needs version 4 to run properly. As it works now, The Java interface uses only a single JVM instance, with a single global classpath, where it collects all the libraries of the interface and all AIs used in the current game (thier ai.jar and jlib/*.jar files). Therefore, either the classes of apache-commons v3 or v4 are loaded, and one of the AIs is doomed to fail.
I guess this is solvable by having a hirarchical classpath -> one child ClassLoader for each AI. I put it on my todo list.

LoidThanead wrote: ... the Java Interface log file was a big help while searching. It said it could not find the appropriate classes, even though I'm quite sure that I included them in the jar file.

Have you checked if your jar was included in the classpath?
the Java Interface log file should contian the classpath.

LoidThanead wrote:Could it be the thrown exception is lost somewhere?

I guess the exception cuases the current event (eg Update or UnitDied) to return an error code to spring (any value != 0). Spring does not yet do anything special when this happens, so yeah.. could well be that it does not get logged anywhere. Though.. i don´t think it would be good if spring would log that.. you know, the infolog containing an update event log entry for each frame...
But.. it is not really optimal as it is now, of course. Maybe i could catch the exception in Java, print it to the Java AI Interface log if logging is set to fine (the default with a debug build), and just throw the same exception again? then again, it would possibly be better to have a solution in spring itsself. Maybe only log an error once for each event per AI (eg, log only the first fail of event Update on AI-X in infolog.txt). Suggestions welcome.

LoidThanead wrote:This might even make an interesting wrapper for the Java AI?

Yeah, sounds like a good candidate for a wrapper. Cool stuff that!

LoidThanead wrote: Though I suppose any discussion about further work on my AI shouldn't go in this thread, though I can still give feedback on the interface itself, should I run into anything that's worth mentioning.

Yeah, do it.
As i just saw, the Wrappers do not yet have their own pages, like the AI Interfaces and the Skirmish AIs. I will do the one for the legacy Cpp wrapper, and then you can do the one for your wrapper aswell if you want.
(one more thing on my todo list)

as it looks right now, i may not have much time the next few days to work on spring (yeah, real life, finally!!!!). but that should not be more then a week.

LoidThanead, i want to stress this again:
you are the first, and possibly only one that works with this system right now. The class diagram of the callback is kind of a fast hack of mine, and now is the best time to change it. And as you work with exactly this, you will soon have a better overview of it then i have, and see where it should be changed. So please report back thigns you would want changed, like:

• methods moved from one class to an other
• methods renamed
• classes renamed
• classes splitt into multiple classes or merged together
• changing certain things to make it possibe to implement a common interface (eg. Resources of UnitDef and Resources of WeaponDef)

If you miss some functionality, this is not as urgent right now. Adding functionality will always need change anyway, so it does not matter if this change occurs now or later, when the interface is more widely used already.

hoijui wrote:Have you checked if your jar was included in the classpath?
the Java Interface log file should contian the classpath.

I simply replaced the existing ai.jar with my own. Since the old one worked, if I replace it it should already be included, right?


As for the exception handling, from an AI developer's point of view, the main issue is that the exception is recorded somewhere s/he can see it and then fix it.
Maybe the engine could assign meaning to return codes? Like, 0 = everything's OK, 1 = recoverable error, 2 = major error, 3 = fatal. Then, if code != 0, it calls a 'getError()' method and writes the error information to an error log? Maybe it even prints a small notification that an error occurred to the infolog, referring to the entry in the error log? In the case of a fatal error, it could gracefully exit the system, otherwise it could just continue.


Finally, just to make sure, it is the structure of the callback that you want me to comment on, right? As in, for example, the Economy class and its methods?
My intention is to work on the framework I mentioned, which will cover the whole of the callback eventually, and report back whenever I run into anything that seems odd, or for which there might be a better solution. Though, if you want me to, I can have a look over the whole of it right now, and see if I can't spot anything of interest.
Tell me if I misunderstood, or if you were expecting something else.

it should, but something could be going wrong (actually somethign is going wrong, as it can not find your class)
when it can not find your class, it could be becasue:
- your jar is nto in the classpath (check the interface log)
- it is searchign for the wrong class (bad entry in AIInfo.lua)
- your jar does not contain the class it should in the correct subdir (check with a zip programm).
i can not think of anything else.

the exception handling thing:
that is something to be proposed in the C Interface thread, i will do that.

the last part.. yes, you understood me correctly.
whether you look over the whole callback right now, or rather during your work on your wrapper.. both is good for me, whle the first is maybe a bit better... it is your choice, whatever you prefer.

@Hoijui (regarding PM)

I still cannot compile caiinterface. Are you sure that com/clan-sy/spring/ai is fully up-to-date? My copy is missing everything out of oo, command, and event directories. The compiler errors are all of the form:
package com.clan-sy.spring.ai.(something) does not exist.

To make sure I was using CMake correctly, I checkout /trunk and compiled no problem. I can't use the installer since I run Linux. Has the installer only been made for Windows?

Also, to make these errors go away:
package com.sun.jna.* does not exist

I dropped the source code for jna directly into com/sun...

@LoidThanead
Thanks for the jars. They showed me all the classes I was missing, but won't I need the source files be able to start anything?

Onezeno, if you add the jar files to the classpath the Java compiler will find the class files inside and allow you to use them. If you're using an IDE such as Eclipse or JCreator, they normally have an option to add external libraries to the classpath.
In Eclipse, this can be done in project->properties->Java Build Path->Libraries. Click 'Add External JARs...' and select the jar files I sent you.
If you're doing everything from the command line, I think you should be able to find the information you need here. Though I recommend you consider switching to a good IDE. (I use Eclipse myself.)

To hoijui, there's no problem with me doing both. When I have the time (probably sometime tonight), I'll have have a closer look at the callback and see if I'd have done anything different. Afterwards, should I come across anything new while working with the callback I can still notify you.

good thanks

@onezeno
as said in the pm already, the files yo uare missing should be automatically created when you use cmake or scons, so something is going wrong there... try to find out what.. if you have more info about it, post it here.
as i also explained in the opm, you can also create these files semi-automatically, by using the files under AI/Interfaces/Java/bin
that should mianly be java_generateWrappers.sh i think.

Okay I was getting a warning about 'No Java icludes found -> Java AI interface not created' from CMake. I fixed that by going to FindJNI.cmake under SET (JAVA_AWT_INCLUDE_DIRECTORIES) and adding $ENV{JAVA_HOME}. $ENV{JAVA_HOME}/include was already present but it didn't fix the error until I added in the next higher directory. With that fixed I now get a new error that prevents CMake from configuring:
So I narrowed down to the following code. I commented out the orginal code and have added my new code below that. You'll notice that it is a bit hard-wired. I first updated the directories, then tried putting the directory directly in code to T/S down. This is the last iteration when I ran out of ideas:
Maybe libjvm.so is not the right library? I couldn't find any library called jvm, as the original code was looking for.

@LoidThanead
Your advice was good I now have the project working in NetBeans. I haven't touched it at all and really haven't looked at it all that much yet. I have a lot of free time for the next week, but then in about a month I'll be getting swamped with the 'real world'. I'm hoping to be able to get some sort of a 'Hello World' AI laid down before then, using your interface. Then I'll be able to work on it as I can make time. I'll probably be PMing you with some newbish questions tomorrow or the next day.