w_title(pimputin)dnl
w_section(1)dnl
w_author(Panu Kalliokoski)dnl

! NAME

pimputin -- an interactive composition program

! SYNOPSIS

''pimputin'' [ -D /objects/ ] [ -p /probability/ ] [ -s /step/ ] [ -r /rank/ ] [ -S /sampleratio/ ] [ /sampledir/  /sampledir/ ... ]

! DESCRIPTION

''pimputin'' gives you a world with objects interacting in different
ways.  Many of the objects correspond to specific sounds, and play
the sound when collided / explicitly played.  The player may arrange
the objects so as to produce sequences.

Try it out with no arguments.  You'll discover soon enough how each
object behaves.  You're the white "@" in the top left corner.

''pimputin'' treats non-option arguments as directories of samples.
Each ordinary file in the directories is treated as a sample, and may be
dropped by the sample-dropping gnome.  If there are no samples, the gnome
never drops anything (boring!).  If you don't have sounds of your own,
try out /usr/share/sounds/.

! OPTIONS

-D /objects/::
	Set the set of /objects/ to be dropped randomly in the world.
	/objects/ is a string of characters corresponding to different
	objects in the world.  A "background daemon" adds new objects to
	the world, picking at random from this string.  If you want to
	increase the probability of a specific object, include it
	multiple times.  Default: "&&&=^#Oxe*"

-p /probability/::
	roughly sets how eagerly the object daemon adds new objects.
	Bigger values mean more objects.  Default: 10

-s /step/::
	sets the length of walls made by wall-creating "bugs" in the
	beginning.  Walls will lie on a grid with cell width & height
	equal to /step/ - 1.  Default: 5

-r /rank/::
	sets the number of generations after which the wall-creating
	"bugs" die.  Note that even if you don't set this, they will
	eventually clutter the screen enough to die anyway.  Default: 9

-S /sampleratio/::
	the sample-dropping gnome (violet "@") will drop samples
	randomly every /sampleratio/ +1'th time it stops.  Default: 0

! CONTROLS

The player is controlled by keypresses.  You can move with arrow keys;
pick up / drop things with space bar (also, you can drop stuff onto other
stuff with "a").

One of your holdings is always "active", the one to be
dropped if you drop stuff.  You can change the active item by numbers
1--8, and you can play the active holding with the lower part of the
keyboard.  "Z" = lower C, "X" = D, "C" = E, etc., and sharp / flat notes
are on the next row: "S" = lower C#, etc.

You can make the game objects go faster by pressing "+" and slower by
pressing "-".

Hitting ESC quits the game.

! SEE ALSO

python(1), esd(1), sox(1)

! BUGS

Playing through ''esd'' causes many problems.  The latency is too big,
and the sound gets messed up a lot if you play too many sounds at a time.
Also, the latency varies a lot, which destroys rhythm timings.  It would
be trivial to port ''pimputin'' to use ''arts''.  Both have the
problem that streaming samples through sockets wastes resources.

You have to start ''esd'' yourself.

Most really-unexpected exceptions are never caught; for example an
interrupted select() will bring the program down.  Also, ''pimputin''
does not support proper screen redrawing (yet).