How to add custom meshes

Prerequisites:
How to add custom packages

Overview:
This page will show you how to add your own custom models (meshes) to Deus Ex.  It won't cover modeling, texturing, or animating, but it will tell you what to do once those steps are done.

Terminology:

Mesh - In this context, a mesh is just another word for a 3D model.

Texture - A 2D image.  This can refer to textures external to UnrealEd, such as .pcx files, or to textures imported into one of your packages.

Vertex - A single point in 3D space.  These are basically floating "dots" that are used to help describe the shape of your model.  When you model, you "connect the dots" in various ways in order to define how the solid parts will look.  (the plural is "vertices")

Polygon - In the Unreal engine, this describes three vertices (points) that are "connected" in a particular order.  In the world of 3D animation, this is called a "three point polygon".  In other words, a triangle!  These triangles form the solid part of your model (the part that you actually see).

Surface - A group of polygons in your mesh that can be referenced as one and can have a set of UV texture mapping coordinates associated with them.  In MilkShape, each Group that you create will end up being a surface.

UV Coordinates (a.k.a. Texture Mapping Coordinates) - A set of 2D coordinates that refer to a row and column position on a texture image.  In the Unreal engine, every polygon is a triangle made up of three 3D points.  Every polygon in a surface can also be associated with three 2D points that refer to a triangle-shaped region of a texture.  These 2D points are called UV coordinates.  The "U" refers to the column position and the "V" refers to the row position.  It's called UV instead of XY so that it's not confused with X, Y, and Z when talking about 3D coordinates.

1. Create your custom mesh

Modeling, texturing, and animating are each huge topics, so I can't cover them in detail here.  You may want to hunt down some tutorials or books.  I can give you some general tips and point you to some resources though:

MilkShape Home Page (for MilkShape users)
Flay.com (Lightwave)
DaliLlama's Lightwave [6] Page (this guy worked as a modeler/animator on Deus Ex)
3D Cafe (multiple, including 3DS, Maya, Lightwave, etc)
3D Palette (multiple; specific to gaming)

General tips:
* The Unreal engine is limited to 8 surfaces per mesh.  So, for instance, don't use more than 8 Groups in MilkShape or more than 8 Surfaces in Lightwave.
* It's a good idea to center your model in most cases.  If you're creating a character, it may be easier to set it up so that it is standing on the ground plane. (at Y=0 in most modeling tools)
* The height and width of your textures need to be "powers of 2."  In other words, both the height and the width need to be one of these numbers: 1, 2, 4, 8, 16, 32, 64, 128, or 256.  You can go higher (512, 1024, etc), but that doesn't seem to be typical when using the Unreal engine (yet).  The height and width do not need to be the same, so a 64 x 32 image is fine.

Once you have successfully created your mesh, including texturing and animation, you're ready to go on.  If you want to create a generic mesh that can be used multiple times with different textures (skins), you'll still need to assign texture coordinates (UV coordinates) to your mesh using reference textures.

2. Export or convert your mesh to Unreal format

Your next step will be do create an initial pair of mesh files in Unreal format.  The exact procedure or utility you use will be different depending on what modeling tool you're using.  Here's a list of the common ones with links to where to find them:

In some cases, you may have to convert your mesh into another 3D format before you can export to Unreal format.  For instance, you may end up having to export from Lightwave into 3DS format first. (note that only Lightwave 6.5 supports 3DS exporting with UV texturing)

Whichever tool you end up using, you'll end up with a pair of files ending with .3d.  One will end with _a.3d and the other with _d.3d.  Some of the tools will also create one or more .uc files.  We'll get into those later, but you'll probably end up needing to edit at least one .uc file.

You'll also want to convert all of your textures to .pcx format if necessary.  If you used 256-color .pcx files as textures in your modeling tool, you don't need to do anything else with them.  Note that only 256-color (8-bit) textures are supported by the Unreal engine.  This isn't as bad as it may sound, since each image can have its own palette.

If you're using Lightwave 5.x and UView, you'll have to refer to the SDK documentation on how to use LWO23D.  I don't have UView, so you're on your own here!  If you get it to work, you can skip to Step 4.

Also, if you're using 3ds2de, you can skip to Step 4.

3. Convert your mesh into Deus Ex format

Unless the tool you used in Step 2 directly supports the Deus Ex format (so far, the only one I know of is the LWO23D tool that comes with the SDK), you will then need to convert your .3d files into the Deus Ex format.  Note that the Unreal engine will allow you to import the .3d files without doing this step, but your mesh is going to look like a jumbled mess!

Currently, the only tool I know of to do this step is my "unr2de" converter.  If you don't have it, download it and read the instructions here:

