# Classe Map - Générateur de Cartes Hexagonales

## Vue d'ensemble

La classe `Map` permet de créer et gérer des cartes composées d'hexagones (damier hexagonal). Chaque hexagone peut contenir une tuile avec des propriétés arbitraires (type, ressources, température, élévation, etc.).

## Architecture

### Classe Tile
Représente une tuile avec des propriétés arbitraires :
- **Propriétés flexibles** : type, ressources, température, élévation, etc.
- **Méthodes d'accès** : `getProperty()`, `setProperty()`, `hasProperty()`
- **Méthodes spécialisées** : `getType()`, `getResources()`, `getTemperature()`, etc.

### Classe Map
- Représente une carte complète
- Gère une grille d'hexagones en coordonnées axiales (q, r)
- Supporte la sauvegarde/chargement au format JSON

### Classe Hexagon
- Représente un hexagone individuel
- Utilise des coordonnées axiales (q, r)
- Peut calculer des coordonnées cubiques (x, y, z) avec x + y + z = 0

## Coordonnées Hexagonales

Le système utilise des coordonnées axiales où :
- `q` : axe horizontal (est-ouest)
- `r` : axe diagonal (nord-est - sud-ouest)
- `s` : coordonnée calculée (-q - r) pour les coordonnées cubiques

## Utilisation de Base

### Créer une Carte

```php
// Créer une carte 10x10
$map = new Map("Ma Carte", 10, 10);
```

### Créer et Placer des Tuiles

```php
// Créer une tuile avec des propriétés
$castleTile = new Tile([
    'type' => 'castle',
    'resources' => ['gold' => 100, 'stone' => 50],
    'temperature' => 20.5,
    'elevation' => 100
]);

// Placer la tuile
$map->setTile(0, 0, $castleTile);

// Créer une tuile simple
$forestTile = new Tile(['type' => 'forest', 'resources' => ['wood' => 200]]);
$map->setTile(1, 1, $forestTile);
```

### Accéder aux Propriétés des Tuiles

```php
// Récupérer une tuile
$tile = $map->getTile(0, 0);

if ($tile) {
    // Accès direct aux propriétés
    $type = $tile->getType();
    $resources = $tile->getResources();
    $temperature = $tile->getTemperature();

    // Accès générique
    $customProperty = $tile->getProperty('custom_prop', 'default');
    $tile->setProperty('new_prop', 'value');
}
```

### Statistiques

```php
$stats = $map->getStatistics();
// Retourne:
// - total_hexagons: nombre total
// - width, height: dimensions
// - tile_type_counts: répartition par type
// - empty_count, empty_percentage: cases vides
// - filled_count, filled_percentage: cases remplies
```

## Sauvegarde et Chargement

### Format JSON

```json
{
    "name": "Ma Carte",
    "width": 5,
    "height": 5,
    "created_at": "2025-10-12 15:30:00",
    "updated_at": "2025-10-12 15:30:00",
    "hexagons": [
        {
            "q": 0,
            "r": 0,
            "tile": {
                "type": "castle",
                "resources": {"gold": 100, "stone": 50},
                "temperature": 20.5
            }
        }
    ]
}
```

### Utilisation

```php
// Sauvegarder
$map->saveToFile('storage/maps/ma_carte.json');

// Charger
$loadedMap = Map::fromFile('storage/maps/ma_carte.json');
```

## Exemples Avancés

### Créer une Tuile Complexe

```php
$tile = new Tile();
$tile->setType('factory');
$tile->setResources(['iron' => 50, 'coal' => 30]);
$tile->setTemperature(15.0);
$tile->setElevation(50);
$tile->setProperty('owner', 'player1');
$tile->setProperty('production_rate', 10);

$map->setTile(5, 5, $tile);
```

### Analyser les Ressources d'une Carte

```php
$totalResources = [];
foreach ($map->getAllHexagons() as $row) {
    foreach ($row as $hexagon) {
        $tile = $hexagon->getTile();
        if ($tile && !$tile->isEmpty()) {
            $resources = $tile->getResources();
            foreach ($resources as $resource => $amount) {
                $totalResources[$resource] = ($totalResources[$resource] ?? 0) + $amount;
            }
        }
    }
}
```

### Filtrer les Tuiles par Critères

```php
$hotTiles = [];
for ($q = 0; $q < $map->getWidth(); $q++) {
    for ($r = 0; $r < $map->getHeight(); $r++) {
        $tile = $map->getTile($q, $r);
        if ($tile && $tile->getTemperature() > 25.0) {
            $hotTiles[] = ['q' => $q, 'r' => $r, 'tile' => $tile];
        }
    }
}
```

## Tests

Pour tester la classe, exécutez :
```bash
php app/Tests/MapTest.php
```

Cela exécute 37 tests validant toutes les fonctionnalités.

## Exemple Complet

Voir le fichier `app/Examples/MapExample.php` pour un exemple complet d'utilisation avec propriétés complexes.