Shotgun Debugger 1.0.2
Copyright (c) 2005 Game Creation Society

This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.

This program 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
GNU General Public License for more details.

===============================================================

Contents
--------
1. Introduction
2. System Requirements
3. Story
4. Controls and Indicators
5. Weapons and Power-Ups
6. Saved Games and Records
7. Tips
8. FAQ
9. Credits and Contact Information


1. Introduction
---------------
Shotgun Debugger is a two-dimensional action game played from an
overhead perspective. You assume the role of a computer "hacker"
trying to escape imprisonment in a strange complex inhabited by
militant robots.

The game uses standard first-person-shooter WASD controls and the
mouse can be used for precise aiming. The player can utilize six
weapons against four types of deadly mechanical combatants, and
gameplay stretches over eight levels.

A save-game system allows you to quit and restart at the level you
left off at, with your game statistics saved. Records are kept for
each level and the game as a whole for completion time, number of
enemy kills, number of shots fired, and number of times hit. You can
also start a new game at any previously-beaten level.


2. System Requirements
----------------------

- Linux or Windows (port to Mac OS X in the works)
- The SDL, SDL_image, and SDL_mixer libraries
  (Windows users need not worry, as the required DLLs are
  included. The library can be found at www.libsdl.org.)
- 17 MB free hard disk space
- Accelerated graphics hardware
- Sound card
- Keyboard (mouse recommended)
- Hands, or other means of controlling the game

A C++ compiler and the SDL headers are required if you are building
the game from source. A Makefile is included in the src directory for
Unix systems, as well as a Dev-C++ project file for compiling on
Windows with Bloodshed Dev-C++ (www.bloodshed.com)

For *nix:
To compile, just type "./compile.sh" in this directory.
To run the program, type "./sdb". If you wish to run
Shotgun Debugger from any directory, perform the following procedure
as root:

- Move the Shotgun Debugger directory to /usr/share or a similar location:
  # cp -r sdb-1.0.2/ /usr/share
- Make a symbolic link in /usr/bin to the SDB executable:
  # cd /usr/bin
  # ln -s /usr/share/sdb-1.0.2/sdb sdb
- Now you can just type "sdb" at a command prompt to play.

3. Story
--------
It is The Future. You play the role of an adventurous computer user,
what the media might incorrectly label a "hacker." In search of a new
system to explore, you receive a tip about a mysterious computer, and
the computer's network address.

One day you attempt to make a connection with the machine, but your
attempts do not go unnoticed. The computer must have been some huge
classified secret, because within minutes, government officials
surround your house and demand your surrender.

You are taken to a mysterious underground complex where deadly robots
wander the halls. You see no alternative to breaking out and
leaving a trail of destruction behind you...


4. Controls and Indicators
--------------------------
Shotgun Debugger uses controls similar to popular first-person shooter
games. The game is viewed from an overhead perspective.

- W and S: move forward and backward
- A and D: sidestep left and right
- Left and Right arrow keys: turn left and right; the mouse can
  also be used
- Spacebar: jump
- Left Control or Left Mouse Button: fire selected weapon
- Tab: cycle through weapons
- 1, 2, 3, 4, 5, 6, 7: select weapon
- R: reload weapon
- Q or Right Mouse Button: throw a grenade (if you have any)
- V: switch view (see below)
- Z or Middle Mouse Button: quick zoom out (see below)
- F2: options screen
- F5: take screenshot (saved to ~/.sdb/ directory in BMP format)
- ESC: pause/abort game

The key assignments can be changed via the "Customize Keys" facility
in the Options menu.

Normally, the camera is centered on the player, and its orientation
remains orthogonal to the walls. Pressing V switches to "heading-lock"
view; the camera's orientation is locked to the player's heading, and
thus the camera rotates when your player turns. In this mode, the
player is always facing upward. The player is also offset slightly
downward, providing a fuller view of what's in front of him.

Pressing and holding Z will slightly zoom the camera out, to get a
wider view of your surroundings. Releasing the key returns the camera
to its normal position.

In the game, you will notice several indicators on the bottom of your
screen:

- The lower-left numeric display indicates your player's health
percentage. The display turns red and flashes if it drops below
25%. When it reaches 0, you're S.O.L.
- Directly to the right of the health display are three vertically
aligned lights; red, green, and indigo. These represent the keys you
currently possess.
- The ammunition remaining for your currently-selected weapon is
displayed in the lower-right corner. It is displayed in the form
XX:YYY, where XX is the number of shots left in the current clip, and
YYY is the amount of reserve ammunition you have.
- The name of the currently-selected weapon is displayed over the
ammunition readout.


