anvil-level-design-blender

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Anvil Level Design Blender Addon

Anvil Level Design Blender插件

Skill by 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.

由ara.so开发的技能——设计技能合集。

Anvil Level Design（Anvil LD）是一款Blender插件，结合了Trenchbroom风格的游戏关卡设计工具。它具备自动化材质应用与UV管理、纹理图集热点映射、相机与网格工具、带背面剔除选择的几何算子，以及优化后的GLB导出工作流。

Installation

安装

Requirements:

Blender 5.1 or higher
Python (bundled with Blender)

Installation steps:

Download the repository as ZIP from GitHub
In Blender: Edit → Preferences → Add-ons
Click the v arrow → Install From Disk
Select the downloaded ZIP file
Enable the addon in preferences

Initial setup:

python

undefined

要求：

Blender 5.1或更高版本
Python（Blender自带）

安装步骤：

从GitHub下载仓库压缩包（ZIP格式）
在Blender中：编辑 → 偏好设置 → 插件
点击下拉箭头 → 从磁盘安装
选择下载的ZIP文件
在偏好设置中启用该插件

初始设置：

python

undefined

Access addon preferences to create workspaces

访问插件偏好设置以创建工作区

Edit → Preferences → Add-ons → Anvil Level Design

编辑 → 偏好设置 → 插件 → 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

材质与UV管理理念

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.

Anvil会自动管理材质以避免重复。材质应用时会自动进行UV展开，确保纹理在面之间无缝平铺。重要提示：不要在对象模式下使用缩放算子调整大小——应通过移动和挤出面来调整，以保持正确的UV坐标。

Workspace Requirements

工作区要求

You must be in "Level Design" or "Hotspot Mapping" workspace to use Anvil features. Features are workspace-contextual.

必须处于“关卡设计”或“热点映射”工作区才能使用Anvil的功能。功能是基于工作区上下文的。

Key Commands - Material Application

核心命令 - 材质应用

Basic Texture Application

基础纹理应用

Apply texture from file browser:

python

undefined

从文件浏览器应用纹理：

python

undefined

1. Select a face in Edit mode

1. 在编辑模式下选择一个面

2. Choose image file in file browser

2. 在文件浏览器中选择图像文件

Material is created and UV is automatically applied

系统会自动创建材质并应用UV


**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


**在面之间复制材质：**
- `Alt + 左键`点击目标面：应用相同材质并保持无缝平铺
- `Alt + 右键`点击源面：从面中拾取纹理（跨对象生效）

**拉伸材质应用：**
- `Shift + Alt + 左键`：应用纹理并拉伸以适配目标面尺寸
- `Shift + Alt + 右键`：拾取要拉伸的纹理

**仅UV操作（不改变材质）：**
- `Ctrl + Alt + 左键`：应用UV但不改变材质
- `Ctrl + Alt + 右键`：拾取UV但不改变材质

Interactive UV Modes

交互式UV模式

Face Snapping UV Mode (
T
key):

python

undefined

面吸附UV模式（
T
键）：

python

undefined

1. Select a face

1. 选择一个面

2. Press T to enter mode

2. 按T键进入模式

3. Move mouse near edges - texture bottom snaps to closest edge

3. 将鼠标移至边缘附近 - 纹理底部会吸附到最近的边缘

4. WASD keys: Select different texture edges

4. WASD键：选择不同的纹理边缘

5. Q/E keys: Set FIT modes

5. Q/E键：设置适配模式

6. Click to apply

6. 点击应用


**Grid Snapping UV Mode:**
```python


**网格吸附UV模式：**
```python

1. Select multiple quad faces (single island only)

1. 选择多个四边形面（仅单个岛）

2. Press T

2. 按T键

3. Snapping applies across entire quad grid

3. 吸附会应用于整个四边形网格

4. Same controls as Face Snapping mode

4. 控制方式与面吸附模式相同


**UV Transform Mode (`Shift + T`):**
```python


**UV变换模式（`Shift + T`）：**
```python

1. Select faces

1. 选择面

2. Press Shift+T

2. 按Shift+T

3. Hover over face to set as origin (for multi-face selection)

3. 将鼠标悬停在面上以设置原点（适用于多面选择）

