Discord: https://discord.gg/FreyDm5MK9
What is the Simple Blender Pipeline?
Recomposition
Material Management
Collision Shape Generation
Blender Options
Misc Fixes
Importing Your Blend File
Recomposition
Default Material Settings
Blender Settings
Advanced Options
Misc Features
When I drag the .blend file into a scene nothing happens
I'm saving my .blend file but it's not updating the unpacked nodes in the scene tree
The output messages are annoying
Disabling the addon doesn't fully disable it
The Simple Blender Pipeline is an addon for both Blender and Godot that aims to make using .blend files in Godot easier. It leverages Godot's node structure to allow the user to easily recompose the objects of a .blend file after importing it into Godot. The addon also aims to resolve some long-standing issues with the default import pipeline. This addon is not a "kitchen sink" addon, it only focuses on what I think are the most pressing issues when working with .blend files. My main focus is for the addon to be lightweight and intuitive to use.
-
Automatic unpacking of .blend files when dragging its .tscn file into an open scene.
-
SBP will take each individual object in the .blend file and add it to the current scene as its own MeshInstance3D.
-
You can then reorganize each of these MeshInstances as you see fit in your scene tree.
-
If you make changes to the .blend file, your scene tree structure in Godot will be maintained.
-
Iteration is easy thanks to a hot reload system! Simply press ctrl+s in Blender to see your changes in Godot!
recomposition_demo.mp4
-
In Project Settings, you can define default material settings for imported materials.
-
These project settings can be overridden via the Blender addon if you need a specific material to have unique settings.
project_settings_demo.mp4
-
Mesh objects can be tagged to auto generate CollisionShape3Ds on import.
-
These CollisionShape3Ds can be recomposed just like the MeshInstance3Ds, This allows you to easily set up physics bodies in your scene tree and have your scene tree structure be respected if you make changes to the blend file.
-
You can discard the mesh object if you only want the CollisionShape3D.
-
The debug visuals in the Godot editor can be automatically hidden on import, this is useful for when you don't want your level geometry to be covered in a z-fighting blue mesh while working.
collision_shape_demo.mp4
-
The Blender plugin features the option to save your blend file in a location outside of your Godot project and then push the save to your Godot directory when you're ready to push an update.
-
You can also set .blend file-wide default settings. These settings are overidden by individual settings on objects.
-
The Metallic Specular setting on materials can now be controlled using the Specular IOR setting in Blender.
-
You now have additional Godot-specific options that can be set inside of Blender. This includes things like mesh transparency, stencil buffer settings, and more.
Begin with downloading the newest release of the addon from the Releases Page. This will be the 'simple_blender_pipeline_1.x.x.zip'. Inside of the zip will be an addon for Godot and an addon for Blender.
Open the 'simple_blender_pipeline_1.x.x.zip/godot' folder. Inside you will find an 'addons' folder. Extract this 'addons' folder to your Godot project's root directory. The file system should look like this:
Next, go to 'Project>Project Settings>Plugins' and enable the Simple Blender Pipeline addon.
Lastly, we need to go to 'Project>Project Settings>Import Defaults' and click on the dropdown menu next to 'Importer'. Select 'Scene' and scroll down to 'Import Script>Path' and click on the file browser icon to the right.
Navigate to 'addons/simple_blender_pipeline' and select the import_script.gd file. Press the save button near the bottom of the window and then restart Godot to insure that the addon is initialized properly.
You're done installing the Godot addon! It's recommended that you go ahead and create a folder for storing your blend files. Inside of your new blend folder, you will want to create a folder named "textures". If this folder doesn't already exist when importing a blend file, Godot will make the folder automatically but the SBP addon might glitch a bit as a result. One more thing to note, if you already have blend files imported into your project before installing the addon, you will need to manually assign the import script to them in Godot's importer menu.
Open the 'simple_blender_pipeline_1.x.x.zip/blender' folder. Extract the 'simple_blender_pipeline_gd_1.x.x.zip' to somewhere that you can easily find it. Now open a new Blender project and navigate to 'Edit>Preferences>Addons', click the dropdown arrow in the top right and select 'Install from Disk'.
Navigate to where you extracted the 'simple_blender_pipeline_gd_1.x.x.zip' and select it. Make sure that this is the correct zip with the "gd" in it's name and not the zip that contains both plugins! The plugin is now installed, quickly double check that it's enabled with the checkbox checked next to the addon.
Now close the Preferences window and navigate to 'File>External Data' and make sure that 'Automatically Pack Resources' is checked.
Navigate to 'File>Defaults' and select 'Save Startup File'. This will ensure that the 'Automatically Pack Resources' setting is always checked in new blend files. It's important to note that this might not be desireable behavior in all usages of Blender, so this may need to be manually disabled when not using Blender for the SBP plugin. This can be undone by simply unchecking the 'Automatically Pack Resources' and resaving the startup file.
The installation of the Blender addon is complete! You can access the addon by pressing the 'n' key, you will see the Simple Blender Pipeline GD tab in the main viewport.
Now that we have both addons installed we will begin exploring the features of the Simple Blender Pipeline!
Upon adding your blend file to your Godot project, Godot will automatically convert it internally to a .tscn file. When you drag this file into an open scene's scene tree, you will see a BlendFileUnpacker node, as well as a new "_unpacked" Node3D with the objects of the blend file as children. So long as the BlendFileUnpacker node is in the scene tree, you now have a hot reload link established. If you make changes to the blend file and press ctrl+s then those changes will automatically be reflected in Godot. The BlendFileUnpacker node can be deleted if you believe that you no longer need to make changes to the blend file. If you ever need to re-establish this link, simply re-add the blend file to the scene tree and it will generate a new BlendFileUnpacker.
import_demo.mp4
One important thing to note about the hot reloading link is that the scene must be open for the hot reload to work automatically. If the currently open tab does not contain the blend scene you're updating, the update will fail. The output window will notify you of any blend files that were not updated, as well as BlendFileUnpacker nodes will change their icon to reflect that they are out of date. Simply pressing the 'Reload' button on the BlendFileUnpacker will resync with your blend file. If you're worried that there may be un-updated BlendFileUnpackers in your project, you can click the 'Scan' button on any BlendFileUnpacker and you will get a list of un-updated nodes in the output window. This is an unfortunate limitation of the engine but I've done my best to mitigate any annoyances.
hot_reload_demo.mp4
You can reparent any of the nodes under the "Unpacker" node. When you make changes to the .blend file, the unpacked nodes will maintain their position in the scene tree. This allows you to create blend files that contain models for multiple different uses that can be easily updated in the future. You can also combine this functionality with the collision shape generation to automatically create a collision shape for a mesh and then reparent it to a physics body. If you make changes to the mesh in Blender, those changes will automatically be reflected in Godot regardless of where it is in the scene tree.
recomposition_demo_2.mp4
In Project Settings you can define the default settings for materials when they're imported into the engine. This can be useful for games that have a ubiquitous artstyle. Are you making a retro psx game with pixelated textures? Set the default texture filter to 'Nearest'. Are you making a game with toon shading? Set the diffuse and specular modes to 'Toon'. If you run into a rare situation where the overridden defaults aren't desireable, you can either revert them in the project settings or use the 'Override Project Settings' option in the Blender addon.
project_settings_demo_2.mp4
By default when you update your blend file, Godot will automatically apply certain default settings to the imported tscn file. As a result, if you want an imported MeshInstance3D to have it's transparency set to 0.5 you will need to change this setting manually everytime that you update your blend file. This is where the Simple Blender Pipeline comes in! In the Blender addon, you can define both mesh and material overrides to ensure that your changes are respected. Some of these override options are redundant (such as texture filtering for example) but I chose to include them in the addon due to them either being slightly obscured in Blender or them not having full feature parity with Godot. There are even some overrides that allow access to previously inaccessible settings like Godot's stencil buffer. All settings are stored per object in its custom properties. You can still set your own custom properties, just make sure that they don't include "sbp" in their name as that's how the addon finds relevant metadata.
blender_settings_demo.mp4
The Blender addon also features an advanced options menu. If you don't want every ctrl+s to automatically be pushed to your Godot project, you can save your .blend file outside of the project and instead use the 'Save Blend File to Godot' menu under 'Advanced Options'. Simply set the name of the file and choose where it will be saved and then press 'Save Blend' when you are ready to push changes to your Godot project! The advanced options menu also allows you to set .blend-wide override settings. For example, If you want everything in your .blend file to have 'Nearest' filtering applied by default, add a .blend override and set it's texture filtering. It's important to note that individual object overrides supercede a .blend-wide override. So if you want everything to be 'Nearest' filtering except for one object, simply set the exception's texture override to 'Linear'.
advanced_settings_demo.mp4
By default the addon does a few things, most of which can be disabled in the Project Settings in Godot.
- Specular IOR in Blender is used for the Metallic Specular setting on Godot materials.
- Float Arrays in Blender Custom Properties are automatically converted into Vector metadata in Godot.
- The Coat Tint property in Blender is used for the Stencil Color in Godot. This is a compromise to be able to properly store color data and may not be desireable if you're actually using the Coat Tint for something.
- All SBP metadata on meshes is automatically removed after import. This helps to declutter your imported mesh metadata if you have your own custom properties attached.
Make sure that the blend file has it's import script set to import_script.gd. You can check this by double clicking the blend file in the FileSystem tab. Blend files that were imported BEFORE installing the plugin will not have the import script automatically attached.
The addon's hot reload only works if the BlendFileUnpacker is present in the scene, and that scene tab is currently focused in the editor. If you are on a different open scene tab, the addon is unable to update the unpacked nodes automatically. Changes are still being made to the .blend file, you just need to navigate to the BlendFileUnpacker node and press 'Reload' to update. It's also good practice to periodically use the 'Scan' button on BlendFileUnpacker nodes to see if there's any scenes that are not up to date.
This can be disabled in the Project Settings under Simple Blender Pipeline>Settings>Print Updates.
To temporarily disable the addon, there's a setting under Project Settings that will fully stop functionality of the addon if set to true. If you wish to uninstall the addon, simply work your way backwards through the installation guide and delete all BlendFileUnpacker nodes from your project.