LOD FORGE DOCUMENTATION

Version 1.0.2 · Blender 4.2 LTS and later

------------------------------------------------------------

TABLE OF CONTENTS

- 1. Installation

- 2. Getting Started

- 3. Smart Decimation 3.1 How Protection Weights Work

- 3.2 UV Seam Detection

- 3.3 Material Boundary Detection

- 3.4 Silhouette Edge Detection

- 3.5 Adaptive Protection Scaling

- 3.6 Decimate Modifier Integration

- 3.7 Skip Decimation (Target >= Source)

    4. Engine Profiles

    5. LOD Presets

    6. Custom Targets

    7. Feature Protection Settings

    8. Budget Enforcement

    9. LOD Preview

    10. LOD Metrics

    11. Batch Generation

    12. Operator Reference

    13. Scripting

    14. Troubleshooting

    15. FAQ

------------------------------------------------------------

1. INSTALLATION

1. Download the add-on ZIP from your Superhive purchase page. Do not unpack it.

2. Open Blender → Edit → Preferences → Add-ons.

3. Click the arrow button in the top right corner, choose Install from Disk and select the downloaded .zip file.

4. Enable the add-on by ticking the checkbox next to LOD Forge.

5. Press N in the 3D Viewport: the LOD Forge panel is under the LODForge tab.

Important:

Blender 4.2 LTS minimum.

------------------------------------------------------------

2. GETTING STARTED

PANEL LOCATION

Press N in the 3D Viewport to open the sidebar; a tab named LODForge appears down its right edge.

QUICK START — 6 STEPS

1. Select a mesh object in the viewport (Object Mode).

2. Open the sidebar (N) and switch to the LODForge tab.

3. Under Preset, pick Desktop Character (or any preset that matches your use case).

4. Under Engine, pick Unity, Unreal or Custom.

5. Leave all three protection options enabled (UV Seams, Material Boundaries, Silhouette).

6. Click Generate LODs.

LOD Forge renames your mesh to LOD0 and builds LOD1 to LOD4 from it (the number of levels is set by LOD Levels), names them according to the selected engine convention,

applies adaptive protection scaling for each level, checks each level against its triangle target, and parents everything under an empty.

The LOD Metrics panel shows triangle counts, reduction percentages and budget pass/fail for every level.

Note:

Tip: When a preset is selected, the triangle targets are displayed as read-only info in the panel.

If a target is at or above the source mesh's triangle count, an info icon appears next to that level: it will be created as an exact copy rather than decimated.

------------------------------------------------------------

3. SMART DECIMATION

  The core of LOD Forge is its protection weight system combined with adaptive scaling. Before

  applying the Decimate modifier, LOD Forge analyses the mesh and creates a vertex group called

  LF_Protection. Vertices that sit on important features receive a weight of

  1.0 (fully protected), while all other vertices receive 0.0

  (free to collapse). For aggressive LOD levels, these weights are then scaled down so the

  decimator can reach the target triangle count.

3.1 HOW PROTECTION WEIGHTS WORK

LOD Forge creates a vertex group named LF_Protection on the mesh. The initial

weight assignment is binary:

- 1.0 — Vertex is on a protected feature (UV seam, material boundary, or silhouette edge)

- 0.0 — Vertex has no special importance and can be freely collapsed

If a vertex qualifies for protection under multiple criteria (e.g., it sits on both a UV seam

and a material boundary), it still receives 1.0 — protection is a flag, not additive.

Note:

Inspect weights: You can view the protection weights by switching to Weight Paint mode

and selecting the LF_Protection vertex group. Red vertices are protected;

blue vertices will be decimated first.

3.2 UV SEAM DETECTION

  LOD Forge uses bmesh to iterate over every edge in the mesh. For each edge where

  edge.seam is True, both vertices of that edge receive a protection

  weight of 1.0. This ensures that UV island boundaries remain intact during decimation,

  preventing the texture tearing that plagues standard Decimate results.

Note:

  Tip: Make sure your UV seams are properly marked before generating LODs.

  LOD Forge reads edge.seam in bmesh — if seams are not marked, there is nothing to protect.

