February 6th, 2012 by Elliott Mitchell

Now and then, as a professional 3D technical artist and game designer, I find it’s helpful to step out of my usual routine and make a game over a weekend. Why? Because it keeps life fresh and exciting while providing a rare sense of instant gratification in the crazy world of video game development. Making a video game over a weekend isn’t easy for one person alone. For this, Global Game Jam was created.

This year’s Global Game Jam was held last January 27 – 29, 2012. I registered with was the Singapore-MIT GAMBIT Game Lab, in Cambridge, Massachusetts. Here is the lowdown of my experience.

The Global Game Jam (GGJ) is an annual International Game Developer Association (IGDA) game creation event. The event unites people from across the globe to make games in under 48 hours. Anyone is welcome to participate in the game jam. Jammers range from industry professionals to hobbyists and students. The primary framework is that under common constraints, each team completes a game, without preconceived ideas or preformed teams, in under 48 hours. This is intended to encourage creativity, experimentation and collaboration resulting in small but innovative games. To support this endeavor, schools, businesses and organizations volunteer to serve as official host sites. Several prominent sponsors such as Loot Drop, Autodesk, Microsoft and Brass Monkey also helped foot the bill.

HOW IT WENT DOWN

Keynote -

GGJ site facilitators kicked off the Jam with a pre-recorded video from the IGDA website titled How to Build A Game in Less Than 48 Hours. The speakers in the video were Gordon Bellamy, the  Executive Director of the IGDA, John Romero (Quake) and Brenda Brathwaite (Wizardry) both co-founders of Loot Drop, Gonzalo Frasca (Ludology.org) the co-founder of Powerful Robot Games and Will Wright (The Simms) co-founder of Maxis. They speakers all gave excellent advice on creativity, leadership, scope and collaboration within a game jam.

Global Constraint -

Our primary constraint was revealed after the keynote video. It was an image of a snake eating it’s own tail. The snake represented Ouroboros, a Greek mythological immortal. Variations of the symbol span across time and space from the modern day back to antiquity. The snake, or dragon in some instances, while eating it’s own tail has made appearances in ancient Egypt, Greece, India, Mexico, West Africa, Europe, South America and elsewhere under a host of names. It’s meaning can be interpreted as opposites merging in an a unifying act of cyclical creation and destruction, immortal for eternity. To alchemists the Ouroboros symbolized the Philosopher’s Stone.

Group Brainstorming –

After the keynote game jammers arbitrarily split into 5 or 6 groups of 11 or so and went into different labs to brainstorm Ouroboros game pitches. After an amusing ricochet of thoughts, references, revisions, personalities and passions each room crafted 6 pitches which were mostly within the scope of the 48 hour Game Jam.

Pitch and Choose -

When the groups reassembled into the main room it was time to pitch.

The Rules-

• Pitches needed to be under a minute
• Title is 3 words or less
• Theme related to the Ouroboros
• The person pitching a game did not necessarily need to be on that potential team

There were about 30 or so pitches, after which each jammer had to choose a role on a game / team that appealed to them. Each Jammer had a single piece of colored coded paper with their name, skill level and intended role.

The Roles-

• Programmer
• Artist
• Game Design
• Audio
• Producer

Games with too many team members were pruned and others lacking members for roles such as programmer were either augmented or eliminated. Eventually semi-balanced teams of 4-6 members were formed around the 11 most popular pitches.

My team decided to develop our game for the Commodore 64 computer using Ethan Fenn’s Comma8 framework. We thought the game narrative and technology married well.

Time to Jam -

Post team formation, clusters of lab space were claimed. Even though most of us also brought our personal laptops, the labs were stocked with sweet dual boot Windows 7 & OS X systems with cinema displays. The lab computers were pre-installed with industry standard software such as Unity3d, Maya, Photoshop… We were also provided peripherals such as stylus tablets and keyboards. Ironically, I was most excited by the real world prototyping materials like blocks and graph paper which were also provided by or host.

First Things First –

After claiming a lab with another awesome team we immediately setup:

• Version control (SVN)
• Installed custom tools for Comma8 (Python, Java, Spite Pad, Tiles and more)
• Confirmed the initial scope of the game
• Set up collaborative project management system with a team Google Group and Google Doc

Cut That Out –

We needed to refine the scope once we were all aware of all the technical limitations such as:

• Commodore 64 from 1982 is old
• 64 kb of RAM for system not much
• 8 bit
• Programed in Assembly Language
• 300 X 200 pixels
• 16 pre-determined crappy colors
• 3 Oscillators
• Rectangular pixels
• Screen Space
• Developing in emulation on a network
• Loading and testing a playable on legacy Commodore 64 hardware
• Less than 48 hours to get it all working
• Our scope was too big, too many levels
• Other factors causing us to consider limiting the scope further included:
• None of us had made games for C 64 before
• Comma8 is an experimental engine that was untested in a game jam situation and is currently in development by Ethan
• Tools such as Sprite Pad and Tiles are very archaic and limiting apps for art creation
• Build process would do strange things to art after build time which required constant iteration

Rapid Iterative Prototyping -

Physical prototyping was employed to reduce the scope before we went too far down any rabbit holes. We used the following materials to prototype:

• Glass white board
• Markers
• Masking tape on the walls
• Paper notes tacked to the walls
• Graph paper
• Wooden blocks
• Pens

Results of Physical Prototyping-

• Cut down scope from 9 levels to 5 levels as the minimum to carry the Ouroboros circular theme of our narrative far enough
• Nailed the key mechanics
• Refined the narrative
• Determined scale and placement of graphical elements
• Limited overall scope

Naturally we ran into design roadblocks and need to revise and adapt a few times. Physical prototyping once again sped up that process and move us along to completion.

QA-

We enlisted a few play testers on the second night and final hours of the game jam to help us gauge the following:

• Playability
• Comprehension of the narrative
• Recognition of the lo-res art assets
• Overall player experiences
• Feelings about the game
• Suggestions
• Bugs

We did wind up having to revise the art, level design and narrative slightly to reach a better balance and game after play testing.

Deadline -

