                            -------------------
                            README file for Bub
                            -------------------

           This version number last payed attention to at v0.99

        Bub is by Brad Spencer <spencer@jacknife.spoon.org>.  This is not
        finished but I'm releasing it now or it will never get out.

                The official Bub homepage can be found at
                  http://jacknife.spoon.org/~spencer/bub.html

What is this?
-------------

        It's a game.  If you want to read the rules, they're below.
        If you want to play, just read some of this so you know how to
        start the thing and then figure them out.

Features:
---------

    This includes a mostly working version of the game, including:

        - High score table
        - A cool title screen.
        - crappy sound effects (-q to turn off sound)
        - null-modem style two-player mode (specify port, irq and bps) with
          the proper rules [32-bit version currently only supports standard
		  IRQs.  See section on command line parameters and the
		  CHANGES.TXT file for more info.]
        - You can pause the game with the Pause key
        - You can continue, but if you do you're not allowed to add your
          name to the highscore list.
        - fast 32-bit code generated by the best compiler in the world, GCC
          (D. J. Delorie's DOS port of GCC, actually: DJGPP v2)
        - standard 16-bit-ish (Borland generated, 386+) code version
          called BUB16.EXE
        - super-compatible BUB286.EXE :)  Now everyone can play!
        - my still-in-the-works ChudMod sound system for great S3M music
          during play (32-bit version only)
        - music by Paul Medynski (aka Reepicheep) designed especially for
          the game (soon)

What are the command-line parameters?
-------------------------------------

        -q      Turns off all sound support (including detection).
        -f <s3mfile>[.s3m]   Play <s3mfile>.S3M as the music file instead
                             of the default song.  Now you can use Bub as
                             a GUS S3M player :)  [32-bit version only]

        Two player mode options:

		*** NOW SUPPORTED IN ALL VERSIONS! ***

        -pXXX   Specify UART's address, in hex. (ex -p2f8 for "com2")
        -iX     Specify UART's IRQ line, in decimal (ex -i3 for "com2")
        -bXXXXX Specify line speed (see below for supported speeds)
        -m      Designate self as master.  One and only one player should
                use this switch.
        -o      Use the 'old school' alpha stage two-player rules that
                we got sort got fond of.

        The switches are order independent.

        See the section on two player mode for more information about
        the serial port settings.

How fast does my machine have to be to play?
--------------------------------------------

        Not too fast, I hope.  I use "Lister", a 486SX33 with 1 whole
        meg of RAM and a $10 Trident video card as my "minimum platform".
        He has no problems at all in DOS.  Under Win95, the video can
        slow down a bit.

        You do need a 386 or above however, since that's how I compiled
        the code.  If you are _really_ desparate, I've compiled a 286
        version based on the same source code as BUB16.EXE :)  [I don't have
        one of these, so I can't test it properly, but I've been told it
        does indeed work.]  The 32-bit version may require a bit more
        horsepower because of the music player and all.  Only the source
        tree for BUB32 has been updated in the last year.

        VGA required, of course.  This sucker runs in 320x240 Mode X.