4. Drag handles to move/resize UV with live preview

4. 拖动手柄移动/调整UV大小，实时预览效果

5. Drag resize handle through opposite side to mirror texture (negative Scale U/V)

5. 拖动调整手柄穿过对面以镜像纹理（负向缩放U/V）

undefined

undefined

Material Panel Settings

材质面板设置

Access via

key → Anvil panel:

python

undefined

按

键打开侧边栏 → Anvil面板：

python

undefined

Manual UV adjustments

手动UV调整

Scale U/V: 1.0 # At 1.0, pixels_per_meter controls texture size Rotation: 0.0 Offset U/V: 0.0, 0.0

Scale U/V: 1.0 # 设为1.0时，pixels_per_meter控制纹理大小 Rotation: 0.0 Offset U/V: 0.0, 0.0

Randomize offset: Click refresh icons next to Offset fields

随机化偏移：点击Offset字段旁的刷新图标

UV Lock toggle

UV锁定开关

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

UV_Lock: True # 材质随面调整而变形 UV_Lock: False # 材质保持世界空间（挤出时不会拉伸）


**实用操作：**
- 重置缩放、旋转、偏移（面对齐投影）
- 将材质居中到面
- 适配材质到面尺寸

**材质属性：**
```python

Link transparency channel to shader

将透明通道链接到着色器

Adjust roughness

调整粗糙度

Enable vertex colors

启用顶点颜色

Premultiply alpha settings

预乘alpha设置

Fix Alpha Bleed tool: Edits source image to set transparent pixels to color

修复Alpha渗色工具：编辑源图像，将透明像素设置为对应颜色

Prevents visible edges on transparent cutout materials for GLB export

避免GLB导出时透明裁剪材质出现可见边缘


**Default material settings:**
- Panel: Anvil (Settings) - per-file defaults
- Addon Preferences - global defaults for new .blend files


**默认材质设置：**
- 面板：Anvil（设置）- 按文件设置默认值
- 插件偏好设置 - 新.blend文件的全局默认值

Material Cleanup

材质清理

python

undefined

python

undefined

In Anvil panel

在Anvil面板中

"Cleanup Unused Materials" button # Removes orphaned materials

undefined

"清理未使用材质"按钮 # 删除孤立材质

undefined

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.

热点映射通过将面形状与纹理图集上的预定义区域匹配来分配UV坐标。热点UV永远不会镜像——始终是非翻转映射。

Setting Up Hotspot Maps

设置热点图

In Hotspot Mapping workspace:

python

undefined

在热点映射工作区中：

python

undefined

1. Open texture atlas in Image Editor

1. 在图像编辑器中打开纹理图集

2. Select Hotspot Edit tool (left sidebar)

2. 选择热点编辑工具（左侧边栏）

3. Press N → Anvil panel

3. 按N键 → Anvil面板

4. Click "Assign Hotspottable" to mark texture as hotspot source

4. 点击"标记为可热点化"将纹理标记为热点源

5. Add lines in image to split into hotspots

5. 在图像中添加线条以分割为热点区域

- Normal line: Click and drag

- 普通线条：点击并拖动

- Non-grid line: Hold Ctrl + drag

- 非网格线条：按住Ctrl + 拖动

6. Resize hotspots by dragging lines

6. 拖动线条调整热点大小

7. Use [ and ] keys for pixel snapping

7. 使用[和]键进行像素吸附


**Data storage:**
- Stored in .blend file by default
- Optional external JSON for cross-project sharing


**数据存储：**
- 默认存储在.blend文件中
- 可选导出为外部JSON以跨项目共享

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

点击热点旁的方向按钮或热点本身的图标来切换：

python

Any      # 适用于任何面，随机旋转
Upwards  # 仅适用于墙面（垂直），纹理顶部朝上 - 适用于砖块、壁板
Floor    # 仅适用于地面（朝上），随机旋转
Ceiling  # 仅适用于天花板（朝下），随机旋转

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

在3D视图的Anvil面板中：

python

"随机化热点"按钮  # 手动触发应用到选中面（若未选中或处于对象模式则应用到所有面）

"自动应用热点"开关  # 在几何编辑时自动应用（仅对移动的几何生效）

"固定"属性  # 选中面后开启可防止随机化

"选择热点"按钮  # 手动选择固定热点

Combined Faces & Seam Mode

组合面与接缝模式

Allow Combined Faces:

python

undefined

允许组合面：

python

undefined

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

undefined


**接缝模式：**
```python
"保留用户接缝"  # 清除自动接缝（对用户而言无变化）
"显示所有接缝"    # 显示算法识别的面岛，用于调试
"清除所有接缝"    # 删除所有接缝

