Setting up the Torque SDK on Linux

Preparing Your System

You don't have to do much to get your system ready to work with Torque. On Linux, simply ensure you meet the system requirements listed below:

Linux and OpenBSD

Required Hardware:

  • Pentium I, II, III, IV, AMD Athlon, etc.

  • 64MB RAM or more, highly dependent on your application

  • A relatively recent NVIDIA 3D card. Other cards may work but are untested.



Required Software:

  • XFree86 4.0 or greater with a appropriate 3D drivers (GLX/DRI) for your video card.

  • SDL SDK version 1.2 or later. (1.2.3 or later is recommended)

  • OpenAL Runtime or SDK Installation. (See the compiler setup document for more information on installing OpenAL)

  • Mesa3D version 3.4 or later. (3.4.2 or later recommended)



Development Tools:

  • GNU make and g++ (version 2 or 3).

  • NASM Assembler version 0.98 or later.



Summary

There you have it, nothing too heavy-duty. Please note, however, though the engine itself has fairly minimal requirements as far as hardware, the performance of any particular game built using the TGE will depend greatly on how each game makes use of the resources available to it. TGE games can vary from very low-demand applications such as small 2D game "toys" to high end (and high framerate) 3D Role Playing Games, First Person Shooters, Racers, Flight Simulators, and whatever you can dream up! Torque is a high-performance engine, it is up to you how far your own code and content will stress a user's systems.

Now that you've downloaded the SDK source-code, and your system is ready to work, read on to learn how to compile the SDK source-code on Linux.

Compiling the Torque Game Engine SDK on Linux and OpenBSD

John QuigleyLinuxOpenBSDBuildBuildingCompileCompilingMakeKDevelopXEmacs

This document describes the steps necessary to get the Torque SDK and Demo application working on a unix system. If you have problems, please read the Known Issues section, below, before posting on the forums.

Installation and Build

Step 1: System Setup

Before beginning, you should insure that all of the hardware/software prerequisites described in the Torque on Linux system requirements section are properly set up. Note that dedicated server build only requires NASM and a functional compiler.

Many unix distributions either install the third party libraries by default or include them on the installation CD. If you are using Mandrake, you may wish to use the Software Manager to install the packages (MandrakeMenu->Configuration->Packaging->Software Manager). You will also need the development files for the packages, these are often in a package named "devel", for example XFree86-devel.

A static version of Mesa's GLU library is required. If your system does not have a libGLU.a file, you will need to install Mesa from source to get it.

OpenAL and SDL

For SDL, its recommended that you install from source if the version that comes with your distribution is older than 1.2.4. For OpenAL, you can use the distribution hosted here on GarageGames. Torque is sensitive to the version of OpenAL installed on your system. The wrong version may produce no sound or cause Torque to crash. You can test sound by mousing over one of the buttons in the shell.

The usual procedure for compiling OpenAL and SDL is:

cd source_directory
./configure (if you get a "not found" error, do "sh ./autogen.sh" first)
make
su
make install
ldconfig


If you are installing SDL or OpenAL from source, note that by default they install themselves in /usr/local/lib, a directory that is not searched in some unix distributions (e.g: RedHat). If this is the case on your system, the library will fail to load when the Demo App starts. You'll need to either change the install prefix (./configure --prefix=/usr), or add /usr/local/lib to /etc/ld.so.conf (and run ldconfig as root after making the change).

Step 2: Compiler Setup and Building

It is recommended that you use GCC3 to build the source. To configure the build, do the following:

cd ~/projects/torque
make -f mk/configure.mk OS=LINUX COMPILER=GCC3 BUILD=DEBUG


This command configures Torque for a Linux GCC3 Debug build. To see a list of other valid configurations, omit the OS, COMPILER, and BUILD options from the command. "Make" will tell you if the configuration is valid after you run the command. If it is, run the following command to build the demo application:

cd ~/projects/torque
make


If all goes well, the torqueDemo_DEBUG.exe will be built and dropped into the "example" directory. You can optionally build the dedicated server and tools as described below, however these are not required.

If all does not go well, re-check your configuration and also consult the Known Issues section, below.

Dedicated Server Build

You may want to do a dedicated server only build. This build does not include any of the client code and therefore has fewer dependencies. The dedicated server is not required, however, since the client can also be run with the -dedicated command. To build the dedicated server:

make clean
make dedicated


The "make clean" step is important. You must also "make clean" if you want to rebuild the client after building the dedicated server.

The name of the dedicated server executable is torqueDemod.