What keys do I use?
-------------------

        SPACE - shoot
        LEFT  - move aimer left
        RIGHT - move aimer right
        PAUSE - pause game   [This doesn't work in two-player mode :)]
        ESC   - give up

What are the one-player rules?
------------------------------

        Shoot bubbles to burst bubbles.  If, by shooting a coloured ball
        at the 'pit', you create a set of three or more touching balls of
        the same colour, they burst.  Pre-set strings of balls with more
        than three balls of the same colour touching do not automatically
        burst.  They were put there very carefully and are quite happy
        until you disturb them.  Any ball which then ends up being a
        'floater' as a result of bursting is then known as a 'dropped ball'.
        The dropped balls will also burst (i.e. fall off the playfield).
        The object of the game is to win all of the levels.  You have one
        chance, like in real life :)

        The next ball you will be given is displayed to the left of the
        launcher.  The game never gives you a 'next ball' of a colour that
        is not in the pit, but since you may eliminate a colour while
        a ball of that colour is the 'next ball', you may find yourself
        re-introducing a colour to the playfield.  The trick is to avoid
        doing this by always knowing what the next ball is going to be.

        Scoring is a bit crazy.  Say you burst n balls of the same
        colour with a shot.  You get 10 * n points.  But if you drop say k
        balls by bursting that set, you get 10 * 2^k points as well.  If
        you are good enough to get over 1000 pts this way, your drop
        bonus is displayed for a few seconds to the left of the playfield
        just so you can have a number to associate with your cornucopia
        of coolness.

        For example:

               +---------------+
               |1 1 1 1 2 3 4 5|    Say you shoot and land a ball of colour
               | 2 3 1 3 4 5 6 |    1 where the X is.  This will match with
               |3     X        |    the other 5 1s and burst them.  Thus, you
               | 4             |    get (1 + 5) * 10 = 60 pts.  However, you
               |6 2            |    have also dropped all of those balls on
               |               |    the left (5 of them), so you get an
               |               |    additional 10 * 2^5 = 320 points.
               |               |

        So the key to high scores is dropping balls.  After 17 dropped balls
        the drop bonuses max out at 10 * 2^17 = 1310720.  Yup, 1.3 million.

        The roof will fall every so often.  Before it does, you get a
        a warning, currently a flashing launcher.  When the
        launcher is flashing slow, you have two shots left.  A rapidly
        flashing launcher indicates that you only have one shot remaining
        before the roof falls.  You may wonder why you only get 4 shots
        between roof falls on the first level but 8 shots on level 3.
        [Why does this part of the readme file sound like it was translated
        from Japanese?]  Essential the roof falls every
        (8 - (# of balls not in the pit)) shots.  This number is recalulated
        after every shot has been handled (including the moving the roof
        if necessary).  The one exception to the rule is that once the roof
        has gone into early-warning mode, it can't jump back out.  Also,
        the roof is not allowed to fall before giving ample warning.
        I suppose this doesn't really affect the player that much, but it
        is good to know.  The roof will never fall without warning, but
        once you see the warning, the roof will always fall as scheduled.

        EXCEPTION: Some levels (like #4) were just plain too hard with the
        formula roof drops, so there is an override value that is used
        for the particularily difficult or unusual levels.  Hopefully,
        things will be fair this way.  (Without it, finishing level 4 was
        impossible.)

        You lose when a ball lies in the 'void', the first row with the
        red background.  You can, however safely shoot a ball which will
        end up in the void provided it bursts immediately upon contact.
        Try it, you'll understand.

        You win when you beat all of the levels in the game.  Currently,
        there are 20 levels.  You can "continue" if you want to see
        the higher levels.  In the arcade, you can throw quarters in the
        machine all day if you want.  Same with continues here.  You can
        _not_ add your name to the high score list after you have continued,
        however, so this is not the way to get monster scores.

What are the two-player rules?
------------------------------

        The goal in two player mode is to either clear your board (so
        amazingly hard that it can be considered impossible) or make your
        opponent lose.

        The rules in two-player mode are significantly complicated.  First,
        there's a 'stack' which is _shared_ by the two players.  Bursting
        and dropping balls sends them to the stack -- sometimes.  Here are
        the rules:

                - If n balls of the same colour are burst, then
                  n - 3 balls are added to the stack.
                - If m balls are dropped as the result of a burst, then
                  m balls are added to the stack AND the stack is sent
                  to the other player.
               
        By 'sent to the other player', I mean that the other guy receives
        all of the balls that were on the stack _on_his_screen_.  Each ball
        on the stack starts in a random column inside the void and 'bubbles'
        up until it bumps into something.  This makes the player who
        receives the stack very very angry :)  Note:

                - By bursting three bubbles that have a ball of a
                  different colour dangling on, you can instantly send
                  a stack of one to the other guy.  (Provided the stack
                  was zero when you did this, otherwise you'd send a lot
                  more and should probably duck under the desk or wear
                  a disguise.)
                - The stack is _shared_ between the two players.  It builds
                  up until one of the two players drops a ball.

        In two player mode, the size of the stack is displayed on the right
        hand side of the screen.  Note that the colour of the balls is
        not important (read 'random').  Score is still there incase you
        do something very cool and want to see how many points you have, but
        you can not get a high score in two-player mode.

        The roof doesn't fall in two player mode, but instead, something
        worse happens.  [I placed this break here to make you wonder
        what could possibly be worse than a falling roof.]  The existing
        rows in the playfield still move down, but the top row is replaced
        with a new row of random balls.  Muwhauahwuahruhruahrauwhuahhahaha!
        So, technically, you can play forever (I hope that Tetris math guy
        doesn't read this), but don't consider it a realistic goal, no
        matter what your therapist told you.  [What?  You don't have a
        therapist?  I guess you decided to read the instructions _before_
        you played the game. :)]

        If you specify -o on the command line, the rules for two-player mode
        change and nothing falls.

        So, you know, make the other guy lose.  

How do I play this thing 2-player?
----------------------------------

        Just setup a serial connection (8 bits, no pairity, 1 stop bit)
        at any normal serial speed up to 115200 bps.  Then start
        the game with the appropriate parameters, and it will switch into
        two-player mode.  Note that Bub sends an average of about a byte
        every couple of seconds, so you could probably safely play this
        game via smoke-signals.  I've tried it with IHHD (Internet
        Head-to-Head Daemon) and it works fine.

        One machine has to be the master and one the slave.  Why?  Cause
        it's easier for me that way :)

        In case you're a complete tool:  Both machines need to use the
        same line speed, but they can use different communications
        ports.  [Yeah, maybe that is a bit rude.]

        For example:

        On one machine, which is using "com2", type:

                bub32 -p2f8 -i3 -b9600 -m

        and on the other, using "com1", type:
                
                bub32 -p3f8 -i4 -b9600 -m

        [Substitute BUB16 or BUB286 where appropriate.]

        The game will negotiate for a few milliseconds and then startup
        right into the play screen.

        Ok, now I know what you're all not thinking:  Will it support my
        strange serial port which uses port 0x7ff and IRQ 97?  Well, it
        would probably be okay with the port, but Bub's a bit more picky
        when it comes to IRQs.  Currently, IRQs 3, 4, 5, and 7 are supported
        for serial communications, but only 3 has really been tested to
        any degree.  If you use one of the others, PLEASE let me know if
        it works or not!  Thanks!  If you use IRQ 2 or some such nonsense,
        open up your machine right now and change it!  Yuck! :)

        If you see a small white dot in the top-left corner of the screen,
        that means an invalid packet was received by the game.  I was
        getting these via IHHD (only on the slave end), but it didn't seem
        to affect gameplay.  It has never happened over a standard modem
        or serial cable connection.

