Blender importer/exporter [1.7.0]

Ask for help about creating mods and scripts for Grimrock 2 or share your tips, scripts, tools and assets with other modders here. Warning: forum contains spoilers!
minmay
Posts: 2768
Joined: Mon Sep 23, 2013 2:24 am

Blender importer/exporter [1.7.0]

Post by minmay »

This is a continuation of bitcpy's excellent Blender importer/exporter for Legend of Grimrock models and animations.

bitcpy did all the hard work; I just ported it to work with Blender 3.3+ and did a few tweaks. The latest version in that thread only fully worked with Blender 2.73a and earlier, and wouldn't load at all in Blender 2.8 and later due to changes in Blender's Python API.

Download
Old versions: 1.6.1, 1.5.1, 1.5.0

This port doesn't have the years of community usage that the previous version did, so it's not as battle-tested; expect some bugs, but if you report them here I'll try to fix them.

Install it from the add-on preferences in Blender, or just put the file in your [Blender version]/scripts/addons/ directory and enable it in said add-on preferences (make sure to show "Community" support level add-ons).

Usage
With the add-on enabled, File -> Import and File -> Export will have options for Grimrock models and animations. Both Grimrock 1 and 2 files are supported.
To export a Grimrock 1 animation, just select it in the "Animation version" dropdown menu when prompted for the export location. Grimrock 1 and 2 use the same model file format.

Models will import with a parent Empty object called "game_matrix", which transforms its children from Grimrock's axis order to Blender's axis order. This object will not be exported. This lets you import and export models without having to do this transformation by hand. You can also create the game_matrix object without importing a model, using the button in the "Create" section of the 3D view tool panel thingy (the one that pops up when you press 'n' by default and lets you change translation/rotation/scale).

Empty objects, bones, and meshes will all export as nodes in the model file. Blender objects of other types (cameras, lights, etc.) are ignored.
Objects that are hidden using the eye icons in the Outliner are not exported.
Grimrock, like all games not made for the Sega Saturn, only uses triangles for its faces. Quadrilaterals will be automatically turned into triangles for export. Polygons with more than 4 edges will cause the export to fail entirely, so triangulate them first (Ctrl+T in edit mode by default).

Tip: If you're making a new model, you might want to start by importing an existing Grimrock model anyway, because it will give you a Grimrock-compatible object hierarchy to work with. I especially recommend this for rigged models and double-especially recommend it for monster models.

Animation export details
Currently the script only exports animations for objects that are in the main scene collection. Objects that are in another collection - even if that collection is itself in the scene collection - will be ignored.
Remember to use Bake Action before exporting to generate all animation frames.

More detail about going between Blender and Grimrock
SpoilerShow
Why does the exporter keep separating my faces?
In Grimrock, faces can only share a vertex if they agree on the material, UV coordinates, and normal of that vertex. Two faces with different materials, different normals, non-contiguous UV coordinates, and so on, cannot be joined in Grimrock; the exporter will separate them in the model file, even if they're joined in Blender.

In Blender, if you've set faces to have flat shading instead of smooth shading, they won't have matching vertex normals anymore - causing every flat-shaded face to become separated from every other face when you export the model. This results in a model that uses way more memory and GPU power than you intended (and looks bad too).
So do not set objects or faces to use flat shading in Blender. Instead, always use smooth shading by default, and when you want flat shading for an intersection, mark the relevant edges as sharp ("Edge -> Mark Sharp").

Object -> Shade Smooth will set smooth shading on the entire selected object; there's also the auto smooth feature in the "Normals" section of Object Data Properties (the tab with the green triangle wireframe icon). The script always imports models with auto smooth on, to prevent accidental flat shading.

If you import a model file and a ton of its faces are separated (probably because someone accidentally exported it with all flat shading), don't fret: you can easily join them again by selecting all vertices ('a' key by default) and using the "Mesh -> Clean Up -> Merge by distance" command. Then use "Mesh -> Normals -> Reset Vectors" to reset the normals (see below).

Custom normals
Grimrock models have vertex normals stored in the model file, and these normals don't have to match the "natural" normal of the vertex. For example, beach_cattail_blocker.model has normals pointed upwards so that they receive more light from the sun.

This script preserves these normals as custom normals in Blender. If you're modifying the geometry of an imported model, the imported normals probably won't make sense anymore, and you'll want to get rid of them. To do this, use "Mesh -> Normals -> Reset Vectors", which will restore the "natural" normals for selected vertices.

Alternatively, if you want to use natural normals for the entire object, go to Object Data Properties (same place you go to edit vertex groups) -> Geometry Data, and click "Clear Custom Split Normals Data".

Negative scale
If you export a model and the lighting on it in Grimrock is all weird, you probably exported it with negative scale in Grimrock's space. To fix this, just invert the scale of the mesh/empty again: if it's already negative in Blender, apply it and Mesh -> Normals -> Flip, then export again.
If it isn't negative in Blender, then make it negative (that 'n' menu is useful here, just put the cursor over each Scale number and hit '-' to invert them), apply it, then make it negative again (and don't apply), and flip the normals, then export. Do not change the scale of the game_matrix object.