Tools

To build the tools, cd into the "tools" directory and do "make". buildWad, map2dif and texture2bm8 will be built. At the time of this writing, the tools have not been tested, so report problems to jmquigs@bigfoot.com .

Step 4: Run the Demo Application

To run the Demo Application, cd into the example directory and issue this command to start it:

cd ~/projects/torque/example
./torqueDemo_DEBUG.exe


The demo application client should start.

Known Issues

General

  • The compilation currently generates a number of warnings. The majority of these are benign float/int conversions. These warnings are "normal" and will eventually be removed.

  • The demo application must be started in the example directory. (If for some reason you need to start it elsewhere, use the -chdir parameter so that the application can cd to the example dir).

  • Torque has problems linking with GLU on some S.U.S.E. distributions. Reinstalling mesa may help.

  • On Unix, Torque stores created files (e.g.: .dso) in "~/.garagegames/exename". This directory is also searched first for files that need to be read. This behavior can be disabled by removing the -DUSE_FILE_REDIRECT parameter in conf.UNIX.mk. It can also be disabled at runtime with the "-nohomedir" command line parameter.



Dedicated Server

  • The client can be run as a dedicated server, or you can use the dedicated server only build (see above).

  • You can start the dedicated server with no mission loaded with this command:

    cd [example directory]
    ./torqueDemod_DEBUG.exe -dedicated


  • Or you can specify a mission on the command line with the -mission flag, for example:

    cd [example directory]
    ./torqueDemod_DEBUG.exe -dedicated -mission fps/data/missions/waterWorld.mis


  • You can exit the dedicated server by typing quit();



Client

  • The -console option can be useful for troubleshooting startup problems.

  • There is distortion with some sound effects. This is being investigated.

  • There is a performance problem when zooming. This is being investigated.

  • Some systems have problems with CD audio initialization (crash or hang during startup). If your system is affected use the -nocdaudio command line parameter.

  • Clipboard notes: the client does not support copy/paste with the X primary selection buffer (i.e.: highlight plus middle mouse button). You must use explicit cut/copy/paste commands in each application. For Torque these are CTRL-C (Copy), CTRL-V (Paste), and CTRL-X (Cut). Also note that due to a bug in QT, pasting is not supported from KDE/QT apps (this is fixed in QT3)

  • If you have an AMD system with an AGP graphics card, you may experience lockups in 3D applications. The following fix is from the Gentoo linux site:

    If you have been experiencing lockups on your Athlon, Duron or Athlon MP system when using AGP video, try passing the mem=nopentium option to your kernel (using GRUB or LILO) at boot-time. This tells Linux to go back to using 4K pages, avoiding this CPU bug.




BSD

  • The BSD port is not currently maintained. It may be maintained in the future. If you have interest in the BSD port, send an email to jmquigs@bigfoot.com .



Getting Help

If you have problems building or working with Torque, the first thing you should do is go over your configuration and re-check the documentation. If you can't fix the problem, you can try asking for help in the Garage Games IRC Room , or on the Forums. For forum posts, please post your message to the private SDK "Getting Started" forum. Include the word "linux" somewhere in the subject line to make your message easily locatable with a search.

Development Environments for Torque

This section covers some of the development environments that can be used to work with Torque. Though a complete tutorial for these tools is beyond the scope of this document, this section offers a few tips for setting up and using these tools.

KDevelop

KDevelop 3 works pretty much straight out of the box with Torque.

  • Install Kdevelop if you do not already have it installed. On mandrake systems, this can be done through the software manager. NOTE: If you are using gnome and do not have KDE installed at all, you will not be able to use the embedded console in KDevelop. While not necessary, this console is useful.

  • Next, run Kdevelop setup if you have not already, and make intelligent choices... most options can be accepted with default values.

  • After Kdevelop starts up, go to Options->KDevelop Setup. You may want to change the path to the default project directory.

  • Now, go to Project->Generate Project File. Navigate to the torque dir and press ok. You may receive a message saying "No Makefile.am found, are you sure you want to do this?" If so, choose yes. Next, you'll see some activity in the messages window. When finished, your project may not be opened; in this case, go to Project->Open and navigate to the directory you generated the project file in. Choose the newly generated file - *.kdevprj; it will probably take a few minutes to load due to the number of files in the project.

  • Go to Project->Options. On the General tab, uncheck "Modify Makefiles". Next, go to the "Make Options" tab and check "Run make in" and make sure it is set to ./ Then go to the "Binary" tab and set the path and filename to example/torqueDemo_DEBUG.exe Click ok. You may receive a message stating that new makefiles will be generated. These would clutter up your torque directory, but don't worry because the make will fail. Next, the dir will be refreshed. This may take a few minutes.



