Dodger (c) 2006 by Miran Amon - A TINS 2006 game - TINS is not speedhack
version 1.18, created 5th March 2006, last updated 9th November 2006


This game is my entry for the 2006 TINS competition. TINS is Not Speedhack.
TINS is a Speedhack-like competition which is organized over 1 weekend.
Special rules are anounced at the start of the competition and entrants have
72 hours of time to come up with a unique original new game that conforms
to those rules.

Actually version 1.01 was my TINS '06 entry. Since then the game has been
much improved.

-------------
 0. Contents
-------------

1.  The competition rules
2.  About code and content reuse
3.  How to compile
4.  Technical info
5.  How to play
6.  Languages
7.  Themes
8.  Replays
9.  Highscores
10. Known bugs
11. Change log
12. Credits
13. Contact info


--------------------------
 1. The competition rules
--------------------------

1. Genre requirenment: "Time" should be the theme of your game.

The point of the game is to survive for the longest time possible. This game is
all about time. If you get a good time, you get your name on the score board.

2. Artistic requirenment: the game should feature (a) railway(s) and / or train(s).

The tank-like drones that shoot rockets at you move on railway tracks.

3. Technical requirenment: Provide a help function, that can be accessed during the game.

You can press F1 in the game to see helpfull instructions. Press F1 to hide
them again.

4. Technical requirenment: Provide a good example of ascii-art.

The intro is made with ASCII art. Unfortunately it's not very good ASCII art.
Note: Removed since v1.14 due to excessive lameness.


---------------------------------
 2. About code and content reuse
---------------------------------

I based this game on my TINS 05 entry (Tuna Jump). Only the basic framework was
retained though. I also reused some utility classes and other code from various
other projects of mine (e.g. framerate monitor, screenshot saver, music player
and some more).

I also recycled the fontsmall.pcx font and the explode.wav sample. The scottn.ttf
font is taken from my c:\windows\fonts directory. How it got there I don't
remember, probably from some random free font site. All other content and code
not mentioned above, including all graphics, font, samples and music was created
during the contest.


-------------------
 3. How to compile
-------------------

This game requires the following libraries:

Allegro 4.2.0 - http://alleg.sourceforge.net
MASkinG 0.80 - http://members.allegro.cc/miran
AllegroFont 1.9.2 - http://members.allegro.cc/miran
CURL - http://curl.sourceforge.net/
DUMB - http://dumb.sourceforge.net/
pthreads on Linux

The game was developed with MinGW (gcc v3.2.3) and Linux (gcc v4.1.1).
It should compile on both platforms with the provided makefiles. If not,
do let me know.

To compile with MinGW you first have to install the above libraries and then
just type "make -f makefile.mgw" in the game directory. In Linux type
"make -f makefile.linux". There should be no errors or warnings.


-------------------
 4. Technical info
-------------------

Resolution: 640x480
Bit depth:  32 bpp
Input:      mouse (and keyboard for the menus)
Sound:      yes
Music:      IT played with DUMB

Minimal requirenments: I have no idea. Probably won't run very well, if at all,
on older computers. I'd say around 1GHz is minimum. That's because the game is
very unpotimized. I get around 50% CPU usage at 100 FPS on my Athlon64 3000+.

Note that the game doesn't work in any resolution other than 640x480x32. If
you edit allegro.cfg by hand and change some of the generic settings not
specifig to this game, you can easily make it crash or freeze or do other
unwanted things.

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
WARNING:
Please do not look at the source code unless you absolutely have to. It's ugly,
it's hackish and you should not attempt to learn from it. It's not my usual
style and if you just want to see what a MASkinG game looks like on the inside,
this is not a good example!
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!


----------------
 5. How to play
----------------

You control the piece that is initially positioned in the centre of the screen.
Use the mouse to hold and drag it around the play area. Try to avoid the
other four pieces as they are your enemies and the projectiles that the drones
at the edges of the play area shoot randomly at you. The game starts as soon as
you make your first move and ends when you crash into a wall, an enemy or a
projectile. Try to survive for the longest time possible.

