Torque Game Engine DocumentationVersion 1.3.x
| Torque Game Engine Documentation Version 1.3.x |
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:
Required Hardware:
Required Software:
Development Tools:
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.
Abstract
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.
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).
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 .
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 |
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. |
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 .
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.
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 3 works pretty much straight out of the box with Torque.
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.
While not the most "visual" environment around, XEmacs is a fairly capable Torque editing environment. Here are some tips for using XEmacs with Torque.
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.
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.
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:
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.
Abstract
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.
This section contains the step-by-step instructions for building the binary package. The executable built by this process has the following requirements:
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) |
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.
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).
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.
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 |
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.
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.
You may be thinking: "This process is complex. Why not just build a fully statically linked binary?" There are a few reasons:
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!