3.3 MATERIAL BOUNDARY DETECTION

  For every edge in the mesh, LOD Forge checks the two faces that share it. If those adjacent

  faces have different material_index values, the edge sits on a material boundary.

  Both vertices of that edge are assigned a protection weight of 1.0. This prevents the

  Decimate modifier from collapsing edges where two materials meet, which would cause color

  bleeding and shading artifacts.

3.4 SILHOUETTE EDGE DETECTION

  Silhouette edges are detected by measuring the angle between the normals of two adjacent faces

  that share an edge. If this angle exceeds the Angle Threshold (default: 60°),

  the edge is considered a silhouette-defining feature and both its vertices are protected.

The calculation works as follows:

    # Pseudocode for silhouette detection

    for edge in bmesh.edges:

        if len(edge.link_faces) == 2:

            face_a, face_b = edge.link_faces

            angle = angle_between(face_a.normal, face_b.normal)

            if angle > threshold:

                for vert in edge.verts:

                    protect(vert, weight=1.0)

  Lower threshold values protect more edges (aggressive protection); higher values protect

  only the sharpest creases (relaxed protection). See the

  Feature Protection Settings section for recommended values.

3.5 ADAPTIVE PROTECTION SCALING

  This is the key innovation in LOD Forge. Standard protection works well for gentle decimation

  (LOD1 at 50% of the original), but for aggressive LOD levels (LOD3 at 10% of the original),

  full protection can prevent the decimator from reaching the target triangle count. Adaptive

  protection solves this by automatically scaling down protection weights for aggressive levels.

THE FORMULA

  scaled_weight = original_weight × max(0.2, ratio)

Where:

- original_weight is the binary protection weight (0.0 or 1.0)

- ratio is the decimation ratio = target_tris / source_tris

- 0.2 is the floor — protection never drops below 20% of the original weight

WHEN ADAPTIVE SCALING ACTIVATES

Adaptive scaling only activates when the ratio is below 0.3. For ratios of 0.3 and above,

protection weights remain at full strength (1.0). For example:

- ratio 0.5 — full protection, weight 1.0

- ratio 0.2 — scaled protection, weight 0.2

- ratio 0.1 — floor, weight 0.2

EXAMPLE

Consider a mesh with 15,000 triangles using the Desktop Character preset (LOD1: 15,000, LOD2: 7,500, LOD3: 3,000, LOD4: 1,500):

- LOD1: target 15,000 is not below the source → exact copy, no decimation.

- LOD2: ratio = 7500/15000 = 0.5 → weight stays 1.0. Full protection.

- LOD3: ratio = 3000/15000 = 0.2 → below 0.3 → weight × max(0.2, 0.2) = 0.2.

- LOD4: ratio = 1500/15000 = 0.1 → below 0.3 → weight × 0.2 (the floor).

Each level is decimated in up to three passes: if a pass leaves the mesh above its target, the next pass uses a corrected ratio.

3.6 DECIMATE MODIFIER INTEGRATION

LOD Forge uses the DECIMATE modifier with mode COLLAPSE. It configures:

- modifier.vertex_group = "LF_Protection"

- modifier.invert_vertex_group = True

With invert_vertex_group enabled, vertices with weight 1.0 resist collapse and vertices with weight 0.0 collapse first.

3.7 SKIP DECIMATION (TARGET >= SOURCE)

If the target triangle count for a given LOD level is greater than or equal to the source mesh's

actual triangle count, LOD Forge skips decimation and creates that level as an exact copy

of the source mesh.

Note:

Example: Your mesh has 4,000 triangles and you use the Desktop Character preset

(LOD1: 15,000, LOD2: 7,500). Both are at or above 4,000, so LOD1 and LOD2 are exact copies. LOD3 (3,000) and LOD4 (1,500) are decimated normally.

------------------------------------------------------------

4. ENGINE PROFILES

The Engine setting controls how the levels and their parent empty are named.

Profile Level names Parent empty

Unity MeshName_LOD0, _LOD1, … MeshName_LODGroup

