ScriptX Animation Library

Design Document and Building Instructions

Don Hopkins, Kaleida Labs.

Design Document

Description:

The Animation class is an abstract protocol for playing named animation sequences.

Each Animation object has a set of named sequences it knows how to play. You can ask it for the names of its actions, tell it to play an action, find out if an action is playing, wait till an action is finished, cancel an ongoing action, pause and resume animation, and get notification of actions starting, flipping frames, and finishing.

Purpose:

The Animation class does not dictate any particular kind of animation, it just serves as an interface between media specific drivers and title specific behavior. It hides the drivers from the behavior, so animation of many different types can play together. The abstract Animation class is the least common denominator across many different kinds of animation, and does not implement any presentation itself.

There are many Animation media subclasses that implement different forms of animation using various media types and algorithms. Each animated object must inherit from exactly one of those. There are also many optional mixins that implement higher level behavior, and animated objects can inherit from any of these they need, as well as title specific mixins that serve as glue between the title and arbitrary plug-in animations.

ScriptX titles can dynamically import any type of animation at run time, by binding to the Animation media subclass required to play the particular media type, and mixing in title specific Animation subclasses, that allow it to interoperate with other objects in the title.

Usage:

The interface to instantiating new animation objects is consistant across all media types. There is one required key argument passed into init, which is "media:", a keyed list (or HashTable), with certain key/value pairs defined in it, depending on the media type. There is one required key that tells the name of the required Animation media subclass, that knows how to interpret the rest of the keys.

Instead of distributing actual instances of Animation subclasses in accessory containers, you distribute the media table, which contains the name of the required Animation subclass, and all the information necessary to create the animation. You do not want to distribute actual instances of the Animation media subclass in the title container, because then it will be too late for titles importing the objects to mix other Animation subclasses in with the Animation media subclass. Instead, you supply the data and the driver, so titles importing the animations have a chance to mix their own behaviors in with the drivers at run time before instantiating the animations.

The anim.sxl animation library contains a set of Animation media subclasses, but the title containers with animation media can contain their own copy of the required media subclass, to be used in case it's not already defined in the Animation module. We bind to the Animation media subclass by name, and check to see if it's already defined in the Animation module first, only loading it from the container if necessary. This is so if you have several instances that use the same drivers, they will all share the same code, and if you have custom drivers that implement certain types of animation more efficiently (like taking advantage of accellerators), you can load those in before importing animations, and they will run faster. Dynamically binding by name to the media class at runtime also allows you to develop authoring tools by defining editable media driver subclasses that let you create new animations and save them out as media tables, to be used with simpler play-only drivers distributed in the animation accessory containers to be used by customers.

It's good practice to store lower level built-in ScriptX objects in the animation media table, like bitmaps, arrays, and keyed lists, instead of instances of your own classes. That way you have more flexability to change your own classes, and your persistant objects will not be obsoleted because their classes change from under them. Your Animation media subclasses can rehydrate those low level object into instances of your own specialized classes at run-time, dynamically binding to those classes by name, so you can upgrade them at a later time, without having to rebuild and replace all your animation containers. This can also result in smaller storage containers because you're storing fewer high level objects, and just storing the code to create those objects instead (algorithmic compression).

To be done:

We need conventions for keys and values! The animation library is a start, but needs to be formalized so other media types can do the same thing and be handled properly. An accessory container should be a keyed list with certain well-known keys in it.

Right now I'm using a key called @media to hold the animation media table, which itself is a keyed list with a key identifying the name of the animation media subclass, that knows how to deal with rest of the keys. I think the key in the animation accessory container should be renamed @animationMedia to be more specific about the format, and we can define other accessory keys like @bitmapMedia, @audioMedia, or @playerMedia, etc, that have their own self identifying formats and drivers.

Building the animation library and demos:

Building Overview:

First you must make the animation library by loading "makeanim.sx". That will make a library container called "anim.sxl". After it compiles, you must quit ScriptX before building the demos. Next, you may build the demos of the various animation media subclasses, by loading "makedemo.sx", or loading the individual "mk*.sx" files in the "demos" folder. Those will make title containers in the anim directory that you can load into the Kaleida Media Player, to demostrate the animations.

Because they are so large, all of the media may not be installed or included with the distribution, so you may not be able to rebuild all of the animation demo title containers. But the ScriptX files that build them are included so you can see how they work.

Building the "anim" library:

Load "makeanim.sx" from the "anim" directory into ScriptX, and it will build "anim.sxl", the animation library, in that same directory.

Building the animation demos:

Load "makedemo.sx" from the "anim" directory into ScriptX, and it will build the animation demos from the "anim/demos" directory, as title containers in the "anim" directory.

Running the animation demos:

Load the title containers "dude.sxt", "eye.sxt", or "count.sxt" from the "anim" directory into the Kaleida Media Player, and press the words at the top of the windows to see the animations. You can drag the animations around with the mouse.

Building the director importer animation demos:

Note that before building, you must have the "dtk" and "dirimp" directories installed in the right place, the same directory as the ScriptX application. Copy the "anim.sxl" library from the "anim" directory to the "dtkanim" directory. Load "makedemo.sx" from the "dtkanim" directory into ScriptX, and it will build the musical instrument animation demos from the "anim/demos" directory, as title containers in the "dtkanim" directory. Copy the title containers "piano.sxt", "trumpet.sxt", and "violin.sxt" from the "dtkanim" directory into the "anim" directory.