You might want to do a Save-all just in case something goes wrong for some unforeseen reason.

Now it is time to compile your project. Simply go to Build->Make. Pay attention to the Messages window to see if you get any errors. To execute the demo after it has successfully compiled you will need to do Build->Execute with Arguments and put -chdir example in the popup. To debug the demo you need to do Debug->Start (other)...->Debug with Arguments and enter -chdir example in the popup. NOTE: Before debugging, you must set breakpoints and you cannot set them during debugging like in VC++. If the project compiles, but hangs and nothing pops up, see in the Known Issues section above for information on the -console option.

XEmacs

While not the most "visual" environment around, XEmacs is a fairly capable Torque editing environment. Here are some tips for using XEmacs with Torque.

  • The "grep-find" command (M-x grep-find) is useful for searching through files for a regular expression. By default it will search all directories in the current buffer's directory. Do M-x pwd to figure out what directory you are in. Do M-x man, "grep" for more information about grep.

  • The emacs "compile" and "recompile" commands (M-x compile and M-x recompile) can be used to build torque from the ide. The difference between the two is that compile will ask you for a command line to run and recompile just runs the last compile command.

  • You can do a visual diff between two files with the M-x ediff-files command. The M-x ediff-directories command is similar, except that you can diff a set of files in a directory in succession. ediff-directories can also generate "patch"-compatible patch files.

  • You can debug from within xemacs, or you can debug using one of the tools described below.



Debugging Tools

  • The "gdb" command can be used to analyze core dumps to get a backtrace. Run "gdb -c core torqueDemo_DEBUG.exe", then type "where". Some systems do not dump core by default; you can enable core dumps with the command "ulimit -c 500000000"

  • You can use gdb for interactive debugging, although its interface is tough for new users. Some decent visual debuggers include "ddd" and "gvd", both of these work with Torque.

  • If torque hangs for some reason, you can send it a SIGSEGV. This will cause it to crash, and from there you can use the gdb command above to analyze the core dump. Do to this, use the "ps" command to get the pid of torque (ps -aux | grep "torque"), then kill torque by sending SIGSEGV to the lowest pid reported by ps (e.g.: kill -11 8686).



Installing with the windows SDK

NOTE: The number one problem people have when installing from a windows directory is that the case of lib/openal/LINUX gets lowercased. If you get openal compiler errors, make sure this directory is "LINUX" and not "linux".

You can install the SDK code from the windows SDK. However, this method of installation requires that you have a Windows installation available, whose files are accessible to your unix partition.

Boot into Windows and install the SDK on to a filesystem that is accessible to your unix installation. Reboot into unix and copy the files from the windows filesystem to your unix file system.

The C++ header and script source files distributed with the Windows SDK need to be converted from Windows/DOS CR/LF line endings into using only LF. The shell script unixchange.sh located in the torque/tools/unix directory is provided for this purpose. The script should be executed once from the torque/tools/unix directory before running the makefile.

unixchange.sh may also need to be converted before it is run. You can use the "dos2unix" utility to convert the file before running it. This utility is part of the unix2dos package and comes with RedHat Linux and probably many other distributions, though it may not be installed by default.

Mandrake NVIDIA Driver Setup

This section will help you get new drivers installed for your video card since torque is a 3d game and will need them. Currently there are only Nvidia Drivers installation instructions. NOTE: You need to have XFree86 4.0 or higher installed.

nVidia Drivers

The Nvidia website has instructions for installing their drivers and they are very helpful, but in case of difficulty with a Mandrake install, the required steps are listed below. The NVidia Linux drivers website is located here . You will need to download NVIDIA_GLX-1.0-2313.i386.rpm and NVIDIA_kernel-1.0-2313.mdk81up.i686.rpm . If you are unsure what you need, Nvidia has a program that can tell you. It can be accessed here .