Unreal to Deus Ex Mesh Converter

If you use MilkShape, you'll also want to check out the MilkShape export tips at the above link.

4. Create or modify a .uc file for importing the mesh into Deus Ex

If the tool you used in Step 3 created a .uc file, you'll need to pull it up in a text editor.  If it did not create a .uc file, you can use the following example as a starting point.  Move or save this .uc file in your Classes folder that is under your package's folder.

class LaserGun expands Actor;

#exec MESH IMPORT MESH=LaserGun ANIVFILE=MODELS\LaserGun_a.3d DATAFILE=MODELS\LaserGun_d.3d X=0 Y=0 Z=0
#exec MESH ORIGIN MESH=LaserGun X=0 Y=0 Z=0

#exec MESH SEQUENCE MESH=LaserGun SEQ=All STARTFRAME=0 NUMFRAMES=25
#exec MESH SEQUENCE MESH=LaserGun SEQ=Still STARTFRAME=0 NUMFRAMES=1
#exec MESH SEQUENCE MESH=LaserGun SEQ=Fire STARTFRAME=1 NUMFRAMES=20
#exec MESH SEQUENCE MESH=LaserGun SEQ=Reload STARTFRAME=21 NUMFRAMES=5

#exec MESHMAP NEW MESHMAP=LaserGun MESH=LaserGun
#exec MESHMAP SCALE MESHMAP=LaserGun X=1 Y=1 Z=1

#exec TEXTURE IMPORT NAME=LaserGunTex1 FILE=MODELS\raygun_barrel.pcx GROUP=Skins
#exec TEXTURE IMPORT NAME=LaserGunTex2 FILE=MODELS\raygun_body.pcx GROUP=Skins

#exec MESHMAP SETTEXTURE MESHMAP=LaserGun NUM=1 TEXTURE=LaserGunTex1
#exec MESHMAP SETTEXTURE MESHMAP=LaserGun NUM=2 TEXTURE=LaserGunTex2
#exec MESHMAP SETTEXTURE MESHMAP=LaserGun NUM=3 TEXTURE=LaserGunTex1

defaultproperties
{
DrawType=DT_Mesh
Mesh=LaserGun
}

To understand everything that's going on here, let's break down all of the types of statements you'll need to have in your file.

Class Definition Statement

class LaserGun expands Actor;

Well, right off the bat we've got a problem.  The tool you used to create your .3d files didn't know anything about how you plan on using your mesh, so it just set it up as a generic "Actor".  This is rarely (if ever) what you'll want when you get to the point of really using your mesh for something (like for a weapon or character).  Even if it's just a "decoration", you'll want to change this.  We'll get back to this later, but for now this is enough to get the mesh into Deus Ex.  It will show up in the UnrealEd Mesh Viewer and as something you can place in a map.  You just won't be able to do much with it.

For now, replace "LaserGun" with what you want to call your new object.  Do not include any spaces.

Mesh Import Statement

#exec MESH IMPORT MESH=LaserGun ANIVFILE=MODELS\LaserGun_a.3d DATAFILE=MODELS\LaserGun_d.3d X=0 Y=0 Z=0

This one's easy.  Just replace the _a.3d and _d.3d names with the names of your .3d files and call your mesh something after the "MESH=".  This tells the Unreal compiler where to find your .3d files.  In this example, the .3d files would be stored in a Models folder under your package folder.  This is the common convention, so it's best just to stick with it.

Origin Statement

#exec MESH ORIGIN MESH=LaserGun X=0 Y=0 Z=0

For most items like weapons or pickup items, you'll want to just leave this statement as is, except for changing the mesh name.  The MESH ORIGIN statement sets up where the center of the mesh is.  In other words, the point where your mesh will rotate around and move from.  If you've centered your mesh properly in your modeling tool, you can use X=0 Y=0 Z=0 and the square selection brackets that appear in the game when you're pointing at an item will line up correctly, among other things.

If you're doing a character, you may find it more convenient to model with the feet on the "ground".  In that case, you'd want to compensate for that by changing the Z value to halfway up your mesh.  In that case, your MESH ORIGIN statement would have something like Z=37 instead of Z=0.

You can also use the MESH ORIGIN statement to set the initial rotation values of your mesh.  If you've modeled a character, and he/she ends up standing the wrong direction in the game, you can fix that here.  You do that by adding PITCH, ROLL, and/or YAW values to the statement.  The values aren't angles though.  A value of 64 means 90 degrees, a value of 128 means 180 degrees, etc.  So this statement:

#exec MESH ORIGIN MESH=LaserGun X=0 Y=0 Z=0 PITCH=32 ROLL=128 YAW=-64

