Frequently Asked Questions for Crystal Space V0.11

Note! I removed all answers regarding to versions older than 0.14. This is the latest release and you should not use anything older.

• Where can I download Crystal Space?
• What do you need to compile Crystal Space?
• What do you need to run Crystal Space?
• I downloaded Crystal Space and it won't run!
• What about documentation?
• Running Crystal Space more memory efficient.
• Crystal Space is really slow on my computer. Can't something be done?
• How to contribute textures.
• How to contribute to Crystal Space in general.
• How does Crystal Space work?
• Writing a game/MUD/RPG with Crystal Space.

Where can I download Crystal Space?
A1. The latest beta release (0.15) can be downloaded from:

• My Home Page
• FTP Space for my home page

What do you need to compile Crystal Space?
A1. A compiler and a computer! :-)
A2. Seriously though. Although you really need a compiler and a computer you obviously need more than that: you need the Crystal Space source archive :-)

What do you need to run Crystal Space?
A. You need the following:

• The WalkTest executable. This is a demo program that is included in the main source archive. This is what most people see as 'Crystal Space' although it is actually only a program using Crystal Space. Note that there exist two types of executables: staticly linked and dynamically linked. If you have a staticly linked executable (for example, the DOS executable will always be static) then you don't need any of the following drivers. Otherwise you will need:
• A 3D Rasterizer library. You can choose either the software renderer or else one of the hardware accelerated renderers. You also have to choose the correct library for your system. On OS/2 and Windows this will be a DLL file. On Unix (Linux) this will be SO file.
• A 2D Graphics driver. Some of the 3D Rasterizer libraries already contain the corresponding 2D Graphics driver but the software renderer does not. In that case you need to download the correct 2D Graphics driver for your system.
• The Network NULL driver. This driver provides dummy networking support for your system. Download this if you're not interested in networking (just yet).
• The Network Sockets driver. This driver provides a socket networking implementation. Use this if your system supports this and you want to experiment with networking.
• The 'csregsvr' utility (if you are not on Windows and if you are using a dynamicly linked executable). This utility is required to register all the above libraries. On Windows you must register them using the standard utility RegSvr32.
• For all features in Crystal Space to work correctly you should also download 'standard.zip'. You should NOT extract this file, Crystal Space can read from the ZIP file directly. It contains additional data that is used by the engine. If it is not present then some features (like sound and the missile) may not work correctly.
• Finally you need at least one level file. This is also a ZIP archive (like large.zip, maze.zip, or room.zip) and should NOT be extracted. Note that 'mazed.zip' is NOT a level file and is ment for MazeD. 'standard.zip' can also not be used as a level file.

I downloaded Crystal Space and it won't run!
A1. Are you sure that you have downloaded everything as explained in the two previous questions? If so then go to the following answer.
A2. Crystal Space requires an 8, 15, 16, or 32-bit display and will not work on other displays currently.
A3. Several people coudn't run Crystal Space because they downloaded an executable and it didn't seem to be a valid executable. It turned out that the problem was that their browser removed the 'gz' extension from the file while downloading without decompressing it. The executables that you can downloaded are compressed with 'gzip' and you first need to decompress them before you can run them.
A4. If you are using a dynamicly linked executable (like the ones on Linux, Windows, BeOS, Macintosh, and OS/2) then you should not forget to register the COM drivers included with CS (the 3D Rasterizer, the 2D Graphics Driver and the networking drivers). On Windows this is done with the RegSvr32 utility (just type RegSvr32 ???.dll). On Linux/Unix this is done with the 'csregsvr' utility (just type csregsvr *.so). Instructions on other systems will be similar.
A5. Are you sure it is trying to load the correct level? If you are running with a commandline (DOS-box or a Unix shell) you can try to give the level you want to run on the commandline like this: cryst ../data/maze.zip. Otherwise you can also edit 'cryst.cfg' and change the line 'WORLDFILE=...' to the correct level.
A6. If all else fails mail me :-)

What about documentation?
A. There is a lot of documentation available. Not all of it is completely up-to-date but we try to do our best in keeping them as up-to-date as possible. Here are quick pointers to all documentation:

• The documentation included with CS: at the same place as where you can download the CS sources you should also be able to download the file 'docs???.tgz' or 'docs???.zip'. This archive contains a lot of documents (about the console, the configuration file, sound, MazeD, internal workings of CS, the history of CS, the format of world files, and so on...)
• Automatically generated documentation: there is also the archive 'csdoc???.tgz' which contains automatically generated HTML documentation. This documentation is generated from the source and is ideal for getting an idea of the class structure used in Crystal Space.
• Various other documents: on the (Home Page) there are some other documents related to 3D and Crystal Space including the very important CS API document (which is unfinished). This document intends to be the main document that is going to be used by game developers.

