Learning Crystal Space

Crsytal space is a 3d engine library. A free one. With full source code. And very little documentation.

It is scarily complete. With just a few pages of code, you can write a full quake-like game. It natively supports advanced features such as procedural texturing (water and fire to you and me) bumpmapping, dynamic lights, portals, shadows, sparkly particle effects, HUD overlays, alpha blending, window manager, networking, input devices and sound.

Another advantage to this engine is the number of targets. A single binary can load in plugins to run in software, directX or openGl (as well as a couple of esoteric others) - and the same code can be compiled to run natively on DOS, windows, mac, linux, os2, beos and even the amiga.

So - there's the good stuff. The bad stuff is it's a bit clumsy to learn. So follow me as I try to do so :)

Baby steps

You can't do anything till you've got it installed. Here's my steps on how to install it.

I'm going to assume you're doing this for windows. If you want to do another system, be my guest but don't expect me to know how to do it.

1. Read the FAQ - this should tell you how to get started.
2. And it does. Section 2.4.3 Platform specific installation instructions for windows using mingw32 (just trust me on the mingw32 for now)
3. First we need a compiler. Mingw32 is a decent one, and they've made a package that has all the extra little bits that CS needs too. This saves effor,t so we'll use that. [Download - 13Meg]
4. Ok, so we do need one extra little bit. Nasm is the assembler that we will use. [Download - 165k]
5. And then we need CS itself. May as well grab the whole thing. [Download - 20Meg]
6. Now, follow the instructions in that FAQ. First install everything (nasm goes into mingw/bin)
7. You have to set a few environment variables. On NT that's right click 'my computer' and on win9x it's editing your autoexec.bat. Note that if you installed mingw elsewhere, then you need to change that bit
8. SET PATH=C:\mingw32\bin {NOTE - add this before the rest of the path, so the final instruction will be something like SET PATH=c:\mingw32\bin;c:\dos;c:\windows;c:\windows\command}
9. SET PYTHON_INC=C:\mingw32\include\python1.5
10. SET PYTHONPATH=C:\mingw32\lib\python1.5
11. You do NOT need to reboot. Just open a new command (DOS) window and if you're on win9x run autoexec.bat from it. {c: [ENTER] cd \ [ENTER] autoexec [ENTER] }
12. Now we need to build the library, and a load of examples. This will take about 1/4 of an hour on a fast machine, maybe longer. Take a quick nap.
13. Change to the base directory of crystal-space (c:\CS unless you changed it)
14. In the DOS window run the following make commands in order
    1. make win32gcc MODE=debug
    2. make depend
    3. make -k all {this is the one that takes ages}
15. Now you can enjoy the prettiness. You should have a load of demos to look at - try running vsh, bumptest, csdemo and walktest (You'll have to read the manual for the keys) Also try running them with -video=opengl

Ok, one thing. When I say 'with -xxx=yyy' I mean that you add that on the command line. If you are running them from a DOS window, you literally just add that onto the end of the command {ie. bumptest -video=opengl } - if you are running them from within explorer, then you will need to make shortcuts, and put that on the end of the 'target' box.

Ok, that's enough for now. For homework, I suggest that you run through the tutorial chapter in the manual (you've got a copy of it on your HDD now, in /CS/docs ) and work your way through the example code that goes with it.

I strongly suggest that you do it all by hand, rather than just skipping to the different versions on disk.