This game is all about skills, reaction time and the ability to look ahead.
It is very difficult. It requires you to keep an eye on 10 or more objects
at the same time, predict their movement, react to it and plan your moves.
You will be lucky if you can keep your ship in one piece for more than 15
seconds.


--------------
 6. Languages
--------------

The game can be translated into any language provided that the fonts used by
the theme can display the required characters. If you want to add a translation
for your language, simply copy the file english.lng inside the language
directory to <mylanguage>.lng where <mylanguage> is the name of your language,
open it in a text editor such as Notepad and change all English texts to your
own. Make sure you don't write words that are too long because for some there
is limited space in the game. If your language requires characters other than
the ones provided in the 7bit ASCII set, please use the UTF8 encoding for the
language file. Some texts, most notably the help string (and all texts that
are printed with the small font) must NOT contain any non ASCII characters.
If your language requires them, please substitute them with whatever you feel
is most appropriate. For example instead of , you could write ae.

Try to keep the text's meaning roughly the same in your translation. Feel free
to change the about, intro and outro texts though if you think it is necessary,
but leave the parts containing % symbols unchanged. Also feel free to add your
name to the credits string.

If you translate the game to a new language, please send it to me to the email
address found at the bottom of this document so it can be included in the next
version or made public on the game's website.


-----------
 7. Themes
-----------

The game supports themes. Just about every aspect of the game's visuals and
audio can be customized. If you'd like to make your own theme for Dodger, here's
how it's done.

Each theme is put in its own directory under 'themes'. Here's a list of all the
files that are required to be present in a theme:

skin.ini: This is the skin description file. Dodger is made with a library
  called MASkinG which supports skins and this file describes every aspect of
  a skin. It's a normal text file that can be edited with any text editor. The
  default theme called Dodger is heavily commented and should give you a good
  idea of what each value does. Most of the settings aren't even used in Dodger
  though except for the button, mouse and some other entries. For Dodger themes
  a special section is added for the game specific settings and those are
  commented as well. This file must be named skin.ini.

data.dat: The Allegro datafile that contains skin graphics, mouse cursors and
  GUI sounds. Allegro datafiles can be opened and manipulated with the Grabber
  program that comes with Allegro. This file can be named anything you like
  and is referenced from skin.ini. Actually there can be three separate datafiles
  if necessary, one for bitmaps, one for sounds and one for cursors. As with
  skin.ini many of the MASkinG standard objects aren't used, but the following
  must be present in the datafile(s):

  MOUSE_NORMAL - A film strip sequence of mouse cursors that form an
    animated cursor. The details about how this bitmap is interpreted are
    written in the skin.ini file (i.e. how many frames there are and how
    fast the cursor should animate). Note that the cursor doesn't actually
	have to be animated, it could only be a single image.

  PANEL_RAISED - Used for drawing raised panels (i.e. the time, highscore
    and help panels in the main game screen). The bitmap is split into 9
    sections (3x3) and the one in the centre is tiled to fill the panel so
    the actual bitmap can be quite small to conserve space. The relevant
	entries in the [TILING] section of skin.ini define how the tiling is
	done.

  PANEL_SUNKEN - Like above, but used for sunken panels. In the game this
    is used just for the name entry edit box.

  SAMPLE_ACTIVATE - The sample that is played when a button is clicked.

  SAMPLE_GOTFOCUS - The sample that is played when a button gets focus.

  SCROLL_* - These are used for the highscore and replay lists. All bitmaps
    contain 4 subbitmaps that are used for different states (normal, selected,
    disabled and focused). The UP,DOWN,LEFT and RIGHT bitmaps are the little
    arrows on the list scrollers, HBACK and VBACK are tiled across the back
    of the horizontal and vertical scrollers and HGRIP and VGRIP are used
    for the scroller's grip buttons.

  All other objects should be left as they are. In skin.ini you can fine tune
  how the bitmaps are interpreted.