1.5 hours before the game jam was to end it was pencilsdown. Time to upload to the IDGA Global Game Jam website, any other host servers and on to the site presentation computer. Out of the total 48 hours allotted to the game jam, we

only had about 25 working lab hours. Much time was spent on logistics like the keynote video, brainstorming, pitching, uploading and presenting. Our site also was only open from 9 am to midnight so there was not 24 hour access. With 25 hours of lab time all 11 games at my site were uploaded and ready for presentation.

Presentations -

The best part ever! The presentations were so exciting. Many of the jammers were so focused on their work they were not aware of what other teams were up to. One by one teams went up and presented their games in whatever the current game state was at the deadline.

Most were pretty innovative, experimental and funny. Titles such as The Ouroboros Hangover and Hoop Snake had the jammers in stitches. Fire farting dragons, Hoop Snakes, drunk Ouroboros and so on were big hits. Unity, HTML 5, Flash, Flex, XNA, Comma8 and Flixel were used to create the great games in under 48 hours.

Take Aways -

My teammates and I consider the game we made, Walking Backwards, to be a success.   We accomplished our goals:

• Experimental game
• A compelling narrative
• Awesome audio composition
• Most functionality we wanted we achieved
• Runs on an original Commodore 64 with Joysticks
• Can be played with a Java emulator
• Got to work together under pressure and have a blast

Would have liked-

• Avatar to animate properly (we had bi-directional sprites made but not implemented)
• More audio for sound effects

The final take away I had, besides feeling simultaneously exhilarated and exhausted, is how essential networking at the game jam is for greater success. Beyond just meeting new people, networking at the jam made or broke some games. Some teams didn’t take time to walk around and talk to other teams. In one instance, a team didn’t figure out a essential ghost mechanic by the end of the jam. They realized at presentation time another team had implemented the same mechanic they failed to nail down in the same engine. Networking also provided mutual feedback, play testing, critique, advise, friendships and rounds of beer after the event ended. Many of the jammers now have a better sense of each other’s strengths and weaknesses, their performance under stress, their abilities to collaborate, lead and follow.

I, for one, will be a life long game jammer, ready to collaborate while pushing into both familiar and new territories of game development with various teams, themes and dreams.

Follow this link to see all the games created at my site hosted by the Singapore-MIT GAMBIT Game Labs

——

Elliott Mitchell

Technical Director- Infrared5

Twitter: @ Mrt3d

C64, Game Development, Game Jam, Global Game Jam, Ouroboros

January 11th, 2012 by Elliott Mitchell

Have you ever worked on a game that was beautifully lit in the Unity editor but ran like ants on molasses on your target device? Chances are you might benefit from using lightmaps. Ever worked on a game that was beautifully lit with lightmaps but looked different between your Mac and PC in the Unity editor? Chances are you might want to create your own 2nd UV sets in Maya.

If you didn’t know, lightmaps are 2D textures pre-generated by baking (rendering) lights onto the surfaces of 3D objects in a scene. These textures are additively blended with the 3D model’s original textures to simulate illumination and fine shadows without the use of realtime lights at runtime. The number of realtime lights rendering at any given time can make or break a 3D game when it comes to optimal performance. By reducing the number of realtime lights and shadows your games will play through more smoothly. Using fewer realtime lights also allows for more resources to be dedicated to other aspects of the game like higher poly counts and more textures. This holds true especially when developing for most 3D platforms including iOS, Android, Mac, PC, Web, XBox, PS3 and more.

Since the release of Unity 3 back in September 2010, many Unity developers have been taking advantage of Beast Lightmapping as a one-stop lightmapping solution within the Unity editor. At first glance Beast is a phenomenal time saving and performance enhancing tool. Rather quickly, Beast can automate several tedious tasks that would have needed to be preformed by a trained 3D technical artist in an application like Maya. Those tasks being mostly UV related are:

• Generating 2nd UV sets for lightmapping 3D objects
• Unwrapping 3D geometry into flattened 2D shells which don’t overlap in O to 1 UV co-ordinate quadrant
• Packing UV shells (arranging the unwrapped 2D shells to optimally fit within a square quadrant with room for mipmap bleeding)
• Atlasing lightmap textures (combining many individual baked textures into larger texture sheets for efficiency)
• Indexing lightmaps (linking multiple 3D model’s 2nd UV set UV co-ordinate data with multiple baked texture atlases in a scene)
• Additively applies the lightmaps to your existing model’s shaders to give 3D objects the illusion of being illuminated by realtime lights in a scene

• Other UV properties may be tweaked in the Advanced FBX import settings influencing how the 2nd UVs are unwrapped and packed which all may drastically alter your final results and do not always transfer through version control

Why is this significant? Well your 3D object’s original UV set is typically used to align and apply textures like diffuse, specular, normal, alpha texture maps, etc, onto the 3D object’s surfaces. There are no real restrictions on laying out your UVs for texturing. UV’s may be stretched to tile a texture, they can overlap, be mirrored… Lightmap texturing requirements in Unity, on the other hand, are different and require:

• A 2nd UV set
• No overlapping UVs
• UVs and must be contained in the 0 to 1, 0 to 1 UV co-ordinate space

Unwrapping and packing UVs so they don’t overlap and are optimally contained in 0 to 1 UV co-ordinate space is tedious and time consuming for a tech artist. Many developers without a tech artist purchase 3D models online to “save time and money”. Typically those models won’t have 2nd UV sets included. Beast can Unwrap lightmapping UVs for the developer without much effort in the Unity Inspector by:

• Selecting the FBX to lightmap in the Unity Project Editor window
• Set the FBX to Static in the Inspector
• Check Generate Lightmap UVs in the FBXImporter Inspector settings
• Change options in the Advanced Settings if needed

Atlasing multiple 3D model’s UVs and textures is extremely time consuming and not always practical especially when textures and models may change at a moment’s notice during the development process.  Frequent changes to atlased assets tend to create overwhelming amounts of tedious work. Again, Beast’s automation is truly a great time saver allowing flexibility in atlasing for iterative level design plus scene, object and texture changes in the Unity editor.

