Blender Vertex Mesh export Plugin [V1.2.5].

[Skywolf]

Because using 3ds2unr is such a janky mess did I decide to learn Python for once and write a small plugin to give Blender the possibility to export to Unreal .3d vertex mesh format. Took way longer than I expected. Mainly because of how hard it is to find any decent documentation about Blender's API. But I digress.

Version 1.2.5 Disclaimer: use at your own risk. Shouldn't do anyting malicious and the worst it could do it ruin your .blend file (so make a back-up to be on the safe side) but you never know.


To install or update open the User Preferences of Blender. Go to the Add-ons tab and click install from file. Then select the .zip file. Now click on the Import-Export Catergory and enable it.

When exporting with Use Actions checked make sure you selected objects that affect the mesh first and then select the mesh you want to export last so it is the active object (yellow outline instead of orange).

So lets say you have a mesh and an armature that deforms it. Select the armature first and then select the mesh while holding shift. Now the armature should have a orange outline while the mesh has a yellow one.

When just using the Timeline (Use Actions unchecked) you just need to select the mesh.


Now it's time to go over the options and limitations (because this is Unreal. So ofcourse there are limitations )

When exporting you have the options to pick whether it should use Actions or just the scene timeline for animation data. Using Actions is eassier to work with while using the Timeline allows for things like Keyframes and the NLA editor (Non Linear Action editor) to be used.

Down side is that when using the timeline method you won't be getting a nice .uc file with all the animation data filled in for you. Just an ALL and Still sequence. The others will have to be entered by hand.

Due to how Blender handles frames is it not possible to have an Action export with just one frame. To get around this did I set it up so that when an Action only has 1 set of key frames (one vertical row) it will export it as an 1 frame sequence.


Now the limits dictated by the file format.

• There is a vertex (note vertex. not polygons) limit of 16383 dictated by the animation file. So people dreaming of making 6million polygon versions of every asset in Unreal will probably have a bad time .
• Always keep your vertices within 255*255*255 units. -128 to 127 Blender units on each axis.
• UVs snap to a 256 to 256 grid. But because Unreal reads everything on a 1 pixel offset on the x axis was I forced to add an offset. This basically means that, when using a 256*256 image, the whole outer ring of pixels wont be used and UV vertices on these will cause an error. Just like when you move your vertices outside the image.
• For the best results set the fps under render settings to something lower than the default 24fps and base your animations on that. Around 10-15 should be fine. Setting it higher will just give you larger file sizes while making the animations look worse aswell. Keep in mind that this doesn't affect the rate at which the animations are played back in Unreal.

I probably forgot about some things. But I'm sure people will remind me of those when they come across them.


Materials

Polyflags and texnum are handled by material name The material should start with a three digits containing a number between 0 and 255 (if not it will use the material index instead) which is the texnum. After this you can add one of the following (case sensitive):

• _NOMRAL/_NM The default. Used if none of these are given.
• _2SIDED/_DD Makes this poly 2-sided
• _TRANSLUCENT/_LU Makes this poly translucent and 2-sided
• _MASKED/_CL Makes this poly masked and 2-sided
• _MODULATED/_MD Makes this poly modulated and 2-sided
• _ALPHABLEND/_AB Makes this poly alphablend and 2-sided (227 only)
• _WEAPONTRI/_PH makes this poly a weapon triangle (used to place the weapon in 3rd person view).

You can the add these to the name. Unlike the pervious list you can have more than one of these at the same time (also case sensitive):

• _UNLIT/_UL No lighting and full lit.
• _FLAT/_FL Not really sure to be honest. Probably related to the mesh curvy thingy.
• _ENVIRONMENT/_RF Render this poly to make it look shiny.
• _NOSMOOTH/_NS No texture smoothing (see: Minecraft)

Example: The following name would make the polygons assigned to this material translucent while unlit and shiny (environment) while using texture slot 0:

000_UL_TRANSLUCENT_ENVIRONMENT_

Note how the order of the flags don't matter. The only thing that has a specific spot in the name is the texture slot.

You can have different flags for different polygons while still make them use the same texture slot. So lets say I make another one and name it like this:

000_MD_FLAT_

Would it use the same texture slot while using these flags instead.

The texture name (used for the .uc file) is read from the name of the first texture in the texture list of a given material. If two materials with the same material slot have a different texture only the first in the list will be used. the .pcx extension will be added automatically.

This should be everything.


While using this plugin is at your own risk (aka: make a backup of your .Blend file), are any feedback and bug reports welcome .