...would mean a pitch of 45 degrees, a roll of 180 degrees, and a yaw of -90 degrees.

Animation Sequence Statements

#exec MESH SEQUENCE MESH=LaserGun SEQ=All STARTFRAME=0 NUMFRAMES=25
#exec MESH SEQUENCE MESH=LaserGun SEQ=Still STARTFRAME=0 NUMFRAMES=1
#exec MESH SEQUENCE MESH=LaserGun SEQ=Fire STARTFRAME=1 NUMFRAMES=20 RATE=20
#exec MESH SEQUENCE MESH=LaserGun SEQ=Reload STARTFRAME=21 NUMFRAMES=5 RATE=7.5

If your mesh includes animation, you'll usually need to name your various animation sequences in these statements.  Most tools that generate .uc files when you create your .3d files don't do much for you here.  By convention, the first sequence name is called "All" and simply includes all of your animation frames.  Create a MESH SEQUENCE statement for each of your animation sequences and give each a meaningful name.  Unless the sequence is only 1 frame long, you'll want to add a "RATE=" statement to the end of the line.  This sets up how long it will take to play the sequence, in frames per second.

If your mesh does not include any animation, you can just use something like this:

#exec MESH SEQUENCE MESH=LaserGun SEQ=All STARTFRAME=0 NUMFRAMES=1
#exec MESH SEQUENCE MESH=LaserGun SEQ=Still STARTFRAME=0 NUMFRAMES=1

Meshmap to Mesh Associations

#exec MESHMAP NEW MESHMAP=LaserGun MESH=LaserGun

Don't worry about this one; just replace LaserGun with the name of your mesh and you'll be fine.

Meshmap Scaling Statement

#exec MESHMAP SCALE MESHMAP=LaserGun X=1 Y=1 Z=1

Scaling is an important concept to understand.  The way that your modeling tool's "units" relate to Unreal units differs depending on which tool you use; in some cases the conversion tool you use is a factor too.  In MilkShape it's easy: 1 MilkShape unit will become 1 Unreal unit.  That way if you treat 16 units in MilkShape as 1 foot, you should be able to set your scaling to "X=1 Y=1 Z=1".  Note that when you use "unr2de", the X, Y, and Z scaling should all be equal (unless you want to stretch your mesh out).  This is different that what most tools will put in your .uc file because of how the traditional Unreal format works (Z will be half of what X and Y are).  Just remember that you'll need to change the numbers to all be the same.

If you go poking around in the mesh import files that the actual game used, you may run into this sort of thing:

#exec MESHMAP SCALE MESHMAP=GM_Suit X=0.00390625 Y=0.00390625 Z=0.00390625

If you were wondering, the number 0.00390625 isn't just some wacky number that somebody made up.  It's 1/256.  If you are using 3ds2de or a conversion tool that directly supports the Deus Ex format, these would be appropriate scaling values.

Mesh Notify Statements (optional)

#exec MESH NOTIFY MESH=GM_Suit SEQ=Walk TIME=0.1 FUNCTION=PlayFootStep
#exec MESH NOTIFY MESH=GM_Suit SEQ=Walk TIME=0.6 FUNCTION=PlayFootStep
#exec MESH NOTIFY MESH=GM_Suit SEQ=Run TIME=0.1 FUNCTION=PlayFootStep
#exec MESH NOTIFY MESH=GM_Suit SEQ=Run TIME=0.6 FUNCTION=PlayFootStep

You may want to synchronize something with particular parts of your animation sequence.  For instance, if you've created a new character mesh, you might want to take a walk cycle that you've created and sync each footstep with a sound of the footstep.  In this example, the Walk and Run sequences are both 10 frames long and in both, one foot hits the ground at 0.1 (10%) into the animation sequence, and the other foot hits the ground at 0.6 (60%) into the sequence.  This value is independent of the animation rate of each sequence; the Walk sequence's animation rate is 10 frames per second and Run is 18 fps.

Texture Import Statements (optional)

#exec TEXTURE IMPORT NAME=LaserGunTex1 FILE=MODELS\raygun_barrel.pcx GROUP=Skins

While I've labeled this part as "optional", you'll almost always have it.  For every new texture image that your mesh uses, you'll need a line to import it.  Give it a meaningful name in place of "LaserGunTex1" and fill in the name of the .pcx file.  In this example, the .pcx files would be in the \Models folder under your package folder.  You can change that to something else if you want.