尺寸权重滑块：

python

undefined

Default (0.0): Closest aspect ratio match (preserves pixel aspect)

默认（0.0）：选择最接近的宽高比匹配（保持像素比例）

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)


**最佳实践：**
- 在图集中创建多种宽高比和尺寸的热点
- 确保对任何几何都能良好匹配
- 算法不会分割非矩形面岛（例如L形面保持独立）

Geometry Tools

几何工具

Selection Tools

选择工具

Backface Culling Override:

python

undefined

背面剔除覆盖：

python

undefined

Anvil overrides selection to ignore culled backfaces when not in X-ray mode

当未处于X射线模式时，Anvil会覆盖选择逻辑，忽略被剔除的背面

Works with:

支持：

- Box select (single click, Shift-click, Alt-click)

- 框选（单击、Shift+单击、Alt+单击）

- Lasso select (single click variants)

- 套索选择（单击变体）

Limitations (Blender API):

限制（Blender API）：

- Does NOT work with box/lasso dragging

- 不支持框选/套索拖动

- Does NOT work with circle select or tweak tool

- 不支持圆形选择或微调工具


**Vertex Paint mode:**
```python


**顶点绘制模式：**
```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


**绘制选择（`Ctrl + 左键`）：**
```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


**选择相连元素：**
```python
L                 # 悬停在元素上：选择所有相连元素
Ctrl+L            # 悬停在元素上：选择法线匹配的相连元素
                  # 重复按会逐步选择法线相似度更高的面
Ctrl+Shift+L      # 逐步回退基于法线的选择
Shift+L           # 将相连面岛添加到选择中

Context Aware Weld (

key)

上下文感知焊接（

键）

python

undefined

python

undefined

Press W for context-aware welding

按W键执行上下文感知焊接

Action varies based on selection context

操作根据选择上下文而变化

Next weld action flagged in Anvil panel

下一次焊接操作会在Anvil面板中标记

Specific behaviors described in relevant README sections

具体行为请参考相关README章节

undefined

undefined

Cube Cut Mode (

key in Edit mode)

立方体切割模式（编辑模式下按

键）

python

undefined

python

undefined

Enter cube cut mode

进入立方体切割模式

Press C in Edit mode
Click on face to start drawing
Move mouse and click to define rectangular face
Move mouse third time to define depth
Click third time to make cut

在编辑模式下按C键
点击面开始绘制
移动鼠标并点击定义矩形面
第三次移动鼠标定义深度
第三次点击完成切割

Behavior:

行为：

- Only affects selected faces (or all if none selected)

- 仅影响选中面（若未选中则影响所有面）

- Drawing rectangle in orthogonal view creates infinite cut

- 在正交视图中绘制矩形会创建无限切割

undefined

undefined

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)

python

右键鼠标按钮  # 相机导航
Tab                # 切换对象/编辑模式
G                  # 移动选择
E                  # 挤出选择
Alt+Click          # 选择循环边
B                  # 添加立方体（在对象和编辑模式下均生效）
L                  # 选择相连面（在多立方体编辑模式选择中很有用）

Configuration

配置

Addon Preferences

插件偏好设置

Access: Edit → Preferences → Add-ons → Anvil Level Design

python

undefined

访问路径： 编辑 → 偏好设置 → 插件 → Anvil Level Design

python

undefined

Workspace creation

工作区创建

"Create Level Design Workspace" "Create Hotspot Mapping Workspace"

"创建关卡设计工作区" "创建热点映射工作区"

Hotkey remapping

快捷键重映射

All addon hotkeys collected here for convenience

所有Anvil快捷键集中在此处，方便操作

Default material settings (global for new .blend files)

默认材质设置（新.blend文件的全局设置）

