mario/DEVELOPMENT_GUIDE.md

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

# 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

npm install -g ngrok
npm run dev
# Dans un autre terminal :
ngrok http 3000

Option 2 : localtunel

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

// 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 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 :

// 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 :

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

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

📚 Ressources

Documentation

• Phaser 3
• DeviceOrientation API
• PWA Guide

Assets Gratuits

• OpenGameArt.org
• Kenney.nl
• Itch.io Assets

Outils

• Piskel - Sprites
• Tiled - Niveaux
• GIMP - É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