Minecraft Model Converter - Blockbench to MonoGame

A converter tool that transforms static Minecraft models from Blockbench format (.bbmodel) to MonoGame-compatible vertex data.

Features

• Converts Blockbench .bbmodel files to MonoGame vertex data
• Supports multiple textures per model
• Generates both C# code and JSON data files
• Handles cube geometry with proper normals and UV mapping
• Compatible with MonoGame's VertexPositionNormalTexture format

Usage

dotnet run <input.bbmodel> <output_directory>

Examples

# Convert a Blockbench model to MonoGame format
dotnet run models/creeper.bbmodel output/

# This will generate:
# output/Creeper.cs - C# class with vertex/index data
# output/creeper_data.json - JSON data file for runtime loading

Output Files

The converter generates two types of files:

1. C# Model Class (e.g., Creeper.cs)

Contains static methods to get vertex data, indices, and texture names:

var vertices = Creeper.GetVertices();
var indices = Creeper.GetIndices();
var textureNames = Creeper.GetTextureNames();

2. JSON Data File (e.g., creeper_data.json)

Contains the model data in JSON format for runtime loading.

Using in MonoGame

Here's how to use the generated model in your MonoGame project:

// Using the generated C# class
var vertices = YourModel.GetVertices();
var indices = YourModel.GetIndices();
var textureNames = YourModel.GetTextureNames();

// Create vertex and index buffers
var vertexBuffer = new VertexBuffer(GraphicsDevice, typeof(VertexPositionNormalTexture), 
    vertices.Count, BufferUsage.WriteOnly);
vertexBuffer.SetData(vertices.ToArray());

var indexBuffer = new IndexBuffer(GraphicsDevice, typeof(int), 
    indices.Count, BufferUsage.WriteOnly);
indexBuffer.SetData(indices.ToArray());

// Load textures
var textures = new Texture2D[textureNames.Length];
for (int i = 0; i < textureNames.Length; i++)
{
    textures[i] = Content.Load<Texture2D>(textureNames[i]);
}

Supported Blockbench Features

• ✅ Cube elements with position and size
• ✅ Face textures and UV mapping
• ✅ Multiple textures per model
• ✅ Element names and organization
• ⚠️ Basic rotation support (may need adjustment)
• ❌ Animation data (static models only)
• ❌ Complex geometry (cubes only)

Coordinate System

The converter transforms Blockbench coordinates to MonoGame:

• Blockbench uses pixel units (16 pixels = 1 block)
• MonoGame output uses world units (1.0f = 1 unit)
• Coordinates are divided by 16 during conversion

Requirements

• .NET 6.0 or later
• MonoGame.Framework.DesktopGL 3.8.1.303
• Newtonsoft.Json 13.0.3

Building

dotnet build
dotnet run -- models/your_model.bbmodel output/

Tips for Blockbench Models

1. Use consistent texture sizes (recommended: 16x16, 32x32, 64x64)
2. Name your elements descriptively for better generated code
3. Keep models relatively simple for better performance
4. Test UV mapping carefully as coordinate systems differ

Troubleshooting

• Invalid dimensions: Check that your Blockbench elements have valid from/to coordinates
• Missing textures: Ensure texture paths are correctly set in Blockbench
• UV mapping issues: Verify texture coordinates in Blockbench match expected output

Contributing

Feel free to submit issues or pull requests to improve the converter!