Default_Pixels_Per_Meter: 100.0 Default_Roughness: 0.5 Default_Transparency_Mode: "OPAQUE"

undefined

Default_Pixels_Per_Meter: 100.0 Default_Roughness: 0.5 Default_Transparency_Mode: "OPAQUE"

undefined

Per-File Settings

按文件设置

Anvil (Settings) panel:

python

undefined

Anvil（设置）面板：

python

undefined

Default material properties for new textures in current file

当前文件中新纹理的默认材质属性

Pixels_Per_Meter: 100.0 Roughness: 0.5 Enable_Vertex_Colors: False Transparency_Settings: {...}

undefined

Pixels_Per_Meter: 100.0 Roughness: 0.5 Enable_Vertex_Colors: False Transparency_Settings: {...}

undefined

Code Examples

代码示例

Python API - Material Application

Python API - 材质应用

python

import bpy

python

import bpy

Access Anvil operators through bpy.ops

通过bpy.ops访问Anvil算子

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

def apply_texture_to_selected_face(image_path): """将文件中的纹理应用到选中面""" # 加载图像 img = bpy.data.images.load(image_path)

# Anvil会处理材质创建和UV应用
# 通常通过UI操作，但也可通过脚本实现：
obj = bpy.context.active_object
if obj and obj.mode == 'EDIT':
    # 选择面并通过Anvil算子应用
    # bpy.ops.anvil.apply_material_from_image()
    pass

def get_anvil_material_settings(): """访问Anvil材质设置""" 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

UV操作

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

undefined

def set_uv_scale_rotation(scale_u=1.0, scale_v=1.0, rotation=0.0): """通过Anvil属性设置UV变换""" obj = bpy.context.active_object if obj and obj.mode == 'EDIT': # 访问Anvil UV属性 # 属性存储在对象/网格数据中 # bpy.ops.anvil.set_uv_transform(scale_u=scale_u, scale_v=scale_v, rotation=rotation) pass

undefined

Python API - Hotspot Management

Python API - 热点管理

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

python

import bpy
import json

def create_hotspot_data(image_name, hotspots):
    """定义热点数据结构"""
    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):
    """将热点数据导出到外部JSON"""
    with open(filepath, 'w') as f:
        json.dump(data, f, indent=2)

def apply_random_hotspots():
    """触发选中面的热点随机化"""
    # 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' } ]

undefined

undefined

Python API - Geometry Operations

Python API - 几何操作

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

python

import bpy

def context_aware_weld():
    """执行上下文感知焊接"""
    # bpy.ops.anvil.context_weld()
    pass

def select_connected_by_normal():
    """选择法线匹配的相连面"""
    # bpy.ops.anvil.select_connected_normal()
    pass

def paint_select_setup():
    """设置绘制选择模式"""
    obj = bpy.context.active_object
    if obj and obj.type == 'MESH':
        # 确保正确的选择模式
        bpy.ops.object.mode_set(mode='EDIT')
        bpy.context.tool_settings.mesh_select_mode = (False, False, True)  # 面模式

Common Patterns

常见模式

Level Design Workflow

关卡设计工作流

python

undefined

python

undefined

1. Initial geometry blocking

1. 初始几何块搭建

- Switch to Level Design workspace

- 切换到关卡设计工作区

- Enter Edit mode (Tab)

- 进入编辑模式（Tab）

- Press B to add cubes

- 按B键添加立方体

- Use G (move) and E (extrude) to shape level

- 使用G（移动）和E（挤出）塑造关卡

- Alt+Click to select loops

- Alt+Click选择循环边

- L to select connected geometry

- L选择相连几何

2. Texture application

2. 纹理应用

- Select face

- 选择面

- Choose image in file browser (auto-applies material)

- 在文件浏览器中选择图像（自动应用材质）

- Alt+Left Mouse on other faces to copy texture

- Alt+左键点击其他面复制纹理

- Press T for Face Snapping UV Mode to align texture edges

- 按T键进入面吸附UV模式对齐纹理边缘

- Use Shift+T for UV Transform Mode for manual fine-tuning

- 使用Shift+T进入UV变换模式进行手动微调

3. Detail with hotspots

3. 热点细节处理

- 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)

- 设置方向类型（墙面用Upwards，地面/天花板用Floor/Ceiling）

