space-game/docs/BLENDER_EXPORT.md

Blender Export Utility

Automated export of Blender .blend files to GLB format using Blender's command-line interface.

Installation

First, install the required dependencies:

npm install

This will install tsx and @types/node which are needed to run the export scripts.

Requirements

• Blender: Must be installed on your system
  • macOS: Install from blender.org (will be at /Applications/Blender.app)
  • Windows: Install to default location (C:\Program Files\Blender Foundation\Blender\)
  • Linux: Install via package manager (sudo apt install blender)

Usage

Basic Export

Export a single .blend file to .glb:

npm run export-blend -- public/ship1.blend public/ship1.glb

Watch Mode

Automatically re-export when the .blend file changes:

npm run export-blend -- public/ship1.blend public/ship1.glb --watch

This is useful during development - save your Blender file and it will auto-export!

Batch Export

Export all .blend files in a directory:

npm run export-blend -- public/ public/ --batch

This will:

• Find all .blend files in public/
• Export each to .glb with the same name
• Skip .blend1 backup files

Compression

Enable Draco mesh compression for smaller file sizes:

npm run export-blend -- public/ship1.blend public/ship1.glb --compress

Advanced Options

# Don't apply modifiers during export
npm run export-blend -- input.blend output.glb --no-modifiers

# Combine options
npm run export-blend -- input.blend output.glb --watch --compress

Programmatic Usage

You can also use the export functions directly in your TypeScript code:

import { exportBlendToGLB, batchExportBlendToGLB, watchAndExport } from './src/utils/blenderExporter';

// Single export
async function exportMyModel() {
  const result = await exportBlendToGLB(
    './models/ship.blend',
    './public/ship.glb',
    {
      exportParams: {
        export_draco_mesh_compression_enable: true,
        export_apply_modifiers: true,
        export_animations: true
      }
    }
  );

  console.log(`Exported in ${result.duration}ms`);
}

// Batch export
async function exportAllModels() {
  const results = await batchExportBlendToGLB([
    ['./models/ship1.blend', './public/ship1.glb'],
    ['./models/ship2.blend', './public/ship2.glb'],
    ['./models/asteroid.blend', './public/asteroid.glb']
  ], {
    exportParams: {
      export_draco_mesh_compression_enable: true
    }
  });

  console.log(`Exported ${results.length} files`);
}

// Watch for changes
function watchMyModel() {
  const stopWatching = watchAndExport(
    './models/ship.blend',
    './public/ship.glb',
    {
      exportParams: {
        export_apply_modifiers: true
      }
    }
  );

  // Call stopWatching() when you want to stop
  setTimeout(() => {
    stopWatching();
  }, 60000); // Stop after 1 minute
}

Export Parameters

The following glTF export parameters are supported:

Parameter	Type	Default	Description
export_format	'GLB' | 'GLTF_SEPARATE' | 'GLTF_EMBEDDED'	'GLB'	Output format
export_draco_mesh_compression_enable	boolean	false	Enable Draco compression
export_apply_modifiers	boolean	true	Apply modifiers before export
export_yup	boolean	true	Use Y-up coordinate system
export_animations	boolean	true	Export animations
export_materials	'EXPORT' | 'PLACEHOLDER' | 'NONE'	'EXPORT'	Material export mode

See Blender's glTF export documentation for all available parameters.

Troubleshooting

"Blender executable not found"

Solution: Set a custom Blender path:

await exportBlendToGLB('input.blend', 'output.glb', {
  blenderPath: '/custom/path/to/blender'
});

Or for the CLI, edit the blenderExporter.ts file to update getDefaultBlenderPath().

"Export timed out"

Solution: Increase the timeout (default is 60 seconds):

await exportBlendToGLB('large-model.blend', 'output.glb', {
  timeout: 120000 // 2 minutes
});

Output file not created

Check that:

1. The .blend file opens in Blender without errors
2. The output directory exists
3. You have write permissions to the output directory
4. Check the console for Blender error messages

Example Workflow

Here's a typical development workflow:

# Terminal 1: Run the dev server
npm run build

# Terminal 2: Watch your ship model
npm run export-blend -- public/ship2.blend public/ship2.glb --watch --compress

# Now edit ship2.blend in Blender
# Every time you save, it will auto-export to ship2.glb
# Refresh your browser to see changes

Integration with Build Process

You can add the batch export to your build process:

{
  "scripts": {
    "prebuild": "npm run export-blend:batch -- public/ public/",
    "build": "tsc && vite build"
  }
}

Now all .blend files will be exported before every build!

Performance Tips

1. Use compression for production: Add --compress flag to reduce file sizes by ~50-70%
2. Batch exports are sequential: Large batches may take time
3. Watch mode debounces: Changes are detected with 1-second delay to avoid excessive exports
4. Optimize your models: Lower poly counts export faster

Current Project Models

Here are the .blend files currently in the project:

# Export all current models
npm run export-blend -- public/ship1.blend public/ship1.glb
npm run export-blend -- public/ship2.blend public/ship2.glb
npm run export-blend -- public/asteroid4.blend public/asteroid4.glb
npm run export-blend -- public/base.blend public/base.glb

# Or batch export all at once
npm run export-blend:batch -- public/ public/