CS 1102 (A16) Individual Project
Implementing an Animation Language

Project Description

You must design and implement a language for animating graphic objects on a canvas. Graphic objects can move smoothly or jump around the canvas, optionally stopping when a graphic object bumps into something (like an edge of the canvas or another graphic object). Graphic objects can also be added or removed during an animation. Here are three sample animations:

• The first sample shows a red ball moving at a angle towards the blue wall until it hits the wall. At that point, the wall disappears and the ball moves back towards the left edge of the canvas, stopping when it hits the left edge of the canvas.

• The second sample shows a purple circle jumping to random locations around the canvas until it hits the top edge of the canvas.

• The third sample shows an orange circle dropping straight down until it hits the green rectangle. At that point, the red rectangle appears and the circle moves right until it hits the red rectangle, after which the orange circle jumps to a random location and stops.

For this project, you will develop:

1. A language for specifying animations such as these.

2. A program (interpreter) that will run an animation written in your language, displaying it on the screen.

You will do the project in two stages: a language design stage, followed by an implementation stage. Each stage has a separate due date.

Project Goal

The goal of the project is to make sure each student can define, design, and implement a domain-specific programming language.

This is an individual project -- you may not work with your homework partner, or any other students, on this project (see the collaboration policy for more details).

• Graphics must include at least circles and rectangles. You many optionally include other graphical objects (such as image gifs).

• Individual commands must include moving, jumping, and deleting graphic objects that are already on the canvas, as well as adding new objects to the canvas. Each command can move, jump, add or delete a single object, but the sequence of commands may move different objects.

• Your language must provide a way to repeat each of these commands until an object hits either an edge of the canvas or another (specific) graphic.

• The programmer should be able to specify the rate at which an object moves along each of the x and y axes, as well as each object's initial location on the canvas. Here, "rate" means how many pixels the object moves between each frame of the animation.

• In order to receive a final grade of B or better, your language will need to support repetition of arbitrary blocks of commands (see Grading section below all the criteria for the different grade levels).

Hints and Guidelines

• Think of the slideshow language we developed in class (and the exam language in Homework 4) as jerky textual animations that wait for user input to advance. This should give you a good idea of how to think about designing this language.

• No "abstraction Leakage"! Not only do you not want any function definitions in this assignment, but your language definition also must not make any assumptions about a particular function name existing in the interpreter.

• Some students have approached this project as if they were designing a physics-based simulator, which leads to an event-driven architecture. This is a valid approach to animation, but requires a different (and significantly more complex) programming pattern than the command interpreter we are trying to practice here. Think of this application as a simple computer automation of traditional "hand drawn" (cel) animation in which each command execution computes the next frame.

What to Turn in

Submit both the proposed language and examples showing how to represent all three sample animations above, plus one more animation of your own choosing, in your language.

You do not need to be able to run animation programs at the end of this stage. But you should be able to click 'Run' in DrRacket to execute your data definitions and examples without error!

A nice syntax (i.e., using macros) for the language is NOT needed at this stage either (you will add this in the implementation phase). All you need to submit are the data definitions and examples of data that you need to capture animation programs.

Like Homework 4, your submission at this point should NOT include any function definitions (or templates) or lambdas.

Submit an electronic file design.rkt (under turnin name Project Design) containing your work for this phase.

You will also be using a modified version of the graphics package you used in Homework 2, in which big-bang has been removed. This modified version is called world-cs1102.rkt. Download it and save it in the same directory as your project file, and then include the following at the top of your project file:

(require "world-cs1102.rkt")

Here are the key graphics functions that you will need to use:

• (create-canvas width height) initializes a drawing canvas with the given width and height (call only once per toplevel interpreter execution).
• (empty-scene width height) returns an empty scene (use same width and height as create-canvas).

• (place-image image x y scene) returns a new scene with given image added at given location in given scene.

• (update-frame scene) displays the given scene on the canvas (replacing the current contents of the canvas).
• (sleep/yield seconds) delays the drawing of the next frame by the given number of seconds. This can be used to control the rate of your animation. Values around 0.25 work well for this in practice. (Note: the full name of this function is "sleep/yield".)

• (random k) generates a random integer between 0 and k.

The main function in your implementation should be called run-animation. It takes an animation program in your language and executes it (displays the animation on the screen). Your animation should happen in one window over time---you are not trying to produce a sequence of still frames as shown in the samples.

You may decide to change or enhance your original language design as you write your interpreter. That's fine (even expected---implementing helps you assess your design decisions). Your project report (see below) should describe and explain the reason for all changes you decided to make from your original design.

Test Cases

(set! global (f global ...))

By the way, don't just write the test cases after you are all done, because they are required! It will save you a lot of time overall to write and run test cases all the way along your incremental development (successive refinement) process.

Finally, because the Pretty Big language does not by default provide check-expect, you will need to do some extra setup for testing, as described here.

The Project Report

Please write up to one page of comments at the front of your file (using the Racket block comment characters #| and |#) answering the following questions:

1. What must the TA do to run your program? Provide concrete instructions (such as "execute (run-animation animation1)"), including a list of the animations you defined as your test cases. The staff won't grade a program that they can't run.

2. What is the status of your implementation? Explain which features/aspects work and which don't. If you didn't get the repeating blocks commands to work, for example, say so. This gives the staff guidelines on how to test your system.

3. How have you changed your design since the version you submitted for the design deadline? Explain the changes and why you made them (i.e., I found I couldn't do X because of problem Y with my earlier definition). We're interested in seeing what doing the implementation taught you about the language design.

4. What, if anything, do you think could be cleaner in your design or implementation? If you are satisfied with your design, say so. If you think certain aspects should really be easier to use, easier to write, etc, explain those aspects and what you'd like to see different. No danger of losing points for honesty here (you'll only lose points for problems that we can detect without reading your report) -- we just want to hear your assessment as we determine our own.

What to Turn in

1. A file project.rkt containing your work for this phase. Include your project report (see above) as a block comment (using #| and |#) at the front of the file.

Submit these via turnin, under the name Project Final

• You are welcome to add extra kinds of animation to your language, but new features will not make up for missing required elements of your language. Adding features while your program isn't yet robust will cost you points.

• We will grade your report for writing (complete sentences, spelling, punctuation, clarity, etc) as well as technical content.

• We will look for whether you followed good coding practices, such as contracts, purposes, helper functions and test case coverage (see above).

• We will NOT deduct points for details regarding the relative coordinates of graphics, such as whether a circle hitting a rectangle overlaps the rectangle slightly before your program detects the hit or whether a bounce happens a couple of pixels early. We care that you see how to structure a language implementation, not that you precisely implement graphics-manipulation algorithms.

• You may use any Racket function or syntax in the Pretty Big language that does not have an exclamation point in its name, except that you are allowed to use set! to update one or two global variables (see guidelines). However, be aware that you can get an A and do a beautiful job of the code using only the functions and syntax introduced in class.

Violations of this policy follow the general course collaboration policy, and will likely result in an NR for the course.

Why this policy? Given the fairly open collaboration policy on homeworks, this assignment helps us assess how much each student understands of the course material. Since some students struggle in timed situations such as exams, the project gives you a more open-ended setting in which to demonstrate what you've understood of the course material.