This directory contains my asteroids game.

Roadmap to the files:

Makefile
	The Makefile I use when working on it.  You likely will need to
	tweak this to make it work for you.

README
	This file.

a.c
	The main game source.

afont.c
	The line-drawing font definition tables and code to use them.

afont.h
	Interface definition for afont.c.

ahelp.awk
ahelp.txt
	The help screens text (.txt) and an awk script to turn the .txt
	file into a .c file for compilation (.awk).

gl.c
gl.h
	The machine-independent part of the pseudo-GL code.  If you
	want to port to a new keyboard and/or framebuffer, read gl.doc.
	This is not even close to a full GL implementation; it is just
	barely enough to get the game to run.

gl.doc
	Documentation on the interface between gl.c and the gl-idev-*
	and gl-odev-* modules, and the gl-md-asm.h interface.  If you
	want to port it to a new keyboard, framebuffer, or CPU, this is
	what you need to read.

gl-int.h
	Internal interface definitions, for use by gl.c and the various
	keyboard and framebuffer modules.

gl-idev-none.c
gl-idev-sun3.c
gl-idev-sun4.c
	Input device modules.  "none" is a dummy input device that
	never produces input; it is useful for some debugging and
	testing operations.  sun3 and sun4 are for Sun type-3 and
	type-4 keyboards.

gl-odev-bwtwo.c
gl-odev-cgthree.c
gl-odev-cgsix.c
	Output device modules.  bwtwo is for Sun machines with bwtwo
	framebuffers, cgthree for those with cgthrees.  The bwtwo file
	also provides a display called "smallbwtwo" which uses only a
	half-size screen in the centre of the display.  It is useful
	primarily if you want to improve the frame rate and are willing
	to give up the resolution to get it.  cgsix is for cgsix
	framebuffers, and is actually the snappiest of the lot, because
	it knows how to take advantage of the hardware's line-drawing
	capabilities.  (It also does colormap-based double-buffering,
	which makes for a very smooth display.)

gl-md-asm.h
	Interface .h file for some routines commonly written in
	assembly for speed.  See gl.doc for more.

gl-asm-sparc.s
	The SPARC assembly implementation of the gl-md-asm.h interface.

gl-generic.c
	A generic C implementation of the gl-md-asm.h interface.  This
	should work, if there's no machine-specific module for your
	machine, but is likely to be comparatively slow.  It's
	certainly usable for testing the rest of a port, though.

machine/*
	Include files to make it possible to build on a stock system
	without having to litter the source with excessive ifdefs.

dumpbwtwo.c
	An auxiliary program for dumping the contents of a SPARC bwtwo
	under NetBSD.  Primarily useful when logged in to such a
	machine over the net and debugging the game.  (Output is a pbm
	file.)

linetest.c
	A test program that draws some lines.  If this won't work, you
	have little hope of making the full-fledged game work;
	conversely, if this works, the output side of the full game
	should work.

states.doc.1
states.doc.2
	Two different files that appear to be documentation for the
	internal state transitions of the game.  Useful only to people
	who wish to hack on the internals.

x.c
	A program that might help you determine a good value for
	TICKS_PER_SEC if you're trying to do a port to another system.

At least one version of gcc (2.6.3 for SunOS 4.1.2 on the SPARC) is
known to miscompile this code.  adjletter(), called from
controlbutton(), gets inlined wrong - it behaves as if let (in
adjletter()) were unsigned rather than signed, or perhaps more
precisely, it loses the "if (let < 0)" comparison and the code
controlled by it.  The effect is that when using turn-left to step from
space to left-arrow when entering a score, the display weirds out for a
few keystrokes.  It eventually recovers if you keep pressing
turn-left/turn-right.

This program expects to "own" the keyboard and screen for the duration
of the run.  If you have other similar programs running, it will
probably fail to start up; the usual symptom is an inability to open
/dev/kbd and a consequent inability to find a keyboard it can use.  The
commonest case is a window system like X, which will likewise expect to
own the hardware for the duration.  This game does not get along with
things like X; shut them down to run asteroids.