                          Search and Rescue

                             Version 0.6

                            Hacking Guide

    Note: Version represented in this document may be out of date, verify
    version above with actual version of accompanying source.


Contents
--------

   * Submitting Changes
   * Source Layout


Submitting Changes
------------------

    Changes !!ARE NEVER ACCEPTED!! before initial contact with authors,
    please contact authors first before submitting changes.

    http://wolfpack.twu.net/contacts.html


Source Layout
-------------

Note, $TOPLEVEL represents this source's toplevel directory.
Most (not all) .c and .cpp files will have an accompany .h file with the
same name.


    In $TOPLEVEL/include:

	These file are global include files for most of the general
	globally shared functions.

    In $TOPLEVEL/sar:

	This is the source directory for the program.

	Makefile.*	Makefiles for compiling and installing under
			UNIXes.

	Makefile.srclist	List of header files and sources for
				other Makefiles.

	cmd.c		SAR Command line front end, passes inputs to
			other functions in cmd*.c sources.

	cmd*.c		SAR Command line handler functions.

	config.h	SAR Globally configurable constants.

	explosion.c	Explosion object creation.

	gctl.c		Game controller (keyboard, joystick, etc) input
			wrapper, takes input from device specific
			functions and updates the game controller (gctl)
			values which other functions rely on for
			controller values.

	gw.h		GUI wrapper header.

	gww.cpp		MSW GUI wrapper functions.

	gwx.c		X11 GUI wrapper functions.

	gwx_dialog.c	X11 GUI dialog wrapper functions (since Xlib
			does not have a built in dialog system).

	horizon.c	Generates a 1d horizon texture.

	image.c		IO and drawing of images, using the GUI
			wrapper functions to draw them.

	main.c		Program main function and other core
			operations functions (including timming,
			signal handler, GUI wrapper callbacks, etc).
			See sar.h for header info.

	menu.c		SAR menu object (widgets) core.

	menumap.c	SAR map menu object (widget) handler.

	messages.c	Handles and draws messages printed on screen in
			game.

	mission.c	Mission handling core.

	missionio.c	Mission file IO.

	obj.h		SAR object definations.

	objio.c		SAR scene and object file IO.

	objiocb.c	SAR scene and object file loading progress
			callback.

	objiopremodeled.c	Creates SAR premodeled objects.

	objutils.c	SAR scene and object utility functions,
			including deleting, checking, list io, etc.

	prefio.c	SAR preferances file IO.

	sar.h		SAR core header file.

	sardraw.c	SAR in game drawing routines, uses OpenGL
			and a bit of the GUI wrapper code.

	sardrawpremodeled.c	Supplmentary functions for sardraw.c
				to draw premodeled SAR objects.

	sarinstall.c		Creates/coppies global program
				configuration and data files/dirs to
				local user's directory.

	sarkey.c	In game keyboard key handling, called from
			functions in main.c. If key input is not
			handled, it will be passed to the gctl.c
			functions.

	sarmenubuild.c	Creates the menu and their menu objects
			(widgets), then sets up the initial data and
			callbacks.

	sarmenucb.c	SAR menu callback handlers.

	saroptions.c	SAR supplmentary callbacks for the options
			menu, also includes options fetch and apply
			to menu objects (widgets) functions.

	sarutils.c	SAR primary utility functions that handle SAR
			global and core level things.

	sarreality.h	SAR simulation, reality, and timming constants.

	sfm*.c		SAR Flight Dynamics Model (SFM) library, called
			by the sim*.c functions.
                        Note that this is really an intigrated library,
                        it may be made into a shared library (so) later
                        on.

	sfm.c		SFM realm init, shutdown, and management.

	sfmmath.c	SFM math utilities, includes conversions and
			angle calculation functions.

	sfmmodel.c	SFM flight dynamics model IO.

	sfmsimforce.c	SFM flight dynamics model engine, simulates
			forces acted on the fdm.

	sim*.c		SAR simulation functions, calls and manages sfm*.c
			functions.

	simcb.c		SAR simulation callbacks for the SFM.

	simcontact.c	SAR simulation object to object contact/collision
			checking and handling.

	simmanage.c	SAR simulation core functions, primary
			calling source to the SFM functions.

	simop.c		SAR simulation operations and procedures, mostly
			procedure functions for simmanage.c.

	simsurface.c	SAR simulation surface checking, checks position
			against landable/walkable ground.

	simutils.c	SAR simulation calculation and simple
			modification utility functions.

	smoke.c		SAR smoke object creation.

	sound.c		Y2 sound wrapper, handles playing and management
			if Y sound play objects.

	textinput.c	In game text input prompt handling.

	texturelistio.c	Standard textures list IO, loads a list of
			referances to standard textures to be loaded
			for each scene.

	v3d*.c		Vertex 3D (V3D) visual models and textures IO.
			Note that this is really an intigrated library,
			it may be made into a shared library (so) later
			on.

	v3dfio.c	V3D visual model file IO.

	v3dhf.c		V3D heightfield image file IO.

	v3dmodel.c	V3D visual model IO.

	v3dmh.c		V3D visual model header items IO, header items
			used in recording the header block items in each
			V3D visual model.

	v3dmp.c		V3D visual model primitives IO, primitives used
			on each V3D visual model.

	v3dtex.c	V3D texture (image) file IO.

	weatherio.c	Weather file IO, weather file specifiying
			available weather settings.


                                                         -----------------
                                                         Search and Rescue
