IGB_Blender Map Conversion Tutorial (XML2 / MUA)

[Kaiko]

IGB_Blender Map Conversion Tutorial (XML2 / MUA)

This tutorial explains how to convert a map into a playable XML2 or Marvel Ultimate Alliance map using the IGB_Blender plugin.

In this example we convert a Doom Castle map from MFF, but the same process works for most maps.

Tutorial Video - https://www.youtube.com/watch?v=wtjmEbYA8W8
Requirements

• Blender installed
• IGB_Blender plugin
• PySide6 installed through the plugin
• XML2 or MUA game files

Step 1 - Open Blender and Install the Plugin

• Open Blender
• Install the IGB_Blender plugin
• Open the IGB Extras panel
• Install PySide6
• Restart Blender

Step 2 - Import the Map

Import the map you want to convert. In this tutorial we use a Doom Castle map from MFF.

After importing the map you may see objects called empties. These are not needed for this process.

• Select only the empty objects
• Delete them

Be careful not to delete mesh objects.


Step 3 - Fix Orientation and Scale

Most imported maps will not be correctly oriented or scaled.

• Rotate the mesh so it is upright
• Scale the map to match the game's scale

A good way to judge scale is by importing another map from the game or importing a character model for comparison.


Step 4 - Clean the Map

Delete anything from the map that you do not want included.

• Remove unwanted objects
• Select everything
• Apply transforms

Ctrl + A → Apply Transform

Step 4.5 - Material Setup

Before continuing it is recommended to convert all materials to the IGB material format.

• Open the IGB tab
• Go to the Materials section
• Click Convert All to IGB

This converts all scene materials so they are compatible with the IGB exporter.

After converting materials you can edit them using the Quick Tools section in the IGB tab.

• Edit all materials
• Edit only selected materials

It is usually best to do material setup before combining the mesh, but materials can also be edited later using Blender's Materials tab. The Materials tab also includes an IGB section for adjusting exporter settings.

It is also recommended to pack textures into the Blender file. This helps prevent missing textures if the project is moved to another computer.


Step 5 - Map Maker Setup

Open the Map Maker tab under the Scene panel.

Fill in the following fields:

• Game Data Directory
• Output Directory
• Map Name
• Map Path

You can also configure the party light tint. For testing a radius of around 10000 is recommended.


Step 6 - Place the Player Start

Click somewhere in the scene where you want the player to spawn.

• Go to Entity Definitions
• Create a new entity named

  Player_Start

• Set the class to

  Player Start

• Click Place Entity

This places the Player Start in the scene.

The X axis determines the direction the player will face.


Step 7 - Add an Extraction Point

You can add an Extraction Point manually, but the plugin provides a faster option.

• Open the Quick Add section
• Select Extraction Point
• Place it in the scene

Step 8 - Combine the Map Mesh

Before creating collision the map mesh should be combined.

• Select all mesh objects in the map
• Press Ctrl + J

This joins the meshes into one object.

This step is very important.


Step 9 - Create Collision

Generating collision from the full mesh is not recommended because it can create very large files and cause crashes.

Instead create simple collision manually.

• Open the IGB Tools tab
• Go to the Collision section
• Click Create Colliders Collection

This creates a collection used for collision meshes.

• Add a plane to the collection
• Scale it</li>
  

[li]Use Edit Mode to shape it</li>
[/li][/list]

Keep collision meshes simple.


Step 10 - Generate the NavMesh

Once collision is ready you can generate the navigation mesh.

• Select the collider mesh
• Go to Map Maker → Build</li>
  
• Click Generate NavMesh

Recommended settings:

• Cell Size around 40 for most maps
• 25 for tighter corners

Smaller cell sizes increase the number of navigation cells and may crash Blender on large maps.


Step 11 - Build the Map Files

In the Build section open Compile & Deploy and press:

Build All

This generates the required files:

• ENGB
• NAVB
• BOYB
• CHRB
• PKGB

Wait until the message

Build complete

appears.


Step 12 - Export the IGB

Open the IGB Tools tab and click Export IGB.

Navigate to the folder where the compiled files were created.

Example:

Maps/Kaiko/Doomcastle

Make sure the exported IGB file name matches the other map files.

Recommended settings:

• Texture Format: CLUT
• Collision Source: Colliders Collection
• Surface Type: 0

Now export the IGB.


Step 13 - Load the Map in the Game

Open the file:

Scripts/menus/new_game.py

Comment out the intro commands and add:

loadMapChooseTeam("kaiko/raid_shibuya/raid_shibuya")

Example:

#startMovie("cine01","waitSignal")
#waitsignal("waitSignal")

loadMapChooseTeam("kaiko/raid_shibuya/raid_shibuya")

Step 14 - Launch the Game

Start the game and the map should load directly.

You should now be able to explore the converted map.


Common Problems

IGB write failed: ushort format requires 0 <= number <= 65535

This usually means the mesh data is too large.

Possible causes:

• The map mesh was not combined using Ctrl + J
• The mesh is extremely high poly
• The mesh is very far from the world origin

Try reducing polygon count or simplifying the mesh.

Map Size Limits

The Alchemy engine used by XML2 and MUA does not handle very large maps well.

• Try to keep maps under 100 MB
• Around 70–75 MB is usually the safe range

Reducing geometry or texture sizes can help keep the map within limits.