0. Contents of This Document
----------------------------

    1. Compilation Instructions
    2. Specific Compilation Instructions on Amiga (from Ralf Eisele)
    3. Running Crystal Space
    4. Special Comments for X Windows Version
    5. Commandline Arguments And The Config File
    6. The Console



1. Compilation Instructions
---------------------------

Before compiling Crystal Space you should edit 'types.h' and see if it
conforms to your system.

After that you must make sure that you have the 'zlib', 'libpng', and
'jpeglib' libraries compiled which you can find in 'src/zlib', 'src/libpng',
and 'src/jpeglib'. Read the README there for installation instructions.
Note that the PNG and JPEG libraries are optional. If you don't want/have
them you can exclude them in 'cs.mak'.

For example, if you don't want JPEG support then you can change DO_JPG=yes
to DO_JPG=no inside cs.mak. Note that for all levels which are currently
available on the home page you only need GIF support. You can safely
remove PNG and JPEG support.

After that you can try to compile Crystal Space.
To create Crystal Space from the source you can use one
of the provided makefiles:

	makefile.djg			DOS/DJGPP.
	makefile.bsd			BSD and X Windows.
	makefile.lnx			Linux and X Windows.
	makefile.svg			Linux and SVGALIB.
	makefile.ggi			Linux and GGI library.
	makefile.sol			Solaris and X Windows.
	makefile.sgi			SGI/IRIX and X Windows.
	makefile.unx			general Unix and X Windows.
	makefile.os2			OS/2.
	makefile.wnt			Windows NT with GCC.
	makefile.aos			Amiga.

	makefile.l68			Amiga with Linux.
	makefile.wat			DOS/Watcom.
	makefile.wwc			Win32/Watcom.

The first eleven makefiles all use the file 'cs.mak'. Edit 'cs.mak'
for specific Crystal Space options that are configurable at compile
time.

Or one of the following project files:

	mac_prj.sit			Macintosh.
	system/wcc/cryst.wpj		DOS/Watcom.
	cryst.tgt			DOS/Watcom (or makefile.wat).
	wincryst.tgt			Win32/Watcom (or makefile.wwc).
	win32/cryst/wincryst.wpj	Win32/Watcom.
	win32/cryst/wincryst.dsw	Win32/Visual C++.
	win32/cryst/wincryst.dsp	Win32/Visual C++.
	system/win32/CrystalSpace.*	Win32/Visual C++ project files

Edit the makefile (or cs.mak if you are using one of djg, bsd, lnx,
ggi, sol, svg, sgi, unx, wnt, os2, or aos) and possibly make changes as
explained in the makefile. Then type:

	make -f makefile.??? cs

or

	gmake -f makefile.??? cs

This should generate a correct executable ('cryst' or
'cryst.exe'). It is possible that you will have to do a:

	make -f makefile.??? depend

first to generate correct dependencies (you will know when
make starts compiling about not being able to make certain
files). Note you need the Unix utility 'sed' to be able to
use 'make depend'. If you don't have 'sed' just edit
'cs.dep' and make it empty. Then you can just try to compile
CS again.

Note! the makefiles for djg, bsd, lnx, ggi, sol, svg, sgi, unx,
wnt, os2, and aos require GNU make!

Note! Since I don't have easy access to a Windows, Amiga, OS/2,
or Macintosh compiler I can't test/change the makefiles or project
files belong to that port. Sometimes I add a new source file or
so. In that case these makefiles or project files will no longer
work and you will have to change them yourselves (if possible).

(Note! Since the OS/2 and Amiga ports use the standard 'cs.mak'
file they will probably work correctly when I add files).


2. Specific Compilation Instructions on Amiga (from Ralf Eisele):
-----------------------------------------------------------------

This is a little doc for compiling Crystalspace on the Amiga:
I will transform this piece of text into a Guide file when I have
more time on my hands.

- First of all you need to install the Amiga GNU compiler.
  (How to install and get the GNU compiler is not yet documented)

- After you installed the GNU compiler you need a assign to
  the GNU compiler.
  Put the following assign into your s:startup-sequence or into
  your s:user-startup.

  Assign gg: <Your path where you have installed the GNU compiler>

  If you want to change the assign from gg: to something else
  remember to also change it in the makefile.aos ( -Igg:include )

- Unpack the Crystal Space archive in a directory of your choice.
  A directory cryst will be created for you.

- Unpack the zlib_1.1.1.tgz archive. Unpack this archive in the
  cryst directory. If you want support for PNG or JPEG you can also
  unpack the libpng.tgz and the libjpeg.tgz into the same directory
  as zlib_1.1.1.tgz (in directory cryst). These two aren't needed to
  a working Crystal Space version.

- You need to make the zlib. This is done by compiling the z.lib
  library. Go to the zlib directory (cryst/zlib) and type
  "make -f makefile.aos" without the quotation marks.

  If all goes well you will get a zlib.lib file. To be sure that
  the zlib file is OK you can also type  "make -f makefile.aos test".
  Now the zlib will be build and the zlib will be tested to see if
  it has been build correctly.

