A Guide To: Model Bundles

Introduction:

Mafia: Toolkit uses a system called "Model Bundles". This enables users to import/export one or more objects at once, instead of having to manage each individual asset. This file (.mtb) can then be converted to and from the FBX format using "M2FBX". The toolkit handles conversions between MTB and FBX. These 'Model Bundles' provide a massive advantage of its predecessor; it allows multiple object import and export, automatic assignment of frame types, includes collisions in the import process, automatic construction of new materials, as well as an import window to tweak values before the importing process is complete. However, this introduces a new level of complexity when dealing with models. This guide will explain how to use Model Bundles. Please also try to export a Bundle using the Toolkit. It will help you with this process by allowing you to look through the structure, and understand the setup which the Toolkit expects.

The Structure:

Once you understand the structure of a Model Bundle it becomes relatively straightforward. The idea behind the bundle is to have a "dummy", which is essentially a Mafia "Frame". It contains the world position and rotation and what type it should be stored as. Since each "Frame" type has a different type of data, (eg. A Mesh requires 1 to 3 LODs, but an Area requires a bounding box), each dummy should have a suffix such as [MESH] or [DUMY]. Please see the picture below for a working example:

Here is an example. You want to create a new frame which consists of a static mesh. The new mesh wants to be called "My_New_Mesh". Since we also want it to be a static mesh, we also need add [MESH] to the name of the dummy. This will help my tools understand how to convert this dummy (and its children) into a FrameObjectMesh. When dealing with a mesh, the model itself needs to have "LOD" in the name. The Toolkit expects the most detailed mesh first, following the 2nd detailed and then finally the least detailed - the lowest quality mesh. The 2nd and 3rd quality mesh are entirely optional.

At the moment, the tool can only import the following types using the Model Bundle system. More will be introduced in future updates. FrameObjectDummy does not require any extra data.

| Frame Type       | Suffix |
|------------------|--------|
| FrameObjectMesh  | [MESH] |
| FrameObjectDummy | [DUMY] |

Setting up a Static Mesh:

The mesh system follows the predecessor. All models need to be triangulated, have atleast one material, the size needs to be below 16384 on all axis and the indices count needs to be below 65535. To calculate this number, divide the number of triangles by 3. Since the game compresses the vertex information, it is absolutely essential that the models are kept small. The smaller the mesh, the better the model will look ingame. This is extremely important for terrain meshes. If the model is too large, then you may notice 'seams' in game. This is because the model is too big, and due to compression, the model has lost a major amount of quality.

For enabling different vertex information in the Mafia II engine, modellers are required to rename their UV Maps and Vertex Colour Maps so M2FBX can acknowledge them and allow the Map Editor to use the available data and save correctly. The table below details the available attributes used by Mafia II. Even though this data is present, the assigned material may need to be modified to use the attribute data. All models require Diffuse Mapping.

Vertex Attribute	Required Name	Uses	Supported
Diffuse Mapping	DiffuseUV	For Material Mapping	Yes
UV0 Mapping	UV0	Unknown; Cars Maybe?	Yes
UV1 Mapping	UV1	Unknown; Cars Maybe?	Yes
OM/AO Mapping	OMUV	Used for the OM/AO Maps assigned to SingleMeshes	Yes
Vertex Colour 0 Mapping	ColorMap0	Unknown; Used for Trees	Yes
Vertex Colour 1 Mapping	ColorMap1	Unknown; Used for Trees	Yes
Bounding Box Coefficients	???	Unknown; Used for Trees	No
Damage Groups	???	CrashObjects/Destructibles	No
Blend/Bone Data	???	Pedestrians, Cars and Weapons	No

When setting up materials, no textures need to be assigned. Just the name of the material (which can be found in defaultXX.mtl) and the selected faces on the model. If this data is not present, then M2FBX will struggle to convert the model for the Map Editor to use. The Model Bundle system has the ability to create basic materials if required.

Tips When Exporting a Bundle to FBX:

Since the conversion between FBX is terrible, you may notice that Blender may make all objects small. Check the scale of the dummies (or models!). Make sure the scales X, Y and Z are set to 1 on all axis. Otherwise you may notice the models being too small ingame. Make sure all models are triangulated.

Importing a Bundle:

With this new model system, a new way of importing models into the Toolkit has been vastly improved. It has been improved to make aware what is going to be imported and allow users to weak the properties to their liking. Here is a quick breakdown of each button, tabs and UI elements: The "Validate" button runs through the entire bundle and checks for errors. The "Continue" button should be pressed when the user is happy with the import options. Finally, the "Stop" button should be pressed if they are not happy with the bundle, and want to stop the import process. The tree view on the left side has two tabs. One for the Models (Also known as the Frames), with the other one being Materials. The first tab includes all the objects we expect to import and convert to frames. This should include all the nodes seen in the bundle the user exported, as well as a "tick" or "cross" to identify which objects are currently broken. On the right side of the window, we have the object data. This allows the user to view the settings for each object. The properties in this UI element vary - some objects have a name, position and a rotation, whereas other object types, such as a Mesh, has which types of "vertex types" we are expecting to import. It also includes what materials we expect to be used on the mesh. Finally, the bottom part of the window is for information and debugging the conversion. The first tab, "Validation Messages" includes all the errors / warnings found when validating the bundle. The second tab, "Import Messages" includes the debugging log for the conversion process between FBX and MTB.