FreeWorld Editor

These tutorials focus mainly on OpenGL, Win32 programming and the ODE physics engine. OpenGL has moved on to great heights and I don't cover the newest features but cover all of the basic concepts you will need with working example programs.

Working with the Win32 API is a great way to get to the heart of Windows and is just as relevant today as ever before. Whereas ODE has been marginalized as hardware accelerated physics becomes more common.

Games and graphics utilities can be made quickly and easily using game engines like Unity so this and Linux development in general will be the focus of my next tutorials.

FreeWorld Editor

Released 21/07/2003

The FreeWorld editor was made to help alleviate a problem that many face when developing a game, at least for freelance/hobbyist game developers, which is that in order to program your own spatial partitioning system such as BSP trees, octrees and many other features you need to have world data to test them with. The choices were often to use a pre-written tool to extract the polygon data from an existing map format or write your own tool, unfortunately most existing map formats are confusing and making your own tool can be a challenge, especially if there is very little information available. For small tests you can just calculate the data yourself but it can take a lot of time if you want to test your program in a lot of different cases. The intention behind FreeWorld was to create an editor that exports the simplest data format possible so that writing your own world loader is made easier.

The editor is still under development, many changes to the program and interface will be made in the coming months. It also needs a lot more error checking and other niceties to be added to the program so you should save your world to a brush file (discussed later) regularly and if you run into an error message you can try ignoring the message and undo the last carve or add, if this doesn't work then you will have to abort the program. Also note that a lot of the following tutorial may have to change with the next updates or be scrapped altogether.

When the editor starts you will be asked for the name of a couple of data files, one is for a spline data file and the other is for a static light data file, for now choose the default files for each and the editor will begin. You will see that it has the standard three orthogonal windows and a perspective window. You can open as many windows as you like by using the main menu, though I haven't set a different camera for each perspective window, you can press C to cycle through five cameras using a single perspective window for now. If you find that the movement in the perspective window becomes slow then minimize any unused orthogonal windows you have open or maximize the perspective window.

FreeWorld History:

21/07/2003

The FreeWorld Editor allows you to create and export world data to be used in your own programs, the data file format is intended to be easy to understand and load, consisting of only polygon and texturing information. The program is still under development and future versions will see an improved interface and many additional features. The program also comes with a tutorial and full source code.

27/08/2003

I have now fixed a major bug with the FreeWorld Editor, namely the removal of the exterior/outfacing polygons of the map during compilation. The solution works well but makes the compilation process longer, if you want to know how I went about it you can have a read about it here. There still remains a problem with the textures when viewing the world which I will be working on next, as well as fixing a problem with the portal creation process which shows itself when compiling more complicated maps.

The other changes to the program are:

The addition of a new dialog with a progress bar when compiling the world.

Tessellating the polygons and removing the outfacing polygons is now optional.

Pressing the escape key now saves the current brushes for the undo function.

The disappearing main menu has been fixed.

The file sizes have been reduced by removing a lot of the textures.

Fixed the problem with rotating multiple brushes

One important point, if you plan to use your map with the loader, it seems to upset the portal creation if the origin is not contained within the interior of the map. The start position of the camera is at the origin which may be the issue.

I hope you find the program a little easier to use, if you have any suggestions then I will be happy to hear your ideas.

22/10/2003

I've had a bit of a rest from the program lately, just intermittently trying to get the concave brushes to carve and fix the excessive portal splits that occur when creating a large worlds. But to no avail, so I have just removed the partitioning and portals from the loader for now while I set about rewriting the portal creation code.

A few modifications to the editor are:

Fixed the keyboard controls for scrolling and zooming in the 2D views.

Now removes all coplanar polygons during the compile.

Improved the camera rotation in 3D view.

Fixed polygon selection to only select forward facing polygons.

Now deselects all brushes after compile.

FreeWorld Tutorial:

Toolbar

The toolbar buttons have tooltips enabled so you can see what function they perform by placing the mouse over them. Most of them, such as the first four buttons should be familiar to you if you have used a world editor before so I will only go over the differences. The fifth button adds all selected brushes together into a single brush, the brushes can be convex or concave. The sixth button will carve all brushes that intersect the currently selected brushes. The seventh and eighth buttons allow you to group and ungroup brushes, the color of the brushes in the orthogonal windows will change to highlight them if grouped, if you don't like the random color that the program produces then keep clicking the group button until you get a color you like. The next three buttons allow you to save and load the currently selected brushes to and from a file. This allows you to construct separate, modular pieces of buildings and furniture and later use them to construct a complete world. The next button is the undo button, for now it only allows you to step back to before the last carve or add, though a future version will allow multiple steps back and will include undoing of all transforms. Following the undo button are the last two brush functions which allow you to select or deselect all of the brushes, this is handy when you have finished constructing the world because, at present, the only way to save the world in the editor is to select all brushes and save them to a brush file. Later I will finish writing the function to save all the world data, including lights and splines, to a single map file. The next button with a T+ on it brings up the texture window and the T- button will hide it again. I won't go into texturing details here except to say that the textures in this window were automatically loaded from the TGA image files found in the textures folder when the editor started. Next we have the spline properties button which will be familiar to those who have used the Spline_Ed program, if not then take a look below for a description of what these properties are. Following the spline properties is the static light properties, the static lights can be created and set here to be used later if you want to illuminate the world using light mapping in the viewer. I will go into more detail about the static lights towards the end of this tutorial. The last four buttons on the toolbar will respectively, set the overall grid size, set the size of the cell between the grid lines, toggle snap-to-grid and the last button will set the rotation angle used when rotating brushes and textures.

Status Bar

The left hand side of the status bar displays the current position of mouse in OpenGL coordinates as it travels over the orthogonal windows, but not when traveling over the perspective window. The next four positions on the status bar reflect the values selected using the last four toolbar buttons.

Camera Movement

The movement of the camera in the perspective window is controlled with the mouse, left click and hold the button down to turn the camera or right click and hold the button down to move the camera backwards and forwards or to rotate the camera. Camera movement in the orthogonal windows is very similar, left click and hold the button down to drag the grid to a new position or right click and hold the button down to zoom in and out.

Build Lines

You might have noticed that the yellow lines crossing the center of the grid turn red as the mouse moves over them, these yellow lines are called build lines and allow you to set the third coordinate when creating a brush in an orthogonal window. By left clicking and holding the button down you can drag these lines within the orthogonal windows. They are necessary when more than one orthogonal window is open for the same view, if you had two front windows open in different positions on the Y axis and you were creating a brush in the top window then it becomes unclear where on the Y axis the brush should be created. The brushes could have been created at the origin by default but that involves moving the brush to its final position after it is created, with the build lines you can set the third coordinate exactly when building in the orthogonal windows. So if you are creating a brush in the top window you would first position the horizontal Y axis build line in the front or left windows, or if you are creating a brush in the left window you would first position the vertical X axis build line in the front or top windows. They are also used to position the brush when pasting a copied brush. If the view in an orthogonal window moves so that the build lines are outside of that view then the build lines will float at the edge of the window to make selecting them easier.

Brush Creation

To create a brush, hold down a shift key and left click and drag in an orthogonal window to create the dimensions of the brush, then release the left mouse button to create the brush. If you release the shift key before the mouse button then the brush creation will not go ahead. When the brush is created it is highlighted by a red bounding box with resizing control points in green.

Selecting & Deselecting Brushes

To select between different brushes in the orthogonal windows left click on any edge of the brush and the bounding box will highlight the selection. Within the perspective window you select a brush by double left clicking on the brush and the selected brush will be tinted red. To select more than one brush or to deselect a brush hold down the control key. Pressing the escape key will deselect all brushes.

Moving & Rotating Brushes

