GTA Import/Export Tool Script Tutorial by Hollower
Contents •
Introduction
•
Quick Start
•
•
•
Customizing The Interface
•
Running The Script
Importing •
File Selection
•
Options
•
Objects
•
Materials
•
Textures
•
Hierarchy
•
Vertex Groups
•
Skeleton
Exporting •
The Basics
•
Creating New Models
•
•
•
Hierarchy & Objects
•
Geometry
•
Materials
•
Textures
•
Prelighting
Skeletal Models •
Setting Up The Framework
•
Vertex Groups
•
Exporting and the Bone Patch file
Conclusion
Introduction This is a tutorial for using the GTA Import/Export Tool python script in Blender . This tutorial does not cover how to use Blender itself. I have included a lot of detail to make it as newbie newb ie friendly as possible, but if you are new to Blender you will definately need to spend a significant amount of time reading other tutorials and making simple test creations before you even think about think about diving into your GTA modding plans. The place to start is the documentation at blender.org at blender.org and the tutorials at Blender3D.org Blender3D.org.. Visit the following forums for community help. Please be sure to read pinned topics and search before asking questions. elYsiun - for Blender discussion
Quick Start Customizing The Interface At the top of the main Blender screen you should see a drop-down menu (SCR:) with a list of screens you can choose from. These are different window layouts for various purposes. You can create your own, and I recommend creating a screen with a Text window for loading scripts. Go to File->Save Default Settings to keep your changes. Note: New in Blender 2.32 is a 'Script' window which may cause confusion. The 'Text Editor' window is actually where scripts are loaded. It automatically turns into a 'Script' window when running, and back to 'Text Editor' when stopped.
Here we have a text panel for the script. The text panel has it's own menu bar (at the bottom by default).
Running The Script Go to File->Open and open GTA_IE_01b.py Note: It is important to know that ".blend" files contain everything from your Blender session; not only scene data, but also loaded scripts. If you have a new version of the script but open an old blend file, you may find yourself accidentally using an older version. If in doubt reopen the script.
Now that the script is loaded you can run it ( File->Run Python Script or ALT-P within text window).
This is the running script interface. If it isn't completely displayed you can adjust the borders of the window.
Importing File Selection To import a model either type the path in the Filename box or press the Browse button and choose one that way. If you browse, the Texture Path will be automatically filled in with the same location. Textures must be in BMP format. Alpha layers must be a s seperate BMP files. Currently the importer cannot use TGA files. The file names should be the same as they were in the TXD archive.
Options Under the import button there are two toggle buttons. When a toggle button is down the feature is enabled. When it is up the feature is disabled. The 'msplit' option is for compatability with DFFs exported by ZModeler . Importing is much faster with it disabled, but if the materials appear to be assigned incorrectly try with it enabled. In theory it will only be
Warning: The higher the polygon count, the slower this option becomes. I've had some custom models take so long that Windows decided Blender had frozen. I'm attempting to fix this but perhaps take it as a sign that the poly count is too high for the game anyway. The 'bpatch' option is for skeletal models (player/ped). In these files there is a section of skeleton data that cannot be imported yet. The data describes the size and shape of the bones. When this button is enabled, upon import the bone data will be extracted and saved in a file with the same name as the DFF with the extension ".bp". The exporter can use this file to reinsert the data. Press the import button to begin importation. Watch the status window for messages. If all goes well you should see the model appear in the 3D window. Warning: Do not import more than one DFF in the same session, as this can cause n ame conflicts. Deleting the objects is not enough because the materials and textures are still loaded. Always start fresh using File>New (CTRL-X).
Locating Everything Objects
The importer organizes objects into layers for convenience. You can enable a layer by clicking it or multiple layers with shift-click. You can move an object to another layer(s) by selecting it and pressing M. "_dam" (damaged) objects go to layer 2. "_vlo" (low detail) objects go to layer 3. "_L1"-"_L4" (damage or variations) objects go to layers 2-5. Dummies go to layer 5. All other objects stay in the first layer.
Materials
Currently every mesh gets a unique set of materials, even if they are completely identical to materials on other meshes. You can share materials on your own models for export. Warning: Blender has a hard-coded limit of 16 materials per mesh. Some of the game models exceed this. Materials after 16 will be ignored and you'll see a message in the status window about it.
Textures
Textures are mapped to a material via this panel:
The color map (regular texture) will go in the first slot. The alpha map, if any, will go in the second slot. The reflection map, if any, will go in the third slot. Reflection maps are loaded but not enabled because Blender requires a special format. The only way to know what it looks like in the game is to view it in the game. Currently the mixing mode cannot be set by the script. The default is 'Mix'. For alphas to look correct when rendered in Blender they should be set to 'Mul'. This only effects rendering.
Hierarchy
Blender doesn't have a traditional hierarchy browser. You can see the objects with connections in the OOPS window, but it isn't pretty...
In the 3D window parent/child attachments are shown as dotted lines and children turn white when moving with the parent. A proper hierarchy viewer is planned for a future version of this script.
Vertex Groups
If you import a skeletal model, the vertex groups can be found in this panel.
Skeleton
There is currently no way to import skeletons. I have made one that matches the proportions of the default player.dff model. To use it go to File->Append... and select the TommySkeleton.blend file, then 'Object' , then 'TommySkeleton' , then press the 'Load Library' button. To attach the skeleton make it parent of the player model object 'Root_mesh' (select both, selecting the skeleton last, then CTRL-P).
Select "Use Armature"
Select "Don't Create Groups". Assuming the vertex groups were properly imported, that is all that is needed to rig the default player model for use within Blender. See the Exporting section for instructions on rigging a custom model.
Exporting The Basics First I will cover just straight exporting as if the only thing done was an import and then export with no modification. Please do not skip to this part without having read the section on importing! To export a model you must first select the base of the hierarchy.
For vehicles it is usually a dummy with the name of the vehicle, at the center. For world and human models the mesh is usually the base. You will probably get a n error message if you didn't select the right thing. Fill in the Filename box. If a file by that name already exists, the new filename will have a number appended to it. Next choose the type of object this is to be in the game.
The drop-menu gives you a selection to choose from. The four flags below are set automatically for the type of model you choose. They are there for advanced modders who wish to experiment with non-standard settings (some combinations can crash the game). Press the export button and watch the status window for messages.
Creating New Models This part will cover how to setup your custom models properly for exporting. It will not teach how to model . There are plenty of Blender tutorials for that.
Hierarchy & Objects
When making your models great care must be taken to match the same basic structure as the original model or model type it is going to be used as. The object names and hierarchy must matchexactly. The script does not enforce this, so even if you recieve no error messages you can easily export an invalid file. This makes
You will use the following commands for building the hierarchy. Blender has two ways of parenting; with or without inverse. For this script you should always use without inverse. This means the parent object's origin will become the new base (0,0,0) of the child. CTRL-SHIFT-P
"Make Parent (without inverse)"
Makes the active object parent of selected objects
ALT-P
"Clear Parent"
Clears the active object from its parent
When naming an object use the OB field, not the ME field. ME is for the name of the mesh data, which this script ignores.
Sometimes something will look right in Blender but in the game it will be rotated or positioned wrong. The following commands may help resolve these type of orientation problems. CTRL-A
"Apply Size/Rot"
This basically "saves" the current scale/rotation of an object, making it the new base (1,1,1)/(0,0,0)
CTRL-C
"Copy Attributes"
Choose "Location" to move the selected object to the exact location of the active object. Great for aligning things.
ALT-R
"Clear Rotation"
Resets the rotation back to (0,0,0)
ALT-G
"Clear Location"
Resets the location back to (0,0,0)
Note: What most GTA modelers know of as "dummies" are called "empties" in Blender. Other than that they work the same as you're used to.
Geometry
All faces of a mesh must be triangles. CTRL-T
In edit mode, converts selected faces to triangles.
Normals are important for correct lighting and reflections. They tell what the angle (perpendicular) of a face is.
CTRL-N
"Recalculate normals outside"
Automatically calculate normals for selected faces (in edit mode)
The automatic calculation isn't always perfect, so if you see any of the blue lines pointing the wrong way select the face and press flip normals. Sometimes it helps to select only the portion of the model that is wrong and recalculate.
Materials
There are a lot of material settings in Blender, but the exporter only uses a few of them.
RGBA and Spec are used for all. Ref is used if the material has a reflection map. To enable primary car color on a material set the RGB colors exactly:
To enable secondary car color on a material set the RGB colors exactly:
Textures
Working with textures and UV mapping is a complicated subject well outside the scope of this tutorial. Here are some links to get you started... UVMapping Tutorial
To simplify things, the exporter makes the following assumptions: •
•
•
•
Any texture in the first slot is a color map (diffuse texture) Any texture in the second slot is an alpha map Any texture in the third slot is a reflection map, or... If the texture in the third slot is mapped to 'Nor' it is a bump map
It's up to you to create a proper TXD file. The texture name is the file name, not including extension. It doesn't matter what you name the texture within Blender, the file name is what will be referenced. Note: Bump maps are still experimental. Don't overuse as there is a noticeable performance drop in-game when bump mapped objects are visible. In my testing I could only get it to work on world models. Ref (reflectivity) is used to set the bump depth because the Nor slider can't be read by the script. In the TXD the bump map texture must have the same dimensions and color depth as the texture it overlays.
Prelighting
Prelighting is a method of using vertex colors to simulate light and shadow.
On all materials enable VCol_Light. Add lamps to the scene, arrange how you want the model to be lit, select the mesh, then press the VertCol Make button. Delete the lights or move them to another layer if you want to render a prelit object, otherwise the brightness will be doubled for obvious reasons.
You can also paint vertex colors by hand with Vertex Paint mode. It takes practice to make it look good, but the difference is well worth it!
Naturally, prelighting will only be exported if the prelit flag is enabled.
Skeletal Models Vice City's skeletal models are the most challenging to work with. They have long been impossible to create. I will try to cover all of the important details, but don't expect to just dive into it without a lot of prior experience in Blender.
Setting Up The Framework
The first thing you'll want to do is import the default player.dff model from the game and study how everything is arranged. Notice how the dummies (layer 5) are rotated 90 degrees from where you would expect them to be. Leave them where they are. Since skeletons cannot be imported in this version, I have included one I made from scratch. Note: in Blender skeletons are called "armatures". Go to File->Append... and select the TommySkeleton.blend file, then 'Object' , then 'TommySkeleton' . Then press the 'Load Library' button.
This armature matches player.dff . It will need to be modified to match most other models.
You can now delete the mesh 'Root_mesh' . If you want to keep it as a reference just move it to another
reused. At this point everything is ready for you to create (or import) your custom model. For it to be usable as a player model it must have only one material mapped to a texture named player.bmp. Name the object 'Root_mesh' . (if you kept the old one now is the time to delete it) Select both layers 1 and 5 so that the original dummies are visible. Make the mesh 'Root_mesh' parent of the dummy named 'Root' . Next make the armature 'TommySkeleton' parent of the mesh 'Root_mesh' .
"Use Armature".
"Name Groups".
Vertex Groups
Unlike models imported from the game, your custom model doesn't have any vertices assigned to groups yet. You can choose "Create From Closest Bones" for automatic skinning, but it is rarely a good fit. I would only use that method for a quick test. Otherwise, choose "Name Groups". It will create empty groups na med for the bones to which you can assign vertices.
These are the buttons you'll be working with. They will appear when you enter mesh edit mode. Enter edit mode and make sure no verts are selected. Select a group of verts corrosponding to an underlying bone (B,LMB-drag for box or B,B,LMB for circle). Then select (SHIFT-RMB) or deselect (B,B,MMB) individual verts to define the precise area.
Press 'Assign' to add the selected verts to the selected group. A single vertex can belong to up to 4 groups. In theory there should only be overlap near the joints. Do not assign any verts to 'Root'. You probably wondered what that 'Weight' field is for. This value effects how strongly the vertex is "pulled" by the bone. At 1.0 it will move in perfect unison. Use smaller numbers for those joint verts that belong to more than one group. Ideally (not required) the sum of the weights of one vertex should equal 1.0. So a vertex that is equally influenced by two bones should be assigned with a weight of 0.5 to each group. You can also use the "Weight Paint" mode. It works like vertex paint, and does both assigning and weighting.
It seems like a more intuitive approach but I have found it difficult to work with. You can't see the vertices so it's easy to miss the mark. Give it a try. I have had the best results by assigning at 1.0 with the selection method and then using weight paint to carefully tweak the joint areas. It is also v ery helpful to study the original game models in weight paint mode.
Exporting and the Bone Patch File
If you have made it this far you are a dedicated modder and I salute you! If you read the section on importing you might remember something about extracting some important bone data to a .bp file. Well, this is where that file comes back into play. Copy the file to the same folder you will be exporting to, and rename it to match the name of the dff file. For example if you are exporting "C:\temp\myplayer.dff", the bone patch file should be "C:\temp\myplayer.bp". If it can't find the file it will print an error message and the dff will still be exported corrupt. If everything went smoothly you should be able to import the model into the game and see how well the skin fits. It will probably need some tweaking. Try to view the model in as many animations/poses as you can, holding all weapons, driving all vehicles, e tc.
Conclusion I hope you found these instructions helpful. Believe it or not this is my first Blender script, and my first tutorial. I plan to continue improving the script to fix bugs and introduce new features. When new versions of Blender come out, old versions of the script will likely become unstable or unusable with them when they change the scripting API. Visit my home page to get the latest updates.
© Copyright 2004 Stephen Orning. All rights reserved.
