feat: Implement Map Loading Architecture (PRP 1.5)

[dcversus]

🗺️ Map Loading Architecture Implementation

Implements PRP 1.5 - Complete map loading system supporting classic RTS formats with legal asset replacement.

---

📋 Summary

This PR adds comprehensive map loading functionality for:

• W3X/W3M (Warcraft 3) maps
• SCM/SCX (StarCraft 1) maps
• EdgeStory format (legal, glTF 2.0 based)

All with automatic conversion to copyright-compliant assets.

---

✨ Features

1. W3X/W3M Support (~1,500 lines)

• ✅ W3IParser: Map info, players, forces, random tables
• ✅ W3EParser: Terrain heightmap, textures, water levels, cliffs
• ✅ W3DParser: Doodad placements with item drops
• ✅ W3UParser: Unit placements with hero properties, inventory
• ✅ W3XMapLoader: Complete MPQ extraction and orchestration

2. SCM/SCX Support (~450 lines)

• ✅ CHKParser: Chunk-based format (VER, DIM, ERA, MTXM, UNIT, SPRP)
• ✅ SCMMapLoader: MPQ extraction and CHK parsing
• ✅ Tile map to heightmap conversion

3. EdgeStory Format (~550 lines)

• ✅ EdgeStoryFormat: glTF 2.0 based type definitions
• ✅ EdgeStoryConverter: Converts proprietary → legal format
• ✅ AssetMapper: 60+ unit/building mappings (CC0/MIT)
• ✅ Copyright validation system

4. Unified API (~450 lines)

• ✅ MapLoaderRegistry: Single entry point for all formats
• ✅ Progress tracking callbacks
• ✅ Statistics (load time, unit count, terrain size)
• ✅ Export to JSON/Binary

---

🏗️ Architecture

src/formats/maps/
├── MapLoaderRegistry.ts      # Main API (200 lines)
├── AssetMapper.ts             # Asset replacement (320 lines)
├── types.ts                   # Common types (230 lines)
├── w3x/                       # Warcraft 3 (1,580 lines)
│   ├── W3XMapLoader.ts
│   ├── W3IParser.ts
│   ├── W3EParser.ts
│   ├── W3DParser.ts
│   └── W3UParser.ts
├── scm/                       # StarCraft 1 (570 lines)
│   ├── SCMMapLoader.ts
│   └── CHKParser.ts
└── edgestory/                 # Legal format (500 lines)
    ├── EdgeStoryConverter.ts
    └── EdgeStoryFormat.ts

Total: ~3,000 lines of production code

---

💻 Usage

import { MapLoaderRegistry } from '@/formats/maps';

const registry = new MapLoaderRegistry();

// Load any supported format
const result = await registry.loadMap(file, {
  convertToEdgeStory: true,
  validateAssets: true,
  onProgress: (stage, progress) => {
    console.log(`${stage}: ${progress}%`);
  }
});

// Access results
console.log(`Loaded ${result.stats.unitCount} units`);
console.log(`Terrain: ${result.stats.terrainSize.width}x${result.stats.terrainSize.height}`);
console.log(`Load time: ${result.stats.loadTime}ms`);

// Export to EdgeStory format
const json = registry.exportEdgeStoryToJSON(result.edgeStoryMap);

---

🛡️ Legal Compliance

Asset Replacement System

• 60+ mappings from copyrighted to legal assets
• CC0/MIT licenses only
• Automatic copyright validation
• Asset source attribution

Example Mappings

W3X: 'hfoo' (Footman) → 'edge_warrior_melee_01' (CC0)
W3X: 'hpea' (Peasant) → 'edge_worker_01' (CC0)
SCM: 'Terran Marine' → 'edge_infantry_rifle_01' (CC0)
SCM: 'Zerg Zergling' → 'edge_melee_fast_01' (CC0)

---

✅ Success Criteria

• ✅ Architecture: All files <500 lines
• ✅ W3X Support: Full parser for w3i, w3e, doo, units files
• ✅ SCM Support: Complete CHK format parser
• ✅ EdgeStory Format: glTF 2.0 based with extensions
• ✅ Asset Replacement: 100% legal alternatives
• ✅ Type Safety: TypeScript strict mode passes
• ✅ Clean Room: Zero copyrighted content

---

📊 Performance Targets (Future)

Benchmarks to be added in testing phase:

• W3X load: <10s for typical map
• SCM load: <5s for typical map
• Memory: <512MB during conversion
• Accuracy: 98% terrain conversion

---

🔗 Related Work

Depends on:

• PRP 1.1: Babylon.js Integration
• PRP 1.2: Advanced Terrain System
• MPQ Parser (already implemented)

Enables:

• JASS → TypeScript transpilation
• SC2Map support (CASC format)
• Enhanced asset library
• Map editor integration

---

🧪 Testing

All code passes TypeScript strict type checking:

npm run typecheck  # ✅ Passes with 0 errors

Unit tests to be added in separate PR (test infrastructure setup).

---

📝 Documentation

• PRP: PRPs/phase1-foundation/1.5-map-loading-architecture.md
• Format Research: PRPs/phase5-formats/FORMATS_RESEARCH.md
• Code Documentation: JSDoc comments throughout

---

🚀 Next Steps

1. Add comprehensive test suite
2. Integrate with Babylon.js renderer
3. Add SC2Map support (CASC parser)
4. Build asset library (CC0/MIT models)
5. Performance benchmarking

---

Refs: PRP 1.5 - Map Loading Architecture