WHAT:

  So, uh, there's a bunch of penguins on an iceberg in Antarctica. You have
  been selected to catch them so they can be shipped to Finland, where they
  are essential to a secret plot for world domination.

  In order to trap the penguins, you'll need to break the iceberg into small
  chunks. (They're afraid of water, for no apparent reason. Ah well. "The
  Matrix" had more plot holes than this, and it still was a hit.) You do
  this by melting lines in the ice with Special High-Tech GNU Tools.

  If a penguin hits a line in progress, however, it vanishes with a loud
  noise, and you lose a life. (Yes, a life. This story is really breaking
  down, isn't it? But never fear -- I'll keep going until it's completely
  dead.)

  Once 80% or more of the iceberg is gone, the remaining chunks are small
  enough for shipping. Of course, if you manage to get rid of more than
  that, you'll save on postage, thus earning you exponential amounts of Geek
  Cred (a.k.a. "score").

  After you ship off one batch of penguins, it's time to move on to the
  next. Each subsequent 'berg will have one more penguin, and you'll have
  one more life. This will continue until you lose, or until you exceed
  level one hundred or so, which Ain't Gonna Happen.

  Of course, this is an urgent mission, so you'll be penalized if you're
  slow -- every second or so, your score drops down by one. But don't worry,
  I'm not completely cruel, so any points you earn on one level are yours to
  keep forever, no matter how long you take on subsequent icebergs.

  As far as I can tell, this makes no narrative sense whatsoever, so at this
  point, I declare the backstory / game metaphor completely collapsed. Just
  go play.


HOW:

  The left mouse button starts drawing lines; the right (and/or middle)
  button toggles between making vertical and horizontal lines.  Note that
  left clicking actually starts *two* lines: either up and down or left and
  right. (This will make plenty of sense when you're actually playing.) If
  one of these lines is hit before it reaches the edge of the iceberg,
  you'll lose a life. If both are hit, you'll lose two lives.

  As a tiny bit of grace, if you click directly on a penguin, it'll say
  "Ouch" and nothing else will happen.

  Once a line is completed, any area containing no penguins is cleared.
  Falls into the ocean, so to speak. Once 80% has been cleared, the level is
  complete. However, you get an exponential bonus for every percentage point
  above that, so you want to try to make your last line suddenly clear a
  huge chunk of ice. (Again, this will make sense once you've played for a
  while.) Oh, and you also get a (much smaller) bonus for having lives left
  over at the end of a level.

  Taking a long time on a level doesn't affect these bonuses, but it can
  chip away at your score, so you have to balance the time it takes to set
  up a situation where you can clear 99% of the iceberg against the bonus
  you'll get for doing so.

  Having trouble? A hint: it's useful to make traps by intentionally letting
  some of your lines get broken. That way, you can create smaller areas in
  which you can catch the pesky little things easily.


WHY:

  There's a game for MS Windows called "Jezzball". You may notice that this
  one is extremely similar. There's a reason for that. See, our main
  computer at home runs Linux most of the time, but it has Win95 set up to
  dual-boot if need be. (Unfortunately, it's too slow to run VMware or Wine
  well.) Ideally, of course, the machine stays in Linux, but my wife, Karen,
  really likes puzzle sorts of games and became highly addicted to this
  Jezzball thing. Well, we simply couldn't have the system wasting its life
  in Windows all that time, so I took it upon myself to create a
  sort-of-clone. (It's not a pure clone, because I like to think that I've
  done many things in a far superior way.) So this game can be thought of,
  in a simultaneously dangerously geeky and dangerously mushy way, as sort
  of a dual love-letter, to both Karen and Linux. :)

  It's therefore somewhat ironic that IceBreaker now exists in a MS
  Windows version. Ah well. I know not all of you have been converted yet,
  and you might as well enjoy the game too.

  Oh, and to answer another "Why" question, especially for my friend Lars:
  why is this program written in C and yet uses C++ style comments? Because
  I like C++ style comments, that's why.

WHO:

  This game was written by Matthew Miller <mattdm@mattdm.org>.

  Recent versions have benefited immensely from the help of Enrico Tassi
  <gareuselesinge@infinito.it>. He's responsible for getting the Win32 port
  to work so nicely, and for a lot of fancy new features. Enrico doesn't
  live here in Boston, but he's a huge fan of Boston band Letters To Cleo,
  so that counts for something.

  Much thanks to Karen for everything. In fact, if you really love this
  game, check out Ten Thousand Villages <http://www.tenthousandvillages.org>,
  the non-profit organization for which she works. And if you live near
  Boston, MA, stop in to the store in Coolidge Corner (Brookline) and say
  "Hi" and perhaps buy something -- they have cool stuff and it's a really
  great organization.

  Thanks also to Tae-Jin, for helping me squash a nasty bug, and to Paul for
  testing and suggestions and proofreading this document. And to the folks
  at the helpdesk downstairs for playing this game instead of working.

  The sounds were either originally created or borrowed from freely-licensed
  sources and modified heavily. Thanks to Wesley Crossman for his
  contributions. I'd still like lots more cool good ones -- either
  improvements of the existing sounds or for new themes.

  The penguin image is mostly my own work, but is based on a graphic
  from Pingus <http://dark.x.dtu.dk/~grumbel/pingus/>.

  Actually, I'm quite open to accepting any help anyone wants to give.


WHEN:

  A week or two in September 2000, and then some more time in July 2001,
  and then in May 2002, so on.


WHERE:

  Get it from: <http://www.mattdm.org/icebreaker/>

  Report bugs: <mattdm@mattdm.org>


WHICH:

  (As in, "On which libraries does icebreaker depend?")

  libSDL and libSDL_mixer. <http://www.libsdl.org/>


WHITHER:

  I'm now actively working on IceBreaker, and a few other people have been
  too (most notably, Enrico Tassi). If you want to help, or are just
  interested in what's going on, check out the development section of the
  IceBreaker website at <http://www.mattdm.org/icebreaker/development.html>.


------------------------------------------------------------------------------
Copyright (C) 2000-2002 Matthew Miller and others and released under the
terms of the GNU General Public License.

This project uses the Simple DirectMedia Layer and SDL Mixer libraries which
are available under the GNU LGPL license. SDL and SDL_mixer source code
should be available from wherever you got IceBreaker; if you can't find it,
it is available at <http://www.mattdm.org/icebreaker/> or at the main SDL
site <http://www.libsdl.org/>.

The Simple DirectMedia Layer (SDL for short) is a cross-platfrom library
designed to make it easy to write multi-media software, such as games and
emulators.

The Simple DirectMedia Layer library source code is available from:
http://www.libsdl.org/

This library is distributed under the terms of the GNU LGPL license:
http://www.gnu.org/copyleft/lesser.html

IceBreaker is free software -- you're welcome to do anything you like with
it under the terms of the GNU GPL. However, as a courtesy, if you do make
changes to the code, packaging, themes, or whatever, I really would
appreciate it if you'd send me what you've done (e-mail <mattdm@mattdm.org>,
but check before sending binary attachments). That way, improvements can get
rolled into the main version and everyone can benefit. Thanks!

IceBreaker themes are simple to create. They're are definined in text files
with the extension .ibt (that's _I_ce_B_reaker _T_heme) in the IceBreaker
data directory. The filename is the name of the theme itself, which must be
seven characters or less -- not because of the DOS 8.3 limit but because
more than seven requires the options menubox to be really big and ugly and
we don't want that.

The file consists mostly of color definitions, and also gives the location
of the two sound files and the one sprite bitmap. Color definitions begin
with a keyword ("Background", "NormalText", etc.) and then give decimal
values from 0-255 for red, green, and blue, respectively.

The sound and image defintions are just the keyword followed by a filename.
More info on file formats in a bit.

The keywords aren't case sensitive, and you can use any amount of whitespace
you want. If you leave out a particular keyword, IceBreaker will use the
default but spit out a complaint on stderr -- so don't do that. (There's
currently one exception -- SpriteMirrorBitmap, which I'll get to in a bit.)


The default theme is "linux", and the file linux.ibt looks approximately
like this:

  Background              0   64  128
  NormalText            255  255  255
  BoardFillMin          224  224  224
  BoardFillMax          255  255  255
  Gridline              192  192  192
  GridHighlight         192  192  192
  Line1                   0    0    0
  Line2                 192    0   64
  MenuHighlight         255  255  255
  GameoverText          192    0   64
  ScorescrollText         0    0    0
  BonusscrollText       192    0   64
  TextentryBox            0    0    0
  TextentryText         255  255  255
  CopyrightText         192  192  192
  SpriteTransparent     255    0    0
  SpriteBitmap          penguin.bmp
  SoundOuch             ouch.wav
  SoundCrash            crash.wav

The names should mostly be self-explanatory. If something is unclear, let me
know, and I'll either change the name in a future version or write better
documentation here. A few things bear mentioning:

BoardFillMin and BoardFillMax define the colors of the game play area. The
values will be randomly selected from the range given, but there's a twist
-- if two (or three) of the red, green, or blue values have identical Min
*and* identical Max values, those two will be "locked" together. This way,
you can produce grey or monotone backgrounds instead of having every theme
look like the mutant love child of Rainbow Brite and the Swamp Thing.

SpriteTransparent is the color value which will be treated as clear when
drawing the bitmap. In the above example, the penguin.bmp has a bright red
background, and since SpriteTransparent is set to the matching value, the
background isn't shown.

The bitmap file should be a 24-bit MS-Windows-style .bmp format. I know that
this is Lame(tm) but the SDL library which IceBreaker uses understands this
format natively, and so using it allows us to avoid having a whole extra
library just to load some really tiny bitmaps. They should be 14x14, by the
way. If you want, you can make them as small as 12x12, but that's basically
treated as the top-left of 14x14, and support for that may vanish in a
future version. (If you want smaller, just mask out most of the image.)

Don't underestimate how hard it is to make a sprite image look good at such
a tiny size. Making a theme which represents something in real life rather
than being abstract or iconic is a challenge. A future version of IceBreaker
may allow you to include background and playing board graphics instead of
just colors -- but don't hold your breath for that.

In addition to SpriteBitmap, you may also set SpriteMirrorBitmap. If this
tag exists, the given image will be used when the sprite is moving to the
right, and the main SpriteBitmap when it's moving to the left. If you leave
out this tag, there will be no warning -- the main bitmap will be used for
both. In fact, leaving it out is the best thing to do if you don't want your
image to flip, because it saves, like, 500 bytes of RAM over defining the
same image twice. And we all know how important those few bytes of RAM are
these days, right?

The sound files are 8 bit mono PCM at 22050. They should also be really
short -- under a second. This'll mean the total size will be easily less
than 30k -- if it's not, something's not right.

If you do produce a good theme, let me know -- send it to
<mattdm@mattdm.org>, and I'll consider including it with the main
distribution. All themes must be licensed under the GPL.