Huh?  How do I play this thing 2-player over the modem?  ... the Internet?
--------------------------------------------------------------------------

        First, read the section above.

        The modem:

          - Find out what "COM port" your modem is on.  In specific,
            determine your UART's (i.e. "COM port"'s) base address and IRQ.

            Standard values are (given as Bub command line options):

                COM1:   -p3f8 -i4
                COM2:   -p2f8 -i3
                COM3:   -p3e8 -i4
                COM4:   -p2e8 -i3

            Note that if you have an (ugh) internal modem, you will almost
            never have the default settings :(  You will have to do one
            of the following:

                a) Open your case and read the jumper settings if you are
                   lucky enough to not have a PnP modem.  (I'm serious.)

            OR  b) Load Windows 95, goto the Control Panel, open System
                   find your modem on the list and check its resources.

            OR  c) Ask someone who knows.  

          - Load Telemate, err, I mean load your favorite terminal program.
          - Set the port settings to something Bub supports (like almost
            anything), and remember them!  You need to know the base address
            and IRQ as mentioned above, but you also need to know the line
            speed.
          - Call your friend (or enemy, as the case may be).
          - Make sure the connection is working (by typing...).
          - Decide who will be the master and who will be the slave.  Both
            are the same as far as the gameplay is concerned, it's just a
            communications thing.
          - Exit Telema... err, the term program WITHOUT HANGING UP.  I don't
            mean drop to DOS, I mean quit the damn thing.  (In you-know-what,
            ALT-X will do this for you.)
          - Go to your Bub directory (you did give it its own directory?),
            and...

                The master types something like

                   bub32 -p2f8 -i3 -b57600 -m

                while the slave types something along the lines of

                   bub286 -p3e8 -i4 -b57600

          - If all goes well, you'll be connected and you can start playing!

          Note that different versions of Bub should be able to talk to each
          other.

        IHHD (Internet play):

          There is nodirect TCP/IP support, so you'll have to find IHHD and
          use it.  It comes with pretty complete instructions, but it doesn't
          work over the new-fangled SLIP/PPP connections that everyone and
          their dog has nowadays.  You'll need the old-fashioned UNIX shell
          account to do this.

          Real IPX and TCP/IP are on the horizon.

