README for tsshp-0.2.10f 21-Apr-2003
====================================

This is the shack (Shock Hack) code for TSSHP. It runs under Linux/XFree86
 (though it ought to work on other X-based systems with minimal tweaking) or
 under the SDL (Simple DirectMedia Layer) games API for Linux or Win32. (Who
 wants to do the Mac/BeOS ports, then?)

TSSHP is distributed under the (modified) BSD licence; see the file LICENCE
 for details.

What it does
------------

A 3D renderer which lets you explore Citadel Station from System Shock (or the
 Stygian Abyss, or the Labyrinth of Worlds). The basic architecture is present
 and fully texture-mapped. Wall decals (icons, switches, paintings, stains,
 bullet holes etc.), sprites and 3D models are drawn. Cyberspace levels for
 System Shock are drawn wire-framed and depth-cued.

Static and dynamic lighting is supported, up to a point, for architecture and
 objects. The only dynamic light so far implemented is the Avatar's lamp for
 Underworld.

The main framework for the MFD/HUD is present, courtesy firefreak. The
 sensaround multi-view display for System Shock is supported, as is an automap
 feature both in an MFD and as a transparent heads-up map in the main view.
 Other transparencies (force doors, bridges, invisible mutants) are rendered
 for System Shock.

Hardware acceleration, if you have a 3D graphics card, is supported using
 OpenGL for the cyberspace wireframe and for "real-space" levels (though light
 sourcing is still done in software).

Physics clipping is not performed. Physics simulation in general is absent
 (viewpoint is clamped to a fairly arbitrary distance above the base floor
 height).

It's probably of interest only to fairly serious hackers at the moment. The
 resfile reading routines might be of use to those wanting to extract bits of
 data. (Well obviously). There are odd lurking bits of code that were things
 I wanted to try out, or aren't ready for use yet, or I just haven't got
 round to removing. They might be interesting. Or good for a laugh.

See the changelog for changes to version 0.2.10e .

The changes from previous READUS are now in the file CHANGES (SourceForge
 insists on a changelog when editing release details)


How to get it going
-------------------

This section deals with compilation under Linux. For the Windows executable
 release, see the file README-Win32.txt

You need the following:

	Linux, or a suitably Linux-ish Unix implementation. (I haven't tried
	 to get TSSHP running under Unix, so I don't actually know what
	 "suitably Linux-ish" means).
	X (tested under XFree86 4.2).
	Development tools for C and X programming.
	System Shock and/or Ultima Underworld (either one). TSSHP ought to work
	 with the floppy version of System Shock or the demo.
	If you want to use the SDL, you will need at least a version 1.1 SDL.
	If you want audio you need SDL_mixer in addition to the SDL library.
	Similarly, hardware acceleration requires at least version 1.1 OpenGL
	 libraries and headers.

You'll have to change the paths in cyb.cfg unless you have the CD mounted under
 /cdrom . To use Ultima Underworld levels you must change `uwdata' in the same
 place to point at your Underworld installation.

The starting level is now specifiable on the command line, as of 0.0.pre3 .
 The starting position is automatically set to a convenient elevator in all
 levels except 1 where it's the healing machine where you start.

The default build now uses OpenGL. If you want a software-only version (slow)
 you will need to comment out the line GL_OBJS in accel/Makefile.linux and
 change HAVE_OPENGL to 0 at the bottom of src/defines.h .

If you are using the native X version you must set BITS_PER_PIXEL in
 src/defines.h according to the bit depth of your X server. The only bit
 depths currently supported are 8 and 32.

The makefile is very simple and shouldn't need any editing. Just extract the
 files and type `make'. If all goes well you should be able to run the
 executable by typing `./shack'.

Controls
--------

S forwards, X back, A left, D right. Z/C strafe. Cursor keys will work as
 well, as will the numeric keypad if you've got your keymap set up right.

ESCAPE quits. This now turns auto-repeat back on properly under X.
 You also could try CTRL-X - with the new control system this should work, too

Pressing F12 will cause a screenshot to be written to disc. This defaults to
 PNG format under Linux, otherwise will write a TGA. Screenshots are called
 `shackXX.png' or `shackXX.tga'.

