fix: update raw.ksy with verified field names, v<32 support, missing color_a

Changes verified against Ghidra RE of ReadNewTerrainFormat (0x0103b920),
RAWReadHeightmap, RAWReadColorandLightMaps, RAWReadFlairData, RAWReadSceneMap,
RAWReadMeshData, FUN_0103aaf0 (blend map reader), and the four legacy terrain
functions (FUN_01013db0, FUN_01013880, FUN_01013640, FUN_01013550) in
legouniverse.exe 1.10.64. Validated against all 309 .raw files across
multiple client versions (v31 and v32) — 309/309 pass.

Chunked format (v30+):
- Rename density → scale (matches client field name)
- Rename diffuse_res → color_map_resolution, diffuse_res_pixels → color_map_pixels
- Rename bits → blend_channel_mask
- Add color_a (u1) to flair_attributes (35→36 byte fix)
- Remove size: 36 override on flairs
- Add version/vert_size guards on mesh data
- Replace unknown1/unknown2 with proper v<32 definitions

Legacy flat-grid format (v<30):
- Document the legacy format in a legacy_grid reference type
- No file header; zone LUZ version determines layout
- Four sub-readers: heightmap, color map, texture, scene map
- Version-dependent field sizes across v0-v29

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: aronwk-aaron

files/raw.ksy

@@ -4,11 +4,32 @@ meta:
   endian: le
   imports:
     - ../common/common
+doc: >
+  LEGO Universe .raw terrain file format.
+
+  There are two distinct formats sharing the .raw extension:
+
+  1. **Chunked format** (zone LUZ version >= 30): Self-describing with a
+     u16 version + u1 dev header, followed by chunked terrain data.
+     This is the format described by the top-level seq below.
+     File versions 31 and 32 are known to exist.
+
+  2. **Legacy flat-grid format** (zone LUZ version < 30): No file header.
+     The zone's LUZ file version determines the field layout. This format
+     uses a single flat grid instead of chunks. Since the file is not
+     self-describing, the legacy format cannot be expressed in this ksy
+     and is documented in the `legacy_grid` type below for reference.
+     No known .raw files use this format in any shipped client.
+
+  The client's `OpenTerrain` function (0x01048080) selects the reader:
+    mapVersion < 30 → legacy flat-grid reader
+    mapVersion >= 30 → `ReadNewTerrainFormat` (chunked reader)
 seq:
   - id: version
     type: u2
   - id: dev
     type: u1
+    doc: Must be 0 for valid terrain data; non-zero aborts loading
   - id: num_chunks
     type: u4
     if: dev == 0
@@ -43,73 +64,92 @@ types:
         type: u4
         repeat: expr
         repeat-expr: 4
-      - id: density
+      - id: scale
         type: f4
+        doc: Heightmap scale factor, used to transform grid coords to world coords
       - id: height_map
         type: f4
         repeat: expr
         repeat-expr: width * height
-      - id: diffuse_res
+      - id: color_map_resolution
         type: u4
         if: _root.version >= 32
-      - id: diffuse_res_pixels
-        size: diffuse_res * diffuse_res * 4
+        doc: Resolution of the color/diffuse map
+      - id: color_map_pixels
+        size: color_map_resolution * color_map_resolution * 4
         if: _root.version >= 32
-        doc: RGBA
-      - id: unknown1
-        type: u1
-        repeat: eos
+        doc: RGBA color map pixels (raw block)
+      - id: color_map_pixels_legacy
+        size: width * width * 4
         if: _root.version < 32
-        doc: todo
+        doc: >
+          v<32 color map. Client reads width*width pixels (4 bytes each)
+          with per-pixel BGRA byte swizzle. colorMapResolution = width - 1;
+          only the inner (width-1)^2 pixels are used.
       - id: diffuse_map_dds_size
         type: u4
         if: _root.version >= 32
       - id: diffuse_map_dds
         size: diffuse_map_dds_size
         if: _root.version >= 32
+        doc: DDS texture data for diffuse/light map
       - id: blend_res
         type: u4
       - id: blend_pixels
         size: blend_res * blend_res * 4
