Export ASE using USMExport (idtech)

Exporting ASE from Blender using USMExport in Blender 2.45

Getting custom made 3D models in to idtech 4 games (the various "Doom" and "Quake") is a lot easier to do now than is used to be with the older QeRadiant thanks to the improvements made over QuakeEdits ability to handle more 3D formats than previously.

The following tutorial will explain the process of getting 'static' models from a 3D modeling program into QuakeEdit and the games it supports so you will need a working knowledge of both QuakeEdit (the game you're editing) and a 3D application - whether that's Blender, Maya, gmax, Max et-al.

The following tutorial was written using USMExport as written for Blender 2.45 so certain features and options may have since changed and or been removed or improved. To export ASE using newer versions of Blender and scripts click here.

How to get models in to QuakeEdit ^

QuakeEdit essentially has two ways of loading models in to maps as they're being built. One is to 'load' an asset using the editors default model viewer. The other is to place a func_static into the level, loading the asset 'on' to the entity; QuakeEdit no longer loads models using the misc_model entity. These actions will be covered in more detail below, but suffice to say now, using either/or has the same end result; a model in the map.

View Properties & grid settings ^

Blender has this neat little feature, that usually goes unnoticed, which can be tricky to set up in other 3D app's; you can set the grid to mirror the unit based measurement system of Quake 3 and Doom 3 by altering the 'Spacing' info (highlighted in green opposite) of the background grid plan. This in theory means when you start to model you'll basically be using the same units of scale as Doom 3 so objects will match.

Design note : As of Blender 2.43 the minor grid spacing can be changed to use a different subdivision ("Divisions") from the default '10' - that is, the grid itself can display different subdivisions. This needs to be set to '8'.

NOTE : The grid currently only displays correctly in Orthogonal views (top, front and side views), the 3D viewport displays the grid settings incorrectly so it appears that you may be working on the wrong grid settings when in fact you are not.

setting up the grid in Blender to match Radiants

Changing GRID setting, "Spacing: 8.00" for idtech

To match the default QeRadiant and GTK Radiant grid settings in Blender, open the "View Properties" panel by clicking the "View" menu in the 3D windows header area and selecting "View Properties" - "View >> View Properties". Change 'Spacing' to '8.00' and max out the 'Clip End' value.

Design notes : If you need to go even bigger, because you're working on a terrain for instance, setting the spacing to larger sizes ('64.00') will also work; although you may need to import a sizing block as mentioned below so you're better able to keep relative size between brushwork objects and models correct.

Conversely, if you need greater precision using smaller values will also work - divide the grid setting ('8') by two (or any 'power of 2' subdivision) so you keep the relationship between Blenders grid and Doom 3 editor grid correct.

Another way to get your sizing info is to draw out a standard fixed block in Doom 3 Radiant, 128x128x128 for example, and then export that block to an OBJ model (select the object : menu > select > export > OBJ) which can then be subsequently imported into Blender or the modeling app you're using.

Incidentally, the default grid setup in Doom3 Radiant is '8' minor units (lighter coloured grid lines) per one major (the darker grid lines).

NOTE : Although Blender, as mentioned above, can be set to the same 'major' grid unit size as the Quake and Doom editors it's minor units are divided by '10' rather than '8'. This generally doesn't cause any issues.

Before export, quads, uvw mapped ^

It's assumed here that you have a object ready to roll and modeled using quad based polygons. It also needs to have been UVW mapped and then UVW unwrapped with at least a basic textured material (a material that contains a 2D texture).

Design note : When applying the material to the object keep in mind that you only need the basic material and the UVW map data. The more complex settings that can be applied to a material are not used, all the game is looking for is the base material and the UVW map

the model used for this tutorial

Completed model of a wooden corner support ready for exporting - note the models position relative to the XYZ grid, it's placed so the centre of mass is at the 0,0,0, point to allow for the model to be buried into brushwork without burying the origin point (which would be where the 0,0,0, point currently is) and resulting in 'leak' errors at compile time.

Prepping the model ^

We're going to be using the USM Unreal Tournament ASE export script for Blender3D by Doc Holiday. The good thing about this particular script is that the interface shows you any errors *before* you export a model.

Design note: Goofos's ASE export script can also be used and is in fact the preferred method over the now obsolete USM Exporter

If you try to export the model now, the chances are it'll throw up a few warning flags relate to certain aspects of the mesh, usually this will be to do with the presence of quad ('quadratic - 'quads' for short) polygons in the mesh - see image below showing quads selected.

