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).

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).

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).

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).

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 ? – 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.

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).

Note: Library pieces stay aligned to whole cells, and objects are not part of them – use prefabs for objects (see Objects).

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.

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.