                  Müslifresser Softworx proudly presents...
 
                             B O O M E R A N G

                           a programming example                        (v1.4)


pinball machine design (c)1974 by Bally,
version for Visual Pinball copyleft 2001 by CYBERYOGI =CO=Windler

File list:
~~~~~~~~~~
This ZIP archive should be named "Boomerang1.4emu.zip" and contain the fol-
lowing components:

  Boomerang v1.4 aProgrammingExample.vpt" - the game itself
  Boomerang_aProgrammingExample.txt"      - manual (the text you are reading)
  privateParts_Boomerang.zip              - useful stuff for programmers
  Boomerang-flyer1.jpg                    - pinball machine flyer picture
  Boomerang-rules-flyer.jpg               - another flyer picture

You may not distribute modified versions of this ZIP archive under the same
name.

This game needs Visual Pinball 0.4.1930 and was successfully tested on a PC
with AMD K6 300MHz CPU and 128MB RAM.(A slightly slower PC may still work but
this game is quite CPU intensive due to the captive balls.)


About:
~~~~~~
Wellcome to the possibly world first emulated EM pinball game!

You may ask what I mean with emulation,because there are no ROMs nor anything
CPU-like in electro-mechanical pinball machines.But unlike ordinary simulations
of pinball game rules,the entire behaviour of this program is based on a model
of the inner working of the machine.Even the simulated score reel counters of
this program are so faithfully reproduced that they not just click and rotate,
but even can get stuck and hum when a ball lies on a playfield switch.

If you want to learn more about the technology behind this game or about Visual
Pinball programming,then urgently take a look into the source code.(Click
"script" button of Visual Pinball.) This work is an open source project that
employs literate programming,i.e. the code is commented very detailedly and
contains many explanations. This introduction text is rather short because most
info stands anyway there, including the seedware open source licence.


I am a cyberage-child,born in the year of Pong.I did not grew up with EM pin-
ball machines but with 8 bit videogames and homecomputers of the Artarian gene-
ration.A decade ago I restored a used Bally "Champ" EM pinball machine,but I
sold it soon because in the humid basement its paint (on the backglass etc.)
began to rot and also the relay contacts suffered badly from humidity.

I wrote this program because I want to help to create a technology to preserve
the experience of playing these games for future generations,and due to I
was annoyed by the tons of bad Visual Pinball EM remakes and a very impudent
wannabe programmer,as software-techniques student I decided to write a state-
of-the-art reference implementation to demonstrate what can be done with the VP
environment despite of its many limitations,flaws and bugs.

For video arcade games there is MAME,for home computers and consoles there is
MESS and also computerized pinball machines have been emulated with PinMAME,but
yet there was no solution for electro-mechanical pinball machines.With this
work I hope I can help to close the gap by providing a sort of framework for
building other emulations from.

What particularly fascinates me with electro-mechanical pinball hardware is
that this stuff has rhythm.Such a circuit consists of multiple dozens of relays
and contact wheels those get their signals from the so-called "score motor",
which is a motor-driven camshaft mechanism with many leaf switch contacts
that forms the main command sequencing unit of the machine.(For details see
source code.) When this camshaft rotates,all the relays and solenoid coils of
the machine begin to click,chatter,stomp and rattle with green sparking con-
tacts,depending on which relays are actually set.It is basically just digital
hardware based on Boolean logics,but unlike modern computers you can see and
hear it working (in a nutshell similar like the relay operated ancient "Zuse
V4" electronic brain) and it sounds partly like a mixture of an Indian tabla
drummer and tapdance because all actions are synchronized to that score motor.

As an art project I would love to build orchestrion-like mechanical tekkno
music machines,and for this I could imagine to construct a metal cabinet full
of rattling relays and solenoid-operated percussion instruments,and in the
center should be visibly mounted behind a glass pane a revolving Gottlieb score
motor which controls the produced rhythms. 

This acoustical aspect was totally missing in most simulated Visual Pinball EM
pinball games,and because the few ones those have mechanism sounds just play
pre-recorded samples instead of deriving their sounds from a model of the
internal mechanism,I decided to recreate the cybernetics of the inner working
by emulating the timing of the score motor.Due to I have very little hardware
information and even less sound samples of these machines,my emulation is 
likely everything but accurate,but important is that at least every sound it
makes belongs to an internal action and is not just played "because it is cool"
to play a mechanical noise here and there,like the fake chess android "The
Turk" of Baron Von Kempelen in the 18th cetury did.


Credits:
~~~~~~~
Many thanks to Randy Davis,who created Visual Pinball and though made my work 
and the revival of all these great historical pinball games possible.(What a
pity that there is no Linux version...) Also thanks to PeBo,who find out the
trick how to simulate a realistic looking mechanical reel score counter,to
Kurt Herman for the idea of round voxel graphics 3D targets and thanks to Boris
(?) for the highscore save and load routine.Thanks to Frank Gigliotti for the
tip and picture for the shiny ball.Also thanks to the Visual PinMAME team for
some sounds and especially very much thanks to Frank Menzler who donated the 
great Bally mechanism sound sample set from his nice "Fireball" VP game and
also helped me with details about the Bally hardware. And not to forget to 
thank to Bally for the beautiful pinball machine design.Thanks to Jeff Stue-
cheli for the detailed explanation of the original "Boomerang" game rules.

No thanks at all to an egomanic moron who refuses any programming help and
flamed me instead by his disgustingly self-rightous false pride.(But never to
forget: boomerangs come back - always! ;-) )


