City files (#2)

* Start

* update

Author: FizzySD

src/SUMMARY.md

@@ -89,5 +89,12 @@
     - [Navigation Vector](./file-formats/navigation-vector.md)
     - [Navpoint Matrix](./file-formats/navpoint-matrix.md)
     - [Fixed Paths](./file-formats/fixed-paths.md)
+    - [Town Map (.town)](./file-formats/town.md)
+    - [Build Mask (.locked)](./file-formats/locked.md)
+    - [City Nodes (.nodes)](./file-formats/nodes.md)
+    - [Spawn Points (.spawn)](./file-formats/spawn.md)
+    - [Isometric Tiles (.let)](./file-formats/let.md)
+    - [Tile Groups (.lgr)](./file-formats/lgr.md)
+    - [AIM Images (.aim)](./file-formats/aim.md)
 - [Community Tools](./community-tools.md)
 - [Appendix](./ch80-00-appendix.md)

src/file-formats/aim.md

@@ -0,0 +1,28 @@
+# AIM Images (.aim)
+The engine's image format, handled by `AIM.dll` and selected as
+`ShaderFormat=aim` in `iso.ini`. It is used both for tile bitmaps in
+`./images/module_stadtkarte/` and for baked town overview images in
+`./iso/towns/<id>.aim`.
+
+The file starts with the magic `AIM\0`, followed by an embedded name string and
+a sequence of chunks of the form `{ Type, Size, Data }`:
+```
+0000  41 49 4d 00 ...        "AIM\0"
+0009  6c 61 6c 61 00         embedded name string
+...   chunks { Type, Size, Data }
+```
+
+| Chunk Type | Encoding | Example |
+|-|-|-|
+| `22` | RGB / BGR, uncompressed | town overview `0.aim` (`272 x 155`) |
+| `34` | compressed indexed BGRA | tile bitmaps |
+
+Tile bitmaps are sheets of `34 x 21` diamonds keyed on magenta (`FF 00 FF`); a
+single file may hold several variants. The overview `iso/towns/<id>.aim` decodes
+to a `272 x 155` painted image (the same size as the matching `.tga`), not a tile
+render.
+
+`.aim` files can be converted to and from PNG with the community `aim_converter`
+tool (`to-png` / `to-aim`).
+
+[To be completed]

src/file-formats/let.md

@@ -0,0 +1,32 @@
+# Isometric Tiles (.let)
+Individual isometric tiles are stored in `./iso/let/<name>.let`
+(`TileFormat=let` in `iso.ini`). A `.let` file is a small (~104 byte) descriptor
+that binds a tile to its bitmap; it does not contain pixel data itself.
+
+The descriptor is defined as:
+
+| Offset | Type | Field |
+|-|-|-|
+| `0x08` | `u8[4]` | colour key, magenta `FF 00 FF` |
+| `0x10` | `uint32` | tile width (`34`) |
+| `0x14` | `uint32` | tile height (`21`) |
+| `0x30` | `uint32` | source width |
+| `0x34` | `uint32` | source height |
+| `0x38` | `uint32` | path length |
+| `0x3c` | ASCII | NUL-terminated path to the [`.aim`](./aim.md) bitmap |
+
+For example, `1_1.let`:
+```
+0000  00 52 1b 01 0e 00 00 00 ff 00 ff ff 00 00 00 00
+0010  00 00 00 00 22 00 00 00 15 00 00 00 01 00 00 00
+0020  01 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00
+0030  22 00 00 00 15 00 00 00 28 00 00 00 69 6d 61 67   "imag
+0040  65 73 5c 6d 6f 64 75 6c 65 5f 73 74 61 64 74 6b   es\module_stadtk
+0050  61 72 74 65 2f 77 61 73 73 65 72 5f 6e 65 75 2e   arte/wasser_neu.
+0060  61 69 6d 00 00 00 00 00                           aim
+```
+points at `images\module_stadtkarte/wasser_neu.aim` (water).
+
+The tile size (`34 x 21`) matches `TileSize` in `iso.ini`. Tiles named
+`1_1`..`9_9` are ground tilesets; the remaining named files are objects.
+Variants are bundled by [tile groups](./lgr.md).

src/file-formats/lgr.md

@@ -0,0 +1,16 @@
+# Tile Groups (.lgr)
+Groups of interchangeable tiles are stored in `./iso/let/<name>.lgr`
+(`GroupFormat=lgr` in `iso.ini`). Unlike most of the engine's formats, a `.lgr`
+file is plain INI text. The engine treats the members as variants of one tile.
+```ini
+[GROUP]
+Type=2
+FileCnt=72
+File0=0 0 1_6.let
+File1=0 0 1_2.let
+File2=0 0 1_3.let
+...
+```
+Each `File<n>` entry is `offsetX offsetY <name>.let`, and `FileCnt` is the number
+of member [tiles](./let.md). For example, `Wasser_NEU.lgr` groups 72 water tile
+variants.

src/file-formats/locked.md

@@ -0,0 +1,14 @@
+# Build Mask (.locked)
+The build mask of a town is stored in `./iso/towns/<id>.locked`
+(`LockFormat=locked` in `iso.ini`).
+
+It is a flat array of one byte per tile covering the town area only
+(`128 x 226 = 28928` bytes, no header).
+
+| Value | Meaning |
+|-|-|
+| `0x00` | buildable |
+| `0x01` | locked |
+
+The entry for column `x` and row `y` (`0..225`) is the byte at `y * 128 + x`.
+The covered area matches rows `0..225` of the [town map](./town.md).

src/file-formats/nodes.md

@@ -0,0 +1,24 @@
+# City Nodes (.nodes)
+The polyline data of a town is stored in `./iso/towns/<id>.nodes`
+(`NodesFormat=nodes` in `iso.ini`).
+
+It is a list of sections, each holding a number of nodes (polylines), each
+holding a number of points. All values are `uint32`. The file format is defined
+as:
+```
+File    := Section[]
+Section := { SectionID, NodeCount, Node[NodeCount] }
+Node    := { PointCount, Point[PointCount] }
+Point   := { X, Y }
+```
+A sample file holds 5 sections (60 nodes, 303 points):
+
+| Section | Nodes | Description |
+|-|-|-|
+| 0 | 24 | ships town docking path (polylines starting near `y = 10`) |
+| 1, 2 | 3 + 3 | citizen route paths (those boundaries have to be 22pixel apart) |
+| 3 | 1 | small 4 point region |
+| 4 | 29 | detail features |
+
+The coordinates use a pixel/unit space (observed `X` `17..4352`, `Y`
+`10..2353`), not the tile grid.

src/file-formats/spawn.md

@@ -0,0 +1,13 @@
+# Spawn Points (.spawn)
+Spawn data of a town is stored in `./iso/towns/<id>.spawn`
+(`SpawnFormat=spawn` in `iso.ini`).
+
+The file is an array of `uint32` values that decode as pairs and appear to be
+grouped into sections, similar to the [nodes](./nodes.md) file:
+```
+          | 00  01   02  03   04  05   06  07 |
+00000000  | A      | B      | A      | B      |
+```
+The first value of each pair (`A`) lies in the tile-column range (`0..127`),
+while the paired value (`B`) increases monotonically within a run. The exact
+field semantics and section boundaries have not been identified.

src/file-formats/town.md

@@ -0,0 +1,37 @@
+# Town Map (.town)
+The isometric tile map of a town is stored in `./iso/towns/<id>.town`.
+A sibling file `<id>.editor` uses the same layout.
+
+A map is a grid of `128 x 452` tiles. The file is a 26 byte header followed by
+the tile array of `128 * 452 = 57856` tiles, 4 bytes each (`57856 * 4 = 231424`
+bytes), so the tile data begins at offset `0x1a`.
+
+Each tile is defined as:
+```
+          | 00  01   02  03 |
+00000000  | Tile ID | Terrain |
+```
+`Tile ID` is a `uint16` selecting the ground or object tile (observed range
+`0..904`). `Terrain` is a `uint16` that packs the elevation level and a slope
+code as `Terrain = (Level << 8) | Slope`:
+
+| Slope | Meaning |
+|-|-|
+| `0x00` | flat |
+| `0x01`..`0x06` | slope direction |
+| `0xff` | scarp / cliff edge |
+
+The tile at column `x` (`0..127`) and row `y` (`0..451`) is located at
+`0x1a + (y * 128 + x) * 4`.
+
+The grid is split at row `226`: rows `0..225` cover the town itself (the same
+area as the [build mask](./locked.md)), while rows `226..451` describe the
+surrounding world and sea.
+
+The `Tile ID` does not map directly to a [tile](./let.md) filename. The lookup
+from `Tile ID` to a concrete tile is resolved internally by the engine and is
+not stored in the game's text files.
+
+## Header
+The purpose of most of the 26 byte header is not yet identified. The `uint16` at
+offset `0x02` holds the map width (`128`).