Multiple meshes
Model files with fewer Mesh objects and fewer materials are faster to render. Sometimes you need multiple mesh objects because you're animating them differently from each other, but otherwise you should merge your mesh objects into one in Blender, in order to get better game performance.

Tangents
Exporting tangents is optional, but tangents are required for normal mapping to work, so you almost always want to export them. However, if you're sure you won't use a normal map with a model (perhaps the model's only being used as an emitterMesh for a particle emitter, or with a translucent material that can't receive lighting anyway?), then you can disable tangent export for a slight filesize savings if you want.
Version history and stuff
SpoilerShow

Code: Select all

# bitcpy, minmay

# NOTE
#   Loads a Legend of Grimrock 1 & 2 model from either a .model file or a .dat container
#   Loads a Legend of Grimrock 1 & 2 animation from either a .animation file or a .dat container
#   Saves a Legend of Grimrock 1 & 2 model
#   Saves a Legend of Grimrock 1 & 2 animation
#
#   Names of models and animations in .dat container are determined by doing an extremly simple scan of lua compiled files.

# Known issues / things to improve:
# - Model export can sometimes split vertices that shouldn't be split
#     Example: import and export assets/models/env/beach_cattail_blocker.model, and some of the cattails will have one of the triangles at their tips become split from the rest of the mesh
# - Importing models with nodes that have the same names as existing objects in Blender will use those nodes for parenting instead of the newly imported nodes.
#     Sometimes this is what you want (usually you would prefer to reuse the existing RootNode instead of the new one), but sometimes it isn't, e.g. importing
#     two monster models at once will make a big mess.
#     Should probably switch to using the newly imported nodes by default. Special case to use the existing RootNode but not others?
# - Importing models with vertices that have normals of 0,0,0 will use auto-computed normals for those vertices instead
# - Animation import is CPU-crushing, could be made much faster
# - Animation import should probably clear existing keyframes...
# - Load material definitions from Grimrock lua files?

# HISTORY
#
#   Version 1.7.0 (minmay)
#       Updated for Blender 4
#
#   Version 1.6.1 (minmay)
#       Fixed exporting for models without vertex colors. oops.
#
#   Version 1.6.0 (minmay)
#       Updated for Blender 3.3
#       Added vertex color support. Vertex colors are not used in either Grimrock game's built-in shaders, but the model format supports them and custom shaders (umods or tricky custom dungeons) can use them.
#
#   Version 1.5.1 (minmay)
#       Fixed Grimrock 1 animations exporting with the wrong header
#       Disabled vertex color export for now; in the meantime, now you can import models that have vertex colors without getting an error (the colors probably won't be right though)
#       Fixed "root" bone nodes exporting with no parent node instead of the armature's parent node
#       Exporting a model with an object named the same as a bone will no longer try to re-parent and re-transform those objects to match the bone.
#         I know disabling the re-transform sucks, but it was breaking with some models like fjeld_warg.model and I'm not cool enough to figure out how to fix it.
#         The re-parenting will stay gone, so that you can make node hierarchies with bone nodes above the mesh animated by that bone, e.g. beach_master_gate.model in the standard assets.
#         Exporting a bone without a correspondingly named object will still create a node with the same transform as the bone, so if you moved a bone
#           in a model you can still update the node position simply by deleting the object.
#
#   Version 1.5.0 (minmay, with kind retroactive permission from bitcpy)
#       Ported to Blender 2.9
#       As Blender now has full support for custom normals, models like forest_plant_cluster_01.model can now be imported/exported without losing their custom normals
#       Removed the foliage normals utility introduced in 1.4.3, as it's obsolete now that Blender fully supports custom normals
#       Exporting a model with bones now automatically creates corresponding nodes
#       Importing a model with nodes that have invalid parents no longer causes an error (fixes import of some custom Grimrock 1 models)
#       Importing multiple models no longer creates multiple game_matrix objects
#       Trying to export a model with N-gons (or anything else that causes an error while generating the Grimrock model/animation structure) now writes nothing instead of writing an empty file
#       Trying to export a model with N-gons now has a more helpful error message
#
#   Version 1.4.4
#       Added a small sub-section when weighting vertices for models that seems to have incorrect skinning.
#       This fixes the 'lindworm' and 'viper_root' model in assets/models/monsters/ in the original LoG2 assets.
#       It also fixes the hash_e5e1535f model from the .dat container (some sort of lindworm model)
#
#   Version 1.4.3
#       Added experimental normal re-generation for when dealing with ground foliage
#       Don't include any hidden nodes when exporting (sub-children will be excluded as well)
#       
#   Version 1.4.2
#       Fixed a bug where meshes didn't export if no root node existed above it
#       Added so that n-gon polygons are automatically selected when exporter is about to die
#
#   Version 1.4.1
#       Bug fix when importing models with multiple materials
#
#   Version 1.4
#       Support for exporting skinned animations
#       Animation import support for LoG 1
#       Animation export support for LoG 1
#
#   Version 1.3.2
#       Basic animation export for rigid objects
#
#   Version 1.3.1
#       Tools panel property to create game matrix when building models from scratch
#       Option to apply tangent transform to vertices during export if baked tangent normal map with game_matrix transform applied
#       Added Mikkelsens method for splitting quads
#       Animation importer no longer need to specify an armature
#       Animation importer can import animations even if nodes are missing
#       
#   Version 1.3
#       Support for model export
#       Added material creation when importing models
#
#   Version 1.2
#       Added support for animation import
#   
#   Version 1.1
#       Added node hierarchy support and skinning
#
#   Version 1.0
#       Raw import of .model files
Last edited by minmay on Fri Dec 08, 2023 8:47 pm, edited 14 times in total.
Grimrock 1 dungeon
Grimrock 2 resources
I no longer answer scripting questions in private messages. Please ask in a forum topic or this Discord server.
User avatar
Skuggasveinn
Posts: 561
Joined: Wed Sep 26, 2012 5:28 pm