Notes:
~~~~~
-No matter what ever you may flame,I definitely won't remove the popup reques-
 ter at program start,because it does NOT disturb the game in any way.You not
 even need to fumble your mouse out of that waste paper basket under the desk
 where it always comes to rest when you search for it. ;-) It is not necessary
 to grasp a mouse to click the OK button;a simple hit on [return] is enough to
 get the thing out of your face immediately.

-My name is not "Cyber-Yogi" or the like,but CYBERYOGI =CO=Windler.Cyberyogi
 is just a spiritual title (much like "brother" for a monk) and neither a name
 nor my nickname.


The game:
~~~~~~~~
This game is a recreation of the historical Bally pinball machine "Boomerang"
from 1974. I chose this game for emulation because I knew this needed to be 
done when I fell in love with its shamanism inspired Australian Aborigine art-
work design,which provides a unique magical athmosphere in combination with
this strange,rythmical clicking and rattling mechanism that does its magical
drumming somewhere deep down in the depth of the machine.Yes,this thing is 
just virtual,but there are certainly not many of these machines left anymore,
and though for most people it will be likely the only "Boomerang" game they
will see in their life,therefore I tried to make my job good to preserve the
experience.


I knew little about this game and I was not sure what the intended game 
rules are,though I oriented myself on another,horrible VP simulation of it and
on my memories from Bally "Champ" game rules.Later Jeff Stuecheli helped me
to simulate the original Bally game rules more exactly.Due to these authentic
rules are very boring(way too easy to get maximum bonus,center bumper stays
always lit),I made the game rules switchable between an "authentic" and my own
"enhanced" mode,which is much more challenging and also has some different
light effects and sound design(bonus ladder etc.).

-On the center bumper stands "100 when lit" but in the other simulation it is 
 always on,therefore I added a rule that it starts unlit and is lit after the
 tophole is hit.Also my spinner scores only 10 points until the center bumper
 is lit,and 100 afterwards.

-In the playfield area around the center bumper there is a visible hole under
 each rubber band,out of that a metal part seems to tower up behind each
 rubber band.I thought they may be slingshots,but Jeff Stuecheli told me that
 these are simple leaf spring contacts those score each 10 points per hit.
 I could imagine that the ball should vigorously rattle around for many seconds
 in the Tribal Boomerang area and then come out in a difficultly predictable 
 angle.I made the center bumper quite strong to get such an effect,but the ball
 despite yet never bumps around for really long there.

-In the game there was apparently no way to get an extra ball without loosing
 the present ball trough the outlanes,though the "shoot again" in the other
 simulation only served the purpose of an outlane close gate or kickback in-
 stead of getting a "real" extra ball.I changed this by adding a rule that a
 tophole hit wins an extra ball when the bonus ladder has reached its end (i.e.
 bonus 15000).Jeff Stuecheli told me that the original machine can be adjusted
 in a way that the specials at captive ball lane ends serve the same purpose.
 Though I made them in enhanced mode score 10000 points and win an extra 
 credit,while in authentic mode they win a shoot again.

-In the other simulation I found a lousily programmed lock mechanism that
 prevents increasing the bonus twice when a captive ball rolls forward and
 back again over the same lit A,B,C or D rollover target.I included a similar
 (but reasonable programmed) mechanism into my emulation.Stuecheli explained
 that this is not authentic Bally,though I kept it only in in my enhanced game
 rules to make it more difficult to add bonus.