music.it: The background music in Impulse Tracker format. The file must be
  named music.it and it must contain two "songs". First an unlooped intro
  of about 10 seconds at order 0. Then a looped song of any length at order 1.

samples:
  cling.wav - Played when an enemy bounces off a wall.
  shot.wav - Played when a drone shoots a projectile.
  explode.wav - Played when something explodes.

  All samples must have those exact names and should be of roughly the same
  lengths as the ones in the default theme.

fonts:
  All fonts are referenced in skin.ini. FONT0 is used for the bottom text
  scroller and the name entry box, FONT1 is used for the highscore and help
  panels, FONT2 is the main font and is used for most GUI elements such as
  labels and buttons in the menus and FONT3 is the large title font.

  FONT1 must be a fixed width 6x14 monochrome font. The size of each character
  must be exactly 6x14 pixels and the font should not use colours. Use the
  Allegro Font Editor (or any general purpose image manipulation program) to
  edit this font if necessary.

  All fonts other than FONT1 can be any type of supported font (bitmap, TTF,
  etc), preferably something nice and thick.

bitmaps and sprites: All game bitmaps and sprites should be TGA files with an
  alpha channel for transparency. The filenames and dimensions are fixed.
  Most sprites have two frames of animation which are played at around two
  frames per second.

  back.tga - The main play area. Size is 464x464. There is a 40 pixel thick
    border around the central 384x384 play area. Unlike with sprites the
    transparency is set with the mask colour which is rgb(255,0,255)!

  player[1|2].tga - The player's piece sprite. Size is 64x64.

  drone[1-4][a|b].tga - The four enemies. Same size as the player.

  tank[1-4].tga - The tank drones. Size is 32x32. tank1 and tank2 are the normal
    sprites and tank3 and tank4 are used when the tank is shooting. All four
    tanks share the same sprite which is rotated in-game as necessary.

  rocket.tga - The tank projectile. Size is 16x16. Not animated, rotated in-game
    as necessary.

That's it. If you make a nice theme, send it to me to the email address found
at the bottom of this document so it can be included in the next release or
made public on the game's website.


-------------
 8. Replays
-------------

The game automatically saves replays of your top scoring games in the replays
directory. After each game you can press 'R' to view the replay, even if you
didn't make it to the highscore list. For those replays a file named ####.rpl
is used where #### is the score you achieved in hundredths of a second. For
example if you got 8.72 seconds and didn't make it to the highscore list, a
replay named 872.rpl is saved when you view the replay.

If you do get on the highscore list and enter your name, a file named
<name>-####.rpl is saved where <name> is the name you entered.

If you have a particularly spectacular replay, do send it to me.


---------------
 9. Highscores
---------------

Dodger saves highscores to an online server and downloads them every time you
start the game as well as every time you make it to the online highscore list.
All the downloading and uploading is done automatically in the background as
long as you're connected to the internet.

In addidtion to the online list, a local list of scores is also kept. You can
review the lists in the highscores menu as well as in-game. Note though that
due to space restrictions only the top 15 scores are displayed in the in-game
lists.

In the online highscore list each unique name appears only once. Only the
top score of each player is displayed in the online list.


----------------
 10. Known bugs
----------------

- Some old replays don't work. New ones should all work now.
- It is exceedingly easy to cheat.
- The game sometimes crashes on exit, mostly after changing some of the settings
  such as the fullscreen flag and the theme. Workaround: edit the config file by
  hand.
- Sometimes you are asked to enter your name twice and the score is saved twice
  as well. Happens very rarely for unknown reasons.
- On windows switching from fullscreen to windowed mode leaves the window
  size unchanged on some systems.
- Doesn't work in any colour depth other than 32 (because of alpha transparency
  in the sprites).


----------------
 11. Change log
----------------

v1.18 (8.11.2006):
 - bugfix: you could move while the game was paused
 - minor bugfixes in some of the translations

