how to run and use bomb
-----------------------


platform-specific information:

linux

  if the DISPLAY environment variable is set, then bomb opens an X
  window and runs there.  8, 16, and 24-bit displays are supported.

  otherwise bomb uses svgalib, and must be run as root in a `graphics
  capable virtual console'.  the usual way to get this is to hit
  Control-Alt-F2 and log in as root.  this one runs full-screen and at
  a higher frame-rate than with X.

  the file guile.txt documents how to script bomb in lisp, so that you
  can compose rather than improvise.

  set the "fps" environment variable to control the frames per second.


mac

  big-bomb runs with replicated pixels, so it fills more of the screen.

  ssaver-bomb exits on keyboard input so that it can work as a screen
  saver with autolaunch (http://www.stclairsw.com/alch_bg.html).

  for best effect, set your screen to eight bits per pixel and the
  lowest number of pixels.


win32

  make sure you used a 32-bit unzip program (one that supports long
  file names).



basic operation
---------------

if you run it and leave it alone (ie don't touch the keyboard), it
will go into automatic mode (automode).  put on your favorite audio
CD, sit back, and enjoy the show.  use Control-C or ESC (or Command-Q
on the mac) to exit.

a collection of ~20 parameters control how the image on the screen
changes.  each parameter set defines a particular texture, shape, or
effect.  as long as the parameters remain unchanged the same basic
visual pattern will evolve on screen.  in automode the parameters are
occasionally varied at random.

`bomb' starts out with roughly the same parameters every time: a
boiling texture dissolving the title page. if you wait, the parameters
will change and new effects will appear.


keyboard commands
-----------------

it's also possible to change the parameters manually with the
keyboard.  the space bar randomizes all parameters and clears the
screen.  it can be used as a `reject button': if the program is doing
something stupid, hit the space bar and a new (and hopefully better)
effect will appear.  this is the crudest possible control.

the rest of the keys are mapped to commands that adjust the various
parameters.  the normal layout is described below.  access to the
easier-to-remember `mood organ' mappings follow.

the middle row of keys (asdfghjkl;') changes the rule.  the rule
controls the basic algorithm used by the effect.  variants of a rule
can be accessed by pressing the same key repeatedly (try hitting
'f' or 'g' several times).

  a  rug          2
  s  image rug    1
  d  RD           2  (RD = reaction/diffusion)
  f  rotor/flame  9
  g  acidlife     2
  h  multi rug    1
  j  anneal rug   2
  k  slip         1
  l  rug rug      1
  ;  brain rug    1
  '  fish/slugs   2
  A  static       1
  F  fuse         4
  G  quad         1


the lower row of keys (zxcvbn) randomize individual parameters for
finer control:

  z  change speed/texture
  x  fill screen
  c  change color
  v  next shape
  b  next shape II
  n  toggle rhythm
  m  next shape III

v is context sensitive, think of it as getting the `next shape'.  eg
in image rule it loads a new image, in rotor rule it picks a new
harmony or flame, in the brain it changes the excitation rules.  b is
a variant of v, be sure to try it with the brain.  use m and b with
RD.  m in image mode uses the image sequences.



the top row selects an individual parameter to vary.  after the
parameter is selected, the ,. keys (unshifted <>) move the value up
and down.  eg while in image rule try pressing r, then several commas.
you can also type a number followed by RETURN to enter a specific
value, or repeatedly hit the parameter key to increment/toggle the
value (try uuuu)

  q  color map
  w  beat size
  e  beat speed
  r  texture/speed
  t  # icons in window
  y  icon sequence
  u  toggle smooth color
  i  texture/mask -- unusable
  o  misc
  p  blit rect size
  [  speed of shape change
  ]  speed of driver rule
  \  assoc search time
  {  hot time
  }  cool time
  |  brain rule
  P  brain shift
  O  cycle bkg (in rug2)
  I  smooth/random underflow

advanced behavior
-----------------

  B   fade to black
  Q   enter automode
  0   (zero) disable automode
  L   toggle mode lock
  =   dump frame to dribble dir (PPM format)
  +   toggle periodic dribble
  Z   new image and clear screen (good for image mode)
  WER pulse colormap
  C   invert driver
  /   load driver
  D   permute colormap by rotating bits of indices (press 8 times = identity)
  S   toggle smooth/plain cmap
  J   double board horiz
  H   double board vert
 ^F   toggle display frame rate and audio input (not on linux)

random, useless, and broken
---------------------------

  Y   cooler
  U   hotter
  V   previous drift pattern
  T   brighten


other organs
------------

the above keyboard commands allow exploration of bomb's entire
parameter space, but by using clumsy random-walking and type-a-number
interfaces.  keybaord mappings called `organs' allow you to (eg) map a
single parameter across the whole keyboard.  in these modes the space
bar and exit-program commands still function, but all the other keys
(including shift and control combinations) are mapped to the
parameter.

the basic organs are

  1     standard
  2     mood
  3     shape
  4     color

[[ currently the digits 1-4 have been hijacked and are bound to change
   the organ rather than type-in-numbers ]]

bomb starts out with the standard organ described above.  the shape
organ drives with different images.  the color organ picks the
colormap (even keys produce smooth/looped colors; odd keys produce
plain colormaps).  the mood organ binds entire parameter sets to
individual keys (only a-n so far).



audio input
-----------

the mac, SGI, and win32 versions support audio input.  as of now,
bomb makes only minimal and rather simplistic use of the audio
signal.  some of the modes are uneffected by audio; 's' and ';'
are two that work relatively well.

the 'n' key toggles use of audio, if available and applicable.

on win32, a beep during startup indicates that the audio driver
could not be opened, and bomb will run without it.