Running the director importer animation demos:

Load the title containers "piano.sxt", "trumpet.sxt", or "violin.sxt" from the "dtkanim" directory into the Kaleida Media Player, and press the words at the top of the windows to see the animations. You can drag the animations around with the mouse.

Source Code and Media for the Animation Library:

The source code to the latest animation library is available here: anim.sit.Hqx
And the Director Toolkit animation importer demo is here: dtkanim.sit.Hqx

Here are all the files in the anim and animdtk directories, and a short explaination of their purpose:
  • anim/makeanim.sx
    Load this to build the anim.sxl library.
  • anim/anim.cls
    Defines the abstract Animation class.
  • anim/actorm.cls
    Media class that implements each frame as a group of bitmaps, AnimationActorMedia. Based on Warren's actor animation class. Good if you have to re-use lots of bitmaps in each frame, in different positions. Could be smarter about re-using presenters.
  • anim/bitmapm.cls
    Media class that implements each frame as a bitmap. This is probably the simplest and easiest kind of animation, though maybe not the most memory efficient. Dumb and fast.
  • anim/filmm.cls
    Media class that implements all frames as one tall bitmap, like a strip of film. This is quite memory efficient, since you only have one bitmap around instead of zillions! The frames of the single tall bitmap are used by all of the animation actions. Need a related class that represents each action as a filmstrip, so each can be stored separately, and you don't need to load all possible frames in at once.
  • anim/playerm.cls
    Media class that implements animations of players driven by their own clock. When you start an action, it starts the player, and it keeps going until the player hits the end of the action, however many frames that takes.
  • anim/pfarmm.cls
    Media class that implements playfarm character animations. Ideosynchratic playfarm behavior, and generic stuff that still needs to be factored out, like the action queue.
  • anim/scorem.cls
    Media class that implements animations of director score players. This would better be done as one score player per action, because it's slow to seek around in score players to play actions, the way this does. Need to modify the animimp.sx importer to do this.
  • anim/soundm.cls
    Mixin to play a sound and loop an action until the sound's over. Useful for miming to music (nillie vanilee would love this mixin).
  • anim/state.cls
    Mixin that implements a clickable state machine. Neat way to make specify interactive behaviors. Needs to be more general, though.
  • anim/shimmer.cls
    Mixin to randomly slow actions (to make playfarm flowers shimmer slowly). Bizarre but re-useable.
  • anim/animdemo.cls
    Class that implements animation demo, a window with buttons to animate each action.
  • anim/mediaimp.sx
    Utilities for importing media.
  • anim/animimp.sx
    Classes for importing labeled director scores an named animation sequences, using the DTK. This is a great example of the cool stuff you can do with the DTK, interoplating specially formatted director files into custom ScriptX objects. In this case, you just make a score, containing your animation action sequences with a label at the beginning of each one, and this will import them, composite the layers together into a single shrink-wrapped bitmap, and put it together into the proper format for the AnimationBitmapMedia class.
  • anim/anim.sxl
    The animation library. This contains the Animation class and a bunch of animation media subclasses, optional mixins, utilities for importing media, and a demo class.
  • anim/makedemo.sx
    Load this to build the demos of the animation media classes.
  • anim/demos
    This folder holds the builders and media for the animation demos.
  • anim/demos/mkcount.sx
    Make the counting hand animation demo, that uses the AnimationPlayerMedia class to play a quicktime movie of a counting hand.
  • anim/demos/mkdude.sx
    Make the playdoh dude head animation demo, that uses the AnimationFilmMedia class to spin the dude's head.
  • anim/demos/mkeye.sx
    Make the eyeball animation demo, that uses the AnimationBitmapMedia class to roll the eyeball around.
  • anim/demos/count.mov
    Flattened quicktime movie of a counting hand.
  • anim/demos/dudefilm.bmp
    Tall bitmap with frames of a spinning playdoh dude's head.
  • anim/demos/eye
    A folder full of eyeball bitmaps.
  • anim/count.sxt
    The counting hand animation demo. You can load this into the KMP.
  • anim/dude.sxt
    The playdoh dude head animation demo. You can load this into the KMP.
  • anim/eye.sxt
    The spinning eyeball animation demo. You can load this into the KMP, too!
  • dtkanim/makedemo.sx
    Load this to build the demos of the Animation classes using the Director Toolkit.
  • dtkanim/demos
    This folder holds the demos of the Animation class and the DTK.
  • dtkanim/demos/director
    This folder holds the director files that are imported as animations using the DTK.
  • dtkanim/demos/mkdirect.sx
    Load this to build the piano, trumpet, and violin animation demos. You must have the Director Toolkit installed (including the folders dtk and dirimp in the folder where ScriptX starts up.)
  • dtkanim/piano.sxt
    The piano animation demo. You can load this into the KMP.
  • dtkanim/trumpet.sxt
    The trumpet animation demo. You can load this into the KMP.
  • dtkanim/violin.sxt
    The violin animation demo. You can load this into the KMP.