Getting Started IAM Development

From AI Wiki

Jump to: navigation, search


Register an Iam

Registering an Iam works exactly like registering a regular player. The link is here: Player Registration Since it is not possible (yet) to manage more than one player account through one registered identity, you'll have to create a valid e-mail address for your Iam. You can use the service to your liking, like Yahoo or GMail. Then you need to use this e-mail address to register as a player with Blue Mars and activate the account and set it up just like a normal player. When you follow all the required steps of registration and confirmation you'll be able to download and install the Blue Mars client.

Of course, if you didn't register as a Blue Mars player yourself yet you need to do that as well. Without it you won't be able to test and interact with your own Iam. After the registration and confirmation procedure you'll be able to download and install the Blue Mars client software. For any other information about Blue Mars or the Blue Mars client you can always go to the main web-site Blue Mars

When you log into Blue Mars yourself you'll first be presented with the 'Places Browser'. Go to Iam Town to see and test your Iam. Most of the sample Iams will automatically appear there and it is the designated area for bot-testing.

Make sure you have Java

Chances are you already have Java installed on your computer. All Apple Macintoshes come with Java pre-installed and so do most Windows PCs. Many Linux distributions also come with some version of Java. Obviously this depends on your particular distribution. If your Linux has OpenJDK as a Java installation then we strongly recommend replacing it with Sun's JDK, as we've found OpenJDK to be rather unstable. In case your computer does not have Java installed for one reason or another, you can download a Java Software Developer Kit here: One way to find out if you have Java installed is typing "java -version" in a command-line tool. If you have it installed this will print the version you have installed. Sun's Java 6 is the recommended version. Java 5 will probably work as well but we'll not actively support it. Older versions than Java 5 are unlikely to work at all.

Download & Install Eclipse (optional)

Eclipse is an interactive development environment (IDE) for Java. Strictly speaking it is not a requirement to use Eclipse, but it is highly recommended. If you're an experienced Java developer and prefer to use a different method or development tool, then you'll have little trouble doing so. But until we have a large demand (and more staff) that warrants us supporting other development platforms, all documentation and tutorials will assume the use of Eclipse as development environment. Eclipse is free and can be downloaded here: and choose your preferred installation. If this is your first time, we'd recommend getting either 'Eclipse IDE for Java Developers' or 'Eclipse Classic'. Download and installation is straightforward and when in doubt you can refer to the Eclipse web-site: for support, instructions and documentation.

Now that you have downloaded and installed Eclipse, run it. It will start by asking you to select a 'workspace'. The workspace is nothing but a directory that will hold your Java projects managed by Eclipse. It is common to use a directory somewhere under your user-directory, but you are free to select any place you think convenient. Remember what you select though, as you'll need it in upcoming sections and it will be referred to as your 'workspace' directory.

Download files needed for Iam development

With Eclipse up and running we finally get to the point of getting the files needed for actual Iam development. The latest release of the IamFramework is always posted on the forum. Go here Release page go to the latest release post and download the file, decompress it into a folder called IamTemplate (or any other name of your choosing) and put the resulting directory under the 'workspace' directory you have selected for Eclipse. What this contains is a template that can be used as a starting point for Iam-development. As a matter of fact, you can even run it just as it is. There are actually several ways you can run it. The easiest way is to double-click the IamFramework.jar file in your Explorer, Finder or whatever visual file-system you're using. If things went well, you can log in Blue Mars using your Blue Mars client, and go to Iam Town. Not far from where your avatar appears you'll see an avatar standing called 'Alexis'.

There are disadvantages of starting an Iam this way. One is that if any problem appeared, you may not see anything happening at all. One reason that this may happen is when another developer is running this same application just this very moment. In that case you won't be able to log in with the same Iam at the same time. (Don't worry, we'll show you how to avoid this problem a few sections down.) This is a good way to start your Iam as a finished application, but not one you'll likely use while still developing. Another, slightly more verbose, way to start the Iam is to use a command-line tool. Go to the IamTemplate directory in your workspace and type "java -jar IamFramework.jar". (There are also some batch-file that you can use to do this for you called startIam.bat or )This time you should see it print a few lines like the following:

