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/02-installing.md

@@ -0,0 +1,88 @@
+# Installing LlamaMod and the first start
+
+LlamaMod runs on **Windows** and **Linux**. It needs your own copy of the game – the CD or an ISO
+image of it. The game itself does not have to be installed: LlamaMod copies what it needs into
+its own data folder and never changes the original.
+
+## Download and start
+
+| System | Package | Start |
+|---|---|---|
+| Windows | `LlamaMod-<version>-full-windows-x64.zip` | Unzip anywhere and start **LlamaMod.exe**. Keep `LlamaMod.exe` and the `runtime` folder together. No installation and no administrator rights are needed. |
+| Linux | `LlamaMod-<version>-full-linux-x64.tar.gz` | Unpack and start `./LlamaMod`. `./install-desktop-entry.sh` adds a menu entry. Install **Wine** to run the game. |
+
+Both packages bring their own Java runtime. The editor's 3D view needs a graphics driver with
+**OpenGL 3.3** (any graphics card from the last ten years).
+
+## First start: setting up the game
+
+On the first start a wizard asks where your game is:
+
+![The setup wizard](img/app_wizard.jpg)
+
+1. Choose **ISO file…** for a CD image, or **Folder / CD…** for the inserted CD or a copied
+   folder. LlamaMod shows how many files it found and how much disk space it needs – or, in red,
+   what is wrong: the file is not a CD image, the folder does not contain the game, the ISO file
+   is incomplete (an interrupted download), or the disk is too full.
+2. Check the **Data folder**. Game copy, mods, save games and settings are stored there. The
+   default is `%LOCALAPPDATA%\LlamaMod` on Windows and `~/.local/share/LlamaMod` on Linux;
+   **Change…** picks another place.
+3. Click **Set up**. LlamaMod copies the game data, checks it for damaged files and reports
+   **All set!** **Cancel** stops the copy; clicking **Set up** again continues where it stopped.
+
+You can repeat this later with **Settings → Set up again…**.
+
+## The LlamaMod window
+
+![LlamaMod's mod list](img/app_mods.jpg)
+
+* **▶ Play** (top right) starts the game with the selected mods. While the game runs, the button
+  reads **■ Quit game** – handy when the game hangs or its window is hidden. If the game
+  crashes, LlamaMod says so and offers to open the log files.
+* **Level Editor** (next to Play) opens the level editor in its own window.
+* The **Mods** tab lists all mods by category (**Levels**, **Gameplay**, **Visual**,
+  **Cheats & debug**). Tick the ones you want, set their options (each one is explained next to
+  it) and click **Apply**. **Restore original** switches all mods off. Mods marked *modifies groove.exe* change the
+  game program in LlamaMod's private copy (see [antivirus warnings](20-troubleshooting.md)).
+  All mods and their options are listed in [LlamaMod mods](18-mods.md).
+* The **Save games** tab edits the three save slots: unlocked worlds and chapters, coins, gold
+  coins and collectibles per level, lives, where the world map **Opens at**, **Unlock all
+  worlds** and **Unlock TestLevel (world 9)**. **Undo changes** throws away unsaved edits. A
+  backup is made before every change (**Backups** opens the folder); **Import…** reads a `.ksv`
+  file and starts in the backups folder, so restoring a backup is two clicks.
+* The **Settings** tab sets the game resolution (**Automatic** shows the size it will use),
+  **Run in a window** (Linux: Wine virtual desktop, recommended), the light or dark
+  **Appearance**, the Wine command, the data folder (**Open folder**, **Logs**), **Set up
+  again…** (copies the game once more; mods, settings and save games are kept) and **Clear
+  cache** for the mod cache.
+
+![The save game editor (dark theme)](img/app_saves.jpg)
+
+> **Tip:** Every level project in the data folder's `levels` folder appears as a mod in the
+> **Levels** category. That is how you install levels from other people – see
+> [Sharing levels](17-sharing.md).
+
+## Starting the editor
+
+* Click **Level Editor** in LlamaMod's header, or
+* start LlamaMod with `--editor`, optionally followed by a project file or the name of an
+  original level, for example `LlamaMod --editor t1l1m001` (Village chapter 1).
+
+The editor opens with a start page: **New level**, **Open original level**, **Open project** and
+your recent projects. **Help → Getting started** (**Shift+F1**) shows a five-step tour, and this
+manual is always one **F1** away.
+
+![The editor's start page](img/ui_empty.jpg)
+
+## The data folder
+
+| Folder | Content |
+|---|---|
+| `levels/` | your level projects (`.llamalevel`) – each one is a mod |
+| `editor/` | editor settings, autosaves, prefabs |
+| `library/` | geometry saved to the editor's library (`.llamamesh`) |
+| `original/` | the untouched copy of the game from your CD |
+| `game/`, `cd-active/` | the copy the game runs from, with the active mods applied |
+| `cache/` | built mod files (cleared with **Settings → Clear cache**) |
+| `backups/saves/` | save game backups |
+| `logs/` | log files (game, mod apply) for troubleshooting |