To move a brush or group of brushes left click within the brushes bounding box and drag it to a new position. Holding the tab key and left clicking within the brushes bounding box will rotate the selected brushes anti-clockwise by the current rotation angle while right clicking will rotate the brushes clockwise.

Adding and Carving Brushes

When adding brushes you can add both convex and concave brushes. When carving the cutting brushes must be convex as the brushes produced will be illegal if you cut with a concave brush. One difference between this editor and other editors is that a concave brush will be produced as a result of the carve rather than a group of convex brushes, this was done because the next update of the editor will allow carving with concave brushes. I will add here, for those that are interested, that the carving of a concave brush is done by first partitioning the brush into convex areas and creating temporary portals to fill in the missing faces along the partitions. If you want to see how the brush was partitioned press T to toggle the test mode, the perspective window will display a wire frame view of the last brush to be carved in yellow and show the portals as blue faces. As the brush to be carved becomes more complicated then the longer it takes to carve it due to the partitioning process. For this reason I recommend that you make your world in a modular way, constructing small building blocks and saving them to a brush file, rather than adding and carving one big world brush. Also, there is little need to add the brushes together for the same reason above, all the brushes are added together and have the redundant polygons removed before the final creation of the world data.

Textures

To enter texture mode press the T+ button on the toolbar. When you are in texture mode the brush selection in the perspective windows changes to allow the selection of individual polygons. To change a texture, first double left click on the polygon you want to change in the perspective window, it will be highlighted with a yellow tint. As with brush selection, you can select more than one polygon at a time or deselect a polygon by holding down the control key when double clicking. Pressing the escape key will deselect all polygons. To change the textures of all selected polygons simply click on the texture you want in the texture window, you can add more textures by double right clicking in the texture window and selecting add from the context menu that appears but there is no way to remove a texture for now. When you have a polygon or group of polygons selected you can rotate the textures by holding down the tab key and left or right clicking anywhere within the perspective window. To shift the textures first hold down the shift key and left click and drag the mouse within the perspective window or to scale the textures do the same but by right clicking and dragging the mouse instead. I need to put in a bit more work with the texture window until I am happy with it, for example you currently have to left click on a texture in the texture window before you can select it as the default texture or brush default texture, this is best done when no polygons are selected. The difference between the default option and the brush default option is that the default option sets that texture as the texture to be used when creating any brushes while the brush default option will set all polygons on the currently selected brushes to that texture but not for newly created brushes. To hide the texture window, and leave texture mode, either select hide window from the context menu or use the button on the toolbar.

Saving & Exporting the World Data

As I mentioned above, the only way to save the world at the moment is to select all brushes and save them to a brush file. When exporting the world using the main menu you will be given the option to save the static lights, sometimes this may fail to occur, if so you can save these yourself using the save option in the static light properties. Splines are not saved automatically so you need to save them yourself using the spline properties dialog. The world is currently exported as triangles to make the data compatible with my world loader/viewer, but the next version will allow the saving of the n-sided polygons and I plan to add options to save the data in an indexed form or as precompiled sectors (leaves of a BSP tree) so that the loader/viewer does not have to BSP the polygon data before using it. The data that the editor exports is intended to be easy to read into your own programs, the data file begins with an integer value for the number of polygons (triangles in this case) in the data file which is then followed by the data for each polygon:

unsigned integer value

float

integer

Which is then followed by the data for each vertex of the polygon:

float

texture index

horizontal texture scale

vertical texture scale

horizontal texture shift

vertical texture shift

texture rotation value

number of polygon vertices (three in this case)

x coordinate

y coordinate

z coordinate

u texture coordinate

v texture coordinate

Keyboard Controls

Not all of the keyboard controls have been added yet, though there are some for changing the camera and for camera movement, namely pressing C will switch between five different cameras in the perspective window and you can use the arrow keys with the pageup and pagedown keys to move the camera.

The numbers 1-9 and 0 are used to set the speed of camera movement 1 being the slowest and 0 being the fastest. The other keyboard controls are the escape key, which deselects any selected brushes and polygons, the space key which will reset the camera for the active window and the insert and delete keys will resize the grid. The H key will toggle the test mode which displays a wire frame view of the last carved brush and the G key toggles snap-to-grid.

