mdl export issues

[vurt 118]

A crapshoot for sure, but any expert here when it comes to .mdl export? its very complex and difficult since there really are no guides that i have found, but i do know some things from googling, making chatGPT sweep the internet and summarize and just testing. 

Just editing a current working .mdl and exporting it is super easy and always works, but if you try to export e.g a imported model of another format (e.g a morrowind .nif or whatever) or probably if you create a new mesh in blender, then things gets very complex and you will end up with nothing exported because some requirement wasn't met (yet this is never reported, so impossible to know where it failed). 

Here is a summary that me and chatgpt pretty much has come up with after many, many hours. (script fix = i am trying to make a script that will just auto fix these issues).
But this is not nearly enough to make an export work. What else is needed for a proper export is unknown to me. It would be cool to create a script that fixes all these things automatically... So if someone has any insight apart from below (some stuff there can absolutely be wrong btw, dont trust it lol), please let me know.

 

1. Root node setup

KOTOR expects one root node with the same name as the exported model (e.g., Tree01 → root object Tree01).

All geometry, emitters, lights, etc. must be parented under this root.

Blender’s scene often has multiple roots or collections — the script creates a single proper root and re-parents everything under it.

✅ Script fix: Creates a root node (if missing) and re-parents all meshes to it.

 

2. Trimesh (geometry) hierarchy

Every visible mesh in KOTOR MDL must be a Trimesh node, not a generic object.

Parent-child order matters:
root → trimesh → (possibly more trimeshes)

Meshes cannot be children of empty collections, lights, or non-trimesh objects.

✅ Script fix: Finds all visible mesh objects and ensures they’re parented correctly to the root (or another trimesh if hierarchical).

 

3. Transformation and coordinate resets

KOTOR uses Y-up, Blender is Z-up.

Negative scale or unapplied transforms cause flipped normals or inverted export.

MDL exporter needs applied transforms and consistent orientation.

✅ Script fix: Applies scale/rotation transforms so geometry exports cleanly.

 

4. Material & texture linking

KOTOR MDL doesn’t read Blender’s Principled BSDF setup.

It expects a simple diffuse texture link — typically .tga or .tpc.

Export fails or uses wrong texture if:

Multiple nodes are connected,

Material uses unsupported shaders,

Texture isn’t named properly.

✅ Script fix: Rebuilds simple material slot linking so the exporter recognizes texture assignments (Diffuse → TGA/TPC filename).

 

5. Naming compliance

No spaces or illegal characters in node names.

Exporter crashes or renames objects automatically otherwise.

✅ Script fix: Sanitizes names to comply with MDL naming conventions.

 

6. Lightmap / secondary UV disabling

KOTOR MDL doesn’t use Blender’s secondary UV maps or lightmap channels.

Keeping them can confuse the exporter or result in invalid tangents.

✅ Script fix: Strips or ignores unused UV sets to prevent broken exports.

 

7. Empty / collection cleanup

Unused empties or nested collections confuse the hierarchy parser.

Each geometry must have a direct lineage to the root, not via hidden empties.

✅ Script fix: Flattens collections, removes orphan empties, and preserves a clean, linear hierarchy.

 

8. Consistent object origin (pivot)

MDL pivot points define animation centers and attachment positions.

If the Blender origin is offset (common after import), animations or rotations look wrong.

✅ Script fix: Re-centers or aligns origins as per parent hierarchy.

 

9. Quaternion-based rotations

KotOR’s .MDL format uses quaternion-based rotations internally (not Euler).
If a Blender object’s transform stack or animation data includes:

• non-applied rotation,

• Euler keyframes, or

• mismatched rotation modes,

the KotOR exporter (specifically io_scene_kotor) often silently fails or exports a file missing key node data — i.e. the .MDL will be 0 bytes or crash the game.

 

10. Export sanity checks

Before letting you export, the script verifies:

There is exactly one root.

All meshes are children of valid MDL nodes.

There are no unlinked materials or images.

Scene hierarchy is valid for MDL tree structure.

 

 

[DarthParametric 3,900]

12 minutes ago, vurt said:

one root node

More correctly, this is the OdysseyBase.

13 minutes ago, vurt said:

Meshes cannot be children of empty collections, lights, or non-trimesh objects