Plan to write a proper documentation on the Oldunreal wiki at one point. But this will have to do for now.

Changelog:

Code: Select all

1.2.5 - 04/06/17
-Fixed the mesh scaling for ION Storm (Deus Ex) format in the .uc file to adjust for the larger scale due to the larger file format.

1.2.4 - 04/02/17
-Fixed the mesh scaling for ION Storm (Deus Ex) format in the .uc file.
-Fixed a crash when exporting the .uc file if the user unchenked exporting the animation and/or data file.

1.2.3 - 04/01/17
-Changed the way the ION Storm (Deus Ex) is written at the suggestion of Han. Should yield the same result but doesn't have the unnecessary bit shifting.

1.2.2 - 03/31/17
-Fixed padding in ION Storm (Deus Ex) format.

1.2.1 - 03/30/17
-Fixed crashing when a mesh is exported with no UV data. A model with no UV data will have LODNOTEX=True set in the .uc file.
-Added MLOD, LODSTYLE and LODFRAME settings for the .uc file.
-Updated the version number in the bl_info section this time....

1.1.2 - 03/24/17
-Added support for ION Storm format.
-Added support for ION Polytype and Polyflag matertial naming scheme.
-Modified reading of the texture slots space in the material names to allow up to 256 (0-255) texture slots.
-Added RATE= for sequences in .uc file based on scene fps setting.
-Set an initial rotation in the .uc file to rotate the mesh 90 degrees to make Blender's front also the front in Unreal.
-Added folder settings for use with ucc -make.
-Made the selection for Actions or Scene Timeline a list instead of a bool.
-Vertex coordinates are now rounded instead of truncated.
-Vertex coordinates are now clamped to move any vertices outside the 255*255*255 range to the borders instead of a random location.
-Fixed crashing when exporting meshes with no materials or empty first texture slot.

0.9.0 - 03/21/17 
-Initial release.

[Krull0r]

AWESOME Plugin!

I only read the description in your post yet but such an exporter will save a lot of time and keeps my hair colored

I'll try it out in the next days!



Thank you for sharing your work with us

[dustinechoes849]

This looks rad!
Gonna give this a shot.

[han]

I personally do like the ION syntax used for polyflags, especially as this avoids using extremly long names. Adding support for that/switching to that in my ActorX fork is still on my todo list.

Like 3ds2unr/de LWO23D.exe uses a similar system to derive the james mesh triangle type, and hence the polyflags flags for the triangle out of parts of the material name. If the material contains a substring in the form _XY the flags do get added. Here is a list:

Base types, mutally exclusive:
_CL - "Masked", sets PF_TwoSided | PF_Masked.
_DD - "NormalTwoSided", sets PF_TwoSided.
_LU - "Translucent", sets PF_TwoSided | PF_Translucent.
_MD - "Modulate", sets PF_TwoSided | PF_Modulated.
_PH - "Placeholder", sets PF_TwoSided | PF_Invisible (weapon triangle).

Additional FX flags.
_UL - "Unlit", sets PF_Unlit.
_RF - "Environment", sets PF_Environment.
_FL - "Flat", sets PF_Flat.
_NS - "NoSmooth", sets PF_NoSmooth.

Example:
A material name of Embla_CL_UL would make it masked, two sided and unlit (PF_TwoSided | PF_Masked | PF_Unlit).

Also you should consider not just using a single digit start, but use two digits in front. While multiskins are limited, the actual mesh can have more than eight textures and render fine, you just won't be able to override those by using multiskins (Though I would certainly discourage creating such meshes, but also I don't see that your tool should have this limitiation as changing this is certainly not much of an effort).

What I certainly would like you to add is support to IONs versions of the James Mesh format. Deus Ex basically use INT X:16, Y:16, Z:16; _PAD:16; as packing of the vertex data instead of the default Unreal X:11, Y:11, Z:10; packing, and thus AnivHeader.FrameSize value is twice as large.

[Skywolf]

I personally do like the ION syntax used for polyflags, especially as this avoids using extremly long names. Adding support for that/switching to that in my ActorX fork is still on my todo list.

Like 3ds2unr/de LWO23D.exe uses a similar system to derive the james mesh triangle type, and hence the polyflags flags for the triangle out of parts of the material name. If the material contains a substring in the form _XY the flags do get added. Here is a list:

Base types, mutally exclusive:
_CL - "Masked", sets PF_TwoSided | PF_Masked.
_DD - "NormalTwoSided", sets PF_TwoSided.
_LU - "Translucent", sets PF_TwoSided | PF_Translucent.
_MD - "Modulate", sets PF_TwoSided | PF_Modulated.
_PH - "Placeholder", sets PF_TwoSided | PF_Invisible (weapon triangle).

Additional FX flags.
_UL - "Unlit", sets PF_Unlit.
_RF - "Environment", sets PF_Environment.
_FL - "Flat", sets PF_Flat.
_NS - "NoSmooth", sets PF_NoSmooth.

Example:
A material name of Embla_CL_UL would make it masked, two sided and unlit (PF_TwoSided | PF_Masked | PF_Unlit).

Will add support for this. Probably along side the current implementation for those who prefer longer but more obvious names.

Also you should consider not just using a single digit start, but use two digits in front. While multiskins are limited, the actual mesh can have more than eight textures and render fine, you just won't be able to override those by using multiskins (Though I would certainly discourage creating such meshes, but also I don't see that your tool should have this limitiation as changing this is certainly not much of an effort).

Well, why not. Easy to implement and good for the weird people who like to make meshes with 256 different textures.

What I certainly would like you to add is support to IONs versions of the James Mesh format. Deus Ex basically use INT X:16, Y:16, Z:16; _PAD:16; as packing of the vertex data instead of the default Unreal X:11, Y:11, Z:10; packing, and thus AnivHeader.FrameSize value is twice as large.

This part is kinda confusing for me. What is _PAD? just empty wasted space? And with FrameSize being twice as large, does this also apply to the size of the variable (so 2 bytes instead of one)?

Other than that, should be easy enough to get going. Although I have no way of testing it so someone else will have to do that . Can't go much wrong though once the above questions are cleared up.

[[]KAOS[]Casey]

_PAD is probably binary compatibility if they ever wanted to add W... but obviously they didn't. though I have no idea what they'd use W for exactly... And yes, it's just empty (probably zeroed) padding.

[han]

Yes, the padding is just garbage, though should be set to zero. It is used so the vertices get an 8 byte alignment.

With twice as large I was refering to the value of AnivHeader.FrameSize as this is basically FrameVerts*sizeof(Vertex). And as sizeof(Vertex)==4 for Unreal and sizeof(Vertex)==8 for Deus Ex it gets twice as large.

[Skywolf]

Where does the padding go? Is it padding-z-y-x or z-y-x-padding?

Other than that. I assume this would be the right code then? I want to make it use the same 256x256x256 limit and just export it with the increased accuracy. To make exporting to both formats as seamless as possible.

