(Last updated for ver 0.2.0)

First things first, download the Avatar Core if you haven't already. Instructions for doing that and setting up your authoring tool/IDE can be found on the Installation page. It may also be helpful to keep handy the API Documentation as a reference for the samples covered here. And if you're completely new to Avatar Core, be sure that you've read the Introduction as it will give you a nice overview of the framework as a whole.

• Avatar Core Hello World
• Sample Code
• Walkthrough
• Hello World with XML
• Sample Code
• Walkthrough
• Where to go from here

Avatar Core Hello World

The Avatar Core framework doesn't support text directly, so a Hello World! example (one which serves as a simple introduction to a new programming language or API) will have to be faked with an image. The image being used will be the following:

In this example we'll use what will essentially be the bare minimum necessary for the framework to display this image on the screen. This requires 4 classes from the framework: Avatar (com.myavatareditor.avatarcore.Avatar), Feature (com.myavatareditor.avatarcore.Feature), Art (com.myavatareditor.avatarcore.Art), and AvatarDisplay (com.myavatareditor.avatarcore.display.AvatarDisplay). The Avatar will contain a Feature which in turn references an Art. Then, that Avatar is given to the AvatarDisplay display object so it can be drawn on the screen.

Avatars can contain any number of Feature objects. Features in turn reference only one primary Art object. Art specifies what is to be displayed visually for that Feature. When an AvatarDisplay is given an Avatar object to be drawn, it automatically reads through its Feature objects and finds all the Art objects that it needs to displayed on the screen.

Sample Code

import com.myavatareditor.avatarcore.*;
import com.myavatareditor.avatarcore.display.*;

var avatar:Avatar = new Avatar();
var feature:Feature = new Feature();
var art:Art = new Art("http://www.myavatareditor.com/avatarcore/images/tutorial/hello_world.png");

avatar.addItem(feature);
feature.art = art;

var avatarDisplay:AvatarDisplay = new AvatarDisplay(avatar);
addChild(avatarDisplay);

When published, you end up with:

Note: For the image to display, you will need to be connected to the internet unless you change the URL used by the Art object.

Walkthrough

The first thing that is necessary is the is importing the classes being used. Most of the core Avatar Core classes are defined directly in the com.myavatareditor.avatarcore. AvatarDisplay, being a DisplayObject (the view), is contained within the com.myavatareditor.avatarcore.display package.

import com.myavatareditor.avatarcore.*;
import com.myavatareditor.avatarcore.display.*;

Next, the objects that make up the avatar model are created, starting with the Avatar itself. This needs at least one Feature and an Art instance to be referenced by that feature. Here, the Art instance references the hello_world.png.

var avatar:Avatar = new Avatar();
var feature:Feature = new Feature();
var art:Art = new Art("http://www.myavatareditor.com/avatarcore/images/tutorial/hello_world.png");

Once the avatar objects have been created, they can be assembled. Since Avatar objects can contain many Feature instances, they uses a function not unlike DisplayObjectContainer.addChild, addItem, to obtain Feature references. Feature, on the other hand, can only contain one Art object, so it simply uses a property called art. The addItem function is used quite a bit in Avatar Core as it is part of Avatar Core's Collection API used by many objects in the framework.

avatar.addItem(feature);
feature.art = art;

Finally an AvatarDisplay object is created to display the Avatar visually. This is added to the display list and allows us to see the avatar and all of its feature art.

var avatarDisplay:AvatarDisplay = new AvatarDisplay(avatar);
addChild(avatarDisplay);

Hello World with XML

One of the more important features of Avatar Core is the ability to describe avatars in XML. This should be the more commonly used workflow when working with avatars in Avatar Core - defining avatars in XML and using a generic client application to load that XML and display the avatar character it describes. This example takes the previous Hello World example and switches it over to use XML. For the sake of simplicity, the XML will be included inline with the rest of the source code, but it would be more likely that this would be loaded in from an external source in practice.

Sample Code

import com.myavatareditor.avatarcore.*;
import com.myavatareditor.avatarcore.display.*;
import com.myavatareditor.avatarcore.xml.*;

var avatarXML:XML = 

	<Avatar xmlns="com.myavatareditor.avatarcore">
		<Feature>
			<art src="http://www.myavatareditor.com/avatarcore/images/tutorial/hello_world.png" />
		</Feature>
	</Avatar>;

var xmlParser:XMLDefinitionParser = new XMLDefinitionParser();
var avatar:Avatar = xmlParser.parse(avatarXML) as Avatar;

var avatarDisplay:AvatarDisplay = new AvatarDisplay(avatar);
addChild(avatarDisplay);

When published, the results are the same as before:

Walkthrough

As before, the necessary imports are included. This time an extra import for com.myavatareditor.avatarcore.xml is added for the XML parser.

import com.myavatareditor.avatarcore.*;
import com.myavatareditor.avatarcore.display.*;
import com.myavatareditor.avatarcore.xml.*;

Next is the XML, here assigned to the avatarXML variable. It mirrors the Avatar definition created within the source code before. It consists of an Avatar node (the Avatar instance), a nested Feature node (Feature child item added to Avatar), and an art node which represents the Art instance assigned to the art property of the parent Feature. The Art instance's src attribute is defined as the same URL passed into the Art constructor, which before, defined the src property for that Art instance.

Note that the xml namespace specified within the XML is the same is the package path used by Avatar, Feature, and Art (com.myavatareditor.avatarcore). This namespace is required since it's actually used to locate those definitions when the XML is being parsed.

var avatarXML:XML = 

	<Avatar xmlns="com.myavatareditor.avatarcore">
		<Feature>
			<art src="http://www.myavatareditor.com/avatarcore/images/tutorial/hello_world.png" />
		</Feature>
	</Avatar>;

With the XML defined, it can be converted to a tangible Avatar instance. This is done using the XMLDefinitionParser class. Using it's parse method with the XML, the Avatar defined by that XML is created and saved to the avatar variable.

The XMLDefinitionParser class contains all the logic necessary for converting the XML to runtime objects. This includes automatically instantiating XML nodes as object instances, adding them to collections (Feature in Avatar) or assigning them as object properties (art in Feature).

var xmlParser:XMLDefinitionParser = new XMLDefinitionParser();
var avatar:Avatar = xmlParser.parse(avatarXML) as Avatar;

Finally, as was the case before, an AvatarDisplay instance is created for the Avatar and added to the display list for viewing.

var avatarDisplay:AvatarDisplay = new AvatarDisplay(avatar);
addChild(avatarDisplay);

Where to go from here

• AboutFeatures
• AboutArt
• AboutXMLParsing
• AboutLibraries
• AboutColors
• AboutAdjusts
• AboutBehaviors