- to avoid thousands of warnings you have to change two include
  files.
    - GG:include/dirent.h: change the line "#ifdef amigados" to "#ifdef _amigaos_"
    - GG:include/sys/stat.h: ""   ""   ""	   ""	""	 ""

- Compiling without FPU:
  Set DO_ASM to no in file cs.mak

- Compiling with FPU:
  DO_ASM=yes and add to the Flag HOW_OPTIMIZE "-m68881"

- If you don't have png, jpeg installed set DO_PNG=no and DO_JPG=no
  in file cs.mak. You will need the GIF switch because without it
  your program will do nophing.

- Before you can compile CS you will need to add a include directory
  where the GNU make can find the Amiga specific includes like exec/type.h
  etc. This is essental, or the Amiga.cpp will not be compiled.

- This is all that I could think of at the moment, more will be added. Any
  comments will be appreciated.

Note: Be aware of using an editor who expands the TAB key to spaces.
      Your makefiles wouldn't work correctly. GOLDED is such an editor,
      it costed Ralf Eisele hours to find what was wrong whith his
      makefile.


3. Running Crystal Space
------------------------

To run Crystal Space you need at least the following:

    1. An executable (cryst.exe, cryst, wincryst.exe, ...)
    2. The configuration file: cryst.cfg
    3. One or more level files (*.zip)

And of course you also need a computer :-)

The executable and the configuration file must be located in
the same directory. The level files may be put anywhere. Please
note that the level files should NOT be extracted. Crystal Space
can read zip files directly and this is also the prefered way.

To run Crystal Space with a specific level you have two
possibilities (lets assume that you have put the level in a
directory called 'data' and this directory is located in the
same directory as the executable):

    cryst data/level.zip

(replace level.zip with any level you want).

Otherwise you can edit cryst.cfg and set WORLDFILE=data/level.zip
as a configuration option.

Note that Crystal Space currently only supports 256-color displays
(with a colormap) or 15/16-bit truecolor displays (note that Crystal
Space may not support 15/16-bit mode on all systems).

When Crystal Space starts it will begin calculating several tables.
Depending on the type of your display (8-bit or 15/16-bit) and on
several configuration values it will need to calculate a different
number of tables. In 8-bit mode it is possible that the calculation
of these tables takes such a long time that Crystal Space will cache
them inside the level file (Crystal Space will automatically add the
needed tables to the zip file if they are not already there).
Note that all levels available on my home page already contain these
tables if they need them.

Sometimes Crystal Space may complain that some table or lightmap
is not up-to-date. Don't worry, due to small inaccuracies in the
calculations it is possible that the same table or lightmap is calculated
differently on several systems. In that case Crystal Space will (often)
detect this and automatically recalculate the offending object (you need
not do anything for this except wait until the calculations are finished).
This should not happen again if you run Crystal Space again with the
same level.


4. Special Comments for X Windows Version
-----------------------------------------

Note that the X version of Crystal Space optionally supports the Shared
Memory Extension (SHM). This makes Crystal Space run much faster if your
server supports it (Crystal Space should also support DGA but this is not
yet the case).

By default Crystal Space assumes that your server supports SHM. It will
automatically autodetect if your server doesn't support it. So you can
safely leave it enabled.


5. Commandline Arguments And The Config File
--------------------------------------------

Crystal Space supports a number of commandline options. With
'-help' you get a list and a description (including the default
that is used for that option). The default for every commandline
option is set internally in the program unless there is a
corresponding line for it in the config file. For example,
normally the default for -cache is 5000000 (the default size
of the texture cache). But when CACHE=2000000 is set in 'cryst.cfg'
the default will be 2000000. Using an option on the commandline will
always override the default.

Some interesting options to play with are:
  -nolight
	To disable the lighting system. The only purpose of this option
	is to make the startup faster and it can be used to test some
	things. It does not influence the frame rate so it can be used
	to quickly test the speed under several different configurations.
  -physics
	There is a preliminary physics system in Crystal Space which is
	off by default. By giving this commandline option you enable it.
	Give it a try. It is fun (although a bit sluggish currently).
  -mode 640x480
	(or an other value). Use this option to set the size of the display.

The configuration file ('cryst.cfg') is useful for keeping options that
you use often. Not all options can be set with the configuration file
though, and not all configuration file options have a corresponding
commandline option. See docs/config.txt for a complete list of all
configuration file options.


6. The Console
--------------

Starting with version 0.06 there is also an input/output console that
you can use. Press 'tab' to toggle between the console and normal output.
There are several commands that you can use. Type 'help' to get the
list of commands. There is a section in docs/document.txt describing
all these commands.

Note that typing in this console is currently a bit cumbersome depending
on the operating system. In DOS you will either have to type very slowly
(if you have a low framerate) or press the keys very slightly. This
will hopefully be fixed in the next version. In X Windows the console
works much better.