-      - id: bits
+        doc: >
+          Blend/texture map pixels. v>=32 reads as raw RGBA block;
+          v<32 reads per-pixel as B,G,R,A (byte-swizzled).
+      - id: blend_channel_mask
         type: u1
         if: _root.version >= 32
+        doc: Bitmask of active detail textures (bits 0-3)
       - id: blend_map_dds_size
         type: u4
         if: _root.version >= 32
       - id: blend_map_dds
         size: blend_map_dds_size
         if: _root.version >= 32
+        doc: DDS texture data for blend map (DXT5)
       - id: num_flairs
         type: u4
       - id: flairs
         type: flair_attributes
-        size: 36
         repeat: expr
         repeat-expr: num_flairs
       - id: scene_map
-        size: diffuse_res * diffuse_res
+        size: color_map_resolution * color_map_resolution
         if: _root.version >= 32
-      - id: unknown2
-        type: u1
-        repeat: eos
-        if: _root.version < 32
-        doc: todo
+        doc: Per-pixel scene ID assignment, indexes into LUZ scene list
+      - id: scene_map_v31
+        size: width * width
+        if: _root.version == 31
+        doc: >
+          v31 scene map. Allocates (colorMapRes+1)^2 where colorMapRes=width-1.
+          Client reads (colorMapRes+1)^2 cells; inner colorMapRes^2 cells
+          contain scene IDs, border cells are skipped/discarded.
+      - id: scene_map_skip
+        size: 1
+        if: _root.version < 31
+        doc: v<31 skips 1 byte; scene map is zero-filled by client
       - id: vert_size
         type: u4
         if: _root.version >= 32
       - id: mesh_vert_usage
         type: u2
         repeat: expr
         repeat-expr: vert_size
+        if: _root.version >= 32 and vert_size != 0
       - id: mesh_vert_size
         type: u2
         repeat: expr
         repeat-expr: 16
+        if: _root.version >= 32 and vert_size != 0
       - id: mesh_tri
         type: mesh_tri
         repeat: expr
         repeat-expr: 16
+        if: _root.version >= 32 and vert_size != 0
 
   flair_attributes:
     seq:
@@ -127,6 +167,8 @@ types:
         type: u1
       - id: color_b
         type: u1
+      - id: color_a
+        type: u1
   mesh_tri:
     seq:
       - id: mesh_tri_list_size
@@ -135,3 +177,42 @@ types:
         type: u2
         repeat: expr
         repeat-expr: mesh_tri_list_size
+
+  legacy_grid:
+    doc: >
+      Legacy flat-grid terrain format (zone LUZ version < 30).
+      NOT parseable from this ksy — requires the zone's LUZ version
+      as external context since the file has no header. Documented
+      here for reference only.
+
+      This format uses a single flat grid of `width * height` cells
+      instead of the chunked layout. No known .raw files use this
+      format in any shipped client.
+
+      The client's OpenTerrain (0x01048080) calls four functions in
+      sequence, each gated on the zone's map version:
+
+      FUN_01013db0 — Heightmap:
+        v < 4:  width = height = 1280; u16 heights (scaled to float)
+        v 4-10: width = height = 1280; f32 heights (v<11 scaled)
+        v 11+:  u32 width, u32 height from file
+        v 12+:  f32 scale from file (v<12 uses hardcoded 3.0)
+        All:    totalCells = width * height; float heightmap[totalCells]
+
+      FUN_01013880 — Color map:
+        v < 3:  no data (defaults)
+        v 3:    u32 packed ARGB per cell
+        v 4-7:  4x f32 RGBA per cell (scaled by constant)
+        v 8-10: 4x f32 RGBA per cell (unscaled)
+        v 11+:  4x u1 RGBA per cell
+        v 4+:   also 2x f32 UV per cell
+
+      FUN_01013640 — Texture/material:
+        v < 6:  no data
+        v 6-9:  u32 material ID per cell
+        v 10+:  20-byte struct per cell (materialId + blend weights)
+
+      FUN_01013550 — Scene map:
+        v < 20: no data (zero-filled)
+        v 20+:  1024-byte palette, then u1 scene ID per cell
+    seq: []