llamamod/docs/manual/07-meshes.md

# Importing meshes and the library

Brushes cover blocks, ramps and stairs. For everything else – a bridge, a ruin, a statue – you
can import a 3D model from Blender or any other modelling program. The editor turns it into a
**mesh brush**: when the level is built, the model is cut into the engine's 1×1-cell tiles, gets
collision and lit vertex colours, and its textures are packed onto texture pages.

The **library** works the other way round: it saves geometry from any level (original tiles,
brushes and meshes, with their textures) so you can insert it into other levels. And **Export
selection as OBJ** takes level geometry to Blender, **Export level as glTF** the whole level.

## Supported files

| Format | What is read |
|---|---|
| **OBJ** (`.obj` + `.mtl`) | triangles and polygons, UVs, materials with diffuse colour (`Kd`) and texture (`map_Kd`), optional vertex colours (`v x y z r g b`) |
| **glTF 2.0** (`.gltf` with external or embedded buffers and images, `.glb`) | node transforms, base colour factor and texture, vertex colours (`COLOR_0`), double-sided materials |

Textures may be PNG or JPG. The model file and every file it references are **copied into the
project**, so the `.llamalevel` file stays complete when you share it (see
[Sharing levels](17-sharing.md)).

## Import mesh dialog

**File → Import mesh (OBJ, glTF)…** (or **Import mesh…** in the **Imported** tab of the Assets
panel) asks for the file and opens the import dialog. The left side is a preview you can orbit by
dragging; the grid squares are 1 cell and the small marker shows the llama's size (0.6 cells).

![The Import mesh dialog](img/geo_import.jpg)

**Source** shows the file name, triangle and vertex count, materials and the resulting size in
cells.

### Orientation and size

| Option | Meaning |
|---|---|
| **Up axis** | **Y up (glTF, most OBJ)** or **Z up (some CAD exports)** |
| **Unit scale (file units → cells)** | how many cells one unit of the file is |
| **Largest side** … **cells** + **Fit** | sets the unit scale so the largest side becomes this many cells (default 4) |
| **Turn** | 0°, 90°, 180° or 270° about the vertical axis |
| **Mirror (left ↔ right)** | mirrors the model |
| **Stand on the ground (bottom at the click point)** | puts the lowest point of the model on the surface you click |

### Textures

| Option | Meaning |
|---|---|
| **Texture size on the page** | 32, 64, **128** or 256 pixels: the size each material texture gets on the level's texture pages |
| **UV precision (steps per texture)** | 4, **8**, 16 or 32: how finely each triangle's texture rectangle is rounded |
| **Double-sided** | faces are drawn from both sides (thin walls, leaves) |
| **Lit (baked vertex colours)** | the model gets lighting like the rest of the level; off = full brightness |

### Collision

| Choice | Result |
|---|---|
| **From the mesh (every triangle)** | every triangle becomes a collision polygon – exact, the llama can walk on all surfaces |
| **Simplified: invisible box around it** | an invisible block around the model instead – cheap and smooth, good for statues and props |
| **None (decoration only)** | no collision at all |

**Material** sets the collision material (0 normal, 16 exit floor, 30 death … see
[Building geometry](06-geometry.md)).

### Warnings

Below the options the dialog estimates how the model will be cut: how many grid cells it covers
and how many triangles land in the densest cell. It warns in red when

* a cell may exceed the engine's **8000 vertices per tile** – simplify the mesh or scale it up,
* the model is **larger than the level grid**.

### Placement

* **Click in the viewport to place** – after **Import**, a box follows the cursor; click where
  the model should stand.
* **At the view centre** – the model is placed at the point you look at.

The status bar then says "Placed … – move/turn/scale it with the gizmo tools".

## The engine's texture rules

> **Engine limit:** the engine has no free texture coordinates. Every triangle always shows one
> half of a rectangular area of a texture page.

The importer therefore gives each triangle the rectangle around its UVs (rounded to the **UV
precision**) on a copy of its material's texture, flipped where that fits better. In practice:

* **Rectangular quads with UVs that fill the texture map exactly** – the ideal case (walls, planks,
  floors).
* Arbitrary UV layouts (unwrapped characters, atlases) are approximated and can look blurry or
  shifted.
* UVs beyond 0…1 (tiling) are clamped – repeat the geometry instead of the texture.
* Untextured materials use their flat colour; vertex colours tint the lighting.

Imported textures are packed onto new 256×256 texture pages at the chosen size. Several mesh
imports add several pages; the engine allows at most 127 pages per level (see
[Textures](08-textures.md)).

## Mesh brushes

An imported model is listed in the Outliner under **Imported meshes** (the file) and under
**Brushes** (each placed copy, a *mesh brush*). The **Imported** tab of the Assets panel shows all
meshes of the project: drag one into the viewport to place another copy.

