thedevilbox/README.md

# 🎮 Oulvic - Jeu de type Pac-Man

Un jeu de type Pac-Man développé en JavaScript vanilla par **Ludo** et **Syoul**.

---

## 📖 Table des matières

1. [Description](#description)
2. [Fonctionnalités](#fonctionnalités)
3. [Structure du projet](#structure-du-projet)
4. [Installation](#installation)
5. [Comment jouer](#comment-jouer)
6. [Architecture du code](#architecture-du-code)
7. [Documentation technique](#documentation-technique)

---

## 📝 Description

**Oulvic** est un clone de Pac-Man développé entièrement en HTML5, CSS3 et JavaScript vanilla. Le jeu utilise l'élément `<canvas>` pour le rendu graphique et propose une expérience de jeu complète avec :

- Un personnage jouable aux couleurs changeantes
- 4 fantômes avec intelligence artificielle
- 3 labyrinthes différents
- Système de niveaux progressifs
- Classement des scores (localStorage)
- Interface responsive

---

## ✨ Fonctionnalités

### Gameplay
- **Déplacement fluide** : Mouvement pixel par pixel avec interpolation
- **Système de vies** : 3 vies représentées par des cœurs
- **Points** : Collecte de pastilles (+10 points) et bonus
- **Progression de niveau** : Passer au niveau suivant en mangeant 4 cerises

### Bonus
| Bonus | Points | Effet |
|-------|--------|-------|
| 🍒 Cerise | +100 | Active la poursuite des fantômes pendant un temps limité. 4 cerises = niveau suivant |
| ⭐ Étoile "L" | +15 | Bonus supplémentaire |

### Fantômes
- **4 fantômes** avec couleurs distinctes (rouge, magenta, cyan, orange)
- **IA adaptative** : Les fantômes poursuivent Pac-Man après qu'une cerise soit mangée
- **Vitesse croissante** : Les fantômes accélèrent à chaque niveau

### Labyrinthes
- 3 variantes de labyrinthes qui alternent à chaque niveau
- Génération dynamique avec remplissage des espaces vides
- Randomisation légère pour plus de variété

---

## 📁 Structure du projet

```
pacmanludo/
├── index.html    # Page HTML principale
├── style.css     # Feuille de styles
├── game.js       # Logique du jeu
└── README.md     # Documentation
```

---

## 🚀 Installation

1. **Cloner ou télécharger** le projet
2. **Ouvrir** `index.html` dans un navigateur web moderne
3. **Jouer !**

Aucune dépendance externe n'est requise.

---

## 🎯 Comment jouer

### Contrôles
| Touche | Action |
|--------|--------|
| ↑ Flèche Haut | Déplacer vers le haut |
| ↓ Flèche Bas | Déplacer vers le bas |
| ← Flèche Gauche | Déplacer vers la gauche |
| → Flèche Droite | Déplacer vers la droite |

### Objectif
1. Collectez toutes les pastilles blanches pour marquer des points
2. Mangez les cerises pour activer la poursuite et progresser
3. Évitez les fantômes !
4. Atteignez le score le plus élevé possible

### Progression
- **4 cerises mangées** = passage au niveau suivant
- À chaque niveau :
  - Pac-Man accélère légèrement (+5% par niveau)
  - Les fantômes deviennent plus rapides (+20% par niveau)
  - Le labyrinthe change (cycle de 3 labyrinthes)

---

## 🏗️ Architecture du code

### `index.html`

Structure HTML de la page :

```html
├── main-wrapper
│   ├── container (zone de jeu)
│   │   ├── Titre "OULVIC"
│   │   ├── Champ nom d'utilisateur
│   │   ├── Barre d'informations (score, niveau, vies, statut)
│   │   ├── Canvas du jeu (600x600)
│   │   └── Instructions et bouton rejouer
│   └── leaderboard-container (classement)
└── footer (crédits)
```

### `style.css`

| Section | Description |
|---------|-------------|
| Reset & Body | Styles de base, fond sombre avec effets |
| Layout | Flexbox pour disposition responsive |
| Game Info | Styles pour score, niveau, vies |
| Canvas | Bordure dorée, ombres |
| Leaderboard | Tableau des scores stylisé |
| Responsive | Media queries pour mobile |

### `game.js`

#### Constantes principales

```javascript
CELL_SIZE = 20      // Taille d'une cellule en pixels
COLS = 30           // Nombre de colonnes
ROWS = 30           // Nombre de lignes

// Types de cellules
WALL = 1            // Mur (bleu)
DOT = 2             // Pastille (blanc)
EMPTY = 0           // Vide
TUNNEL = 3          // Tunnel (passage fantômes)
BONUS_CHERRY = 4    // Cerise bonus
BONUS_LUDO = 5      // Étoile bonus
```

---

## 📚 Documentation technique

### Classe `Pacman`

Gère le personnage jouable.

| Propriété | Type | Description |
|-----------|------|-------------|
| `x, y` | number | Position en cellules |
| `pixelX, pixelY` | number | Position en pixels (mouvement fluide) |
| `direction` | number | Direction actuelle (0=haut, 1=droite, 2=bas, 3=gauche) |
| `nextDirection` | number | Prochaine direction demandée |
| `speed` | number | Vitesse de déplacement |
| `mouthAngle` | number | Animation de la bouche |
| `colorAnimation` | number | Animation des couleurs HSL |

| Méthode | Description |
|---------|-------------|
| `update()` | Met à jour la position et l'animation |
| `canMove(direction)` | Vérifie si le mouvement est possible |
| `collectDot()` | Collecte les pastilles et bonus |
| `draw()` | Dessine Pac-Man sur le canvas |

---

### Classe `Ghost`

Gère les fantômes ennemis.

| Propriété | Type | Description |
|-----------|------|-------------|
| `x, y` | number | Position en cellules |
| `pixelX, pixelY` | number | Position en pixels |
| `color` | string | Couleur du fantôme |
| `direction` | number | Direction de déplacement |
| `speed` | number | Vitesse (augmente avec le niveau) |
| `moveInterval` | number | Intervalle entre changements de direction |

| Méthode | Description |
|---------|-------------|
| `update()` | Met à jour la position et l'IA |
| `updateSpeed()` | Ajuste la vitesse selon le niveau |
| `canMove(direction)` | Vérifie si le mouvement est possible |
| `getDirectionToPacman(dirs)` | Calcule la meilleure direction vers Pac-Man |
| `draw()` | Dessine le fantôme (corps + yeux) |

---

### Classe `Bonus`

Gère les objets bonus (cerises, étoiles).

| Propriété | Type | Description |
|-----------|------|-------------|
| `x, y` | number | Position en cellules |
| `type` | number | Type de bonus (CHERRY ou LUDO) |
| `animation` | number | Animation de pulsation |

| Méthode | Description |
|---------|-------------|
| `update()` | Met à jour l'animation |
| `draw()` | Dessine le bonus avec effet de scale |

---

### Fonctions principales

#### Gestion du labyrinthe

| Fonction | Description |
|----------|-------------|
| `countDots()` | Compte le nombre de pastilles restantes |
| `drawMaze()` | Dessine le labyrinthe complet |
| `fillEmptySpaces()` | Remplit les espaces vides avec des pastilles |
| `randomizeMaze()` | Ajoute des variations aléatoires au labyrinthe |
| `placeBonuses()` | Place les bonus aux positions définies |

#### Gestion du jeu

| Fonction | Description |
|----------|-------------|
| `initGame()` | Initialise une nouvelle partie |
| `gameLoop()` | Boucle principale du jeu (requestAnimationFrame) |
| `checkCollisions()` | Détecte les collisions Pac-Man/fantômes |
| `nextLevel()` | Passe au niveau suivant |
| `restartCurrentLevel()` | Recommence le niveau actuel (après perte de vie) |

#### Interface utilisateur

| Fonction | Description |
|----------|-------------|
| `updateLivesDisplay()` | Met à jour l'affichage des vies |
| `updateLeaderboard()` | Rafraîchit le classement |
| `saveScore()` | Sauvegarde le score en localStorage |
| `getScores()` | Récupère les scores depuis localStorage |

---

### Variables globales d'état

```javascript
let score = 0;              // Score actuel
let level = 1;              // Niveau actuel
let lives = 3;              // Vies restantes
let gameRunning = true;     // État du jeu
let totalDots = 0;          // Pastilles restantes
let cherriesEaten = 0;      // Cerises mangées (niveau actuel)
let isChangingLevel = false; // Flag de transition
let cherryEatenRecently = false; // Mode poursuite activé
let cherryEatenTimer = 0;   // Durée du mode poursuite
```

---

### Système de stockage des scores

Les scores sont sauvegardés dans le `localStorage` du navigateur sous la clé `pacmanScores`.

**Format des données :**
```javascript
{
    username: "NomJoueur",  // Nom saisi ou "Anonyme"
    score: 1500,            // Score final
    date: "2025-12-01T..."  // Date ISO
}
```

- Maximum **10 scores** conservés
- Triés par score décroissant

---

### Labyrinthes

Le jeu dispose de 3 labyrinthes prédéfinis (`originalMaze1`, `originalMaze2`, `originalMaze3`) stockés comme tableaux 2D de 30x30.

**Rotation des labyrinthes :**
```javascript
mazeIndex = (level - 1) % 3
```

Les labyrinthes sont modifiés dynamiquement :
1. `fillEmptySpaces()` - Remplit les zones vides
2. `randomizeMaze()` - Ajoute de la variété

---

## 🎨 Design

### Palette de couleurs

| Élément | Couleur |
|---------|---------|
| Fond | `#0a0a0a` (noir) |
| Murs | `#0000ff` (bleu) |
| Pastilles | `#ffffff` (blanc) |
| Texte titre | `#ffd700` (or) |
| Cerises | `#ff0000` (rouge) |
| Cœurs | `#ff0000` (rouge) |

### Fantômes
- Rouge : `#ff0000`
- Magenta : `#ff00ff`
- Cyan : `#00ffff`
- Orange : `#ffa500`

### Pac-Man
- Couleur animée en HSL (arc-en-ciel)

---

## 🔧 Personnalisation

### Modifier la difficulté

Dans `game.js` :

```javascript
// Vitesse de base de Pac-Man (ligne 145)
this.baseSpeed = 0.15;

// Vitesse de base des fantômes (ligne 277)
this.baseSpeed = 0.1;

// Accélération par niveau
pacman.speed = pacman.baseSpeed * (1 + (level - 1) * 0.05);
ghost.speed = ghost.baseSpeed * (1 + (level - 1) * 0.2);
```

### Modifier les points

```javascript
// Pastille (ligne 213)
score += 10;

// Cerise (ligne 224)
score += 100;

// Étoile Ludo (ligne 241)
score += 15;
```

---

## 📄 Licence

Projet créé par **Ludo** et **Syoul**.

---

## 🙏 Crédits

- Inspiration : Pac-Man original (Namco, 1980)
- Développement : Ludo & Syoul