llamamod/docs/manual/tutorial-blender.md

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.

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