CS 638 Project 0.0: Getting started with the LithTech Development System

This page is designed as a tutorial to get you up and running with the LithTech Development System (LTDS). By the end of the tutorial, you will understand the basic structure of a client-server LithTech application, and will have created a functional (although extremely basic) program using the LTDS.

Throughout this tutorial I will refer to the LithTech Programming Guide. This can be found in PDF form in the C:\Program Files\LithTech\docs directory.

The first step in getting you familiarized with the LTDS is to read the following sections of the Programming Guide:

Many of the concepts discussed in the Programming Guide will become more clear as you gain experience with the LTDS.

You will now create a LithTech application by following a few main steps.

I. Set up Visual Studio

   Visual Studio needs to know where to find include files and libraries. After starting up the IDE, click on Tools -> Options, then click on the Directories tab. Add the following directory to the Include files list:

   C:\Program Files\LithTech\engine\sdk\inc

   Use the up-arrow icon to move the directory you entered to the top of the list (so that Visual Studio finds LithTech versions of files before other versions). Next, add the following directory to the Library files list, moving it to the top when finished:

   C:\Program Files\LithTech\engine\sdk\lib

II. Create a new workspace

   In Visual Studio, click on File -> New, then click the Workspaces tab. Select the directory where you want your workspace to be created (this should be somewhere in your personal directory), then type in the name of your workspace (e.g., "Project1 "). This will also create a new directory under the one you just specified (with the same name as your new workspace). I will refer to this directory as your project directory.

III. Create a CShell Project

1. The LithTech game engine contains all the core functionality of the LTDS (e.g., physics, rendering). The code you write will be compiled into dynamic-link libraries. When you execute LithTech.exe, the engine will load the libraries and call the functions you have provided to run the game (diagrammed on page 10 of the Programming Guide). The first library you need is a client shell. Add a new Win32 Dynamic-Link Library project to the workspace. Name it cshell with the following Location :

   <your project directory>\cshell\src

2. In the Win32 Dynamic-Link Library – Step 1 of 1 dialog box, select An Empty DLL project. Click Finish.

3. Add the following files to the project:

   C:\Program Files\LithTech\engine\sdk\inc\ltdistrobj_impl.cpp

   C:\Program Files\LithTech\engine\sdk\inc\ltengineobjectsclient.cpp

   C:\Program Files\LithTech\engine\sdk\inc\ltmodule.cpp

   C:\Program Files\LithTech\engine\sdk\lib\physics.lib

4. You will now have to write the client shell class, which will be defined in ltclientshell.h and ltclientshell.cpp. Click this link to go to a tutorial on implementing this class.

5. Add ltclientshell.h and ltclientshell.cpp to the cshell project’s source files.


IV. Create an SShell Project

1. Add a new Win32 Dynamic-Link Library project to the workspace. Name it sshell with the following Location:

   <your project directory>\sshell\src

2. In the Win32 Dynamic-Link Library – Step 1 of 1 dialog box, select An Empty DLL project. Click Finish.

3. In the sshell Project Settings dialog box’s Link tab for All Configurations, change the Output file name to object.lto.

4. Add the following source files to the project:

   C:\Program Files\LithTech\engine\sdk\inc\ltdistrobj_impl.cpp

   C:\Program Files\LithTech\engine\sdk\inc\ltengineobjects.cpp

   C:\Program Files\LithTech\engine\sdk\inc\ltmodule.cpp

   C:\Program Files\LithTech\engine\sdk\lib\physics.lib

5. You will now have to write the server shell class, which will be defined in ltservershell.h and ltservershell.cpp. Click this link to go to a tutorial on implementing this class.

6. Add ltservershell.h and ltservershell.cpp to the sshell project’s source files.

V. Compile and Execute the Skeletal Application

1. Build both the cshell project and the sshell project.

2. As explained in the Programming Guide, all the resources and code for a LithTech application are usually rooted in a single directory, which is referred to as the resource directory. Any levels, models, sound effects, and textures will be placed in their own directories within this resource directory. Create a new folder in your project directory called rez as shown below:

   <your project directory>\rez

3. You now need to copy the two libraries you have created into your resource directory. In a full-scale LithTech application, there would be other directories under rez, such as worlds, models, and sounds. For now, all you have are the client and server shell, so you don’t need to create any other directories. Copy the following files into the rez directory from Step 2 (skip the debug\ part if you did a release build):

   <your project directory>\cshell\src\debug\cshell.dll

   <your project directory>\sshell\src\debug\object.lto

4. There are two other libraries that need to be present for LithTech to run. We will not be creating these files, so we will need to copy them from one of the LTDS sample applications. For more information on what these files do, consult the Programming Guide. Copy the following files into the rez directory from Step 2:

   C:\Program Files\LithTech\samples\base\samplebase\rez\cres.dll

   C:\Program Files\LithTech\samples\base\samplebase\rez\sres.dll

5. It is useful to have a bin directory, because you can then have a variety of batch files that build your project, run it in debug or release mode, and other such things. It is also where you put autoexec.cfg, which is used for specifying keyboard and mouse commands for your application (along with some other uses). Create the following directory:

   <your project directory>\bin

6. Select both of your projects, then open the Project Settings dialog box for Win32 Debug. Select the Debug tab. In the Executable for debug session box, enter the absolute path to the LithTech executable:

   C:\Program Files\LithTech\proj\Debug\lithtech.exe

7. In the Working directory box, enter the absolute path to your application’s bin directory. In this case:

   <your project directory>\bin

8. You now need to tell the application where it can find certain default engine objects (found in engine.rez). More importantly, you need to specify where your application’s libraries (client and server shells) and other resources (levels, textures, etc) are located. This is done with the -rez command-line parameter. In the Program arguments box, enter the following:

   -rez C:\Program Files\LithTech\proj\debug\engine.rez -rez ..\rez

9. You can now execute the application from Visual Studio. All you will see is a black screen with a bit of text on the console. To quit the application, press '~' to bring down the console, then type "quit" and press the Enter key. (If what you are typing does not echo to the console, just type “quit” and press Enter anyway – it should still work)