118 lines
6.0 KiB
Markdown
118 lines
6.0 KiB
Markdown
# 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.
|
||
|
||
|
||
|
||
### 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.
|
||
|
||
|
||
|
||
## 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 |
|