Frank Menzler told me various infos about the hardware behaviour of Bally EM
pinball machines.Due to I intended to design my emulation code as generic as
possible,I added various flags in the "pinball machine constants" section
of the sourcecode for switching the behaviour. If you think they are set
incorrectly or other things in my algorithm are wrong,please e-mail me.
e-mail: windle_c@informatik.fh-hamburg.de


How to play:
~~~~~~~~~~~
Press 'R' to see the game rules. Use 5,6,7 to insert washers and 'S' to start
or add players.(The 1st coin chute behaves like the start button.) '9' swit-
ches between authentic Bally game rules (IMO way too easy) and an enhanced 
game rule set created by me (more challenging).

To all pinball wizards: Have no fear to turnover the score display back to 0;
my "reel-a-listic"(tm) ;-) score counter will never give up and keep display-
ing your score by its own way even when you manage to turn all reels back to
0 (listen to it!).Also your highscore will be displayed and saved correctly.
IMO there is nothing more annoying than a too short score display - mine won't
give up despite its realistic appearance.


Subtle features and tricks:
~~~~~~~~~~~~~~~~~~~~~~~~~~
Due to this is an emulation,you can explore various strange behaviours of the
simulated mechanism:

-E.g. when your ball hits the outhole without scoring points,it will be re-
 ejected("fairplay interlock").Also when the ball lies in front of the plunger
 and you nudge it back into the eject chute (try this),it will be re-ejected
 by the same algorithm.

-When you overpay the 1st credit chute or add a player after the 1st ball,the
 game will reset.By suggestions of Frank Menzler I changed my reset algorithm
 to make the game also start immediately when the ball was still in the firing
 chute or on the playfield when the reset was done in the middle of a game.
 Also the start button can reset the game.

-Any coins will be rejected when the credit counter is at maximum (25 credits).

-When you tilt during bonus collection,the playfield lights will go off and
 the rest of the bonus will not be added to the score anymore.When "Double 
 Bonus" was lit(lets the bonus ladder decrement slower),it will be cleared
 by the tilt and though speed up the bonus ladder countdown.(Is the speed
 of my bonus ladder emulated authentic?)

-The "shoot again" lamp stays on until points are scored.It stays also on
 during tilt (is this correct?).

-When you insert coins while the score motor is running(or credits are added)
 you will hear the coin plummeting back into the coin eject chute because
 there is a wild clicking rejector mechanism in the coin door that refuses
 coins under this condition because the credit add mechanism of a real pinball
 machine would count wrong when the motor is not at its 0 position.

If any of these features are incorrect,please e-mail me.

And remember,this is open source.If you want to learn Visual Pinball program-
ming,then urgently take a look at the source code.


Operator settings:
~~~~~~~~~~~~~~~~~
-In the "operator settings" section of the source code you can adjust the
 tilt sensitivity,balls per play and various other parameters.

-This game saves highscores in the User directory of Visual Pinball.To reset
 the highscore,simply delete the "Boomerang_highscore.txt" file. To disable
 highscore saving set highScoreFileName=false in the "operator settings"
 section of the source code.

-You may also change some parameters in the "pinball machine constants"
 section,but these are not intended as user settings an can mess up or crash
 the emulation when set wrongly.Especially the interaction of various timers
 reacts very sensitive on changes,and some settings make only sense to be
 changed when components on the backbox or playfield are changed also (e.g.
 number of score counters per machine).


Known bugs and limitations:
~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Sometimes sound samples play at wrong times;especially a score counter chime
 is sometimes played after game over or after bonus counting,although theoreti-
 cally it can only sound when a score reel digit flipps (which is impossible
 after game over).I guess this is a Visual Pinball bug caused by the extremely
 high polyphony load that my emulator causes in some situations.Also certain
 noises (e.g. creditCounter.wav) sound thinner and quieter than they should.
 I already used various tricks to reduce the polyphony which reduced these 
 bugs,but in some situations it doesn't help.

-The credit counter sometimes counted wrong due to a race condition between the
 scoreMotor timer and the creditAdder timer despite correctly calculated timing
 (a Visual Pinball bug?).I circumvented this flaw by incrementing the credit
 variable already before starting the creditAdd timer and only update the credit
 display and play a sound by it. Though when the problem occures (happens only
 on slow PCs like mine?),the counter only knocks too few times but still counts
 correctly.

-The spinner sometimes ignores edge hits. This is a Visual Pinball bug and not
 caused by me. To make the spinner wider and use transparent rims would be a
 solution (I first tried this),but it would need to have invisible rims this
 way which doesn't look realistic.

