From 5b180c55791302aedb681943432428331e4dfd78 Mon Sep 17 00:00:00 2001
From: Kelsi <kelsihates2fa@gmail.com>
Date: Tue, 5 May 2026 13:10:48 -0700
Subject: [PATCH] docs: update FORMAT_SPEC with WHM alpha maps, JSON DBC, PNG
 textures

- WHM spec now documents per-chunk alpha map data with backward compat
- Added JSON DBC format section (replaces binary DBC)
- Added PNG texture section (replaces BLP)
- Added open format scoring criteria (0-6 scale)
---
 tools/editor/FORMAT_SPEC.md | 25 +++++++++++++++++++++++--
 1 file changed, 23 insertions(+), 2 deletions(-)

diff --git a/tools/editor/FORMAT_SPEC.md b/tools/editor/FORMAT_SPEC.md
index 891b553a..0333e426 100644
--- a/tools/editor/FORMAT_SPEC.md
+++ b/tools/editor/FORMAT_SPEC.md
@@ -11,8 +11,10 @@ Novel file formats for custom WoW zone content. No Blizzard IP.
 - Extension: `.whm`
 - Magic: `WHM1` (0x314D4857)
 - Version: 1 (embedded in magic — WHM2 for future revisions)
-- Layout: magic(4) + chunks(4) + vertsPerChunk(4) + [baseHeight(4) + heights[145](580)] × 256
-- Total size: 12 + 256 × 584 = 149,516 bytes
+- Layout: magic(4) + chunks(4) + vertsPerChunk(4) + per-chunk data × 256
+- Per-chunk: baseHeight(4) + heights[145](580) + alphaSize(4) + alphaData(alphaSize)
+- Alpha data: raw alpha blend maps for texture layers (same format as ADT MCAL)
+- Backward compatible: older WHM files without alpha data still load (alphaSize=0)
 
 ## WOM — Wowee Open Model (binary)
 - Extension: `.wom`
@@ -41,5 +43,24 @@ Novel file formats for custom WoW zone content. No Blizzard IP.
 - `hasCreatures`, `description`, `tiles` array, `files` map
 - `editorVersion` for compatibility tracking
 
+## JSON DBC — Data Table Replacement
+- Replaces binary DBC files
+- Format: `{"format": "wowee-dbc-json-1.0", "records": [...], "fieldCount": N}`
+- Records are arrays of mixed types: integers, floats, strings
+- Client loads via DBCFile::loadJSON() when found in custom_zones/ or output/
+
+## PNG Textures — Texture Replacement
+- Replaces BLP texture files
+- Standard PNG format, loaded by client's texture override system
+- Editor auto-converts BLP→PNG on export via stb_image_write
+
+## Open Format Scoring (0-6)
+1. WOT terrain metadata present
+2. WHM heightmap with valid magic
+3. zone.json map definition
+4. PNG textures present
+5. WOM models with valid magic
+6. WOB buildings with valid magic
+
 ## All formats are novel, portable, and open for redistribution.
 ## No Blizzard intellectual property is used in any format definition.