0    [main] INFO  com.avatar_reality.blue_mars.iam.IamBeanHelper.getIamBeans( - Found 1 xml files
51   [main] INFO  org.springframework.beans.factory.xml.XmlBeanDefinitionReader.loadBeanDefinitions( - Loading XML bean definitions from file [...]
367  [main] INFO  com.avatar_reality.blue_mars.tkclient.TKClientManager.init( - Connect avt499
Logging in of Iams complete.

Type 'quit' in the console to stop the Iam. If you don't see the lines above, something must have gone wrong somewhere. Hopefully the error on your screen will indicate what it is that is wrong or missing.

Lastly we'll show you how to run an Iam from within Eclipse. First of all you'll need to start Eclipse. Since this is a new project, it will not appear in Eclipse just yet. Select File -> Import -> General -> Existing Projects into Workspace. Click Next (or double-click the Existing... option) and click "Browse" and select the IamTemplate directory and click "Finish". Now you'll have a project called 'IamTemplate' in Eclipse. There are many ways to view and organize your project in Eclipse. If you don't see it on your screen already, add a tab called 'Navigator' by selecting Windows -> Show View -> Navigator. In the navigator view, open the 'source' directory under the IamTemplate project and open the file by double-clicking on it. You'll see it only contains a few lines of code. Now select Run -> Run As -> Java Application. Possibly you'll see the same lines appear in the 'Console' tab that appeared when you started it from the command line. (If you don't see any 'Console' tab, add it by selecting Window -> Show View -> Console.) Again, an Iam called Alexis will appear in Iam Town of Blue Mars.

Now what? Time to peek under the hood

Great, you're able to start an Iam. You may have already noticed though that it just stands there. It doesn't do anything. Time to peek under the hood and see how things work and what we'll need to do to make 'your' Iam actually do something. If you open the 'source' directory in your IamTemplate project you'll find two Java files there. One, you've already encountered. Time to open the other one, you'll see that this class has a lot of functions defined in them but that they are all empty except for a commented line saying "TODO Auto-generated method stub". You'll also see that all of them are marked with @override, meaning they override existing functions of an existing base-class.Take a moment and hover your cursor over a few of those functions and you'll see a box pop up with a brief description of what the function does. If the text doesn't fit in the box, F2 will allow you to make it bigger.

OK, tempting to start putting some code in these, isn't it? Let me first point out that this is a template project containing a template Java file. Before you do anything, you might consider some renaming before you go on. This process will also teach you a few other important concepts of the Iam-Framework. First of all, maybe it's a good idea to rename your project to something more meaningful. Right-click it in the Navigator tab and select Rename... and change it to EchoIam. Next, select the identifier IamBehaviorTemplate in the first line of the class where it says public class IamBehaviorTemplate, right-click and select Refactor -> Rename and change it to EchoBehavior. Note that it also changed the name of the constructor for you. Also change the string defined a little lower and change its contents to EchoBehavior as well. Next go to the 'receiveSayAction()' function and enter one line of code so that it looks like this:

public void receiveSayAction(String entityName, String text)
    say(text+" to you too!");

Now we need to do one more thing. Open the file MyIam.xml. In this file you'll need to change the line where it says <bean id="MyIamBehavior" class="IamTemplateBehavior" scope="prototype"/> and replace IamTemplateBehavior with EchoBehavior. While we're here, let's look at this file a little closer. This is a Spring configuration file. Spring is an extensive framework about which you can find lots of information here In the IamFramework it is used to make a sort of plug-in architecture. Instead of executing an Iam directly, Spring is used to assemble one or more Iams based on these kind of XML files. Since we're modifying this file now, take the time to change the "" login-name and replace the "bot123" password with the ones you registered with Blue Mars. This will avoid you getting in the way of other developers who may be trying to run the default Iam in the IamTemplate project, resulting in a 'Already Logged In' error.

OK, time to give it another go. Select Run -> Run History -> TestMyIam to run the Iam once more. If all goes well, your Iam appears again, now with the name you selected. Try saying something and you should get a reply. Congratulations, you made your Iam do something!

Technical sidenote: If you've followed the instructions above, everything should works as expected. There's a pitfall in the procedure described above however, and it may help prevent future problems to understand it. In the XML file that describes your Iam there's a few lines that say:

	<bean id="classpath" class="com.avatar_reality.blue_mars.iam.ClassPathBean">
		<property name="jarList">

This says where your class-files are to be found that implement the Iam. But we didn't update this file with the new echo code. So how come it still worked? Well, actually, it doesn't work completely. If you were to start the Iam from the command-line with the usual command java -jar IamFramework.jar you would see an error that your EchoBehavior class cannot be found. For it to work as a stand-alone application, you'd need to export the jar-file again. You do this by right-clicking the createJar.jardesc file and selecting "Create JAR". Usually during development while you run your Iam from Eclipse, it's better to delete the JAR-file altogether to avoid confusion and only create it when you're ready for the official release of your Iam.

Getting fancy.

OK, your initial enthusiasm could cool quickly now that you find how little your Iam actually does. But it's a start. Let's add a few simple tweaks to make it a little more life-like. Modify the receiveSayAction() function so that it looks as follows:

public void receiveSayAction(String entityName, String text)
       Entity entity = findEntity(entityName);
       say(text+" to you too, "+entity.getFirstName());

(If the compiler complains about not knowing the type 'Entity', put the cursor just after 'Entity' and press CONTROL-SPACE and select the Entity class from the iam.framework. Or mannually add a statement at the beginning of your file saying "import com.avatar_reality.blue_mars.iam.framework.Entity;")

Now when you speak to the Iam, it will not only answer, but it will turn towards you and make a speaking gesture while talking. Talking fancy! Although this demonstrates how easy it is to make the Iam react and do interesting stuff, it also shows there are a lot of things in the IamFramework that will take time to learn and find out how things work. Many of these functionalities will be addressed in future tutorials and/or example Iams. For now, let me point you to what is probably the most important resource of information for Iam developers, the javadocs. Some of these you have already seen by hovering the cursor over things. But a more extensive view of what is there for you to use and build on you get from the actual javadoc files. In your project, go to the javadoc directory and open the index.html file. Depending on how your eclipse is configured, you may want to right-click and choose Open With -> Web Browser. Or you can open it from your file-system with a browser and bookmark it.

Summary, what you've learned so far.

As you've seen it's easy to run an Iam. And it's only slightly more complicated to program your Iam todo something or react to events in the virtual world. This is done by implementing a behavior class which must be a sub-class of com.avatar_reality.blue_mars.iam.framework.behavior.BehaviorAdapter. Any events observed by the avatar that represents your Iam will arrive in one of the 'receiveXXX()' functions of this class, which you intercept by overriding. Note that you don't actually need to override any of them for your Iam to work properly. There's nothing that says your Iam actually has to listen to what anybody says! After some time you may actually decide to delete those you don't ever plan to implement. In the template they are there to show you which they are. This class also has several functions that initiate an action by the avatar of your Iam. Since your Iam can do pretty much the same things that all avatars can, it's no surprise that there's a certain symmetry between the actions it receives and the actions it can perform itself. In the last example you've seen the receiveSayAction() function call functions like say() and doAnimation(). Look up these classes in the javadocs to see a full list of functions you can call. Looking up the class com.avatar_reality.blue_mars.iam.framework.behavior.AbstractBehavior is a good place to start.

Personal tools