Beast’s automation is truly great except for when your team is using both Mac and PC computers on the same project with version control that is. Sometimes lightmaps will appear to be totally fine on a Mac and look completely messed up on PC and vise versa. It’s daunting to remedy this and may require, among several tasks, re-baking the all the lightmaps for the scene.

Why are there differences between the Mac and PC when generating 2nd UV sets in Beast? The answer is Mac and PC computers have different floating point precisions used to calculate and generate 2nd UV sets for lightmapping upon importing in the Unity editor.  The differences between Mac and PC generated UVs are minuet but can lead to drastic visual problems. One might assume that with version control like Unity Asset Server or Git, the assets would be synced and exactly the same, but they are not. Metadata and version control issues are for another blog post down the road.

What can one to do to avoid issues with 2nd UV sets across Mac and PC computers in Unity? Well, here are four of my tips to avoid lightmap issues in Unity:

1. Create your own 2nd UV sets and let Beast atlas, index and apply your lightmaps in your Unity scene
2. Avoid re-importing or re-generate 2nd UV assets if the project is being developed in Unity across Mac and PC computers when your not creating your own 2nd UV sets externally
3. Use external version control like Git with Unity Pro with metadata set to be exposed in the Explorer or Finder to better sync changes to your assets and metadata
4. Use 3rd party editor scripts like Lightmap Manager 2 to help speedup the lightmap baking process by empowering you to be able to just re-bake single objects without having to re-bake the entire scene

Getting Down To Business – The How To Section

If your 3D model already has a good 2nd UV set and you want to enable Unity to use it:

• Select the FBX in the Unity Project Editor window
• Simply uncheck Generate Lightmap UVs in the FBXImporter Inspector settings
• Re-bake lightmaps

How to add or create a 2nd UV set in Maya to export to Unity if you don’t have a 2nd UV set already available?

Workflow 1 -> When you already have UV’s that are not overlapping and contained within the 0 to 1 co-ordinate space:

1. Import and select your model in Maya (be sure not to include import path info in your namespaces)
2. Go to the Polygon Menu Set
3. Open the Window Menu -> UV Texture Editor to see your current UVs
4. Go to Create UVs Menu -> UV Set Editor
5. With your model selected click Copy in the UV Set Editor to create a 2nd UV set
6. Rename your 2nd UV set to whatever you want
7. Export your FBX with it’s new 2nd UV set
8. Import the Asset back into Unity
9. Select the FBX in the Unity Project Editor window
10. Uncheck Generate Lightmap UVs in the FBXImporter Inspector settings.
11. Re-bake Lightmaps

Workflow 2 -> When you have UV’s that are overlapping and/or not contained within the 0 to 1 co-ordinate space:

1. Import and select your model in Maya (be sure not to include import path info in your namespaces)
2. Go to the Polygon Menu Set
3. Open the Window menu -> UV Texture Editor to see your current UVs
4. Go to Create UVs menu -> UV Set Editor
5. With your model selected click either Copy or New in the UV Set Editor to create a 2nd UV set depending on whether or not you want to try to start from scratch or to work from what you already have in your original UV set
6. Rename your 2nd UV set to whatever you want
7. Use the UV layout tools in Maya’s UV Texture Editor to layout and edit your new 2nd UV set being certain to have no overlapping UV’s contained in the 0 to 1 UV co-ordinate space (another tutorial on this step will be in a future blog post)
8. Export your FBX with it’s new 2nd UV set
9. Import the Asset back into Unity
10. Select the FBX in the Unity Project Editor window
11. Uncheck Generate Lightmap UVs in the FBXImporter Inspector settings.
12. Re-bake Lightmaps

Workflow 3 -> Add a second UV set from models unwrapped in a 3rd party UV tool like Headus UV or Zbrush to your 3D model in Maya

1. Import your original 3D model into the 3rd party application like Heads UV and layout your 2nd UV set being certain to have no overlapping UV’s contained in the 0 to 1 UV co-ordinate space (tutorials to come)
2. Export your model with a new UV set for lightmapping as a new version of your model named something different from the original model.
3. Import and select your original Model in Maya (be sure not to include import path info in your namespaces)
4. Go to the Polygon Menu set
5. Open the Window Menu -> UV Texture Editor to see your current UVs
6. Go to Create UVs Menu -> UV Set Editor
7. With your model selected click New in the UV Set Editor to create a 2nd UV set
8. Select and rename your 2nd UV set to whatever you want in the UV Set Editor
9. Import the new model with the new UV set being certain to have no overlapping UV’s all contained in the 0 to 1 UV co-ordinate space
10. Make sure your two models are occupying the exact same space with all transform nodes like translation, rotation and scale values being the exactly the same
11. Select the new model in Maya and be sure it’s UV is set selected in the UV Set Editor
12. Shift select the old model in Maya (you may need to do this in the Outliner) and be sure it’s 2nd UV is set selected in the UV Set Editor
13. In the Polygon Menu Set goto the Mesh Menu -> Transfer Attributes Options
14. Reset the Transfer Attributes Options settings to default by File -> reset Settings within the Transfer Attributes Menus
15. Set Attributes to Transfer all to -> Off except for UV Sets to -> Current
16. Set Attribute Settings to -> Sample Space Topology with the rest of the options at default
17. Click Transfer at the bottom of the Transfer Attributes Options
18. Delete non-deformer history on the models or the UVs will break by going to the Edit menu -> Delete by Type -> Non-Deformer History
19. Select the original 3D model’s 2nd UV set in the UV Set Editor window and look at the UV Texture Editor window to see it the UV’s are correct
20. Export your FBX with it’s new 2nd UV set
21. Import the Asset back into Unity
22. Select the FBX in the Unity Project Editor window
23. Uncheck Generate Lightmap UVs in the FBXImporter Inspector settings.
24. Re-bake Lightmaps

Once you have added your own 2nd UV sets for Unity lightmapping there will be no lightmap differences between projects in Mac and PC Unity Editors! You will have ultimate control over how 2nd UV space is packed which is great for keeping down vertex counts from your 2nd UV sets, minimize mipmap bleeding and maintain consistent lightmap results!

Keep an eye out for more tutorials on UV and Lightmap troubleshooting in Unity coming in the near future on the Infrared5 blog! You can also play Brass Monkey’s Monkey Golf to see our bear examples in action.

-Elliott Mitchell

@mrt3d on Twitter

@infrared5 on Twitter

Maya, Unity 3D

September 19th, 2011 by Keith Peters

It’s been a while, but we finally come to part 3 of this series.

In part 1 we learned the basics of setting up an Android project in Eclipse and drawing to the canvas.

In part 2 we covered animation and threading.

In this episode, we will look at handling the accelerometer, allowing you to control the animation by tilting your Android device.

Set up

We’ll continue on with the same project we created last time, which had a circle moving from left to right across the screen. Since we’ll be allowing the user to tilt the phone in any direction, we want to disable the auto-rotation feature that will change the orientation when the phone is tilted. This is done in the Android manifest xml file. We want to add the following line to the activity tag:

android:screenOrientation="portrait"

This will force the device to remain in portrait orientation no matter how it is tilted. The whole manifest will now look like this:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
      package="com.infrared5"
      android:versionCode="1"
      android:versionName="1.0">
    <uses-sdk android:minSdkVersion="8" />

    <application android:icon="@drawable/icon" android:label="@string/app_name">
        <activity android:name=".Animation"
                  android:label="@string/app_name"
                  android:screenOrientation="portrait">
            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>
        </activity>

    </application>
</manifest>

Listening for Accelerometer Events

The next thing we want to do is listen for accelerometer events, which will occur whenver the device is tilted. In reality, it’s not like you will only get events when the device is moving. You will get a steady stream of accelerometer events even if the device is sitting by itself on a table. But different types of applications may need to get these events more or less often. For example, a game may need to be very responsive and be very up to date on the events coming in, whereas in another type of application, it may not be so vital and you can opt to get the events less often to save on processing. Android allows you to listen for these events using the following values to control how often you will get them:

SENSOR_DELAY_FASTEST
SENSOR_DELAY_GAME
SENSOR_DELAY_NORMAL
SENSOR_DELAY_UI

These are all static values on the SensorManager class. We’ll see how they are used in a moment.

First we’ll go into our AnimView class which starts out like this right now:

public class AnimView extends SurfaceView implements SurfaceHolder.Callback {

In addition to implementing the SurfaceHolder.Callback interface, we now want to implement the android.hardware.SensorEventListener interface. So import that interface and add it to the class signature:

public class AnimView extends SurfaceView implements SurfaceHolder.Callback, SensorEventListener {

This, of course, will cause the compiler to complain that you have not implemented the required methods of that interface. Triggering a quick fix will add the following method stubs:

@Override
public void onAccuracyChanged(Sensor sensor, int accuracy) {
    // TODO Auto-generated method stub

}

@Override
public void onSensorChanged(SensorEvent event) {
    // TODO Auto-generated method stub

}

Before we do anything with these, we need to write the code that listens for the sensor events. We’ll do that right in the constructor.

public AnimView(Context context) {
	super(context);
	holder = getHolder();
	holder.addCallback(this);

	SensorManager manager = (SensorManager)context.getSystemService(Context.SENSOR_SERVICE);
	if(manager.getSensorList(Sensor.TYPE_ACCELEROMETER).size() != 0) {
		Sensor accelerometer = manager.getSensorList(Sensor.TYPE_ACCELEROMETER).get(0);
		manager.registerListener(this, accelerometer, SensorManager.SENSOR_DELAY_GAME);
	}
}

First we get an instance of the SensorManager class. This is done by calling the getSystemService on the context that is passed into the view’s constructor. We tell it which service we want: the Context.SENSOR_SERVICE.

Once we have the SensorManager, we need to check if there is indeed an accelerometer on this device. If so, we get the first available one. I’m not sure if any existing device has more than one accelerometer, but the api leaves that possibility open.

Finally, we register this class as a listener to the accelerometer, passing in the sensor delay you need, as covered earlier. At this point, we should start receiving events in the two methods we just added.

All we are interested in now is the onSensorChanged method, which will give us the data on how the device is currently oriented. As you can see, this method gets passed an instance of SensorEvent. This object has a property called values, which is a simple array of floats. For accelerometer events, the tilt on the x, y and z axes are represented by the first 3 elements of the array. i.e.:

event.values[0] is the degree of tilt on the x axis
event.values[1] is the degree of tilt on the y axis
event.values[2] is the degree of tilt on the z axis

All of these values will be in the range of -9.81 to +9.81. For a thorough explanation of why these values are used, see the SensorEvent class documentation here:

http://developer.android.com/reference/android/hardware/SensorEvent.html

For our purposes, we only care about the x and y axes. We’ll pass those values to the AnimThread class with a method called setTilt. This method doesn’t exist yet, but we’ll create it soon.

@Override
public void onSensorChanged(SensorEvent event) {
    if(animThread != null) {
        animThread.setTilt(event.values[0], event.values[1]);
    }
}

Note that the method will probably be called before and/or after the thread is created, so we’ll test to make sure it exists before calling any methods on it. For this simple demo, we won’t do any high or low pass filtering as described in the SensorEvent documentation, but if you wanted to do so, this would be a good place to do it.

Handling the Tilt Values

Now we need to create the setTilt method in AnimThread, but first let’s create a few properties there. We’ll need something to hold the raw tilt values, and some properties to hold the current position and velocity of the ball. The top of that class should now look like this:

public class AnimThread extends Thread {

    private SurfaceHolder holder;
    private boolean running = true;
    private float x = 100;
    private float y = 100;
    private float vx = 0;
    private float vy = 0;
    private float tiltX = 0;
    private float tiltY = 0;

Now we can create the setTilt method, which will be pretty simple:

public void setTilt(float tiltX, float tiltY) {
    this.tiltX = tiltX;
    this.tiltY = tiltY;
}

Now all we have to do is make use of those values. The strategy is to add the tilt values (or at least a part of them) to the velocity values, then add the velocity to the position values, and finally draw the circle at the final x, y point. Here’s the run method in full:

@Override
public void run() {
    while(running ) {
        Canvas canvas = null;

        try {
            canvas = holder.lockCanvas();
             synchronized (holder) {
                // update
                vx -= tiltX * 0.1;
                vy += tiltY * 0.1;
                x += vx;
                y += vy;

                // draw
                canvas.drawColor(Color.BLACK);
                Paint paint = new Paint();
                paint.setColor(Color.WHITE);
                canvas.drawCircle(x, y, 50, paint);
            }
        }
        finally {
            if (canvas != null) {
                holder.unlockCanvasAndPost(canvas);
            }
        }
    }
}

We’re now at a point where you can test the app. Hold the phone flat when you start it. The ball should “roll” in the direction you tilt the phone. Of course, it will roll out of sight if you’re not careful, so we need to fix that next.

Handling Screen Edges – Bouncing

The following stuff I’ve covered in a number of books and tutorials on my personal site, www.bit-101.com, so I’m not going to belabor the point. We’re just going to see if the ball has gone past any edge of the screen and if so, place it on the edge and reverse the velocity on that axis. Here’s the final AnimThread class in full:

package com.infrared5;

import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.view.SurfaceHolder;

public class AnimThread extends Thread {

    private SurfaceHolder holder;
    private boolean running = true;
    private float x = 100;
    private float y = 100;
    private float vx = 0;
    private float vy = 0;
    private float tiltX = 0;
    private float tiltY = 0;

    public AnimThread(SurfaceHolder holder) {
        this.holder = holder;
    }

    @Override
    public void run() {
        while(running ) {
            Canvas canvas = null;

            try {
                canvas = holder.lockCanvas();
                 synchronized (holder) {
                    // update
                    vx -= tiltX * 0.1;
                    vy += tiltY * 0.1;
                    x += vx;
                    y += vy;
                    if(x + 50 > canvas.getWidth()) {
                        x = canvas.getWidth() - 50;
                        vx *= -0.9;
                    }
                    else if(x - 50  canvas.getHeight()) {
                        y = canvas.getHeight() - 50;
                        vy *= -0.9;
                    }
                    else if(y - 50 < 0) {
                        y = 50;
                        vy *= -0.9;
                    }

                    // draw
                    canvas.drawColor(Color.BLACK);
                    Paint paint = new Paint();
                    paint.setColor(Color.WHITE);
                    canvas.drawCircle(x, y, 50, paint);
                }
            }
            finally {
                if (canvas != null) {
                    holder.unlockCanvasAndPost(canvas);
                }
            }
        }
    }

    public void setRunning(boolean b) {
        running = b;
    }

    public void setTilt(float tiltX, float tiltY) {
        this.tiltX = tiltX;
        this.tiltY = tiltY;
    }

}

Now as you tilt the device, the ball will bounce off the edges of the screen, with just a little less force than it hit.

Summary

We now have a working, accelerometer-based interactive animation. This isn’t meant to be a perfect example in terms of best practices. I’d probalby pull out a lot of hard coded values into variables, extract some of the code into separate methods, etc. I’d also get a time delta between updates so that devices running at different speeds would run the animation at the same rate. Perhaps I’ll be able to cover some of that in a future tutorial. But this gives you a good idea of the structure and what happens where and how to get started.

July 19th, 2011 by Keith Peters

Android Animation

In the first part of this series, we covered basic graphics in Android – starting a new Android project, creating a custom view and displaying it, and using that view to draw custom graphics in its onDraw method. To recap, the drawing occured only when the onDraw method was called by the system when it determined that the app needed to refresh its display. This generally occurs once when the app starts and only occasionally, if ever, thereafter. For animation, we need to be able to trigger redraws on a regular basis. This is quite a bit more complex than drawing a static image, but not horribly so, so let’s dive in.

SurfaceView

In the last example, we extended View for our custom view class. That was fine for the purpose, but will not be adequate for drawing multiple times like we need to do for animation. For View, the onDraw method is triggered by the system when it knows that the Canvas is safe to draw on. It can set things up for us before calling onDraw, and then clean up when it is done executing. Since we need to do drawing on our own schedule, we need a view class that will let us do this set up and clean up ourselves. That class is called SurfaceView. So that’s what our new view will extend.

To get started, create a new Android project the same way we did last time. Call the project and activity “Animation”. Again, in the main activity class replace the call to setContentView with a custom view. We’ll call this AnimView:

package com.infrared5;

import android.app.Activity;
import android.os.Bundle;

public class Animation extends Activity {
    private AnimView view;

    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        view = new AnimView(this);
        setContentView(view);
    }
}

Of course, AnimView does not exist, so we’ll get an error. Trigger a quick fix, which will offer to create the AnimView class. Before accepting the defaults in the New Java Class dialog, change the superclass field to “android.view.SurfaceView”. When the class is created, trigger another quick fix to create the constructor. You should end up with the following:

package com.infrared5;

import android.content.Context;
import android.view.SurfaceView;

public class AnimView extends SurfaceView {

    public AnimView(Context context) {
        super(context);
        // TODO Auto-generated constructor stub
    }
}

At this point, the app should compile and run, but naturally will show just a black screen.

SurfaceHolder

Again, since we will be a lot more in control of when things get drawn, we need to go a little more low level in what we are doing. When using onDraw, you are automatically passed a Canvas object that you are safe to draw on. When using SurfaceView though, you need to get your canvas from something called a SurfaceHolder. This can be retrieved by simply calling getHolder() from the SurfaceView instance. That’s easy enough, but there’s another bit of complexity coming up.

You can’t draw to a surface of a SurfaceView/SurfaceHolder until the surface is created. And you should not draw to it after it has been destroyed. So we need to know when these things happen. To do that, we can let the holder know that we want to handle related events. To do this, we call surfaceHolderInstance.addCallback(viewInstance). But one more catch – the object you pass to this method must implement an interface defined as SurfaceHolder.Callback. So our class definition starts out as:

public class AnimView extends SurfaceView implements SurfaceHolder.Callback {

When you do that, you’ll be informed that you are not implenting the required methods of that interface. Use a quick fix to add them. With all that done, you should have the following:

package com.infrared5;

import android.content.Context;
import android.view.SurfaceHolder;
import android.view.SurfaceView;

public class AnimView extends SurfaceView implements SurfaceHolder.Callback {

    private SurfaceHolder holder;

    public AnimView(Context context) {
        super(context);
        holder = getHolder();
        holder.addCallback(this);
    }

    @Override
    public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {
        // TODO Auto-generated method stub
    }

    @Override
    public void surfaceCreated(SurfaceHolder holder) {
        // TODO Auto-generated method stub
    }

    @Override
    public void surfaceDestroyed(SurfaceHolder holder) {
        // TODO Auto-generated method stub
        }
    }
}

Threading

Now we can start animating. In animation, you need generally have some kind of model of what you are animating, with some kind of rules on how that model changes. you need to update the model, and then render that model to the display, then update the model again, render again, and so on.

If you are used to animating in Flash you’re familiar with doing this via enterFrame, or perhaps with timers. Timers are also used in JavaScript animation. In Android though, we generally use threads.

Threads can be a bit scary as they are a bit more complex than a simple timer. If you’re not familiar with threads, the concept is just that you are starting another process that runs independently from the main process. This is useful for operations that might take a long time or will not return immediately. The new thread does its own thing in its own time frame, and the main process of your app continues to do what it needs to do, remaining responsive, etc.

The scary part of threads is that they run separately, but are able to access the same variables and objects in a non-synchronized way. Thus, one thread might be performing some procedure on a given object, and right in the middle of tht procedure, the other thread might step in and change the state of that object or even delete it. So you have to take some extra steps to guard against these types of situations.

Our view will use a separate thread to perform its animation. We will create and start the thread running in the surfaceCreated method, and we will stop the thread in the surfaceDestroyed method. There are a number of different ways to use threads. The way we’ll do it is to subclass the Thread class and put the custom functionality in that class.

Here’s the start of our custom thread class:

package com.infrared5;

import android.view.SurfaceHolder;

public class AnimThread extends Thread {

    private SurfaceHolder holder;
    private boolean running = true;

    public AnimThread(SurfaceHolder holder) {
        this.holder = holder;
    }

    @Override
    public void run() {
        // this is where the animation will occur
    }

    public void setRunning(boolean b) {
        running = b;
    }
}

In order to draw to a canvas, we’ll need the surface holder to get the canvas from, so we’ll pass that in in the constructor and save it. We’ll also need a variable that will indicate whether or not the thread is currently running and a way to set that.

When we create an instance of this thread class and call start() on it, its run method will be executed in a separate process. We’ll actually use a while loop to do our animation. This may seem odd if you’re coming from the Flash or JavaScript world, where in infinite while loop would just lock things up. But because this is in a separate thread, it works out fine.

The pseudocode for what we will do is like this:

public void run() {
    while(running) {
        // update the model
        // get a canvas
        // draw to the canvas
    }
}

This will just run forever. Well, until we set running to false anyway. As you might have guessed, we’ll create and start the thread in the surfaceCreated method and we’ll set running to false in the surfaceDestroyed method. There’s a few more details to it, but we’ll get there eventually.

Locking and Unlocking

To get a canvas from a surface holder, we actually call holder.lockCanvas(). This prevents anything from happening to the canvas while we are using it. When we are done with our drawing, we call holder.unlockCanvasAndPost(canvas), passing in the canvas instance we just drew to. This frees it up and displays what was just drawn.

Here is the final code with some actual animation going on:

package com.infrared5;

import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.view.SurfaceHolder;

public class AnimThread extends Thread {

    private SurfaceHolder holder;
    private boolean running = true;
    int i = 0;

    public AnimThread(SurfaceHolder holder) {
        this.holder = holder;
    }

    @Override
    public void run() {
        while(running ) {
            Canvas canvas = null;

            try {
                canvas = holder.lockCanvas();
                 synchronized (holder) {
                    // draw
                    canvas.drawColor(Color.BLACK);
                    Paint paint = new Paint();
                    paint.setColor(Color.WHITE);
                    canvas.drawCircle(i++, 100, 50, paint);
                }
            }
            finally {
                    if (canvas != null) {
                            holder.unlockCanvasAndPost(canvas);
                        }
            }
        }
    }

    public void setRunning(boolean b) {
        running = b;
    }
}

Here you can see we declare the canvas variable, then we enter a try block where we get the canvas and do the drawing. This allows us to unlock the canvas in a finally block, so that even if an exception is thrown while drawing, we won’t leave the canvas in locked state.

Note that the drawing is done in a synchronized block. This puts a lock on the holder so that nothing else can change it from another thread while we are using it. In this block we set the background to black and draw a white circle. The x value will be incremented on each loop, moving the circle across the screen.

Starting and stopping the thread

All we have to do now is create, start, and stop this thread. We’ve already said that we’ll do that in surfaceCreated and surfaceDestroyed methods. So let’s see what this looks like. First the created:

@Override
public void surfaceCreated(SurfaceHolder holder) {
    animThread = new AnimThread(holder);
    animThread.setRunning(true);
    animThread.start();
}

Simple enough. We create the thread, passing in the suface holder, set running to true, and start it. This will wind up executing the run method, which will run that for loop in a separate process.

The destroyed method is a bit more complex:

@Override
public void surfaceDestroyed(SurfaceHolder holder) {
    boolean retry = true;
    animThread.setRunning(false);
    while (retry) {
        try {
            animThread.join();
            retry = false;
        } catch (InterruptedException e) {
        }
    }
}

First of all, we set running to false. This will allow the while loop in the run method to exit. But since that’s happening in another thread, we don’t know exactly when that’s going to happen. So we want to make sure that it’s really fully complete before we leave here. We do that with the join method of the thread. That will cause execution to stop and wait for that thread to end. However, this will sometimes result in an InterruptedException. So we throw that whole thing in a try/catch statement and keep retrying it until the join finally successfully returns. Here’s the final AnimView class:

package com.infrared5;

import android.content.Context;
import android.view.SurfaceHolder;
import android.view.SurfaceView;

public class AnimView extends SurfaceView implements SurfaceHolder.Callback {