To set-up:

  • First you need to disable Xwindows login on boot, if it is enabled. If your install does not boot straight into Xwindows then you can skip this step. Switch to root by typing su and then as root edit your /etc/inittab file. You should see a line that looks like this id:5:initdefault: change the 5 to a 3 and then save the file.

  • Now that we no longer start into xwindows its time to exit out of Xwindows to a normal prompt. (you may have to restart or I guess you could press ctrl-alt-backspace to kill Xwindows)

  • Change to the dir that you downloaded the drivers to. If you are not su (i.e. root) then make it so now. Type -ivh NVIDIA_kernel-1.0-2313.mdk81up.i686.rpm and check to make sure this is the same filename as the one you downloaded. If not, use your filename. The install process should begin and will finally say "Nvidia Drivers installed successfully" (or give a similar success message). Next, issue the command rpm -ivh NVIDIA_GLX-1.0-2313.i386.rpm . This command might generate some warnings, but don't worry about them.

  • Next, edit /etc/X11/XF86Config-4. Scroll down until you see Load "dbe" and add on the next line Load "glx" then continue on down the file till you get to Section "Device" where it is talking about your graphics card...mine has Identifier "NVIDIA GeForce2 DDR (generic)" but that will depend on which graphics card you have. (mine is a Geforce 2 MX) you should see in that section Driver "nv" you need to change the "nv" to "nvidia". Now save and exit the file.

  • Now restart Xwindows with startx you should see a short nvidia splash screen now when X starts up. If you have any problems or you are not using mandrake 8.1 then consult the Nvidia documentation for further help.



Credits

This document was written by John Quigley.

The Mandrake Software manager information, KDevelop guide, NVIDIA driver guide, and OpenAL compilation commands were contributed by Tim Newell.

Building a Linux Release Package

John QuigleyLinuxOpenBSDBuildBuildingCompileCompilingMakeRelease

This document describes the steps for building a Linux binary Release package for your game. It is a bit of a balancing act to create a binary package that will run on many hardware/software configurations and also not conflict with various open source licenses (especially GNU). With this document, you should be able to accomplish the task successfully.

Installation and Build

This section contains the step-by-step instructions for building the binary package. The executable built by this process has the following requirements:

  • Pentium-compatible with MMX

  • GNU Libc 2.2 (+)



Configuring Third Party Libraries

The SDL and OpenAL libraries should be specially configured for a distributable binary package. The goals here are to create optimized libraries for best performance and compatibility and to eliminate dependencies on other libraries that Torque doesn't need. You will need the SDL and OpenAL source distributions to perform this step.

First build the OpenAL library. Do the following in the openal source directory:

cd path/to/openal/linux
sh autogen.sh
./configure --target=i586-pc-linux-gnu --enable-optimization
make


After building the library, do a check to make sure no extraneous content was linked in. Run the "ldd" command on the library to check this:

ldd linux/src/libopenal.so.0.0.6


The output should look similar to the following. If there are extra libs you should investigate why they are being linked in. If they don't exist on the end user's system, the openal library will fail to load.

libm.so.6 => /lib/i686/libm.so.6 (0x400ab000)
libdl.so.2 => /lib/libdl.so.2 (0x400ce000)
libpthread.so.0 => /lib/i686/libpthread.so.0 (0x400d1000)
libc.so.6 => /lib/i686/libc.so.6 (0x42000000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)


Next, build and install the optimized SDL library:

cd path/to/SDL-1.2.4
./configure --target=i586-pc-linux-gnu --enable-debug=no --enable-audio=no
make


Next do a check for extraneous libs:

ldd src/.libs/libSDL.so
libm.so.6 => /lib/i686/libm.so.6 (0x40080000)
libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x400a3000)
libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x40178000)
libdl.so.2 => /lib/libdl.so.2 (0x40185000)
libc.so.6 => /lib/i686/libc.so.6 (0x42000000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x80000000)


If there are other libraries that you did not explicitly include, check your configuration. If everything is OK, then install the library:

make install (as root)


Build the Executable

Next you need to build a Release version of your Torque game. Before you begin, consider changing the -DUSE_FILE_REDIRECT parameter in the makefile. To build the executable, do this:

make -f mk/configure.mk OS=LINUX COMPILER=GCC3 BUILD=RELEASE
make clean
make


After you've built the executable, do a final check to make sure that you don't have wacky libs getting included:

ldd torqueDemo.exe
libSDL-1.2.so.0 => /usr/local/lib/libSDL-1.2.so.0 (0x4002b000)
libpthread.so.0 => /lib/i686/libpthread.so.0 (0x40095000)
libdl.so.2 => /lib/libdl.so.2 (0x400a9000)
libstdc++-libc6.2-2.so.3 => /usr/lib/libstdc++-libc6.2-2.so.3 (0x400ac000)
libm.so.6 => /lib/i686/libm.so.6 (0x400ef000)
libc.so.6 => /lib/i686/libc.so.6 (0x42000000)
libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x40111000)
libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x401e7000)
/lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)