Pressing `-' will print the current map coordinates of the viewpoint to the
 console (stdout). These numbers are given in hex at a resolution of 256
 points to a map tile. 

`3' activates the sensaround multi-view display in System Shock mode. Backtick
 (`) will bring up the heads-up map. (It's really cute).

Page Up and Page Down move between levels.

There are many more controls already - read the configuration to get them
 all (control.cfg) - Yes, this means that they are finally reconfigurable.

Configuration and Command-line Options
--------------------------------------

Default options can be set using the file cyb.cfg in the TSSHP base directory.
 This is a text file, one line per option. Configuration file options are
 exactly the same as command-line options, but without the leading `-'. 

Options are

-d, -dump [chunk]	Produce hex dump of chunk for debugging
-dump-strings		(Underworld) Dump all game strings to console
-dark-gamma		(Relative) gamma correction for light levels
-e, -extract		Chunk number of bitmap to extract (Linux, PNG only)
-extract-sub      	Subchunk of bitmap to extract
-f, -frame-times	Print frame rate to console
-fov			Field-of-view angle in degrees (left-to-right, 1-179)
-fullscreen		(SDL) Try to run in fullscreen mode
-h, -height		Window height in pixels
-no-alogs		Disable playing of audio logs and emails
-no-hud			Disable HUD (for benchmarking the 3D renderer)
-no-vmail		Disable vmail
-nosound		Disable all sound
-p, -print-map		Print ASCII map of level to console
-s, -start-level	Start level 0-15 (R, 1-9, SHODAN, groves, c-space)
-u, -uw			Play Ultima Underworld instead of System Shock
-w, -width		Window width in pixels
-x, -xpos		Start at X position
-y, -ypos		Start at Y position
-cddata [dir]		Set directory to look for System Shock CD files
-hddata [dir]		Set directory to look for files that Shock usually
			 installs to your hard disc
-uwdata [dir]		Set directory to look for Underworld data files
-mfdcfg [file]  	file for MFD priority configuration
-concfg [file]      	file for control configuration (default: control.cfg)


Control configuration
---------------------

When you look at control.cfg you'll see the following format:

For triggers:
[Action]
<Mode>;<Type>;<Key>[+Modifier]

For operations:
[Operation]
<Mode>;<Movement>[+Modifier]

The [Action] or [Operation] mark the beginning of a block - the
following lines are the bindings to this Action or Operation.

The <Mode> describes in which Mode this binding is valid. 
(but don't think it's valid in this mode alone -- more to that later)

<Type> for Actions have following possible values:
SYNC     as long as the trigger is 'down' the action is performed
TRIGGER  every time the trigger goes 'down' action is performed
SWITCH   action is performed at first press (+release) and stopped
         with second press (+release)
typical bindings:
[Walk Forward]
Action Mode;SYNC;s
[Compass]
Action Mode;SWITCH;7
[Screenshot]
Global;TRIGGER;F12

<Key> is clear ;)
<Modifier> are (up to 4) '+' added modifier, which have to be
down too with the <Key>

<Movement> is the movement that is bound to the operation

see bottom of control.cfg for valid special keys and Movements.

Modes:
internally are (currently) 7 Modes used:
Writing, Menu, User Modes 1 - 3, Action Mode, Global
Their priority is from left to the right.
That means: the same binding in a higher priorised mode
executes it's action instead of the lower one.

The user is only allowed to set bindings for User Modes 1-3 and
Action mode.
GlobalMode is only readable (so you can't redefine the
screenshot key in global mode for example)

MenuMode is reserved for menus; WriteMode for textual input.

TSSHP grants only access to one User Mode at a time - so
no mixing here.

If you feel you have mixed something up and don't know how
to get out, just delete the control.cfg and start/stop TSSHP.
The file will then be written with the preset defaults.


MFD configuration 
-----------------

(also see the comments in mfd.cfg)

With the configuration file (mfd.cfg) you define
1. What should be displayed where on which event and
2. Which priority do the events have in correlation with the
   shown data

The [events] section should be easy to understand, so with
the mfd sections -- but the the key is to get behind the
clou of the last three ;)

An example:
[events]
target.new;target;weapon
[left]
none
target.new
map
target
[center]
none
inventory
target.new

Event section:
When you get a new target you want it's info to the left and
weapon list in center mfd.

Left section:
- When you see nothing to the left, no event will change that
  (since it's the topmost = highest priority)
- Although you may see the map which is above target info the
  event still will show target info, since the event itself is
  above 'map' (if you understood that case you got the whole
  system :)

Center section:
When you see nothing or are skimming through your inventory the
event will not change that, since both are above

If an event or a MFD card isn't listed it's got the lowest
possible priority - thus: events not listed will never show up
and cards not listed will probably pushed back by events.

Yes, one can set up bogus priorities which can behave
obscure, but this is what it makes so strong.


Sound / Music 
-------------

If you want to build TSSHP with sound, then you just need to make
sure that you have the latest version of the SDL_Mixer library.
This is required in addition to the latest version of the SDL library.

Under Windows you will get music without any configuration changes.

If you don't like the track that is currently playing, press the "]" key.

Linux music support is available, but only if you are using the SDL_mixer
driver. To enable this support you also have to download the full set of
"GUS Patches" which enable the Timidity MIDI player to convert the Midi
data into Wave data that can be mixed by the system.

Details of what to download and where to put them are in the README files
for the SDL_mixer library. Under debian you just need to install both
timidity and timidity-patches, on other distributions you will have to
download the patches themselves, but be warned that these are 15Meg big :)


Bugs and Problems
-----------------

Static lightmaps aren't displayed in exactly the way that they appear in the
 original. TSSHP's static lighting model is almost, but not quite, compatible
 with System Shock's. I don't think that this is too much to worry about, to be
 honest.

Other decals are sometimes visible through doors. (They aren't properly sorted
 within their tiles at the moment).

The tile sorting algorithm is improved, but I'd like better clipping. I might
 try my hand at a full occlusion engine, cos that sounds like fun.

Control input has not been tested with very special cases. Either it would
 work, or it just wouldn't -- if it does not, mail firefreak.

It's very slow.


Wishlist
--------

Too many things to mention, but I think it can be summed up as "we want to
 write the games Looking Glass would have written if they'd had today's
 technology". Now there's a mission statement for you.


I think that's about all we need. Mail me if you have trouble. Or if you don't.
-- 
jim       (jim@madeira.physiol.ucl.ac.uk)
firefreak (firefreak@ping.at)
Bryan	  (bryan@r3v3ng.net)