Unreal MeshName_LOD0, _LOD1, … MeshName_LODs

Custom MeshName_LOD0, _LOD1, … MeshName_LODGroup

LOD0 is your source mesh, renamed. The add-on names the chain; how an engine importer reads it is set in that engine.

------------------------------------------------------------

5. LOD PRESETS

Each preset fills the triangle targets of four levels, LOD1 to LOD4. LOD0 is always the source mesh itself.

Preset LOD1 LOD2 LOD3 LOD4

Desktop Character 15,000 7,500 3,000 1,500

Desktop Environment 25,000 12,000 5,000 2,000

Mobile Character 5,000 2,500 1,000 500

Mobile Prop 2,000 1,000 500 200

When a preset is selected, the targets are shown as read-only info. If a target is at or above the source mesh's triangle count, an info icon appears next to that level — it will be an exact copy.

------------------------------------------------------------

6. CUSTOM TARGETS

Select Custom in the Preset dropdown to edit the targets yourself. LOD Levels (1 to 6) sets how many levels are built; one field per level appears, labelled LOD1, LOD2, and so on.

A target higher than the source mesh's triangle count does not add geometry: that level is an exact copy of the source.

------------------------------------------------------------

7. FEATURE PROTECTION SETTINGS

The protection panel exposes three toggles and one slider:

UV SEAMS

  Toggle: On by default. When enabled, vertices on UV seam edges

  (edge.seam == True in bmesh) receive protection weight. Disable this only if your mesh

  has no meaningful UV layout (e.g., procedurally textured or vertex-colored assets).

MATERIAL BOUNDARIES

  Toggle: On by default. When enabled, vertices on edges shared by faces with

  different material_index values are protected. Disable if your mesh uses a single

  material or if material zone integrity is not important.

SILHOUETTE EDGES

  Toggle: On by default. When enabled, vertices on edges where the angle between

  adjacent face normals exceeds the angle threshold are protected. Disable for organic meshes

  where you want maximum decimation freedom and silhouette is less critical.