How do I hook this thing up to a Quake server?
----------------------------------------------

        Sorry; I just couldn't resist. :)  If anyone wants to write a
        Bub-Bot, though, let me know!

Why does Bub crash and make wierd noises (32-bit version)?
----------------------------------------------------------

        Well, the sound system is not perfect yet, so ChudMod probably
        encountered something it didn't know how to handle.  If you get
        a stack trace, please send it to me along with a directory listing
        from

        DIR BUB*.EXE

        so I know exactly which compile it was :)

        Note that Scream Tracker 3 will sometimes save a song with an order
        list that references non-existant patterns.  This is the only
        thing that has crashes the player in recent memory.

What's planned?
---------------

        - More and better sound effects.  Right now, all you get in the
          32-bit version is music.  In the other versions, you get one
          sound effect.
        - IPX and TCP/IP, almost certainly.
        - There will be a level editor by the time the final release is
          ready.  Maybe.

I've finished the game, but my life _still_ has no meaning.  What now?
----------------------------------------------------------------------

        Well, there are only 20 levels at the moment.  At least I think
        so.  I haven't gotten past level 10 yet :)  I know I put them in
        there, though.  [Yes, they're all there.  This was written long,
        long ago, but it's staying in.]

This looks like another game I've seen.
---------------------------------------

        Yeah, so? :)  See below.  I decided to implement the rules as
        closely to the "original" as possible, however. :)  For example,
        in two-player mode, the roof, she don't fall, what.  Hint hint :)