- Back in Level Design workspace, enable Auto Apply Hotspots

- 返回关卡设计工作区，启用自动应用热点

- Create detail geometry - hotspots apply automatically

- 创建细节几何 - 热点会自动应用

4. Refinement

4. 优化调整

- Use Ctrl+L to select by normal

- 使用Ctrl+L按法线选择

- Apply specific materials to groups

- 为面组应用特定材质

- Mark important hotspots as Fixed

- 将重要热点标记为固定

- Manually Choose Hotspot where needed

- 必要时手动选择热点

5. Export

5. 导出

- Use Anvil (Export) panel for GLB export

- 使用Anvil（导出）面板进行GLB导出

- Materials configured for game engine compatibility

- 材质已配置为适配游戏引擎

undefined

undefined

Texture Atlas Setup

纹理图集设置

python

undefined

python

undefined

Best practices for hotspot atlases:

热点图集最佳实践：

1. Include wide variety of aspect ratios

1. 包含多种宽高比

- Square (1:1)

- 正方形（1:1）

- Wide rectangles (4:1, 8:1)

- 宽矩形（4:1, 8:1）

- Tall rectangles (1:4, 1:8)

- 高矩形（1:4, 1:8）

- Common ratios (2:1, 3:2)

- 常见比例（2:1, 3:2）

2. Include multiple size variants

2. 包含多种尺寸变体

- Large (1024x1024) for big surfaces

- 大尺寸（1024x1024）用于大表面

- Medium (512x512, 512x256) for common use

- 中等尺寸（512x512, 512x256）用于通用场景

- Small (256x256, 128x256) for details

- 小尺寸（256x256, 128x256）用于细节

- This prevents blurry textures from small hotspots

- 避免小热点导致纹理模糊

3. Organize by orientation

3. 按方向分组

- Group wall textures (Upwards orientation)

- 墙面纹理组（Upwards方向）

- Group floor textures (Floor orientation)

- 地面纹理组（Floor方向）

- Group ceiling textures (Ceiling orientation)

- 天花板纹理组（Ceiling方向）

- Generic details (Any orientation)

- 通用细节（Any方向）

4. Name hotspots descriptively

4. 为热点命名清晰

- Helps when manually choosing fixed hotspots

- 手动选择固定热点时更方便

undefined

undefined

Material Optimization

材质优化

python

undefined

python

undefined

Material management strategy:

材质管理策略：

1. Use single atlas per material type

1. 每种材质类型使用单个图集

- One atlas for stone/brick

- 一个图集用于石材/砖块

- One atlas for metal

- 一个图集用于金属

- One atlas for wood

- 一个图集用于木材

- Reduces material count

- 减少材质数量

2. Leverage Anvil's duplicate prevention

2. 利用Anvil的重复材质预防功能

- Addon automatically merges duplicate materials

- 插件会自动合并重复材质

- Periodically run "Cleanup Unused Materials"

- 定期运行“清理未使用材质”

3. Configure defaults early

3. 尽早配置默认值

- Set Pixels_Per_Meter for project scale

- 为项目比例设置Pixels_Per_Meter

- Set default roughness per material type

- 为每种材质类型设置默认粗糙度

- Configure transparency settings before texturing

- 纹理制作前配置透明设置

4. Fix alpha bleed before export

4. 导出前修复Alpha渗色

- Use Fix Alpha Bleed tool on transparent textures

- 对透明纹理使用修复Alpha渗色工具

- Or enable premultiply alpha in material settings

- 或在材质设置中启用预乘alpha

- Test in target engine

- 在目标引擎中测试

undefined

undefined

Troubleshooting

故障排除

Textures Not Applying Correctly

纹理无法正确应用

Problem: Alt+Left Mouse doesn't apply texture

python

undefined

问题： Alt+左键无法应用纹理

python

undefined

Check:

检查：

Are you in Level Design workspace?
Is face actually selected (orange highlight)?
Is object in Edit mode?
Try Alt+Right Mouse to pick texture first

是否处于关卡设计工作区？
面是否真的被选中（橙色高亮）？
对象是否处于编辑模式？
尝试先按Alt+右键拾取纹理

If texture applies but looks wrong:

如果纹理已应用但显示异常：

Check UV Lock setting in Anvil panel
Verify Scale U/V values (should typically be 1.0 or close)
Check if texture is mirrored (negative Scale U/V) - use panel to reset


**Problem:** Textures stretch when extruding
```python

检查Anvil面板中的UV锁定设置
验证Scale U/V值（通常应为1.0或接近1.0）
检查纹理是否被镜像（负向Scale U/V）- 使用面板重置


**问题：** 挤出时纹理拉伸
```python

UV Lock is ON

UV锁定处于开启状态

Solution: Turn UV Lock OFF in Anvil panel for world-space material behavior

解决方案：在Anvil面板中关闭UV锁定，实现世界空间材质行为

UV Lock ON: Material warps with geometry

UV锁定开启：材质随几何变形

UV Lock OFF: Material maintains world space (preferred for level design)

UV锁定关闭：材质保持世界空间（关卡设计首选）

undefined

undefined

Hotspot Issues

热点问题

Problem: Hotspots not applying

python

undefined

问题： 热点无法应用

python

undefined

Check:

检查：

Is image marked as "Hotspottable" in Hotspot Mapping workspace?
Are hotspot regions properly defined (visible lines in Image Editor)?
Does face orientation match hotspot orientation type?
- Use Shift+Z to toggle wireframe and see face normals
Is "Allow Combined Faces" causing unexpected island grouping?
- Try disabling to process faces individually


**Problem:** Wrong hotspots selected
```python

图像是否在热点映射工作区中被标记为“可热点化”？
热点区域是否正确定义（图像编辑器中可见线条）？
面方向是否与热点方向类型匹配？
- 使用Shift+Z切换线框模式查看面法线
“允许组合面”是否导致意外的面岛分组？
- 尝试禁用该选项，单独处理每个面


**问题：** 选中错误的热点
```python

Issue: Small hotspots chosen, textures blurry

问题：选择了小热点，纹理模糊

Solution: Adjust Size Weight slider

解决方案：调整尺寸权重滑块

- Higher values favor hotspots matching texel density

- 增大值优先选择匹配像素密度的热点

- Lower values favor aspect ratio matches only

- 减小值仅优先匹配宽高比

Issue: Hotspots randomize on every edit

问题：每次编辑时热点都会随机化

Solution: Mark preferred hotspots as Fixed

解决方案：将合适的热点标记为固定

1. Select faces with good hotspots

1. 选择带有合适热点的面

2. Enable "Fixed" property in Anvil panel

2. 在Anvil面板中启用“固定”属性


**Problem:** Hotspots creating seams
```python


**问题：** 热点产生接缝
```python

Check Seam Mode setting:

检查接缝模式设置：

"Maintain User Seams" # Default, clears auto-seams "Display All Seams" # Shows what algorithm sees as islands "Clear All Seams" # Nuclear option

"保留用户接缝" # 默认，清除自动接缝 "显示所有接缝" # 显示算法识别的面岛 "清除所有接缝" # 终极解决方案

If islands not forming as expected:

如果面岛未按预期形成：

Switch to "Display All Seams" mode
See where algorithm splits geometry
Manually add seams where needed
Or disable "Allow Combined Faces" for per-face control

undefined

切换到“显示所有接缝”模式
查看算法如何分割几何
在需要的地方手动添加接缝
或禁用“允许组合面”以实现逐面控制

undefined

Selection Problems

选择问题

Problem: Selecting through geometry

python

undefined

问题： 选择穿透几何

python

undefined

Backface culling limitations:

背面剔除限制：

Turn OFF X-ray mode (Alt+Z) for backface culling to work
Use single-click selections, not drag selections
Avoid circle select - use Paint Select (Ctrl+Left Mouse) instead
Box select and lasso work for clicks, not drags

关闭X射线模式（Alt+Z），背面剔除才会生效
使用单击选择，而非拖动选择
避免圆形选择 - 使用绘制选择（Ctrl+左键）替代
框选和套索仅对单击操作生效，拖动无效

For vertex paint:

顶点绘制：

Face orientation automatically enabled to show paintable faces

会自动启用面方向以显示可绘制的面


**Problem:** Cannot select specific faces
```python


**问题：** 无法选择特定面
```python