    private SurfaceHolder holder;
    private AnimThread animThread;

    public AnimView(Context context) {
        super(context);
        holder = getHolder();
        holder.addCallback(this);
    }

    @Override
    public void surfaceChanged(SurfaceHolder holder, int format, int width, int height) {
    }

    @Override
    public void surfaceCreated(SurfaceHolder holder) {
        animThread = new AnimThread(holder);
        animThread.setRunning(true);
        animThread.start();
    }

    @Override
    public void surfaceDestroyed(SurfaceHolder holder) {
        boolean retry = true;
        animThread.setRunning(false);
        while (retry) {
            try {
                animThread.join();
                retry = false;
            } catch (InterruptedException e) {
            }
        }
    }
}

Android, Animation, bit101, Graphics, Tutorial

June 27th, 2011 by Keith Peters

This is the start of a series of tutorials on graphics and animation on the Android platform. There is plenty of information out there on how to create general form-based, controls-and-layout type of Android apps, but very little on how to do more creative drawing and animation. So this series will cover the following topics:

1. Android graphics.
2. Android animation.
3. Android input: Accelerometer.
4. Android input: Touch.

Today we’ll get started with simple graphics. There are actually a few different ways to draw graphics on the screen in Android.

First, there is the Canvas class, which gives you a nice basic drawing API to create lines, circles, rectangles, fills, strokes, deal with bitmaps, etc.

Then there’s OpenGL. If you’re going to do 3D or just need more raw graphics and animation power, you’ll probably want to use OpenGL, or more likely use one of the various 3rd party libraries that make it a bit easier to use.

And then there is something called RenderScript, which was introduced in Android 3.0 (which, at the time of this writing is supported by only a few devices).

For this set of articles, we’ll be using the simplest and most widely available option, Canvas.

Setting up an Android coding environment

Of course, before we can even get started, you’ll need to have an Android coding environment set up and a connected Android device. You could use the Android simulator, and you should use it for testing different device resolutions and capabilities, but in general day-to-day dev, you’ll probably find it faster and easier to deploy and test on a device.

I’m not going to go into very deep detail about this, only because Google has covered it in far more depth than I ever could. So I’ll just point you to the right place.

http://developer.android.com/index.html

Here you’ll find links to the SDK, Developer’s Guide, References, Resources, Videos, and a blog. Within all that, you’ll find step by step instructions on how to set up your environment. But in a nutshell, you’ll need to:
1. Install Eclipse (or another editor of your choice, but this tutorial will assume you’re using Eclipse).
2. Download the Android SDK. This is just a folder of files and tools used in developing Android apps.
3. Install the ADT Plugin, Android Development Tools. This is an Eclipse plugin that will set up your Eclipse install to build Android apps.
4. Add Android platforms and components.

These steps are all covered in more detail here:

http://developer.android.com/sdk/installing.html

Connecting a device or creating a virtual device (emulator)

Next you’ll need to have someplace to run your code. Again, I recommend using a real device as much as you can. Setting up a device for development is covered here:

http://developer.android.com/guide/developing/device.html

If you don’t have a physical device, or are at a point where you need to test some different resolutions or features your device doesn’t have, this link will walk you through setting up a virtual device on the emulator:

http://developer.android.com/guide/developing/devices/index.html

Code!

OK, let’s make an app. Assuming you have everything installed and working, and are using Eclipse as your editor, fire it up and create a new workspace. Then create a new project by using the menu File -> New -> Android Project. This will bring up the “New Android Project” dialog.

Give your project a name, “Drawing” and choose a Build Target. We’ll stick with Android 2.2 since that’s a pretty common one.

Going further down, we need an application name, package name, and activity name. The application name is what will show up on the device. For now, think of the activity name as the name of the main class of the app. The package is the class package as in any Java project. Finally we need to specify the minimum SDK version. We’ll choose 8 here to coincide with the Android 2.2 SDK. The whole numbering system for SDKs and SDK versions is a bit confusing. I’ll leave it to you to figure it out more on your own. But the above settings will work for now.

Now we can click “Finish” and our project will be created. Your package explorer view should look like this:

There you can see your src folder with your package and main activity class. Opening that class you should see the following code:

package com.infrared5;
import android.app.Activity;
import android.os.Bundle;

public class Drawing extends Activity {
    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.main);
    }
}

Since this is the only activity in this application, this class will be instantiated when the app is run, and the onCreate method will be called. This is where you want to hook into to initialize pretty much everything.

Right now, onCreate calls super.onCreate and then setContentView, passing in something called R.layout.main. If you’re curious what this is, look in the folder res/layout and you’ll see main.xml, which will look like this:

If you’ve done any work with Flex, Silverlight, or any other XML-based layout systems (or even HTML) this will look pretty familiar. It creates a layout with a single child that is a TextView. The TextView’s text property is set to “@string/hello”. If you want to see what that is, look in res/values/strings.xml.

The Android compiler will compile all the stuff in the res folder into classes or embeddable assets as appropriate. So res/layout/main.xml becomes the R.layout.main, which is an instance of a class that extends View and can be set as the activity’s content view using setContentView.

Now, if you’ve set everything up correctly, you should be able to run or debug this project on your device and/or in the emulator and see something like the following:

If this is not working, stop here and get it debugged. This is the bare bones of project setup, and everything else depends on this.

Custom Views

OK, that’s all very interesting, but we’re not going to use much in the res folder or any of that xml-based layout stuff here. We’re going down to the metal and writing our own drawing code.

But since we aren’t relying on the compiler to create a view from xml for us, we’ll have to make our own view class. We can even use some of the ADT plugin’s shortcuts to let it do a bunch of the work for us. Change Drawing.java to look like this:

package com.infrared5;

import android.app.Activity;
import android.os.Bundle;
import android.view.View;

public class Drawing extends Activity {

    private View drawingView;

    /** Called when the activity is first created. */
    @Override
    public void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        drawingView = new DrawingView(this);
        setContentView(drawingView);
    }
}