Re: Blender importer/exporter [1.5.0]

Post by Skuggasveinn »

This is fantastic news , I will try this out for sure and report back.
minmay wrote: Mon Jan 11, 2021 9:23 pm Tip: If you're making a new model, you might want to start by importing an existing Grimrock model anyway, because it will give you a Grimrock-compatible object hierarchy to work with. I especially recommend this for rigged models and double-especially recommend it for monster models.
WORD - this is what I have been doing for almost all the things I animate, what I did was to load the small_fish.model along with the small_fish_swim.animation , I then clear the animation and clear the transpose of the bones, delete the faces of the mesh, and save the blender file in that state. What I end up with is a two bone rig that I can expend on with more bones, ready to be parented to any mesh I then bring in but with bullet proof hierachy. Just keep the blend file so you always have a base to go from.

some fun blender session ahead :D

kind regards.
Skuggasveinn.
Link to all my LoG 2 assets on Nexus.
Link to all my LoG 1 assets on Nexus.
User avatar
Isaac
Posts: 3172
Joined: Fri Mar 02, 2012 10:02 pm

Re: Blender importer/exporter [1.5.0]

Post by Isaac »

Thank you for doing this minmay! Image
User avatar
maneus
Posts: 246
Joined: Mon Jun 17, 2013 10:42 pm
Location: Switzerland

Re: Blender importer/exporter [1.5.0]

Post by maneus »

Thanks a lot minmay. Thumbs Up!
User avatar
maneus
Posts: 246
Joined: Mon Jun 17, 2013 10:42 pm
Location: Switzerland

Re: Blender importer/exporter [1.5.0]

Post by maneus »

I have a question about the Blender 2.92.0 release and the new importer/exporter 1.5.0:

I installed it in Blender 2.92.0 and activated it, but it doesn´t work.
There is a note right of the add-on line that says "Upgrade to 2.8x needed".

Does anyone know how to solve this little problem?
User avatar
Isaac
Posts: 3172
Joined: Fri Mar 02, 2012 10:02 pm

Re: Blender importer/exporter [1.5.0]

Post by Isaac »

I am using Blender v 2.92.0, with the 1.5.0 script, and do not have this error. :? (Import/Export of models & animation are working.)

Image
User avatar
maneus
Posts: 246
Joined: Mon Jun 17, 2013 10:42 pm
Location: Switzerland

Re: Blender importer/exporter [1.5.0]

Post by maneus »

Okay, found out today, that the version I installed was 1.4.4. I dowloaded it again and now it worked. Thank you.
User avatar
maneus
Posts: 246
Joined: Mon Jun 17, 2013 10:42 pm
Location: Switzerland

Re: Blender importer/exporter [1.5.0]

Post by maneus »

If I save an animation as a "Legend of Grimrock" animation with Blender 2.92, it is not recognized in the editor as a LoG animation,
but as a LoG2 animation. I get the following error message when I try to open it in the editor:

Image

The saved animation has a size of 10kb instead of 37kb (when I create the animation with GrimFBX).
User avatar
Isaac
Posts: 3172
Joined: Fri Mar 02, 2012 10:02 pm

Re: Blender importer/exporter [1.5.0]

Post by Isaac »

The animation format was a principle change between LoG1 & 2. LoG2 animations won't work in LoG1.

In the animation export panel, you must select the animation format that you wish to export.
Image
User avatar
maneus
Posts: 246
Joined: Mon Jun 17, 2013 10:42 pm
Location: Switzerland

Re: Blender importer/exporter [1.5.0]

Post by maneus »

Isaac, yes I know that fact (it´s not my first animation). ;)
But, if you choose LoG1 animation (in Blender 2.92), the exported animation did not work. (As I wrote in my post)
And your photo was taken with Blender 2.7x, but I speak of the Blender importer/exporter 1.5.0 and Blender 2.92.
But thank you for your reply.
Post Reply