When would you not need to include this?  There are three cases that I can think of:
1) You're using a texture that is in a different package.  I would recommend avoiding that if possible, just because it could get confusing.  However, if there's a cool texture in one of the Deus Ex packages that you want to use, go for it.
2) The import statement is in a different .uc file used by the same package.  I would tend to avoid this one too.
3) You want to set the mesh up for multi-skinning.  It's possible to leave out any associations to specific textures and create a generic mesh.  That's how all of the NPC's in Deus Ex are done.  There are only a handful of character meshes in Deus Ex, but each mesh can have different sets of "skins" (textures) that can be applied so that the same mesh looks like a different person.  For example, the AlexJacobson and BoatPerson characters both use the same mesh, but have different textures.  How to actually create a new NPC (or whatever) and assign skins is another topic; see the link below.

If you assign the same surface to multiple Groups (surfaces) in MilkShape, the .uc file it generates will have multiple TEXTURE IMPORT statements for the same .pcx file.  That's not what you want.  Remove any duplicate import statements.  You may need to rename some of the textures in the "TEXTURE=" part of the MESHMAP SETTEXTURE statements to use the name of the texture that you actually *are* importing.

Meshmap to Texture Associations (optional)

#exec MESHMAP SETTEXTURE MESHMAP=LaserGun NUM=1 TEXTURE=LaserGunTex1
#exec MESHMAP SETTEXTURE MESHMAP=LaserGun NUM=2 TEXTURE=LaserGunTex2
#exec MESHMAP SETTEXTURE MESHMAP=LaserGun NUM=3 TEXTURE=LaserGunTex1

Again, you'll almost always want to include these types of statements, unless you're creating a generic mesh.  These statements associate the various surfaces in your mesh with specific textures.  In MilkShape, you will get one of these for each Group you create.  Each Group will be a "surface" that is numbered 1 to whatever.  The "NUM=1" line says to associate the first surface with the LaserGunTex1 texture.  Note that you can refer to the same texture from multiple surfaces.  In this case, you'd only need to import LaserGunTex1 once, though.  Since the maximum number of surfaces allowed is 8, you would never have more than 8 of these statments per mesh.

Level-of-Detail setting (optional)

You may not realize this, but when you import a model, there is an automatic level-of-detail (LOD) feature which happens. Here's an example of that import statement for the GM_Trench character model, which actually *reduces* how aggressively to reduce polygons as the distance from the model increases:

#exec MESH LODPARAMS MESH=GM_Trench STRENGTH=0.5

Perhaps the Deus Ex developers found that character models distorted too much.  If you don't specify this line, the default ends up being STRENGTH=1.0.  For a lot more detail on LOD, see Epic Games' LOD tech notes.

Default Properties

defaultproperties
{
DrawType=DT_Mesh
Mesh=LaserGun
}

Don't worry about this too much.  Just replace "LaserGun" with the name of your mesh and you're good to go.

Remember to save your .uc file in the \Classes folder under your package folder and name it the same as the class.  The example would have been named LaserGun.uc.

5. Optional: Create another .uc file for importing a new "thing"

The topic of how to add stuff into Deus Ex that actually do things is covered elsewhere, but I'll briefly show you the basic idea.

Your mesh is just a 3D object with no interesting properties or behavior.  You'll typically want to use your mesh as a weapon, character, pickup item, or at least something you can interact with in some way.  The way to do that is by creating another .uc file that "expands" on an existing type of object, such as DeusExWeapon (for weapons), HumanCivilian (for civilian characters), DeusExPickup (for things that can be picked up and put into your inventory), or DeusExDecoration (for stuff like plants).  Each type of object that you can create (there are many), has a set of properties that you can set.  One of the properties is which mesh or meshes to use.  Some objects may have multiple meshes associated with them.  For instance, a weapon has a "first person" version of the mesh that includes JC's hand and part of his arm, as well as a "pickup" version that is used to show that weapon sitting on the ground.

Without going into a lot of detail, here's a short example to give you the idea.  The part in quotes after LodMesh would be the reference to your mesh (that was imported in another .uc file).

class Guitar extends DeusExDecoration;

defaultproperties
{
    bCanBeBase=True
    ItemName="Fender Stratocaster"
    Mesh=LodMesh'MyPackage.Guitar'
    CollisionRadius=18.790000
    CollisionHeight=6.750000
    Mass=10.000000
    Buoyancy=15.000000
}

6. Import it into the game!

When you have your .uc files, your .3d model files, and your .pcx texture files in place, you're ready to actually import your mesh into your package, so that it's ready to use in Deus Ex.  If you've ever compiled a package with "ucc make" then you already know how to do this step.  Delete your .u package file from the \DeusEx\System folder and in a command prompt (MS-DOS prompt) in the \DeusEx\System directory type in "ucc make".  If you've done everything right, your mesh is ready to go.  Fire up UnrealEd and enjoy.

Related topics:
How to organize multiple meshes/actors in your .uc files
Re-skinning generic meshes

Back to main page