Requirements

This document assumes that you already know the basics of modelling, texturing, and UV-Mapping objects in blender3d. There are a large number of tutorials, including video tutorials, out on the internet on how to create objects in blender, then texture them. Before an object can be made into a prefab the following needs to be there:

• A mesh object (or set of objects) that you'd like to turn into prefabs

• Each object must be UV-Mapped fully. Note that the more texture sharing, the better

• UV MAP TUTORIAL

• Another

• Each object must have an actual bitmap texture assigned to it in texture slot 0, material type 'texture' (Shown how later in this page)

• You can check to make sure its good by rendering it in blender3d's built in renderer. If it renders there, and you're sure that you're using a bitmap texture (not pre-generated) then it should be good. Note that blender happily accepts PSD files and many other popular formats without needing to turn them into BMPs first

• Note that one of the steps involves selecting what gets exported. So you can have all sorts of stuff in the BLEND file to help you make the final prefabs (cameras, etc) but only what you choose gets actually exported

• You can order the Prefab exporter to ignore an object by putting a dot (.) in its name. It automatically ignores all nonmeshes and noncurves.

Steps (each covered in more detail below)

• Name your objects appropriately

• Make sure textures are correctly set up. Also, Name your textures and materials appropriately

• Ensure object centers are appropriately placed

• Use the Materializer python script to auto-assign material types ("chrome, specular, diffuse, glowing, glass...") to the prefabs

• Create 2D Curve objects in blender to represent the collidable surface of the object (since all collisions are on the z=0 plane)

• Ensure that the curves are named appropriately

• Run the export script, choose an output folder, and press the Magic Button

• Run the prefab compiler on the resulting text files to turn them into Binary Hyperbol Prefab Files

• Edit the resulting mex file if you need to

• Export your textures and ensure they are in the right format (DDS or TGA)

Naming your objects appropriately

Generally, when prefabs are made, they are made in sets.

The entire set is in the same .BLEND blender3d file at once, so that textures can be shared easily. For the Magic Button export to work (which exports all objects in the entire blend file), your objects should be named appropriately. Appropriate names are suggested to be a set name, underscore, then a hint name. Keep it short. For example, if you're making things which look like scaffolding, and they plug into each other, and you have a middle piece, a corner, and a terminator piece, then perhaps name them scaf_mid scaf_corner and scaf_term. To name an object, you may as well name both its object and its mesh the same thing.

See the screenshot below:

In this screenshot, we have three prefabs.

The middle one, the straight piece, is selected. In the bottom area (links and materials) in the edit subtype, I have named it r1_straight1 Notice both mesh and object (ME and OB) are named the same thing. This is useful. I've also turned on show names (F7, its under the DRAW box, 'draw extra' 'name') Z for wireframe mode. As long as all of your objects are appropriately named, it can automagically export.

Ensuring textures are correct

For it to properly export, each mesh object you intend to export must have a texture bound to the first slot of its material. Objects can share materials, and have multiple materials (its the only way to use multiple textures on a single object). In the shading panel (F5) if you repeatedly hit F5 you will cycle through the options. With your object selected, make sure the material buttons are selected (red ball).

See the attached screenshot:

Note that in the screenshot, it shows:

• Each object should have a MATERIAL

• Each object's MATERIAL should be linked to the MESH, not the object

• Each material should be named without underscores or spaces and there should be quite a lot of extra room. (That will get used later, and will screw up if you use too much, so keep it like 8 or so letters at most)

• Each MATERIAL should have a TEXTURE in slot zero

• Each TEXTURES input map should be UV

• Nothing else matters to the exporter. You can tweak the shininess and chromeness who cares, it does not matter, it is not exported

• It is not recommended that you do anything except a plain diffuse texture map that looks normal (no shiny or anything) and ensure it renders. Later we will use the Materializer to automaticaly choose an appropriate shader and that will alter the material to look somewhat like it does in game. (Adding shininess etc as appropriate) so don't bother.

If you go into the textures subpanel you see this:

In this screen shot note that

• texture type is IMAGE

• The texture is appropriately named

• The other crap doesnt matter to the exporter

Ensuring object centers are appropriately placed

