Contest Entries

We've now entered the world of being real Java programmers because we know how to create our own objects. This contest is an opportunity for us to explore Java graphics and gain practice creating more objects. AnimationWorld is a framework which allows us to create animations and test them out. A complete work of animation includes a set of animated objects called sprites. The sprites are drawn in a specific order for each animation frame and then updated to a new state between each frame. An animation proceeds as a series of frames. The speed of the animation is the number of frames per second (fps). We can also set the number of frames in the complete animated work.

AnimationWorld

Try out the following two animations: EasyAnimation1 and EasyAnimation2. A screenshot of AnimationWorld is below:

EasyAnimation2

The basic control buttons are on the right button panel.

Run: Runs the animation until the number of frames has been reached. If the animation is at or past the last frame, the animation will be reset before being run. If the animation is somewhere before the last frame, the animation will be run from its current frame to the last frame.
Reset: Resets all the Sprites to their initial position and state. Does not run the animation.
NextFrame: Allows one to proceed through the animation on a frame by frame basis. Will let you move past the last frame.
Reset All: Resets the entire state of AnimationWorld to be the initial state when it was first loaded.

The following properties of the animation can be changed in AnimationWorld:

Current Frame: Enter the animation frame you want and hit the corresponding Set button.
Frames per Second: Enter the rate at which you want the animation to proceed and hit the corresponding Set button. The default frame rate can be obtained by hitting the Reset All button.
Number of Frames: Enter the frame at which you want the animation to stop and hit the corresponding Set button. The default number of frames can be obtained by hitting the Reset All button.

The following properties of the Sprites can be changed in AnimationWorld:

DebugMode: You can pick one Sprite at a time to debug. If a Sprite is being debugged, it will print out the message in your getState method for each frame in the animation in which it is being displayed.
Hidden: You can hide and show Sprites. By default, all the Sprites start being shown whenever they are active. Double-click on the Sprite's name in the "Show Sprites" list to move it to a hidden state. Double-click on the Sprite's name in the "Hide Sprites" list to move it back to a visible state. For example, you can watch just one Sprite in the animation or you can remove the background from the animation.

Basic Animation Structure

Creating an animation involves extending the AnimationWorld class and defining one method called initializeAnimation. Here's the code for EasyAnimation1:

public class EasyAnimation1 extends AnimationWorld {
  public void initializeAnimation () {
    MovingText hello = new MovingText("Hello!", 20, 150, 1, 0, Color.red);
    addSprite("Hello!", hello);
  }
}

To add Sprites to the animation, we use the addSprite method.

public void addSprite (String name, Sprite s)
Adds the Sprite to the animation and allows it to be referenced by the name given.

In the animation above, there is one Sprite. The MovingText Sprite moves text starting from the specified starting position (x,y) by the increment given (dx,dy) between frames and renders text in the color given. Defaults are used for everything else in this animation. The default background is white. The default frame size fills the entire space even if we resize the window. The default frames per second is 12. The default number of frames in the animation is 60. Note that the defaults can all be changed via the AnimationWorld interface. The defaults are set slow and small to values which are likely the minimum that you would want to use.

Here is the code for EasyAnimation2:

public class EasyAnimation2 extends AnimationWorld {

  public void initializeAnimation () {
    // set animation properties first
    setFrameSize(500,100);
    setFps(24);
    setMaxFrameNumber(180);

    // create Sprites and set Sprite properties
    ColorBackground background1 = new ColorBackground(Color.red);
    background1.setLastFrameNumber(160);

    ColorBackground background2 = new ColorBackground(Color.black);
    background2.setFirstFrameNumber(161);

    MovingText hello = new MovingText("Hello!", 20, 40, 5, 0, Color.green);

    MovingText bye = new MovingText("When will I see you again?", 300, 80, -1, 0, Color.cyan);
    bye.setFirstFrameNumber(25);

    FlashingText smile = new FlashingText("Smile!", 400, 40, Color.blue, Color.white, 10);
    smile.setFont(new Font("TimesRoman",Font.ITALIC,36));
    smile.setActiveFrameNumbers(50,120);

    // add Sprites to animation in the order in which they should be drawn
    // Sprites added before other Sprites appear behind those Sprites
    addSprite("red background", background1);
    addSprite("orange", background2);
    addSprite("Hello!", hello);
    addSprite("see ya", bye);
    addSprite("=)", smile);
  }

}

In this example, we are now using all of the possible methods we can use to set animation properties. They are explained below:

public void setFrameSize(int width, int height)
This method limits the animation to the specified width and height regardless of the size of the window. Centers the animation frame in the space available. Should only be used if you want a smaller animation space than normal.
public void setFps(int newFps)
This method sets the default frames per second for the animation to the number given. The default frames per second shows initially in the AnimationWorld interface and can be accessed again via the Reset All button.
public void setMaxFrameNumber(int newMaxFrameNumber)
This method sets the default number of frames in the animation. The default number of frames shows initially in the AnimationWorld interface and can be accessed again via the Reset All button. When we run an animation, it stops after rendering the frame numbered with the maximum number of frames.

