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/15-build-play.md

@@ -0,0 +1,100 @@
+# Building, problems and play-testing
+
+Before the game can load your level, the editor **builds** it: brushes and meshes become tiles,
+textures are packed, objects and waypoints are written, and everything is checked. Building is
+fast (a few seconds) and happens in the background, so you can keep working.
+
+## Check for problems
+
+**Level → Check for problems** runs all checks without building. The results appear in the
+**Problems** panel:
+
+![The Problems panel after a check](img/obj_problems.jpg)
+
+* **Errors** (red) would break the level. They block **Build** and **Play** until you fix them.
+* **Warnings** (yellow) are things that probably do not work as you expect.
+* **Info** (blue) are hints.
+
+Double-click a message to select the item it is about (and frame it with **F**). The button in
+the panel's toolbar validates again without building.
+
+### What is checked
+
+| Area | Examples | Details |
+|---|---|---|
+| Level | no player start (error), several player starts, no exit in a new level, no geometry | [Objects](09-objects.md#object-checks) |
+| Geometry | tiles outside the grid, tile models over 8000 vertices, overlapping identical tiles, no floor under the player start, no exit floor (16) in the door's cell, small gaps between floors | [Building geometry](06-geometry.md#geometry-checks) |
+| Objects | wrong parameter counts, values out of range, missing waypoints, impossible exit targets | [Objects](09-objects.md#object-checks) |
+| Waypoints | chains not stored in one piece (with an automatic repair) | [Waypoints](10-waypoints.md#waypoint-checks) |
+| Environment | fog too short or too long, missing start zone, teleport targets outside the grid, black or ignored lights | [Environment](12-environment.md#environment-checks) |
+| Visibility | the player start in a region that does not draw itself, regions that are never drawn | [Visibility regions](13-visibility.md#visibility-checks) |
+| Textures | more than 127 texture pages, textures on missing pages | [Textures](08-textures.md#limits) |
+
+## Build
+
+**Level → Build** (**Ctrl+B**, toolbar **Build**) checks and builds the level. When it is done the
+Problems panel shows **Build OK** with the numbers of tiles (and how many came from brushes),
+objects and waypoints, the size of the level file and the time it took – plus any warnings. The
+status bar keeps the result of the last build; click it to open the Problems panel.
+
+![A successful build](img/geo_build_ok.jpg)
+
+**File → Export level WAD…** builds the level and saves the game file (`.wad`) wherever you like
+– for your own experiments; to play or share a level you do not need it.
+
+## Play-testing
+
+**Level → Play** (**F5**, toolbar **Play**) does everything in one go:
+
+1. builds the level,
+2. installs it in LlamaMod's `levels` folder as a level mod (next to the mods you have switched
+   on),
+3. prepares the play-test save slot (unlocked up to your level),
+4. starts the game **directly in the level** – no logos, no menus, no map.
+
+![The game started straight in the level](img/play_boot.jpg)
+
+In the game, press **Escape** to quit straight back to the editor. When the game has ended,
+LlamaMod switches your normal mod selection back on; the level itself stays installed.
+
+### Play from the camera position
+
+**Level → Play from camera position** (**Shift+F5**) starts the llama on the ground in the middle
+of the view, facing the way the camera looks. Point the view at the spot you want to test – a
+difficult jump, the end of a parkour – and press **Shift+F5**.
+
+![The llama starting where the editor camera looked](img/play_from_here.jpg)
+
+The editor checks that there is walkable **collision** at that point: many things that look solid
+(tree crowns, roofs, decoration) have none. If there is no floor nearby, it tells you instead of
+dropping the llama into the void. The original level's opening fly-by is skipped in this mode.
+
+### Play-test options
+
+| Option (Level menu) | Default | Meaning |
+|---|---|---|
+| **Play boots straight into the level** | on | Off: the game starts at the main menu with the map cursor on your level (choose *Spiel starten* → slot → Enter on the map); groove.exe is not changed. |
+| **Escape quits the play-test** | on | In a play-test the pause key ends the game at once. Off: Escape opens the normal pause menu. |
+| Play-test save slot (**Edit → Preferences**) | 3 | The slot the game plays with; it is backed up before it is changed. |
+
+> **Note:** Booting into the level uses the **Boot to level** mod, which adds code to LlamaMod's
+> private copy of groove.exe. Some antivirus programs warn about such files – see
+> [Troubleshooting](20-troubleshooting.md).
+
+### When something goes wrong
+
+| Message or symptom | What to do |
+|---|---|
+| "The game is still running" | The level files cannot be replaced while the game runs. Click **Quit game and play** to close it and start the play-test, or quit it yourself. |
+| The llama falls through the floor | Look at the collision (**C**); give the floor collision (the brush's collision faces, or a collision material other than 30). |
+| The level door does nothing | The door needs **exit floor (16)** in its own cell – use the **Exit** setup of the Objects panel. |
+| The game crashes while loading | Run **Check for problems** and fix all errors; keep everything inside the grid; only one player start. |
+| Objects are missing in the game | Some objects only appear after an event or a cut-scene; also check the visibility regions. |
+
+More in [Troubleshooting and FAQ](20-troubleshooting.md).
+
+## Playing without the editor
+
+The level is now a mod in LlamaMod's **Levels** category. To play it the normal way, tick it in
+LlamaMod, click **Apply** and **Play**. New levels are on the world-9 (TestLevel) map – unlock
+it in **Save games → Unlock TestLevel (world 9)**; edited original levels replace their chapter.