5. Weapons and Power-ups
========================
The player can use six weapons in his mission to escape the facility:

- Energy Rifle (key 2): A futuristic, fully-automatic assault
rifle. A clip holds forty shots.

- Shotgun (key 3): Standard pump-action shotgun with kinetic energy
penetrating shells. It can hold six shells at a time.

- Highly Experimental Positron Accelerator (HEPA) (key 4): The HEPA
fires a high-energy cluster of particles that produces a very large
and deadly explosion on impact. The blast radius of the HEPA is very
large, so make sure you're clear when you fire it. The HEPA holds four
positron cells at a time.

- Fragmentation Grenade (key 5): Small explosive device that releases
deadly fragments on detonation. Grenades can be thrown with the
opposite hand when using the rifle or shotgun by pressing G or the
right mouse button. They bounce off walls and objects, and have a
three-second fuse. You can hold a maximum of ten grenades.

- Laser (key 6): The laser is capable of penetrating multiple enemies
at once, causing high levels of damage in the process. The weapon
requires some skill to use, because the beam is reflected off of
walls. Before firing the laser, ensure that you do not get hit by the beam!
The laser holds six power cells, allowing for six shots.
If you have a full load of six cells in the gun, you can charge the
laser by holding down the fire button. The laser will glow, and your
ammunition display will flash when the charge is complete. Releasing
the trigger releases a blast which does not bounce off walls and does
six times as much damage. It does, however, expend all six cells.

- EMP Shock Generator (key 7): The ESG is a weapon left
behind by the robots' former human masters, who used it as a means of
controlling unexpected behavior. When fired, the ESG emits an
electromagnetic pulse that temporarily disables all robots on the
screen. They will, however, regain consciousness after approximately
fifteen seconds. The ESG holds one battery at a time, and you can carry
six batteries at once.

Various powerups can be found scattered about the levels:
- Ammunition: Rifle clips (40 shots), shotgun shells (6 shots),
positron cells (4 shots), grenades, laser cells (6 shots), and ESG
batteries.
- Health pack: replenishes 25% of your health.
- Keys: The facility has several security levels; 1, 2, and 3. Areas
with special clearance require you to have the proper key to
enter. Key 1 is colored red, key 2 is colored green, and key 3 is
indigo. The colored lights to the right of your health display
indicate the keys you have in your possession.

Switches and control panels are found in some levels. These are
distinguished by a spotlighted glow around them. Walk up to and
touch them to activate them. They will usually open doors or perform
some other function.


6. Saved Games and Records
==========================
During gameplay, various statistics are recorded for each level:
completion time, number of enemies destroyed, number of shots fired
(including grenades thrown), and number of times hit.

Your progress is saved as you make your way through the game. If you
choose to exit the game, choosing the "Continue Game" option at
startup will return you to the level you left off at, with all your
statistics from your previous session.

When you choose "New Game" at the main menu, you may start a new game
on any level you have previously cleared. There is one caveat; see
next paragraph.

Records are also kept; shortest completion time, most enemies killed,
fewest shots fired, and least hits taken. These records are kept for
individual levels, and, when you complete the game, for your entire
run as a whole. Note that if you started your game on any level OTHER
THAN THE FIRST, you are NOT ELIGIBLE to set full-game records, and
your final statistics are not displayed.

The best records can be viewed by selecting "Records" at the main
menu. They can be cleared by selecting "Clear Records" from the
Records listing.

You can erase your saved game by going to the Options menu and
selecting "Erase Saved Game." Here, you can also choose to "Reset
Progress"--erase your game and your stored level progress, revoking
your privilege to start new games on levels other than the first. The
records are left untouched, though.

If you manage to finish the game in under 40 minutes, you'll receive
a reward--but be warned, you lose it when you reset your progress.
It also prevents you from setting new records.


7. Tips
-------
Shotgun Debugger is a short game, but it can be a bit frustrating at
times. Take these tips into mind:

- The "heading-lock" view mode is very useful in certain situations,
and can provide better aiming capability.

- Be sure not to pass up control panels and keys.

- Boxes and barrels can be pushed; use these to your
advantage. Deliberately destroying explosive barrels can be an
effective tactic, but make sure you are clear of the blast radius.

- Glowing white or red surfaces on the ground are usually
deadly. Avoid them. Also avoid glowing, transparent force fields, as
these also damage you. They also damage robots, so they can also be
used to your advantage.

- Have fun, kick lots of robot scrap, and send me a postcard.


8. FAQ
------
Q: I'm trying to compile the game, but I'm getting errors!
A: If you're getting linker errors, or messages about missing
libraries or header files, you don't have the SDL libraries
installed. They can be found at the following websites:

SDL:       http://www.libsdl.org
SDL_image: http://www.libsdl.org/projects/SDL_image/
SDL_mixer: http://www.libsdl.org/projects/SDL_mixer/

Also ensure you have the GL and GLU libraries and the corresponding headers.

If you're getting syntax or other compilation errors, then I suck at
coding. Send me the exact error message, your platform, and your
version of GCC. (contact info below)


Q: The game crashes when I run it!
A: If you're on Windows, you'll notice that a file "stdout.txt" is
created in the Shotgun Debugger directory after you run the game. This
file contains console messages; if the game crashes, you'll probably
find something informative here. Send me the contents of this file,
and a rough approximation of the circumstances under which the crash occurred.

If you're of the gearhead type, modify the Makefile to enable
debugging information (-ggdb) and run the program from GDB. Send me a
copy of the error message and the backtrace; I'll try and address it
as soon as I can.


Q: Is there a way I can see the current frame rate?
A: Yes. In the preferences.txt file, add the line "show_fps 1" to display the
in-game frame rate. (not shown for menus, etc.) Remove the line to turn the
display off.


Q: I'm on Linux, and the game runs slow as crap! Like, four frames per
second!
A: You don't have hardware accelerated graphics drivers. Check your
video card manufacturer's website for Linux drivers and install them
according to their instructions; the game should run fine once the
drivers are installed.


Q: I hate WASD! Can I change the key bindings?
A: Yes. Select "Customize Keys" from the Options menu. You cannot assign
actions to the Escape key, the number keys 1 through 7, or the F-keys.
At this time, you cannot change the mouse button assignments.


Q: The mouse is way too sensitive, or not sensitive enough. Can I
change the sensitivity?
A: Yes. Open up the preferences.txt file in a text editor (Notepad on
Windows). You should see a line that says "mouse_sensitivity
xx". Increasing this number makes the mouse more sensitive. The
default value is 20. Setting it to 0 disables mouse control.
If you want the game to ignore small mouse movements, you can increase
the "mouse_threshold" option.


Q: The game runs ludicrously fast on my computer, and it's affecting
the gameplay. What do I do?
A: While Shotgun Debugger, for the most part, runs identically at any
frame rate, very high frame rates may cause undesired effects. A
framecap option allows you to limit the number of frames per second
the game runs at. In the preferences.txt file, add the line "framecap
xx", where xx is the number of frames per second. It must be greater
than 15.


Q: I can't get past the first level! The agents keep catching me!
A: Run like hell down the street, and look out for shortcuts in
neighbors' yards. And remember, the shortest distance between two points 
is a straight line.


Q: What the hell does "shotgun debugger" mean?
A: Well, you've got a shotgun, and you're using it to exterminate a
robot pestilence. Give it some thought.

Actually, it comes from the term "shotgun debugging"--the Jargon File
(http://www.catb.org/~esr/jargon/) defines it as "the software
equivalent of Easter egging; the making of relatively undirected
changes to  software in the hope that a bug will be perturbed out of
existence. This almost never works, and usually introduces more bugs."
We think it's a cool name.


Q: I heard the game has cheats. What are they?
A: Your mom has cheats.


Q: I was trying to build an antenna in C++. I don't know where to
start. can anyone help me?? if there is some code that would
be even better. I don't care about the type of antenna as long as it
communicates.
A: Shut up. (posted in comp.object, Jan. 3, 2005)


Q: Does Wean Hall really have a ninth floor?
A: Once again, shut up.


9. Credits and Contact Information
----------------------------------
Project leader, programming, game concept, 2D art, and writer
of sweet readme files:
Matthew Sarnoff

Lead level designer, design feedback:
Chris DeLeon

Character models:
John Nesky

Level designers:
Gregory Peng
Jeff Thoene

Sound effects:
Matthew Sarnoff
Chris DeLeon

Music:
Tuscan Knox

Testing:
Michael Weber

Shotgun Debugger is a product of the Game Creation Society, a
nonprofit organization at Carnegie Mellon University.

The Simple DirectMedia Layer is released under the GNU Lesser General Public
License. See LICENSE_SDL for more details.

Shotgun Debugger website:
http://sdb.gamecreation.org

GCS website:
http://www.gamecreation.org

Shotgun Debugger message board:
http://board.gamecreation.org, requires free ezBoard registration

Matt's website:
http://www.contrib.andrew.cmu.edu/~msarnoff


If you have questions, bug reports, suggestions, etc. e-mail Matt
at msarnoff@andrew.cmu.edu.


June 10, 2005
