initial commit: llamamod 0.2.0 – reverse-engineered level formats (wad, map, trak, text, stpc), python tools and notes, java mod manager (iso install, mod pipeline with exe patching, save editor, wine/windows launcher) with mods (test world, debug wireframe, mirror, randomizer, fog, cheats, intro skip, practice, free camera, boot to level, level projects) and the 3d level editor (geometry, objects, cross-world import, environment, textures, play-test, manual)

docs/manual/07-meshes.md

@@ -0,0 +1,192 @@
+# 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.
+
+## 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.
+
+## 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).