Page MenuHome

Import / Export MilkShape3D MS3D files (conform with v1.8.4)
Closed, ArchivedPublic


Project: Blender Extensions
Tracker: Py Scripts Contrib
Python: 3.2
Blender: 2.65
Author(s): Alexander Nussbaumer
Script name: io_scene_ms3d / MilkShape3D_MS3D
Wiki page:
Category: Import Export
SVN Download:
Status: Closed

this addon allows you to import ms3d files to blender and export ms3d from blender.
it is a basic and unoptimized one!
its performance is poor, but it works - don't use too many vertices and faces, or you will need plenty of time to use the addon.

all geometry, texturing stuff is working. the only important thing that is currently not implemented is joints, bones and keyframes
(no armatures, no bones, no poses, no animation)

the exporter will export:
- vertices, without doubles. (will apply the orgin to world coordinates x:0.0, y:0.0, z:0.0)
- triangles, it converts automatically 4 poly faces to triangles.
- normales, of the vertices
- uv-coordinates of the texture
- material of the mesh
- smoothing groups

what the exporter will not do:
- does not apply modifier or constraints
- does only export the first material of a mesh
- does only export the uv-coordinates of the first uv-texture of the mesh
- does not export bones and joints
- does not export keyframes
- does not export comments

the importer will import:
- groups as separated meshes
- vertices and triangles
- uv-coordinates
- smoothing groups
- materials

what the importer will not do:
- does not import normals
- does not import bones and joints
- does not import keyframes
- does not import comments

installation instruction:
- copy the "io_ms3d" folder to <Blender>/2.60/scripts/addons
- open blender
- File | User Preferences | Addons | Import-Export
- enable "Import-Export: MilkShape3D MS3D format (.ms3d)"

containing files:

__README__.txt : this file
§ Blender maintenance : entry point for blender plugins
initialize and registers/unregisters plugin functions
§ Blender maintenance : entry point for importer
§ Blender maintenance : entry point for exporter
§ Blender maintenance : objects and structures that specified a MilkShape3D file
base functions to write/read its objects itself
§ MilkShape maintenance : common converter
functions to bring Blender content in a correct way to MilkShape
functions to bring MilkShape content in a correct way to Blender
§ Blender -> MilkShape3D maintenance
§ MilkShape3D -> Blender maintenance

File | Import | MilkShape3D MS3D format (.ms3d)

File | Export | MilkShape3D MS3D format (.ms3d)

Event Timeline

to see a very basic use (of a earlyer version):

for material in

This is bad logic - see this thread --

some other notes---
if (smoothGroupKey not in smoothGroupFaceIndices.keys()):
can be---
if smoothGroupKey not in smoothGroupFaceIndices:

nKeys = len(smoothGroupFaceIndices.keys())
can be---
nKeys = len(smoothGroupFaceIndices)

thanks for that information...
this addon is my very first contact with python and blender scripting...
i will make review my code...

changed: (0, 3, 2, "beta (2011-11-27 00:00)")
mod: merged "" to "" (and droped "")
mod: moved exclusive importer stuff to "" (renamed BlenderFromMs3d... to ...)
mod: moved exclusive exporter stuff to "" (renamed Ms3dFromBlender... to ...)
fix: import object namings (keep track possible name collisions of ms3d and blender objects on non empty blender scenes - may have same names, but different content)
add: import to group option

i added some dictionaries and helper functions to track name translations between ms3d and blender.
for some objects, e.g. materials, the functions will also try to find a matching materials by comparing its content and sub objects (e.g. textures).
for other objects where name translations may happen, there is no search implemented (only a hull, what will never take affect).

than i also moved code to separate logic parts to its classes.

Thanks for the update, looking over the script and I still and not quite happy with how its working,

When you load data into a 3D scene you dont expect it to make changes to your existing data, an armature for instance may be in another scene and it might be some time before you realize its been clobbered by the importer.

there are comments like this:
# OPTIONAL: try to find an existing one, that fits

