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/20-troubleshooting.md

@@ -0,0 +1,118 @@
+# Troubleshooting and FAQ
+
+## Setting up and playing
+
+| Problem | Solution |
+|---|---|
+| "This file is not a CD image (ISO)" | You picked another kind of file. Choose the game's `.iso` file, or use **Folder / CD…** for the CD or a copied folder. |
+| "The game was not found here" | The folder is not the game CD. Choose the CD drive itself or a folder you copied the whole CD into – it contains a folder named `Setup`. |
+| "The ISO file is incomplete" | The download or copy of the ISO was interrupted. Copy or download it again. |
+| "Some game files are damaged" | The CD or ISO copy is faulty. Try another copy, or clean the CD. |
+| "Not enough free disk space" | The game copy needs about 900 MB. Free up space or choose another **Data folder**. |
+| The game hangs or its window is gone | Click **■ Quit game** in LlamaMod (the Play button while the game runs). |
+| "The game crashed" | Switch off the mods you turned on last, or click **Restore original**, and play again. If the original game crashes too, report it with `game.log` (**Settings → Logs**). |
+| "groove.exe was removed or changed" | Click **Rebuild**; LlamaMod writes it again and then starts the game. On Windows, see [Antivirus warnings](#antivirus-warnings). |
+
+## The editor
+
+| Problem | Solution |
+|---|---|
+| "OpenGL 3.3 is not available" or a black viewport | Update the graphics driver. In a virtual machine, switch on 3D acceleration. Without a usable driver the editor can still run with software OpenGL, but slowly. |
+| The editor is slow in a big level | Hide what you do not need (**H**, or switch layers off), close the Textures window, use the top view for large moves. |
+| A key does nothing | Single-letter keys do not work while a text field has the focus – click into the viewport first. Some keys are shared by two tools (see [Keys](19-shortcuts.md#keys)); use the toolbar button. |
+| I lost my changes after a crash | Start the editor again and choose **Recover** – autosave keeps unsaved changes (Edit → Preferences sets how often). |
+| A panel is gone | **View → Panels** opens it again. |
+| An object type I want is not in the list | The Objects list shows the base level's types and the ones you imported. Import the type from **Assets → All worlds** ([Importing objects from other worlds](09-objects.md#importing-objects-from-other-worlds)). |
+
+## Building and play-testing
+
+| Problem | Solution |
+|---|---|
+| Build or Play is refused | The Problems panel lists errors; fix them first (double-click a message to find the item). |
+| "The game is still running" | Level files cannot be replaced while the game runs – click **Quit game and play** in the message, or quit the game yourself. |
+| The llama falls through the floor | Show collision (**C**). The floor needs collision: check the brush's collision faces in **Brush shape**, or paint the floor with the **Collision** tool. |
+| **Play from camera position** says there is no floor | Point the middle of the view at walkable ground. Tree crowns, roofs and decoration often have no collision. |
+| The exit does not work | The LevelDoor needs **exit floor (16)** in its cell. The **Exit** setup in the Objects panel places both together. |
+| The level does not load / the game crashes | **Level → Check for problems**; keep tiles inside the grid; exactly one player start; no tile model over 8000 vertices. |
+| My level is missing on the world map | New levels are in world 9 (TestLevel). Unlock it in LlamaMod's **Save games** tab, or play with **F5**. |
+| Two levels show the same content | They use the same TestLevel chapter – change the **TestLevel chapter** option of one of them. |
+| Objects near the start are invisible at first | Also true in the original levels: objects within a few cells of the start appear after a moment. |
+
+## Windows
+
+### Antivirus warnings
+
+Some mods (and every play-test with **Play boots straight into the level**) add code to
+**groove.exe** in LlamaMod's private game copy. Antivirus programs such as Windows Defender may
+report this changed file as a threat – a false positive: your original files are untouched and
+nothing is downloaded.
+
+![LlamaMod's antivirus notice](img/app_av.jpg)
+
+* On Windows, LlamaMod shows a notice before it applies such mods for the first time (Linux
+  has no such problem and shows none).
+* If groove.exe was removed or blocked, LlamaMod says so and offers **Rebuild**.
+* To stop it from happening again, add the LlamaMod data folder as an exclusion: Windows
+  Security → Virus & threat protection → Manage settings → Exclusions → Add or remove exclusions
+  → Add an exclusion → Folder.
+* Or switch off **Level → Play boots straight into the level**: play-tests then start at the
+  main menu and do not change groove.exe.
+
+### Windows in a virtual machine
+
+LlamaMod and the editor work in a virtual machine with 3D acceleration, but the game's old
+DirectX 6/7 graphics often do not: "Direct Draw kann nicht gestartet werden" or an upside-down
+picture are typical. Use a real Windows PC, or play under Wine on Linux. On real hardware no
+extra wrapper should be needed.
+
+## Linux
+
+* The game runs through **Wine**; install it from your distribution. **Settings → Wine command**
+  points LlamaMod at a specific Wine (leave it empty for the installed one); the line below it
+  says whether that Wine was found.
+* The first **Play** prepares Wine for the game, which can take a minute.
+* **Settings → Run in a window** (Wine virtual desktop) is recommended – otherwise the game
+  switches the whole screen to its resolution.
+* LlamaMod uses its own Wine prefix in the data folder, so your other Wine programs are not
+  affected.
+
+## The mod cache
+
+LlamaMod keeps built mod files in the data folder's `cache` folder. If something looks wrong
+after an update, **Settings → Clear cache** throws it away; active mods are rebuilt on the next
+**Apply**.
+
+## Known limits
+
+* Object types from other levels can be imported, but imports are permanent and limited by the
+  engine's 16 MB level memory, 128 sounds and 127 texture pages
+  ([Importing objects](09-objects.md#importing-objects-from-other-worlds)).
+* Tiles and objects only turn about the vertical axis; only brushes scale and turn freely.
+* The engine has no free texture coordinates: every triangle shows one half of a texture
+  rectangle ([Textures](08-textures.md)).
+* At most 8000 vertices per tile model and 127 texture pages per level.
+* Lights only light object models; tiles use baked vertex colours.
+* Texture animations are not animated in the viewport (the texture manager previews them).
+* Many object parameters and some data fields are not understood yet – they are shown raw.
+* The editor was tested mainly on Linux; Windows works, but real Windows hardware has seen less
+  testing.
+
+## FAQ
+
+**Do I need the German version of the game?**
+The tools were developed with the German CD. Other language versions use the same engine and
+should work; if one does not, please report it.
+
+**Can I share levels with people who do not have the game?**
+No – levels are built from the receiver's own game copy. That is also what makes sharing legal:
+a project contains no game data.
+
+**Does the editor change my installed game or my saves?**
+No. LlamaMod works on its own copy in the data folder. Play-tests use one save slot of that copy
+(slot 3 by default) and back it up first.
+
+**Can I edit a level I downloaded?**
+Yes – open the `.llamalevel` file with **File → Open project**.
+
+**Where are my levels?**
+In the `levels` folder of the data folder (**Settings → Data folder → Open folder** in LlamaMod).