Code: Select all

            for verts in me.vertices:
                
                co = ((int(verts.co[0] * 256) & 0xffff))
                
                co += (((int((verts.co[1]*-1)* 256) & 0xffff)

[han]

Probably "padding-z-y-x" I guess. Just writing in (file) order X-Y-Z-PAD. Never dealt with the bits directly.

For DX you could also just skip dealing with the bits and just write it as 2 byte integers each.

Also you might want to round instead of truncating, as this gives half the maximum error compared to truncation, though truncating moves everything into one direction (or towards (0,0,0) as 3ds2unr afaik did).

In any case you should not bitmask, but rather clamp the vertex coordiates into the specific range, as this will just move any outside vertex to the borders instead of moving it somewhere more or less random.

[Skywolf]

Probably "padding-z-y-x" I guess. Just writing in (file) order X-Y-Z-PAD. Never dealt with the bits directly.

For DX you could also just skip dealing with the bits and just write it as 2 byte integers each.

Python adds data at the end of a file. Not at the beginning. So just writing X-Y-Z-PAD puts it in the wrong order. No idea if there is a way to change that. But I already adapted my code to this.

Also you might want to round instead of truncating, as this gives half the maximum error compared to truncation, though truncating moves everything into one direction (or towards (0,0,0) as 3ds2unr afaik did).

In any case you should not bitmask, but rather clamp the vertex coordiates into the specific range, as this will just move any outside vertex to the borders instead of moving it somewhere more or less random.

Was already considering this. But first wanted to get it to work as similairly to 3ds2unr as possible. Will be first on my list after getting Deus Ex support to work.

Little update:

Code: Select all

-Added support for ION Storm format (unfinished, missing padding).
-Added support for ION Polytype and Polyflag matertial naming scheme.
-Modified reading of the texture slots space in the material names to allow up to 256 (0-255) texture slots.
-Added RATE= for sequences in .uc file based on scene fps setting.
-Set an initial rotation in the .uc file to rotate the mesh 90 degrees to make Blender's front also the front in Unreal.
-Added folder settings for use with ucc -make.
-Made the selection for Actions or Scene Timeline a list instead of a bool.

[han]

Python adds data at the end of a file. Not at the beginning. So just writing X-Y-Z-PAD puts it in the wrong order. No idea if there is a way to change that. But I already adapted my code to this.

I was refering to writing each component one after another, as each of these is 2 bytes, so these won't need to be bit shifted together, while you can't do that for the Unreal Mesh format as the components are not byte boundary aligned.

[Skywolf]

Alright, uploaded the updated version (see original post).

Can someone test the ION Storm (Deus Ex) format?

[han]

Can someone test the ION Storm (Deus Ex) format?

Do you have some Sample blender file to test with? Mh might be a neat idea to include such a test file in the release.

[Skywolf]

https://www.dropbox.com/s/xlwsycpamt2bj ... blend?dl=0

Still contains the old 3ds2unr prepare script but you should just ignore this and export it using the plugin. Export with Actions as animation source.

[dustinechoes849]

I decided to DL this and try it, but...

What happened?

Here's what I did step by step (with incredible grammar and spelling):

herez le modél


try to xporté
de konfig defauliet


put into le correct folder in C:\Unreal den add to lé EditPackages end all dat mumbo jumbo


UCC MAKE
BOOOOOOM
NO WORK !



...did I mess something up? (other than my spelling and grammar)

here's the files:
https://www.dropbox.com/s/fouswfjs7c42k ... d.zip?dl=0
despite the the filename of the .ZIP, there's more than just the _d.3d file lol

EDIT: the whole blender window before export (btw, I'm a noob at blender)

[Skywolf]

You told my plugin to export with Actions as animation source. But you didn't make any. So it just created an empty _a.3d file with just a header but no vertex coordinates. So you just gave Unreal a bunch of vertices and polys in the data file with no way to make a functional model out of it .

If you just want to export an one frame model set the start and end in the timeline (bottom of your screenshot) to the same number and export with Scene Timeline as animation source.

[dustinechoes849]

It worked!

For some reason, the model gets more and more disintegrated the further I am from it. Like some kinda broken LOD thing. When the model's up close, it looks fine tho.

EDIT: I tried changing the MINVERTS to 539, the amount displayed in blender, and it looks a lot better, but there's a few polys that vanish when I'm not up close to the model in-game.

[Skywolf]

You can lower LODStrength a bit if Unreal LODs your model too much. Or set it to 0 to disable it entirely. But if you want that just add MLOD=0 to the "#exec mesh import" line to import the model as a Mesh instead of a LodMesh.

Has anybody tested the Deus Ex format already?

[dustinechoes849]

It worked!

I'm installing Deus Ex right now to try it there.

[dustinechoes849]

Tried exporting the default Blender cube thing, using the same method I did with the riddler trophy, except in Ion Storm mode.

[Skywolf]

Blender doesn't give objects an UV map by default is seems. So the plugin tries to access data that doesn't exist and throws an error.

Uv unwap (Doesn't matter how, just so there is some UV data) and try again. Will make the plugin handle this scenario properly later.

[han]

Blender doesn't give objects an UV map by default is seems. So the plugin tries to access data that doesn't exist and throws an error.

Uv unwap (Doesn't matter how, just so there is some UV data) and try again. Will make the plugin handle this scenario properly later.

Maybe set LODNOTEX=True along that way, to make it somewhat more explicitly shown in the *.uc file.

Regarding the LODing behaviour, maybe adding an option to select the LODSTYLE. See: http://www.hypercoop.tk/infobase/archive/unrealtech/lodtechnologynotes.htm HP1 uses LODSTYLE=10, which seems to be a resonable default though.

Haven't yet figured my way yet through Blender, the sample blend file looked a bit weired when opened in Blender, but might jsut have been viewport settings.

[Skywolf]

Can you combine LOD styles? For example: 10 would be 2 and 8 combined.

The example .blend file doesn't require any changes to test the exporter. Everything is already selected and set up so that all you have to do is export with actions and animation source.

[han]

Yes, they act as sort of flags for calculating costs for collapsing. Though combining 1 and 8 would obviously make less sense. There appears to be also some 32, which seems to further increase the influence of the edge lenghts.

[Skywolf]

Done. Added a setting for LODFRAME and MLOD aswell.

See original post for link and changelog.