Since it can be useful to reuse data, images specifically - This should be an opt-in option, from what I can tell, with the current code its always running.
something like "ReUse Existing Data", with tooltip saying which datablocks can get re-used.

Even when this is added, names longer then blender supports wont work - so eventually you may want to store custom property per datablock which stores the original name to compare against.

Generally speaking though, it seems a bit redundant that everyone who writes an importer should have their own material/image/texture armature comparison functions and manage merging with existing data. Id prefer this be handled by a separate tool, at least IMHO its out of the scope of what an importer should do.
Blender can have data loaded from another blend file which the importer will find and use currently, you can explicitly ask for non linked-library data but again, everyone having to take care of these issues in their importers seems overkill imho.

before i make changes again - and run in the wrong direction...

1. you mean, if i want to reuse existing stuff, that is not comming from the current importing scope, i should give the user a choice to enable or disable that option. (like do it at your own risk)
1.1. if i reuse existing data i have take care of it, if the object is a linked resource of an external source.
- i will give the user the choise to reuse with the tooltip note, what will be affected.

2. but generally it is not the job of an importer to compare object content, because never all proterties will be handled in the same way - the importer is only looking for properties that is known to the importer, but an object can hold other important stuff, that the importer may not respect.
- so i should drop that functionallity compleately? ... or is there a library existing, i can use to compare content of objects in a standardized way.

3. i should add to every named objects or propertiey, that are available in ms3d, but not in blender, a custom property (like "ms3d_name", "ms3d_comment")...
3.1 and the exporter should use that properties again (if the custom properties are present and the user want to use these)

1) - yep.
2) - IMHO it should not be the job of the importer, but if you think its useful - Im not totally against, but it at least should be an option. so far we dont have a tool to merge data but we could ---- so suggest drop or make an option the user can select.
3) - for really reliable behavior this would be best.
3.1) it might make sense to use them though the user may have dupicated objects and not edited the property, theres also no gaurentee the names will be unique.

General comment - for addons some tools may want to define their own fairly spesific workflows where they do very un-blender like things, but from what I can see typical import/export isnt one of these but perhaps I miss something.

next try...

changed: (0, 3, 3, "beta (2011-11-29 00:00)")
mod: reuse existing data (now optional)
fix: reuse existing data (now ignores data if library is not none)
add: import process adds custom_properties with raw data (naming and some others, if expecting lost in translation)

Hi, looked over the script, and think this is ok to commit into addons_contrib/

... or from blenders source checkout:



+1 to commit this script as is however, further improvements can be made there.

I've added you as a developer so you can commit to this path with the same user/pass used here.

Final suggestions (not essential but noticed while reading 3.3)...
- When you check if data exists then get it, this does 2x lookups, for large dictionaries this can get slow, at any rate its unnecessary.

if "name" in somedict:result = somedict["name"]

can be replaced with 1x lookup...

result = somedict.get("name")
if result is not None: ....

This also works for* members.

Another thing, you can request non library members within this get() function, see:

thank you Campbell...
i've commit it successfully to

updated download link from "io_ms3d" to "io_scene_ms3d" on wiki page.

since Blender rev.42816, the add-on is not working proper anymore...
in the implementation of mathutils.Matrix was changed with Blender rev. 42816...
a fixed version of the add-on io_scene_ms3d will come soon.

