Lightmapping

Bake realistic lighting and shadows directly in Blender and export them to the web for stunning visuals with excellent performance.

What is Lightmapping?

Lightmapping is the process of pre-calculating lighting and baking it into textures. This gives you:

Benefits:

• ✨ Photorealistic lighting - Bake complex lighting calculations once
• ⚡ Great performance - No real-time lighting calculations needed
• 🎨 Artistic control - Fine-tune lighting in Blender
• 📦 Small file sizes - Compressed lightmap textures
• 🔄 Multiple instances - Each instance can have unique lightmaps

Use Cases:

• Architectural visualization
• Product showcases with dramatic lighting
• Art galleries and museum experiences
• Any scene with static lighting

Requirements

Before you start:

• At least one light in your scene
• Objects marked as Lightmapped in the Needle Object panel
• Blender's lighting set up the way you want it

Quick Start

Step 1: Mark Objects for Lightmapping

For Mesh Objects:

1. Select your mesh object
2. Open the Needle Object panel (Object Properties tab)
3. Enable the Lightmapped checkbox

For Lights:

1. Select your light
2. Open the Needle Object panel
3. Enable Lightmapped to include it in baking

Step 2: Configure Settings

You can configure lightmapping from two places:

Option A: Scene Panel (Quick Access)

Open the Needle tab in the 3D viewport's sidebar (press N to toggle).

Option B: Render Properties (Full Settings)

Go to Render Properties tab and find the Lightmapping panel.

Step 3: Bake Lightmaps

1. Click the Bake button (in either panel)
2. Wait for baking to complete (progress shows in Blender)
3. Lightmaps are automatically exported with your scene

What Happens:

• Needle Engine generates lightmap UVs automatically (no manual UV unwrapping needed!)
• Blender bakes lighting into textures
• Textures are saved in your project
• Export includes lightmap data

Lightmap Settings Explained

Resolution

Lightmap Resolution - Texels per unit

• Higher = better quality, larger files
• Lower = faster baking, smaller files
• Recommended: 10-50 for most scenes

Quality

Samples - Render samples for baking

• More samples = cleaner results, slower baking
• Fewer samples = faster but noisier
• Recommended: 128-512 for production

Denoise - Remove noise from baked lightmaps

• Enable for cleaner results
• Requires Blender's denoiser

Advanced

Max Lightmap Size - Maximum texture size

• Limits memory usage
• Recommended: 2048 or 4096

Pack Margin - Padding between UV islands

• Prevents light bleeding between objects
• Recommended: 4-16 pixels

Automatic UV Generation

Needle Engine's lightmapping plugin automatically generates lightmap UVs - no manual unwrapping required!

How it works:

• Analyzes your geometry
• Creates optimal UV layouts
• Packs efficiently into texture space
• Handles multiple instances intelligently

This means:

• ✅ No second UV channel needed
• ✅ Works with complex models
• ✅ Supports instanced objects with unique lighting

Best Practices

Scene Setup

Lighting:

• Use area lights for soft, natural lighting
• Combine sun light with fill lights for outdoor scenes
• Add rim lights to highlight edges
• Consider color temperature (warm/cool)

Geometry:

• Ensure clean topology (no overlapping faces)
• Lightmap static architecture, not characters
• Use separate objects for elements that need different lightmap resolution

Performance:

• Only lightmap objects that benefit from it
• Use lower resolution for background elements
• Compress textures in production builds

Troubleshooting

Black or dark lightmaps:

• Check that lights are marked as Lightmapped
• Increase render samples
• Verify normals are correct (consistent face orientation)

Seams or artifacts:

• Increase Pack Margin setting
• Check for overlapping UV islands
• Ensure geometry is watertight (no gaps)

Too slow:

• Reduce lightmap resolution
• Reduce render samples
• Bake in sections (bake one object at a time)

File too large:

• Lower lightmap resolution
• Reduce Max Lightmap Size
• Enable texture compression in production builds

Workflow Tips

Iterative Baking

While developing:

1. Use lower resolution and fewer samples for fast iteration
2. Mark only key objects as lightmapped initially
3. Test in browser frequently
4. Increase quality for final bake

Combining with Real-Time Lighting

You can mix lightmaps with dynamic lights:

• Use lightmaps for static ambient lighting
• Add dynamic point lights for moving elements
• Result: Beautiful base lighting + interactive highlights

Multiple Lightmap Scenarios

Bake different lighting conditions:

• Day/night versions
• Different seasons
• Dramatic vs. natural lighting
• Switch between them at runtime

Exporting Lightmaps

Lightmaps are exported automatically when you:

1. Save your .blend file (if auto-export is enabled)
2. Click Export in the Needle Project panel
3. Run Build: Production

Output:

• Lightmap textures saved in your project's assets folder
• GLB file includes lightmap data
• Ready to use on the web - no additional setup needed

Advanced: Runtime Control

You can control lightmaps from TypeScript:

import { Behaviour, Renderer } from "@needle-tools/engine";

export class LightmapSwitcher extends Behaviour {

    switchToNightLightmaps() {
        const renderers = this.gameObject.getComponentsInChildren(Renderer);
        for (const renderer of renderers) {
            // Access and modify lightmap data
            // (specific API depends on your setup)
        }
    }
}

Experimental Feature Notice

Next Steps

• Texture Compression - Optimize lightmap file sizes
• Deployment Guide - Publish your lightmapped scenes
• Components Overview - Add interactivity to lit scenes

Need Help?

• Discord Community - Ask about lightmapping workflows
• Forum - Share your lightmapped scenes
• Download Example - Working lightmap sample