Design note: Goofos's ASE exporter will automatically triangulate a mesh. It's preferred that this be done manually.

mesh with 'quads' selected

Original quad based polygon model

These need to be removed by converting the mesh to an object wholly composed of triangular polygons ('tris' for short), the reason for doing this is because of the way a quad is made; the corner to corner edge through the centre of the face - which you don't normally see - can follow a diagonal in more than one direction, this means the game engine can't determine where that diagonal edge is at any given time using just the corner vertex points without additional data.

Triangulating a mesh ^

Depending on what 3D app you're using converting quads to triangles may vary. In Blender3D you need to have all the vertices selected ('A') in edit mode and then hit keyboard Ctrl+T, this will force triangulation of the whole mesh. Incidentally you can convert triangles back into quads using Alt+J (but you have to do this one 'quad' at a time, otherwise you can't control which triangles get merged with their neighbour).

mesh with 'quads' selected as above, but now triangulated

...after triangulation

Once you've triangulated the mesh you should end up with something similar to the above - the yellow outline is the main 'quad' (made now from 2 triangles); the orange line the edge added by triangulation.

Edge 'turning'/Edge 'flipping' in Blender ^

You may notice after triangulating the mesh the new distribution of polygons has created some odd 'indentations' where the corner to corner edge cuts across the surface (the orange line in the image above). The next step is to correct these and check the orientation of the triangles so we give the mesh a more shapely appearance. Doing this means flipping or turning edges.

In edit mode simply select the corner vertices for the corresponding faces and press Ctrl+F, you'll see the edge between the two polygons change orientation. Be careful doing this though as you can crash Blender by trying to flip and edge into a weird placement.

Design note: if you're not sure whether the face has been selected look for the 'Mesh Tools 1' panel where you'll see a series of buttons. These correspond to various 'draw modes' which act as visual aids as you work. Select 'draw edges' & 'draw faces'. This now highlights the edges and faces you've just selected. As of Blender 2.35a there is now a face select mode which should allow the selection of faces by 'face' rather than by corresponding vertices - in edit mode use Ctrl+TAB to open a popup where vertex, edge or face can be selected.

Just go round the whole model checking to see if the edges are giving the mesh the shape it needs. Once you've done that the next thing to do is the smooth groups.

Smoothgroups and game models ^

If you were to export the model in it's current state you'd find it wouldn't be lit correctly in game, this is because Doom 3 is using the information it reads about the smooth groups from a 'solid' object. What this means is that Doom 3 reads how light gets distributed over an objects surface (polygon to polygon) by using smoothgroups so if you leave an object as one big grouping the lighting will be distributed relative to that, causing weird side effects in game (usually it results in an object only being lit correctly from underneath or from behind, but other visual artifacts occur). To correct this the mesh needs to be 'split', this is done using the split mesh command.

Forcing smoothgroups using 'Split Mesh' ^

Although Blender has various options to set different and variable smooth groups for 'internal' use, i.e.. within the Blender environment itself, splitting a mesh is the only way to guarantee wysiwyg in game What this basically does is physically detach selected faces into their own sub-mesh (to use 3DS Max terminology) whilst keeping it part of the parent mesh; i.e.. the mesh is still a single object.

The normal way of do this kind of thing is to physically detach mesh sections so they become individual objects not attached in any way to the original mesh. You would then select each section and 'merge' or 'attach' them back together into one mesh object. This basically does the same thing as split mesh as it creates a single object made from a number of sub-objects that have their own face vertices along any given 'shared' edge. Split mesh is slightly more convenient to work with.

using Blenders 'split mesh' command to create polygon 'regions'

Selecting vertices and face to create a new smooth group

Split mesh only works in edit mode (keyboard 'Tab') so once there make sure all the vertices are deselected ('A') - if you happen to leave the odd rogue vertex in place it can cause problems later so double check this (the mesh will turn yellow if you had any vertices already selected, just hit 'A' again to deselect all).

