firefrost-operations-manual/docs/tasks/blender-cinematic-workflow/DEPLOYMENT-GUIDE.md

# Blender Cinematic Workflow — Deployment Guide

**Task:** Install and configure Blender-based cinematic production workflow  
**Audience:** Michael, Holly, future Firefrost staff  
**Time Estimate:** 45-60 minutes (first-time setup)  
**Difficulty:** Beginner-friendly  
**Prerequisites:** Windows laptop, Minecraft with Replay Mod (Forge port)

---

## What This Guide Does

By the end of this guide, you will have:

1. ✅ Blender 4.0+ installed and configured
2. ✅ MCprep addon installed and working
3. ✅ Mineways installed for world exports
4. ✅ PowerShell launcher script on your desktop
5. ✅ Hand-accessible settings enabled
6. ✅ Verification test completed (export → import → render)

**Why we're doing this:** Moving cinematic editing from Minecraft's Replay Mod (physically taxing, limited quality) to Blender (hand-friendly, professional ray-traced lighting).

---

## Part 1: Install Blender

### Step 1.1: Download Blender

1. Open your web browser
2. Go to: **https://www.blender.org/download/**
3. Click the big blue **"Download Blender"** button
4. The website will automatically detect you're on Windows
5. Wait for the download to complete (file will be named something like `blender-4.0.2-windows-x64.msi`)

**File size:** Approximately 300 MB  
**Download time:** 2-5 minutes depending on internet speed

### Step 1.2: Install Blender

1. **Find the downloaded file:**
   - Open your **Downloads** folder
   - Look for the file starting with `blender-4.0`

2. **Run the installer:**
   - Double-click the `.msi` file
   - Windows might show a security warning — click **"Run"** or **"Yes"**