A mesh brush moves, turns and scales with the gizmo tools like any brush, including free 3D
rotation (about its origin) and per-axis stretching with the Scale tool. Its parameters in the
Inspector:

| Parameter | Meaning |
|---|---|
| **Mesh asset** | the imported file it shows |
| **X / Y / Z**, **Rotation (°)**, **Scale** | placement |
| **Collision**, **Collision material** | collision from the mesh |
| **Double-sided**, **Lit (vertex colours)** | as in the dialog |
| **Texture size on the page (16-256)**, **UV rectangle precision (steps per texture)** | as in the dialog |
| **Tint (r, g, b)** | colour multiplier |

The **Brush shape** section (rotation fields, quarter turns, mirror, **Visible**, face table)
works as for other brushes.

### Re-import mesh

Changed the model in Blender? Select the mesh brush and choose **Geometry → Re-import mesh…**.
The editor remembers the source file and asks **Reload <file>?** – **Yes** loads the same file
again, **No** lets you choose another file. Up axis, unit scale and the placement of the brush are
kept.

## The library

The library stores pieces of geometry as reusable assets, available in **every** level and on
every base level – a village house in a jungle level, a set of platforms you built once.

![The Library tab in the Assets panel](img/geo_library.jpg)

### Saving to the library

1. Select tiles, brushes and/or mesh brushes.
2. Choose **Geometry → Save selection to library…** or **Save selection…** in the **Library** tab.
3. Enter a name (**Save to library**).

The asset is written to `<data>/library/<name>.llamamesh` (the LlamaMod data folder). It contains
the tile models with their collision and vertex colours and every texture used, as pictures.
Brushes and meshes are stored in their built form (tiles). Death-plane tiles are left out.

### Inserting from the library

* Drag an entry from the **Library** tab into the viewport – it is anchored at the cell under the
  drop point, or
* double-click it or press **Insert** – it is placed at the view centre.

Textures with identical pixels already in the level are reused; the others are packed onto new
texture pages (with their blend mode). Identical tile models are reused too. **Delete** removes
the entry from the library (not from levels that already use it).

![Library pieces inserted into a new level (right) and the same geometry re-imported from OBJ (left)](img/geo_library_insert.jpg)

> **Note:** Library pieces stay aligned to whole cells, and objects are not part of them – use
> prefabs for objects (see [Objects](09-objects.md)).

> **Note:** A library file contains pictures of the game's textures. It is meant for your own
> projects; when you share a level, the textures it uses are stored in the project anyway.

## Export selection as OBJ

**File → Export selection as OBJ…** writes the selected tiles, brushes and meshes as a Wavefront
OBJ for Blender:

* `name.obj` + `name.mtl` + one PNG per texture,
* UVs per triangle (the texture-rectangle halves the engine uses),
* vertex colours as `v x y z r g b`,
* with **Also write the collision polygons (…_collision.obj)** a second OBJ with the collision
  polygons, grouped by material.

The coordinates use the importer's convention, so the file can be imported again unchanged: edit
it in Blender, then **File → Import mesh** it back (round trip).

> **Note:** The exported textures are game data – fine for your own editing, please don't share
> them.

## Export the level as glTF

**File → Export level as glTF…** writes the whole level – tiles, brushes and meshes – as one glTF
2.0 file for Blender or any 3D viewer:

* **.glb** (binary) or **.gltf** (text, everything in one file), chosen by the file type,
* the level's texture pages as PNG pictures inside the file, the game's vertex colours
  (light and shade) as vertex colours, transparent and double-sided parts as such,
* unlit materials, so viewers show the baked colours like the game.

| Option | Meaning |
|---|---|
| **Object models** | also the models of placed objects (coins, characters …) as the viewport shows them |
| **Leave out hidden items** | items hidden in the editor (**H**) are not exported |
| **Game orientation** | mirrors the level so that Blender and viewers show it the same way round as the game. Off: the same axes as the OBJ export and **Import mesh**, so the file can be imported again unchanged |

Tiles with **Exclude from build** are left out. 1 unit is 1 cell.

![glTF export dialog and the exported village read back by Import mesh](img/geo_gltf_export.jpg)

> **Note:** The exported textures are game data – fine for your own use, please don't share them.

## Tips for good meshes

* Model at the right scale: 1 cell is one grid square, the llama is about 0.6 cells tall. Use
  **Fit** in the dialog if the file has other units.
* Keep the polygon count low – the original levels use simple shapes. Very dense meshes hit the
  8000-vertex limit per cell.
* Use simple, rectangular UV layouts and one texture per material.
* Choose **Simplified: invisible box** for decorative props the llama should not climb.
* Check the collision with the **Collision** layer (**C**) and play-test from the spot with
  **Shift+F5**.

A step-by-step example is the [Blender tutorial](tutorial-blender.md).