-I don't know if my score motor speed is realistic. The cam positions were
 just tweaked by ear by listening to some sound samples (e.g. bell100-5.wav,
 bell1000-3.wav and some reset noises).By suggestion of Frank Menzler I placed
 the cams of the 5 cam wheel now in the same distance like the 6 cam wheel to
 get an audible pause between the 2 5er groups of clicks during score counter
 reset. Possibly the speed is also mains frequency dependant(50 vs. 60Hz) be-
 cause 5 pulse sound samples of different Visual Pinball games rattle with 
 very noticible different speeds.

-The right,yellow wood rim of the playfield is missing in this game.Although 
 it would be theoretically possible to edit the playfield pictures to add it
 by hand,I left it away because the wider playfield would just reduce the
 space for the background graphics further.Due to my game is not a fully rea-
 listic but rather impressionistic interpretation of the pinball machine,I
 I did not attempt to simulate the cabinet shape correctly.Generally the real
 pinball cabinet rim would be likely much wider and though waste more screen
 space when exactly simulated.

-The left and right artificial cabinet edges are displayed black instead of
 metal grey,because they are outside the playfield coordinate system.(This is
 a Visual Pinball bug.)

-Various mechanical sounds may be quite off.Especially the relay click was
 recorded from a Bally "Fireball" reset relay,which unlike other relay is
 placed in the backbox,though the relay timbre may be totally off.The noise
 of multiple simultaneous clicking relays is in reality likely very different
 due to the emulator just plays the same sample with a higher polyphony and
 no intentional delay between the clicks,which may cause bad phasing distor-
 tions.Also the state wheel reset noises are fake may be too loud.(For more
 sound details about the used samples and problems see source code.) The score
 counter reset noises are an approximation and may sound quite wrong when many
 counters spin simultaneously.

-The ball rolling noise is just simulated by invisible playfield rollover 
 triggers those start samples,though it may be sometimes a little out of
 sync with the ball motion.(I find it quite ok,but people those are habitted
 to play on real pinball machines may find it sounds strange.) I already stop
 the sound where the ball is known to be motionless,but by my knowledge a phy-
 sically correct simulation of ball rolling noise is not possible with Visual
 Pinbal yet,because there is neither a way yet to detect the actual ball po-
 sition directly,nor to control the volume and pitch of a sound sample.
 (The noises can be disabled from 'operator settings'.)

-The real pinball machine has a "100000" lamp for each player below the "1-up"
 etc. lamp to memorize the 1st 100000 points when the score counter overflows.
 I did not simulate this feature,because my reel-a-listic score counter can
 handle extra digits anyway and though an additional light-up "100000" would
 only confuse the player.

-Jeff Stuecheli told me that the "special" lamps at the captive ball lanes 
 were light blue on his pinball machine,though I also changed mine this way,
 because it looks better.But on the playfield picture from the Shiva site they
 look definitely very redish(remove these lamps on my VP playfield to see it),
 though I am not sure if there were multiple different versions of the machine
 made.
 

Private parts:
~~~~~~~~~~~~~
In the "privateParts" ZIP file you can find some graphical elements etc.
those may be useful for other Visual Pinball programmers.Most of the .bmp
picture files use black (RGB 0,0,0) or white (RGB 255,255,255) as the trans-
parent colour;only red100_rastered.bmp (bumper texture) uses RGB 240,240,240
instead.

The picture Boome_man.bmp was included as an example how semi-transparent
decals can be designed;note the 2 different perforation styles to change the
degree of translucency. The files grey1.bmp and grey2.bmp are samples of
the perforation I used for transparency.Important is that the raster used in
grey2.bmp looks only correct when at all intended screen resolutions the
picture size stays at least twice the visible decal size;otherwise the
perforation holes will become visible which looks really ugly.Boome_score1.bmp
is an example how the semi-transparent score counter frames are designed.

Also the picture Boome_acryl.bmp is an example how transparent parts can be
simulated.It basically consists of 2 vertically shifted versions of the out-
lines of the acryl parts;one is a little greyer than the other.

The spinner4.bmp is an experimental version of the texture I tried with a
wider-than-visible spinner to prevent the edge hit bug,but this is not part
of the current "Boomerang" version because trhe spinner rims look wrong so far
they are not set to transparent(black) when using this.

The target*.bmp decals were not used in this game because I found better
methods to create round targets than pasting 2D stickers on the backdrop.

The file BoomerangNoMotorVBS.txt contains an obsolete and incomplete source
code version of this game,which employs traditional simulation techniques in-
stead of emulation.You may find it usefull for programming own,non-mechanical
pinball games because there are e.g. quite versatile bonus counting routines
in it.

