---
name: blender-game-assets
description: Build game-ready 3D assets in Blender by script - buildings, props and objects modelled from reference images - and export them to a game engine at the right scale. Use when asked to model, build or make a 3D object, prop, building or kit in Blender, to model something from a photo or drawing, or to export a Blender mesh to Unreal, Unity or Godot. Covers parametric builders, the modifier stack, joining parts without seams, UVs, normals, the export scale trap and in-engine checks. Not for character clothing: start from a free Fab garment and customise it instead.
---

# Blender game assets (indie edition)

A simplified, engine-neutral version of the Blender skill used to build Second Chance
(secondchancegame.com/blender-modelling). It assumes an agent that can run Python inside
Blender (a Blender MCP server, or `blender --background --python build.py`). Every rule here
came from something that went wrong at least once.

## The five rules

1. **Build by script, not by hand.** Every asset is a Python builder with its measurements as
   named constants at the top, in metres. A change is an edit and a re-run, never a manual fix
   that the next re-run throws away.
2. **Measure before you model.** Write down the real-world size of the thing (from the
   reference, a standard, or a tape measure) before the first vertex.
3. **Render and compare.** After each build, render from the same angle as the reference and
   put the two side by side. Do not call a model done from a description of it.
4. **Probe the export, every session.** Export a known-size box, import it into the engine and
   read its bounds before exporting anything real (see "The scale trap").
5. **Check it in the engine, not in Blender.** Blender's viewport hides inverted faces and
   missing collision. Only the engine shows what the player will see.

## Two ways to drive Blender

| | Live (Blender MCP server) | Headless (command line) |
|---|---|---|
| Use for | Inspecting a scene, small edits, viewport screenshots | Building kits, big meshes, exports, batch renders |
| Touches | The file the user has open | Only the .blend you pass it |

**Setup (live):** Blender 5.1+. Preferences > Get Extensions > Repositories > add
`https://lab.blender.org/`, install and enable the **MCP** add-on, then connect your agent
(Claude desktop: the Blender extension; other clients:
`pip install git+https://projects.blender.org/lab/blender_mcp.git`). Test by asking for the
object list before changing anything. Docs: https://www.blender.org/lab/mcp-server/

**Live habits:** inspect before you edit; return numbers from every call; screenshot the
viewport after each step; keep calls small (a heavy call can time the socket out); FBX export
may need an explicit `bpy.context.temp_override(window=..., area=<VIEW_3D>, region=<WINDOW>)`.

**Headless:**

```
blender -b --factory-startup -P build.py -- --render
blender -b kit.blend -P build.py -- --only Lamp --render out/
```

- `-b` no window; `--factory-startup` ignores user prefs and add-ons; args after `--` go to the
  script (`sys.argv[sys.argv.index("--")+1:]`).
- Give the builder modes (build / render / export / only one piece).
- Pass the .blend on the command line. A builder that saves to a fixed path from an empty
  scene will overwrite the real file.
- Render previews to a folder and look at them; a quiet exit proves nothing.
- Blender's bundled Python lacks common libraries (e.g. PIL): generate textures in a separate
  step and load them as files.
- Check enum names against your version (e.g. `BLENDER_EEVEE_NEXT` does not exist in 5.1).

Rule of thumb: **live to look, headless to build.**

## Code-execution habits

- Re-import everything in every call; find objects by name, never by "the active object".
- Name everything with a prefix (`GEO-`, `SM_`), never leave `Cube.027`.
- Return or print structured results (names, vertex counts, bounds) so the result can be checked.
- Prefer `bmesh` and the data API for builders: they are precise and need no UI context.
  Use `bpy.ops` for one-off actions, and set mode, selection and active object first.
- In edit mode, write bmesh changes back (`bmesh.update_edit_mesh`) or they are silently lost.
- Keep long builds in several calls, and save the .blend between stages.

## Decision tree

```
What are you making?
├── Building / architecture   → parametric "parts" builder (walls with openings, slabs, roofs)
├── Repeating kit (fence, rail, column, tile) → one unit + Array (+ Curve) modifier
├── Hard-surface prop         → cube/cylinder primitives + Bevel + Subdivision
├── Object from a photo       → measure → block out → refine against side-by-side renders
├── Round / turned object     → one profile curve revolved (Screw modifier / spin), not stacked cylinders
└── Clothing for a character  → do not build it: customise a free Fab garment (see "Clothing")
```