Use selection modes:

使用选择模式：

Ctrl+L # Select by normal - progressively select similar-facing faces L # Select all connected Shift+L # Add island to selection Alt+Click # Select loop

Ctrl+L # 按法线选择 - 逐步选择法线相似的面 L # 选择所有相连元素 Shift+L # 添加面岛到选择 Alt+Click # 选择循环边

Paint Select for precision:

绘制选择实现精准选择：

Ctrl+Left Mouse # Hold and drag, respects backface culling

undefined

Ctrl+左键 # 按住并拖动，遵循背面剔除规则

undefined

Performance Issues

性能问题

Problem: Slow material application

python

undefined

问题： 材质应用缓慢

python

undefined

Too many materials:

材质过多：

Use "Cleanup Unused Materials" in Anvil panel regularly
Consolidate similar materials to atlases
Check material count in Outliner

定期在Anvil面板中运行“清理未使用材质”
将相似材质合并到图集中
在大纲视图中检查材质数量

Too many faces:

面数过多：

Use decimation modifier on detail geometry
Merge unnecessary faces
Use instancing for repeated elements


**Problem:** Hotspot randomization slow
```python

对细节几何使用简化修改器
合并不必要的面
对重复元素使用实例化


**问题：** 热点随机化缓慢
```python

Large texture atlas:

纹理图集过大：

Reduce atlas resolution if possible
Reduce number of hotspot regions
Disable "Auto Apply Hotspots" during heavy modeling
Manually trigger with "Randomise Hotspots" when ready

undefined

尽可能降低图集分辨率
减少热点区域数量
大量建模时禁用“自动应用热点”
准备好后手动触发“随机化热点”

undefined

Export Issues

导出问题

Problem: Transparent materials wrong in GLB

python

undefined

问题： GLB中透明材质显示异常

python

undefined

Alpha bleed visible:

出现Alpha渗色：

Use "Fix Alpha Bleed" tool on source textures
Or enable premultiply alpha in material settings
Check material blend mode (should be appropriate for engine)

对源纹理使用“修复Alpha渗色”工具
或在材质设置中启用预乘alpha
检查材质混合模式（应适配目标引擎）

Missing materials:

材质缺失：

Verify all materials are assigned in Blender
Check Anvil (Export) panel settings
Test with simpler material setup first

undefined

验证所有材质在Blender中已分配
检查Anvil（导出）面板设置
先使用简单材质设置测试

undefined

Workspace Lost

工作区丢失

Problem: Level Design or Hotspot Mapping workspace missing

python

undefined

问题： 关卡设计或热点映射工作区丢失

python

undefined

Solution:

解决方案：

Edit → Preferences → Add-ons → Anvil Level Design
Click "Create Level Design Workspace"
Click "Create Hotspot Mapping Workspace"
Workspaces appear at top of Blender window

undefined

编辑 → 偏好设置 → 插件 → Anvil Level Design
点击“创建关卡设计工作区”
点击“创建热点映射工作区”
工作区会出现在Blender窗口顶部

undefined

Keyboard Shortcuts Not Working

快捷键无效

Problem: Hotkeys don't trigger Anvil features

python

undefined

问题： 快捷键无法触发Anvil功能

python

undefined

Check:

检查：

Are you in correct workspace? (Level Design or Hotspot Mapping)
Are you in correct mode? (Object vs Edit mode)
Check addon preferences for hotkey conflicts
Remap conflicting keys in preferences
Verify addon is enabled in preferences

undefined

是否处于正确的工作区？（关卡设计或热点映射）
是否处于正确的模式？（对象模式 vs 编辑模式）
在插件偏好设置中检查快捷键冲突
在偏好设置中重新映射冲突的快捷键
验证插件是否在偏好设置中启用

undefined

Advanced Configuration

高级配置

Custom Hotkey Setup

自定义快捷键设置

python

undefined

python

undefined

Access: Edit → Preferences → Add-ons → Anvil Level Design

访问路径：编辑 → 偏好设置 → 插件 → Anvil Level Design

All Anvil hotkeys collected in preferences

所有Anvil快捷键集中在此处

Common remapping:

常见重映射：

T # Face Snapping UV Mode (might conflict with tools) Shift+T # UV Transform Mode C # Cube Cut (conflicts with circle select) W # Context Aware Weld B # Add Cube (conflicts with box select in some contexts)

T # 面吸附UV模式（可能与工具冲突） Shift+T # UV变换模式 C # 立方体切割（与圆形选择冲突） W # 上下文感知焊接 B # 添加立方体（在某些场景下与框选冲突）

Consider remapping to:

建议重映射到：

- Function keys (F1-F12)

- 功能键（F1-F12）

- Alt+key combinations

- Alt+键组合

- Numpad keys if not using for view

- 数字小键盘（若未用于视图控制）

undefined

undefined

Performance Tuning

性能调优

python

undefined

python

undefined

For large levels:

针对大型关卡：

1. Material management

1. 材质管理

Max_Materials_Before_Warning: 50 # Set lower for cleanup reminders

Max_Materials_Before_Warning: 50 # 降低值以提前提醒清理

2. Hotspot settings

2. 热点设置

Size_Weight: 0.3 # Balance quality vs speed Allow_Combined_Faces: False # Faster processing, less smart grouping

Size_Weight: 0.3 # 平衡质量与速度 Allow_Combined_Faces: False # 处理更快，但智能分组减少

3. Selection settings

3. 选择设置

Disable paint select if not needed # Slight performance gain

禁用绘制选择（若不需要） # 小幅提升性能

4. UV settings

4. UV设置

UV_Lock: False # Default off for better performance on extrusions

undefined

UV_Lock: False # 默认关闭，挤出时性能更好

undefined

Integration with Version Control

与版本控制集成

python

undefined

python

undefined

Hotspot data in external JSON:

热点数据存储在外部JSON中：

In Hotspot Mapping workspace:

在热点映射工作区中：

Define hotspots on texture atlas
Export hotspot data to JSON
Commit JSON to version control
Team members load same JSON
Consistent hotspot behavior across team

在纹理图集上定义热点
将热点数据导出为JSON
将JSON提交到版本控制
团队成员加载相同的JSON
团队间热点行为保持一致

.blend file considerations:

.blend文件注意事项：

- Store in Git LFS if using version control

- 若使用版本控制，存储在Git LFS中

- Hotspot data embedded by default

- 热点数据默认嵌入文件

- External JSON optional for sharing

- 可选导出为外部JSON用于共享

undefined

undefined

Resources

资源

Discord: https://discord.gg/hHFZbDzR57
GitHub: https://github.com/alexjhetherington/anvil-level-design
Example files: Check
```
examples/hotspot_tutorial.blend
```
in repository

Discord： https://discord.gg/hHFZbDzR57
GitHub： https://github.com/alexjhetherington/anvil-level-design
示例文件： 查看仓库中的
```
examples/hotspot_tutorial.blend
```

Quick Reference Card

快速参考卡

python

undefined

python

undefined

Material Application

材质应用

Alt+Left Mouse # Copy material to face (seamless tiling) Alt+Right Mouse # Pick material from face Shift+Alt+Left Mouse # Apply stretched to fit Ctrl+Alt+Left Mouse # Apply UV only (no material change)

Alt+左键 # 将材质复制到面（无缝平铺） Alt+右键 # 从面拾取材质 Shift+Alt+左键 # 拉伸适配应用 Ctrl+Alt+左键 # 仅应用UV（不改变材质）

UV Modes

UV模式

T # Face Snapping UV Mode Shift+T # UV Transform Mode WASD (in UV mode) # Select texture edges Q/E (in UV mode) # FIT modes

T # 面吸附UV模式 Shift+T # UV变换模式 WASD（UV模式下） # 选择纹理边缘 Q/E（UV模式下） # 适配模式

Selection

选择

L # Select connected Ctrl+L # Select by normal Shift+L # Add island Ctrl+Left Mouse # Paint select

L # 选择相连元素 Ctrl+L # 按法线选择 Shift+L # 添加面岛 Ctrl+左键 # 绘制选择

Geometry

几何

B # Add cube C (Edit mode) # Cube cut E # Extrude G # Move W # Context aware weld

B # 添加立方体 C（编辑模式） # 立方体切割 E # 挤出 G # 移动 W # 上下文感知焊接