...and now enjoy playing pinball.


Revision history:
~~~~~~~~~~~~~~~~~
Version 1.4:

-Dual game rules selection added: This provides a completely new,authentic 
 Bally "Boomerang" rule set.(Thanks to Jeff Stuecheli for game description.)
 Due to the authentic game rules are quite boring and earning bonus points is
 ridiculously easy(any lit rollovers always increment bonus),I kept a slightly
 modified version of the previous rule set selectable as a more challenging
 "enhanced mode".(Both have independend highscore saving and some independent
 operator settings.)

-4 leaf switches behind the rubber bands in the Tribal Center area added,those
 score each 10 points per hit when the center bumper is lit (i.e. in authentic
 mode always).Also the yellow center targets now advance the spinner lights
 when center bumper lit.

-Various playfield tweaks done.This makes e.g. the captive ball lanes more 
 challenging.(Yes,it is intended that the captive ball reaches the lane end
 special target only at a particular hit angle and not always anymore.) It is
 also easier now to shoot the ball back to the top to hit the tophole.

-"Special" lamps colour changed from red to light blue.

-Made the wire guides below the flippers droppable to prevent balls getting
 stuck under the flippers.(This bug may have been just a cosmetical problem,
 but it behaved unrealistic and especially it might have crashed very slow PCs
 by excessive CPU load consumption.)

-Appearance of bonus ladder and spinner lights in authentic game rule mode
 changed from "bar" to "dot" display (authentic Bally);also 1 spinner lamp
 stays always on in this mode (is this correct?).Bonus ladder counting speed
 changed.(Jeff Stuecheli told me that the real pinball machine counts faster
 and not longer while collecting double bonus.)
 In my enhanced mode I kept both like the old version - I like the previous
 light and sound design of the bonus ladder much better because it counts fas-
 ter and sounds more powerful.(This way the player is also reminded in which
 mode he his actually playing.)

-Bug fixed that didn't turn off playfield lights when game over happened 
 after tilt.

-Many game state parameters are saved now (e.g. credits,spinner state,score
 displays and the previously selected game rule set).

 Note: I changed the name of the highscore entry in the Boomerang_highscore
       .txt file,because now there are 2 independant highscores and the game
       rules etc. have changed since v1.3 in a way that both rule sets are not
       identical with the old version (but the "enhanced" version is close).
       Though write your old highscore down or copy the file before starting
       the new game if you don't want to loose it.


Version 1.3:

-Seedware open source licence updated to 1.1,to make it clearer how to treat
 existing code when merged with seedware parts.

-Operator settings constant ballRollNoisesEnabled added,to make it possible
 to switch the ball roll noises off. (This also helps to reduce the CPU load
 of this game when it jerks on slow PCs).Also made the click of round roll-
 overs quieter and a damper hit quits the ball rolling noise now (important
 for plunger sound behaviour).

-Much more realistic looking shiny balls added; the previous ones looked like
 when a child had them in his jeans pockets for 3 years. ;-) Thanks to Frank
 Gigliotti for the tip and the picture for the shiny ball. (I modified con-
 trast, brightness and the transparent part of the picture to make it match 
 better with the playfield. You can find 2 versions of it in the privatParts
 ZIP file.)


Version 1.2:

-Credit counter blocks now coin chutes when at maximum credit.

-Start button can now reset/quit a running game. (Both is authentic Bally.)

-Made the metal front cover (with the instruction cards) a bit higher than the
 rest of the playfield. Due to it is now made from one piece,this also fixes
 the black outline pixel rubbish that might have been visible at the outhole
 mould rims at certain screen resolutions.


Version 1.1:

-Reset sequence algorithm changed to start a game without waiting that the
 ball returns to the outhole;though the score motor now doesn't hum forever
 anymore when the ball is still in the firing chute.

-Score motor cam placement and speed tweaked to make the score counter reset
 rhythm sound more realistic.(I made the pause between the groups of 5 pul-
 ses longer.)

-Center bumper loudness increased.

-2 flyer pictures included into ZIP archive.


Version 1.0:

-initial release.


                        MAY THE SOFTWARE BE WITH YOU!


*============================================================================*
I                  CYBERYOGI Christian Oliver(=CO=) Windler                  I
I         (teachmaster of LOGOLOGIE - the first cyberage-religion!)          I
I                                      !                                     I
*=============================ABANDON=THE=BRUTALITY==========================*
        {http://www.informatik.fh-hamburg.de/~windle_c/e_index.html}

e-mail: windle_c@informatik.fh-hamburg.de