Splines

The splines are used to set a path through the world for the camera to follow or for it to look at. At the top of the properties window you can use the drop down list to select the current spline to work with. Within the orthogonal windows, you can only manipulate the current splines control points. Next to this are two check boxes that set or clear the splines visibility and repeat properties. If the repeat check box is clear then the output point on the spline will only travel the spline once and then stop, otherwise it will repeat continuously. At the top left of the properties window you can set the color of the spline. On the left hand side of the properties window you can enter the degree of the spline and the number of control points it has, below these you can set the number of output points which is basically the resolution of the spline, the more output points the better the spline will look. Below this you can set the start and end times (in milliseconds) for the spline, the greater the time between the start and end times the longer it takes for the output point to travel the spline. On the right hand side of the spline properties dialog you can add, delete, save and load the splines, below these buttons you can cycle through the splines with a single click on the button marked current and do the same for the target spline below this. The target spline is the spline that the camera will look at when the camera is in 'follow' mode, which you can select by clicking on the (camera) mode button. The other two modes are 'free' which is the default camera mode and 'look', which means that the camera will travel along the current spline and look directly at the origin.

Static Lights

The static lights are used in the world loader/viewer to illuminate the world using light mapping. The static lights are represented in the perspective window as wire frame spheres and by circles in the orthogonal windows. You can move the static lights within the orthogonal windows by left clicking and dragging on the center control point or resize the lights diameter by left clicking and dragging on the control point on the circles perimeter. From the static light properties window you can select the current static light by using the drop down list near the top, next to this is a check box to set the current lights visibility state in the editor, this has no effect within the viewer as all lights are treated as visible. You can change the color of the light by clicking on the button next to the check box, this color is used within the viewer. Below the color button you can add, delete, save and load the lights. On the right of the properties window you can manually enter the position and radius values for the current light and also set the light brightness value. Setting the brightness of the light takes a bit of practice, but try setting the brightness to a overly high value to start with and then test them in the world, if the lights are brighter than you want you can then load the lights back into the editor to make the changes, if the brightness is set too low or the light is outside of the world then the polygons will not be illuminated.

Things to Note:

The textures are loaded automatically by the editor when the program starts, the program searches for any TGA images it finds in the textures folder, if you want to change the textures loaded at startup then add them to this folder before the program starts. The textures folder for the editor and the loader/viewer need to be identical for the correct images to appear when viewing the world.

With the splines and static lights you should load and have present at least one of each or the program may crash, just make them non-visible if you don't want to see them.

There is a small bug that I haven't tracked down yet that means that you can't select the build lines or static lights at the origin until at least one brush has been created, unfortunately that is my only clue as to what the problem may be, if the brush is deleted then you can select objects at the origin.

One problem is related to the removal of exterior polygons when the world is compiled. I have found that some of the exterior polygons are not being removed so this may upset the BSP process in the world loader, the workaround to this problem for now is to make sure the exterior of the world is a box shape before compiling and the easiest way to do this is to start with a solid box and carve out the rooms of the world but compiling and carving can take a lot longer due to the complexity of the brush.

When you come to export the world and you select the menu item it may take a while to respond, this happens because the program compiles the world before the save-as dialog appears, the same can also happen when carving a complex brush, it will appear as if the program has frozen, but it is working in the background. I'll have to add a progress bar with the next update.

There also appears to be more than one polygon per face left after some carves which sometimes results in the wrong polygon being rendered in the world loader.

Lastly, the world loader does not load worlds with a single room, it expects the world to partition into more than one area during the BSP process, I will fix these and any other bugs that I find before the next update.

I hope you find the editor useful, it desperately needs an undo for transformations and many other standard features, though it should be helpful if all you need is a simple world. If you have any problems or suggestions then send me an email or you can post to the Wiki below.