v1.17 (8.11.2006):
 - fixed a problem with the intro screen
 - optimized text rendering somewhat; the game is still slow though
 - added Czech, French, German, Italian, Polish, Spanish and Swedish
   translations
 - made the lists of languages and themes sort alphabetically
 - fixed logic framerate to 100 Hz

v1.16 (7.11.2006):
 - added support Unicode strings (special characters in many languages)
 - removed the requirement for using bitmap fonts in themes

v1.15 (7.11.2006):
 - added support for themes
 - bugfix: replays that didn't make it to the highscore list would
   be saved as 0.rpl.

v1.14 (6.11.2006):
 - added shadows
 - added support for multiple languages
 - made it possible to view a replay after getting a top score
 - fixed a huge problem with uploading highscores
 - changed the lame ASCII art intro screen to a plain one

v1.13 (5.11.2006):
 - fixed a problem with instant replays on Linux
 - improved the synchronization between local and online scores

v1.12 (4.11.2006):
 - made the game really work on Linux (there were problems with filenames)
 - implemented own random generator identical to the one found in msvcrt.dll
   so replays saved with the prebuilt binary on Windows also work in these
   newer versions). Big thanks to William Heatley for his superior DLL
   disassembling skillz.
 - implemented online highscores in the Linux version

v1.11 (19.3.2006):
 - fixed a big bad bug introduced in v1.10 that would make all the highscores
   in one session have the same date and time

v1.10 (18.3.2006):
 - added the option to save and view a replay even when you don't get
   into the highscore list

v1.09 (16.3.2006):
 - made "Reduce CPU usage" actually work; it has several levels too
 - highscores now aren't updated and a replay isn't saved if you don't
   enter a name

v1.08 (16.3.2006):
 - added tooltips to the highscore lists
 - changed the in-game highscore list to toggle between
   local and online only on mouse click
 - made sure the player doesn't die in replay mode until the
   replay is over
 - added a quick logic framerate check to prevent lamers from cheating
   by slowing the game down by lowering the logic framerate
 - made stereo sound

v1.07 (10.3.2006):
 - added a replay list to the higscores menu

v1.06 (10.3.2006):
 - bugfix: made sure all threads are killed on program exit
 - limited name entry to alfanumerical characters only
 - added replays
 - some minor graphics improvements
 - made separate highscore lists for local and online scores

v1.05 (8.3.2006):
 - added some support for online highscores (doesn't work in Linux yet!)


v1.04 (8.3.2006):
 - made the highscore list's name column in the top right of the game
   screen wide enough to actually hold 16 characters
 - compiled a highscore table from scores posted on allegro.cc

v1.03 (7.3.2006):
 - made the "enter your name" box remember the last name you write
 - made any key and mouse click start a new game


v1.02 (6.3.2006):
 - fixed the drone-wall collision respose
 - adjust difficulty by making the drones move a little slower and reach
   a little lower top speed; they also swerve a little less
 - updated the credits scroller text

v1.01 (5.3.2006):
 - made the highscore lists not receive input focus
 - made the player radius a few pixels smaller
 - fixed the panels on the right side of the screen so they now properly hide


--------------
 12. Credits
--------------

Thanks to:

 - Shawn Hargreaves and everyone else involved with creating Allegro.
 - Ben Davis for creating D.U.M.B.
 - Javier Gonzalez for creating AllegroFont.
 - The guys who maintain cURL.
 - Matthew Leverton for running allegro.cc and providing webspace for the game.
 - Everyone at the allegro.cc forums who helped in any way in creating
   this game.
 - Everyone else I forgot to mention. :)

Big thanks also to the guys who provided translations:

 - Czech: OICW
 - French: Castagnier Mickal
 - German: Michael Faerber
 - Italian: FMC
 - Polish: Tomasz Grajewski
 - Spanish: Paul whoknows
 - Swedish: Kent Larsson


--------------
 13. Contact
--------------

email:   miran.amon@gmail.com
website: http://members.allegro.cc/miran