Here we’ve created a new class member, drawingView of type View, instantiated it as a new DrawingView, passing in this to the constructor, and set it as the content view.

Of course, Eclipse will complain because DrawingView does not exist yet. But if we click on that error it will offer to create the class for you. It will even know that it should extend View. So go ahead and let it create that class. It should look like this:

package com.infrared5;

import android.view.View;

public class DrawingView extends View {

}

Now it’s going to complain again because it wants a constructor that takes an argument. Again, use the quick fix feature to let it create the constructor it wants. Now you’ll have this:

package com.infrared5;

import android.content.Context;
import android.view.View;

public class DrawingView extends View {

    public DrawingView(Context context) {
    super(context);
        // TODO Auto-generated constructor stub
    }
}

We’re at a stable point here, so go ahead and run that on your device/emulator and make sure it launches. You shouldn’t see anything but a black screen with the app name at the top, but it should compile and deploy.

OK, now we have a view we can draw in. The View class is designed so that all the drawing will be done in an onDraw method. This method will be automatically called whenever the view needs to be redrawn. To create this method, type “onDraw”, trigger auto-complete, and accept the first choice. You should wind up with an onDraw method like you see below (or you could go all old school and actually type it by hand).

package com.infrared5;

import android.content.Context;
import android.graphics.Canvas;
import android.view.View;

public class DrawingView extends View {

    public DrawingView(Context context) {
        super(context);
    }

    @Override
    protected void onDraw(Canvas canvas) {
        super.onDraw(canvas);
    }
}

You see this method has given us a Canvas to draw on. If you trigger autocomplete on canvas, you’ll see that it has all kinds of drawing methods. Let’s add a call to drawLine right after the super.onDraw call:

@Override
protected void onDraw(Canvas canvas) {
    super.onDraw(canvas);
    canvas.drawLine(0, 0, 100, 100, paint);
}

As you probably guessed, the first arguments for this are the x, y values of an initial and an ending 2d point. The last argument, paint, is a Paint object that tells the system what to make this line look like (color, width, etc.). Since we haven’t defined paint yet, it will give you an error. Trigger a quick fix to create a field named paint. Then in the constructor we’ll instantiate it and give it some properties. Here’s the result:

package com.infrared5;

import android.content.Context;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.Paint.Style;
import android.view.View;

public class DrawingView extends View {

    private Paint paint;

    public DrawingView(Context context) {
        super(context);
        paint = new Paint();
        paint.setColor(Color.WHITE);
        paint.setStyle(Style.STROKE);
    }

    @Override
    protected void onDraw(Canvas canvas) {
        super.onDraw(canvas);
        canvas.drawLine(0, 0, 100, 100, paint);
    }
}

Don’t forget the imports for Color and Style. You can run or debug this now and you should have an utterly fascinating diagonal white line on your device’s screen. When you’ve calmed down and gotten yourself under control, we’ll move on.

Setting the Background Color

Perhaps you want to change the background color. You can do that will canvas.drawColor, passing in the color you want to use. Note that this will actually clear the screen, so you’ll want to do this before drawing anything important.

Specifying Colors

In addition to the constants on the color class, like Color.BLACK, Color.WHITE, Color.RED, etc. you can specify exact colors with Color.rgb(red, green, blue) where each parameter is an int from 0 to 255, or Color.argb(alpha, red, green, blue) if you need transparency.

So to set the background to a kind of light purple, do something like this:

@Override
protected void onDraw(Canvas canvas) {
    super.onDraw(canvas);
    canvas.drawColor(Color.rgb(200, 155, 255));
    canvas.drawLine(0, 0, 100, 100, paint);
}

Other Shapes

As mentioned, there are lots of other options on Canvas for drawing various things. A few examples:

canvas.drawCircle(cx, cy, radius, paint)

Here cx and cy are the center point to draw a circle with the given radius.

canvas.drawRect(rect, paint)

Here rect is a Rect object or a RectF object (which would use floats rather than ints for its measurements).

canvas.drawPoint(x, y, paint)

Pretty obvious.

Then there are drawOval, drawArc, drawRoundRect, and many others.

Putting it all together

Just to implement a few things all at once, we’ll do something like this for a final demo:

package com.infrared5;

import java.util.Random;

import android.content.Context;
import android.graphics.Canvas;
import android.graphics.Color;
import android.graphics.Paint;
import android.graphics.Rect;
import android.graphics.Paint.Style;
import android.view.View;

public class DrawingView extends View {

    private Paint paint;

    public DrawingView(Context context) {
        super(context);
        paint = new Paint();
        paint.setColor(Color.WHITE);
        paint.setStyle(Style.FILL);
    }

    @Override
    protected void onDraw(Canvas canvas) {
        super.onDraw(canvas);
        canvas.drawColor(Color.rgb(200, 155, 255));
        int cols = 5;
        int margin = 20;
        int w = (canvas.getWidth() - (cols + 1) * margin) / cols;
        int rows = canvas.getHeight() / (w + margin);
        Random rand = new Random();
        for(int i = 0; i < cols; i++) {
            int x = margin + i * (w + margin);
            for(int j = 0; j < rows; j++) {
                int y = margin + j * (w + margin);
                Rect r = new Rect(x, y, x + w, y + w);
                paint.setColor(Color.rgb(rand.nextInt(255), rand.nextInt(255), rand.nextInt(255)));
                canvas.drawRect(r, paint);
            }
        }
    }
}

Here we’ve set the style to FILL instead of STROKE, then use some fancy math and a couple of for loops to draw a grid of squares, each with a random color. Nothing amazing, but assuming you have some previous experience with any kind of drawing API from any other language, this should set you up to create all kinds of custom graphics in your Android app or game.

Summary

Here we’ve seen how to set up a new Android project and create a custom view that we can draw into. The view class is instantiated and added as the activity’s main content view, and the onDraw method is called when it’s ready to display.

Of course, since generally speaking this is only called the one time near the start of the app, it’s just a static drawing. In the next installment of this series, we’ll dive into animation and making things move in Android.

Android, Application Development, Mobile Development, Tutorial