components used: 3D State

this tutorial will not work with borland kylix

Part 1Part 2 download source code

In the first of our series on how to use the 3D State Engine for Delphi, we're going to introduce you to a few basic commands that allow us to load in an example world (built using 3D State's World Builder), and display it on the screen. We'll show you how to then navigate around the world. This tutorial will not go through the details of actually creating the World file we are about to load in, but instead show you how to get Delphi to use a sample World file that I've taken from the 'Worlds' folder found with the engine. I've chosen this file because of it's simplicity.

The first step is to link our program to the 3D State Engine. Once you've created a new application, the first thing you want to do is go to 'Project' | 'Add to Project...' from the menu (or Shift+F11), and navigate to the Engine/Uses directory where you installed the 3D State Developer Studio for Delphi. The file you want to add to your project is called 'STATED.pas'. Once you've done this you need to also place the '3DSTATE.dll' file (found in Engine/DLLs) either into the same directory as you're saving this program, or into your Windows/System folder (so that all future programs you write can use it).

With that out the way, we can now start the actual coding. The first thing we'll want our code to do when it's run is to get the engine to open the world file. The best place to put this code is in our FormShow procedure, so go to the Events tab and create an 'OnShow' handler. Now enter code so that your FormShow procedure looks like that shown below.

procedure TForm1.FormShow(Sender: TObject);
  LoadWld : Integer;
  ErrorMsg : string;

  LoadWld := STATE_engine_load_world('Lesson6.wld', '', 'Bitmaps', USER_DEFINED_BEHAVIOR);

  if(LoadWld <> OK) then

    ErrorMsg := 'The world failed to load. Aborting.';
    MessageBox(Handle,PChar(ErrorMsg),'Error',MB_OK or MB_ICONWARNING);

  camera := STATE_camera_get_default_camera;

This code is pretty simple. We're actually only using two lines of code that refer directly to the 3D State Engine, the rest is fairly simple Delphi code. These other lines handle error checking, and throw up a message box displaying the error found in the String variable 'ErrorMsg' if the world fails to load for whatever reason (errors are logged to the file error.log). The line we're really interested in though, is that of the very first line after our first begin. This line uses 'STATE_engine_load_world' to open the file Lesson6.wld.

The first of the four parameters in this function specifies the name of the file itself, the second specifies a directory where the world are placed (which in this case we don't need), the third parameter specifies the name of the directory of the textures used in our world file, and the last parameter tells the engine to let us specify how we move the objects around the world.

The second of the two engine functions sets up our camera in the scene. We're using a variable called camera for this, of DWORD type. You'll need to add the following line to the 'private declarations' section of your code up near the top, to declare this variable:

camera : DWORD;

The camera variable will specify where the engine can find the default camera in our scene. If we had many cameras in our world file we would use STATE_camera_get_using_name to specify which camera from our world file we want to look through at this time (provided we can remember the name of it).

At this point then we've loaded in our world and set up our camera. We need to however display what the camera can see in the world on our form. We do this using the OnPaint event, which you should create, and alter so it looks like this:

procedure TForm1.FormPaint(Sender: TObject);
(STATE_engine_is_engine_empty() = YES) then


Again, you'll see that the code here is very simple. The first thing we do is check to see if the STATE engine is empty or not. It should be, because we've just successfully loaded in our world file, but it never hurts to be sure. If that's gone well, we then proceed to the bit where all our work is shown on the form. The STATE_engine_render function does this easily, by taking in the name of our window (the 'Handle' bit) and our camera (in this case we've called it 'camera' because we're imaginative like that). Calling this line places whatever the camera in our world file can currently see. Simple!

Before we compile though, we need to do make a few other additions just to make sure everything goes smoothly. We need to create our OnClose event and make it look like that shown next.

procedure TForm1.FormClose(Sender: TObject; var Action: TCloseAction);
  Action := caFree;

There's little to be said for these two lines. The first simply closes the engine, while the second closes the form, and frees up any allocated memory that it was using. They're both very important lines to call though to make sure everything closes down correctly, so don't forget them!

You should now be able to compile and run your code. Doing so will display the world file in all it's glory across your form. You can't move around yet, making it a bit useless, but we'll do that in part 2, on the next page.

Part 1Part 2 download source code

Subscribe to the feed NEWS Feed
archived news | mailing list

[ all tutorials found at are Copyright © 2008 Ben Watt ]