iDevGames

Introduction

The recent release of version 18.001 of Crystal Space, the Open Source 3D game toolkit, may be of interest to Macintosh developers. This is the first release which natively supports Apple’s new Cocoa technology introduced in Mac OS X. As the creator and maintainer of the Mac OS X, Mac OS X Server 1.0 (Rhapsody), OpenStep, NextStep, and BeOS ports of Crystal Space, I hope to provide readers with the inside scoop on the status of Crystal Space as it relates to the Macintosh platform.

If you have any questions, comments, criticisms, or would simply like to discuss Crystal Space and/or Mac OS X, please feel free to contact me.

Clarifications

There are two completely distinct ports of Crystal Space for Macintosh.

Classic (Macintosh Toolbox)

The first port is based on the Classic Macintosh Toolbox. This port has not been Carbonized, which means that it may work with Macintosh OS 9 but is incompatible with Mac OS X. Another problem with this port is that it has seen almost no maintenance in the last year (or more) and is consequently incomplete and unstable. Unfortunately, the maintainers of this port have had very little time, recently, to devote to Crystal Space. As a consequence, it is common for several months to elapse between updates to this port. A final issue is that this port does not necessarily keep up with CodeWarrior revisions, and there have been reports of problems compiling Crystal Space with newer versions of CodeWarrior. (However, see “ate Breaking News” below.)

Cocoa

The second port is based on Apple’s brand new Cocoa technology which was inherited from NeXT and which is new in Mac OS X. This is a pure-Cocoa port. Therefore it is suitable for Mac OS X, but not for earlier Macintosh releases. This port is, in fact, the same port which runs on Mac OS X Server 1.0 (Rhapsody), OpenStep, and NextStep. I am extremely active with Crystal Space and, as a consequence, this port tends to be very well maintained.

Documentation

The Cocoa-based port of Crystal Space is fairly well documented. People interested in building and using Crystal Space on Macintosh are encouraged to read section 2.4.4 of the Crystal Space User’s Manual. People interested in actually improving or augmented the Cocoa-based port (or even people interested in the nitty-gritty details) are encouraged to read section 8.1.1 which contains an in-depth technical discussion of the Cocoa-based port.

The online documentation can be accessed on-line at:

http://www.crystalspace3d.org/tikiwiki/tiki-index.php?page=Documentation

Finally, if you have downloaded the Crystal Space 18.001 package, or if you have retrieved Crystal Space from the CVS repository, you will find these documents in the CS/docs/html and CS/docs/pubapi directories, respectively.

Caveats

Although I performed all the tasks involved in porting Crystal Space to Mac OS X, I do not actually own Macintosh hardware or have access to Mac OS X (though donations would be gladly accepted). Thus, the Mac OS X port was actually performed blindly. Just prior the 18.001 release (in fact only minutes before), we had the good fortune of having a member of the mailing-list test the Mac OS X port. This gentleman reported the good news that he succeeded at building Crystal Space’s plug-in modules and running the WalkTest demonstration program. This is particularly encouraging news given the totally blind porting effort. It also reflects well on the Cocoa technology since the same code works for Mac OS X Server 1.0 (Rhapsody), OpenStep, and NextStep.

However, beyond what was reported by the tester’s initial attempts at building and running the project, there is not yet much concrete information to report about the Cocoa-based Crystal Space port. I await further feedback from Crystal Space users and the Macintosh community. Another issue of potential concern for Macintosh users is video performance. Earlier Cocoa-based environments from NeXT did not support video hardware acceleration, so there was never any need (or indeed opportunity) to write drivers which take advantage of hardware acceleration. Consequently, only a high-level AppKit-based driver is available. This driver supports only software rendering. Although I have employed several techniques for squeezing performance out of this driver, because of its high-level nature as well as certain AppKit restrictions, it will no doubt be slower than a driver which employs a lower-level API for more direct access to the video hardware.

In the future, I would like to see the introduction of drivers based on CoreGraphics and OpenGL. Given my current lack of Macintosh hardware, there is little likelihood that I will write these drivers any time soon, but I would be happy to give guidance to any one who wants to volunteer for the task. Because of the highly encapsulated nature of drivers in Crystal Space, writing a video driver may very well prove manageable even for someone with limited exposure to the Crystal Space environment.

One final caveat deals with the build environment. Crystal Space is in a beta state and changes fairly often. Historical experience has shown that maintaining up-to-date project files can be a difficult task. As a consequence, the build procedure for Crystal Space is command-line-based and involves invoking a few commands from within the Terminal application. Although, building the project from the command-line is quite simple and straightforward, it is understandable that Macintosh developers who are used to working within an integrated development environments (IDE) may find this build procedure rather crude. In the future, I may set up a facility for automatically generating up-to-date Project Builder project files on-the-fly, much in the same way that I recently created a facility for automatically generating Visual-C++ project files.

A side effect of building Crystal Space from the command-line, using the standard makefile system employed by most other ports of Crystal Space, is that the compiled executables are not placed into application wrappers .app. One consequence of this is that it may not be possible to launch Crystal Space programs via double-click from the Finder¹.

If this is indeed the case, then programs will have to be launched manually from the command-line. The documentation which I wrote for the Crystal Space User’s Manual explains all about this limitation. To resolve this issue, in addition to the possibility of creating Project Builder project files, my plans include re-engineering Crystal Space’s makefile system to allow it to generate properly wrapped .app applications.

Future Directions

The Cocoa-based port is considered the most important Macintosh port since it is up-to-date and well maintained.

We have considered dropping the pre-Carbon port of Crystal Space on account of its incomplete and out-of-date nature. However, our decision to not (yet) drop that port is based on the understanding that it will probably take Macintosh users a year or two to transition from Mac OS 9 to Mac OS X.

It would be nice for the classic Macintosh port of Crystal Space to be Carbonized since that would allow it to run on both Mac OS X and Mac OS 9. Whether or not this will actually occur, depends on whether or not we can find developers willing to make the effort to perform the conversion and then support it afterward. (However, see the “Late Breaking News” section below.)

In the long-run, because the Cocoa-based port is built upon Apple’s newest technology, we foresee that this will be the port of choice for the future, and that the old classic Macintosh Toolbox port will ultimately be phased out.

Late Breaking News

One of the pre-Carbon Mac OS 9 port maintainers, K. Robert Bate”, has just returned from a prolonged absence and has once again started updating on the Mac OS 9 port of Crystal Space. His most recent work involves updating the CodeWarrior project files (which were extremely outdated) and ensuring that the project can be built with the most recent version of CodeWarrior. Mr. Bate has also stated his intention of Carbonizing the Mac OS 9 port, however it is unknown as to when this task will be completed.

The patched CodeWarrior project files will be made available as part of the 18.002 release of Crystal Space (for which I do not currently have a concrete release date). Patched project files can also be retrieved from the CVS repository by checking out the R0_18 branch of Crystal Space. For instance, you might invoke the following instruction from the command-line to retrieve the R0_18 branch:bq.

cvs -z9 -d

:pserver:anonymous@cvs.crystal.sourceforge.net:/cvsroot/crystal

checkout -P -rR0_18 CS

If you are a CVS user, then you may also be interested in Crystal Space version 19.dev which is under development in the main CVS trunk. Be aware, however, that this version has already diverged significantly from stable version 18, and there are no guarantees that it will even build or run on Mac OS X at this time. For the moment, we recommend that people stick with the 18 release unless they are feeling particularly adventurous.

¹ Without access to Mac OS X, I am unable to personally verify this.

introduction,mac,crystal,space,engine