If you've turned on the draw edges & draw faces feature mentioned in the note above then as you select the vertices of each face that will form the basis of the sub-mesh it'll turn 'yellow', it's a good idea to have that tool turned on. Then all that needs doing now is to just hit 'Y'. A little popup will show which ask you to confirm the split, click 'split'.

Design note: if you think you've made a mistake in the selection when the 'split' popup shows just hit Esc or move the mouse away from the dialogue box to 'cancel' the operation. Depending on which version of Blender you're using (2.30 and above) you'll also be able to use UNDO by hitting the 'U' key whilst in edit mode.

Working with 'Split Mesh' smoothgroups ^

If there are several areas on the mesh that need to be split like this it's a good idea to then do at least one of two things.

  1. Add a new 'sub-material' and apply that the the still selected sub-mesh.

  2. Hide the current selection ('H' = hide 'Ctrl+H' = un-hide).

The reason behind this is that currently Blender won't allow you to select this sub-mesh 'as-is' so the only way to make the whole object easier to work with is to either hide the sections as you work on them or assign a different sub-material to them so at the press of a button they can be selected/deselected (from the 'Link & Materials' tool panel in the edit buttons window); trying to Shift+LMB click vertices when there are several of them in one location gets tricky and is time consuming on really complex splits.

separate smooth group region

Distinct smooth grouped areas

Once you've gone over the mesh and split it up the way you want the smooth groups to appear you'll end up with something similar to the shot above, you can see how the shadowing is distributed across the model to give clear and distinct regions, the top faces are no longer connected to the main body. The result of this is a nice clean line which allows each area to show up correctly lit in game

Design note: depending on what the model is like you may find, as was the case with the object shown above, that you may need to split the mesh down the back to 'force' the lighting to correctly show from the front. A split like that is kind of tricky to do on it's own - you can't just split the mesh along one set of vertices - so you have to split the mesh into two halves, front to back, and then weld the front set back together again thus creating a seam only down the back of the mesh.

If you find using the 'spilt mesh' feature cumbersome to use then you can, as was mentioned above, still split the up mesh the old fashion way by using 'Separate Mesh'. Simply select the verts/polys to create a selection area and then hit keyboard 'P' to totally create a completely separate object from selected polygons/verts. Once you've done this to the mesh and get the sections you want joining them all back together again using Ctrl+J will create smoothgroups as described above.

Multiple smoothgroups using the 'Split Mesh' function ^

Obviously creating of each split will depend on what the model is, the red lines shown below indicate where a 'boarder' has been created so that along the line there are multiple sets of vertices, one for each region, each 'leg' is a separate region the bottom faces of which have also been split so in game shadows don't try and wrap around that edge (the number of vertex sets will depend on the number of region splits in the local area). The box-out shows an important 'hidden' split that runs down the back of the model forcing an edge to be seen which in turn forces a slightly better distribution of the shadows on the trunk of the mesh in game Again the top and bottom faces of that section have been split from the main mesh.

red lines indicate the boarders of each split mesh region

Red lines indicate the boarders of each split mesh region

Design note: don't forget that to create a 'region' you need to select polygons up to the point at which you want a border to be created because you're separating mesh sections from each other and not vertex rows. As an example, the edge created on the connection point between the right leg and the trunk has been done by selecting all the polygons that constitute that part of the mesh and then splitting, if you select just the vertices along the edges and split you just end up with another row of vertices.

Prepping models for export ^

Depending on what the model is for and where it's going to go the final thing we need to do before export is position it in object space relative to the 0.0.0. grid centre of Blender and then 'freeze' it in place.

almost ready for export - the model is centered to allow for burrying into brushwork without errors.

Almost ready - the model is centred to allow burying into brushwork without errors.

The reason re-centring like this needs to be done is to avoid errors where the origin point of the model gets buried in solid brushwork. The example model used in this tutorial for instance has been positioned over the grid in such a way as to allow the origin point to occupy approx. the centre of mass of the models mesh. This now means that in D3Ed the model can be buried a few units into brushwork without worry about 'Entity Leak' errors (and thus given the impression of a wall being built around the support rather than the support just sitting on the surface).

Incidentally, if you're getting that error cropping up when you're doing something it's worth checking the origin point of the models you've used in a map as a first port of call to make sure none of them are buried or hiding inside brush work.

