Buddabing's Animation Language

I have designed the software to be capable of playing animations. An animation can be a series of flashing lights, a dimming or brightening effect, a light moving in sequence from one LED to another, and many other options.

With the aid of gl.tter's Light Signal Engine, animations can be tied to game events. In the game "Mr. Do", for example, an animation can be played whenever Mr. Do's ball is thrown. In the game "Tempest", an animation can be played whenever the Superzapper is activated. Animations, while not essential to game play, add a fun element to the user's cabinet. The use of animations is not limited to the MAME emulator. Any emulator which is open source can be modified to use animations. Daphne, for example, can be modified so that an animation plays when Dirk the Daring's sword is activated.

Animation Primitives

The animation compiler animaker.exe outputs a series of primitives. Animation primitives are a sequence of numbers, separated by one or more spaces. The first number in the sequence is the duration of the primitive, in milliseconds. The second number in the sequence is the starting port number on the LED controller board. On my LED controller, the port numbers run from 1 to 40. I have included support for up to four controllers connected at a time. Port numbers 41 to 80 map to the second controller, ports 81 to 120 to the third controller, and 121 to 160 map to the fourth controller.

Numbers after the first two are percentages. So a zero represents zero percent, and 100 represents 100%. On Buddabing's LED controller, there are only 17 levels of brightness. Other controllers may have more or fewer levels, and thus the percentage format is applicable to more controllers than just mine.

There are three special percentage values. 127 in the percentage field means to leave the previous value of that port unchanged. 128 in the percentage field sets the value of the port to a random value between zero and 100. 129 in the percentage field sets the value of the port to either zero or 100. The random values are done at runtime, thus the random animations will look different each time they are run.

Animation Language Constructs

repeat

Usage:
repeat repeat_count
{
   .... stuff to be repeated, including other repeats, multiplexes, or includes....
}

The repeat construct allows a primitive or sequence of primitive to be repeated multiple times.

This example will flash an LED attached to port 1 five times.

repeat 5
{
  ( 100 1 + )
  ( 100 1 0 )
}

There are two things to notice about this example. First, both animation primitives are enclosed in parentheses. Second, there is a plus in the first animation primitive. The plus is simply a shorthand for 100%.

random

Usage:
random
{
   duration start_port num_ports random_type
}

The random construct sets ports to random values.

The braces are required. The random type can be 1 or 2. Random type 1 sets the range of ports to a random value between 0 and 100. Random type 2 sets the range of ports randomly to either 0 or 100.

ramp

Usage:
ramp
{
   duration start_port num_ports starting_brightness ending_brightness
}

Light a series of ports, all the same brightness, in a gradual sequence from starting_brightness to ending_brightness.

The braces are required. Note that the starting and ending brightnesses don't have to be 100 or 0. Also, ramps can go up (ending brightness greater than starting brightness) or down (ending brightness less than starting brightness)

clear
Usage:
clear

This simple construct turns off all lights on all controllers. It has zero duration.

include
Usage:
include filename

All text within the include argument is substituted into the file. At this time, quotes are not permitted and filenames must not contain any spaces.

controllers
Usage:

controllers number

Compile the animation for the specified number of controllers. This can be omitted if you have only one LED controller.

multiplex

Usage:
multiplex
{
   sequence
   {
      ... sequence of primitives
   }
   sequence
   {
      ... sequence of primitives
   }
   ... more sequences of primitives
}

This powerful construct allows multiple separate animations to be played at the same time.

For example, you can flash a light on port 1 and on port 31 with the following construct:

multiplex
{
   sequence
   {
      repeat 10
      {
         ( 100 1 + )
         ( 100 1 0 )
      }
   }
   sequence
   {
      repeat 10
      {
         ( 100 31 + )
         ( 100 31 0 )
      }
   }
}