Who gets credit?
----------------

    The game itself was written by me, Brad Spencer, but that doesn't
    mean I wrote all of the code.  To save time (it's only Bub, for god's
    sake), I grabbed a few libraries/code-snippets:

        - MODEX105.ZIP was the filename on x2ftp.oulu.fi.  This "all that
          you really need" Mode X library was written by Matt Pritchard

        - Paul Fenwick for the excellent XLIB Mode X libary for DJGPP v2.
          Naturally, this is available on x2ftp.oulu.fi.

        - LIBKB-1.00 is by Markus Franz Xaver Johannes Oberhumer.  It lets
          me treat the keyboard like a big plastic thing with buttons on
          it instead of some dumb text stream.  This thing rules, 'cause it
          works with DJGPP v2 without me even noticing!

        - Bubble Crack, by whoever lives at bcrack@mavenry.altcit.eskimo.com,
          is the only other PC version of this game I've seen.  I didn't
          use any code from it, but I initially grabbed the levels since
          many of them were similar to those in the arcade.

        - Brett Paterson, for writing the excellent FMODDOC and giving me a
          basis for the GUS low-level sound routines.  There is a bit of
          his code in there somewhere.  Thanks.  I "ported" this to DJGPP
          by changing all "unsigned int" to "unsigned short int" and writing
          a couple of macros.  Cool.

        - Chris Blum, for writing UART_LIB, which I used for the two-player
          serial routines in the 16-bit versions.  I recommend this and all
		  the stuff I've mentioned.

        - Paul Medynski (aka Reepicheep), for writing the music.  He's a
          good friend of mine and you can get more of his stuff from
          http://dragon.acadiau.ca/~021210m or mail him at
          021210m@axe.acadiau.ca.  I'm sure he'd like to hear from you :)

    So now you're thinking, "This guy didn't write anything."  Fine, think
    that if you want.  The point is, I wanted to write the game "quickly",
    and avoid some of the crappy stuff this time around.  But I do like
    the crappy stuff, I just don't have my own yet :)  Besides, lighten up,
    it's only Bub!

    Additional:  Hey, I wrote ChudMod over the summer and ported it to djgpp
    while I was in Ottawa this fall, so there :)  As I write bits and pieces,
    the third-party stuff will slowly disappear :)

	Additional #2:  Hey, hey, hey.... More code gets replaced as I write
	my own IRQ driven serial library for djgpp!  Music _and_ two-player
	Bub all at once!

    Thanks go to those listed above, plus:

        - Paul Gordon and Dave Moulaison for introducing me to the arcade
          (read 'NEO-GEO') version of the game.

        - Jon Kerr, Dave Whiting, Jordan Hunt and even Goon for playtesting
          and putting up with watching me code.

        - Taito, for creating Bust-A-Move, the father of all bubble-smashing
          games.  Bust-A-Move (aka Puzzle Bobble) is not officially available
          for the PC, so I had to write my own.

        - The administrators of x2ftp.oulu.fi.  "Where do you go when you
          want to get brand name coding info at a fraction of retail cost?"
          (play on a quote from UHF)

        - Those "unofficial" beta testers who managed to get their hands on
          some early versions :)  hehehe

        - comp.msdos.sys.djgpp for being a great source of info on a great
          compiler!  You can get djgpp at http://www.delorie.com.
          It's free!

Known bugs:
-----------

        - Sometimes crashes under Windows 95.  Rare.  No reason found yet.

        - May crash on close when music is enabled on 32-bit version.  it
          shouldn't though.  [I think this is gone.]

        - Messes up your clock.  This will be fixed in the next version.

        - ChudMod may not be perfect, so look out.

        - The "You Lose" graphic was the only one in the whole game made
          with a width that was not divisible by four, so it used to appear
          as a mess at the end of the game.  This was fixed, but now the
          16-bit versions have the bug instead, since they haven't been
          recompiled since the summer.  This will probably stay unless
          anybody actually cares.

Previous "known bugs" that are NOW supposed to be FIXED:
--------------------------------------------------------

        - 32-bit version with music screwed up the game's timing.  All timing
          in this version now works with or without music.  Thanks, Yord.

        - Sometimes levels don't fully appear.  I plan on stripping the
          the movement code out of the beast and writing a simple user-deadly
          level editor that can save the bastards in some raw format.  Or
          maybe I'll just make a converter that changes the numbers in the
          *.BUB files to a raw format.  Yeah, that's easier.  Done.  Fixed.

        - Balls _still_ sometimes get stuck in the right wall.  I know how this
          _can_ happen, but not how it _does_ happen.  This will be fixed
          eventually.  Fixed.

        - Dropping more than 17 balls gives you more and more points.  This
          is against the original rules.  Fixed.

        - Bonus time calculations were being done in "fast" floating point
          for some reason, so machines with no coprocessors always claimed
          that each level had been completed in -1 seconds :)  Fixed.

        - Many many rule changes happened between v0.80 and v0.87.  They
          are now "what they're supposed to be" and should stay pretty
          stable.  The high score protection was changed to invalidate
          high score files created with the old rules.

        - High score table "Level" column is now updated properly.

        - Some screen paging bugs and extra drawing eliminated

--------------
March 22, 1997
Typos checked August 10, 1997
URL updated January 22, 2000
