BBMOD Blender
August 3, 2026 ยท View on GitHub
Import and export BBMOD models, BBANIM actions, and BBMAT materials directly from Blender!
Table of Contents
About
BBMOD Blender is an addon for Blender that brings the BBMOD pipeline into your DCC of choice. It exports your scenes into the formats used by BBMOD for GameMaker:
.bbmod- 3D models with meshes, nodes, bones, and vertex attributes.bbanim- skeletal animations sampled from armature actions.bbmat- materials with textures, blending, culling, and render pass shaders
The addon is designed to be used together with BBMOD, which loads these files at runtime. For more info, please see the BBMOD homepage https://blueburn.cz/bbmod/.
Installation
- Requires Blender 5.1 or newer.
- Download the addon as
io_scene_bbmod.zipfrom Releases page. - In Blender, go to
Edit > Preferences > Add-ons > Install from Disk, select the ZIP file, and enable the addon.
The addon registers under File > Import and File > Export.
Usage
Select the root object(s) of what you want to export (or leave nothing selected to export the whole scene), then use
File > Export > BBMOD Model (.bbmod). A .bbmod file is written for the model, plus one .bbmat file per material
and one .bbanim file per action of the armature (when enabled).
Export options
- General - export only the selection, triangulate n-gons, write a conversion log file.
- Transform - optimization level (None / Static / Animated), up axis, mirror, flip UV Y.
- Vertex Attributes - which vertex attributes to include (bones, normals, tangents, UV, UV2, vertex colors).
- Material Export - everything related to BBMAT files, see Material export.
- Animation - whether to export BBANIM files, which bone spaces to include (Parent / World / Bone), and the sampling rate in FPS (0 matches the scene FPS). Exporting an armature without animations, or no armature at all, is not an error - the animation export is simply skipped.
Material export
The material type dropdown controls which base material the exported BBMAT uses:
| Material Type | __MaterialName written |
|---|---|
| Default | BBMOD_MATERIAL_DEFAULT (forward renderer) |
| Deferred | BBMOD_MATERIAL_DEFERRED (deferred renderer) |
When a material contains a texture whose image name contains lightmap, it is packed into the BBMAT's Lightmap
texture slot (RGBM) and the material automatically becomes BBMOD_MATERIAL_DEFAULT_LIGHTMAP.
Texture slot mapping
The addon reads the Principled BSDF node tree of each material. An image connected to the corresponding input is written into the matching BBMAT texture slot. When a slot is not connected, the image is looked up by name keywords:
| BBMAT slot | Principled input / name keyword |
|---|---|
| Base | Base Color, or basecolor / base_color / albedo / diffuse / color |
| Alpha | Alpha |
| Normal | Normal, with flip normal Y option |
| Roughness | Roughness |
| Metallic | Metallic |
| Emissive | Emission Color |
| Lightmap | image named with lightmap |
| AO | image named with ao |
| Subsurface | Subsurface Color / Subsurface Weight |
Blending and alpha testing
Alpha blending is content driven: a material gets AlphaBlend: true only when its alpha actually contains
semi-transparent pixels (values strictly between 0.01 and 0.99). Purely opaque materials and cutouts (0/1 alpha)
do not blend - cutouts are rendered with AlphaTest instead. The AlphaTest value is 0.1 for blended materials and
0.9 otherwise (CLIP materials use Blender's alpha_threshold).
Render pass shaders
The Render Pass Shaders checkboxes control which passes are written into the BBMAT's Shaders section:
| Pass | Shader written | Default |
|---|---|---|
| Shadows | BBMOD_SHADER_DEFAULT_DEPTH | on |
| Depth Only | BBMOD_SHADER_DEFAULT_DEPTH | on |
| Id | BBMOD_SHADER_INSTANCE_ID | on |
| Reflection Capture | BBMOD_SHADER_DEFAULT | off |
Selecting the Deferred material type automatically unchecks Depth Only (and Default re-checks it), since the
deferred renderer does not need it. When all passes are disabled, the Shaders section is omitted entirely.
Texture filtering
The Texture Filtering dropdown writes the Mipmapping property of the BBMAT: mip_markedonly (default), mip_on,
or mip_off. With mip_markedonly, mipmaps are generated only for textures marked for mipmapping in the engine.
Import
File > Import > BBMOD Model (.bbmod) imports the model, its materials, and its actions. The import options mirror the
export ones - up axis, mirror, and flip UV Y - so files written by this addon round-trip correctly. BBMAT and BBANIM
files can also be imported on their own.
Development
The addon lives in io_scene_bbmod/, with a tests/ folder for the unit tests. The tests do not require Blender and
run with a plain Python interpreter (only numpy is needed):
python -m unittest discover -s tests
material_export.py/material_import.py- BBMAT packing, texture sampling and slot detectionexporters.py/importers.py- BBMOD and BBANIM reading and writingbbmod_format.py/bbmat_format.py/bbanim_format.py- the file format implementationsbinary.py- low-level binary reader/writertypes.py- in-memory model, mesh, bone, node, and animation types
License
BBMOD Blender is available under the MIT license. Full text is available here.