luminesweeper
source release 20051210
© 2005 Damian Yerrick

 ___________________________________________________________________
|                                                                   |
|       luminesweeper for Game Boy Advance, version 20051009        |
|___________________________________________________________________|

_____________________________________________________________________
Rationale

Where I come from, nobody I know can afford Sony's new portable game
system.  So I decided to criticize the high price of the PSP and save
my fellow players the 290 USD that a PSP system and a game costs by
making a homebrew game for the Game Boy Advance handheld system.  It
appears that a lot more people have a GBA or Nintendo DS than have a
PSP, and GBA flash devices capable of running multiboot games have
come down far in price.

It's pronounced like "luminous sweeper".

_____________________________________________________________________
Installing

To run this game on a home computer, use a GBA emulator such as
VisualBoyAdvance or NO$GBA. To run this game on a GBA or a Nintendo
DS, use a multiboot linker cable or a GBA flash card; North Americans
can buy GBA flash cards from web sites such as Kick Trading.
The zipfile includes a version with music whose file name suffix is
.gba, intended for play on a PC or on a GBA with a flash cart, and a
silent version whose file name suffix is .mb, intended for play using
the various "multiboot" methods such as the launcher, the MBV2 cable
(GBA only), the Flash2Advance (F2A) cable (GBA only), the XBOO cable
(GBA only), or the inexpensive GBA Movie Player.  Note: GBA MP users
should delete the .gba file, rename the .mb file to end in .mb.gba,
and then look in the Game menu.

_____________________________________________________________________
Game left

This mode of luminesweeper will be familiar to anybody who has played
Lumines.  Square pieces, each made of four blocks where each block is
colored dark or light, are falling into a 16x10 block well.  Move and
rotate them to arrange them into BLAWKs (four blocks of the same
color arranged in a 2x2 square) so that the sweeper, which moves from
left to right across the well every 3 to 6 seconds (depending on the
tempo of the song), will erase them as it passes. Let the blocks fill
to the top, and the game is over.

Controls

    * Control Pad: Move falling piece
    * [A]: Rotate falling piece clockwise
    * [B]: Rotate falling piece anticlockwise
    * L or R: Move falling piece as far sideways as it can go

Scoring

There are three ways to earn points:

    * Moving the falling piece downward gives 1 point per space
    * Erasing each BLAWK gives 40 points, or more if at least four
      BLAWKs are erased in one pass of the sweeper.
    * Keeping a clean playfield gives 1000 points for "monochrome"
      (all remaining blocks one color) or 10,000 points for "empty"
      (no remaining blocks)

_____________________________________________________________________
Game right
[screenshot of right mode]

This mode of luminesweeper will be familiar to anybody who has played
Minesweeper.  The playfield is between 8x8 and 30x16 spaces, some of
which contain a hidden explosive. Click on a space, and it'll tell
you how many explosives are in the 3x3 square centered on that space.
You can place a flag to mark where an explosive is so that you don't
accidentally click it. The sweeper passes from top to bottom and
extends the area you have uncovered, pointing out the location of
explosives.  Click a space with an explosive that hasn't been swept,
and the game is over.

Some experienced winmine players may not understand the rationale
behind the sweeper in this game. It's needed in part because play
with a D-pad isn't as fast as play with a mouse.

Controls

    * Control Pad: Move cursor
    * [A]: Click the space under the cursor
    * [B]: Place or remove a flag on the space under the cursor
    * [A]+[B]: If correct number of flags surround the space under
      the cursor, click all unflagged spaces around that space


 ___________________________________________________________________
|                                                                   |
|           Skin maker for game left, version 20051010              |
|___________________________________________________________________|


This program takes image files, compiles them into .Lskin files for
use by Luminesweeper game left, and then produces one or more GBA ROM
files.

_____________________________________________________________________
System requirements

* Windows 2000 or Windows XP (the batch file relies on cmd.exe
  features not present in command.com)
