documentation for level builders: docs index, step-by-step guide, file format reference (wad, geometry, objects, textures, audio, testlevel chapters, engine limits), strat vm and script language with the arena as worked example, tools overview, developer notes; readme rewritten as project front page with screenshots; review notes moved to notes/dev

docs/reference/game-files.md

@@ -0,0 +1,99 @@
+# Game files
+
+What is on the CD and on the hard disk, how files are named, and the small formats around the
+levels. The level files themselves are described in [WAD container](wad.md).
+
+## Two folders: HD and CD
+
+The installer copies a small **HD** part to the hard disk; everything big stays on the **CD**. The
+game looks up each file in `HDPath\dir\file`, then in `CDPath\dir\file`, then on every CD drive
+(`FUN_00415690`). A plain folder in `CDPath` is enough – no real CD drive is needed. LlamaMod relies
+on this: it points `CDPath` at its own `cd-active` folder, where mod outputs replace original files
+([notes/llamamod-app.md](../../notes/llamamod-app.md#registry-cd-path-and-the-exe-patch)).
+
+| Folder | Contents |
+|---|---|
+| HD (`Setup/<lang>/Hd` on the CD) | `groove.exe`, `aal.dll`, `aleax2.3dl`, the audio codecs `asfcodec.adl` and `Vagcodec.adl`, `music/english.cvs` (speech), save games `king0.ksv`…`king2.ksv` |
+| CD (`Setup/<lang>/Cd`) | `wads/` level files, `music/*.asf` music, `movies/*.dat` videos, `*.cor` pictures, `test9.tle`, empty folders `gallery/`, `in/`, `out/` |
+
+Registry key (all values): `HKEY_LOCAL_MACHINE\Software\Disney Interactive\Emperors New Groove\1.0`
+with `CDPath`, `HDPath`, screen size, volumes and devices. LlamaMod's base patch of `groove.exe`
+redirects it to `HKEY_CURRENT_USER`, so no admin rights are needed.
+
+Development used the **German CD**. Other language versions are expected to use the same formats
+but were not tested.
+
+## Level naming scheme
+
+Levels are named **`t<tribe>l<world>m<chapter>`** (tribe is always 1 in the game):
+
+| World | Name | Files | Notes |
+|---|---|---|---|
+| 1 | Village | t1l1m001–004 | `t1l1m001` is the default base level for new levels |
+| 2 | Jungle at Night | t1l2m001–003 | t1l2m003 is the llama chase (player strat `LlamaChase`) |
+| 3 | River | t1l3m001–004 | player strat `KuscoAndPachaTogetherOnATree` |
+| 4 | Jungle by Day | t1l4m001–003 | t1l4m002 has the Alligator (used by the arena) |
+| 5 | Mountain | t1l5m001–003 | |
+| 6 | City | t1l6m001–003 | |
+| 7 | Catacombs | t1l7m001–005 | m001/3/5 are roller-coaster rides (player strat `RollerCoaster`) |
+| 8 | Lab | t1l8m001–006 | |
+| 9 | TestLevel | none on the CD | 49 chapter slots, see [TestLevel](testlevel.md) |
+
+Other WADs: `t0i0m000` (front end), `t0i0m998` / `t0i0m999` (outro and game-over backdrops),
+`t6l6m001/002` (memory-card/options screens – *likely*), `FESOUND.WAD` (front-end sound bank, not
+a chunk file). The chapter counts the world map uses are a table in `groove.exe` (0x572420):
+4, 3, 4, 3, 3, 3, 5, 5, 49 – world 8 has one more file than its table entry (*unknown* why).
+
+## Pictures (COR)
+
+| File | Use |
+|---|---|
+| `T1<w><c>.COR` | loading picture of world *w*, chapter *c* (`T191.COR` … `T1949.COR` for TestLevel) |
+| `<w><c><n>.cor` | concept art shown with a chapter (*likely*) |
+| `tally<n>.cor`, `gameover.cor`, `loading.cor`, logos | screens; `gameovertest.cor` is unused |
+
+Format (*certain*, [`tools/cor2png.py`](../../tools/cor2png.py)): 8-byte signature
+`17 98 AF 89 FE 42 D1 12`, u32 version 1, u32 unpacked size, u32 packed size, then LZ data:
+a byte `n < 0x80` = *n* literal bytes follow; `1LLLoooo oooooooo` = copy L+3 bytes from *o* bytes
+back. The result is 640×480 RGB (a few greyscale ones). [`tools/png2cor.py`](../../tools/png2cor.py)
+and [`CorEncoder.java`](../../src/main/java/com/eliasmueller/llamamod/format/CorEncoder.java) write
+it; LlamaMod uses that for the loading pictures of new levels.
+
+## Movies and demos
+
+* `movies/<w><c><n>intro.dat` / `…outro.dat` and the logo movies: MPEG-1 video 320×240, 29.97 fps,
+  MP2 audio, played through DirectShow. The Intro skip mod patches the calls that start them
+  ([notes/mod-introskip.md](../../notes/mod-introskip.md)).
+* `wads/*.DEM`: recorded attract-mode demos, u32 frame count + 8 bytes of input per frame
+  (*likely*; not used by LlamaMod).
+
+## Save games (KSV)
+
+`king0.ksv`…`king2.ksv` in the game folder, 256 bytes each. Decoded from the load/save functions
+`FUN_0041c640` / `FUN_0041c820`; code: [`save/Ksv.java`](../../src/main/java/com/eliasmueller/llamamod/save/Ksv.java).
+
+| Offset | Meaning |
+|---|---|
+| 0x00 | used flag (0 = empty) |
+| 0x01 / 0x02 | lives / energy |
+| 0x03–0x06 | world-map cursor: tribe, world, chapter, map |
+| 0x07 | number of gold coins |
+| 0x08–0x3D | u8 [9][6] chapter flags (bit 0 collectible found, bit 1 all coins = gold coin) |
+| 0x3E–0x41 | last played tribe, world, chapter, map |
+| 0x42 / 0x43 | highest unlocked world / chapter |
+| 0x44–0xAF | u16 [9][6] coins per chapter |
+| 0xB0–0xCF | unknown |
+| 0xD0–0xD9 | options (effects and music volume, speaker mode, …) |
+
+To start a TestLevel chapter without a mod, set the cursor, the last played and the highest
+unlocked world/chapter to 9 and the chapter. LlamaMod does this with `llamamod --unlock <slot> 9 <chapter> --cursor`
+and with the *Save games* tab.
+
+## Hidden debug features
+
+Strings and code in `groove.exe` point to leftovers of the developers' tools. They were seen in the
+binary but **not** verified or used by LlamaMod: F6 writes a screenshot `capture<n>.tga`, the
+command-line switch `-display_diagnostics` writes a `<PC name>.dispdiag` file, a log
+`c:\kingdom_dbg.txt`, and an unused slide-show player that reads the empty `in`/`out` folders.
+The *Built-in cheats* mod uses the game's own cheat codes
+([notes/mod-cheats.md](../../notes/mod-cheats.md)).