## Buildings: the parts builder

Make a small library of functions that return geometry into one parts dictionary, keyed by
material, and build each building from them. No `bpy.ops` inside the builder.

```python
import bpy, bmesh
T = 0.25          # wall thickness, metres
STOREY = 2.7

def box(bm, x0, y0, z0, x1, y1, z1):
    """Axis-aligned box with OUTWARD faces. Check the winding once, in the engine."""
    v = [bm.verts.new(p) for p in [
        (x0,y0,z0),(x1,y0,z0),(x1,y1,z0),(x0,y1,z0),
        (x0,y0,z1),(x1,y0,z1),(x1,y1,z1),(x0,y1,z1)]]
    for f in [(0,3,2,1),(4,5,6,7),(0,1,5,4),(1,2,6,5),(2,3,7,6),(3,0,4,7)]:
        bm.faces.new([v[i] for i in f])

def wall_x(bm, x0, x1, y, z0, z1, openings=()):
    """A wall along X, split around openings given as (xa, xb, za, zb)."""
    cuts = sorted(openings)
    x = x0
    for xa, xb, za, zb in cuts:
        box(bm, x, y, z0, xa, y+T, z1)                 # solid run before the opening
        if za > z0: box(bm, xa, y, z0, xb, y+T, za)    # under the sill
        if zb < z1: box(bm, xa, y, zb, xb, y+T, z1)    # over the lintel
        x = xb
    box(bm, x, y, z0, x1, y+T, z1)
```

House conventions that saved us repeated work:

- **Pick one front direction and one origin** for the whole kit (we use: front faces -Y, origin
  at the front-left corner on the ground). Placement code can then be written once.
- **Doors are separate meshes** with the pivot on the hinge, so the engine can swing them.
- **Inset the inner skin of a wall at its ends** and inset floor slabs slightly from the walls,
  or the corners z-fight.
- **Openings are ranges along the wall's own axis.** A wall that runs along Y takes Y ranges,
  not X. Get this wrong and the window lands in the next room.
- **Seal the roof.** Gables, hips and dormers must close, or light leaks in at the eaves.
- **Walk it before you ship it.** A building can pass every doorway-width check and still be
  impossible to cross. Flood-fill the walkable floor from the front door (in the engine or on a
  grid) and make sure every room is reached.

## Objects from reference images

1. **Find the size.** Use a known dimension in the photo (a door is about 2 m, a brick course
   75 mm, a kerb 125 mm) and scale everything else from it. Write the numbers down as constants.
2. **Name the three axes** for anything elongated: long, broad and thin. Orient it so the
   broad face is what the player sees; a blade seen edge-on reads as a pole.
3. **Block out with primitives**, then refine. Get the silhouette right before any detail.
4. **Overlap parts by 5-15 mm at every join** so the seam is hidden inside the larger part.
   Parts that only just touch leave a visible line. For a truly seamless join of one material,
   Boolean-union them.
5. **Taper to a real point** by moving the end vertices together and merging them
   (`remove_doubles`), not by scaling them towards zero.
6. **Smooth-shade round parts**; leave bevelled hard-surface parts flat or edge-split.
7. **Render from the photo's angle and compare side by side.** Fix the biggest difference
   first. Repeat until the differences are details.

## Modifier stack order

```
Mirror → Array → Solidify → Bevel → Subdivision Surface → (Boolean, if needed)
```

Bevel before Subdivision, or round shapes pinch. Mirror first, with clipping on.

```python
ob = bpy.data.objects["GEO-box"]
bev = ob.modifiers.new("Bevel", "BEVEL")
bev.width, bev.segments, bev.limit_method = 0.02, 3, "ANGLE"
sub = ob.modifiers.new("Subsurf", "SUBSURF")
sub.levels, sub.render_levels = 2, 2
```

Apply modifiers (or export with them applied) before handing the mesh to an engine.

## Hollow things

A cup, bowl or bin is **one surface of revolution** whose profile goes up the outside, over the
rim and back down the inside. Two nested solid cylinders are not a hollow: the inside renders
filled. Let `bmesh.ops.recalc_face_normals` work out which way is outward on the closed shell.

## UVs and texel density

- `smart_project` scales every object's UVs to fill 0..1 whatever its size, so a shared tiling
  texture looks huge on small props and tiny on big ones. **Rescale the UVs by world area**
  so one tile always covers the same real distance:

```python
import math
def uv_worldscale(me, metres_per_tile=0.5):
    uv = me.uv_layers.active.data
    a3 = sum(p.area for p in me.polygons)
    auv = 0.0
    for p in me.polygons:
        pts = [uv[i].uv for i in p.loop_indices]
        auv += abs(sum(pts[i].x*pts[i-1].y - pts[i-1].x*pts[i].y for i in range(len(pts)))) / 2
    s = math.sqrt(a3 / auv) / metres_per_tile
    for d in uv: d.uv = (d.uv.x * s, d.uv.y * s)
```

- Textures that carry readable content (signs, labels, posters) need hand-written UVs, and the
  engine may flip U, V or both. Test with an image that has asymmetric text on it: reversed
  reading order means U is flipped; correct order with mirrored letters means V is flipped.
- In recent Blender versions, create the UV layer yourself before unwrapping
  (`me.uv_layers.new()`); do not assume an operator made one.

## Normals and winding

- Recalculate normals outward before export (`bmesh.ops.recalc_face_normals` or Shift+N).
- **Check floors from above in the engine.** A slab whose top face points down is invisible from
  above and has no walkable collision, while every wall of the same mesh looks fine.

## The scale trap (read before every export)

Blender works in metres; many engines read FBX numbers differently (Unreal reads centimetres).
The correct export flags have changed between Blender versions and even between sessions in the
same file. **Do not trust a recipe; probe.**

```python
# 1. In Blender: a probe with three DIFFERENT sizes catches axis swaps as well as scale
bpy.ops.mesh.primitive_cube_add(size=1)
p = bpy.context.active_object; p.name = "PROBE"; p.scale = (0.5, 0.3, 0.2)
bpy.ops.object.transform_apply(scale=True)
# 2. Export it with your usual flags, import it into the engine, read its bounds.
#    Unreal: expect 50 x 30 x 20. Unity/Godot: expect 0.5 x 0.3 x 0.2.
# 3. If it is 100x off either way, change ONE flag, re-probe, then delete the probe.
```

Then assert the bounds in your import script, so a wrong scale fails loudly:

```python
assert 5 < max_extent < 500, f"scale wrong: {max_extent}"
```

Other export habits:

- Apply transforms (Ctrl+A, All Transforms) before export.
- FBX: smoothing `EDGE` (not `FACE`, which flattens smooth shading), Add Leaf Bones off.
- Hidden objects can export as empty files: check the file size, then re-import it.
- **Never trust an export you have not imported.**

## Clothing: do not build it, customise a free Fab asset

We are good at buildings and objects. We are not good at clothing, and the only things we can
say with certainty about it are what did not work. **Do not model character clothing from
scratch in Blender.** Start from a free garment on Epic's Fab marketplace (fab.com) made for
your character system, and customise it: recolour it, swap its textures, add a logo, adjust
the fit. Check each asset's licence allows use in your game.

What did not work for us, so you can skip it:

- **Garments built by script around the body.** They worked, but lost on quality to
  purpose-made garments every time. Folds, drape and the weight of fabric are exactly what a
  script describes badly.
- **Trusting a still image.** A garment exported at the wrong scale looked perfect in its
  reference pose and collapsed to a hundredth of its size the moment an animation played.
  Another stood frozen while the body walked on, because its root bone did not match.
- **Assuming a logo will show.** A print placed on the wrong material slot was simply
  invisible, with no error.

If you customise a Fab garment in Blender, the export rules above still apply, and only a
capture of the character moving proves it works.

## Common pitfalls

| Symptom | Fix |
|---|---|
| Asset 100x too small or too big in the engine | Probe the export scale; assert bounds on import |
| Floors invisible from above, player falls through | Face winding: recalc normals, check slab tops in engine |
| Visible line where two parts meet | Overlap the parts 5-15 mm, or Boolean-union them |
| Round shapes pinch | Bevel before Subdivision |
| Black or dark faces | Recalculate normals outward |
| Texture scale different on every prop | Rescale UVs by world area |
| Sign text mirrored or reversed | U vs V flip: read which one before changing anything |
| A bowl renders solid | Build one revolved shell, not nested cylinders |

## Licence

Free to use, copy and adapt for your own projects. No warranty: check every result in your own
engine. From the Second Chance devlog, secondchancegame.com.