As before, you probably don't want any libs other than the above. Next, re-name the executable using something like:

mv torqueDemo.exe mygame.dynamic


You should also check the example directory to make sure that it doesn't contain any debug builds, core dumps, or other extraneous files.

Make the tplib Directory

By now you've guessed that your game executable will be dynamically linked. The glibc 3 libraries (pthread, dl, m, c, ld-linux) and the OpenGL library (libGL.so) will be required on the end user's system. The other libraries will be distributed with the binary package. This maximizes the chance that the end user will be able to run the game "out of the box".

The bundled libraries will be installed in a directory called "tplib" (for Third Party Libraries) under the game root folder, for example: "example/tplib". The SDK includes a tool that will populate the tplib directory. This tool is called mktplib.sh .

Legalese alert! Before you run mktplib, you should update "tools/unix/tplib_template/ReadMe.ThirdParty.html". This file is supposed to contain the version numbers of the LGPL/GPL components that are in use. These values are set to XXXXX by default in the template file, and you should update them before you run mktplib.sh.

Run mktplib.sh like this:

cd path/to/torque/tools/unix
./mktplib.sh path/to/openal path/to/game_executable


For example:

./mktplib.sh ~/dist/libs/openal/openal-cvs/snapshot-unpack/openal ~/projects/torque/current/torque/example/mygame.dynamic


After running this you should have a populated "tplib" subdirectory of the game root folder. Note that it includes the GPL and LGPL and the ReadMe.ThirdParty.html file (required for GNU license compliance).

Make the Program Launcher

If the end user tries to run "mygame.dynamic" directly, chances are that it won't work because the "tplib" directory is not in the library path by default. We fix this problem by using a shell script to start the game; the script sets the library path and runs the game executable, passing it any command line arguments. The script is simple:

#!/bin/sh
export LD_LIBRARY_PATH="tplib:$LD_LIBRARY_PATH"
./mygame.dynamic $@


Put this into a file called "mygame" (or whatever your game title is) in the game root directory, and make the file executable with chmod +x mygame . Users will start the game using this file.

Build the tar File

Now its time to build the tar file, or "tarball" as it is sometimes called. First, a cosmetic item. If the game root is still called "example", you may want to make a symlink to it so that the tarball doesn't contain that name:

ln -s example MyGame


The first argument will be used to name the tar file. The second indicates the subdirectory that is the game root directory. A third optional argument is a "release tag", which is just a string that will be inserted into the filename. Running this command will produce a tarball that looks like this:

mygame-06-16-2002.tar.bz2


Note that the filename includes the game name and the date the tar was built. Isn't that nice. Note also that bzip2 compression is used to reduce file size. One way that users can unpack this file is with:

tar -xvjf mygame-06-16-2002.tar.bz2


Test the Package

The most important step. The binary package won't do much good if it's broken, right?! A basic sniff test is to unpack the package on the system on which it was built. Make sure it starts correctly, sound works, etc... When you're confident that it isn't obviously broken, its worth trying the package out on a few different linux systems, especially different distros or different versions of the same distro. Gentoo/Debian and other non-canned distributions are great test cases.

Notes
File Redirection

By default, the unix build will redirect file writes to a directory in the user's home directory called ~/.garagegames/exename. This allows the game to be installed in a directory that the user doesn't have write access to (for example /usr/local/games). The downside is that this makes modding the game more complicated (user's have to know to look for scripts in the home directory, and files created by the editor will be stored there).

You can disable -DUSE_FILE_REDIRECT in conf.UNIX.mk. This way, files will be created in the game root directory, just like the windows/mac versions. It's your call whether to build the executable with this enabled or not.

Static Linking

You may be thinking: "This process is complex. Why not just build a fully statically linked binary?" There are a few reasons:

  • Every fully statically linked binary we've tested crashed when loading NVIDIA's libGL.so. There is apparently a way to do it (see Loki's tribes2 binary), but the procedure is obscure.

  • A statically linked binary violates the LGPL, because of SDL and all the glibc libraries. This is true even if you also include a dynamically linked binary: although you are preserving the spirit of the LGPL by including the dynamic binary, the static one is technically a problem.



Still, if someone comes up with the procedure for making a fully statically linked binary that doesn't crash, we'd be glad to hear it. Send email to jmquigs@bigfoot.com .

Okey dokey, all done, now have fun! Now that you've built the demo, read the Torque Demo Application section to learn how to use it!