fixed version is available now (
you can use it with blender 2.60 and newer rev. 42816.

Due to changes to the api including the merging of bmesh, several addons are outdated.
Please, if you are the author of an addon check your script with blender revision 44256 or newer.
That is builds made After blender 2.62 official release.
I would ask that updates be made to your addon before the Blender 2.63 release.
6-8 weeks away.
This allows time for the api to become more exposed & bmesh to stablize furthur.
If you need help, drop into irc freenode #blenderpython or #blendercoders & feel welcome to ask questions.
At the time of 2.63 release, scripts that are not repaired or in active developement will have their tracker page marked "Closed"
this will not affect your links to the tracker, similar to closing scripts in 2.49b, the page will be still availible & can be re-opened.

Thanks for your understanding & patience during these Exciting Times.

Moved from Py Scripts Upload to Py Scripts Contrib

moved page to contrib
assigned to beta-tester

WARNING: my addon (0,3,8 from 2012-01-17) will not work with the Blender 2.63 release, because of the BMesh changes in Blender.
I am currently working on it to fix that issue. please stay tuned.

committed a rewritten importer to svn contribs, that uses BMesh. i disabled the exporter for a moment, until it is ready for blender 2.63 as well.

attached the old backup of importer / exporter (v0.3.8) for blender 2.60 .. 2.62, for people who need a working add-on for older blender until the new exporter is not ready for blender 2.63 ..

Import/export plugin won't enable, also error message in .xsession-errors

Traceback (most recent call last):
File "/usr/lib/blender/scripts/modules/", line 259, in enable
mod = __import__(module_name)
File "/home/shadowwraith/.blender/2.62/scripts/addons/io_scene_ms3d/", line 56, in <module>
from io_scene_ms3d.ms3d_ui import (
File "/home/shadowwraith/.blender/2.62/scripts/addons/io_scene_ms3d/", line 67, in <module>
from bmesh import (
ImportError: No module named bmesh

hello Thomas,

for me, it looks like, you try to enable the newer addon v0.4.0.3 that is made for blender 2.63 with a blender v2.62... that will definitely not work.
if you use blender 2.62, please use the old addon version 0.3.8 (e.g.

the importer is mainly completed (see the wiki for limitations - the exporter is incomplete).
please, can somebody take a look to the add-on, if it is good enough to put to release add-on?

the exporter is restored now - with basic functionality only. (old unused code of v0.3.8 is completely dropped)

with version the importer is final - 100% of the planned features are implemented (see wiki)

v0.5.0.0 is ready.
all planned features are implemented and working (importer is 100% ready, exporter is 100% ready)
video tutorial is coming soon.

wiki documentation of the add-on is completed.


I have some issues with import/export of version.

Files for testing:

Also, try to import, then export, then import again. You will get different result from original import.

Thanks for development!

hello Paul...
thank you for providing me all the test files.
(all my development based on only two test ms3d files i found in the internet "diabolo.ms3d", "dwart1.ms3d")

1. that the bone-system looks so weird, is because, i implemented the system in the easiest way for me - in that way, i don't have to recalculate a nice looking bone-system and don't have to adjust all animation keyframes to it.
ms3d joints will be in blender a bone with the length of one blender unit. the dimension of your models are very tiny, so the bones (joins) are looking way oversized.

i will try to add an option to implement a nicer looking bone-system and adjustment.

2. it seams that there are other issues, because not all bones will influence its vertices.
i'll try to find the reason and will fix it as soon as possible.

3. the verbose mode is not working (out of memory)... you files are huge. ;)
so i have to fix that first to figure out wat is wrong with the other issues.

4. and i saw an issue because of the unicode sting encoding...
i have to study the documents to figure out how to handle these special unicode characters.

hi Paul,

i updated the add-on to v0.5.0.2
it will solve problems with bone weights,
joint sizes in the viewport,
exporting forgotten model properties,
the verbose mode on larger models (content),
and i disabled printing the original file name on system console (unicode problems)

... i hope in this way you can work with the add-on.

Hey man!!!!

It seems you fixed it.

I can work with Milkshape models! Thank you! Great job! But if I work with Blender to MilkShape i have some issues:
- I cannot bake animation with IK bones.
- I cannot bake animation with NLA tracks.

Just try to export these blend files and import them again:

And another bug is "export button" is locked if my last selection was Armature.

Thank you! Great addon!

hello Paul,

- that the exporter is enabled only if a mesh object is selected is not a bug - i have done it, because otherwise i don't know what to handle in case a selected armature is used by more mesh objects. (this i will not change at the moment)

- now the add-on will respect also nla-tracks, that are not muted and all its strips that are not muted as well as normal action.
- the issue with IK bones is still present in v0.5.0.4 - this will take a bit more time to implement... sorry.

PS.: i noticed, your ms3d files "...xprime_legionary...ms3d" does contains "vertex_ex.extra" values. do you use this information in some way in your destination environment or game ? if yes, tell me, than i put this to my todo list.

btw... the animations and models are very cool.

Hello Alexander!

You added NLA Strips!!! YOU ROCK MAN!!! THANK YOU A LOT!!!

About IK-constarint - you don't need to implement the IK-constraints. All you need is to add checkBox "BakeAnimation" for your Exporter.
I did it in blender but if you make such a "checkbox" for exporter - it will be cool!
Heve a look at my video how i baked animation and removed constraints:

In python it would be like that:
bpy.ops.nla.bake(frame_start=1, frame_end=25, step=1, only_selected=False, clear_constraints=True, bake_types={'POSE', 'OBJECT'})

Then all IK-constaraints and other constraints will be baked to Armature. You can add this like a checkbox "BakeAnimation" for your cool Exporter.

About "vertex_ex.extra" i don't know what it is...
The more implemented the better.. :)

I have an exceprion with importing of "ГОТОВО_xprime_legionary_lod0_animby_MTW2_Mace_charge_attack.ms3d" which is in the archive.

Traceback (most recent call last):
File "/home/mifth/Documents/blender/2.64/scripts/addons/io_scene_ms3d/", line 403, in execute
def execute(self, blender_context):
File "/home/mifth/Documents/blender/2.64/scripts/addons/io_scene_ms3d/", line 76, in <module>
from io_scene_ms3d.ms3d_utils import (
ImportError: cannot import name set_sence_to_metric

location:<unknown location>:-1

Forgot to say that if you bake animation, so another new "Action" is created. It becomes very tricky for exporting of NLA strips... Just take a look at this...

hi Paul,

i could not reproduce your issue with "...ImportError: cannot import name set_sence_to_metric" on my system 2.64.9.
what version are you using?
anyhow i changed the (re-)initialization of the add-on a bit, there was an issue on F8-key - hopefully this will solve your issue as well.

since the last two nightly/daily builds my add-on was crashing blender only by exporting your "character_IK.blend" test file. i changed also that, and i hope is will work well in the wide range of releases/builds of blender.

i added an export option to shrink the animation to only the region from first available keyframe to the last available one. maybe that will be handy in case of NLA-tracks strips if you want only a single or few of them (when some strips a muted e.g. by H-key)

i think, your suggestion to bake IKs, is not optimal, because it will produce a keyframe each frame, that will produce much overhead. i will try to implement IK (bone constraints) to get a lightweight result... but it takes time - hopefully this weekend.

... thank you for testing.

Hello man!

It seems there is no issue anymore. I recompiled the addon...

No need to implement IK-constraints of MilkShape. You certainly need to bake all keyframes, because blender-IK and milkshape-IK are different. Also animation curves are different too in all apps.

Ogre-exporter and FBX-exporter bake animation constraints.
You can check blender2Ogre exporter (it bakes animation):

Or you can add checkBox "Bake Animation" to have a choice for exporting. :)

thanks man!

ok, now the armature constraints (IKs) will baked to the output in the fly (take the correct matrices, combine them in the correct order - and voila!).
reading your last post about different interpretation of curves, i added an option to export keys at each frame, not only at each keyframe.

i think that's it for the moment... any other challenge ? :D
(let me know if i can test your game)


OMG! You did professional plugin! Congratulations! Great Job!
I think this plugin should go with official expoters, really.

As for me, so i do not create a game with MilkShape. I just want to help with animations in this project:
There all animations were made with milkShape. Possibly i will participate there a bit...

But i make a game with Java (jMonkey Engine).
Like these demos:
Just contact me if you want to spend some free time for indie games. :)

Just one remark about MilkShape Importer: when i import model.. there is an "Empty" created. Is it ok? I do not know how it works in milkShape.. Are you sure that there should be an "Empty"?

Thank you! Great job for our community!

... the "Empty" is not from the content of the MilkShape model. i create this empty to easy place the import to the cursor and as "group point" where both (mesh and armature) are parented to, to have all together in one point - only for organization purpose.

"natus ob imperium" looks it is a big project, i hope you will get the possibility to participate... would be great chance.

i am not a game developer (but i would like to be), my initial intention to create this add-on came from to contribute the future pinball community - they make so cool pinball games.
i would be very proud about, if my add-on goes to official exporters in blender...

Hello again. :)