3. **Installation wizard:**
   - Click **"Next"** on the welcome screen
   - **License agreement:** Click **"I accept"**, then **"Next"**
   - **Installation location:** Leave as default (`C:\Program Files\Blender Foundation\Blender 4.0\`) — click **"Next"**
   - Click **"Install"**
   - Wait 2-3 minutes for installation
   - Click **"Finish"**

4. **First launch:**
   - Blender should open automatically
   - You'll see a "Blender Quick Setup" window
   - **Important settings for hand accessibility:**
     - Under "Shortcuts," select **"Blender"** (default is fine)
     - Under "Theme," pick whatever you like (doesn't affect workflow)
     - Click **"Next"**
   - Click **"Save New Settings"**

5. **Verify Blender is working:**
   - You should see a gray window with a cube in the center
   - In the top-left corner, you should see: `Blender 4.0.x` (or higher)
   - **Close Blender for now** (File → Quit, or just click the X)

✅ **Checkpoint:** Blender is installed and launches successfully.

---

## Part 2: Install MCprep Addon

MCprep is a plugin that automates Minecraft material setup in Blender. It fixes transparency on leaves/glass and adds glow to torches automatically.

### Step 2.1: Download MCprep

1. Open your web browser
2. Go to: **https://theduckcow.com/dev/blender/mcprep/**
3. Click the green **"Download MCprep"** button
4. The file will be named something like `MCprep_addon_3_5_3.zip`
5. **DO NOT UNZIP THIS FILE** — Blender needs the .zip as-is

**File size:** Approximately 15 MB  
**Download time:** 10-30 seconds

### Step 2.2: Install MCprep in Blender

1. **Open Blender** (double-click the icon on your desktop or in Start menu)

2. **Open Preferences:**
   - At the top of the screen, click **Edit** → **Preferences**
   - A new window will open

3. **Go to Add-ons section:**
   - On the left side of the Preferences window, click **"Add-ons"**

4. **Install the addon:**
   - At the top-right of this window, click the **"Install..."** button
   - A file browser will open
   - Navigate to your **Downloads** folder
   - Find the file `MCprep_addon_3_5_3.zip` (or similar name)
   - Click on it once to select it
   - Click **"Install Add-on"** button in bottom-right

5. **Enable the addon:**
   - The Preferences window will now show a search box
   - Type: **mcprep**
   - You should see **"Import-Export: MCprep"** appear
   - **Click the checkbox** next to it to enable it
   - You should see the checkbox turn blue/checked

6. **Verify installation:**
   - Look at the right side of the screen (the tall panel)
   - Press the **N** key on your keyboard (this toggles the side panel)
   - You should see a tab labeled **"MCprep"** appear at the top
   - Click on that **MCprep** tab
   - You should see buttons like "Prep Materials" and "Spawn Mob"

7. **Save settings:**
   - At the bottom-left of the Preferences window, click the **≡** menu icon (three lines)
   - Click **"Save Preferences"**
   - Close the Preferences window

✅ **Checkpoint:** MCprep addon is installed and visible in the N-Panel.

---

## Part 3: Install Mineways

Mineways exports Minecraft world chunks as 3D files that Blender can import.

### Step 3.1: Download Mineways

1. Open your web browser
2. Go to: **https://www.realtimerendering.com/erich/minecraft/public/mineways/**
3. Scroll down to the **"Download"** section
4. Click the link: **"Mineways version [latest] installer"**
5. File will be named something like `mineways_9.12_installer.exe`

**File size:** Approximately 30 MB  
**Download time:** 30-60 seconds

### Step 3.2: Install Mineways

1. **Find the downloaded file:**
   - Open your **Downloads** folder
   - Look for `mineways_9.12_installer.exe` (or similar)

2. **Run the installer:**
   - Double-click the `.exe` file
   - Windows might show a security warning — click **"Run"** or **"Yes"**

3. **Installation wizard:**
   - Welcome screen: Click **"Next"**
   - License agreement: Click **"I Agree"**
   - Installation location: Leave as default — click **"Next"**
   - Start menu folder: Leave as default — click **"Install"**
   - Wait 15-30 seconds
   - **IMPORTANT:** Uncheck "View README.txt" before clicking **"Finish"**
   - Click **"Finish"**

4. **First launch test:**
   - Press **Windows key** on your keyboard
   - Type: **mineways**
   - Click **"Mineways"** when it appears
   - A window should open showing a file browser
   - **You can close Mineways for now** — we're just verifying it works

✅ **Checkpoint:** Mineways is installed and launches successfully.

---

## Part 4: Enable Hand-Accessible Settings in Blender

These settings reduce the need for precise clicking and dragging.

### Step 4.1: Enable Emulate Numpad

**Why:** Most laptops don't have a number pad on the right side. This setting lets you use the regular number keys (1-9, 0) for camera views.

1. **Open Blender**
2. Go to **Edit** → **Preferences**
3. On the left side, click **"Input"**
4. Look for the section labeled **"Keyboard"**
5. Find the checkbox: **"Emulate Numpad"**
6. **Check the box** if it's not already checked
7. At the bottom-left, click **≡** → **"Save Preferences"**
8. Close Preferences window

### Step 4.2: Enable Camera to View (Per-Project Setting)

**Why:** This makes the camera follow your view as you navigate, so "filming" feels like playing Minecraft.

**Note:** This needs to be enabled each time you start a new Blender project. We'll include it in the production workflow.

1. In Blender, press **N** to open the side panel (if not already open)
2. Click the **"View"** tab at the top of the side panel
3. Scroll down to find **"View Lock"** section
4. Find the checkbox: **"Camera to View"**
5. **Check the box**
6. Now when you rotate your view (middle-mouse drag), the camera moves with you

✅ **Checkpoint:** Hand-accessible settings are configured.

---

## Part 5: Create the PowerShell Launcher Script

This script opens all three tools (Replay folder, Mineways, Blender) with one click.

### Step 5.1: Create the Script File

1. **Open Notepad:**
   - Press **Windows key**
   - Type: **notepad**
   - Press **Enter**

2. **Copy the script below:**

```powershell
# --- Firefrost Gaming Cinematic Suite Launcher ---
# Created: March 30, 2026
# Purpose: One-click launch of replay folder + Mineways + Blender

Write-Host "🔥❄️ Firefrost Gaming Cinematic Suite" -ForegroundColor Cyan
Write-Host "Initializing tools..." -ForegroundColor Yellow
Write-Host ""

# Auto-detect current user (no hardcoded paths)
$username = $env:USERNAME

# 1. Open the Replay Mod folder
$replayPath = "C:\Users\$username\AppData\Roaming\.minecraft\replay_recordings"
Write-Host "Opening Replay Mod folder..." -ForegroundColor Green
if (Test-Path $replayPath) {
    Invoke-Item $replayPath
    Write-Host "  ✓ Replay folder opened" -ForegroundColor Green
} else {
    Write-Host "  ✗ Replay folder not found at: $replayPath" -ForegroundColor Red
    Write-Host "    Check your Minecraft installation path" -ForegroundColor Yellow
}
Write-Host ""

# 2. Launch Mineways
$minewaysPath = "C:\Program Files (x86)\Mineways\mineways.exe"
Write-Host "Launching Mineways..." -ForegroundColor Green
if (Test-Path $minewaysPath) {
    Start-Process $minewaysPath
    Write-Host "  ✓ Mineways launched" -ForegroundColor Green
} else {
    Write-Host "  ✗ Mineways not found at: $minewaysPath" -ForegroundColor Red
    Write-Host "    Check installation location" -ForegroundColor Yellow
}
Write-Host ""

# 3. Launch Blender
$blenderPath = "C:\Program Files\Blender Foundation\Blender 4.0\blender.exe"
Write-Host "Launching Blender..." -ForegroundColor Green
if (Test-Path $blenderPath) {
    Start-Process $blenderPath
    Write-Host "  ✓ Blender launched" -ForegroundColor Green
} else {
    # Try Blender 4.1 or 4.2 paths
    $blenderPath = "C:\Program Files\Blender Foundation\Blender 4.1\blender.exe"
    if (Test-Path $blenderPath) {
        Start-Process $blenderPath
        Write-Host "  ✓ Blender launched (version 4.1)" -ForegroundColor Green
    } else {
        Write-Host "  ✗ Blender not found" -ForegroundColor Red
        Write-Host "    Check Blender installation" -ForegroundColor Yellow
    }
}
Write-Host ""

Write-Host "🎬 Cinematic Suite ready!" -ForegroundColor Cyan
Write-Host "Fire + Frost + Foundation = Where Love Builds Legacy" -ForegroundColor Magenta
Write-Host ""
Pause
```

3. **Save the script:**
   - Click **File** → **Save As**
   - **Save in:** Desktop (select from the left sidebar)
   - **File name:** Type exactly: `EditMode.ps1`
   - **Save as type:** Change from "Text Documents" to **"All Files (*.*)"**
   - Click **"Save"**

4. **Close Notepad**

### Step 5.2: Enable PowerShell Scripts (First Time Only)

Windows blocks scripts by default for security. We need to allow this one.

1. **Open PowerShell as Administrator:**
   - Press **Windows key**
   - Type: **powershell**
   - **Right-click** on "Windows PowerShell"
   - Click **"Run as administrator"**
   - Click **"Yes"** when Windows asks for permission

2. **Enable scripts:**
   - A blue window will open
   - Type this command exactly:
   ```
   Set-ExecutionPolicy RemoteSigned
   ```
   - Press **Enter**
   - Type: **Y**
   - Press **Enter** again

3. **Close PowerShell:**
   - Type: **exit**
   - Press **Enter**

### Step 5.3: Test the Launcher

1. **Find the script on your desktop:**
   - Look for `EditMode.ps1`

2. **Run the script:**
   - **Right-click** on `EditMode.ps1`
   - Click **"Run with PowerShell"**

3. **What should happen:**
   - A blue PowerShell window opens
   - You see colorful text showing what's launching
   - Your Replay Mod folder opens in File Explorer
   - Mineways launches
   - Blender launches
   - PowerShell window says "Press Enter to continue..."
   - Press **Enter** to close the PowerShell window

4. **If something doesn't launch:**
   - The script will show a red ✗ and tell you what's wrong
   - Most common issue: Replay folder path (Forge vs Fabric use different folder names)
   - You can edit the script in Notepad to fix paths if needed

✅ **Checkpoint:** Launcher script works and opens all three tools.

---

## Part 6: Verification Test (Export → Import → Render)

Let's test the entire workflow with a simple world export.

### Step 6.1: Get a World to Export

**Option A:** Use an existing single-player world  
**Option B:** Download a server backup from Pterodactyl panel

For this test, we'll use a single-player world:

1. **Locate your world saves:**
   - Press **Windows key + R**
   - Type: `%appdata%\.minecraft\saves`
   - Press **Enter**
   - A folder opens showing all your single-player worlds

2. **Pick a small world** (faster export for testing)
   - Any world will work
   - Note the folder name — you'll need this in Mineways

### Step 6.2: Export with Mineways

1. **Launch Mineways** (or use the EditMode.ps1 script)

2. **Open your world:**
   - Click **"File"** → **"Open World..."**
   - Navigate to: `C:\Users\[YourUsername]\AppData\Roaming\.minecraft\saves`
   - Click on the world folder you want to export
   - Click **"Select Folder"**

3. **You should see:**
   - A 2D map of your world appears in the window
   - You can zoom in/out with mouse wheel

4. **Select an area to export:**
   - **Left-click and drag** to draw a rectangle around the area you want
   - **Tip:** Start with a small area (like a single building) for your first test
   - The selected area will be highlighted

5. **Export settings:**
   - Click **"File"** → **"Export for Rendering..."**
   - A settings window opens

6. **Configure export:**
   - **Export location:** Click **"Choose..."** and pick your Desktop (easy to find)
   - **File name:** Type: `test-export`
   - **Export type:** Leave as **"Wavefront OBJ file"**
   - **Material options:**
     - Check: **"Export full materials"**
     - Check: **"Export blocks with textures"**
   - **Ignore these settings for now** — MCprep will fix materials later
   - Click **"Export"**

7. **Wait for export:**
   - Progress bar appears
   - Small exports: 10-30 seconds
   - Large exports: 1-5 minutes

8. **Verify export:**
   - Go to your Desktop
   - You should see a folder named `test-export`
   - Inside that folder: `test-export.obj` and a bunch of `.png` texture files

✅ **Checkpoint:** World exported successfully from Mineways.

### Step 6.3: Import into Blender

1. **Launch Blender** (or use EditMode.ps1)

2. **Delete the default cube:**
   - Click on the cube in the center (it turns orange when selected)
   - Press **Delete** key on your keyboard
   - A menu appears — click **"Delete"**

3. **Import the .obj file:**
   - Click **"File"** → **"Import"** → **"Wavefront (.obj)"**
   - Navigate to your Desktop → `test-export` folder
   - Click on `test-export.obj`
   - Click **"Import OBJ"** button in top-right

4. **Wait for import:**
   - This can take 15 seconds to 2 minutes depending on size
   - You'll see blocks appear in the 3D view

5. **Navigate around:**
   - **Hold middle mouse button** and drag to rotate view
   - **Scroll mouse wheel** to zoom in/out
   - **Shift + middle mouse button** to pan left/right/up/down
   - Press **Home** key to fit everything in view

✅ **Checkpoint:** Minecraft world imported into Blender.

### Step 6.4: Apply MCprep Materials

1. **Select the imported world:**
   - Press **A** key to "Select All"
   - All blocks should turn orange/highlighted

2. **Open MCprep panel:**
   - Press **N** key (if side panel isn't already open)
   - Click the **"MCprep"** tab at the top

3. **Prep materials:**
   - Click the big **"Prep Materials"** button
   - Wait 5-30 seconds
   - You should see a message in the bottom-left: "Materials prepped"

4. **What changed:**
   - Glass blocks are now transparent (instead of solid white)
   - Leaves are now see-through
   - Torches/lanterns now glow
   - Water has transparency

✅ **Checkpoint:** MCprep materials applied successfully.

### Step 6.5: Test Render

Let's render one frame to verify everything works.

1. **Switch to rendered view:**
   - At the top-right of the 3D view, you'll see four small circles
   - Click the **rightmost circle** (it's white/shiny)
   - The view changes to show realistic lighting

2. **If the view is too dark:**
   - This is normal — Minecraft worlds need a sun
   - We'll cover lighting in the production workflow guide
   - For now, just verify you can see blocks and textures

3. **Take a test render:**
   - Press **F12** on your keyboard
   - Blender will render the current camera view
   - A new window opens showing the rendered image
   - This might take 10-60 seconds for first render

4. **Save the render (optional):**
   - In the render window, click **"Image"** → **"Save As..."**
   - Save to Desktop as `test-render.png`
   - Click **"Save As Image"**

5. **Close the render window:**
   - Click the X to close it

✅ **Checkpoint:** Test render completed successfully.

---

## Part 7: Troubleshooting

### Problem: PowerShell script shows "Replay folder not found"

**Solution:**
- The Forge port of Replay Mod uses a different folder name
- Edit the script:
  - Right-click `EditMode.ps1` → **"Edit"**
  - Find the line: `$replayPath = "C:\Users\$username\AppData\Roaming\.minecraft\replay_recordings"`
  - Change `replay_recordings` to `replays` (or whatever folder your Replay Mod uses)
  - Save and close Notepad
  - Try running the script again

### Problem: Blender won't launch from script

**Solution:**
- Verify Blender installed correctly:
  - Press **Windows key**, type **blender**, press **Enter**
  - If Blender opens, note the version number
- Edit the script:
  - Right-click `EditMode.ps1` → **"Edit"**
  - Find the line: `$blenderPath = "C:\Program Files\Blender Foundation\Blender 4.0\blender.exe"`
  - Change `4.0` to match your version (e.g., `4.1` or `4.2`)
  - Save and try again

### Problem: Mineways export is blank/empty

**Solution:**
- Make sure you selected an area by **clicking and dragging** a rectangle
- The selected area is highlighted in a different color
- If you don't see any selection, try drawing a rectangle again
- Make sure you're viewing the correct world (check title bar of Mineways)

### Problem: Blender import takes forever or freezes

**Solution:**
- Large world exports can be slow
- Try exporting a smaller area first
- Close and restart Blender, try importing again
- If still freezing, export an even smaller area (like 50x50 blocks)

### Problem: MCprep "Prep Materials" button does nothing

**Solution:**
- Make sure the imported world is **selected** (press **A** to select all)
- Objects should be highlighted in orange
- Try clicking "Prep Materials" again
- Check bottom-left of Blender for success message

---

## Next Steps

✅ You now have:
- Blender installed and configured
- MCprep addon working
- Mineways exporting worlds
- Launcher script on desktop
- Verified the complete workflow

**What to do next:**

1. **Learn the shortcuts:** See `blender-cheat-sheet.md` in this directory
2. **Production workflow:** See `docs/marketing/cinematic-production-workflow.md` when ready to make real cinematics
3. **Planning context:** See `docs/planning/blender-cinematic-workflow.md` for strategy and rationale

---

## Support & Questions

**For Michael and Holly:**
- If something doesn't work, note the exact error message
- Take a screenshot of the problem
- Ask in Discord or next session with Claude

**For future Firefrost staff:**
- This guide is tested on Windows 10/11
- Blender version: 4.0+ (tested with 4.0.2)
- MCprep version: 3.5.3
- Mineways version: 9.12

---

💙🔥❄️🌟

**Fire + Frost + Foundation = Where Love Builds Legacy**

---

**Created:** March 30, 2026  
**Created By:** Chronicler #48  
**Tested By:** Not yet tested (awaiting Michael/Holly installation)  
**Status:** Ready for deployment