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/01-introduction.md

@@ -0,0 +1,104 @@
+# Introduction and concepts
+
+The **LlamaMod level editor** is a 3D editor for the levels of *The Emperor's New Groove* (PC,
+2000, Argonaut's Croc 2 engine; German: *Ein Königreich für ein Lama*). It belongs to
+**LlamaMod**, a mod manager for the same game: every level you make is installed and played as a
+LlamaMod mod, and LlamaMod also brings ready-made mods such as a free camera, a randomizer or a
+mirror mode (see [LlamaMod mods](18-mods.md)).
+
+With the editor you can
+
+* build **new levels** from blocks, ramps, stairs, water, imported 3D models and the game's own
+  tile models, place coins, enemies, checkpoints and the exit, and play them in the game;
+* **change the original levels** – move, add or remove anything, repaint textures, change fog,
+  music and light;
+* **share** your work as a small `.llamalevel` file that contains no game data, so anyone with
+  the game can play it.
+
+> **Note:** The editor never changes your installed game or your CD. LlamaMod works on a private
+> copy of the game data and builds every level from *your own copy* of the game.
+
+## What a level is made of
+
+The game stores each level in one `.wad` file. The editor shows its parts as a tree in the
+**Outliner** and as properties in the **Inspector**:
+
+| Part | What it is |
+|---|---|
+| **Grid and cells** | A level is a rectangular grid of square **cells**. One cell is one grid square in the viewport (4096 game units); the llama is about 0.6 cells tall. Collision is looked up per cell. |
+| **Tiles** | The building blocks of the original levels: a *tile model* placed in one cell, turned in steps about the vertical axis. A model can be used by many tiles. |
+| **Tile models** | The 3D models of the level's tile set with their faces, textures and collision polygons. |
+| **Brushes** | Editor shapes – floors, blocks, platforms, ramps, stairs, walls, round platforms, fences, trees, water, death planes and imported meshes. They have any size and rotation; when the level is built they are cut into 1×1-cell tiles automatically. See [Building geometry](06-geometry.md). |
+| **Objects** | Everything with behaviour: the llama (player start), coins, food, checkpoints, the exit door, enemies, villagers, moving platforms, cameras and triggers. The game calls them *strats* (small scripts). See [Objects](09-objects.md). |
+| **Waypoints** | Chains of points that belong to objects: patrol paths of enemies, camera paths, respawn points, the two corners of trigger boxes. See [Waypoints and paths](10-waypoints.md). |
+| **Zones** | Environment and teleport entries: fog, sky colour, ambient light and music of an area, and the doors that move the player to another place. See [Environment](12-environment.md). |
+| **Lights** | Directional and point lights that light the object models. Tiles get their light from baked vertex colours. |
+| **Visibility regions** | Which parts of the level are drawn from where – the engine's way to stay fast. See [Visibility regions](13-visibility.md). |
+| **Textures** | 256×256 texture pages and the texture rectangles on them, with optional animations. See [Textures](08-textures.md). |
+| **Level settings** | Name, author, grid size, death plane height, feature flags and the TestLevel chapter. See [Level settings](14-level-settings.md). |
+
+## Collision materials
+
+Every collision polygon has a **material** number that tells the game what happens when the llama
+touches it. The important ones:
+
+| Material | Meaning |
+|---|---|
+| **0** | normal ground and walls |
+| **16** | **exit floor** – the level door (LevelDoor object) ends the level when the llama stands on it in the door's cell |
+| **30** | **no floor / death** – the llama falls, loses a life and respawns at the last checkpoint |
+| 17, 18 | selective collision (used by a level feature flag) |
+| others | special surfaces whose meaning is not known yet |
+
+Press **C** in the editor to see collision coloured by material. The **Collision** tool paints
+materials (see [Building geometry](06-geometry.md)).
+
+## Coordinates
+
+Positions are given in **cells**: **x** grows to the east, **y** is the height, **z** is the grid
+row (it grows to the south). The status bar shows the position under the mouse pointer and the
+grid cell. Angles are in degrees; an object with yaw 0° faces +z.
+
+> **Engine limit:** Tiles and objects can only turn about the vertical axis. Brushes can turn
+> freely – the build converts them into tiles.
+
+## Base levels
+
+Object types, their models and scripts, sounds, the sky and the default textures are not
+something the editor can create from nothing. Every project therefore has a **base level**: one of
+the original levels that provides these things. A new level built on *Village chapter 1* can use
+every object that exists in that chapter – coins, checkpoints, villagers, the exit door and so on.
+Choose a base whose objects and look you want. The base level is fixed when the project is
+created. Object types of other levels can be added later with **Assets → All worlds**
+([Importing objects from other worlds](09-objects.md#importing-objects-from-other-worlds)).
+
+## Worlds, chapters and the TestLevel
+
+The game has eight worlds – **Village, Jungle at Night, River, Jungle by Day, Mountain, City,
+Catacombs, Lab** – each with several chapters. A ninth, hidden world called **TestLevel** has 49
+empty chapter slots. New levels go into one of these TestLevel chapters, so they never replace an
+original level: each project gets its own chapter (shown in the New level dialog and in
+[Level settings](14-level-settings.md)). In the game they appear on the world-9 map as
+"TestLevel – chapter *n*".
+
+Edited original levels are different: they replace that original chapter while their mod is
+switched on in LlamaMod.
+
+## Projects
+
+The editor saves **projects** as `.llamalevel` files. A project stores only *your changes* to the
+base level plus your own imported meshes and textures – never the game's files. That keeps
+projects small (often a few kilobytes) and shareable. When a level is built, the editor reads the
+base level from your game copy and applies the changes; building the same project with the same
+game always gives the same result.
+
+LlamaMod lists every project in its **levels** folder as a mod in the **Levels** category. Tick it
+and press **Play** to play the level – or press **F5** in the editor. See
+[Sharing levels](17-sharing.md).
+
+## What you need
+
+* The PC game (CD or ISO image; developed with the German version).
+* LlamaMod – see [Installing LlamaMod](02-installing.md).
+* A graphics card with **OpenGL 3.3** for the editor's 3D view.
+* On Linux, Wine to run the game (LlamaMod sets it up).