Incorrect. Meshes can indeed be child objects of null/dummy/empty objects. Indeed, this is actually a requirement in some cases. Specifically, what is known as the "A node". This applies to level models where any animated mesh must be the child of a null/dummy that is named the same as the OdysseyBase with "a" appended to the end.

16 minutes ago, vurt said:

It expects a simple diffuse texture link — typically .tga or .tpc.

Except in the case of walkmeshes, which use the walkmesh multi-material, not a usual texture reference.

17 minutes ago, vurt said:

KOTOR MDL doesn’t use Blender’s secondary UV maps or lightmap channels.

I'm not sure how Blender handles UV channels, but lightmapped level models absolutely require a second UV channel for the lightmap UVs.

 

One thing you have missed is that each node requires a unique ID. This is important for character models because bone ID must match the equivalent ID in the supermodel hierarchy. The KMax/MDLEdit workflow gets around this by loading the target supermodel to map the nodes where needed, but KBlender compiles to a binary directly so requires they be set in the editor. I recall I was playing around with an automated mapping script at some point. I know I talked to seedhartha at some point about adding it. Not sure what became of that.

[vurt 118]

That is good to know! My meshes will basically just be trunk and leaves. i do have a working .mdl for this that we try to work from, looking at why this mesh can be exported successfully and others can not. This working .mdl i made from an existing mdl (a tree in one of the world .mdl files), so its just an edit. 
 

[vurt 118]

Managed to fix it, well, at least this one (previous Morrowind mesh) did eventually export.

I was thinking i could add a lot more variety and detail to at least some maps with more trees, bushes, maybe various other clutter.

I am not entirely sure these will have collision, but i think not (no idea where collision is set, i will have to research), so flora will be the most optimal thing to add, bushes or plants that you can just walk through and isnt colliding with enemies etc, so pretty much how it works in modern games. Trees would either need collision or i would only place them where they are not in the way of enemies or the player, like on top of hills and cliffs etc. 

Not sure any of the bigger mods edit these mdl world files (e.g 233telea.mdl)? Hopefully not. 

[WildKarrde 145]

A few additional notes based on my own experience:

14 hours ago, vurt said:

Blender’s scene often has multiple roots or collections — the script creates a single proper root and re-parents everything under it.

KOTORBlender can actually handle multiple models and model roots/OdysseyBases in a single scene.  The key is that when you export the model, you must first select the OdysseyBase of the specific model you wish to export.

14 hours ago, vurt said:

Export fails or uses wrong texture if:

Multiple nodes are connected,

Material uses unsupported shaders,

Texture isn’t named properly.

Except for walkmeshes, KOTORBlender actually ignores the Blender material completely.  All of the parameters that KOTORBlender cares about are set up as properties of the mesh under “KOTOR Model Node”, which can be edited independently of the material.  I’ve had cases where I was lazy and edited the texture name in the model property but didn’t bother to update the Blender material to match, and it still exported fine.

14 hours ago, DarthParametric said:

I'm not sure how Blender handles UV channels, but lightmapped level models absolutely require a second UV channel for the lightmap UVs.

The lightmap UVs are saved under a second UV map called UVMap_lm, and the lightmap texture is set in the KOTOR Model Node properties of the mesh.

14 hours ago, vurt said:

MDL pivot points define animation centers and attachment positions.

If the Blender origin is offset (common after import), animations or rotations look wrong.

Blender calls it the Parent Inverse, you can read more about it here:  https://docs.blender.org/manual/en/latest/scene_layout/object/editing/parent.html. I’ve mainly had it come up as an issue when parenting objects.  I recommend using the “Make Parent without Inverse (Keep Transform)” command to avoid offset issues like this.  I also use this handy addon, which can zero out the Parent Inverse of a mesh after it was already parented while keeping its current position:  https://github.com/drewcassidy/blender-apply-parent-inverse.

26 minutes ago, vurt said:

(no idea where collision is set, i will have to research)

Collisions for area models are set by creating non-walkable areas in the walkmesh, which is stored in the .wok file matching the model name.  KOTORBlender will read and write .wok files as part of the import/export process if they are in the same location as the main MDL/MDX.

[vurt 118]

Very helpful, Thank you!