Design note: the origin point is a small outlined cube 'cage' you can see on model entities when viewed on D3Ed or GTK, it acts as the centre of rotation as well. It's of particular importance to be aware of this 'Entity Leaked' issue with Doom 3 as all brushes are seen as 'structural' and solid so anything caught inside them is culled from the BSP which makes the compile process think there's a leak (hole) in the map.

If you hold down Ctrl whilst moving the model it will move snapped to the grid. It's a good idea to try and do this especially if you've been accurate about a models size and position in relation to in game brush work. Objects can also be moved by smaller snapped increments by holding down Ctrl+Shift.

Apply 'Size' and 'Rotation' ^

Once the model is positioned where it should be on the Blender grid it needs to be 'frozen' into place, this is done with 'Apply Size/Rot'. It's important to do this step if using the USMExporter otherwise it basically re-centres the mesh back to the original position the model had when you first drew out the initial mesh object. This often means a model ends up facing the wrong way or lying flat on it's back. Simply select the model and hit Ctrl+A. A little popup will appear which you need to click to confirm the command. Once done the model is then ready for export.

Apply size/rot confirmation popup

Blender's "Apply size and rotation"

USM ASE Exporter setting ^

Switch to the 'text' viewport (Shift+F11) and then open up the USM exporter script, it'll appear as a text file because loaded scripts don't run by default (incidentally, make sure you have your python path correctly set up otherwise the script won't run or you'll get runtime errors) so with the mouse cursor over the text viewport press keyboard Alt+P to activate and run the script, you should see the GUI pictured opposite appear.

GUI settings ^

USMase exporter interface

USM-Export v1.1 settings

The example shown on the left lists details to do with the wooden support for this tutorial;

  • 'Name', is the object name assigned to the mesh.

  • 'Material', is the name of the material assigned to the mesh.

  • 'V-Color' indicates whether vertex colours is enabled or not (not sure if 'off' by default).

  • 'Textures', shows the number of textures used - this may only be '1' because of the way the plug-in works, it doesn't like seeing mesh data with more than one texture or material otherwise it 'merges' them all on export which gives bad results in game.

  • 'Vertices', lists the number of vertices contained in the mesh.

  • 'Triangles', lists the number of triangular polygons contained in the mesh.

  • 'Quads', lists the number of quad(ratic) polygons the mesh contains; this should be '0' for Doom 3 static model export.

  • 'Edges', list the number of 'rogue' edges contained in the mesh; this should be '0' for ASE export.

  • 'Lost Verts', lists isolated vertices; verts somehow separated from the main body of the mesh, should be at '0' for ASE export.

  • 'SmoothGr', lists the number of groupings the model contains for smoothing; this may list just '1' because of the way the mesh is prepped for ASE exporting.

  • 'Path', shows the 'save file to path on export'; usually the same folder/directory as the working directory the original Blender file is save/loaded to/from. Can be changed by pressing the '...' button on the right and browsing to another location.

  • 'VALID', message saying mesh is 'ok' for export. Any errors present in the mesh show up as red text and an 'INVALID' message.

  • 'Export to [file name].ase', pressing this button will export the mesh to ASE using default or custom settings. The export name is derived from the name given to the mesh object.

If the exporter doesn't show anything when you run the script simply select the object that needs to be exported and move the mouse back over to the exporter, the GUI will then change to list details relative to that selection. It's at this point that any 'errors' in the mesh will be reported by the exporter using red coloured text; polygons left as quads for example, would show as 'Quads : [value]' the [value] being the number of quads still remaining on the mesh. Any errors will need to be fixed before export.

Once the mesh receives a clean bill of health (no red errors) the exporter will give the 'VALID' stamp of approval indicating the mesh can now be exported to the location shown in the 'Path' text field by pressing the 'Export to [name].ase' button (where [name] is the value assigned to the mesh object).

Editing texture paths in the exported ASE model ^