My participation will be very-very small. :)

I think it would be better to remove "Empty" as all other importers (fbx, obj) do not create any additional objects. Imho...

Wrighting games is real fun. :)

now i pushed the version to v0.6.x

- i added an option to take blender materials instead of use the ms3d material panel. this makes it easier to work with modeling from scratch.
- i removed the "Set Scene To Metric" option from importer and moved it to a "space-bar" option.
- the importer / exporter are now reading / storing the vertex extra value - but i did not exposed it to the UI - i have no idea for what it is used for, and i can not remember me ever seen any interface in MilkShape 3D to access to it.
- the methods to call import and export are now accessible and executable from python-script. now you can write your own batch script for automation.




@paul: i will not drop the empty on import. i imported a bunch of models, and i found this empty very handy. btw - the collada importer generates also an "empty".
so i think there are really no open features to implement anymore.

Well Done about 0.6!

It's ok about the Empty. You are the developer you decide what should be. :) I just said my humble opinion.

PS: If you will have some time... Could you have a look at FBX Importer? This plugin was fully dropped since 2.61 and it does not work. We have only working FBX Exporter but not the Importer. This is really a big feature request by many artists... As Unity, UDK and other game engines use FBX for their assets. I can fully test your development if you would like.
Here is the FBX Importer link:

now, the addon v0.7.x needs blender 2.65, because of the internal use of the triangulate modifier on export

this is a request to bring my addon to trunk.
- my addon is tested under blender 2.65, 2.65a and up to svn r53317.
- all features i wanted are implemented.
- the Wiki page is completed and up to date.

thank you all...
alexander nussbaumer

PS.: BTW - merry xmas and a happy new year :D

Hello, found a bug with MS3D 0.9.1 in builds from, r53689 and r53833 (official 2.65a is fine).
See bugreport, attachments and link to crash.txt in comments here:

thank you - and sorry for that trouble - i can see that issue as well in build 53922 and 54001.
i'll take a look to it to fix as soon as possible.

hmm... something changed inbetween official release and somethere of svn >53317. is the official version of 2_65_release:
template_list(data, property, active_data, active_property, prop_list="", rows=5, maxrows=5, type='DEFAULT')
this is the version of 2_65_3 and higher:
template_list(listtype_name, list_id="", dataptr, propname, active_dataptr, active_propname, rows=5, maxrows=5, type='DEFAULT')

will this be the final version for the next releases... ?

I fixed it like this way:

According to blender 2.65.9... "UI_UL_list" should be used now...

Also, another guy gave different approach for the fix:
See '3dmad' post.

I hope it will help.

yes, thank you...
now, my add-on should be fixed with commit [4191] of contrition add-on.
now minimum >= 2.65.3 of blender is required.

moved MilkShape3D add-on

moved the bug tracker for this add-on to

please use the new tracker to report bugs.

Alexander N. (beta-tester) closed this task as Archived.Feb 2 2013, 7:47 AM

This task was automatically closed as archived as part of migration, because it was determined to be no longer active.

The authoritative list of addons is on the wiki, we no longer have a report for each addon to track bugs and updates. Bugs can be reported individually and assigned to the addon developers. See the Addons project page for more information on the workflow.