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/13-visibility.md

@@ -0,0 +1,114 @@
+# Visibility regions
+
+The game was written for PCs of the year 2000. To keep the frame rate up it does not draw the
+whole level all the time: the level grid is divided into up to **32 visibility regions**, and for
+each region a *mask* says which regions can be seen from there. In the Village, for example, the
+inside of a house is not drawn while you stand outside.
+
+New levels start with one region where everything is visible – fine for small levels. For big
+levels, or when you change an original level so that new parts become visible, you edit the
+regions here.
+
+## How the engine decides what to draw
+
+1. The game takes the grid cell the **camera** is in and looks up that cell's region.
+2. The region's **mask** has one bit per region. Tiles and objects in cells whose region bit is
+   set are drawn; all others are skipped.
+3. A mask of **0** means "draw everything". When the camera is **outside the grid**, everything
+   is drawn as well.
+
+So a row in the mask table answers "standing here, what do I see?". A region must always see
+itself – otherwise the ground under the llama and the llama itself would vanish.
+
+> **Note:** it is the camera's cell that counts, not the llama's. The camera hangs a few cells
+> behind the player, so give neighbouring regions some overlap.
+
+## Visibility panel
+
+**Level → Visibility regions** opens the **Visibility** panel (right dock).
+
+![Painting regions while the Visibility panel shows the mask matrix](img/env_regions.jpg)
+
+### Mask matrix
+
+A 32 × 32 grid of check cells: the **row** is the region the camera is in, the **column** is the
+region that is drawn (header *cam↓ draw→*). Click a cell to toggle it, drag to paint several.
+Regions that no cell uses are dimmed. Clicking a row label picks that region (for the preview and
+the region brush). A row without any bit means "everything" – the engine rule above.
+
+Hovering a row shows how many cells the region has, its own triangles and how many triangles the
+game draws with the camera there.
+
+### Masks
+
+| Control | What it does |
+|---|---|
+| **Symmetric** | While on, toggling *A sees B* also sets *B sees A*. |
+| **All visible** | Every region sees every region. |
+| **Self only** | Every region sees only itself (a starting point for hand-made masks). |
+| **Make symmetric** | If A sees B, B now also sees A. |
+| **Auto-generate…** | Computes regions and masks from the level layout (see below). |
+| **Paint regions** | Starts the region brush in the viewport. |
+
+### Preview
+
+**Show** hides in the viewport what the game would not draw:
+
+| Setting | Shows |
+|---|---|
+| **Off (draw everything)** | The normal editor view. |
+| **Follow the camera** | What the game draws for the region the editor camera is in – fly around and watch parts appear and disappear. |
+| **From region n** | What the game draws for a camera in region *n*. |
+
+The preview hides tiles and objects through the editor's hidden flags and restores exactly the
+items it hid; things you hid yourself stay hidden. While it is active they show as hidden in the
+Outliner.
+
+![Previewing the Village from one region: the parts the game would skip are hidden](img/env_region_preview.jpg)
+
+### Statistics
+
+The bottom of the panel shows how many regions are in use and the triangles drawn per camera
+region (maximum and mean). A warning appears when one region draws a lot – the original levels
+stay well below 30 000 triangles.
+
+## Auto-generate
+
+**Auto-generate…** opens *Auto-generate visibility regions*:
+
+| Option | Meaning |
+|---|---|
+| **Layout** | **One region, everything visible**; **Rectangular blocks, visible within a distance**; **Connected areas (islands / rooms), visible within a distance** (default – flood-fills connected floors, at most 32 areas). |
+| **Visible within (cells)** | Regions closer than this see each other. The fog end distance of the level is a good value (default 12). |
+
+It replaces the region of every cell and all masks in one undo step. The result line names the
+highest number of triangles drawn from one region; if it is heavy for the original engine it
+suggests a smaller distance or more, smaller areas.
+
+> **Tip:** more regions means less to draw, but areas can pop in when the camera crosses a
+> border. Always check the result with **Follow the camera** and in a play-test.
+
+## Paint regions tool
+
+The **Paint regions** tool sets the region of grid cells with a square brush. It switches the
+*Visibility regions* layer on, which colours every cell by its region.
+
+| Option | Meaning |
+|---|---|
+| **Region** | The region to paint (colour swatches, Region 0–31). |
+| **Brush** | 1 × 1, 3 × 3, 5 × 5, 9 × 9 or 17 × 17 cells. |
+| **Ctrl+click** | Picks the region of a cell. |
+
+The masks are edited in the Visibility panel. Cells added by growing the grid get region 0.
+
+## Visibility checks
+
+Building and **Level → Check for problems** report:
+
+* **error** – the player start is in a region whose mask does not include the region itself (the
+  ground and the llama would be invisible);
+* **warning** – a region whose geometry is never visible from any region;
+* **info** – a region that draws more than 30 000 triangles (heavy for the original engine; the
+  fog distance limits it further).
+
+The Village (96 × 96 cells) uses 22 of the 32 regions.