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/tutorial-blender.md

@@ -0,0 +1,117 @@
+# 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.
+
+![The Import mesh dialog with preview and options](img/geo_import.jpg)
+
+### 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.
+
+![An imported OBJ bridge in the game](img/geo_game_course.jpg)
+
+## 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 |