When you put prefabs down in the map editor, their centerpoint will be placed on the floor, and they will rotate around that center point. You should use this to make it as easy as possible for yourself when it comes time to actually place them. This means that the centerpoint (pink dot in blender3d) should be at z=0 in blender, and in a good place for rotating the object around.

• Click around to move the 3d cursor to where you want the center of the object to be. Use the side view and the top view.

• Shift-S to snap it to grid or to center it on an object (cursor->grid)

• Make sure that its at z=0. You can use the 'view properties' item in the view menu of the 3d window to show you where the 3d cursor is. Z should be zero.

• Use 'Center cursor' in the edit menu with your obejct selected, to move its center (without moving the object) to the cursor

Using Hyperbol Material Toolkit

ITS INCREDIBLY IMPORTANT THAT YOU HAVE ALREADY ASSIGNED A REAL DIFFUSE MATERIAL WITH TEXTURE TO ALL YOUR OBJECTS BEFORE YOU DO THIS ITS ALSO HIGHLY RECOMMENDED THAT YOU SAVE A BACKUP BEFORE YOU DO THIS AS IT ALTERS THE MESH.

If installed correctly (to your python scripts folder) materializer should appear automatically in edit mode (TAB) under python

The Material Toolkit window appears

In edit mode, simply select faces that you'd like to use a particular shader, and then click the shader name. Most shaders work fine but your workhorse shaders are going to be CHROME, FULLBRIGHT, SPECULAR, CHROME - OVERLAY PULSING, etc. Glass and stuff is tricky Note that overlay type textures will require two textures in the end - one named (texturename).dds and another named (texturename)_over.dds for the glowing overlay on top. Here in the screenshot, I select a bunch of faces (face mode must be used) and then click SPECULAR to give them that 'shiny when they glint in the light' look. They turn yellow in edit mode to indicate what type of shader they use. They will not look yellow in game. ITs just an edit mode indication.

Its highly recommended that you start by selecting all objects and all faces and clicking 'Diffuse' to create a good baseline, uniformly, then selecting just the specially shaded faces

• Each additional material you add to the same object greatly increases its rendering cost.

• Polygons are not nearly as important as textures and number of materials

• This cost can be reduced greatly by having many touching prefabs share the same material and texture. The map compilation process automatically makes optimized sets out of prefabs that share material and texture.

Create Collision Curves for the objects.

For an object to be collidable, it needs collision curves. These are blender Curves set to vector mode, on the 2d plane, named the same as the object but ending with '_coll'.

Here we have our object, again. I'm going to top view, wireframe mode, object mode (not edit mode, tab).

I'm going to center the cursor on the object (SHIFT+S) cursor to selection. Then I'm going to move it a little out of the way and SHIFT+S Cursor to grid so that its not quite on the same center as the object. Then I'm going to press SPACE, and choose "add -> curve -> bezier curve"

It creates a bezier curve for me at the cursor. It automatically selects it and enters 'edit mode' (tab). I'm going to change it into a polygonal curve by clicking the POLY button at the bottom.

Now I rename the object to the same name as the object, but with _coll at the end.This is very important as it is the signal to the magic button that these objects are related.

Now, back to the actual curve. Just like always in blender, adding vertices is easy.

Shift click (might take a middle or right click depending on your settings) with an endpoint selected and vertices are added.

Click to select and delete button to delete.

A nice trick, if you have grid, is to select as many verts as you want and press (SHIFT+S) Selected To grid to auto align all selected objects with the grid!

The idea here is to keep the vertices at Z=0 but to use this 2d line to represent the edge of the object, where it will be collidable.

For example, this prefab

Has the following collision line

Notice that only the edges with polygons are important. Do not use the 'close tool'(c button in edit mode) to close an edge - those are ignored. For closed shapes, simply close the shape by putting a last vert on the first vert. Ships and other projectiles will only collide with these lines, so its a good idea to ensure that they are closed when the object they represent is.

Objects (or pieces) that ships will never reach need not have collision lines at all.