I don't have lots of memory. Can I still run Crystal Space?
A1. Well, that depends. There are several things that you can do to decrease memory usage. First of all, version 0.06 of Crystal Space is already a lot more efficient than previous versions so things may already work.
A2. If this is still not enough you can decrease the size of the texture cache with the -cache commandline option or the CACHE config file option (in 'cryst.cfg'). By default this is set to 5000000 which means 5 megabytes of memory. You can safely decrease this to 1200000 (but don't go any lower or you may get crashes!) thus saving a whopping 3600000 bytes!
A3. Using a low resolution also decreases the memory usage. Crystal Space uses a Z-buffer containing long (4-byte) values with the same size as the display. So a display of 640x480 uses a Z-buffer of 1228800 bytes!
A4. If you are still low on memory there is only one thing you can do: decrease the complexity of the world. For every polygon in the world there is a lot of memory used (the lightmaps for example). If you just want to try the engine you can run Crystal Space with some of the simpler worlds (like 'perf.zip', 'rgb.zip', or 'simple.zip'). 'perf.zip' is a good choice because it is not too complex and it contains most of the features Crystal Space has (since it is designed for performance testing).

Crystal Space is really slow on my computer. Can't something be done about this?
A1. Crystal Space is a 6DOF engine. It needs to do semi-perspective correct texture mapping to get a nice display and this is slow. Compare Crystal Space to Quake and you will see that Crystal Space is not terribly slow (it is slower but only by a few frames per second on my Pentium 90). You can expect that Crystal Space will probably need the same kind of computer as Quake: at least a Pentium or a very fast 486 with a floating point coprocessor. On my old computer (a Pentium 90 with 16M memory) and a screen size of 640x480 I got about 6-9 FPS with no assembler and 8-12 FPS with assembler.
A2. Of course I'm always glad to accept any code that would speed up Crystal Space. Please try.
A3. Many things are being done currently to try to speed up Crystal Space. Hardware acceleration is one important area but there are others.

I want to create textures for Crystal Space. What palette should I use? How big should I create the textures? What format can I use?
A1. The palette does not really matter because Crystal Space tries to calculate the most optimal palette given a set of input textures. But there are some things to keep in mind. Try to get the number of different colors as low as possible without sacrificing for quality and if you design a set of textures that are meant to be used together it is always best to let them use a similar palette. This will make it easier for Crystal Space to calculate a good palette. If you run Crystal Space in truecolor mode (15/16/32-bit mode) and with private colormaps then there is actually no need anymore for using similar palettes.
A2. The width and height of a texture must be a power of 2 (8, 16, 32, 64, ...). That's about the only restriction. Textures need not be square (but it is probably easier to keep them square). You can have textures with sizes like 16x256.
A3. Crystal Space currently uses GIF by default but it can also read TGA, PNG, BMP, and JPG (if enabled in the makefile).
A4. Unless a texture is not meant for tiling you should make sure that it can be tiled. This means that if you put a number of textures next to each other of above each other the boundaries of the 'tiles' should seemlessly integrate with each other. Of course, it is perfectly possible to create textures that are specifically drawn for untiled usage. An example would be a texture representing a computer keyboard. This texture will probably not be tiled (it would be a little strange).
A5. I have some imaging tools (like XV and ImageMagick) so I can do a lot with any textures I get. If you can't output to GIF, no problem, I can read almost any image format. If the size is not a power of two I will scale them. If the image uses too many colors I can reduce the number of colors...

I'd like to contribute to Crystal Space. What can I do?
A. Have a look at the Todo file. I try to keep a fairly comprehensive list of missing features and bugs there. You should contact me so that I can coordinate the efforts and avoid duplicate work.

How does Crystal Space work?
A1. This is a short question with a long answer. Two documents to get you started are 'document.txt' and 'cam_matr.txt' (both included with Crystal Space). 'document.txt' contains a description of how Crystal Space uses the portal system and how lighting works. 'cam_matr.txt' is a document explaining how the camera system is used in Crystal Space. 'document.txt' assumes that you have some knowledge about matrices, and 3D mathematics in general. 'cam_matr.txt' gives more information about matrices and transformations so you can read that file first. 'walkthru.txt' is also a good source of internal information.
A2. Also see the documentation question for more information about available documents.
A3. If you still need more information (after all, not everything is explained in those two documents) just mail me and I will answer you as soon as I can.

I want to write a game/MUD/RPG/... with Crystal Space? Can I do this? Will you help me? ...
A1. The ultimate purpose of Crystal Space is that it will become a useable and powerful engine for writing games and other similar programs. The current version of Crystal Space (0.14) is slowly starting to get ready for this. You can contribute to Crystal Space to make CS even better! I'm willing to help anyone trying to use Crystal Space is another project. However, because of time constraints I will only do development and management of the general Crystal Space engine. Specific features and game development will have to be done by someone else (maybe this changes in future if I will ever acquire more of that precious resource: TIME, but I doubt it). Of course, any enhancements to Crystal Space will undoubtedly benefit all developers using Crystal Space so this should not really be a problem.
A2. Since Crystal Space is now using the LGPL licensing policy you can make commercial or shareware products using it. See the file COPYING which you can find in the source archive for more details about what you can and cannot do.