ANGLE THRESHOLD

  Slider: Range 10° to 170°, default 60°. Controls how aggressively

  silhouette edges are detected.

  Value  Effect                                         Best For

  -----  ---------------------------------------------  ---------------------------------------------

  30°    Aggressive — protects most creases and hard..  Hard-surface models, mechanical parts, weap..

  60°    Balanced — protects distinct creases, allow..  General characters, props, vehicles (recomm..

  90°    Relaxed — only very sharp angles (right-ang..  Organic meshes, terrain, foliage, rounded s..

  Rule of thumb: Start at 60° for most assets. Lower it to 30° for hard-surface

  models with important chamfers. Raise it to 90° for organic shapes where smooth reduction

  matters more than crease preservation.

------------------------------------------------------------

8. BUDGET ENFORCEMENT

  After LOD generation, LOD Forge compares the actual triangle count of each level against the

  target defined by the selected preset or custom values.

HOW IT WORKS

1. LOD Forge generates the decimated mesh for a given level.

2. It counts the actual triangles in the resulting mesh.

3. If actual is at or below the target, the level is marked PASS.

4. If actual > target, the level is marked FAIL and a warning icon is displayed.

WHY A LEVEL MIGHT FAIL

- Too many protected vertices: If a large portion of the mesh is protected and adaptive scaling cannot free enough vertices, the decimator may not reach the target.

- Target too aggressive: Extremely low targets on high-poly meshes with many protected features may not be achievable even with adaptive scaling.

WHAT TO DO WHEN A LEVEL FAILS

- Increase the target triangle count for that level (use Custom preset).

- Disable one or more protection options (try disabling silhouette protection first).

- Increase the silhouette angle threshold to free up more vertices.

- For the failing level specifically, consider disabling all protection — adaptive scaling already reduces protection for aggressive levels, but disabling it completely gives the decimator full freedom.

------------------------------------------------------------

9. LOD PREVIEW

The LOD Preview panel shows one level of the chain in the viewport at a time.

CYCLING THROUGH LEVELS

Click a level button (LOD0, LOD1, …) or use Previous / Next to step through the chain. The selected level becomes visible; the other levels are hidden.

SHOW ALL LODS TOGGLE

Enable Show All LODs to make every level visible at once. The levels stay where they are, on top of each other.

------------------------------------------------------------

10. LOD METRICS

After Generate LODs, the LOD Metrics panel lists every level:

Column Description

LOD Level name (LOD0 is the source)

Tris Actual triangle count

Reduction Percentage of triangles removed relative to LOD0 (LOD0 shows "Source")

Budget A check mark when the level is at or below its target, a warning icon when it is above

Note:

Tip: If you edit an LOD mesh after generation, or select another chain, click Refresh Metrics to recalculate the table.

------------------------------------------------------------

11. BATCH GENERATION

Batch Generate builds a chain for every selected mesh object with the same settings.

WORKFLOW

1. Select the mesh objects in the viewport (Object Mode).

2. Configure the preset, engine profile and protection settings as usual.

3. Click Batch Generate.

4. Each object gets its own LOD chain, naming and parent empty. Objects that are not meshes are skipped.

5. After a batch run the metrics table shows the chain of the active object; select another chain and click Refresh Metrics to see its numbers.

Important:

Running Generate LODs or Batch Generate again on an object that already has a chain rebuilds that chain with the current settings: the old levels and group empty are removed and LOD0 is decimated afresh. With any level of the chain active, the chain is rebuilt from LOD0. Only what LOD Forge 1.0.2 or later built is replaced: LOD objects that came with a model, or a chain made by version 1.0.1, are left alone and named in the message — remove them with Remove LODs first.

------------------------------------------------------------

12. OPERATOR REFERENCE

Generate LODs lodforge.generate LOD chain for the active mesh

Batch Generate lodforge.batch_generate LOD chains for all selected meshes

Remove LODs lodforge.remove Deletes the generated levels and the parent empty, renames LOD0 back and removes the LF_Protection group

Preview LOD lodforge.preview_lod Shows one level (property: level)

Cycle LOD lodforge.cycle_lod Previous / next level (property: direction, -1 or 1)

Show LOD Metrics lodforge.show_metrics Recalculates the metrics table (the Refresh Metrics button)

------------------------------------------------------------

13. SCRIPTING

The operators read their settings from the panel (scene.lodforge), not from operator arguments. To script a run, set the scene properties and call the operator:

props = bpy.context.scene.lodforge

props.preset = 'DESKTOP_CHARACTER'

props.engine = 'UNITY'

bpy.ops.lodforge.generate()

------------------------------------------------------------

14. TROUBLESHOOTING

LODS HAVE THE SAME TRIANGLE COUNT AS THE SOURCE

  Cause: The target triangle count is higher than the source mesh's actual tri count.

  When target >= source, LOD Forge creates an exact copy instead of decimating.

  Fix: Use a lower preset (e.g., Mobile Character instead of Desktop Character) or

  switch to Custom preset and enter targets below your source tri count.

PROTECTION DOES NOT SEEM TO WORK — UVS STILL BREAK

  Cause: The UV seam, material boundary, or silhouette protection toggles may be

  disabled in the panel.

  Fix: Open the Feature Protection section in the LOD Forge panel and make sure

  the relevant toggles are enabled. Also verify that your UV seams are actually marked on the mesh

  (in Edit Mode, check Edge > Mark Seam).

LOD STILL TOO HIGH-POLY DESPITE ADAPTIVE PROTECTION

  Cause: Adaptive protection scales weights down but uses a floor of 0.2, which

  may not be aggressive enough for extreme reduction targets.

  Fix: Try disabling one or more protection options for that level. Alternatively,

  increase the silhouette angle threshold to reduce the number of protected vertices. For extreme

  cases, you can disable all protection for the lowest LOD level.

NAMING CONFLICTS — OBJECTS GET .001 SUFFIX

  Cause: Blender appends .001, .002 when an object with the same name already exists — usually a chain from an earlier run.

  Fix: Select the old chain, run Remove LODs, then generate again.

REMOVE LODS DOES NOT WORK

  Cause: You need to select an object that is part of an LOD chain (has an

  _LOD suffix) for the removal operator to identify which LODs to delete.

  Fix: Select any object with an _LOD0, _LOD1, etc. suffix,

  then click Remove LODs.

BATCH GENERATE SKIPS SOME OBJECTS

  Cause: LOD Forge only processes mesh objects. Non-mesh objects (cameras, lights,

  empties, armatures, curves, text) in your selection are automatically skipped.

  Fix: Convert non-mesh objects to mesh first (Ctrl+A

  > Mesh) if you need LODs for them.

ANGLE THRESHOLD TOO HIGH OR TOO LOW

  Cause: An incorrect angle threshold can either protect too many edges (low value)

  or too few edges (high value).

  Fix: Use 60° as a starting point for most assets. Lower to 30° for

  hard-surface models, raise to 90° for organic meshes.

  After a run, the LF_Protection vertex group on the source shows in Weight Paint mode which vertices were protected.

METRICS SHOW WRONG DATA

  Cause: If you manually edit LOD meshes after generation, the metrics table

  still shows the values from generation time.

  Fix: Click Refresh Metrics to recalculate the table with

  current mesh data.

LOD FORGE PANEL DOES NOT APPEAR IN THE SIDEBAR

  Cause: The addon is not enabled, or a conflicting addon is registered to the

  same panel category.

  Fix: Go to Edit > Preferences > Add-ons, search for

  "LOD Forge", and make sure the checkbox is enabled. Press N in

  the 3D Viewport and check the tab list on the right side of the sidebar.

------------------------------------------------------------

15. FAQ

Q: WHICH BLENDER VERSIONS ARE SUPPORTED?

Blender 4.2 LTS and later.

Q: CAN I UNDO LOD GENERATION?

Yes. Generate LODs, Batch Generate and Remove LODs are registered as undo steps, so Ctrl+Z right after reverts the run. Remove LODs also takes a chain back at any time later.

Q: DOES LOD FORGE MODIFY MY ORIGINAL MESH?

Its geometry is not decimated, but the object is renamed to MeshName_LOD0, gets an LF_Protection vertex group and, with Parent to Empty on, is parented under the chain's empty.

Remove LODs renames it back and removes the vertex group.

Q: CAN I EXPORT THE LODS DIRECTLY TO FBX/GLTF?

LOD Forge does not include its own exporter. Use Blender's FBX or glTF exporter.

Q: HOW DOES ADAPTIVE PROTECTION AFFECT VISUAL QUALITY?

For moderate reduction (ratio 0.3 and above) protection stays at full strength. For aggressive reduction it is scaled down so the decimator can reach the target; the LOD Metrics panel shows whether it did.

Q: WHAT HAPPENS TO SHAPE KEYS?

LOD0 is the original mesh and keeps all of its shape keys. LOD1 and below are decimated from the basis shape and carry no shape keys: Blender cannot apply decimation to a mesh with shape keys. The message after Generate says when this happened.

Q: DOES IT WORK WITH MULTI-MATERIAL MESHES?

Yes. With Protect Material Boundaries on, vertices on edges between two materials are protected from collapsing first.

Q: HOW MANY LOD LEVELS CAN I GENERATE?

One to six, set by LOD Levels. Presets fill four.

Q: WILL LOD FORGE WORK ON MESHES WITH MODIFIERS?

Each LOD copy carries the source's modifier stack; only the Decimate step is applied. Apply Subdivision, Mirror and similar modifiers on the source first if you want them baked into the levels.

Q: CAN I USE LOD FORGE IN A COMMERCIAL PROJECT?

Yes. The add-on is GPL-3.0; the meshes you make with it are yours.

Q: DOES LOD FORGE SUPPORT CURVES, TEXT, OR OTHER NON-MESH OBJECTS?

No. LOD Forge requires mesh objects. Convert curves, text, or other objects to mesh first (Object → Convert → Mesh).

------------------------------------------------------------

LOD Forge v1.0.2

Smart LOD generation for Blender · Preserve what matters, decimate the rest.