# Guide de Développement - Mario Runner

## 🎮 État du Projet

### ✅ Fonctionnalités Implémentées

#### Infrastructure
- ✅ Configuration TypeScript + Vite
- ✅ Structure de projet organisée
- ✅ Phaser 3 intégré
- ✅ PWA configuré (manifest.json)
- ✅ Build et compilation fonctionnels

#### Contrôles
- ✅ **PC** : Contrôle clavier (Flèches gauche/droite + Espace/Haut pour sauter)
- ✅ **Mobile** : Gyroscope pour mouvement + Bouton tactile pour sauter
- ✅ Détection automatique PC vs Mobile
- ✅ Permission gyroscope iOS (requestPermission)
- ✅ Zone morte gyroscope (deadzone) pour stabilité

#### Jeu
- ✅ Classe Player avec physique Arcade
- ✅ Mouvement fluide avec accélération/décélération
- ✅ Saut avec gravité
- ✅ Background qui défile avec effet parallaxe
- ✅ Plateformes statiques (sol + plateformes en l'air)
- ✅ Obstacles (collision → perte de points)
- ✅ Cadeaux (collecte → gain de points)
- ✅ Système de score
- ✅ Timer de 3 minutes
- ✅ Caméra qui suit le joueur
- ✅ Niveau étendu (3x la largeur de l'écran)

#### Scènes
- ✅ BootScene : Chargement des assets
- ✅ MenuScene : Menu avec demande permission gyroscope
- ✅ GameScene : Jeu principal

#### UI
- ✅ Affichage score et timer
- ✅ Info contrôles selon plateforme
- ✅ Bouton retour menu
- ✅ Écran de fin de jeu

### 🚧 À Faire

#### Assets Graphiques
- [ ] Créer spritesheet du personnage (neveu)
  - [ ] Animation idle
  - [ ] Animation walk
  - [ ] Animation jump
- [ ] Background réel (remplacer le ciel généré)
- [ ] Sprites plateformes
- [ ] Sprites obstacles variés
- [ ] Sprites cadeaux variés
- [ ] Icônes PWA (192x192, 512x512)

#### Gameplay
- [ ] Plateformes mobiles
- [ ] Ennemis animés
- [ ] Power-ups spéciaux
- [ ] Checkpoints
- [ ] Système de vies
- [ ] Game Over / Victory screens
- [ ] High scores / LocalStorage

#### Audio
- [ ] Musique de fond
- [ ] Son de saut
- [ ] Son de collecte
- [ ] Son de collision
- [ ] Gestion volume

#### Niveau Design
- [ ] Créer niveaux avec Tiled
- [ ] Importer tilemaps JSON
- [ ] Plusieurs niveaux
- [ ] Progression de difficulté

#### Optimisation
- [ ] Pooling d'objets
- [ ] Optimisation sprites
- [ ] Compression assets
- [ ] Service Worker pour PWA

## 🎯 Commandes Disponibles

```bash
# Développement (hot reload)
npm run dev

# Build de production
npm run build

# Prévisualiser le build
npm run preview
```

## 🧪 Test sur Mobile

### Via réseau local (WiFi)

1. Assurez-vous que mobile et PC sont sur le même WiFi
2. Lancez `npm run dev`
3. Notez l'adresse réseau affichée (ex: `http://192.168.1.10:3000`)
4. Ouvrez cette adresse sur votre mobile

### Via tunnel (pour HTTPS requis par iOS)

**Option 1 : ngrok**
```bash
npm install -g ngrok
npm run dev
# Dans un autre terminal :
ngrok http 3000
```

**Option 2 : localtunel**
```bash
npm install -g localtunnel
npm run dev
# Dans un autre terminal :
lt --port 3000
```

## 📱 Contrôles

### PC (Développement)
- **Flèches Gauche/Droite** : Déplacement
- **Espace** ou **Flèche Haut** : Saut

### Mobile (Production)
- **Gyroscope** : Inclinez le téléphone pour déplacer le personnage
- **Bouton tactile** (bas droite) : Saut

## 🏗 Architecture du Code

### Structure des Fichiers

```
src/
├── main.ts                 # Point d'entrée
├── game.ts                 # Config Phaser
├── scenes/
│   ├── BootScene.ts       # Chargement assets
│   ├── MenuScene.ts       # Menu principal
│   └── GameScene.ts       # Jeu principal
├── controls/
│   ├── GyroControl.ts     # Gestion gyroscope
│   └── JumpButton.ts      # Bouton saut tactile
├── entities/
│   ├── Player.ts          # Joueur
│   ├── Obstacle.ts        # Obstacles
│   └── Gift.ts            # Cadeaux
└── utils/
    └── constants.ts       # Constantes du jeu
```

### Flux du Jeu

```
index.html → main.ts → game.ts
                          ↓
                    BootScene (chargement)
                          ↓
                    MenuScene (permission gyro)
                          ↓
                    GameScene (jeu)
```

### Gestion des Contrôles

```typescript
// GameScene détecte automatiquement la plateforme
if (isMobile) {
    // Gyroscope + Bouton tactile
    gyroControl.getTiltValue() → direction
    jumpButton.on('press') → player.jump()
} else {
    // Clavier
    cursors.left/right → direction
    cursors.space → player.jump()
}

// Mouvement unifié
player.move(direction)
```

## 🎨 Workflow Sprites

Consultez [public/assets/sprites/SPRITE_WORKFLOW.md](public/assets/sprites/SPRITE_WORKFLOW.md) pour le guide complet de création des sprites du personnage.

### Résumé rapide :
1. Détourez la photo (GIMP, remove.bg)
2. Créez les animations (Piskel, Aseprite)
3. Exportez en spritesheet PNG
4. Placez dans `public/assets/sprites/`
5. Chargez dans `BootScene.preload()`
6. Créez animations dans `Player.ts`

## 🔧 Configuration

### Ajuster la Difficulté

Éditez [src/utils/constants.ts](src/utils/constants.ts) :

```typescript
// Physique joueur
export const PLAYER_GRAVITY = 800;        // Gravité
export const PLAYER_JUMP_VELOCITY = -400;  // Force de saut
export const PLAYER_MAX_SPEED = 300;       // Vitesse max
export const PLAYER_ACCELERATION = 50;     // Accélération

// Gyroscope
export const GYRO_DEADZONE = 5;            // Zone morte (degrés)
export const GYRO_MAX_TILT = 30;           // Inclinaison max
export const GYRO_SENSITIVITY = 10;        // Sensibilité

// Niveau
export const LEVEL_DURATION = 180;         // Durée (secondes)
```

### Activer le Mode Debug

Dans [src/game.ts](src/game.ts) :

```typescript
physics: {
    arcade: {
        debug: true,  // Affiche les hitboxes
    },
},
```

## 🐛 Problèmes Courants

### Le gyroscope ne fonctionne pas sur iOS

- ✅ Vérifiez que vous utilisez **HTTPS** (requis par iOS 13+)
- ✅ Vérifiez que la permission a été accordée dans MenuScene
- ✅ Testez sur un vrai appareil iOS (pas de gyro sur simulateur)

### Le jeu est trop rapide/lent

- Ajustez `PLAYER_MAX_SPEED` et `PLAYER_ACCELERATION`
- Ajustez `GYRO_SENSITIVITY` pour mobile

### Les collisions ne fonctionnent pas

- Vérifiez que les objets ont un body physique : `this.physics.add.existing()`
- Vérifiez les colliders/overlaps dans GameScene

### Le build échoue

```bash
# Nettoyer et réinstaller
rm -rf node_modules dist
npm install
npm run build
```

## 📚 Ressources

### Documentation
- [Phaser 3](https://photonstorm.github.io/phaser3-docs/)
- [DeviceOrientation API](https://developer.mozilla.org/en-US/docs/Web/API/DeviceOrientationEvent)
- [PWA Guide](https://web.dev/progressive-web-apps/)

### Assets Gratuits
- [OpenGameArt.org](https://opengameart.org/)
- [Kenney.nl](https://kenney.nl/assets)
- [Itch.io Assets](https://itch.io/game-assets/free)

### Outils
- [Piskel](https://www.piskelapp.com/) - Sprites
- [Tiled](https://www.mapeditor.org/) - Niveaux
- [GIMP](https://www.gimp.org/) - Édition images

## 🚀 Prochaines Étapes Recommandées

1. **Créer les sprites du personnage** (voir SPRITE_WORKFLOW.md)
2. **Ajouter du son** (musique + effets)
3. **Créer plus de niveaux** avec Tiled
4. **Tester sur mobile réel** via tunnel HTTPS
5. **Déployer** (Netlify, Vercel, GitHub Pages)

## 📝 Notes

- Le jeu détecte automatiquement PC vs Mobile
- Les deux modes de contrôle peuvent coexister
- Le code est prêt pour l'ajout de vrais sprites
- La structure est extensible pour ajouter plus de features