The final part of all this is getting the model into Doom 3. Because Blender currently (at time of writing) has a hard coded limit on the number of characters you can use for an object or material name it means the ASE file has to go through another stage before it can be used correctly in game All this means doing is opening the file into NotePad (or a similar text editor - make sure it saves 'pure text' because some editors, like WordPad, tend to save hidden characters used for internal formatting into the file which can cause corruption in other applications to the extent that the file can't be read, opened or edited) and looking for a line of text that says *BITMAP.

*MAP_NAME "blocks.001"
*MAP_CLASS "Bitmap"
*MAP_AMOUNT 1.0000
*BITMAP "rock.tga"
*MAP_TYPE Screen
*UVW_U_OFFSET 0.0000
*UVW_V_OFFSET 0.0000
*UVW_U_TILING 1.0000
*UVW_V_TILING 1.0000

This needs changing to reflect the file path to where the texture (or material file) is so Doom 3 can find it.

Now this next bit is going to cause a bit of a ruckus because there are currently 3 different working methods to reference the file path for the models to work; I've only successfully got one of them to work so I tend to stick to that, they are (in no particular order);

  • //base/models/[path to your material ref]
  • //doom3/base/models/[path to your material ref]
  • //purgatory/purgatory/doom/base/models/[path to your material ref]

A corrected section of an ASE would then look similar to the following after the amends have taken place;

*MAP_NAME "blocks.001"
*MAP_CLASS "Bitmap"
*MAP_AMOUNT 1.0000
*BITMAP "//base/textures/project1/rock"
*MAP_TYPE Screen
*UVW_U_OFFSET 0.0000
*UVW_V_OFFSET 0.0000
*UVW_U_TILING 1.0000

Design note: Doom 3 and Quake 4 appear to have 'fixed' the peculiar file path 'problem' mentioned above. As noted the paths listed were a hangover from the leaked alpha where ASE models more often than not simply refused to work with the normal shader paths you may have been used to when working with Quake 3 ASE assets. In other words doing this;


Simply wouldn't work unless unless;


Was placed in front of the shader/material path at the *BITMAP reference in the ASE file.

For Quake 4 and Doom 3 editing now, the *BITMAP path only requires the respective 'base' folder reference in place so the model can pick up the material assigned to the *BITMAP section of the ASE. Apparently both Quake 4 and Doom 3 pick up the working material file path reference at the 'base' folder point, so in theory everything in front of it is ignored.

Quake 4


Doom 3


The file paths mentioned in the main article still work by the way, so if you're having trouble with these 'new' paths, revert back to those to double check everything is working correctly.

When creating or editing ASE models for use with Quake 4, simply replacing "base" for "q4base" will allow ASE models to load into the game. For more details click here.

If you use GTK or other map editor you might find that models don't appear correctly because of this odd pathing for ASE models. Check for updates regarding this with the coders for whatever editor you use.

Note also that you don't need to put the *.tga file extension on the end of the path because Doom 3 is actually referencing material files (shaders) so the actual image assets (textures) are indirectly referenced from the material (even when you don't use a material file the game still creates a material for these 'orphaned' textures in the background).

Once you've changed the *BITMAP path to reflect where you've got the model and it's assets, save it and place it in a folder within the 'base' folder of Doom 3, making sure to follow a similar file path indicated in the ASE file.

Design note: Make sure that your use of the '\' or '/' reflect what you have in the material file header. If you're using a material file reference header like this;


Make sure your ASE *BITMAP reference is like this;


And not like this;


The two are not read/used by the game in the same way. Also make sure you use lowercase words and letters otherwise the game may report errors to the console (occasionally it'll refuse to load the game if it finds uppercase letters, words and/or file paths).

All you then need to do is open up Doom 3 Radiant, right click on the grid viewport and select 'New Model...' from the popup menu. This will then open the internal model viewer from where you can browse to the new model. Once selected it'll preview and if everything looks ok click the 'OK' button and it'll be placed in Radiant. Compile the map and run in Doom 3 or just hit F3 with Radiant open and the camera viewport will go into 'render mode' which shows you exactly what you'd see in game It's a good quick way to check model lighting as any shadow problems you see here will show up exactly the same in game Depending on what happens here the model will be ok and shadows falling correctly or it won't. If it's still not lit correctly then the split mesh regions will need adjusting until you have something that looks correct relative to the model.

ingame shot showing model correctly lit

The model correctly lit in Doom 3. Also shown is a 'corner' support that's buried in brushwork without errors due to origin point placement as outlined above.