# Tutorial: Import a Blender model

This tutorial takes a small model – a wooden bridge – from Blender into a level, with its texture
and collision, and back again. The same steps work for any OBJ or glTF model from other programs.
Background and all options: [Importing meshes and the library](07-meshes.md).

## 1. Model with the engine in mind

The game engine is from 2000. A few rules make the result look right:

* **Scale**: in the editor 1 cell is one grid square and the llama is about 0.6 cells tall. The
  simplest setup in Blender is **1 Blender unit = 1 cell**. A walkable bridge is 1.5–2 cells wide.
* **Polygons**: keep it simple – tens or hundreds of faces, not thousands. The model is cut into
  1×1-cell pieces and each piece may have at most 8000 vertices.
* **Up axis**: Blender works Z-up, but its OBJ and glTF exporters convert to Y-up by default.
  Keep that default; the editor expects **Y up**.
* **UVs**: the engine has no free texture coordinates – each triangle shows one half of a
  rectangle of a texture. Best results: **quads whose UVs fill the whole texture** (in the UV
  editor: select the faces, *UV → Reset*), one texture per material. Planks, walls and floors map
  exactly; unwrapped organic shapes are only approximated.
* **No tiling**: UVs outside 0…1 are clamped. Repeat the geometry (Array modifier) instead of the
  texture.
* **Textures**: PNG or JPG, square or rectangular, ideally 64–256 pixels. Transparent areas
  (leaves, railings) work with PNG alpha.
* **Origin**: put the origin at the bottom centre of the model – it becomes the placement point.

## 2. Export from Blender

**OBJ** (simplest):

1. *File → Export → Wavefront (.obj)*.
2. Keep *Forward: -Z*, *Up: Y*; enable **UV Coordinates**, **Normals**, **Materials** and, under
   *Materials*, *Path Mode: Copy* so the textures are written next to the `.obj`.
3. Apply modifiers if you used any.

You get `bridge.obj`, `bridge.mtl` and the texture files. Keep them in one folder.

**glTF** works too: *File → Export → glTF 2.0*, format *glTF Binary (.glb)* – everything in one
file. Vertex colours (*Color Attribute*) are imported as well.

## 3. Import into the level

1. Open your level and choose **File → Import mesh (OBJ, glTF)…**. Pick `bridge.obj`.
2. The **Import mesh** dialog opens. Orbit the preview by dragging; the grid squares are 1 cell and
   the marker shows the llama's height.
3. Check the size under **Source**. If it is wrong (for example the file was in centimetres), type
   the wanted size into **Largest side** and press **Fit**.
4. **Up axis**: **Y up**. If the bridge lies on its side, switch to **Z up**.
5. **Turn** it if needed; leave **Stand on the ground** on.

![The Import mesh dialog with preview and options](img/geo_import.jpg)

### Textures

* **Texture size on the page**: 128 is a good default; use 64 for small props, 256 only for large,
  important surfaces – every material gets its own copy on the level's texture pages.
* **UV precision (steps per texture)**: 8 is fine for rectangular layouts; raise it for finer
  layouts.
* **Double-sided** for thin parts seen from both sides (a railing made of planes).
* **Lit (baked vertex colours)** on, so the bridge is shaded like the rest of the level.

### Collision

For a bridge the llama walks on, choose **From the mesh (every triangle)**. For a statue or a
decoration choose **Simplified: invisible box around it** (smooth, cheap) or **None (decoration
only)**. **Material** stays 0 (normal).

### Watch the warnings

The dialog shows how many grid cells the model covers and the triangles in the densest cell. A red
warning about **8000 vertices per tile** means: simplify the model (Blender: *Decimate*) or scale
it up so it spreads over more cells.

6. Choose **Click in the viewport to place**, press **Import** and click the spot where the bridge
   should stand – for example between two platforms.

## 4. Adjust and test

* The bridge is now a **mesh brush**: move it with **W**, turn it with **E** (the red and blue
  rings tilt it freely), scale it with **R**.
* Press **C** to see its collision. Every walkable triangle is coloured.
* Point the camera at the bridge and press **Shift+F5** (**Play from camera position**): the
  llama starts right there. Walk across, then press **Escape** to come back.

![An imported OBJ bridge in the game](img/geo_game_course.jpg)

## 5. Change the model and re-import

Edit the bridge in Blender and export it again under the same name. In the editor, select the
mesh brush and choose **Geometry → Re-import mesh…** → **Yes** reloads the same file. Its
placement, up axis and scale are kept.

## 6. Round trip: from the level to Blender

You can also start from level geometry – to model something that fits exactly onto an original
house or a brush course:

1. Select tiles, brushes or meshes.
2. **File → Export selection as OBJ…**, keep **Also write the collision polygons** on.
3. Import the OBJ into Blender (*Forward -Z, Up Y*). You get the geometry with its textures and
   vertex colours, and `…_collision.obj` with the collision polygons grouped by material.
4. Model your addition around it, export only your new parts, and import them as above.

> **Note:** Exported textures are game data – fine for your own editing, please don't share them.
> Your imported model and its own textures are stored in the project and travel with the
> `.llamalevel` file.

## Troubleshooting

| Problem | Cause and fix |
|---|---|
| model is huge or tiny | wrong unit scale – use **Largest side** + **Fit** |
| model lies on its side | switch **Up axis** |
| no textures | the MTL or the textures were not next to the OBJ – export with *Path Mode: Copy*, or use `.glb` |
| texture looks smeared | UV layout is not rectangular – reset UVs of quads, raise **UV precision** |
| llama falls through | collision is **None** or **Simplified** is not what you wanted – choose **From the mesh**; check with **C** that the surface is coloured; recalculate normals in Blender |
| red 8000-vertex warning | too many triangles in one cell – decimate or scale up |