* Allegro 4.0 DLL (http://www.pineight.com/pc/)
* (for music) GSM Player (http://www.pineight.com/gba/gsm/)
* Plain text editor such as Notepad or MS-DOS Editor
* A way to run programs on the GBA, or a GBA emulator.

_____________________________________________________________________
How to use

1. Put alleg40.dll in the tools folder or in your
   system32 folder.
2. Place .Lspec files in the skins folder.  If you use more than
   seven or so, the .mb.gba file will be too large to load on a
   GBA Movie Player.
3. Place bitmap files in the skins folder or, if the .Lspec file uses
   full paths, anywhere.
4. (Optional) Place a gsmsongs.gbfs file in the same folder as
   mkskins.bat.
5. Open mkskins.bat in Windows Explorer.
6. Write the luminesweeper_custom_with_music.gba file to your GBA
   flash card, or write the luminesweeper_custom.mb.gba file to a CF
   card for use with the GBA Movie Player.

_____________________________________________________________________
Syntax of .Lspec files

The .Lspec file specifies the images and sounds that make up a given
skin.  Images are taken from bitmaps in BMP, PCX, or TGA format.
They can be 16-color, 256-color, high-color, or true-color.  (PNG
support may be added in a future version if there is enough demand.)
All paths to bitmap files are relative to the folder that contains
mkskins.bat; for example, if you put skin images in the 'skins'
folder, you'll need to begin each filename with 'skins/'.

BG=skins/bg.bmp
    (Required)  Points to a 240x160 pixel bitmap file.  The area
    within the playfield can use up to 16 unique colors.  The area
    outside the playfield can use up to 16 unique colors.  However,
    only a total of 31 colors are available, so if both the inside
    and the outside use the full 16 colors,  at least one color
    of the inside must be the same as one color of the outside.

InnerBG=inner.bmp
    (Optional)  Points to a 192x120 pixel or 240x160 pixel bitmap
    file.  If the file is 240x160 pixels, it uses the area where
    the playfield would appear on the screen, whose upper left
    corner is at (32, 32).  The area inside the playfield is
    replaced with this bitmap.

PF=pf.bmp
    (Required)  Points to a 192x120 pixel or 240x160 pixel bitmap
    file.  If the file is 240x160 pixels, it uses the area where the
    playfield would appear on the screen.  This file must follow the
    template that comes with the Luminesweeper Skin Kit.  As the skin
    template contains more than one tile of a given shape, the skin
    compiler will use the top-left-most instance of a given tile.
    Each of the following gets up to 15 colors: the sweeper, the
    swept tiles, the tiles of color A, and the tiles of color B.
    The color of the pixel in the upper left corner is used for
    transparency.

Music=Butterfly.gsm
    Audio to be played during this skin.  Should be in Toast's GSM
    Full Rate format, mono, 18157 Hz.  (Or in s3m format if I ever
    get a Free player written.)  This filename is case sensitive
    and must match the filename used in the GBFS file.

MusicBPM=135.0
    Specifies how fast to move the sweeper, in beats per minute.
    Every beat, the sweeper passes over two columns; it makes a
    complete pass over the playfield in 8 beats.  If not
    specified, 120.0 is used.

MusicLoopStart=2
    Number of passes of the sweeper before the part of music that
    loops.  Must be a positive whole number.

MusicLoopLen=10
    Number of passes of the sweeper during the part of music that
    loops.  Must be a positive whole number.

MoveFreq=1866.76
RotateFreq=1244.51
BlawkFreq=77.78
    Frequency (in hertz) for sound effects played when the falling
    piece is moved sideways, when the piece is rotated, or when a
    BLAWK is formed.  These frequency values must be positive
    decimal numbers between 64.04 and 8192.0, though pitch accuracy
    drops significantly at higher frequencies of 2000 Hz or above.

_____________________________________________________________________
Playfield images

The playfield image is 192x120 pixels in size and contains 16 tiles
across and 10 tiles down, each of size 12x12 pixels.  The color of
the top-left pixel of the bitmap (not of each tile) is used as the
transparent color.

The vertical bar is the sweeper. The top two tiles of the sweeper are
used to form a 12x24 pixel image that is vertically repeated 5 times.
Up to 15 colors plus transparency are available, although the first
three should currently be a gradation from the background color so
that the 'pause' screen looks correct.

The rest of the top row is digits from 0 to 9.  These are drawn 10
pixels apart, that is, they overlap horizontally by two pixels.
Up to 15 colors plus transparency are available.

There are two groups of tiles.  The lone tilesrepresent unmatched
blocks, while the others are for blocks that are part of one or
more BLAWKs.  (Tech note: In Lpf_template.png, each hexdigit refers
to a 4-bit bitfield, where 8, 4, 2, and 1 correspond to the four
corners of a BLAWK.)  All tiles of a given hexdigit and color
must be identical in appearance, or the result is unspecified.
Up to 15 colors plus transparency are available for each color.

The tile in the lower left corner is a bomb, sometimes called
"detonator" or "destroyer".  It is drawn overlapping a block.
Up to 15 colors plus transparency are available.

The tiles overlapping the bottom of the bar are for blocks that have
been marked (either by being in a BLAWK or by being connected to a
bomb in a BLAWK through like-colored blocks) and then swept by the
sweeper.  Up to 15 colors plus transparency are available.

_____________________________________________________________________
How to add music

The skin builder will produce a build with music only if you include
a gsmsongs.gbfs file, which you can create using GSM Player.  Edit
the Go.bat file of GSM Player, using Notepad or another plain text
editor, and remove the line that says "del gsmsongs.gbfs".  Then
build a GSM Player ROM and copy gsmsongs.gbfs to the folder with
mkskins.bat.

The filenames in the .Lspec files MUST match the filenames in
gsmsongs.gbfs exactly.

Music does NOT work on the GBA Movie Player.  Get a SuperCard, an M3,
or a real GBA flash card.

_____________________________________________________________________
Legal

Copyright (c) 2005 Damian Yerrick

This is a free document.  Permission is granted to copy, distribute
and/or modify this document under the terms of any of the following
licenses:

* the GNU Free Documentation License, Version 1.2 or any later
  version published by the Free Software Foundation; with no
  Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts,
  or
* the GNU General Public License, Version 2 or any later version
  published by the Free Software Foundation, or
* the Creative Commons Attribution-ShareAlike License, Version 2.0
  or any later version published by Creative Commons.
  http://creativecommons.org/licenses/by-sa/2.0/

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
licenses for more details.

You should have received a copy of the aforementioned GNU licenses
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

You can contact Damian Yerrick through a web form:
  http://www.pineight.com/contact/

or through paper mail:

  Damian Yerrick
  730 Runnion Ave
  Fort Wayne, IN 46808
  USA

Damian Yerrick and Nathanael Nerode encourage those who modify GFDL
documents such as this not to add Invariant Sections.  Explanation:
http://home.twcny.rr.com/nerode/neroden/fdl.html


 Luminesweeper is not sponsored or endorsed by
the following trademark owners: Lumines is a trademark of Bandai.
Microsoft Windows is a trademark of Microsoft.  Arial is a trademark
of Monotype.  Game Boy is a trademark of Nintendo.  Sony and PSP are
trademarks of Sony. Java is a trademark of Sun Microsystems.
Minesweeper is a trademark of Warterfield Holdings (but not for
computer games).

This document 