In EasyAnimation2 we have now introduced backgrounds and the concept that Sprites can be active in only parts of the animation. Backgrounds are Sprites, too. The ColorBackground class fills the animation frame with the color given. Note that you should add backgrounds first to your animation so they will appear behind all the other Sprites. Sprites are special objects which understand a number of methods which will be explained later. The three methods that restrict when they show up in an animation will be used most often in the initializeAnimation method. They are explained below:

public void setFirstFrameNumber (int newFirstFrameNumber)
The Sprite becomes active starting from the frame number given.
public void setLastFrameNumber (int newLastFrameNumber)
The Sprite stops being active after the frame number given.
public void setActiveFrameNumbers (int newFirstFrameNumber, int newLastFrameNumber)
The Sprite is active between the frame numbers given, inclusive.

An active Sprite is drawn on the screen and can print out debugging messages. Notice that since backgrounds are Sprites, we can change the background in our animation.

Steps for creating a new animation:

Start a new file.

Add the following import statements:

import java.applet.*;
import java.awt.*;

Create a class which extends the AnimationWorld class.

public class MyAnimation extends AnimationWorld {
  // add code here
}

Save it in a file which is named the same name as the class name with a .java extension. In the example above, the file name must be MyAnimation.java.
Add the file to your project.
Define an initializeAnimation method.
Set any animation properties you want.
Define sprites.
Add sprites to animation.
Build, bring it up to date.
Create an .html file for your applet and name it after your class. The standard file for this example would be named MyAnimation.html and would include
```
<HTML>
<HEAD><TITLE>MyAnimation</TITLE></HEAD>
<BODY>
<APPLET CODE="MyAnimation.class" WIDTH=600 HEIGHT=400></APPLET>
</BODY></HTML>
```
Test out the animation in AppletViewer and have fun!

Sprites

Sprites are the objects which live and play in the animation. The bulk of the work is creating your own Sprites. However, creating Sprites is pretty easy. To make our own Sprite, we just need to do the following steps:

Create a new file.
Add the following import statement:
```
import java.awt.*;
```

Create a class which extends the Sprite class.

public class MySprite extends Sprite {
  // add code here
}

Save it in a file which is named the same name as the class name with a .java extension. In the example above, the file name must be MySprite.java.
Add the file to your project.
Add instance variables.
Add methods which tell us something about the Sprite. The following three methods are recommended:
public String name ()
Returns the name of the class.
public String toString ()
Returns a String telling the properties/instance variables of this object.
public String getState ()
Returns a String telling the current state of this object.
Add constructors. These are the methods that allow us to create this Sprite.
Implement the three required methods which define Sprite behavior:
protected void resetState ()
Resets the state of the Sprite to its initial state.
protected void drawState (Graphics g)
Draws the current state of the Sprite on the given Graphics context.
protected void updateState ()
Updates the state of the Sprite to the next state.
Save the file often. Build, bring it up to date.
Add the Sprite to your animations!

Sometimes the Sprite will want to behave differently depending on its environment. A Sprite can get the following information about its environment:

this.width: tells the Sprite the current width of the frame it is in
this.height: tells the Sprite the current height of the frame it is in
this.getCurrentStateNumber(): tells the Sprite the current state it is in
this.getCurrentFrameNumber(): tells the Sprite the current frame it is in

Note that if you start the Sprite after the first frame, the currentStateNumber is not the same as the currentFrameNumber. For example, if we have a Sprite which lives from frames 3-6 inclusive, the following table illustrates the difference:

Frame #	State #
1	0
2	0
3	1
4	2
5	3
6	4
7	4
8	4

Three sample classes have been provided for you to study. More samples may be available later.

Timeline

Midnight, Tuesday, December 7 Entries must be registered (via web form) and a sample working entry uploaded to the students public_html directory on nike.
8am, Wednesday, December 8 No more changes to entries permitted. Final entries must be uploaded to the students web directory and drop folder and hard copies submitted.
Voting by CS111 students for the best entries invarious categories will occur between 8am Wednesday, December 8 and 8pm Thursday, December 9. More details on how the voting will work will be available nearer to the date.
Awards will be given out in lecture on Friday, December 10.

Logistics/Rules

Students may work in groups or as individuals
Each CS111 student may be involved in a maximum of two entry submissions (either two group entries, two individual entries, or one of each)
You may use Animation objects created by other students in the class as well as Animation objects provided as samples with the contest kit in your animation.

Entry Registration/Submission

Entries must be registered via filling out the entry form on the web (not available yet)
Hard copies of your animation and Sprites must be submitted.
.html and .class files must be uploaded to a student's public_html directory on nike
.java files must be uploaded to a student's drop folder (to be created)

Programming Guidelines

Put each Sprite in a separate file and put your name at the top of the file.
If you use Sprites created by other students, document who those students were in the top of those files.
If you take someone else's code and then change it a bit, be sure to credit where you got the code from and comment on what you did differently.

Code

Sample Code for this contest can be found in the folder AnimationContest available in the CS111 download directory. The samples above are in the folder SampleAnimations. A blank folder with the minimal number of files necessary and the template files are available in the ContestEntry folder.