Its also good for performance to keep the number of collision lines low, so feel free to approximate curves with much fewer lines. Each collision line set can contain any number of blender3d curves. So an object can have several unconnected curves forming its collision line. simply make a bunch of curve objects, then select them all and choose join (CTRL+J). Remember to rename the resulting object to the same name as the object it represents, but with _coll

Run the exporter

Each of your objects now has a texture, has a name, and has a collision line set with the correct name. Time to automatically export using the Magic Button!

In OBJECT MODE, select the python script "Hyperbol Prefab Tool" from the scripts menu.

The prefab tool will appear.

The prefab tool lets you specify the parts you want to export. There should only be three settings you're interested in here... the MAGIC BUTTON, the scale, and the export path

First things first - choose an export path. Click on the Export to button and choose a destination .PFB file (type one in if necessary)

Note that when using the Magic Button to export, all meshes that have no period (.) in their name are automatically exported whether selected as geometry or not. Selection is ignored - in fact, it will auto select everything as it seems fit. So make sure that your meshes are named, and that stuff you dont want exported has a dot in its name! (both mesh and object name).

Once the export path is selected, all you need to do is click "Magic Button" and it will do everything for you. It might take some time. It will highlight each one as it does it, so zoom out and look from the top before you start. You will end up with PFB files in the folder you specified (the filename in the box is ignored - the files will be named based on the name of the object). Those PFBs can be fed to the prefab compiler.

Run the prefab compiler on your object

Hard way:

• Go to the folder that you exported your files in

• use a CMD box (start->run->cmd.exe)

• execute the following statement on each of the exported files

• makeprefab b name.pfb

• (Where name.pfb) is the name of the prefab

• for example, "makeprefab b test_corner.pfb"

Easy (?) way

• Associate PFB files with makeprefab.exe (by going to tools, file types in explorer, and creating a new PFB file type, associating it with "makeprefab b %1"

• Edit the file types in windows explorer to add the 'b' in front of makeprefab

Now whenever you double click on any PFB file it will automatically compile it. You can select entire groups of pfbs and it will automatically compile for you

This will output a PF2 and a MEX file. At this point you can already take the PF2 and MEX files, and place them in your maps folder (or elsewhere). If you refer to them in the map editor, they will load. (But will probably be missing textures!)

Making the textures right (and editing the mex file)

Open up the MEX file in notepad or whatever.

The MEX (Model EXtra) file tells the game what shader to use, and what textures to feed that shader.

• Anything that uses OVERLAY or PULSING OVERLAY is going to need two textures.

In the picture above, notice that the "Stretch stand" takes two textures for one of its different shaders. It has 3 shaders. Chrome and Specular does not need a second texture. But OVERLAYPULSE needs another overlaid texture (with alpha) that it renders on top of the underlying texture, glowing and pulsing. So for that texture, its specifying that it should use (imagename)_OVER.dds as the overlay.

Note that the _OVER.dds is automatically created for you, as is the DDS extension. it is assumed that your exports will be DDS - but you can manually edit the file to be tga.

For example, if you intend to include your PF2 and MEX's and textures inside your map folder, you should probably change the relative path of your textures in the MEX file from data/textures/prefabs to data/maps/mapname_v1/texture.dds (or tga).

Textures should be in TGA format or DDS format. If using DDS, please use DXT5 (for alpha) or DXT1 (for nonalpha) orR8G8B8A8 or R8G8B8 only.

DDS is probably the best, but TGA if you can't find a DDS tool. DDS tools are available for photoshop and the Gimp, you can get them straight from nVidia for the former.

All done.

Just make sure that your pf2 and mex files are in the right place, then in the map editor, put a prefab down (any prefab).

Change its MEX and PF2 paths to the relative path to your prefab, and you're done!

Remember, the path to your map folder is probably data/maps/(your-map-name) - so your prefabs could be in data/maps/(your-map-name)/myprefab.pf2

If your pf2 and mex files are correct, and the textures inside them are correctly pointed at it should all Just Work.

As an added bonus, if you're using the auto-packaging feature of the map editor, and you keep your resources inside your map folder, they will automatically be included in the packaging. (This is highly recommended). In other words, the result HBC file from autopack will include the necessary prefabs and textures as long as you keep them all in the map folder. (WAV and OGG are also autopacked)