Haptic hardware support in a 3D game engine

Project Report Screenshots Links Install notes Project members


The aim of this master thesis is to find out if it is possible to integrate haptic hardware support in the open source 3D game engine Crystal Space. Integrating haptic support would make it possible to get a haptic representation of 3D geometry in Crystal Space and therefore take advantage of all the benefits a 3D game engine provides, when building haptic applications. An implementation of the support should be as low-cost as possible by taking advantage of available open source haptic API alternatives. The project is a collaboration between Certec and the Department of Computer Science at Lund Institute of Technology.


The thesis report presents an evaluation of available haptic APIs and comes up with a design and an implementation. The solution has been implemented as a Crystal Space plugin by using modified parts of the e-Touch open module API. The plugin makes it possible to utilize the Phantom haptic device to touch and feel the 3D environments in a Crystal Space application. Two demo applications have also been constructed to show the capabilities of the plugin.

Master thesis report and other papers 

The master thesis report describes the goals in this project. It contains a brief description of haptics and game engines. One part deals with how the plugin was made. There is also a short explanation on how the plugins were designed and how they can be used. Finally some conclusions are drawn about the complete project. The master thesis report can be downloaded here.


Here is a short swedish summary that is easier to understand.

Here is a powepoint presentation that was used when the project was presented at Certec. It is in swedish.




These screenshots were taken from the two demo applications that were developed. The two top screenshots show Demo1, where you can navigate in a 3D environment similar to a FPS (first person shooter) and touch and feel the surroundings with the Phantom device. The bottom two pictures show Demo2, where the object is to roll a ball through a labyrinth using the Phantom device. The player must keep the ball above the surface and there are certain dynamic objects that can help him on the way to reach the finish. The dynamics engine in Crystal Space has been utilized for this demo. 


Install notes

(This guide will only describe how to do if you are using Visual Studio 6.0, but it shold be similar on other development platforms.)


The plugin

The haptic plugin has been tested successfully with the newest Crystal Space version 0.96_004. This guide assumes that this version has been downloaded and compiled correctly. If not check out the Crystal Space homepage for information on how to do this. Do not forget to set the CRYSTAL environment variable before reading further.


The guide also assumes that GHOST SDK 3.1 has been installed and the GHOST_BASE environment variable has been set. Otherwise check out your GHOST manual on how to do this. Of course the phantom drivers should also have been installed.


The third API that needs to be installed is the e-Touch API. The e-Touch API can be found here. There are also a programmer's manual that describes how to compile the API and get it to work with the Phantom device. Remember to have set the enviroment variable ETOUCH_BASE to the main e-Touch directory.   


Now to install the plugin you first need to download the phantom.zip file. This is an archive with the files needed to compile the haptic plugin. Extract this archive to the main Crystal Space directory. Open up the csall workspace and choose to insert a project into this workspace. The mk/visualc directory of Crystal Space should now contain a project file called plgphantom. Insert this project into the workspace and rebuild the libcsgeom project. A function as been added to the csBox3 class in this project so it needs to be rebuilt. Add these dependencies to the project:

  • libcsengine 

  • libcsgeom

  • libcsgfx

  • libcssys

  • libcstool 

  • libcsutil 

Now build the plgphantom project. There will be some warnings but do not care about them.

When the project has been built the phantom.dll file should be registered in the SCF (Shared class facility). 

This can be done by running scfreg that should be in the main Crystal Space directory:


scfreg phantom.dll


This will add a line in the scf.cfg file. Now the plugin should work properly.



The demos

To install the demos to test the plugin you need to download the demos.zip file. Extract this file to the main Crystal Space directory. This will overwrite the standard.zip file in Crystal Space but it will just add new textures and sprites to it so if you have not added anything to this file it really does not matter. In the same way as for the plugin, add the appdemo1 and appdemo2 project to the csall workspace. Do not forget to also add the same dependencies.

To get the levels that comes with the demos to work you need to edit the vfs.cfg file in Crystal Space.


Add these lines in vfs.cfg:


VFS.Mount.lev/labyrinth1 = $@data$/labyrinth1$/ 

VFS.Mount.lev/labyrinth2 = $@data$/labyrinth2$/ 

VFS.Mount.lev/labyrinth3 = $@data$/labyrinth3$/ 

VFS.Mount.lev/labyrinth4 = $@data$/labyrinth4$/ 

VFS.Mount.lev/labyrinth5 = $@data$/labyrinth5$/ 

VFS.Mount.lev/labyrinth6 = $@data$/labyrinth6$/ 

VFS.Mount.lev/labyrinth7 = $@data$/labyrinth7$/ 

VFS.Mount.lev/bighouse = $@data$/bighouse$/ 

VFS.Mount.lev/level1 = $@data$/level1$/ 


Compile the demos and if everything has been installed and compiled correctly you should be able to run them by executing:


demo1 level1 -video=opengl -relight

demo2 -video=opengl -relight


The levels that come with the demos might be a bit dark so you may want to add some more ambient light by editing the engine.cfg file in Crystal Space.

Project members

Daniel Nilsson d96dn@efd.lth.se, Henrik Aamisepp d98ha@efd.lth.se