anvil-level-design-blender

# Anvil Level Design Blender Addon > Skill by [ara.so](https://ara.so) — Design Skills collection. Anvil Level Design (Anvil LD) is a Blender addon combining Trenchbroom-inspired tools for video game level design. It features automated material application and UV management, hotspot mapping for texture atlases, camera and grid tools, geometry operators with backface culling selection, and improved GLB export workflow. ## Installation **Requirements:** - Blender 5.1 or higher - Python (bundled with Blender) **Installation steps:** 1. Download the repository as ZIP from GitHub 2. In Blender: Edit → Preferences → Add-ons 3. Click the v arrow → Install From Disk 4. Select the downloaded ZIP file 5. Enable the addon in preferences **Initial setup:** ```python # Access addon preferences to create workspaces # Edit → Preferences → Add-ons → Anvil Level Design # Click "Create Level Design Workspace" and "Create Hotspot Mapping Workspace" ``` The addon adds two custom workspaces: - **Level Design** - Main workspace for level geometry and texturing - **Hotspot Mapping** - Workspace for defining texture atlas hotspots **Custom hotkey remapping:** All addon hotkeys are collected in addon preferences for easy remapping. Common keys to customize: - Camera tools - Texture application tools - Geometry operators ## Core Concepts ### Material and UV Management Philosophy Anvil manages materials automatically to prevent duplicates. Materials are applied with automatic UV unwrapping that tiles seamlessly across faces. **Critical**: Do not resize in object mode using scale operator - resize by moving and extruding faces to maintain proper UV coordinates. ### Workspace Requirements You must be in "Level Design" or "Hotspot Mapping" workspace to use Anvil features. Features are workspace-contextual. ## Key Commands - Material Application ### Basic Texture Application **Apply texture from file browser:** ```python # 1. Select a face in Edit mode # 2. Choose image file in file browser # Material is created and UV is automatically applied ``` **Copy material between faces:** - `Alt + Left Mouse` on target face: Apply same material with seamless tiling - `Alt + Right Mouse` on source face: Pick texture from face (works across objects) **Stretched material application:** - `Shift + Alt + Left Mouse`: Apply texture stretched to fit target face dimensions - `Shift + Alt + Right Mouse`: Pick texture to be stretched **UV-only operations (no material change):** - `Ctrl + Alt + Left Mouse`: Apply UV without changing material - `Ctrl + Alt + Right Mouse`: Pick UV without changing material ### Interactive UV Modes **Face Snapping UV Mode (`T` key):** ```python # 1. Select a face # 2. Press T to enter mode # 3. Move mouse near edges - texture bottom snaps to closest edge # 4. WASD keys: Select different texture edges # 5. Q/E keys: Set FIT modes # 6. Click to apply ``` **Grid Snapping UV Mode:** ```python # 1. Select multiple quad faces (single island only) # 2. Press T # 3. Snapping applies across entire quad grid # 4. Same controls as Face Snapping mode ``` **UV Transform Mode (`Shift + T`):** ```python # 1. Select faces # 2. Press Shift+T # 3. Hover over face to set as origin (for multi-face selection) # 4. Drag handles to move/resize UV with live preview # 5. Drag resize handle through opposite side to mirror texture (negative Scale U/V) ``` ### Material Panel Settings Access via `N` key → Anvil panel: ```python # Manual UV adjustments Scale U/V: 1.0 # At 1.0, pixels_per_meter controls texture size Rotation: 0.0 Offset U/V: 0.0, 0.0 # Randomize offset: Click refresh icons next to Offset fields # UV Lock toggle UV_Lock: True # Material warps with face adjustments UV_Lock: False # Material maintains world space (no stretching on extrusion) ``` **Utility operations:** - Reset scale, rotation, offset (Face-Aligned project) - Center material to face - Fit material to face dimensions **Material properties:** ```python # Link transparency channel to shader # Adjust roughness # Enable vertex colors # Premultiply alpha settings # Fix Alpha Bleed tool: Edits source image to set transparent pixels to color # Prevents visible edges on transparent cutout materials for GLB export ``` **Default material settings:** - Panel: Anvil (Settings) - per-file defaults - Addon Preferences - global defaults for new .blend files ### Material Cleanup ```python # In Anvil panel "Cleanup Unused Materials" button # Removes orphaned materials ``` ## Hotspot Mapping System Hotspot mapping assigns UV coordinates by matching face shapes to predefined regions on a texture atlas. Hotspot UVs are never mirrored - always non-flipped mapping. ### Setting Up Hotspot Maps **In Hotspot Mapping workspace:** ```python # 1. Open texture atlas in Image Editor # 2. Select Hotspot Edit tool (left sidebar) # 3. Press N → Anvil panel # 4. Click "Assign Hotspottable" to mark texture as hotspot source # 5. Add lines in image to split into hotspots # - Normal line: Click and drag # - Non-grid line: Hold Ctrl + drag # 6. Resize hotspots by dragging lines # 7. Use [ and ] keys for pixel snapping ``` **Data storage:** - Stored in .blend file by default - Optional external JSON for cross-project sharing ### Hotspot Orientation Types Click orientation button next to hotspot or icon on hotspot itself to cycle: ```python Any # Applies to any face, randomized rotation Upwards # Walls only (vertical), texture top points up - for bricks, siding Floor # Floor faces only (up-facing), randomized rotation Ceiling # Ceiling faces only (down-facing), randomized rotation ``` ### Applying Hotspots **In 3D viewport Anvil panel:** ```python "Randomise Hotspots" button # Manual trigger on selected faces (or all if none/object mode) "Auto Apply Hotspots" toggle # Auto-apply on geometry edits (moved geometry only) "Fixed" property # Toggle on selected faces to prevent randomization "Choose Hotspot" button # Manually select a fixed hotspot ``` ### Combined Faces & Seam Mode **Allow Combined Faces:** ```python # Enabled (default): Algorithm treats connected faces as single face # - Works on curved/bent face series # - Attempts to find groups transformable to rectangle # - Splits islands by normals and user seams # Disabled: Each face processed individually ``` **Seam Mode:** ```python "Maintain User Seams" # Clears auto-seams (appears unchanged to user) "Display All Seams" # Shows auto-seams for debugging island detection "Clear All Seams" # Removes all seams ``` **Size Weight slider:** ```python # Default (0.0): Closest aspect ratio match (preserves pixel aspect) # Increase: Weight towards hotspots matching texel density # Prevents blurry textures when small hotspots match aspect ratio ``` **Best practices:** - Create wide variety of aspect ratios and sizes in atlas - Ensures good hotspot matching on any geometry - Algorithm doesn't split non-rectangular islands (e.g., L-shapes remain separate faces) ## Geometry Tools ### Selection Tools **Backface Culling Override:** ```python # Anvil overrides selection to ignore culled backfaces when not in X-ray mode # Works with: # - Box select (single click, Shift-click, Alt-click) # - Lasso select (single click variants) # # Limitations (Blender API): # - Does NOT work with box/lasso dragging # - Does NOT work with circle select or tweak tool ``` **Vertex Paint mode:** ```python # Automatically enables face orientation if not already on # Front face orientation color set to transparent in active theme # Shows which faces cannot be painted through ``` **Paint Select (`Ctrl + Left Mouse`):** ```python # Similar to circle select but respects backface culling # Hold and drag to add crossed items to selection ``` **Select Connected:** ```python L # Hover over element: Select all connected elements Ctrl+L # Hover over element: Select connected with matching normals # Repeated presses select faces progressively by normal similarity Ctrl+Shift+L # Step backward in normal-based selection Shift+L # Add connected island to selection ``` ### Context Aware Weld (`W` key) ```python # Press W for context-aware welding # Action varies based on selection context # Next weld action flagged in Anvil panel # Specific behaviors described in relevant README sections ``` ### Cube Cut Mode (`C` key in Edit mode) ```python # Enter cube cut mode 1. Press C in Edit mode 2. Click on face to start drawing 3. Move mouse and click to define rectangular face 4. Move mouse third time to define depth 5. Click third time to make cut # Behavior: # - Only affects selected faces (or all if none selected) # - Drawing rectangle in orthogonal view creates infinite cut ``` ### Basic Navigation ```python Right Mouse Button # Camera navigation Tab # Toggle Object/Edit mode G # Move selection E # Extrude selection Alt+Click # Select loops B # Add cubes (works in Object and Edit mode) L # Select connected faces (useful for multi-cube edit mode selections) ``` ## Configuration ### Addon Preferences **Access:** Edit → Preferences → Add-ons → Anvil Level Design ```python # Workspace creation "Create Level Design Workspace" "Create Hotspot Mapping Workspace" # Hotkey remapping # All addon hotkeys collected here for convenience # Default material settings (global for new .blend files) Default_Pixels_Per_Meter: 100.0 Default_Roughness: 0.5 Default_Transparency_Mode: "OPAQUE" ``` ### Per-File Settings **Anvil (Settings) panel:** ```python # Default material properties for new textures in current file Pixels_Per_Meter: 100.0 Roughness: 0.5 Enable_Vertex_Colors: False Transparency_Settings: {...} ``` ## Code Examples ### Python API - Material Application ```python import bpy # Access Anvil operators through bpy.ops def apply_texture_to_selected_face(image_path): """Apply texture from file to selected face""" # Load image img = bpy.data.images.load(image_path) # Anvil handles material creation and UV application # Typically done through UI, but can script: obj = bpy.context.active_object if obj and obj.mode == 'EDIT': # Select face and apply through Anvil operators # bpy.ops.anvil.apply_material_from_image() pass def get_anvil_material_settings(): """Access Anvil material settings""" prefs = bpy.context.preferences.addons['anvil-level-design'].preferences settings = { 'pixels_per_meter': prefs.default_pixels_per_meter, 'roughness': prefs.default_roughness, } return settings # UV manipulation def set_uv_scale_rotation(scale_u=1.0, scale_v=1.0, rotation=0.0): """Set UV transformation via Anvil properties""" obj = bpy.context.active_object if obj and obj.mode == 'EDIT': # Access Anvil UV properties # Properties stored in object/mesh data # bpy.ops.anvil.set_uv_transform(scale_u=scale_u, scale_v=scale_v, rotation=rotation) pass ``` ### Python API - Hotspot Management ```python import bpy import json def create_hotspot_data(image_name, hotspots): """Define hotspot data structure""" hotspot_data = { 'image': image_name, 'hotspots': [] } for hs in hotspots: hotspot_data['hotspots'].append({ 'bounds': { 'x_min': hs['x_min'], 'y_min': hs['y_min'], 'x_max': hs['x_max'], 'y_max': hs['y_max'] }, 'orientation': hs.get('orientation', 'Any'), # Any, Upwards, Floor, Ceiling 'name': hs.get('name', '') }) return hotspot_data def export_hotspot_json(data, filepath): """Export hotspot data to external JSON""" with open(filepath, 'w') as f: json.dump(data, f, indent=2) def apply_random_hotspots(): """Trigger hotspot randomization on selected faces""" # bpy.ops.anvil.randomise_hotspots() pass # Example hotspot definition example_hotspots = [ { 'x_min': 0, 'y_min': 0, 'x_max': 512, 'y_max': 512, 'orientation': 'Upwards', 'name': 'brick_wall_01' }, { 'x_min': 512, 'y_min': 0, 'x_max': 1024, 'y_max': 256, 'orientation': 'Floor', 'name': 'floor_tile_01' } ] ``` ### Python API - Geometry Operations ```python import bpy def context_aware_weld(): """Execute context-aware weld""" # bpy.ops.anvil.context_weld() pass def select_connected_by_normal(): """Select connected faces with matching normals""" # bpy.ops.anvil.select_connected_normal() pass def paint_select_setup(): """Setup for paint select mode""" obj = bpy.context.active_object if obj and obj.type == 'MESH': # Ensure proper selection mode bpy.ops.object.mode_set(mode='EDIT') bpy.context.tool_settings.mesh_select_mode = (False, False, True) # Face mode ``` ## Common Patterns ### Level Design Workflow ```python # 1. Initial geometry blocking # - Switch to Level Design workspace # - Enter Edit mode (Tab) # - Press B to add cubes # - Use G (move) and E (extrude) to shape level # - Alt+Click to select loops # - L to select connected geometry # 2. Texture application # - Select face # - Choose image in file browser (auto-applies material) # - Alt+Left Mouse on other faces to copy texture # - Press T for Face Snapping UV Mode to align texture edges # - Use Shift+T for UV Transform Mode for manual fine-tuning # 3. Detail with hotspots # - Create texture atlas # - Switch to Hotspot Mapping workspace # - Use Hotspot Edit tool to define regions # - Set orientation types (Upwards for walls, Floor/Ceiling for horizontals) # - Back in Level Design workspace, enable Auto Apply Hotspots # - Create detail geometry - hotspots apply automatically # 4. Refinement # - Use Ctrl+L to select by normal # - Apply specific materials to groups # - Mark important hotspots as Fixed # - Manually Choose Hotspot where needed # 5. Export # - Use Anvil (Export) panel for GLB export # - Materials configured for game engine compatibility ``` ### Texture Atlas Setup ```python # Best practices for hotspot atlases: # 1. Include wide variety of aspect ratios # - Square (1:1) # - Wide rectangles (4:1, 8:1) # - Tall rectangles (1:4, 1:8) # - Common ratios (2:1, 3:2) # 2. Include multiple size variants # - Large (1024x1024) for big surfaces # - Medium (512x512, 512x256) for common use # - Small (256x256, 128x256) for details # - This prevents blurry textures from small hotspots # 3. Organize by orientation # - Group wall textures (Upwards orientation) # - Group floor textures (Floor orientation) # - Group ceiling textures (Ceiling orientation) # - Generic details (Any orientation) # 4. Name hotspots descriptively # - Helps when manually choosing fixed hotspots ``` ### Material Optimization ```python # Material management strategy: